@minnowdb/core 0.2.1 → 0.3.0

package/dist/storage/types.js

@@ -25,6 +25,29 @@ export function applyManifestRecord(blockIds, record) {
         blockIds.add(id);
 }
 export const simpleDataTypes = ["boolean", "number", "string", "datetime"];
+/** Validates the logical metadata shared by SQL DDL, the schema DSL, and restored catalogs. */
+export function validateSqlDomain(domain, context) {
+    if (domain.kind === "numeric") {
+        const { precision, scale } = domain;
+        if ((precision !== undefined &&
+            (!Number.isSafeInteger(precision) || precision < 1 || precision > 100_000)) ||
+            (scale !== undefined && (!Number.isSafeInteger(scale) || scale < 0 || scale > 100_000)) ||
+            (precision !== undefined && scale !== undefined && scale > precision)) {
+            throw new TypeError(`Invalid NUMERIC domain metadata: ${context}`);
+        }
+    }
+    if (domain.kind === "array" &&
+        (domain.element.trim().length === 0 || domain.element.trim() !== domain.element)) {
+        throw new TypeError(`ARRAY element type must be a trimmed non-empty name: ${context}`);
+    }
+    if (domain.kind === "enum") {
+        if (domain.name.trim().length === 0 || domain.name.trim() !== domain.name) {
+            throw new TypeError(`Enum type name must be a trimmed non-empty name: ${context}`);
+        }
+        validateEnumValues(domain.values, domain.name);
+    }
+    return structuredClone(domain);
+}
 /**
  * The single authority on which enum declarations are legal, shared by the schema DSL's
  * `column.enum()` and the engine's `createTable`: at least one value, every value a non-empty
@@ -46,22 +69,45 @@ export function validateEnumValues(values, context) {
     }
     return [...values];
 }
+/**
+ * Validates the catalog invariants owned by a table's column list. Storage adapters call this
+ * for ordinary catalog writes and before restoring snapshots or checkpoints, so malformed
+ * metadata cannot enter through a less common persistence path.
+ */
+export function validateTableColumns(columns) {
+    if (columns.length === 0)
+        throw new TypeError("A table needs at least one column");
+    for (const column of columns) {
+        const integer = column.integer;
+        if (integer !== undefined && (integer !== true || column.type !== "number")) {
+            throw new TypeError(`Integer domain requires a number column: ${column.name}`);
+        }
+        if (column.sqlDomain !== undefined && column.type !== "string") {
+            throw new TypeError(`SQL domain columns must use string storage: ${column.name}`);
+        }
+        if (column.sqlDomain !== undefined)
+            validateSqlDomain(column.sqlDomain, column.name);
+        if (column.integer === true && column.sqlDomain !== undefined) {
+            throw new TypeError(`A column cannot have both integer and SQL-domain metadata: ${column.name}`);
+        }
+        if (column.enumValues !== undefined && column.sqlDomain !== undefined) {
+            throw new TypeError(`A column cannot have both enum restrictions and a SQL domain: ${column.name}`);
+        }
+    }
+    const ids = new Set(columns.map(({ id }) => id));
+    const names = new Set(columns.map(({ name }) => name));
+    if (ids.size !== columns.length || names.size !== columns.length) {
+        throw new TypeError("Table columns must have unique IDs and names");
+    }
+}
 /**
  * The single authority on which default declarations are legal, shared by the schema DSL's
  * `table()` and the engine's `createTable` so the two entry points (and the wire path between
- * them) can never drift: defaults require non-nullable columns, "now" is datetime-only,
- * auto-increment is the number unique key, and the unique key never defaults to a constant.
+ * them) can never drift. Storage owns structural and literal validation; the engine additionally
+ * parses and type-checks SQL expressions before catalog mutation.
  */
 export function validateColumnDefault(column, defaultValue) {
-    if (column.nullable) {
-        throw new TypeError(`Defaults require a non-nullable column: ${column.name}`);
-    }
     switch (defaultValue.kind) {
-        case "now":
-            if (column.type !== "datetime") {
-                throw new TypeError(`Default now requires a datetime column: ${column.name}`);
-            }
-            return;
         case "autoincrement":
             if (column.type !== "number") {
                 throw new TypeError(`Auto-increment requires a number column: ${column.name}`);
@@ -70,32 +116,110 @@ export function validateColumnDefault(column, defaultValue) {
                 throw new TypeError(`Auto-increment requires the unique key column: ${column.name}`);
             }
             return;
+        case "expression":
+            if (typeof defaultValue.sql !== "string" ||
+                defaultValue.sql.length === 0 ||
+                defaultValue.sql.trim() !== defaultValue.sql) {
+                throw new TypeError(`Default SQL must be a trimmed non-empty expression: ${column.name}`);
+            }
+            return;
         case "literal": {
             const value = defaultValue.value;
-            if (column.type === "datetime") {
-                throw new TypeError(`Datetime columns default with now, not a literal: ${column.name}`);
-            }
-            if (typeof value !== column.type) {
+            const numericDomain = column.sqlDomain?.kind === "numeric";
+            const correctType = column.type === "datetime"
+                ? value instanceof Date && Number.isFinite(value.getTime())
+                : numericDomain
+                    ? typeof value === "number" || typeof value === "string"
+                    : typeof value === column.type;
+            if (!correctType) {
                 throw new TypeError(`Default literal must be a ${column.type}: ${column.name}`);
             }
             if (typeof value === "number" && !Number.isFinite(value)) {
                 throw new TypeError(`Default literal must be finite: ${column.name}`);
             }
+            if (column.integer === true && !Number.isSafeInteger(value)) {
+                throw new TypeError(`Default literal must be a safe integer: ${column.name}`);
+            }
             if (column.enumValues !== undefined &&
                 typeof value === "string" &&
                 !column.enumValues.includes(value)) {
                 throw new TypeError(`Default must be one of the enum values: ${column.name}`);
             }
-            if (column.isUniqueKey) {
-                throw new TypeError(`Unique key cannot default to a constant: ${column.name}`);
+            if (column.sqlDomain?.kind === "enum" &&
+                typeof value === "string" &&
+                !column.sqlDomain.values.includes(value)) {
+                throw new TypeError(`Default must be one of the enum values: ${column.name}`);
             }
             return;
         }
-        // The wire path can hand this untyped data (including specs from removed generator kinds).
+        // Storage restoration and untyped wire callers can still supply malformed catalog data.
         default:
             throw new TypeError(`Unknown default kind: ${String(defaultValue.kind)}`);
     }
 }
+/** Validates the durable identities and ownership rules of one table's secondary indexes. */
+export function validateSecondaryIndexes(record) {
+    const columnIds = new Set(record.columns.map((column) => column.id));
+    const names = new Set();
+    const storageIds = new Set(Object.keys(record.ftsColumns ?? {}));
+    for (const [indexId, index] of Object.entries(record.secondaryIndexes ?? {})) {
+        if (indexId.length === 0 || index.name.length === 0 || index.storageColumnId.length === 0) {
+            throw new TypeError("Secondary-index IDs and names must be non-empty");
+        }
+        const indexedColumnIds = index.columnIds ?? [index.columnId];
+        if (indexedColumnIds.length === 0 ||
+            indexedColumnIds[0] !== index.columnId ||
+            new Set(indexedColumnIds).size !== indexedColumnIds.length ||
+            indexedColumnIds.some((columnId) => !columnIds.has(columnId))) {
+            throw new TypeError(`Secondary index ${index.name} references an unknown column`);
+        }
+        const directions = index.directions ?? indexedColumnIds.map(() => "asc");
+        const termEncoding = index.termEncoding;
+        if (directions.length !== indexedColumnIds.length ||
+            directions.some((direction) => direction !== "asc" && direction !== "desc") ||
+            (termEncoding !== undefined && termEncoding !== "tuple-v1") ||
+            (termEncoding !== "tuple-v1" &&
+                (indexedColumnIds.length > 1 ||
+                    directions.some((direction) => direction !== "asc") ||
+                    index.unique === true))) {
+            throw new TypeError(`Secondary index ${index.name} has invalid key metadata`);
+        }
+        if (index.uniqueEnforced === true && index.unique !== true) {
+            throw new TypeError(`Secondary index ${index.name} enforces uniqueness without UNIQUE`);
+        }
+        if (names.has(index.name))
+            throw new TypeError(`Index already exists: ${index.name}`);
+        names.add(index.name);
+        if (storageIds.has(index.storageColumnId)) {
+            throw new TypeError(`Secondary-index storage ID is already used: ${index.storageColumnId}`);
+        }
+        storageIds.add(index.storageColumnId);
+        const expectedLocator = record.uniqueKeyColumnId === undefined ? "row-id" : "key-hash-v1";
+        const storage = index.storage;
+        if (storage !== "postings-v1" || index.locator !== expectedLocator) {
+            throw new TypeError(`Secondary index ${index.name} has incompatible storage metadata`);
+        }
+        const state = index.state;
+        if ((state !== "building" && state !== "ready" && state !== "invalid") ||
+            !Number.isSafeInteger(index.buildFromVersion) ||
+            index.buildFromVersion < -1 ||
+            (index.state === "building") !== (index.buildId !== undefined)) {
+            throw new TypeError(`Secondary index ${index.name} has invalid build metadata`);
+        }
+    }
+}
+/** Ordered catalog column IDs for legacy and current secondary-index records. */
+export function secondaryIndexColumnIds(index) {
+    return index.columnIds ?? [index.columnId];
+}
+/** Declared directions for legacy and current secondary-index records. */
+export function secondaryIndexDirections(index) {
+    return index.directions ?? secondaryIndexColumnIds(index).map(() => "asc");
+}
+/** Unique-membership namespace owned by one physical secondary index. */
+export function secondaryUniqueKeyNamespace(tableId, indexId) {
+    return `${tableId}\u0000secondary-index\u0000${indexId}`;
+}
 export class TableRecordConflictError extends Error {
     tableId;
     expectedRevision;
@@ -163,6 +287,20 @@ export class LeaseConflictError extends Error {
         this.actualRevision = actualRevision;
     }
 }
+/** Whether a stored term belongs to one exact, prefix, or range lookup. */
+export function ftsPostingQueryMatches(term, query) {
+    if ("term" in query)
+        return query.prefix ? term.startsWith(query.term) : term === query.term;
+    if (query.lower !== undefined) {
+        if (term < query.lower || (term === query.lower && query.lowerInclusive === false))
+            return false;
+    }
+    if (query.upper !== undefined) {
+        if (term > query.upper || (term === query.upper && query.upperInclusive === false))
+            return false;
+    }
+    return true;
+}
 /**
  * Shared candidate-merge core for both stores: fetching chunks is store-specific, but the
  * term-match rule (exact, or prefix as a term range) and the sorted-unique row-id shape must
@@ -176,9 +314,7 @@ export function collectFtsCandidates(chunkLists, terms) {
                 const term = terms[index];
                 if (term === undefined)
                     continue;
-                const matches = term.prefix
-                    ? posting.term.startsWith(term.term)
-                    : posting.term === term.term;
+                const matches = ftsPostingQueryMatches(posting.term, term);
                 if (!matches)
                     continue;
                 const set = sets[index];
@@ -192,6 +328,97 @@ export function collectFtsCandidates(chunkLists, terms) {
         rowIdsByTerm: sets.map((set) => [...set].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0))),
     };
 }
+/**
+ * K-way merges sorted base/delta chunks into canonical term order. Only one term's row map and
+ * one cursor per chunk stay live beyond the returned postings, avoiding a second index-sized map.
+ */
+export function collectFtsPostings(chunkLists) {
+    const heap = [];
+    const before = (left, right) => {
+        const leftTerm = left.postings[left.position]?.term ?? "";
+        const rightTerm = right.postings[right.position]?.term ?? "";
+        return leftTerm < rightTerm || (leftTerm === rightTerm && left.ordinal < right.ordinal);
+    };
+    const cursorAt = (position) => {
+        const cursor = heap[position];
+        if (cursor === undefined)
+            throw new Error("Posting merge heap is inconsistent");
+        return cursor;
+    };
+    const push = (cursor) => {
+        heap.push(cursor);
+        let child = heap.length - 1;
+        while (child > 0) {
+            const parent = (child - 1) >>> 1;
+            const childCursor = cursorAt(child);
+            const parentCursor = cursorAt(parent);
+            if (!before(childCursor, parentCursor))
+                break;
+            heap[parent] = childCursor;
+            heap[child] = parentCursor;
+            child = parent;
+        }
+    };
+    const pop = () => {
+        const first = heap[0];
+        const last = heap.pop();
+        if (first === undefined || last === undefined)
+            return first;
+        if (heap.length === 0)
+            return first;
+        heap[0] = last;
+        let parent = 0;
+        for (;;) {
+            const left = parent * 2 + 1;
+            if (left >= heap.length)
+                break;
+            const right = left + 1;
+            const child = right < heap.length && before(cursorAt(right), cursorAt(left)) ? right : left;
+            const childCursor = cursorAt(child);
+            const parentCursor = cursorAt(parent);
+            if (!before(childCursor, parentCursor))
+                break;
+            heap[parent] = childCursor;
+            heap[child] = parentCursor;
+            parent = child;
+        }
+        return first;
+    };
+    let ordinal = 0;
+    for (const postings of chunkLists) {
+        if (postings.length > 0)
+            push({ postings, position: 0, ordinal });
+        ordinal += 1;
+    }
+    const output = [];
+    while (heap.length > 0) {
+        const term = heap[0]?.postings[heap[0].position]?.term;
+        if (term === undefined)
+            break;
+        const rows = new Map();
+        while (heap[0]?.postings[heap[0].position]?.term === term) {
+            const cursor = pop();
+            if (cursor === undefined)
+                break;
+            const posting = cursor.postings[cursor.position];
+            if (posting === undefined)
+                continue;
+            posting.rowIds.forEach((rowId, index) => {
+                rows.set(rowId, Math.max(rows.get(rowId) ?? 0, posting.tf[index] ?? 1));
+            });
+            cursor.position += 1;
+            if (cursor.position < cursor.postings.length)
+                push(cursor);
+        }
+        const ordered = [...rows].sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        output.push({
+            term,
+            rowIds: ordered.map(([rowId]) => rowId),
+            tf: ordered.map(([, frequency]) => frequency),
+        });
+    }
+    return output;
+}
 /**
  * Shared stale-writer policy for both stores' commit steps: a commit that adds segments to a
  * table with active full-text columns but no covering delta flips the uncovered columns to
@@ -217,6 +444,39 @@ export function invalidateUncoveredFtsColumns(record, coveredColumnIds) {
         return undefined;
     return { ...record, ftsColumns: next, revision: (record.revision ?? 0) + 1 };
 }
+/**
+ * Scalar-index half of the stale-writer rule. A writer that staged table data from catalog
+ * metadata older than a newly building/ready index cannot provide its postings, so the commit
+ * invalidates that index atomically. Readers then scan until a rebuild closes the gap.
+ */
+export function invalidateUncoveredSecondaryIndexes(record, coveredStorageColumnIds) {
+    const indexes = record.secondaryIndexes;
+    if (indexes === undefined)
+        return undefined;
+    let invalidated = false;
+    const next = {};
+    for (const [indexId, index] of Object.entries(indexes)) {
+        if (index.state !== "invalid" && !coveredStorageColumnIds.has(index.storageColumnId)) {
+            const { buildId: _abandonedBuild, ...invalid } = index;
+            void _abandonedBuild;
+            next[indexId] = { ...invalid, state: "invalid" };
+            invalidated = true;
+        }
+        else {
+            next[indexId] = { ...index };
+        }
+    }
+    if (!invalidated)
+        return undefined;
+    return { ...record, secondaryIndexes: next, revision: (record.revision ?? 0) + 1 };
+}
+/** Physical posting IDs a current catalog record authorizes a commit to write. */
+export function activePostingStorageColumnIds(record) {
+    return new Set([
+        ...Object.entries(record.ftsColumns ?? {}).flatMap(([columnId, index]) => index.state === "invalid" ? [] : [columnId]),
+        ...Object.values(record.secondaryIndexes ?? {}).flatMap((index) => index.state === "invalid" ? [] : [index.storageColumnId]),
+    ]);
+}
 export class UniqueKeyConflictError extends Error {
     tableId;
     keyToken;
@@ -227,6 +487,17 @@ export class UniqueKeyConflictError extends Error {
         this.keyToken = keyToken;
     }
 }
+/** A writer prepared before an enforced UNIQUE index existed and therefore cannot enforce it. */
+export class UniqueIndexCoverageError extends Error {
+    tableId;
+    indexName;
+    name = "UniqueIndexCoverageError";
+    constructor(tableId, indexName) {
+        super(`Write did not cover enforced UNIQUE index ${indexName} on table ${tableId}`);
+        this.tableId = tableId;
+        this.indexName = indexName;
+    }
+}
 export class WriteConflictError extends Error {
     expectedVersion;
     actualVersion;