@minnowdb/core 0.4.1 → 0.5.0

package/dist/storage/toolkit/record-core.js

@@ -1,4 +1,4 @@
-import { CompactionBacklogError, CompactionJobConflictError, assertCompactionOutputProvenance, compactionOutputSegmentIds, createManifest, createGarbageCollectionJobRecord, advanceGarbageCollectionJobRecord, collectFtsCandidates, collectFtsPostingsBounded, activePostingStorageColumnIds, invalidateUncoveredFtsColumns, invalidateUncoveredSecondaryIndexes, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, MAX_LEASE_TTL_MS, MAX_ACTIVE_LEASES, MAX_ACTIVE_TEMP_OWNERS, MAX_ACTIVE_COMPACTION_JOBS, MAX_ACTIVE_UNIQUE_KEY_BUILDS, MAX_ACTIVE_TRANSACTIONS, MAX_TERMINAL_TRANSACTION_RECORDS, MAX_TERMINAL_COMPACTION_JOB_RECORDS, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS, MAX_PINNED_MANIFEST_VERSION_LAG, MAX_PINNED_RETIRED_BLOCKS, MAX_PINNED_RETIRED_BYTES, MAX_RETIRED_HISTORY_BYTES, MAX_GLOBAL_STAGED_ARTIFACT_BYTES, MAX_GLOBAL_STAGED_BLOCKS, MAX_GLOBAL_STAGED_SEGMENTS, MAX_TEMP_OWNER_TTL_MS, MAX_ROW_ID, MAX_ROW_ID_EXCLUSIVE_END, MAX_AUTO_INCREMENT_EXCLUSIVE_END, MAX_LEVEL_ZERO_SEGMENTS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_STORAGE_ID_CHARACTERS, MAX_CATALOG_RECORDS, MAX_CATALOG_RETAINED_BYTES, MAX_MANIFEST_RECORDS, MAX_MANIFEST_RETAINED_BYTES, MAX_SEGMENT_RECORDS, MAX_SEGMENT_RETAINED_BYTES, MAX_FTS_CANDIDATE_ROW_IDS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_TOKENS_PER_DOCUMENT, MAX_FTS_BASE_CHUNKS, MAX_FTS_DELTA_CHUNKS, SnapshotManifestMissingError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyConflictError, UniqueKeyBuildConflictError, UniqueIndexCoverageError, assertTransactionArtifactBatchLimits, assertTransactionArtifactJournalLimits, assertTempRunPageBatchLimits, assertStorageBulkReadItems, boundedMaintenanceBatchItems, normalizeCompactionJobRecord, normalizeGarbageCollectionJobRecord, normalizeSegmentRecord, updateCompactionJobRecord, updateTransactionRecord, updateGarbageCollectionPlanningRecord, validateTableColumns, validateSecondaryIndexes, secondaryIndexColumnIds, secondaryIndexWriteContractChanged, secondaryUniqueKeyNamespace, transactionCommitDeltaRetainedBytes, uniqueKeyBuildChunkRetainedBytes, MAX_UNIQUE_KEY_BUILD_TTL_MS, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES_TOTAL, MAX_UNIQUE_KEY_BUILD_TOKENS_PER_CHUNK, validateFtsPostingQueries, validateCanonicalManifestChangedTableIds, catalogRecordRetainedBytes, manifestRecordRetainedReservationBytes, segmentRecordRetainedBytes, snapshotAcceleratorItemRetainedUsage, assertSnapshotImportAcceleratorUsage, SchemaConflictError, WriteConflictError, } from "../types.js";
+import { CompactionBacklogError, CompactionJobConflictError, assertCompactionOutputProvenance, compactionOutputSegmentIds, createManifest, createGarbageCollectionJobRecord, advanceGarbageCollectionJobRecord, collectFtsCandidates, collectFtsPostingsBounded, activePostingStorageColumnIds, invalidateUncoveredFtsColumns, invalidateUncoveredSecondaryIndexes, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, MAX_LEASE_TTL_MS, MAX_ACTIVE_LEASES, MAX_ACTIVE_TEMP_OWNERS, MAX_ACTIVE_COMPACTION_JOBS, MAX_ACTIVE_UNIQUE_KEY_BUILDS, MAX_ACTIVE_TRANSACTIONS, MAX_TERMINAL_TRANSACTION_RECORDS, MAX_TERMINAL_COMPACTION_JOB_RECORDS, MAX_COMPLETED_GARBAGE_COLLECTION_JOB_RECORDS, MAX_PINNED_MANIFEST_VERSION_LAG, MAX_PINNED_RETIRED_BLOCKS, MAX_PINNED_RETIRED_BYTES, MAX_RETIRED_HISTORY_BYTES, MAX_GLOBAL_STAGED_ARTIFACT_BYTES, MAX_GLOBAL_STAGED_BLOCKS, MAX_GLOBAL_STAGED_SEGMENTS, MAX_TEMP_OWNER_TTL_MS, MAX_ROW_ID, MAX_ROW_ID_EXCLUSIVE_END, MAX_AUTO_INCREMENT_EXCLUSIVE_END, MAX_LEVEL_ZERO_SEGMENTS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_STORAGE_ID_CHARACTERS, MAX_CATALOG_RECORDS, MAX_CATALOG_RETAINED_BYTES, MAX_MANIFEST_RECORDS, MAX_MANIFEST_RETAINED_BYTES, MAX_SEGMENT_RECORDS, MAX_SEGMENT_RETAINED_BYTES, MAX_FTS_CANDIDATE_ROW_IDS, MAX_FTS_POSTINGS_PER_CHUNK, MAX_FTS_POSTING_ROW_IDS_PER_CHUNK, MAX_FTS_POSTING_TERM_CHARACTERS, MAX_FTS_TOKENS_PER_DOCUMENT, MAX_FTS_BASE_CHUNKS, MAX_FTS_DELTA_CHUNKS, SnapshotManifestMissingError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyConflictError, UniqueKeyBuildConflictError, UniqueIndexCoverageError, assertTransactionArtifactBatchLimits, assertTransactionArtifactJournalLimits, assertTempRunPageBatchLimits, assertStorageBulkReadItems, boundedMaintenanceBatchItems, normalizeCompactionJobRecord, normalizeGarbageCollectionJobRecord, normalizeSegmentRecord, updateCompactionJobRecord, updateTransactionRecord, updateGarbageCollectionPlanningRecord, validateTableColumns, validateTableForeignKey, validateSecondaryIndexes, secondaryIndexColumnIds, secondaryIndexWriteContractChanged, secondaryUniqueKeyNamespace, transactionCommitDeltaRetainedBytes, uniqueKeyBuildChunkRetainedBytes, MAX_UNIQUE_KEY_BUILD_TTL_MS, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES, MAX_UNIQUE_KEY_BUILD_STAGED_BYTES_TOTAL, MAX_UNIQUE_KEY_BUILD_TOKENS_PER_CHUNK, validateFtsPostingQueries, validateCanonicalManifestChangedTableIds, catalogRecordRetainedBytes, manifestRecordRetainedReservationBytes, segmentRecordRetainedBytes, snapshotAcceleratorItemRetainedUsage, assertSnapshotImportAcceleratorUsage, SchemaConflictError, WriteConflictError, } from "../types.js";
 import { dateIsoString } from "../../date-value.js";
 import { assertWellFormedString, crc32, MAX_STORED_BLOCK_BYTE_LENGTH, } from "../../block-format/index.js";
 const postingTextEncoder = new TextEncoder();
