@minnowdb/core 0.3.0 → 0.4.0

package/dist/engine/defaults.d.ts

@@ -27,4 +27,3 @@ export declare function fillColumnDefaults(table: TableRecord, input: ColumnarBa
  * `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.js

@@ -3,6 +3,7 @@
  * explicit NULL passes through untouched. Literal and SQL-expression defaults are filled before
  * validation. Auto-increment slots stay null until the write path atomically reserves a range.
  */
+import { copyDate } from "../date-value.js";
 export async function fillColumnDefaults(table, input, evaluateExpression, knownRowCount) {
     const rowCount = knownRowCount ?? Object.values(input.columns).find((values) => values.length > 0)?.length ?? 0;
     if (!Number.isSafeInteger(rowCount) || rowCount < 0) {
@@ -76,9 +77,7 @@ export async function fillColumnDefaults(table, input, evaluateExpression, known
             switch (defaultValue.kind) {
                 case "literal":
                     values[index] =
-                        defaultValue.value instanceof Date
-                            ? new Date(defaultValue.value.getTime())
-                            : defaultValue.value;
+                        defaultValue.value instanceof Date ? copyDate(defaultValue.value) : defaultValue.value;
                     break;
                 case "expression":
                     values[index] = await evaluateExpression(defaultValue.sql, index);
@@ -110,4 +109,3 @@ export function patchAutoIncrementValues(input, fill, range) {
         vector[rowIndex] = Number(value);
     });
 }
-//# sourceMappingURL=defaults.js.map

package/dist/engine/errors.d.ts

@@ -34,6 +34,25 @@ export declare class CompactionJobCancelledError extends Error {
     readonly name = "CompactionJobCancelledError";
     constructor(jobId: string);
 }
+/** Refuses more growth after automatic collection repeatedly fails at a generous debt limit. */
+export declare class MaintenanceBacklogError extends Error {
+    readonly pendingCommits: number;
+    readonly causeMessage: string | null;
+    readonly name = "MaintenanceBacklogError";
+    constructor(pendingCommits: number, causeMessage: string | null);
+}
+/**
+ * A paged visible-segment scan cannot continue after its table is dropped or replaced. Segment
+ * metadata for a dropped table is removed immediately, so returning an empty or partial page
+ * would silently misrepresent the captured scan.
+ */
+export declare class VisibleSegmentCursorStaleError extends Error {
+    readonly tableName: string;
+    readonly capturedTableId: string;
+    readonly currentTableId: string | null;
+    readonly name = "VisibleSegmentCursorStaleError";
+    constructor(tableName: string, capturedTableId: string, currentTableId: string | null);
+}
 /**
  * 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
@@ -52,4 +71,3 @@ export declare class SqlCompileError extends TypeError {
     constructor(message: string, offset: number, length: number);
 }
 export {};
-//# sourceMappingURL=errors.d.ts.map

package/dist/engine/errors.js

@@ -3,7 +3,7 @@
  * them (name, fields, instanceof) without bundling the executor.
  */
 function formatValue(value) {
-    return value instanceof Date ? value.toISOString() : String(value);
+    return value instanceof Date ? dateIsoString(value) : String(value);
 }
 export class UniqueConstraintError extends Error {
     tableName;
@@ -57,6 +57,36 @@ export class CompactionJobCancelledError extends Error {
         this.jobId = jobId;
     }
 }
+/** Refuses more growth after automatic collection repeatedly fails at a generous debt limit. */
+export class MaintenanceBacklogError extends Error {
+    pendingCommits;
+    causeMessage;
+    name = "MaintenanceBacklogError";
+    constructor(pendingCommits, causeMessage) {
+        super(`Automatic storage collection could not keep up after ${String(pendingCommits)} commits${causeMessage === null ? "" : `: ${causeMessage}`}`);
+        this.pendingCommits = pendingCommits;
+        this.causeMessage = causeMessage;
+    }
+}
+/**
+ * A paged visible-segment scan cannot continue after its table is dropped or replaced. Segment
+ * metadata for a dropped table is removed immediately, so returning an empty or partial page
+ * would silently misrepresent the captured scan.
+ */
+export class VisibleSegmentCursorStaleError extends Error {
+    tableName;
+    capturedTableId;
+    currentTableId;
+    name = "VisibleSegmentCursorStaleError";
+    constructor(tableName, capturedTableId, currentTableId) {
+        super(`Visible segment cursor for ${tableName} is stale: captured table ${capturedTableId}; ${currentTableId === null
+            ? "the table no longer exists"
+            : `current table is ${currentTableId}`}`);
+        this.tableName = tableName;
+        this.capturedTableId = capturedTableId;
+        this.currentTableId = currentTableId;
+    }
+}
 /**
  * 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
@@ -78,4 +108,4 @@ export class SqlCompileError extends TypeError {
         this.length = length;
     }
 }
-//# sourceMappingURL=errors.js.map
+import { dateIsoString } from "../date-value.js";

package/dist/engine/fts.d.ts

@@ -41,11 +41,6 @@ export declare function tokenize(text: string): string[];
  */
 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. */
@@ -90,4 +85,3 @@ export declare class FtsStatsAccumulator {
 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.js

@@ -11,19 +11,22 @@
  * 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.
  */
+import { assertWellFormedString } from "../block-format/unicode.js";
+import { MAX_CACHEABLE_TEXT_CHARACTERS, MAX_SQL_PATTERN_CHARACTERS } from "./cache-limits.js";
 import { externalSqlDomainValue } from "./sql-domains.js";
+import { MAX_FTS_QUERY_TERMS, MAX_FTS_TOKENS_PER_DOCUMENT, MAX_INDEXED_STRING_CHARACTERS, } from "../storage/types.js";
 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;
+const QUERY_WHITESPACE = /\s/u;
 // 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)
+    if (tokens.length >= MAX_FTS_TOKENS_PER_DOCUMENT)
         return;
     tokens.push(token.length > MAX_TOKEN_LENGTH ? token.slice(0, MAX_TOKEN_LENGTH) : token);
 }
@@ -59,11 +62,15 @@ function emitRun(tokens, run) {
 }
 /** Tokenizes one cell's text: NFKC, locale-independent lowercase, letter/number runs. */
 export function tokenize(text) {
+    if (text.length > MAX_INDEXED_STRING_CHARACTERS) {
+        throw new RangeError(`Full-text values cannot exceed ${String(MAX_INDEXED_STRING_CHARACTERS)} characters`);
+    }
+    assertWellFormedString(text, "Full-text value");
     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)
+        if (tokens.length >= MAX_FTS_TOKENS_PER_DOCUMENT)
             break;
     }
     return tokens;
@@ -74,15 +81,32 @@ export function tokenize(text) {
  * query matches nothing.
  */
 export function tokenizeQuery(query) {
+    if (query.length > MAX_SQL_PATTERN_CHARACTERS) {
+        throw new RangeError(`Full-text queries cannot exceed ${String(MAX_SQL_PATTERN_CHARACTERS)} characters`);
+    }
+    assertWellFormedString(query, "Full-text query");
     const terms = [];
-    for (const chunk of query.split(/\s+/)) {
-        if (chunk.length === 0)
+    let cursor = 0;
+    while (cursor < query.length) {
+        while (cursor < query.length && QUERY_WHITESPACE.test(query[cursor] ?? ""))
+            cursor += 1;
+        const start = cursor;
+        while (cursor < query.length && !QUERY_WHITESPACE.test(query[cursor] ?? ""))
+            cursor += 1;
+        if (cursor === start)
             continue;
-        const prefix = chunk.endsWith("*");
-        const tokens = tokenize(prefix ? chunk.slice(0, -1) : chunk);
-        tokens.forEach((term, index) => {
+        const prefix = query[cursor - 1] === "*";
+        const tokens = tokenize(query.slice(start, prefix ? cursor - 1 : cursor));
+        for (let index = 0; index < tokens.length; index += 1) {
+            const term = tokens[index];
+            if (term === undefined)
+                continue;
             terms.push({ term, prefix: prefix && index === tokens.length - 1 });
-        });
+            // Every caller rejects above 32. Stop before adversarial whitespace can allocate a terms
+            // array proportional to the input; the 33rd item is all validation needs to see.
+            if (terms.length > MAX_FTS_QUERY_TERMS)
+                return terms;
+        }
     }
     return terms;
 }
@@ -93,7 +117,6 @@ export function termMatches(token, 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) {
@@ -101,6 +124,8 @@ export function cachedQueryTerms(query) {
     if (cached !== undefined)
         return cached;
     const terms = tokenizeQuery(query);
+    if (query.length > MAX_CACHEABLE_TEXT_CHARACTERS)
+        return terms;
     if (queryTermsCache.size >= 128)
         queryTermsCache.clear();
     queryTermsCache.set(query, terms);
@@ -108,8 +133,8 @@ export function cachedQueryTerms(query) {
 }
 /** 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`);
