@minnowdb/core 0.4.1 → 0.6.0

package/dist/engine/schema.js

@@ -1,7 +1,52 @@
 import { copyDate, dateMilliseconds } from "../date-value.js";
 import { validateColumnDefault, validateEnumValues, validateSqlDomain, } from "../storage/types.js";
-import { compileCheckExpression, expressionColumns, validateDefaultExpression, } from "./query.js";
+import { childExpressions, compileCheckExpression, expressionColumns, hasAggregate, validateDefaultExpression, } from "./query.js";
 import { externalSqlDomainValue, normalizeSqlDomainValue } from "./sql-domains.js";
+const volatileGeneratedFunctions = new Set([
+    "CURRENT_DATE",
+    "CURRENT_TIMESTAMP",
+    "LOCALTIME",
+    "RANDOM",
+    "GEN_RANDOM_UUID",
+    "NEXTVAL",
+    "CURRVAL",
+]);
+/** Compiles and validates one immutable, row-local generated-column expression. */
+export function compileGeneratedColumnExpression(tableName, columnName, sql, columns) {
+    if (sql.length === 0 || sql.trim() !== sql) {
+        throw new TypeError(`Generated SQL must be a trimmed non-empty expression: ${tableName}.${columnName}`);
+    }
+    const expression = compileCheckExpression(sql, `generated ${tableName}.${columnName}`);
+    if (hasAggregate(expression)) {
+        throw new TypeError(`Generated column ${tableName}.${columnName} must be an immutable expression over sibling columns`);
+    }
+    const inspect = (node) => {
+        if (node.kind === "subquery" || node.kind === "exists") {
+            throw new TypeError(`Generated column ${tableName}.${columnName} must be an immutable expression over sibling columns`);
+        }
+        if (node.kind === "call" && volatileGeneratedFunctions.has(node.name)) {
+            throw new TypeError(`Generated column ${tableName}.${columnName} cannot call volatile function ${node.name}`);
+        }
+        childExpressions(node).forEach(inspect);
+    };
+    inspect(expression);
+    for (const reference of expressionColumns(expression)) {
+        const pieces = reference.split(".");
+        const referencedName = pieces.at(-1) ?? reference;
+        const qualifier = pieces.length > 1 ? pieces.slice(0, -1).join(".") : undefined;
+        if (qualifier !== undefined && qualifier !== tableName) {
+            throw new TypeError(`Generated column ${tableName}.${columnName} references another table: ${reference}`);
+        }
+        const referenced = columns.find(({ name }) => name === referencedName);
+        if (referenced === undefined) {
+            throw new TypeError(`Generated column ${tableName}.${columnName} names an unknown column: ${referencedName}`);
+        }
+        if (referencedName === columnName || referenced.generatedValue !== undefined) {
+            throw new TypeError(`Generated column ${tableName}.${columnName} cannot reference a generated column: ${referencedName}`);
+        }
+    }
+    return expression;
+}
 /**
  * The constraint name `migrate()` gives a declared relation. It matches the name the SQL parser
  * derives for an unnamed inline REFERENCES, so a table built either way has the same catalog.
@@ -45,9 +90,11 @@ function createColumn(type, state = {}) {
         isNullable: (state.isNullable ?? false),
         isUnique: (state.isUnique ?? false),
         hasDefault: (state.defaultSpec !== undefined),
+        isGenerated: (state.generatedSpec !== undefined),
         integer: state.integer ?? false,
         ...(state.sqlDomain === undefined ? {} : { sqlDomain: state.sqlDomain }),
         ...(state.defaultSpec === undefined ? {} : { defaultSpec: state.defaultSpec }),
+        ...(state.generatedSpec === undefined ? {} : { generatedSpec: state.generatedSpec }),
         ...(state.renamedFromName === undefined ? {} : { renamedFromName: state.renamedFromName }),
         ...(state.reference === undefined ? {} : { reference: state.reference }),
         ...(state.enumValues === undefined ? {} : { enumValues: state.enumValues }),
@@ -65,18 +112,28 @@ function createColumn(type, state = {}) {
         }),
         renamedFrom: (name) => {
             validateSchemaName(name, "Rename source");
-            return createColumn(type, { ...state, renamedFromName: name });
+            return createColumn(type, {
+                ...state,
+                renamedFromName: name,
+            });
         },
-        backfill: (value) => createColumn(type, { ...state, backfillValue: value }),
+        backfill: (value) => createColumn(type, {
+            ...state,
+            backfillValue: value,
+        }),
         references: (table, referencedColumn, options = {}) => {
             validateSchemaName(table, "Referenced table");
             validateSchemaName(referencedColumn, "Referenced column");
+            if (options.enforced === false && options.onDelete !== undefined) {
+                throw new TypeError("An informational FOREIGN KEY cannot declare ON DELETE behavior");
+            }
             return createColumn(type, {
                 ...state,
                 reference: {
                     table,
                     column: referencedColumn,
                     onDelete: options.onDelete ?? "restrict",
+                    enforced: options.enforced !== false,
                 },
             });
         },
@@ -96,6 +153,19 @@ function createColumn(type, state = {}) {
                 defaultSpec: { kind: "expression", sql: expression },
             });
         }),
+        generatedSql: (sql) => {
+            const expression = sql.trim();
+            if (expression.length === 0 || expression !== sql) {
+                throw new TypeError("Generated SQL must be a trimmed non-empty expression");
+            }
+            if (state.defaultSpec !== undefined) {
+                throw new TypeError("A generated column cannot also have a default");
+            }
+            return createColumn(type, {
+                ...state,
+                generatedSpec: { kind: "stored", sql: expression },
+            });
+        },
         autoIncrement: (() => {
             if (type !== "number") {
                 throw new TypeError("Auto-increment requires a number column");
@@ -141,6 +211,7 @@ export function columnFromState(state) {
         ...(state.renamedFromName === undefined ? {} : { renamedFromName: state.renamedFromName }),
         ...(state.reference === undefined ? {} : { reference: state.reference }),
         ...(state.defaultSpec === undefined ? {} : { defaultSpec: state.defaultSpec }),
+        ...(state.generatedSpec === undefined ? {} : { generatedSpec: state.generatedSpec }),
         ...(state.enumValues === undefined ? {} : { enumValues: state.enumValues }),
         ...(state.backfillValue === undefined ? {} : { backfillValue: state.backfillValue }),
     });
@@ -160,8 +231,12 @@ export const column = {
     json: () => createColumn("string", { sqlDomain: { kind: "json" } }),
     jsonb: () => createColumn("string", { sqlDomain: { kind: "jsonb" } }),
     uuid: () => createColumn("string", { sqlDomain: { kind: "uuid" } }),
+    /** A zoneless calendar date, represented publicly as canonical `YYYY-MM-DD` text. */
+    date: () => createColumn("string", { sqlDomain: { kind: "date" } }),
     time: () => createColumn("string", { sqlDomain: { kind: "time" } }),
