@minnowdb/core 0.0.1 → 0.1.1

package/dist/engine/defaults.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Write-time default filling. For a default-bearing column (always non-nullable), a null or
+ * absent slot means "generate" and an explicit value passes through untouched. Pure defaults
+ * (now, literals) are filled here before validation; auto-increment slots stay null until the
+ * write path reserves a range from storage, keeping generation atomic across concurrent
+ * writers. Function defaults never reach the engine — the typed facade fills them before the
+ * batch crosses the boundary.
+ */
+import type { RowIdRange, TableColumnRecord, TableRecord } from "../storage/types.js";
+import type { BatchValue, ColumnarBatch } from "./batch.js";
+/** The deferred part of a fill: slots that need storage-reserved auto-increment values. */
+export interface AutoIncrementFill {
+    readonly column: TableColumnRecord;
+    /** Row indexes whose value must come from the reserved range, in row order. */
+    readonly missingIndexes: readonly number[];
+    /** One past the largest explicit value in the batch, so generated keys never collide with it. */
+    readonly atLeast: bigint;
+}
+export interface FilledBatch {
+    readonly batch: ColumnarBatch;
+    /** Full written vectors, input row order, for columns where at least one slot was generated. */
+    readonly generated: Map<string, BatchValue[]>;
+    /** Present whenever the table has an auto-increment column, even if every value is explicit —
+     * the counter still bumps past the explicit maximum in the same atomic step. */
+    readonly autoIncrement?: AutoIncrementFill;
+}
+export declare function fillColumnDefaults(table: TableRecord, input: ColumnarBatch, now: () => Date, knownRowCount?: number): FilledBatch;
+/**
+ * Writes the reserved range into the batch's null slots. The vector is the fresh array
+ * `fillColumnDefaults` created for this fill, never a caller-owned one.
+ */
+export declare function patchAutoIncrementValues(input: ColumnarBatch, fill: AutoIncrementFill, range: RowIdRange): void;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/engine/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/engine/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACtF,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5D,2FAA2F;AAC3F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,+EAA+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,iGAAiG;IACjG,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,gGAAgG;IAChG,QAAQ,CAAC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;IAC9C;oFACgF;IAChF,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,CAAC;CAC5C;AAED,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,WAAW,EAClB,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,MAAM,IAAI,EACf,aAAa,CAAC,EAAE,MAAM,GACrB,WAAW,CA8Db;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,aAAa,EACpB,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,UAAU,GAChB,IAAI,CASN"}

package/dist/engine/defaults.js

