@minnowdb/core 0.1.0 → 0.2.0

package/dist/engine/result-wire.d.ts

@@ -0,0 +1,68 @@
+import type { QueryResult, QueryRow, QueryValue } from "./query.js";
+/**
+ * The shape a query result takes on the worker channel. A result is rows of objects at the
+ * public API on both sides, but row objects are the slowest thing structured clone can be
+ * handed: every row is a fresh object with its own property names. Pivoted into one array per
+ * column — numbers, booleans, and datetimes in typed arrays whose buffers are transferred, and
+ * strings as one flat text with offsets — the same 20,000-row result crosses in a fraction of the
+ * time, and the receiving side rebuilds the rows column by column in tight loops.
+ *
+ * Every value round-trips exactly: NaN, -0, and Infinity survive in a Float64Array, datetimes
+ * travel as epoch milliseconds (an invalid Date's NaN included), nulls in a typed column live in
+ * a byte mask, and a column name like `__proto__` comes back as the own property the engine
+ * defined — never as a prototype assignment.
+ */
+export type WireResultColumn = {
+    kind: "number";
+    values: Float64Array;
+    nulls?: Uint8Array;
+} | {
+    kind: "boolean";
+    values: Uint8Array;
+    nulls?: Uint8Array;
+} | {
+    kind: "datetime";
+    values: Float64Array;
+    nulls?: Uint8Array;
+}
+/**
+ * Every string in the column joined into one flat text, with `offsets[i]..offsets[i + 1]`
+ * delimiting row i. Structured clone copies one string instead of walking thousands, and the
+ * receiver slices rows back out of it — far cheaper on the main thread than an array of
+ * separate strings, which is the form the engine's decoded values would otherwise take.
+ */
+ | {
+    kind: "string";
+    text: string;
+    offsets: Uint32Array;
+    nulls?: Uint8Array;
+}
+/** A column holding more than one type, which SQL allows (`SELECT CASE … END`). */
+ | {
+    kind: "mixed";
+    values: QueryValue[];
+}
+/** Every value null; nothing to carry beyond the row count. */
+ | {
+    kind: "null";
+};
+export interface WireQueryResult {
+    readonly kind: "columnar-result";
+    readonly columns: string[];
+    readonly rowCount: number;
+    readonly values: WireResultColumn[];
+}
+export interface EncodedQueryResult {
+    payload: WireQueryResult;
+    /** The typed-array buffers, freshly allocated here, so postMessage may transfer them. */
+    transfer: ArrayBuffer[];
+}
+export declare function encodeQueryResult(result: QueryResult): EncodedQueryResult;
+/**
+ * Encodes a bare row array (`run()` returns rows without a column list). Every row of one result
+ * carries the same keys in the same order, so the first row names the columns.
+ */
+export declare function encodeQueryRows(rows: readonly QueryRow[]): EncodedQueryResult;
+export declare function decodeQueryResult(payload: unknown): QueryResult;
+export declare function isWireQueryResult(value: unknown): value is WireQueryResult;
+//# sourceMappingURL=result-wire.d.ts.map

package/dist/engine/result-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result-wire.d.ts","sourceRoot":"","sources":["../../src/engine/result-wire.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAEpE;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,GAC5D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,YAAY,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE;AAChE;;;;;GAKG;GACD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,WAAW,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE;AAC5E,mFAAmF;GACjF;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,UAAU,EAAE,CAAA;CAAE;AACzC,+DAA+D;GAC7D;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAErB,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,eAAe,CAAC;IACzB,yFAAyF;IACzF,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,kBAAkB,CAEzE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,GAAG,kBAAkB,CAG7E;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAe/D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAS1E"}

package/dist/engine/result-wire.js