+    if (cachedQueryTerms(query).length > MAX_FTS_QUERY_TERMS) {
+        throw new TypeError(`Full-text queries support at most ${String(MAX_FTS_QUERY_TERMS)} terms`);
     }
 }
 /** Bitmask of query terms present in a token list: bit i set means terms[i] matched. */
@@ -267,9 +292,9 @@ export function renderDocumentValue(value) {
     if (value === null || value === undefined || typeof value === "boolean")
         return undefined;
     if (value instanceof Date)
-        return value.toISOString();
+        return dateIsoString(value);
     if (typeof value === "number")
         return String(value);
     return typeof value === "string" ? value : undefined;
 }
-//# sourceMappingURL=fts.js.map
+import { dateIsoString } from "../date-value.js";

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

@@ -29,4 +29,3 @@ export declare function hashScratch(length: number): number;
 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.js

@@ -4,7 +4,6 @@ const INITIAL_KEY_CAPACITY = 32;
 const INDEX_FIELDS = 4;
 const UINT32_BYTES = Uint32Array.BYTES_PER_ELEMENT;
 const INITIAL_SCRATCH_CAPACITY = 64;
-const REPLACEMENT_CHARACTER_BYTES = [0xef, 0xbf, 0xbd];
 // Every probe encodes its key into this shared scratch arena instead of allocating a fresh buffer
 // per row. Encoding is synchronous and the bytes are consumed before the next probe begins, so a
 // single arena serves every index; the miss path copies out of it before any caller code runs.