@@ -0,0 +1,87 @@
+/**
+ * Write-time default filling. For a default-bearing column (always non-nullable), a null or
+ * absent slot means "generate" and an explicit value passes through untouched. Pure defaults
+ * (now, literals) are filled here before validation; auto-increment slots stay null until the
+ * write path reserves a range from storage, keeping generation atomic across concurrent
+ * writers. Function defaults never reach the engine — the typed facade fills them before the
+ * batch crosses the boundary.
+ */
+export function fillColumnDefaults(table, input, now, knownRowCount) {
+    const defaultColumns = table.columns.filter((column) => column.defaultValue !== undefined);
+    if (defaultColumns.length === 0)
+        return { batch: input, generated: new Map() };
+    const rowCount = knownRowCount ?? Object.values(input.columns).find((values) => values.length > 0)?.length ?? 0;
+    if (rowCount === 0)
+        return { batch: input, generated: new Map() };
+    const columns = { ...input.columns };
+    const generated = new Map();
+    let autoIncrement;
+    let nowValue;
+    for (const column of defaultColumns) {
+        const defaultValue = column.defaultValue;
+        if (defaultValue === undefined)
+            continue;
+        const provided = input.columns[column.name];
+        if (defaultValue.kind === "autoincrement") {
+            const missingIndexes = [];
+            let maxExplicit = 0n;
+            for (let index = 0; index < rowCount; index += 1) {
+                const value = provided?.[index] ?? null;
+                if (value === null) {
+                    missingIndexes.push(index);
+                    continue;
+                }
+                if (typeof value !== "number" || !Number.isSafeInteger(value)) {
+                    throw new TypeError(`${column.name}[${String(index)}] must be a whole number in the safe integer range`);
+                }
+                if (BigInt(value) > maxExplicit)
+                    maxExplicit = BigInt(value);
+            }
+            if (missingIndexes.length > 0) {
+                columns[column.name] =
+                    provided === undefined ? new Array(rowCount).fill(null) : [...provided];
+            }
+            autoIncrement = { column, missingIndexes, atLeast: maxExplicit + 1n };
+            continue;
+        }
+        const values = provided === undefined ? new Array(rowCount).fill(null) : [...provided];
+        let filled = false;
+        for (let index = 0; index < rowCount; index += 1) {
+            if ((values[index] ?? null) !== null)
+                continue;
+            filled = true;
+            switch (defaultValue.kind) {
+                case "now":
+                    values[index] = nowValue ??= now();
+                    break;
+                case "literal":
+                    values[index] = defaultValue.value;
+                    break;
+            }
+        }
+        if (filled) {
+            columns[column.name] = values;
+            generated.set(column.name, values);
+        }
+    }
+    return {
+        batch: { columns },
+        generated,
+        ...(autoIncrement === undefined ? {} : { autoIncrement }),
+    };
+}
+/**
+ * Writes the reserved range into the batch's null slots. The vector is the fresh array
+ * `fillColumnDefaults` created for this fill, never a caller-owned one.
+ */
+export function patchAutoIncrementValues(input, fill, range) {
+    const vector = input.columns[fill.column.name];
+    fill.missingIndexes.forEach((rowIndex, offset) => {
+        const value = range.start + BigInt(offset);
+        if (value > BigInt(Number.MAX_SAFE_INTEGER)) {
+            throw new RangeError(`Auto-increment exhausted the safe integer range: ${fill.column.name}`);
+        }
+        vector[rowIndex] = Number(value);
+    });
+}
+//# sourceMappingURL=defaults.js.map

package/dist/engine/defaults.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.js","sourceRoot":"","sources":["../../src/engine/defaults.ts"],"names":[],"mappings":"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"}

package/dist/engine/errors.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Typed engine errors, kept free of engine imports so the main-thread worker client can rehydrate
+ * them (name, fields, instanceof) without bundling the executor.
+ */
+type ErrorValue = boolean | number | string | Date;
+export declare class UniqueConstraintError extends Error {
+    readonly tableName: string;
+    readonly columnName: string;
+    readonly value: ErrorValue;
+    readonly name = "UniqueConstraintError";
+    constructor(tableName: string, columnName: string, value: ErrorValue);
+}
+export declare class MissingKeyError extends Error {
+    readonly tableName: string;
+    readonly columnName: string;
+    readonly value: ErrorValue;
+    readonly name = "MissingKeyError";
+    constructor(tableName: string, columnName: string, value: ErrorValue);
+}
+export declare class CompactionMemoryBudgetError extends Error {
+    readonly budgetBytes: number;
+    readonly minimumBytes: number;
+    readonly name = "CompactionMemoryBudgetError";
+    constructor(budgetBytes: number, minimumBytes: number);
+}
+export declare class CompactionWriteAmplificationError extends Error {
+    readonly outputBytes: number;
+    readonly maximumOutputBytes: number;
+    readonly name = "CompactionWriteAmplificationError";
+    constructor(outputBytes: number, maximumOutputBytes: number);
+}
+export declare class CompactionJobCancelledError extends Error {
+    readonly jobId: string;
+    readonly name = "CompactionJobCancelledError";
+    constructor(jobId: string);
+}
+/**
+ * SQL that failed to compile, located in the text the caller passed. `offset` and `length` are
+ * character positions into that exact string — leading whitespace included — so an editor can
+ * underline the token that failed without re-deriving the position from the message.
+ *
+ * `length` is 0 where the failure has no width: an empty statement, or a query that ended before
+ * the parser expected it to. Errors raised after parsing succeeds (plan optimization, execution)
+ * carry no position and stay plain `TypeError`s.
+ *
+ * It extends `TypeError` because that is what compilation failures threw before positions existed.
+ */
+export declare class SqlCompileError extends TypeError {
+    readonly offset: number;
+    readonly length: number;
+    readonly name = "SqlCompileError";
+    constructor(message: string, offset: number, length: number);
+}
+export {};
+//# sourceMappingURL=errors.d.ts.map