@@ -0,0 +1,264 @@
+export function encodeQueryResult(result) {
+    return encodeRows(result.columns, result.rows);
+}
+/**
+ * Encodes a bare row array (`run()` returns rows without a column list). Every row of one result
+ * carries the same keys in the same order, so the first row names the columns.
+ */
+export function encodeQueryRows(rows) {
+    const first = rows[0];
+    return encodeRows(first === undefined ? [] : Object.keys(first), rows);
+}
+export function decodeQueryResult(payload) {
+    if (!isWireQueryResult(payload)) {
+        throw new TypeError("Expected a columnar query result frame");
+    }
+    const columns = [...payload.columns];
+    const rows = [];
+    for (let index = 0; index < payload.rowCount; index += 1)
+        rows.push({});
+    // Column by column: each fill loop stores one property name into every row, which the engine
+    // runs noticeably faster than visiting every column of each row in turn.
+    for (const [position, name] of columns.entries()) {
+        const column = payload.values[position];
+        if (column === undefined)
+            throw new TypeError("Columnar result frame is missing a column");
+        fillColumn(rows, name, column);
+    }
+    return { columns, rows };
+}
+export function isWireQueryResult(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        value.kind === "columnar-result" &&
+        Array.isArray(value.columns) &&
+        Array.isArray(value.values) &&
+        typeof value.rowCount === "number");
+}
+function encodeRows(columns, rows) {
+    const transfer = [];
+    const values = columns.map((name) => {
+        const column = encodeColumn(name, rows);
+        if (column.kind === "number" || column.kind === "boolean" || column.kind === "datetime") {
+            transfer.push(column.values.buffer);
+            if (column.nulls !== undefined)
+                transfer.push(column.nulls.buffer);
+        }
+        else if (column.kind === "string") {
+            transfer.push(column.offsets.buffer);
+            if (column.nulls !== undefined)
+                transfer.push(column.nulls.buffer);
+        }
+        return column;
+    });
+    return {
+        payload: { kind: "columnar-result", columns: [...columns], rowCount: rows.length, values },
+        transfer,
+    };
+}
+/**
+ * The first non-null value picks the column's typed form; a later value of another type demotes
+ * the whole column to the mixed form, which is rare enough to restart from scratch rather than
+ * to plan for.
+ */
+function encodeColumn(name, rows) {
+    const rowCount = rows.length;
+    let start = 0;
+    while (start < rowCount && (rows[start]?.[name] ?? null) === null)
+        start += 1;
+    const first = rows[start]?.[name] ?? null;
+    if (first === null)
+        return { kind: "null" };
+    if (typeof first === "number") {
+        const values = new Float64Array(rowCount);
+        let nulls = start === 0 ? undefined : nullMask(rowCount, start);
+        for (let index = start; index < rowCount; index += 1) {
+            const value = rows[index]?.[name] ?? null;
+            if (value === null) {
+                nulls ??= new Uint8Array(rowCount);
+                nulls[index] = 1;
+            }
+            else if (typeof value === "number") {
+                values[index] = value;
+            }
+            else {
+                return encodeMixed(name, rows);
+            }
+        }
+        return nulls === undefined ? { kind: "number", values } : { kind: "number", values, nulls };
+    }
+    if (typeof first === "boolean") {
+        const values = new Uint8Array(rowCount);
+        let nulls = start === 0 ? undefined : nullMask(rowCount, start);
+        for (let index = start; index < rowCount; index += 1) {
+            const value = rows[index]?.[name] ?? null;
+            if (value === null) {
+                nulls ??= new Uint8Array(rowCount);
+                nulls[index] = 1;
+            }
+            else if (typeof value === "boolean") {
+                values[index] = value ? 1 : 0;
+            }
+            else {
+                return encodeMixed(name, rows);
+            }
+        }
+        return nulls === undefined ? { kind: "boolean", values } : { kind: "boolean", values, nulls };
+    }
+    if (first instanceof Date) {
+        const values = new Float64Array(rowCount);
+        let nulls = start === 0 ? undefined : nullMask(rowCount, start);
+        for (let index = start; index < rowCount; index += 1) {
+            const value = rows[index]?.[name] ?? null;
+            if (value === null) {
+                nulls ??= new Uint8Array(rowCount);
+                nulls[index] = 1;
+            }
+            else if (value instanceof Date) {
+                values[index] = value.getTime();
+            }
+            else {
+                return encodeMixed(name, rows);
+            }
+        }
+        return nulls === undefined ? { kind: "datetime", values } : { kind: "datetime", values, nulls };
+    }
+    if (typeof first === "string") {
+        const offsets = new Uint32Array(rowCount + 1);
+        let nulls = start === 0 ? undefined : nullMask(rowCount, start);
+        const parts = [];
+        let length = 0;
+        for (let index = start; index < rowCount; index += 1) {
+            const value = rows[index]?.[name] ?? null;
+            if (value === null) {
+                nulls ??= new Uint8Array(rowCount);
+                nulls[index] = 1;
+            }
+            else if (typeof value === "string") {
+                parts.push(value);
+                length += value.length;
+            }
+            else {
+                return encodeMixed(name, rows);
+            }
+            offsets[index + 1] = length;
+        }
+        const text = parts.join("");
+        return nulls === undefined
+            ? { kind: "string", text, offsets }
+            : { kind: "string", text, offsets, nulls };
+    }
+    return encodeMixed(name, rows);
+}
+function encodeMixed(name, rows) {
+    return { kind: "mixed", values: rows.map((row) => row[name] ?? null) };
+}
+/** A null mask whose first `nullCount` rows are already null. */
+function nullMask(rowCount, nullCount) {
+    const nulls = new Uint8Array(rowCount);
+    nulls.fill(1, 0, nullCount);
+    return nulls;
+}
+/** Stores one decoded column into every row under `name`. */
+function fillColumn(rows, name, column) {
+    if (name === "__proto__") {
+        // Assignment through `row["__proto__"]` would set the prototype; this column goes through
+        // Object.defineProperty, which is what the engine itself does for the name.
+        const values = decodeColumnValues(column, rows.length);
+        let index = 0;
+        for (const row of rows) {
+            Object.defineProperty(row, name, {
+                value: values[index] ?? null,
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+            index += 1;
+        }
+        return;
+    }
+    let index = 0;
+    switch (column.kind) {
+        case "number": {
+            const { values, nulls } = column;
+            if (nulls === undefined) {
+                for (const row of rows) {
+                    row[name] = values[index] ?? 0;
+                    index += 1;
+                }
+            }
+            else {
+                for (const row of rows) {
+                    row[name] = nulls[index] === 1 ? null : (values[index] ?? 0);
+                    index += 1;
+                }
+            }
+            return;
+        }
+        case "boolean": {
+            const { values, nulls } = column;
+            for (const row of rows) {
+                row[name] = nulls?.[index] === 1 ? null : values[index] === 1;
+                index += 1;
+            }
+            return;
+        }
+        case "datetime": {
+            const { values, nulls } = column;
+            for (const row of rows) {
+                row[name] = nulls?.[index] === 1 ? null : new Date(values[index] ?? 0);
+                index += 1;
+            }
+            return;
+        }
+        case "string": {
+            const { text, offsets, nulls } = column;
+            for (const row of rows) {
+                row[name] =
+                    nulls?.[index] === 1 ? null : text.slice(offsets[index] ?? 0, offsets[index + 1] ?? 0);
+                index += 1;
+            }
+            return;
+        }
+        case "mixed": {
+            const { values } = column;
+            for (const row of rows) {
+                row[name] = values[index] ?? null;
+                index += 1;
+            }
+            return;
+        }
+        case "null":
+            for (const row of rows)
+                row[name] = null;
+    }
+}
+/** One column back into plain values, for the one name that cannot be assigned through. */
+function decodeColumnValues(column, rowCount) {
+    const values = [];
+    for (let index = 0; index < rowCount; index += 1) {
+        switch (column.kind) {
+            case "number":
+                values.push(column.nulls?.[index] === 1 ? null : (column.values[index] ?? 0));
+                break;
+            case "boolean":
+                values.push(column.nulls?.[index] === 1 ? null : column.values[index] === 1);
+                break;
+            case "datetime":
+                values.push(column.nulls?.[index] === 1 ? null : new Date(column.values[index] ?? 0));
+                break;
+            case "string":
+                values.push(column.nulls?.[index] === 1
+                    ? null
+                    : column.text.slice(column.offsets[index] ?? 0, column.offsets[index + 1] ?? 0));
+                break;
+            case "mixed":
+                values.push(column.values[index] ?? null);
+                break;
+            case "null":
+                values.push(null);
+        }
+    }
+    return values;
+}
+//# sourceMappingURL=result-wire.js.map

package/dist/engine/result-wire.js.map

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

package/dist/engine/sort-keys.d.ts

@@ -1,17 +1,23 @@
 /**
- * Order-by keys prepared for comparison.
+ * Order-by keys prepared for sorting, and the sort that runs over them.
  *
  * Sorting is comparison-bound: a merge over n rows performs O(n log n) of them, so what one
  * comparison costs decides what the sort costs. Reading a value out of a row by name and then
- * dispatching on its type at every step is most of that cost, and both of it is avoidable —
+ * dispatching on its type at every step is most of that cost, and all of it is avoidable —
  * the values are known before the sort starts, and a term's type does not vary row to row.
  *
- * Each term is extracted once into its own column. A term whose values are all numbers — which
- * includes every datetime, since extraction unboxes them to epoch milliseconds — is stored in a
- * Float64Array beside a null mask, and comparing it is two typed reads and a subtraction. Any
- * other term keeps its values and the generic comparison. The specialized form costs the same
- * eight bytes per key a reference did, plus one byte of mask, so this buys speed with locality
- * rather than with memory.
+ * Each term is extracted once into its own column. A term whose values are all numbers —
+ * which includes every datetime, since extraction unboxes them to epoch milliseconds — or all
+ * booleans is stored in a Float64Array beside a null mask. A string term is stored the same
+ * way, as the rank of each string among the sorted distinct values: the dictionary a string
+ * vector already carries is exactly that set, and comparing two ranks orders the two strings.
+ * Only a term that mixes types keeps its values and the generic comparison.
+ *
+ * With the keys unboxed, the sort itself stops comparing. `sortKeyIndexes` radix-sorts the
+ * leading key's float bits, recognizes input that already arrives in order, and only falls back
+ * to a comparison merge for the terms it cannot encode. Ties on one term are broken by the
+ * next, so what a multi-term sort pays for its later terms is proportional to how many rows tie
+ * on the earlier ones.
  */
 export interface SortKeyColumn {
     /**
@@ -19,18 +25,50 @@ export interface SortKeyColumn {
      * SQLite. Direction and an explicit NULLS FIRST/LAST stay with the caller: a placement is
      * absolute, while direction negates the value comparison.
      *
-     * Specialized when the column is built, so the comparison a sort runs millions of times is a
+     * Specialized when the column is built, so a comparison that runs millions of times is a
      * closure over one representation rather than a branch on which representation it holds.
      */
     readonly compare: (left: number, right: number) => number;
     readonly isNull: (index: number) => boolean;
+    /**
+     * The unboxed keys, when the column has them: numbers, epoch milliseconds, 0/1 for booleans,
+     * or string ranks. Both arrays are present or neither is. Equal numbers mean equal keys and
+     * their order is the order `compare` reports, so a sort can work on these alone.
+     */
+    readonly numbers: Float64Array | undefined;
+    readonly nulls: Uint8Array | undefined;
+}
+/** One ORDER BY term as the sort sees it: its keys, its direction, and its NULL placement. */
+export interface SortKeyTerm {
+    readonly column: SortKeyColumn;
+    readonly descending: boolean;
+    readonly nulls: "first" | "last" | undefined;
 }
 /** Unwraps a datetime to the number the comparisons use; every other value passes through. */
 export declare function comparableSortValue(value: unknown): unknown;
 /**
- * Extracts one term's values into a comparison-ready column. `valueAt` is called exactly once
- * per row, so a caller that reads through a row object or a vector pays that cost once rather
- * than once per comparison.
+ * Extracts one term's values into a comparison-ready column. `valueAt` is called once per row,
+ * so a caller that reads through a row object or a vector pays that cost once rather than once
+ * per comparison. A term that mixes types cannot be unboxed; it is read a second time into the
+ * generic column, whose comparison reports the type error the way it always has.
+ *
+ * Strings are always ranked, whatever their cardinality. Measured at 200k rows, ranking wins by
+ * ten times when six strings repeat and still by three times when nearly every string is
+ * distinct: the distinct set sorts with the engine's own string sort, the rows then sort as
+ * numbers, and neither pays the per-comparison dispatch the generic path does.
  */
 export declare function buildSortKeyColumn(count: number, valueAt: (index: number) => unknown): SortKeyColumn;
+/**
+ * A stable sort of `count` rows by the given terms, returned as the permutation of row indexes
+ * in sorted order. Equal rows keep their input order, which is what makes ORDER BY
+ * deterministic and what lets a bounded top-N decide ties by arrival.
+ *
+ * Each term is sorted in turn: the first over every row, then each later term only within the
+ * runs of rows the earlier terms left tied. A term with unboxed keys is encoded once into
+ * 64-bit integers whose unsigned order is the term's order — direction and NULL placement
+ * folded in — and large ranges are radix-sorted on those bits while small ones merge. A term
+ * without unboxed keys merges under the generic comparison. Both kernels check for input that
+ * is already in order before doing anything else, since a scan often arrives sorted.
+ */
+export declare function sortKeyIndexes(count: number, terms: readonly SortKeyTerm[]): Uint32Array;
 //# sourceMappingURL=sort-keys.d.ts.map

package/dist/engine/sort-keys.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sort-keys.d.ts","sourceRoot":"","sources":["../../src/engine/sort-keys.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;CAC7C;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAClC,aAAa,CA0Cf"}
+{"version":3,"file":"sort-keys.d.ts","sourceRoot":"","sources":["../../src/engine/sort-keys.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1D,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,CAAC;CACxC;AAED,8FAA8F;AAC9F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9C;AAED,8FAA8F;AAC9F,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAClC,aAAa,CA4Df;AAqBD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,WAAW,EAAE,GAAG,WAAW,CAQxF"}