-    interval: () => createColumn("string", { sqlDomain: { kind: "interval" } }),
+    interval: () => createColumn("string", {
+        sqlDomain: { kind: "interval" },
+    }),
     /** JSON array text at the JavaScript boundary, with the SQL element type retained in metadata. */
     array: (element) => createColumn("string", {
         sqlDomain: validateSqlDomain({ kind: "array", element }, "array column"),
@@ -246,6 +321,10 @@ export function table(name, columns, options = {}) {
     if (uniqueEntry?.[1].isNullable === true) {
         throw new TypeError(`Table ${name} unique column must not be nullable: ${uniqueEntry[0]}`);
     }
+    const generatedColumns = entries.map(([columnName, definition]) => ({
+        name: columnName,
+        ...(definition.generatedSpec === undefined ? {} : { generatedValue: definition.generatedSpec }),
+    }));
     for (const [columnName, definition] of entries) {
         validateSchemaName(columnName, "Column");
         if (definition.integer && definition.type !== "number") {
@@ -270,6 +349,15 @@ export function table(name, columns, options = {}) {
         if (backfill !== undefined && definition.isNullable) {
             throw new TypeError(`A nullable column needs no backfill: ${name}.${columnName}. Rows without it already read NULL.`);
         }
+        if (definition.generatedSpec !== undefined) {
+            if (definition.defaultSpec !== undefined || backfill !== undefined) {
+                throw new TypeError(`A generated column cannot also have a default or backfill: ${name}.${columnName}`);
+            }
+            compileGeneratedColumnExpression(name, columnName, definition.generatedSpec.sql, generatedColumns);
+            if (definition.isUnique || primaryKey.includes(columnName)) {
+                throw new TypeError(`Generated columns cannot be row-addressing keys: ${name}.${columnName}`);
+            }
+        }
         if (definition.reference?.onDelete === "set null" && !definition.isNullable) {
             throw new TypeError(`ON DELETE SET NULL requires a nullable column: ${name}.${columnName}`);
         }
@@ -301,6 +389,9 @@ export function table(name, columns, options = {}) {
     const foreignKeyNames = new Set();
     for (const key of foreignKeys) {
         validateSchemaName(key.name, "FOREIGN KEY");
+        if (key.enforced === false && key.onDelete !== undefined) {
+            throw new TypeError(`Informational FOREIGN KEY ${key.name} cannot declare ON DELETE behavior`);
+        }
         if (foreignKeyNames.has(key.name)) {
             throw new TypeError(`Duplicate FOREIGN KEY in table ${name}: ${key.name}`);
         }
@@ -431,6 +522,7 @@ export function declaredForeignKeys(definition) {
             parentTable: reference.table,
             parentColumns: [reference.column],
             onDelete: reference.onDelete,
+            enforced: reference.enforced,
         });
     }
     for (const key of definition.foreignKeys) {
@@ -442,6 +534,7 @@ export function declaredForeignKeys(definition) {
             parentTable: key.references.table,
             parentColumns,
             onDelete: key.onDelete ?? "restrict",
+            enforced: key.enforced !== false,
         });
     }
     return keys;
@@ -472,6 +565,9 @@ export function view(name, definition) {
         if (columnDefinition.defaultSpec !== undefined) {
             throw new TypeError(`A view column cannot have a default: ${name}.${columnName}`);
         }
+        if (columnDefinition.generatedSpec !== undefined) {
+            throw new TypeError(`A view column cannot be generated: ${name}.${columnName}`);
+        }
     }
     return { kind: "view", name, sql: definition.sql, columns: definition.columns };
 }
@@ -625,6 +721,20 @@ export function assertColumnDroppable(record, column) {
             throw new TypeError(`CHECK ${check.name} still uses this column: ${where}`);
         }
     }
+    for (const dependent of record.columns) {
+        if (dependent.generatedValue === undefined)
+            continue;
+        let referenced;
+        try {
+            referenced = expressionColumns(compileCheckExpression(dependent.generatedValue.sql, `generated ${record.name}.${dependent.name}`));
+        }
+        catch {
+            throw new TypeError(`Generated column ${dependent.name} cannot be re-read, so ${where} is not droppable`);
+        }
+        if (referenced.includes(column.name)) {
+            throw new TypeError(`Generated column ${dependent.name} still uses this column: ${where}`);
+        }
+    }
 }
 function assertColumnRenamable(catalog, record, column) {
     const where = `${record.name}.${column.name}`;
@@ -643,6 +753,14 @@ function assertColumnRenamable(catalog, record, column) {
             throw new TypeError(`CHECK ${check.name} prevents renaming ${where}`);
         }
     }
+    for (const dependent of record.columns) {
+        if (dependent.generatedValue === undefined)
+            continue;
+        const referenced = expressionColumns(compileCheckExpression(dependent.generatedValue.sql, `generated ${record.name}.${dependent.name}`));
+        if (referenced.includes(column.name)) {
+            throw new TypeError(`Generated column ${dependent.name} prevents renaming ${where}`);
+        }
+    }
 }
 /**
  * Freezes a column's backfill. A generator runs exactly once — here, while the migration is being
@@ -675,34 +793,58 @@ function backfillsEqual(left, right) {
     return externalLeft === externalRight;
 }
 /**
- * Constraints on an existing table cannot change through a metadata-only step. Attaching a
- * FOREIGN KEY or CHECK to a table that already holds rows would claim something about those rows
+ * Enforced constraints on an existing table cannot change through a metadata-only step. Attaching
+ * a FOREIGN KEY or CHECK to a table that already holds rows would claim something about those rows
  * that nobody has verified, and no validation scan exists; dropping one is refused for the mirror
- * reason, so that a constraint never disappears because a schema file drifted. Both get the same
- * discipline every other unprovable change gets: an explicit error naming the fix.
+ * reason, so that a constraint never disappears because a schema file drifted. Informational
+ * foreign keys are catalog metadata only, so adding, dropping, or remapping one is safe.
  */
-function assertConstraintsUnchanged(record, definition) {
+function planConstraintChanges(record, definition, steps) {
     const describeKey = (key) => `${key.columns.join(",")} -> ${key.parentTable}.` +
         `${key.parentColumns.join(",")} ON DELETE ${key.onDelete}`;
+    const declaredList = declaredForeignKeys(definition);
     const existingKeys = new Map(record.foreignKeys.map((key) => [key.name, key]));
-    const declaredKeys = new Map(declaredForeignKeys(definition).map((key) => [key.name, key]));
+    const declaredKeys = new Map(declaredList.map((key) => [key.name, key]));
+    let informationalChanged = false;
     for (const [name, declared] of declaredKeys) {
         const existing = existingKeys.get(name);
         if (existing === undefined) {
+            if (!declared.enforced) {
+                informationalChanged = true;
+                continue;
+            }
             throw new TypeError(`FOREIGN KEY cannot be added after creation: ${definition.name}.${declared.columns.join(",")}. ` +
                 `Existing rows are not known to satisfy it; recreate the table to add a relation.`);
         }
+        if (existing.enforced !== declared.enforced) {
+            throw new TypeError(`FOREIGN KEY enforcement cannot change: ${definition.name}.${declared.columns.join(",")}`);
+        }
         if (describeKey(existing) !== describeKey(declared)) {
+            if (!declared.enforced) {
+                informationalChanged = true;
+                continue;
+            }
             throw new TypeError(`FOREIGN KEY cannot change: ${definition.name}.${declared.columns.join(",")} is ` +
                 `${describeKey(existing)}, schema says ${describeKey(declared)}`);
         }
     }
     for (const name of existingKeys.keys()) {
         if (!declaredKeys.has(name)) {
+            if (existingKeys.get(name)?.enforced === false) {
+                informationalChanged = true;
+                continue;
+            }
             throw new TypeError(`FOREIGN KEY cannot be dropped: ${definition.name} still has ${name}. ` +
                 `Declare the relation, or recreate the table without it.`);
         }
     }
+    if (informationalChanged) {
+        steps.push({
+            kind: "alter-foreign-keys",
+            tableName: definition.name,
+            foreignKeys: declaredList,
+        });
+    }
     const existingChecks = new Map(record.checks.map((check) => [check.name, check.sql]));
     const declaredChecks = new Map(definition.checks.map((check) => [check.name, check.sql]));
     for (const [name, sql] of declaredChecks) {
@@ -758,6 +900,9 @@ export function planMigration(catalog, definition, options = {}) {
                 }
             }
             if (existing === undefined) {
+                if (columnDefinition.generatedSpec !== undefined) {
+                    throw new TypeError(`Generated columns cannot be added to an existing table without rewriting its rows: ${tableDefinition.name}.${columnName}`);
+                }
                 const backfill = resolveBackfill(columnDefinition);
                 if (!columnDefinition.isNullable && backfill === undefined) {
                     throw new TypeError(`Added columns must be nullable, or carry a backfill: ${tableDefinition.name}.${columnName}`);
@@ -855,13 +1000,24 @@ export function planMigration(catalog, definition, options = {}) {
                         columnName,
                         enabled: isAuto,
                     });
-                    continue;
                 }
+                else {
+                    steps.push({
+                        kind: "alter-default",
+                        tableName: tableDefinition.name,
+                        columnName,
+                        defaultValue: columnDefinition.defaultSpec ?? null,
+                    });
+                }
+            }
+            const existingGenerated = existing.generatedValue;
+            const definedGenerated = columnDefinition.generatedSpec;
+            if (JSON.stringify(existingGenerated ?? null) !== JSON.stringify(definedGenerated ?? null)) {
                 steps.push({
-                    kind: "alter-default",
+                    kind: "alter-generated",
                     tableName: tableDefinition.name,
                     columnName,
-                    defaultValue: columnDefinition.defaultSpec ?? null,
+                    generatedValue: definedGenerated ?? null,
                 });
             }
         }
@@ -889,7 +1045,7 @@ export function planMigration(catalog, definition, options = {}) {
             desiredKeyIds.some((id, index) => id !== existingKeyIds[index])) {
             throw new TypeError(`Primary key order cannot change: ${tableDefinition.name}`);
         }
-        assertConstraintsUnchanged(record, tableDefinition);
+        planConstraintChanges(record, tableDefinition, steps);
     }
     if (options.schemaOwnsDatabase === true) {
         const declaredTables = new Set(definition.tables.map(({ name }) => name));
@@ -1149,6 +1305,16 @@ export function applyColumnSteps(record, steps, createId) {
                 else
                     target.defaultValue = step.defaultValue;
             }
+            continue;
+        }
+        if (step.kind === "alter-generated") {
+            const target = columns.find(({ name }) => name === step.columnName);
+            if (target !== undefined) {
+                if (step.generatedValue === null)
+                    delete target.generatedValue;
+                else
+                    target.generatedValue = step.generatedValue;
+            }
         }
     }
     return columns;

