@minnowdb/core 0.0.1 → 0.1.0

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

package/dist/engine/fts.js.map

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

package/dist/engine/group-index.d.ts

@@ -0,0 +1,32 @@
+import { QueryMemoryContext } from "./memory.js";
+export type GroupIndexKey = null | boolean | number | string;
+/** Byte-addressable, insertion-ordered grouping index with fully reserved typed storage. */
+export declare class ByteGroupIndex<T> {
+    #private;
+    constructor(memory: QueryMemoryContext);
+    get size(): number;
+    get(keys: readonly GroupIndexKey[]): T | undefined;
+    getEmpty(): T | undefined;
+    getOne(key: GroupIndexKey): T | undefined;
+    set(keys: readonly GroupIndexKey[], value: T): void;
+    getOrInsert(keys: readonly GroupIndexKey[], create: () => T): T;
+    getOrInsertOne(key: GroupIndexKey, create: () => T): T;
+    setEmpty(value: T): void;
+    setOne(key: GroupIndexKey, value: T): void;
+    values(): readonly T[];
+}
+/**
+ * Encodes one scalar key into the shared scratch arena and returns its byte length. Exported for
+ * the join index, which shares the arena and byte layout: both consume the encoding synchronously
+ * before any other key operation can run, so a single arena serves every index. NaN is the one
+ * excluded number — group callers canonicalize non-finite to null, join callers skip NaN keys —
+ * while ±Infinity encodes as an ordinary float64 so computed join keys can overflow and still match.
+ */
+export declare function encodeSingleScalarKey(key: GroupIndexKey): number;
+/** FNV-1a over the scratch arena's first `length` bytes. Exported for the join index. */
+export declare function hashScratch(length: number): number;
+/** Matches `arena[offset..offset+length)` against the scratch arena. Exported for the join index. */
+export declare function equalsScratch(arena: Uint8Array, offset: number, length: number): boolean;
+/** Copies the scratch arena's first `length` bytes into owned storage. Exported for the join index. */
+export declare function copyScratchKey(length: number): Uint8Array;
+//# sourceMappingURL=group-index.d.ts.map

package/dist/engine/group-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-index.d.ts","sourceRoot":"","sources":["../../src/engine/group-index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAA+B,MAAM,aAAa,CAAC;AA4B9E,MAAM,MAAM,aAAa,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7D,4FAA4F;AAC5F,qBAAa,cAAc,CAAC,CAAC;;gBAcf,MAAM,EAAE,kBAAkB;IAItC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,GAAG,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,GAAG,CAAC,GAAG,SAAS;IAMlD,QAAQ,IAAI,CAAC,GAAG,SAAS;IAIzB,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,CAAC,GAAG,SAAS;IAMzC,GAAG,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAWnD,WAAW,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;IAK/D,cAAc,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC;IAqCtD,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAIxB,MAAM,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAI1C,MAAM,IAAI,SAAS,CAAC,EAAE;CAkGvB;AAeD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,CAGhE;AAmGD,yFAAyF;AACzF,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAMlD;AAED,qGAAqG;AACrG,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAKxF;AAED,uGAAuG;AACvG,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAEzD"}