@@ -255,8 +254,9 @@ function writeGroupKey(key, offset) {
         scratchView.setFloat64(offset + 1, key === 0 ? 0 : key, true);
         return offset + 1 + Float64Array.BYTES_PER_ELEMENT;
     }
-    // A UTF-16 code unit never expands past three UTF-8 bytes, and a surrogate pair yields four
-    // across two units, so reserving three bytes per unit lets the encode loop skip bounds checks.
+    // A code unit never expands past three UTF-8 bytes. Reserving the one conservative bound keeps
+    // this query hot path single-pass and branch-light; oversized scratch is reclaimed before the
+    // next key operation.
     const bound = safeSum(offset + 5, safeProduct(key.length, 3, "Encoded group key"), "Encoded group key");
     if (bound > 0xffff_ffff)
         throw new RangeError("Encoded group key is too large");
@@ -268,8 +268,8 @@ function writeGroupKey(key, offset) {
     return payloadEnd;
 }
 /**
- * Encodes `value` as UTF-8 at `offset`, which the caller has already sized. Unpaired surrogates
- * become U+FFFD, matching `TextEncoder` so two distinct strings never collapse to one key.
+ * Encodes `value` as UTF-8 in one pass. Isolated surrogates fail before the encoded bytes can
+ * participate in a lookup or insertion.
  */
 function writeUtf8(value, offset) {
     let write = offset;
@@ -300,11 +300,7 @@ function writeUtf8(value, offset) {
             }
         }
         if (code >= 0xd800 && code <= 0xdfff) {
-            scratch[write] = REPLACEMENT_CHARACTER_BYTES[0];
-            scratch[write + 1] = REPLACEMENT_CHARACTER_BYTES[1];
-            scratch[write + 2] = REPLACEMENT_CHARACTER_BYTES[2];
-            write += 3;
-            continue;
+            throw new TypeError(`String value contains an unpaired surrogate at UTF-16 index ${String(index)}`);
         }
         scratch[write] = 0xe0 | (code >>> 12);
         scratch[write + 1] = 0x80 | ((code >>> 6) & 0x3f);