package/dist/engine/sql-domains.d.ts

@@ -18,7 +18,18 @@ export declare function exactNumericCompare(left: unknown, right: unknown): numb
  */
 export declare function boundedJsonText(value: unknown, canonical: boolean, label?: string): string;
 export declare function jsonDomainValue(value: unknown, binary: boolean): string | null;
+/** Returns the JSON document carried by an internal JSON/JSONB scalar, if any. */
+export declare function jsonDomainDocument(value: unknown): string | undefined;
+/**
+ * Tags already-constructed JSON without parsing and re-stringifying it. The validation parse
+ * rejects malformed documents, while retaining duplicate object names and the constructor's
+ * exact member order for embedding in an outer JSON value.
+ */
+export declare function preservedJsonDomainValue(document: string, binary?: boolean): string;
 export declare function uuidDomainValue(value: unknown): string | null;
+/** Canonical, zoneless SQL DATE value. No JavaScript time zone participates in validation. */
+export declare function dateDomainValue(value: unknown): string | null;
+export declare function isDateDomainValue(value: unknown): value is string;
 export declare function timeDomainValue(value: unknown): string | null;
 export declare function intervalDomainValue(value: unknown): string | null;
 export declare function arrayDomainValue(values: readonly unknown[]): string;

package/dist/engine/sql-domains.js

