/** * `U+0000` is the one code point a Postgres `text`/`jsonb` value cannot carry: * the wire protocol terminates strings on it, so the driver throws before the * statement is planned, and the throw carries no SQLSTATE a route layer can * classify — it reaches the caller as a 500, on reads as readily as on writes. * Every boundary that admits caller-supplied text rejects it through * {@link containsNulCharacter}: the JSON request scan, the multipart field * scan, and the canonical folder-path decoder. * * Deliberately only NUL. `\n`, `\t`, and `\r` are ordinary content Postgres * stores verbatim, and a lone surrogate is substituted with `U+FFFD` by the * driver's encoder rather than throwing — a fidelity question, not an * availability one. */ const NUL_CHARACTER = '\u0000' /** * The characters JavaScript's `\s` and `trim()` treat as whitespace, spelled out as a bracket * expression both JavaScript and PostgreSQL regular expressions accept, so a SQL expression can * normalize whitespace exactly as its TypeScript twin does. */ export const WHITESPACE_CHARACTER_CLASS = '[ \\t\\n\\v\\f\\r\\u00a0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff]' /** Reports whether `value` carries a `U+0000`. See {@link NUL_CHARACTER}. */ export function containsNulCharacter(value: string): boolean { return value.includes(NUL_CHARACTER) } /** * Truncates `str` if it exceeds `sliceLength` characters, appending `suffix`. * The total output length when truncated is `sliceLength + suffix.length`. * Defaults suffix to `'...'`. * * @example * truncate('hello world', 8) // 'hello wo...' (11 chars) * truncate('hello world', 8, ' …') // 'hello wo …' * truncate('hi', 10) // 'hi' */ export function truncate(str: string, sliceLength: number, suffix = '...'): string { return str.length > sliceLength ? str.slice(0, sliceLength) + suffix : str } /** * Like {@link truncate}, but never cuts inside a surrogate pair: when the code unit at the cut * would split an astral character, the cut moves one unit earlier. Lengths are still counted in * UTF-16 code units, so the result of a cut is at most `sliceLength + suffix.length` units. * * @example * truncateAtCodePoint('ab😀cd', 3) // 'ab...' (the cut at 3 would split the emoji) * truncateAtCodePoint('ab😀cd', 4) // 'ab😀...' */ export function truncateAtCodePoint(str: string, sliceLength: number, suffix = '...'): string { if (str.length <= sliceLength) return str const splitsPair = sliceLength > 0 && (str.charCodeAt(sliceLength - 1) & 0xfc00) === 0xd800 return str.slice(0, splitsPair ? sliceLength - 1 : sliceLength) + suffix } /** * Lowercases `value` into the `[a-z0-9-]` charset: every run of other characters * becomes one hyphen, and leading and trailing hyphens are dropped. * * ASCII-only by design — the character class drops accented and non-Latin text * rather than transliterating it, so `'Café'` yields `'caf'` and a wholly * non-Latin name yields `''`. Callers that need a non-empty result supply their * own fallback, because what to fall back to is theirs to decide. * * Truncation is likewise the caller's: slicing a slug can leave a trailing * hyphen, and whether to strip it, and at what length, varies by the identifier * being built. * * @example * slugify('Acme Corp') // 'acme-corp' * slugify(' !!Hello!! ') // 'hello' * slugify('***') // '' */ export function slugify(value: string): string { return value .toLowerCase() .replace(/[^a-z0-9]+/g, '-') .replace(/^-|-$/g, '') } /** * Strips a trailing `_vN` version suffix from `value`, yielding the base type. * Only the single trailing suffix is removed; leading occurrences are left intact. * * @example * stripVersionSuffix('notion_search_v2') // 'notion_search' * stripVersionSuffix('x') // 'x' * stripVersionSuffix('a_v2_v3') // 'a_v2' */ export function stripVersionSuffix(value: string): string { return value.replace(/_v\d+$/, '') } /** * Tests whether `value` ends with a `_vN` version suffix. * Only a trailing suffix counts; a leading or embedded `_vN` does not match. * * @example * isVersionedType('notion_search_v2') // true * isVersionedType('plain') // false * isVersionedType('a_version') // false */ export function isVersionedType(value: string): boolean { return /_v\d+$/.test(value) } /** * Normalizes an email address for comparison and storage by trimming * surrounding whitespace and lowercasing. */ export function normalizeEmail(email: string): string { return email.trim().toLowerCase() } /** * RFC 5322-shaped syntax gate for a full address. Format only — domain * reputation, MX/DNS, and membership policy are the caller's concern. */ const EMAIL_SYNTAX_REGEX = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/ /** * Bare `@domain` pattern, for allowlists that grant access to a whole domain. * Single-label domains (`@intranet`) are allowed — self-hosted deployments use * them — but a lone `@` and malformed labels are not. */ const EMAIL_DOMAIN_SYNTAX_REGEX = /^@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*$/ /** * Format-only email syntax check, capped at the RFC 5321 length limit. * * @param allowDomains - also accept a bare `@domain` entry, for allowlists that * grant access to an entire domain rather than a single address. */ export function isValidEmailSyntax(email: string, allowDomains = false): boolean { if (email.length > 254) return false return EMAIL_SYNTAX_REGEX.test(email) || (allowDomains && EMAIL_DOMAIN_SYNTAX_REGEX.test(email)) } /** * Matches an unpaired UTF-16 surrogate half — e.g. one produced by `slice()` * cutting an astral character like 😀 in half. Such a string has no UTF-8 * encoding, so a peer that re-encodes it strictly (Python's JSON response * encoder, for one) throws on it. */ const UNPAIRED_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?(value: T): T { if (typeof value === 'string') { const clean = sanitizeForJsonb(value) return (clean === value ? value : clean) as T } if (Array.isArray(value)) { let changed = false const result = value.map((item) => { const clean = sanitizeValueForJsonb(item) if (clean !== item) changed = true return clean }) return (changed ? result : value) as T } if (typeof value === 'object' && value !== null) { let changed = false const result: Record = {} for (const [key, item] of Object.entries(value as Record)) { const cleanKey = sanitizeForJsonb(key) const cleanItem = sanitizeValueForJsonb(item) if (cleanKey !== key || cleanItem !== item) changed = true result[cleanKey] = cleanItem } return (changed ? result : value) as T } return value } /** * Formats a list of names as quoted values with an overflow tail, listing at * most `maxListed` names. `quote` renders each listed name, for a caller whose * label carries more than the quoted name. * * @example * formatQuotedNameList(['A', 'B'], 3) // '"A", "B"' * formatQuotedNameList(['A', 'B', 'C', 'D'], 3) // '"A", "B", "C" and 1 more' * formatQuotedNameList([], 3) // '' */ export function formatQuotedNameList( names: string[], maxListed: number, quote: (name: string) => string = (name) => `"${name}"` ): string { const listed = names.slice(0, maxListed).map(quote).join(', ') const overflow = names.length - maxListed return overflow > 0 ? `${listed} and ${overflow} more` : listed } /** * Maps every Unicode whitespace character to a plain space, one-to-one. * * Agent-authored block names and values routinely carry non-breaking or narrow * spaces that render identically to " " but never equal a typed space, silently * hiding matches. The replacement is length-preserving (every `\s` character is * a single UTF-16 unit), so indexes into the folded string remain valid ranges * into the original. * * Lives here rather than beside the workflow search index because the Note card * on the canvas has to fold identically to find the same occurrences, and it * renders from `@sim/workflow-renderer` — a package, which cannot import from * `apps/*`. Two copies of this rule silently disagreeing is precisely the bug * that made a match count in the panel and highlight nowhere on the card. */ export function foldSearchWhitespace(value: string): string { return value.replace(/\s/g, ' ') } /** * Lowercases without ever changing the string's length. * * A plain `toLowerCase()` cannot be used where an index into the result has to * address the same character of the input: a few code points lowercase to more * than one (`'\u0130'.toLowerCase()` is two characters), which slides every * later index. Characters that would grow are left alone — they simply match * case-sensitively. The whole-string form is tried first because it is a single * intrinsic and is length-preserving for every input that contains no such code * point, i.e. essentially all of them. * * The fallback still reads each character's replacement out of the whole-string * result rather than lowercasing it in isolation, because some lowercasing is * context-sensitive: a word-final `\u03a3` lowercases to `\u03c2` in the string * but to `\u03c3` on its own. Folding character by character would make one * expanding code point elsewhere in the string silently change how every sigma * in it matches. */ function lowerPreservingLength(value: string): string { const lowered = value.toLowerCase() if (lowered.length === value.length) return lowered let result = '' let loweredOffset = 0 for (const char of value) { const loweredChar = char.toLowerCase() result += loweredChar.length === char.length ? lowered.slice(loweredOffset, loweredOffset + loweredChar.length) : char loweredOffset += loweredChar.length } return result } /** * Visits every occurrence of `query` in `text`, without overlaps. * * The single definition of what "an occurrence" means for search, shared by the * workflow search index and by the Note card that has to mark the same hits on * the canvas. They live in different packages and cannot see each other, so a * second copy of this loop is a silent disagreement waiting to happen: the * panel counts a match the card never paints, which is exactly the bug that * arrived when only the whitespace fold was shared and the scan was not. * * Whitespace is folded first (see {@link foldSearchWhitespace}) and case is * folded with {@link lowerPreservingLength}; both are one-to-one, so the bounds * index the caller's own unfolded string. A plain `toLowerCase()` here would * break that guarantee for the handful of code points that lowercase to two — * every occurrence after one would be reported a character late. */ export function forEachSearchOccurrence( text: string, query: string, visit: (start: number, end: number) => void, caseSensitive = false ): void { if (!query) return const normalize = (value: string) => { const folded = foldSearchWhitespace(value) return caseSensitive ? folded : lowerPreservingLength(folded) } const haystack = normalize(text) const needle = normalize(query) const step = Math.max(needle.length, 1) let index = haystack.indexOf(needle) while (index !== -1) { visit(index, index + needle.length) index = haystack.indexOf(needle, index + step) } } /** * ASCII punctuation a backslash may escape in markdown, per CommonMark. A * backslash before anything else is a literal backslash. */ const MARKDOWN_ESCAPABLE = new Set('!"#$%&\'()*+,-./:;<=>?@[\\]^_`{|}~') /** * `text` with an index back into the string it came from. * * `starts` has one more entry than `text` has characters: `starts[i]` is where * projected character `i` begins in the source, and `starts[text.length]` is * the source length. A projected range `[s, e)` therefore maps to the source * range `[starts[s], starts[e])` — including any backslash the projection * consumed, so a caller rewriting that span never leaves one stranded. */ export interface SearchTextProjection { text: string starts: number[] } /** * Projects markdown onto the text it renders as, for MATCHING only. * * The rich-text editor's serializer backslash-escapes every markdown-significant * character in prose, so a note the reader sees as `SB_ACTION` is stored as * `SB\_ACTION`. Searching what is on screen has to see through that. * * Deliberately a total, structure-free function: it does not try to know which * spans are code. Undoing an escape that a code fence would have kept literal * only ever changes which text a search highlights — no caller writes this * back — whereas a rewriter making the same mistake would corrupt the file. * That asymmetry is why the escape is undone here rather than at serialization. */ export function projectEscapedMarkdownForSearch(value: string): SearchTextProjection { if (!value.includes('\\')) { return { text: value, starts: identityStarts(value.length) } } let text = '' const starts: number[] = [] for (let index = 0; index < value.length; index += 1) { const isEscape = value[index] === '\\' && MARKDOWN_ESCAPABLE.has(value[index + 1] ?? '') starts.push(index) if (isEscape) index += 1 text += value[index] } starts.push(value.length) return { text, starts } } function identityStarts(length: number): number[] { const starts: number[] = new Array(length + 1) for (let index = 0; index <= length; index += 1) starts[index] = index return starts } /** * One character class, declared twice: the `/g` copy is stateful under `.test()` * (`lastIndex` advances between calls), so only `.replace` may use it. */ const REGEX_METACHARACTER = /[.*+?^${}()|[\]\\]/ const REGEX_METACHARACTERS = /[.*+?^${}()|[\]\\]/g /** * Escapes every regex metacharacter in `value` so it matches only itself when * interpolated into a `RegExp`. * * @example * new RegExp(escapeRegExp('a.b')) // matches the literal 'a.b', not 'axb' */ export function escapeRegExp(value: string): string { return value.replace(REGEX_METACHARACTERS, '\\$&') } /** * Removes every trailing `/`. A backward scan rather than `/\/+$/`: that regex * restarts at each `/` in a long run that does not reach the end, so it is * quadratic in the run length. */ export function stripTrailingSlashes(value: string): string { let end = value.length while (end > 0 && value.charCodeAt(end - 1) === 0x2f) end-- return value.slice(0, end) } /** * Escapes the SQL LIKE/ILIKE metacharacters `%`, `_`, and `\` in `value` so * each matches itself. Postgres uses `\` as the default LIKE escape character, * so the result needs no explicit `ESCAPE` clause. * * @example * escapeLikePattern('100%_done') // '100\\%\\_done' */ export function escapeLikePattern(value: string): string { return value.replace(/[\\%_]/g, '\\$&') } /** Reports whether `value` carries a character {@link escapeRegExp} would escape. */ export function hasRegexMetacharacter(value: string): boolean { return REGEX_METACHARACTER.test(value) } /** * Compares two strings by code unit, the ordering `Array.prototype.sort` applies * by default. Deliberately not `localeCompare`: ordering that feeds a hash, a * fingerprint, or a value compared across processes must not vary with the * host's locale. * * @example * ['a', 'Z'].sort(compareStrings) // ['Z', 'a'] — uppercase sorts first */ export function compareStrings(left: string, right: string): number { if (left < right) return -1 if (left > right) return 1 return 0 }