@@ -363,4 +359,3 @@ function safeSum(left, right, label) {
         throw new RangeError(`${label} exceeds the safe integer range`);
     return sum;
 }
-//# sourceMappingURL=group-index.js.map

package/dist/engine/index.d.ts

@@ -1,14 +1,19 @@
+/**
+ * The everyday in-thread API. Larger optional surfaces have their own entry points so exporting
+ * one helper cannot make an application download the worker client or typed live-query layer.
+ */
 export * from "./catalog.js";
-export * from "./client.js";
-export * from "./coordinator.js";
 export * from "./database.js";
-export * from "./schema-wire.js";
-export * from "./worker-host.js";
-export { bindPlanParameters, bindStatementParameters, compileQuery, compileStatement, executeQuery, referencedColumns, type InsertValue, type CompiledQuery, type CompiledStatement, type QueryResult, type QueryRow, type QueryExecutionOptions, type QueryValue, type SqlColumnSchema, type SqlColumnType, } from "./query.js";
+export * from "./errors.js";
 export { QueryMemoryBudgetError, type QueryMemoryUsage } from "./memory.js";
-export { optimizePlan, renderPlan } from "./optimizer.js";
-export * from "./schema.js";
-export * from "./live.js";
-export * from "./sql-driver.js";
-export type { AsyncQueryExecutionOptions, QuerySpillStore } from "./vector.js";
-//# sourceMappingURL=index.d.ts.map
+export { MAX_SQL_NESTING_DEPTH, MAX_SQL_NUMERIC_DIGITS, MAX_SQL_PARAMETERS, MAX_SQL_PATTERN_CHARACTERS, MAX_SQL_PATTERN_MATCH_STEPS, MAX_SQL_SCALAR_RESULT_CHARACTERS, MAX_SQL_STRUCTURED_VALUE_DEPTH, MAX_SQL_STRUCTURED_VALUE_ITEMS, MAX_SQL_TEXT_CHARACTERS, MAX_SQL_TOKENS, } from "./cache-limits.js";
+/**
+ * The core schema declarations stay on the everyday entry. The optional typed-table renderer is
+ * available from `@minnowdb/core/schema`, so applications that execute SQL directly do not ship
+ * its statement builder. Advanced schema internals remain available from that same subpath.
+ */
+export { column, foreignKeyName, isDestructiveStep, planMigration, schema, table, view, } from "./schema.js";
+export type * from "./schema.js";
+export type { InsertValue, CompiledQuery, CompiledStatement, QueryResult, QueryRow, QueryExecutionOptions, QueryValue, SqlColumnSchema, SqlColumnType, } from "./query.js";
+export type { AsyncQueryExecutionOptions, QueryBatchExecutionOptions, QuerySpillStore, } from "./vector.js";
+export type { MinnowSqlDriver, MinnowSqlExecutor } from "./sql-driver.js";

package/dist/engine/index.js

@@ -1,13 +1,15 @@
+/**
+ * The everyday in-thread API. Larger optional surfaces have their own entry points so exporting
+ * one helper cannot make an application download the worker client or typed live-query layer.
+ */
 export * from "./catalog.js";
-export * from "./client.js";
-export * from "./coordinator.js";
 export * from "./database.js";
-export * from "./schema-wire.js";
-export * from "./worker-host.js";
-export { bindPlanParameters, bindStatementParameters, compileQuery, compileStatement, executeQuery, referencedColumns, } from "./query.js";
+export * from "./errors.js";
 export { QueryMemoryBudgetError } from "./memory.js";
-export { optimizePlan, renderPlan } from "./optimizer.js";
-export * from "./schema.js";
-export * from "./live.js";
-export * from "./sql-driver.js";
-//# sourceMappingURL=index.js.map
+export { MAX_SQL_NESTING_DEPTH, MAX_SQL_NUMERIC_DIGITS, MAX_SQL_PARAMETERS, MAX_SQL_PATTERN_CHARACTERS, MAX_SQL_PATTERN_MATCH_STEPS, MAX_SQL_SCALAR_RESULT_CHARACTERS, MAX_SQL_STRUCTURED_VALUE_DEPTH, MAX_SQL_STRUCTURED_VALUE_ITEMS, MAX_SQL_TEXT_CHARACTERS, MAX_SQL_TOKENS, } from "./cache-limits.js";
+/**
+ * The core schema declarations stay on the everyday entry. The optional typed-table renderer is
+ * available from `@minnowdb/core/schema`, so applications that execute SQL directly do not ship
+ * its statement builder. Advanced schema internals remain available from that same subpath.
+ */
+export { column, foreignKeyName, isDestructiveStep, planMigration, schema, table, view, } from "./schema.js";

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