@@ -8,6 +8,7 @@ const NUMERIC = `${PREFIX}numeric:`;
 const JSON_VALUE = `${PREFIX}json:`;
 const JSONB_VALUE = `${PREFIX}jsonb:`;
 const UUID_VALUE = `${PREFIX}uuid:`;
+const DATE_VALUE = `${PREFIX}date:`;
 const TIME_VALUE = `${PREFIX}time:`;
 const INTERVAL_VALUE = `${PREFIX}interval:`;
 const ARRAY_VALUE = `${PREFIX}array:`;
@@ -312,6 +313,31 @@ export function jsonDomainValue(value, binary) {
     const text = boundedJsonText(parsed, binary, binary ? "JSONB value" : "JSON value");
     return boundedTaggedDomainValue(binary ? JSONB_VALUE : JSON_VALUE, text, binary ? "JSONB value" : "JSON value");
 }
+/** Returns the JSON document carried by an internal JSON/JSONB scalar, if any. */
+export function jsonDomainDocument(value) {
+    if (typeof value !== "string")
+        return undefined;
+    if (value.startsWith(JSONB_VALUE))
+        return value.slice(JSONB_VALUE.length);
+    if (value.startsWith(JSON_VALUE))
+        return value.slice(JSON_VALUE.length);
+    return undefined;
+}
+/**
+ * Tags already-constructed JSON without parsing and re-stringifying it. The validation parse
+ * rejects malformed documents, while retaining duplicate object names and the constructor's
+ * exact member order for embedding in an outer JSON value.
+ */
+export function preservedJsonDomainValue(document, binary = false) {
+    assertBoundedDomainString(document, binary ? "JSONB value" : "JSON value");
+    try {
+        JSON.parse(document);
+    }
+    catch {
+        throw new TypeError("Invalid JSON value");
+    }
+    return boundedTaggedDomainValue(binary ? JSONB_VALUE : JSON_VALUE, document, binary ? "JSONB value" : "JSON value");
+}
 export function uuidDomainValue(value) {
     if (value === null || value === undefined)
         return null;
@@ -324,6 +350,42 @@ export function uuidDomainValue(value) {
     }
     return UUID_VALUE + source;
 }