package/dist/engine/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/engine/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,KAAK,UAAU,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAMnD,qBAAa,qBAAsB,SAAQ,KAAK;IAI5C,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU;IAL5B,SAAkB,IAAI,2BAA2B;gBAGtC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU;CAI7B;AAED,qBAAa,eAAgB,SAAQ,KAAK;IAItC,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM;IAC3B,QAAQ,CAAC,KAAK,EAAE,UAAU;IAL5B,SAAkB,IAAI,qBAAqB;gBAGhC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,UAAU;CAI7B;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IAIlD,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM;IAJ/B,SAAkB,IAAI,iCAAiC;gBAG5C,WAAW,EAAE,MAAM,EACnB,YAAY,EAAE,MAAM;CAMhC;AAED,qBAAa,iCAAkC,SAAQ,KAAK;IAIxD,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,MAAM;IAJrC,SAAkB,IAAI,uCAAuC;gBAGlD,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM;CAMtC;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IAGxC,QAAQ,CAAC,KAAK,EAAE,MAAM;IAFlC,SAAkB,IAAI,iCAAiC;gBAElC,KAAK,EAAE,MAAM;CAGnC;AAED;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,SAAS;IAK1C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IALzB,SAAkB,IAAI,qBAAqB;gBAGzC,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM;CAI1B"}

package/dist/engine/errors.js