@@ -9,4 +9,3 @@ export declare class ByteJoinIndex {
     firstRow(value: unknown): number;
     nextRow(row: number): number;
 }
-//# sourceMappingURL=join-index.d.ts.map

package/dist/engine/join-index.js

@@ -1,3 +1,4 @@
+import { dateMilliseconds } from "../date-value.js";
 import { copyScratchKey, encodeSingleScalarKey, equalsScratch, hashScratch, } from "./group-index.js";
 const INITIAL_ENTRY_CAPACITY = 4;
 const INITIAL_BUCKET_CAPACITY = 8;
@@ -190,7 +191,7 @@ export class ByteJoinIndex {
  * so a Date and its number representation join as the same key.
  */
 function encodeJoinKey(value) {
-    const key = value instanceof Date ? value.getTime() : value;
+    const key = value instanceof Date ? dateMilliseconds(value) : value;
     if (key === null || key === undefined)
         return -1;
     if (typeof key === "number" && Number.isNaN(key))
@@ -214,4 +215,3 @@ function safeProduct(left, right, label) {
     }
     return product;
 }
-//# sourceMappingURL=join-index.js.map

package/dist/engine/keyed-live.d.ts

@@ -0,0 +1,57 @@
+import type { LiveQuery } from "./typed-live.js";
+export type LiveResultKey = string | number | boolean | Date;
+export type LiveKeyOf<TRow extends object> = {
+    [TKey in keyof TRow]-?: TRow[TKey] extends LiveResultKey ? TKey : never;
+}[keyof TRow];
+export type LiveResultChange<TRow extends object, TKey extends keyof TRow> = {
+    readonly type: "insert";
+    readonly row: TRow;
+    readonly index: number;
+} | {
+    readonly type: "update";
+    readonly row: TRow;
+    readonly previous: TRow;
+    readonly index: number;
+} | {
+    readonly type: "delete";
+    readonly key: TRow[TKey];
+    readonly previous: TRow;
+    readonly index: number;
+} | {
+    readonly type: "move";
+    readonly key: TRow[TKey];
+    readonly row: TRow;
+    readonly from: number;
+    readonly to: number;
+};
+export type LiveChangesSnapshot<TRow extends object, TKey extends keyof TRow> = {
+    readonly status: "loading";
+    readonly rows: readonly TRow[];
+} | {
+    readonly status: "ready";
+    readonly rows: readonly TRow[];
+    readonly changes: ReadonlyArray<LiveResultChange<TRow, TKey>>;
+    readonly initial: boolean;
+    readonly version: number | null;
+} | {
+    readonly status: "error";
+    readonly rows: readonly TRow[];
+    readonly error: unknown;
+    readonly version: number | null;
+};
+export interface KeyedLiveQueryOptions<TRow extends object, TKey extends LiveKeyOf<TRow>> {
+    readonly key: TKey;
+    /** A window refuses a result larger than this instead of retaining an accidentally unbounded query. */
+    readonly maxRows?: number;
+}
+/** Keyed exact diffs over a typed live query, with optional bounded-window enforcement. */
+export declare class KeyedLiveQuery<TRow extends object, TKey extends LiveKeyOf<TRow>> {
+    #private;
+    readonly $inferRow: TRow;
+    readonly $inferKey: TRow[TKey];
+    constructor(source: LiveQuery<TRow>, options: KeyedLiveQueryOptions<TRow, TKey>);
+    getSnapshot: () => LiveChangesSnapshot<TRow, TKey>;
+    subscribe: (listener: () => void) => (() => void);
+    refresh(): Promise<void>;
+    close(): void;
+}