+/** Canonical, zoneless SQL DATE value. No JavaScript time zone participates in validation. */
+export function dateDomainValue(value) {
+    if (value === null || value === undefined)
+        return null;
+    let source;
+    if (value instanceof Date) {
+        if (!Number.isFinite(value.getTime()))
+            throw new TypeError("DATE accepts a valid Date value");
+        source = dateIsoString(value).slice(0, 10);
+    }
+    else if (typeof value === "string") {
+        assertBoundedDomainString(value, "DATE value");
+        source = value.startsWith(DATE_VALUE) ? value.slice(DATE_VALUE.length) : value;
+    }
+    else {
+        throw new TypeError("DATE accepts a YYYY-MM-DD string value");
+    }
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(source);
+    const year = Number(match?.[1]);
+    const month = Number(match?.[2]);
+    const day = Number(match?.[3]);
+    const leap = year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0);
+    const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+    if (match === null ||
+        year < 1 ||
+        month < 1 ||
+        month > 12 ||
+        day < 1 ||
+        day > (days[month - 1] ?? 0)) {
+        throw new TypeError(`Invalid DATE value: ${String(value)}`);
+    }
+    return DATE_VALUE + source;
+}
+export function isDateDomainValue(value) {
+    return typeof value === "string" && value.startsWith(DATE_VALUE);
+}
 export function timeDomainValue(value) {
     if (value === null || value === undefined)
         return null;
@@ -464,6 +526,8 @@ export function normalizeSqlDomainValue(domain, value) {
         return jsonDomainValue(value, true);
     if (domain.kind === "uuid")
         return uuidDomainValue(value);
+    if (domain.kind === "date")
+        return dateDomainValue(value);
     if (domain.kind === "time")
         return timeDomainValue(value);
     if (domain.kind === "interval")
@@ -562,7 +626,7 @@ export function externalSqlDomainValue(value) {
         return value;
     if (value.startsWith(TEXT_VALUE))
         return value.slice(TEXT_VALUE.length);
-    for (const prefix of [NUMERIC, JSON_VALUE, JSONB_VALUE, UUID_VALUE, TIME_VALUE]) {
+    for (const prefix of [NUMERIC, JSON_VALUE, JSONB_VALUE, UUID_VALUE, DATE_VALUE, TIME_VALUE]) {
         if (value.startsWith(prefix))
             return value.slice(prefix.length);
     }

package/dist/engine/sql-json.js

@@ -1,5 +1,5 @@
 import { stringArgument } from "./sql-semantics.js";
-import { externalSqlDomainValue } from "./sql-domains.js";
+import { externalSqlDomainValue, jsonDomainDocument } from "./sql-domains.js";
 import { MAX_CACHEABLE_TEXT_CHARACTERS, MAX_SQL_SCALAR_RESULT_CHARACTERS } from "./cache-limits.js";
 export function parseJsonPath(path, caller) {
     const text = stringArgument(caller, path).trim();
@@ -119,7 +119,7 @@ export function jsonConstructor(name, values) {
     }
     const members = [];
     for (let index = 0; index + 1 < values.length; index += 2) {
-        const rawKey = values[index];
+        const rawKey = externalSqlDomainValue(values[index]);
         if (rawKey === null || rawKey === undefined) {
             throw new TypeError("JSON_OBJECT keys cannot be NULL");
         }
@@ -136,12 +136,24 @@ export function jsonConstructor(name, values) {
         // Build JSON text directly. WITHOUT UNIQUE KEYS is the default, so duplicate names must be
         // preserved; assigning through a JavaScript object would collapse them and mishandle
         // special names such as "__proto__".
-        const encodedKey = boundedJsonValue(key, "JSON_OBJECT key");
+        // Keys are always JSON strings. In particular, a JSON-domain expression used as a key is
+        // its document text, not a raw object member token as JSON-domain values are below.
+        const encodedKey = boundedJsonString(key, "JSON_OBJECT key");
         const encodedValue = boundedJsonValue(member ?? null, "JSON_OBJECT value");
         members.push(`${encodedKey}:${encodedValue}`);
     }
     return joinBoundedJson("{", members, "}", "JSON_OBJECT result");
 }
+function boundedJsonString(value, label) {
+    if (value.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+        throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+    }
+    const encoded = JSON.stringify(value);
+    if (encoded.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+        throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+    }
+    return encoded;
+}
 function boundedJsonDocument(value, caller) {
     const document = stringArgument(caller, externalSqlDomainValue(value));
     if (document.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
@@ -150,6 +162,13 @@ function boundedJsonDocument(value, caller) {
     return document;
 }
 function boundedJsonValue(value, label) {
+    const domainDocument = jsonDomainDocument(value);
+    if (domainDocument !== undefined) {
+        if (domainDocument.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
+            throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);
+        }
+        return domainDocument;
+    }
     const normalized = jsonValueOf(value);
     if (typeof normalized === "string" && normalized.length > MAX_SQL_SCALAR_RESULT_CHARACTERS) {
         throw new RangeError(`${label} exceeds ${String(MAX_SQL_SCALAR_RESULT_CHARACTERS)} characters`);

package/dist/engine/sql-semantics.js

@@ -1,7 +1,7 @@
 import { dateMilliseconds } from "../date-value.js";
 import { assertWellFormedString } from "../block-format/unicode.js";
 import { MAX_SQL_NESTING_DEPTH, MAX_SQL_PATTERN_CHARACTERS, MAX_SQL_PATTERN_MATCH_STEPS, } from "./cache-limits.js";
-import { collatedDomainCompare, enumDomainCompare, exactNumericCompare, externalSqlDomainValue, externalSqlTextValue, } from "./sql-domains.js";
+import { collatedDomainCompare, enumDomainCompare, exactNumericCompare, externalSqlDomainValue, externalSqlTextValue, isDateDomainValue, } from "./sql-domains.js";
 /**
  * SQL value semantics shared by the row and vector executors.
  *
@@ -31,8 +31,26 @@ export function compareSqlValues(left, right) {
     const exact = exactNumericCompare(left, right);
     if (exact !== undefined)
         return exact;
-    const a = left instanceof Date ? dateMilliseconds(left) : left;
-    const b = right instanceof Date ? dateMilliseconds(right) : right;
+    const temporal = (value) => {
+        if (value instanceof Date)
+            return dateMilliseconds(value);
+        if (!isDateDomainValue(value))
+            return undefined;
+        const external = externalSqlDomainValue(value);
+        return typeof external === "string" ? Date.parse(`${external}T00:00:00.000Z`) : undefined;
+    };
+    const temporalLeft = temporal(left);
+    const temporalRight = temporal(right);
+    if (temporalLeft !== undefined || temporalRight !== undefined) {
+        const comparableLeft = temporalLeft ?? (typeof left === "number" ? left : undefined);
+        const comparableRight = temporalRight ?? (typeof right === "number" ? right : undefined);
+        if (comparableLeft === undefined || comparableRight === undefined) {
+            throw new TypeError("Values must have comparable SQL types");
+        }
+        return comparableLeft - comparableRight;
+    }
+    const a = left;
+    const b = right;
     if (a === b)
         return 0;
     if (a === null || a === undefined)

package/dist/engine/vector.d.ts

@@ -75,6 +75,8 @@ export interface QuerySpillStore {
 export interface AsyncQueryExecutionOptions {
     readonly spillStore?: QuerySpillStore;
     readonly spillPageRows?: number;
+    /** Stops before the next execution or spill-storage batch. */
+    readonly signal?: AbortSignal;
     /**
      * Makes the scan-source window [start, start + length) resident before each batch. Supplied by
      * a streaming preparation whose scan-source vectors hold only a sliding window; the executor
@@ -88,8 +90,6 @@ export interface AsyncQueryExecutionOptions {
 export interface QueryBatchExecutionOptions extends AsyncQueryExecutionOptions {
     /** Maximum result rows handed to the consumer at once. */
     readonly batchRows: number;
-    /** Stops before the next scan batch and is checked after every awaited storage read. */
-    readonly signal?: AbortSignal;
 }
 export interface PrepareVectorQueryOptions {
     readonly memoryContext?: QueryMemoryContext;