@minnowdb/core 0.4.1 → 0.5.0

package/README.md

@@ -9,15 +9,15 @@ npm install @minnowdb/core
 
 - Direct SQL through `MinnowDatabase.query()` and `execute()`.
 - Joins, CTEs, window functions, grouping sets, upserts, `RETURNING`, triggers, exact decimals,
-  JSON/JSONB, arrays, enums, sequences, and savepoints.
+  JSON/JSONB, zoneless DATE, arrays, enums, sequences, and savepoints.
 - Compressed column storage, secondary indexes, full-text search, and snapshot reads.
 - Atomic writes across tabs through IndexedDB or OPFS, strict durability by default, and explicit
   origin-eviction persistence policy.
 - A ready-made worker client with the same everyday database API.
-- TypeScript schema declarations and metadata-only migrations, including SQL domains and
-  composite primary/foreign keys.
-- Batch writes, pull-driven query cursors, live queries, snapshots, compaction, and configurable
-  query memory.
+- TypeScript schema declarations and metadata-only migrations, including SQL domains,
+  composite primary/foreign keys, and informational relationships.
+- Guarded columnar upserts, result-column SQL domains, typed catalog errors, and batch writes.
+- Pull-driven query cursors, live queries, snapshots, compaction, and configurable query memory.
 
 Use [the PostgreSQL compatibility page](https://minnowdb.com/docs/sql/feature-matrix/) for the
 exact SQL surface. Use [the documentation](https://minnowdb.com/docs/) for installation, storage,

package/dist/engine/catalog.d.ts

@@ -33,6 +33,8 @@ export interface CatalogForeignKey {
     readonly parentTable: string;
     readonly parentColumns: readonly string[];
     readonly onDelete: "restrict" | "cascade" | "set null";
+    /** Whether writes and parent deletes enforce this relationship. */
+    readonly enforced: boolean;
 }
 export interface CatalogCheck {
     readonly name: string;

package/dist/engine/catalog.js

@@ -45,7 +45,10 @@ export function toCatalog(records) {
             ...(record.primaryKeyColumnIds === undefined
                 ? {}
                 : { primaryKeyColumnIds: [...record.primaryKeyColumnIds] }),
-            foreignKeys: (record.foreignKeys ?? []).map((key) => ({ ...key })),
+            foreignKeys: (record.foreignKeys ?? []).map((key) => ({
+                ...key,
+                enforced: key.enforced !== false,
+            })),
             checks: (record.checks ?? []).map((check) => ({ ...check })),
             ...(record.secondaryIndexes === undefined
                 ? {}

package/dist/engine/client.d.ts

@@ -1,7 +1,7 @@
 import { type CompactionJobRecord, type GarbageCollectionJobRecord, type StorageIntegrityMode, type StorageIntegrityReport, type StorageStats, type InterruptedSnapshotImport, type InterruptedSnapshotImportAbortResult } from "../storage/types.js";
 import { type BatchRow, type InsertBatchInput } from "./batch.js";
 import type { Catalog } from "./catalog.js";
-import type { BatchValue, BufferPoolStats, StagedWriteResult, BufferedFlushResult, BufferedWriterOptions, CancelCompactionJobResult, CollectGarbageOptions, CollectGarbageStepOptions, CompactTableOptions, CompactTableResult, CompactTableStepOptions, CompactionJobProgress, CreateTableInput, DatabaseRow, MigrateOptions, DeleteBatchInput, DeleteBatchResult, ExecuteResult, GarbageCollectionProgress, GarbageCollectionResult, MaintenanceStatus, InsertBatchResult, QueryOptions, QueryCursorOptions, QuerySpillCleanupOptions, QuerySpillCleanupResult, ReadTableOptions, RunStatementOptions, SnapshotExportOptions, SnapshotImportOptions, TableDefinition, UpdateBatchInput, UpdateBatchResult, UpsertBatchResult, VisibleSegmentPage, VisibleSegmentPageOptions } from "./database.js";
+import type { BatchValue, BufferPoolStats, StagedWriteResult, BufferedFlushResult, BufferedWriterOptions, CancelCompactionJobResult, CollectGarbageOptions, CollectGarbageStepOptions, CompactTableOptions, CompactTableResult, CompactTableStepOptions, CompactionJobProgress, CreateTableInput, DatabaseRow, MigrateOptions, DeleteBatchInput, DeleteBatchResult, ExecuteResult, GarbageCollectionProgress, GarbageCollectionResult, MaintenanceStatus, InsertBatchResult, QueryOptions, QueryCursorOptions, QuerySpillCleanupOptions, QuerySpillCleanupResult, ReadTableOptions, RunStatementOptions, SnapshotExportOptions, SnapshotImportOptions, TableDefinition, UpdateBatchInput, UpdateBatchResult, UpsertBatchResult, UpsertOptions, VisibleSegmentPage, VisibleSegmentPageOptions } from "./database.js";
 import type { LiveQueryInput, LiveQueryInvalidation, LiveQueryObserveOptions, LiveQueryStats, LiveQuerySubscribeOptions } from "./live.js";
 import type { CompiledQuery, CompiledStatement, QueryResult, QueryValue } from "./query.js";
 import type { AnyTable, SchemaDefinition } from "./schema.js";
@@ -78,8 +78,8 @@ export declare class MinnowDatabaseClient {
     migrate(definition: SchemaDefinition<readonly AnyTable[]>, options?: MigrateOptions): Promise<ClientMigrationResult>;
     insertBatch(tableName: string, input: InsertBatchInput): Promise<InsertBatchResult>;
     insert(tableName: string, row: BatchRow): Promise<InsertBatchResult>;
-    upsertBatch(tableName: string, input: InsertBatchInput): Promise<UpsertBatchResult>;
-    upsert(tableName: string, row: BatchRow): Promise<UpsertBatchResult>;
+    upsertBatch(tableName: string, input: InsertBatchInput, options?: UpsertOptions): Promise<UpsertBatchResult>;
+    upsert(tableName: string, row: BatchRow, options?: UpsertOptions): Promise<UpsertBatchResult>;
     updateBatch(tableName: string, input: UpdateBatchInput): Promise<UpdateBatchResult>;
     update(tableName: string, key: Exclude<BatchValue, null>, changes: Readonly<Record<string, BatchValue>>): Promise<UpdateBatchResult>;
     deleteBatch(tableName: string, input: DeleteBatchInput): Promise<DeleteBatchResult>;

package/dist/engine/client.js

@@ -2,7 +2,7 @@ import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConfl
 import { MAX_SNAPSHOT_STREAM_CHUNK_BYTES } from "../storage/snapshot.js";
 import { parseRpcResponse, MAX_DATABASE_RPC_IN_FLIGHT, protocolVersion, } from "../worker-protocol/index.js";
 import { toColumnarBatch } from "./batch.js";
-import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UniqueConstraintError, VisibleSegmentCursorStaleError, } from "./errors.js";
+import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError, } from "./errors.js";
 import { QueryMemoryBudgetError } from "./memory.js";
 import { decodeQueryResult } from "./result-wire.js";
 import { serializeSchema } from "./schema-wire.js";
@@ -30,6 +30,7 @@ function throwIfClientSnapshotAborted(signal) {
 const errorRegistry = new Map([
     UniqueConstraintError,
     MissingKeyError,
+    UnknownTableError,
     CompactionBacklogError,
     CompactionMemoryBudgetError,
     CompactionWriteAmplificationError,
@@ -163,12 +164,12 @@ export class MinnowDatabaseClient {
     async insert(tableName, row) {
         return (await this.#call("insert", [tableName, row]));
     }
-    async upsertBatch(tableName, input) {
+    async upsertBatch(tableName, input, options = {}) {
         const batch = toColumnarBatch(input);
-        return (await this.#call("upsertBatch", [tableName, batch]));
+        return (await this.#call("upsertBatch", [tableName, batch, options]));
     }
-    async upsert(tableName, row) {
-        return (await this.#call("upsert", [tableName, row]));
+    async upsert(tableName, row, options = {}) {
+        return (await this.#call("upsert", [tableName, row, options]));
     }
     async updateBatch(tableName, input) {
         return (await this.#call("updateBatch", [tableName, input]));

package/dist/engine/database.d.ts

@@ -1,11 +1,11 @@
 import { type BatchRow, type BatchValue, type InsertBatchInput } from "./batch.js";
 import { BufferedTableWriter, type BufferedWriterOptions } from "./buffered-writer.js";
 export { attachLifecycleFlush, BufferedTableWriter, MAX_BUFFERED_WRITER_PENDING_ADDS, type BufferedFlushResult, type BufferedWriterOptions, type LifecycleDocumentTarget, type LifecycleFlushOptions, type LifecycleFlushRequester, type LifecyclePageTarget, } from "./buffered-writer.js";
-import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UniqueConstraintError, VisibleSegmentCursorStaleError } from "./errors.js";
+import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError } from "./errors.js";
 import { type Compression } from "../block-format/index.js";
 import { type BlockStore, type ColumnDefault, CompactionBacklogError, type CompactionJobRecord, type CompactionJobState, type GarbageCollectionJobRecord, type GarbageCollectionJobState, type SimpleDataType, type SqlDomain, type StorageIntegrityMode, type StorageIntegrityReport, type StorageStats, type InterruptedSnapshotImport, type InterruptedSnapshotImportAbortResult, TableInUseError } from "../storage/types.js";
 import type { SnapshotExportProgress, SnapshotLoadProgress } from "../storage/snapshot.js";
-import { type CompiledQuery, type CompiledStatement, type ForeignKeyDefinition, type QueryResult, type QueryRow, type QueryValue, type UniqueConstraintDefinition } from "./query.js";
+import { type ComparisonOperator, type CompiledQuery, type CompiledStatement, type ForeignKeyDefinition, type QueryResult, type QueryRow, type QueryValue, type UniqueConstraintDefinition } from "./query.js";
 import { LiveQuerySet, type LiveQuerySetOptions } from "./live.js";
 import { type Catalog } from "./catalog.js";
 import { type AnyTable, type MigrationStep, type SchemaDefinition } from "./schema.js";
@@ -91,9 +91,23 @@ export interface InsertBatchResult {
      */
     generatedColumns?: Record<string, BatchValue[]>;
 }
-export interface UpsertBatchResult extends InsertBatchResult {
+export interface UpsertBatchResult extends Omit<InsertBatchResult, "segmentId"> {
+    segmentId: string | null;
+    /** Input rows considered by the statement, including conflicts rejected by `conflictWhere`. */
+    requestedRowCount: number;
     insertedRowCount: number;
     updatedRowCount: number;
+    skippedRowCount: number;
+}
+export interface UpsertConflictWhere {
+    /** Column of the existing conflicting row to test. */
+    column: string;
+    operator: ComparisonOperator;
+    value: BatchValue;
+}
+export interface UpsertOptions {
+    /** SQL `ON CONFLICT DO UPDATE ... WHERE` semantics over the existing target row. */
+    conflictWhere?: UpsertConflictWhere;
 }
 export interface UpdateBatchInput {
     /** Stable ordinary arrays; do not mutate or expose changing accessors until the write settles. */
@@ -415,7 +429,7 @@ export interface TableDefinition {
     uniqueKey?: string;
 }
 export type DatabaseRow = Record<string, Exclude<BatchValue, null> | null>;
-export { CompactionBacklogError, CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, TableInUseError, UniqueConstraintError, VisibleSegmentCursorStaleError, };
+export { CompactionBacklogError, CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UnknownTableError, TableInUseError, UniqueConstraintError, VisibleSegmentCursorStaleError, };
 export interface MinnowDatabaseOptions {
     /**
      * Block codec for newly written blocks; defaults to "gzip", which is also what compaction
@@ -722,8 +736,8 @@ export declare class MinnowDatabase {
     }): Promise<boolean>;
     insertBatch(tableName: string, input: InsertBatchInput): Promise<InsertBatchResult>;
     insert(tableName: string, row: BatchRow): Promise<InsertBatchResult>;
-    upsertBatch(tableName: string, input: InsertBatchInput): Promise<UpsertBatchResult>;
-    upsert(tableName: string, row: BatchRow): Promise<UpsertBatchResult>;
+    upsertBatch(tableName: string, input: InsertBatchInput, options?: UpsertOptions): Promise<UpsertBatchResult>;
+    upsert(tableName: string, row: BatchRow, options?: UpsertOptions): Promise<UpsertBatchResult>;
     updateBatch(tableName: string, input: UpdateBatchInput): Promise<UpdateBatchResult>;
     update(tableName: string, key: Exclude<BatchValue, null>, changes: Readonly<Record<string, BatchValue>>): Promise<UpdateBatchResult>;
     deleteBatch(tableName: string, input: DeleteBatchInput): Promise<DeleteBatchResult>;