@@ -0,0 +1,81 @@
+/**
+ * Typed engine errors, kept free of engine imports so the main-thread worker client can rehydrate
+ * them (name, fields, instanceof) without bundling the executor.
+ */
+function formatValue(value) {
+    return value instanceof Date ? value.toISOString() : String(value);
+}
+export class UniqueConstraintError extends Error {
+    tableName;
+    columnName;
+    value;
+    name = "UniqueConstraintError";
+    constructor(tableName, columnName, value) {
+        super(`Duplicate value for ${tableName}.${columnName}: ${formatValue(value)}`);
+        this.tableName = tableName;
+        this.columnName = columnName;
+        this.value = value;
+    }
+}
+export class MissingKeyError extends Error {
+    tableName;
+    columnName;
+    value;
+    name = "MissingKeyError";
+    constructor(tableName, columnName, value) {
+        super(`Missing value for ${tableName}.${columnName}: ${formatValue(value)}`);
+        this.tableName = tableName;
+        this.columnName = columnName;
+        this.value = value;
+    }
+}
+export class CompactionMemoryBudgetError extends Error {
+    budgetBytes;
+    minimumBytes;
+    name = "CompactionMemoryBudgetError";
+    constructor(budgetBytes, minimumBytes) {
+        super(`Compaction needs at least ${String(minimumBytes)} bytes of working memory; budget is ${String(budgetBytes)} bytes`);
+        this.budgetBytes = budgetBytes;
+        this.minimumBytes = minimumBytes;
+    }
+}
+export class CompactionWriteAmplificationError extends Error {
+    outputBytes;
+    maximumOutputBytes;
+    name = "CompactionWriteAmplificationError";
+    constructor(outputBytes, maximumOutputBytes) {
+        super(`Compaction output would use ${String(outputBytes)} stored bytes; limit is ${String(maximumOutputBytes)} bytes`);
+        this.outputBytes = outputBytes;
+        this.maximumOutputBytes = maximumOutputBytes;
+    }
+}
+export class CompactionJobCancelledError extends Error {
+    jobId;
+    name = "CompactionJobCancelledError";
+    constructor(jobId) {
+        super(`Compaction job cancelled: ${jobId}`);
+        this.jobId = jobId;
+    }
+}
+/**
+ * SQL that failed to compile, located in the text the caller passed. `offset` and `length` are
+ * character positions into that exact string — leading whitespace included — so an editor can
+ * underline the token that failed without re-deriving the position from the message.
+ *
+ * `length` is 0 where the failure has no width: an empty statement, or a query that ended before
+ * the parser expected it to. Errors raised after parsing succeeds (plan optimization, execution)
+ * carry no position and stay plain `TypeError`s.
+ *
+ * It extends `TypeError` because that is what compilation failures threw before positions existed.
+ */
+export class SqlCompileError extends TypeError {
+    offset;
+    length;
+    name = "SqlCompileError";
+    constructor(message, offset, length) {
+        super(message);
+        this.offset = offset;
+        this.length = length;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/engine/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/engine/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,SAAS,WAAW,CAAC,KAAiB;IACpC,OAAO,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC;AAED,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAInC;IACA;IACA;IALO,IAAI,GAAG,uBAAuB,CAAC;IAEjD,YACW,SAAiB,EACjB,UAAkB,EAClB,KAAiB;QAE1B,KAAK,CAAC,uBAAuB,SAAS,IAAI,UAAU,KAAK,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAJtE,cAAS,GAAT,SAAS,CAAQ;QACjB,eAAU,GAAV,UAAU,CAAQ;QAClB,UAAK,GAAL,KAAK,CAAY;IAG5B,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAI7B;IACA;IACA;IALO,IAAI,GAAG,iBAAiB,CAAC;IAE3C,YACW,SAAiB,EACjB,UAAkB,EAClB,KAAiB;QAE1B,KAAK,CAAC,qBAAqB,SAAS,IAAI,UAAU,KAAK,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QAJpE,cAAS,GAAT,SAAS,CAAQ;QACjB,eAAU,GAAV,UAAU,CAAQ;QAClB,UAAK,GAAL,KAAK,CAAY;IAG5B,CAAC;CACF;AAED,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAIzC;IACA;IAJO,IAAI,GAAG,6BAA6B,CAAC;IAEvD,YACW,WAAmB,EACnB,YAAoB;QAE7B,KAAK,CACH,6BAA6B,MAAM,CAAC,YAAY,CAAC,uCAAuC,MAAM,CAAC,WAAW,CAAC,QAAQ,CACpH,CAAC;QALO,gBAAW,GAAX,WAAW,CAAQ;QACnB,iBAAY,GAAZ,YAAY,CAAQ;IAK/B,CAAC;CACF;AAED,MAAM,OAAO,iCAAkC,SAAQ,KAAK;IAI/C;IACA;IAJO,IAAI,GAAG,mCAAmC,CAAC;IAE7D,YACW,WAAmB,EACnB,kBAA0B;QAEnC,KAAK,CACH,+BAA+B,MAAM,CAAC,WAAW,CAAC,2BAA2B,MAAM,CAAC,kBAAkB,CAAC,QAAQ,CAChH,CAAC;QALO,gBAAW,GAAX,WAAW,CAAQ;QACnB,uBAAkB,GAAlB,kBAAkB,CAAQ;IAKrC,CAAC;CACF;AAED,MAAM,OAAO,2BAA4B,SAAQ,KAAK;IAG/B;IAFH,IAAI,GAAG,6BAA6B,CAAC;IAEvD,YAAqB,KAAa;QAChC,KAAK,CAAC,6BAA6B,KAAK,EAAE,CAAC,CAAC;QADzB,UAAK,GAAL,KAAK,CAAQ;IAElC,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,OAAO,eAAgB,SAAQ,SAAS;IAKjC;IACA;IALO,IAAI,GAAG,iBAAiB,CAAC;IAE3C,YACE,OAAe,EACN,MAAc,EACd,MAAc;QAEvB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,WAAM,GAAN,MAAM,CAAQ;QACd,WAAM,GAAN,MAAM,CAAQ;IAGzB,CAAC;CACF"}

package/dist/engine/fts.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Full-text search primitives: the tokenizer, the query grammar, and the BM25 scorer.
+ *
+ * The tokenizer is deliberately hand-rolled rather than `Intl.Segmenter`: segmentation output
+ * must be identical across browsers, ICU versions, and time, because phase-2 persists tokens in
+ * a multi-tab shared index — an environment-varying tokenizer would silently split one logical
+ * index into two vocabularies. Any change to tokenization must bump `FTS_TOKENIZER_VERSION`;
+ * a persisted index stamped with another version reads as absent and rebuilds.
+ *
+ * The scorer takes only integers (term frequency, document length, document frequency, document
+ * count, total token count), so the row and columnar executors produce bit-identical scores no
+ * matter what order they accumulate in. Keep it that way: never feed it a running float.
+ */
+export declare const FTS_TOKENIZER_VERSION = 1;
+/** One parsed query term; `prefix` terms match any token they prefix. */
+export interface FtsQueryTerm {
+    readonly term: string;
+    readonly prefix: boolean;
+}
+/**
+ * Corpus statistics for one (columns, query) signature — O(#query terms) integers. Every row of
+ * the corpus counts as a document (an all-null document has length 0): this definition is what
+ * lets a persisted index serve exact statistics without a scan, since the document count is
+ * just the table's row count. All producers — the row executor, the columnar scan, and the
+ * postings index — must share it, or BM25 scores drift between paths.
+ */
+export interface FtsStats {
+    /** Every row of the corpus, including all-null documents. */
+    docCount: number;
+    /** Total tokens across all documents. */
+    totalTokens: number;
+    /** Documents containing each query term, aligned with the query's term order. */
+    dfByTerm: number[];
+}
+/** Tokenizes one cell's text: NFKC, locale-independent lowercase, letter/number runs. */
+export declare function tokenize(text: string): string[];
+/**
+ * Parses a query: whitespace-separated chunks, each tokenized with the document pipeline; a
+ * chunk ending in `*` marks its last produced token as a prefix term. Zero terms means the
+ * query matches nothing.
+ */
+export declare function tokenizeQuery(query: string): FtsQueryTerm[];
+export declare function termMatches(token: string, term: FtsQueryTerm): boolean;
+/**
+ * Compile-time cap on query terms: the columnar fast path packs per-term presence into one
+ * 32-bit mask per dictionary entry.
+ */
+export declare const FTS_MAX_QUERY_TERMS = 32;
+/** Tokenized query terms with the same bounded caching scheme as the LIKE pattern cache. */
+export declare function cachedQueryTerms(query: string): FtsQueryTerm[];
+/** Compile-time validation shared by the SQL parser and the DSL expression builder. */
+export declare function validateFtsQuery(query: string): void;
+/** Bitmask of query terms present in a token list: bit i set means terms[i] matched. */
+export declare function termsMask(tokens: readonly string[], terms: readonly FtsQueryTerm[]): number;
+/** The all-terms-present mask; terms.length is capped at 32 so the shift stays in range. */
+export declare function fullTermsMask(termCount: number): number;
+/**
+ * Document-level MATCH truth over one row's rendered column values: every term must appear in
+ * some column (AND across terms, OR across columns). All columns null → SQL unknown (null);
+ * an empty query matches nothing.
+ */
+export declare function ftsMatchTruth(terms: readonly FtsQueryTerm[], values: Iterable<unknown>): boolean | null;
+/**
+ * Per-term frequencies of the query's terms in one token list, aligned with the term order.
+ * A document matches when every slot is non-zero.
+ */
+export declare function termFrequencies(tokens: readonly string[], terms: readonly FtsQueryTerm[]): number[];
+/**
+ * One term's BM25 contribution. Integer inputs only — see the module comment. `df` of zero
+ * contributes nothing (the term appears in no document, so no row scores on it).
+ */
+export declare function bm25Score(tf: number, docLength: number, df: number, docCount: number, totalTokens: number): number;
+/** Sums the contributions of every query term for one document. */
+export declare function bm25DocumentScore(frequencies: readonly number[], docLength: number, stats: FtsStats): number;
+/** Accumulates corpus statistics one document at a time; every producer feeds this. */
+export declare class FtsStatsAccumulator {
+    #private;
+    constructor(terms: readonly FtsQueryTerm[]);
+    /** Adds one document; an all-null row contributes a document of length 0. */
+    addDocument(tokens: readonly string[]): void;
+    /** Adds one document from pre-aggregated counts (the dictionary-table producers). */
+    addDocumentCounts(termMask: number, length: number): void;
+    get stats(): FtsStats;
+}
+/**
+ * Document-level BM25 for one row's rendered column values: term frequencies and document
+ * length sum across columns (the document is the concatenation of its fields). All columns
+ * null → SQL null; a document containing no query term scores 0.
+ */
+export declare function ftsBm25Row(terms: readonly FtsQueryTerm[], values: Iterable<unknown>, stats: FtsStats): number | null;
+/** Renders one cell for the document, per column type. Booleans are excluded from documents. */
+export declare function renderDocumentValue(value: unknown): string | undefined;
+//# sourceMappingURL=fts.d.ts.map

package/dist/engine/fts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fts.d.ts","sourceRoot":"","sources":["../../src/engine/fts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAevC,yEAAyE;AACzE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,QAAQ;IACvB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAmCD,yFAAyF;AACzF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ/C;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAW3D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAEtE;AAED;;;GAGG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAItC,4FAA4F;AAC5F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAO9D;AAED,uFAAuF;AACvF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAIpD;AAED,wFAAwF;AACxF,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,SAAS,YAAY,EAAE,GAAG,MAAM,CAW3F;AAED,4FAA4F;AAC5F,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GACxB,OAAO,GAAG,IAAI,CAsBhB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,EACzB,KAAK,EAAE,SAAS,YAAY,EAAE,GAC7B,MAAM,EAAE,CAWV;AAED;;;GAGG;AACH,wBAAgB,SAAS,CACvB,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,EACjB,EAAE,EAAE,MAAM,EACV,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,MAAM,CASR;AAED,mEAAmE;AACnE,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,SAAS,MAAM,EAAE,EAC9B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,GACd,MAAM,CAYR;AAED,uFAAuF;AACvF,qBAAa,mBAAmB;;gBAIlB,KAAK,EAAE,SAAS,YAAY,EAAE;IAS1C,6EAA6E;IAC7E,WAAW,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAW5C,qFAAqF;IACrF,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAUzD,IAAI,KAAK,IAAI,QAAQ,CAEpB;CACF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,EACzB,KAAK,EAAE,QAAQ,GACd,MAAM,GAAG,IAAI,CAiBf;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAKtE"}

package/dist/engine/fts.js

@@ -0,0 +1,273 @@
+/**
+ * Full-text search primitives: the tokenizer, the query grammar, and the BM25 scorer.
+ *
+ * The tokenizer is deliberately hand-rolled rather than `Intl.Segmenter`: segmentation output
+ * must be identical across browsers, ICU versions, and time, because phase-2 persists tokens in
+ * a multi-tab shared index — an environment-varying tokenizer would silently split one logical
+ * index into two vocabularies. Any change to tokenization must bump `FTS_TOKENIZER_VERSION`;
+ * a persisted index stamped with another version reads as absent and rebuilds.
+ *
+ * The scorer takes only integers (term frequency, document length, document frequency, document
+ * count, total token count), so the row and columnar executors produce bit-identical scores no
+ * matter what order they accumulate in. Keep it that way: never feed it a running float.
+ */
+export const FTS_TOKENIZER_VERSION = 1;
+/** BM25 constants — the standard defaults. */
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+const MAX_TOKEN_LENGTH = 32;
+const MAX_TOKENS_PER_DOCUMENT = 4096;
+const TOKEN_RUN = /[\p{L}\p{N}]+/gu;
+// Script_Extensions rather than Script: shared marks like the katakana prolonged sound mark
+// (U+30FC, script Common) must stay inside the kana run they extend.
+const CJK = /[\p{Script_Extensions=Han}\p{Script_Extensions=Hiragana}\p{Script_Extensions=Katakana}]/u;
+function pushToken(tokens, token) {
+    if (tokens.length >= MAX_TOKENS_PER_DOCUMENT)
+        return;
+    tokens.push(token.length > MAX_TOKEN_LENGTH ? token.slice(0, MAX_TOKEN_LENGTH) : token);
+}
+/**
+ * Splits one normalized run into tokens: contiguous CJK subsequences emit character bigrams
+ * (a single character when alone), everything else stays one token. Bigrams give usable CJK
+ * search without a dictionary while staying fully deterministic.
+ */
+function emitRun(tokens, run) {
+    if (!CJK.test(run)) {
+        pushToken(tokens, run);
+        return;
+    }
+    const characters = Array.from(run);
+    let start = 0;
+    while (start < characters.length) {
+        const isCjk = CJK.test(characters[start] ?? "");
+        let end = start + 1;
+        while (end < characters.length && CJK.test(characters[end] ?? "") === isCjk)
+            end += 1;
+        if (isCjk) {
+            if (end - start === 1)
+                pushToken(tokens, characters[start] ?? "");
+            for (let index = start; index < end - 1; index += 1) {
+                pushToken(tokens, (characters[index] ?? "") + (characters[index + 1] ?? ""));
+            }
+        }
+        else {
+            pushToken(tokens, characters.slice(start, end).join(""));
+        }
+        start = end;
+    }
+}
+/** Tokenizes one cell's text: NFKC, locale-independent lowercase, letter/number runs. */
+export function tokenize(text) {
+    const tokens = [];
+    const normalized = text.normalize("NFKC").toLowerCase();
+    for (const match of normalized.matchAll(TOKEN_RUN)) {
+        emitRun(tokens, match[0]);
+        if (tokens.length >= MAX_TOKENS_PER_DOCUMENT)
+            break;
+    }
+    return tokens;
+}
+/**
+ * Parses a query: whitespace-separated chunks, each tokenized with the document pipeline; a
+ * chunk ending in `*` marks its last produced token as a prefix term. Zero terms means the
+ * query matches nothing.
+ */
+export function tokenizeQuery(query) {
+    const terms = [];
+    for (const chunk of query.split(/\s+/)) {
+        if (chunk.length === 0)
+            continue;
+        const prefix = chunk.endsWith("*");
+        const tokens = tokenize(prefix ? chunk.slice(0, -1) : chunk);
+        tokens.forEach((term, index) => {
+            terms.push({ term, prefix: prefix && index === tokens.length - 1 });
+        });
+    }
+    return terms;
+}
+export function termMatches(token, term) {
+    return term.prefix ? token.startsWith(term.term) : token === term.term;
+}
+/**
+ * Compile-time cap on query terms: the columnar fast path packs per-term presence into one
+ * 32-bit mask per dictionary entry.
+ */
+export const FTS_MAX_QUERY_TERMS = 32;
+const queryTermsCache = new Map();
+/** Tokenized query terms with the same bounded caching scheme as the LIKE pattern cache. */
+export function cachedQueryTerms(query) {
+    const cached = queryTermsCache.get(query);
+    if (cached !== undefined)
+        return cached;
+    const terms = tokenizeQuery(query);
+    if (queryTermsCache.size >= 128)
+        queryTermsCache.clear();
+    queryTermsCache.set(query, terms);
+    return terms;
+}
+/** Compile-time validation shared by the SQL parser and the DSL expression builder. */
+export function validateFtsQuery(query) {
+    if (cachedQueryTerms(query).length > FTS_MAX_QUERY_TERMS) {
+        throw new TypeError(`Full-text queries support at most ${String(FTS_MAX_QUERY_TERMS)} terms`);
+    }
+}
+/** Bitmask of query terms present in a token list: bit i set means terms[i] matched. */
+export function termsMask(tokens, terms) {
+    let mask = 0;
+    for (const token of tokens) {
+        for (let index = 0; index < terms.length; index += 1) {
+            const term = terms[index];
+            if (term !== undefined && (mask & (1 << index)) === 0 && termMatches(token, term)) {
+                mask |= 1 << index;
+            }
+        }
+    }
+    return mask;
+}
+/** The all-terms-present mask; terms.length is capped at 32 so the shift stays in range. */
+export function fullTermsMask(termCount) {
+    return termCount >= 32 ? -1 : (1 << termCount) - 1;
+}
+/**
+ * Document-level MATCH truth over one row's rendered column values: every term must appear in
+ * some column (AND across terms, OR across columns). All columns null → SQL unknown (null);
+ * an empty query matches nothing.
+ */
+export function ftsMatchTruth(terms, values) {
+    let anyPresent = false;
+    const present = new Array(terms.length).fill(false);
+    let satisfied = 0;
+    for (const value of values) {
+        const rendered = renderDocumentValue(value);
+        if (rendered === undefined)
+            continue;
+        anyPresent = true;
+        if (terms.length === 0 || satisfied === terms.length)
+            continue;
+        for (const token of tokenize(rendered)) {
+            for (let index = 0; index < terms.length; index += 1) {
+                const term = terms[index];
+                if (term !== undefined && present[index] !== true && termMatches(token, term)) {
+                    present[index] = true;
+                    satisfied += 1;
+                }
+            }
+            if (satisfied === terms.length)
+                break;
+        }
+    }
+    if (!anyPresent)
+        return null;
+    return terms.length > 0 && satisfied === terms.length;
+}
+/**
+ * Per-term frequencies of the query's terms in one token list, aligned with the term order.
+ * A document matches when every slot is non-zero.
+ */
+export function termFrequencies(tokens, terms) {
+    const frequencies = new Array(terms.length).fill(0);
+    for (const token of tokens) {
+        for (let index = 0; index < terms.length; index += 1) {
+            const term = terms[index];
+            if (term !== undefined && termMatches(token, term)) {
+                frequencies[index] = (frequencies[index] ?? 0) + 1;
+            }
+        }
+    }
+    return frequencies;
+}
+/**
+ * One term's BM25 contribution. Integer inputs only — see the module comment. `df` of zero
+ * contributes nothing (the term appears in no document, so no row scores on it).
+ */
+export function bm25Score(tf, docLength, df, docCount, totalTokens) {
+    if (tf === 0 || df === 0 || docCount === 0)
+        return 0;
+    const idf = Math.log(1 + (docCount - df + 0.5) / (df + 0.5));
+    const averageLength = totalTokens / docCount;
+    const normalized = (tf * (BM25_K1 + 1)) /
+        (tf +
+            BM25_K1 * (1 - BM25_B + (BM25_B * docLength) / (averageLength === 0 ? 1 : averageLength)));
+    return idf * normalized;
+}
+/** Sums the contributions of every query term for one document. */
+export function bm25DocumentScore(frequencies, docLength, stats) {
+    let score = 0;
+    for (let index = 0; index < frequencies.length; index += 1) {
+        score += bm25Score(frequencies[index] ?? 0, docLength, stats.dfByTerm[index] ?? 0, stats.docCount, stats.totalTokens);
+    }
+    return score;
+}
+/** Accumulates corpus statistics one document at a time; every producer feeds this. */
+export class FtsStatsAccumulator {
+    #terms;
+    #stats;
+    constructor(terms) {
+        this.#terms = terms;
+        this.#stats = {
+            docCount: 0,
+            totalTokens: 0,
+            dfByTerm: new Array(terms.length).fill(0),
+        };
+    }
+    /** Adds one document; an all-null row contributes a document of length 0. */
+    addDocument(tokens) {
+        this.#stats.docCount += 1;
+        this.#stats.totalTokens += tokens.length;
+        const frequencies = termFrequencies(tokens, this.#terms);
+        for (let index = 0; index < frequencies.length; index += 1) {
+            if ((frequencies[index] ?? 0) > 0) {
+                this.#stats.dfByTerm[index] = (this.#stats.dfByTerm[index] ?? 0) + 1;
+            }
+        }
+    }
+    /** Adds one document from pre-aggregated counts (the dictionary-table producers). */
+    addDocumentCounts(termMask, length) {
+        this.#stats.docCount += 1;
+        this.#stats.totalTokens += length;
+        for (let index = 0; index < this.#terms.length; index += 1) {
+            if ((termMask & (1 << index)) !== 0) {
+                this.#stats.dfByTerm[index] = (this.#stats.dfByTerm[index] ?? 0) + 1;
+            }
+        }
+    }
+    get stats() {
+        return this.#stats;
+    }
+}
+/**
+ * Document-level BM25 for one row's rendered column values: term frequencies and document
+ * length sum across columns (the document is the concatenation of its fields). All columns
+ * null → SQL null; a document containing no query term scores 0.
+ */
+export function ftsBm25Row(terms, values, stats) {
+    let anyPresent = false;
+    let docLength = 0;
+    const frequencies = new Array(terms.length).fill(0);
+    for (const value of values) {
+        const rendered = renderDocumentValue(value);
+        if (rendered === undefined)
+            continue;
+        anyPresent = true;
+        const tokens = tokenize(rendered);
+        docLength += tokens.length;
+        const partial = termFrequencies(tokens, terms);
+        for (let index = 0; index < terms.length; index += 1) {
+            frequencies[index] = (frequencies[index] ?? 0) + (partial[index] ?? 0);
+        }
+    }
+    if (!anyPresent)
+        return null;
+    return bm25DocumentScore(frequencies, docLength, stats);
+}
+/** Renders one cell for the document, per column type. Booleans are excluded from documents. */
+export function renderDocumentValue(value) {
+    if (value === null || value === undefined || typeof value === "boolean")
+        return undefined;
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "number")
+        return String(value);
+    return typeof value === "string" ? value : undefined;
+}
+//# sourceMappingURL=fts.js.map