@@ -1300,16 +1300,7 @@ export class RecordCore {
             if (parent === undefined) {
                 throw new TypeError(`FOREIGN KEY ${key.name} references a missing table: ${key.parentTable}`);
             }
-            const addressIds = parent.primaryKeyColumnIds?.length
-                ? parent.primaryKeyColumnIds
-                : parent.uniqueKeyColumnId === undefined
-                    ? []
-                    : [parent.uniqueKeyColumnId];
-            const addressNames = addressIds.map((id) => parent.columns.find((column) => column.id === id)?.name ?? "");
-            if (addressNames.length !== key.parentColumns.length ||
-                addressNames.some((name, index) => name !== key.parentColumns[index])) {
-                throw new TypeError(`FOREIGN KEY ${key.name} must reference the parent primary or unique key`);
-            }
+            validateTableForeignKey(record, key, parent);
         }
     }
     getTable(id) {
@@ -1342,7 +1333,7 @@ export class RecordCore {
         }
         if (update.columns !== undefined)
             validateTableColumns(update.columns);
-        const { ftsColumns: previousFts, secondaryIndexes: previousSecondary, triggers: previousTriggers, view: previousView, ...base } = record;
+        const { ftsColumns: previousFts, secondaryIndexes: previousSecondary, triggers: previousTriggers, view: previousView, foreignKeys: previousForeignKeys, ...base } = record;
         let nextFts = update.ftsColumns === undefined ? previousFts : update.ftsColumns;
         let nextSecondary = update.secondaryIndexes === undefined ? previousSecondary : update.secondaryIndexes;
         const retainedColumnIds = update.columns === undefined
@@ -1373,6 +1364,7 @@ export class RecordCore {
         }
         const nextTriggers = update.triggers === undefined ? previousTriggers : update.triggers;
         const nextView = update.view === undefined ? previousView : update.view;
+        const nextForeignKeys = update.foreignKeys ?? previousForeignKeys;
         validateTableView(nextView ?? undefined);
         const updated = {
             ...base,
@@ -1386,10 +1378,12 @@ export class RecordCore {
             ...(nextTriggers === null || nextTriggers === undefined
                 ? {}
                 : { triggers: structuredClone(nextTriggers) }),
+            ...(nextForeignKeys === undefined ? {} : { foreignKeys: structuredClone(nextForeignKeys) }),
             ...(nextView === null || nextView === undefined ? {} : { view: structuredClone(nextView) }),
             revision: safeWholeIncrement(expectedRevision, "Table revision"),
         };
         validateSecondaryIndexes(updated);
+        this.#assertTableForeignKeys(updated);
         this.#assertTableTriggerOwnership(updated);
         let autoIncrementCounter;
         if (update.autoIncrementSeed !== undefined) {
@@ -5552,16 +5546,7 @@ function validateRecordCoreState(state, physical) {
             if (parent === undefined) {
                 throw new TypeError(`FOREIGN KEY ${key.name} references a missing table: ${key.parentTable}`);
             }
-            const addressIds = parent.primaryKeyColumnIds?.length
-                ? parent.primaryKeyColumnIds
-                : parent.uniqueKeyColumnId === undefined
-                    ? []
-                    : [parent.uniqueKeyColumnId];
-            const addressNames = addressIds.map((id) => parent.columns.find((column) => column.id === id)?.name ?? "");
-            if (addressNames.length !== key.parentColumns.length ||
-                addressNames.some((name, index) => name !== key.parentColumns[index])) {
-                throw new TypeError(`FOREIGN KEY ${key.name} must reference the parent primary or unique key`);
-            }
+            validateTableForeignKey(table, key, parent);
         }
     }
     const terminalTransactionCount = state.transactions.filter((transaction) => transaction.status !== "active").length;

package/dist/storage/types.d.ts

@@ -111,7 +111,7 @@ export type SqlDomain = {
     precision?: number;
     scale?: number;
 } | {
-    kind: "json" | "jsonb" | "uuid" | "time" | "interval";
+    kind: "json" | "jsonb" | "uuid" | "date" | "time" | "interval";
 } | {
     kind: "array";
     element: string;
@@ -264,6 +264,15 @@ export interface SecondaryIndexRecord {
  * accelerator. Index identity, key shape, and UNIQUE enforcement are structural.
  */
 export declare function secondaryIndexWriteContractChanged(previous: Readonly<Record<string, SecondaryIndexRecord>> | null | undefined, next: Readonly<Record<string, SecondaryIndexRecord>> | null | undefined): boolean;
+export interface TableForeignKeyRecord {
+    name: string;
+    columns: string[];
+    parentTable: string;
+    parentColumns: string[];
+    onDelete: "restrict" | "cascade" | "set null";
+    /** False records relationship metadata without write/delete enforcement. Absent means true. */
+    enforced?: boolean;
+}
 export interface TableRecord {
     id: string;
     name: string;
@@ -279,13 +288,7 @@ export interface TableRecord {
     /** BEFORE/AFTER triggers on this table, fired by the committing writer in its transaction. */
     triggers?: TriggerRecord[];
     /** FOREIGN KEY constraints. Column tuples are always explicit, including scalar keys. */
-    foreignKeys?: Array<{
-        name: string;
-        columns: string[];
-        parentTable: string;
-        parentColumns: string[];
-        onDelete: "restrict" | "cascade" | "set null";
-    }>;
+    foreignKeys?: TableForeignKeyRecord[];
     /**
      * Row-level CHECK constraints (E141-06), each the text of a boolean expression over this
      * table's own columns. Text rather than a compiled form because the record crosses the worker
@@ -329,6 +332,12 @@ export interface TableRecord {
     /** Compare-and-swap revision for catalog evolution. */
     revision: number;
 }
+/**
+ * Validates one relationship against its child and parent records. This is shared by every
+ * storage adapter and snapshot restore path so informational relationships cannot bypass the
+ * same structural and domain checks as enforced foreign keys.
+ */
+export declare function validateTableForeignKey(childTable: TableRecord, key: TableForeignKeyRecord, parentTable: TableRecord): void;
 /** Exact UTF-8 bytes used when the canonical record-wire JSON codec persists a table record. */
 export declare function catalogRecordRetainedBytes(record: TableRecord): number;
 export declare function manifestRecordRetainedBytes(record: Manifest): number;
@@ -1815,6 +1824,8 @@ export interface CatalogMutationOptions {
 /** Atomic replacement fields for one catalog record. */
 export interface TableRecordUpdate extends CatalogMutationOptions {
     columns?: TableColumnRecord[];
+    /** Replaces the complete relationship catalog. */
+    foreignKeys?: TableRecord["foreignKeys"];
     /** Replaces the full-text index state map; null clears it. */
     ftsColumns?: Record<string, FtsColumnIndexRecord> | null;
     /** Replaces the secondary-index state map; null clears it. */

package/dist/storage/types.js

@@ -258,6 +258,70 @@ export function secondaryIndexWriteContractChanged(previous, next) {
             left.locator !== right.locator);
     });
 }
+/**
+ * Validates one relationship against its child and parent records. This is shared by every
+ * storage adapter and snapshot restore path so informational relationships cannot bypass the
+ * same structural and domain checks as enforced foreign keys.
+ */
+export function validateTableForeignKey(childTable, key, parentTable) {
+    if (typeof key.name !== "string" ||
+        key.name.length === 0 ||
+        typeof key.parentTable !== "string" ||
+        key.parentTable.length === 0 ||
+        !Array.isArray(key.columns) ||
+        !Array.isArray(key.parentColumns) ||
+        key.columns.length === 0 ||
+        key.columns.some((column) => typeof column !== "string" || column.length === 0) ||
+        key.parentColumns.some((column) => typeof column !== "string" || column.length === 0) ||
+        new Set(key.columns).size !== key.columns.length ||
+        new Set(key.parentColumns).size !== key.parentColumns.length ||
+        !["restrict", "cascade", "set null"].includes(key.onDelete) ||
+        (key.enforced !== undefined && typeof key.enforced !== "boolean")) {
+        throw new TypeError("FOREIGN KEY metadata is invalid");
+    }
+    if (key.parentTable !== parentTable.name) {
+        throw new TypeError(`FOREIGN KEY ${key.name} resolved to the wrong parent table`);
+    }
+    if (key.enforced === false && key.onDelete !== "restrict") {
+        throw new TypeError(`Informational FOREIGN KEY ${key.name} cannot declare ON DELETE actions`);
+    }
+    const children = key.columns.map((name) => childTable.columns.find((column) => column.name === name && column.hidden !== true));
+    if (children.some((column) => column === undefined)) {
+        throw new TypeError(`FOREIGN KEY ${key.name} names a column this table does not have`);
+    }
+    const addressIds = parentTable.primaryKeyColumnIds?.length
+        ? parentTable.primaryKeyColumnIds
+        : parentTable.uniqueKeyColumnId === undefined
+            ? []
+            : [parentTable.uniqueKeyColumnId];
+    const parents = addressIds.map((id) => parentTable.columns.find((column) => column.id === id && column.hidden !== true));
+    const addressNames = parents.map((column) => column?.name ?? "");
+    if (addressNames.length !== key.parentColumns.length ||
+        addressNames.some((name, index) => name !== key.parentColumns[index])) {
+        throw new TypeError(`FOREIGN KEY ${key.name} must reference the parent primary or unique key`);
+    }
+    if (children.length !== parents.length) {
+        throw new TypeError(`FOREIGN KEY ${key.name} has ${String(children.length)} child columns for ${String(parents.length)} parent columns`);
+    }
+    children.forEach((child, index) => {
+        const parent = parents[index];
+        if (child === undefined || parent === undefined) {
+            throw new TypeError(`FOREIGN KEY ${key.name} is missing a key column`);
+        }
+        if (child.type !== parent.type) {
+            throw new TypeError(`FOREIGN KEY ${key.name} compares ${child.type} with ${parent.type}`);
+        }
+        if ((child.integer === true) !== (parent.integer === true)) {
+            throw new TypeError(`FOREIGN KEY ${key.name} compares an integer domain with an approximate number domain`);
+        }
+        if (JSON.stringify(child.sqlDomain ?? null) !== JSON.stringify(parent.sqlDomain ?? null)) {
+            throw new TypeError(`FOREIGN KEY ${key.name} compares different SQL value domains`);
+        }
+        if (key.onDelete === "set null" && !child.nullable) {
+            throw new TypeError(`FOREIGN KEY ${key.name} cannot SET NULL a NOT NULL column`);
+        }
+    });
+}
 const catalogRecordTextEncoder = new TextEncoder();
 function durableRecordRetainedBytes(record, label) {
     // Keep this byte accounting identical to the canonical record-wire JSON codec without
@@ -389,6 +453,11 @@ export function validateTableRecordBounds(record) {
         throw new RangeError(`A table cannot exceed ${String(MAX_TABLE_CONSTRAINTS)} named constraints`);
     }
     const constraintNames = new Set();
+    for (const key of record.foreignKeys ?? []) {
+        if (key.enforced !== undefined && typeof key.enforced !== "boolean") {
+            throw new TypeError(`FOREIGN KEY enforcement is invalid: ${key.name}`);
+        }
+    }
     for (const constraintName of namedConstraints) {
         validateCatalogName(constraintName, "Constraint name");
         if (constraintNames.has(constraintName)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minnowdb/core",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "A columnar SQL database for the browser: PostgreSQL-style SQL over durable IndexedDB or OPFS data, with no server or WebAssembly module.",
   "license": "MIT",
   "author": "Eric Wilhite",

package/postgres-feature-profile.json

@@ -149,6 +149,11 @@
       "classification": "different",
       "reason": "Minnow returns arrays as canonical JSON text at the JavaScript boundary while PostgreSQL clients commonly return native arrays."
     },
+    {
+      "id": "type.date",
+      "classification": "different",
+      "reason": "Minnow returns zoneless DATE values as canonical YYYY-MM-DD text while PostgreSQL clients commonly materialize them as midnight Date objects."
+    },
     {
       "id": "json.query",
       "classification": "different",

package/sql-feature-matrix.json

@@ -1161,6 +1161,12 @@
       "example": "SELECT TIME '12:00:00' AS at",
       "notes": "A time of day without a time zone, returned as canonical text."
     },
+    {
+      "id": "type.date",
+      "status": "supported",
+      "example": "SELECT CAST('2026-08-26' AS DATE) AS day",
+      "notes": "A calendar date without a time zone, returned as canonical YYYY-MM-DD text."
+    },
     {
       "id": "ddl.sequence",
       "status": "supported",