@minnowdb/core 0.8.0 → 0.9.1

package/dist/engine/artifact-cache.js

@@ -52,11 +52,12 @@ class ArtifactCache {
     return entry.payload;
   }
   put(key, payload, bytes) {
-    if (!this.enabled || bytes > this.#limitBytes)
-      return;
     if (!Number.isSafeInteger(bytes) || bytes < 0) {
       throw new RangeError("Artifact cache entry bytes must be a non-negative whole number");
     }
+    bytes += 96 + key.length * 2;
+    if (!this.enabled || !Number.isSafeInteger(bytes) || bytes > this.#limitBytes)
+      return;
     const existing = this.#entries.get(key);
     if (existing !== void 0) {
       this.#usedBytes -= existing.bytes;

package/dist/engine/buffered-writer.js

@@ -47,6 +47,16 @@ class BufferedTableWriter {
     });
   }
   async flush() {
+    const adds = this.#addTail;
+    await adds;
+    let result;
+    if (this.#inFlight !== void 0)
+      result = await this.#inFlight;
+    if (this.#rows.length > 0)
+      result = await this.#flushBatch();
+    return result;
+  }
+  async #flushBatch() {
     if (this.#inFlight !== void 0)
       return this.#inFlight;
     if (this.#rows.length === 0)
@@ -102,7 +112,7 @@ class BufferedTableWriter {
       if (this.#inFlight !== void 0)
         await this.#inFlight;
       else
-        await this.flush();
+        await this.#flushBatch();
     }
   }
   async #addSerial(row) {
@@ -115,7 +125,7 @@ class BufferedTableWriter {
     }
     if (this.#inFlight !== void 0)
       await this.#inFlight;
-    return this.flush();
+    return this.#flushBatch();
   }
   #scheduleAgeFlush() {
     if (this.#timer !== void 0 || this.#rows.length === 0 || this.#closed)

package/dist/engine/client.d.ts

@@ -1,4 +1,4 @@
-import { type LiveQueryPatchOptions } from "./live-patch.js";
+import { type LiveQueryPatch, type LiveQueryPatchOptions } from "./live-patch.js";
 import { type CompactionJobRecord, type GarbageCollectionJobRecord, type StorageIntegrityMode, type StorageIntegrityReport, type StorageStats, type InterruptedSnapshotImport, type InterruptedSnapshotImportAbortResult } from "../storage/types.js";
 import { type BatchRow } from "./batch.js";
 import type { Catalog } from "./catalog.js";
@@ -47,6 +47,8 @@ export interface MinnowDatabaseClientOptions<TSchema extends AnySchema = Untyped
     store?: StoreDescriptor;
     /** Cloneable database options applied when the worker constructs the database. */
     databaseOptions?: WireDatabaseOptions;
+    /** Maximum response wait, including initialization; defaults to 60 seconds. */
+    requestTimeoutMs?: number;
 }
 export interface ClientLiveQueryOptions {
     /** BroadcastChannel name the worker uses to exchange cross-tab commit hints. */
@@ -56,6 +58,8 @@ export interface ClientLiveQueryOptions {
 export interface CloseClientOptions {
     /** Also terminate the worker after disposing; only meaningful when the transport can. */
     terminateWorker?: boolean;
+    /** Grace allowed for disposal before closing the transport; defaults to 5 seconds. */
+    timeoutMs?: number;
 }
 export interface ClientMigrationResult {
     createdTables: string[];
@@ -67,6 +71,7 @@ export interface ClientMigrationResult {
 }
 interface EventRoute {
     onChange?: (result: QueryResult, delivery: LiveQueryDelivery) => void;
+    onPatch?: (patch: LiveQueryPatch, delivery: LiveQueryDelivery) => void;
     onInvalidate?: (invalidation: LiveQueryInvalidation) => void;
     onError?: (error: unknown) => void;
     onComplete?: () => void;
@@ -75,6 +80,7 @@ interface EventRoute {
     onStats?: (stats: QueryExecutionStats) => void;
 }
 interface RpcCallControls {
+    timeoutMs?: number;
     signal?: AbortSignal | undefined;
     onStats?: ((stats: QueryExecutionStats) => void) | undefined;
 }
@@ -265,7 +271,7 @@ export declare class ClientLiveQuerySet {
     constructor(client: MinnowDatabaseClient, handleId: string, created: Promise<unknown>);
     /** Registers a query (SQL or a compiled-plan envelope) and re-runs it on relevant changes. */
     subscribe(query: LiveQueryInput, options: LiveQuerySubscribeOptions): Promise<ClientLiveSubscription>;
-    /** Delivers changed row payloads; the worker transport still sends its result snapshot. */
+    /** Transfers resets followed by changed row payloads and retained positions across the worker. */
     subscribePatches(query: LiveQueryInput, options: LiveQueryPatchOptions): Promise<ClientLiveSubscription>;
     /** Registers dependency observation while leaving execution/result mapping to an adapter. */
     observe(query: LiveQueryInput, options: LiveQueryObserveOptions): Promise<ClientLiveSubscription>;

package/dist/engine/client.js

@@ -1,9 +1,9 @@
 import { createLiveQueryPatch } from "./live-patch.js";
-import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, PostingBuildConflictError, SnapshotManifestMissingError, SnapshotImportConflictError, SchemaConflictError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyBuildConflictError, UniqueKeyConflictError, UniqueIndexCoverageError, WriteConflictError, StorageCorruptionError, StorageFormatVersionError, OpfsUncertainOutcomeError } from "../storage/types.js";
+import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, PostingBuildConflictError, SnapshotManifestMissingError, SnapshotImportConflictError, SchemaConflictError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueKeyBuildConflictError, UniqueKeyConflictError, UniqueIndexCoverageError, WriteConflictError, StorageCorruptionError, StorageFormatVersionError, OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError } from "../storage/types.js";
 import { MAX_SNAPSHOT_STREAM_CHUNK_BYTES } from "../storage/snapshot.js";
 import { parseRpcResponse, MAX_DATABASE_RPC_IN_FLIGHT, protocolVersion } from "../worker-protocol/index.js";
 import { definedVectors, toColumnarBatch } from "./batch.js";
-import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, DatabaseReadBacklogError, LiveQueryLimitError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError } from "./errors.js";
+import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, DatabaseReadBacklogError, TransactionExpiredError, DatabaseWorkerTimeoutError, DatabaseWorkerOutcomeUnknownError, LiveQueryLimitError, 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";
@@ -33,6 +33,9 @@ const errorRegistry = new Map([
   CompactionJobCancelledError,
   MaintenanceBacklogError,
   DatabaseReadBacklogError,
+  TransactionExpiredError,
+  DatabaseWorkerTimeoutError,
+  DatabaseWorkerOutcomeUnknownError,
   LiveQueryLimitError,
   SqlCompileError,
   QueryMemoryBudgetError,
@@ -59,6 +62,8 @@ const errorRegistry = new Map([
   PostingBuildConflictError,
   StorageCorruptionError,
   StorageFormatVersionError,
+  OpfsCoordinationError,
+  OpfsDatabaseInUseError,
   OpfsUncertainOutcomeError
 ].map((constructor) => [constructor.name, constructor]));
 function rehydrateError(serialized) {
@@ -98,6 +103,8 @@ class MinnowDatabaseClient {
     return this;
   }
   #transport;
+  #requestTimeoutMs;
+  #closePromise;
   #pending = /* @__PURE__ */ new Map();
   #events = /* @__PURE__ */ new Map();
   #ready;
@@ -114,6 +121,7 @@ class MinnowDatabaseClient {
     this.#fail(new Error("A database worker message could not be deserialized"));
   };
   constructor(transport, options = {}) {
+    this.#requestTimeoutMs = clientDeadline(options.requestTimeoutMs ?? 6e4);
     this.#schema = options.schema;
     this.#transport = transport;
     transport.addEventListener("message", this.#onMessage);
@@ -289,10 +297,10 @@ class MinnowDatabaseClient {
     try {
       const session = {
         version: opened.version,
-        query: (sql, options = {}) => this.query(sql, {
-          ...options,
-          ...opened.version === null ? {} : { version: opened.version }
-        })
+        query: async (sql, options = {}) => {
+          const { signal, onStats, ...wireOptions } = options;
+          return decodeQueryResult(await this._invokeControlled(opened.handleId, "query", [sql, wireOptions, onStats !== void 0], { signal, onStats }));
+        }
       };
       return await action(session);
     } finally {
@@ -301,18 +309,33 @@ class MinnowDatabaseClient {
   }
   async write(action) {
     const opened = await this.#call("writeOpen", []);
-    const stage = (op, tableName, input, options) => this._invoke(opened.handleId, "stage", [
+    let tail = Promise.resolve();
+    let accepting = true;
+    let pending = 0;
+    const enqueue = (run) => {
+      if (!accepting)
+        return Promise.reject(new Error("The write scope has ended"));
+      if (pending >= MAX_DATABASE_RPC_IN_FLIGHT)
+        return Promise.reject(new RangeError("Too many pending write scope calls; await a statement"));
+      pending += 1;
+      const task = tail.then(run);
+      tail = task.then(() => void 0, () => void 0);
+      return task.finally(() => {
+        pending -= 1;
+      });
+    };
+    const stage = (op, tableName, input, options) => enqueue(() => this._invoke(opened.handleId, "stage", [
       op,
       tableName,
       input,
       options
-    ]);
+    ]));
     const session = {
-      query: async (sql, options = {}) => {
+      query: (sql, options = {}) => enqueue(async () => {
         const { signal, onStats, ...wireOptions } = options;
         return decodeQueryResult(await this._invokeControlled(opened.handleId, "query", [sql, wireOptions, onStats !== void 0], { signal, onStats }));
-      },
-      execute: (sql, params) => this._invoke(opened.handleId, "execute", params === void 0 ? [sql] : [sql, params]),
+      }),
+      execute: (sql, params) => enqueue(() => this._invoke(opened.handleId, "execute", params === void 0 ? [sql] : [sql, params])),
       insertBatch: (tableName, input) => stage("insertBatch", tableName, input),
       upsertBatch: (tableName, input, options) => stage("upsertBatch", tableName, input, options),
       updateBatch: (tableName, input) => stage("updateBatch", tableName, input),
@@ -320,9 +343,13 @@ class MinnowDatabaseClient {
     };
     try {
       const result = await action(session);
+      accepting = false;
+      await tail;
       const committed = await this._invoke(opened.handleId, "commit", []);
       return { result, version: committed.version };
     } catch (error) {
+      accepting = false;
+      await tail;
       await this._invoke(opened.handleId, "abort", []).catch(() => void 0);
       throw error;
     }
@@ -470,17 +497,22 @@ class MinnowDatabaseClient {
   async listGarbageCollectionJobs() {
     return await this.#call("listGarbageCollectionJobs", []);
   }
-  async close(options = {}) {
-    if (this.#closed)
-      return;
+  close(options = {}) {
+    if (this.#closePromise !== void 0)
+      return this.#closePromise;
+    const timeoutMs = clientDeadline(options.timeoutMs ?? 5e3);
     this.#closed = true;
+    this.#closePromise = this.#closeTransport(options, timeoutMs);
+    return this.#closePromise;
+  }
+  async #closeTransport(options, timeoutMs) {
     if (this.#onVisibilityChange !== void 0 && typeof document !== "undefined") {
       document.removeEventListener("visibilitychange", this.#onVisibilityChange);
     }
     try {
-      await this.#post("rpc-call", null, "dispose", []);
+      await this.#post("rpc-call", null, "dispose", [], void 0, true, { timeoutMs });
     } finally {
-      this.#events.clear();
+      this.#fail(new Error("Database client is closed"));
       this.#transport.removeEventListener?.("message", this.#onMessage);
       this.#transport.removeEventListener?.("error", this.#onError);
       this.#transport.removeEventListener?.("messageerror", this.#onMessageError);
@@ -517,14 +549,29 @@ class MinnowDatabaseClient {
       throw new RangeError(`A database worker connection cannot hold more than ${String(MAX_DATABASE_RPC_IN_FLIGHT)} in-flight requests`);
     }
     const requestId = crypto.randomUUID();
+    const timeoutMs = controls.timeoutMs ?? this.#requestTimeoutMs;
+    const mayPublish = rpcMayPublish(method, args);
     return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => this.#fail(new DatabaseWorkerTimeoutError(method, timeoutMs)), timeoutMs);
+      timer.unref?.();
       const onAbort = () => {
         try {
           this.#transport.postMessage({ version: protocolVersion, requestId, kind: "rpc-cancel" });
         } catch {
         }
+        const call = this.#pending.get(requestId);
+        if (call === void 0)
+          return;
+        this.#pending.delete(requestId);
+        call.cleanup?.();
+        const error = new Error("Database request was cancelled", {
+          cause: controls.signal?.reason
+        });
+        error.name = "AbortError";
+        call.reject(mayPublish ? new DatabaseWorkerOutcomeUnknownError(method, requestId, { cause: error }) : error);
       };
       const cleanup = () => {
+        clearTimeout(timer);
         controls.signal?.removeEventListener("abort", onAbort);
         if (controls.onStats !== void 0)
           this.#events.delete(requestId);
@@ -533,7 +580,7 @@ class MinnowDatabaseClient {
       if (controls.onStats !== void 0) {
         this.#events.set(requestId, { onStats: controls.onStats });
       }
-      this.#pending.set(requestId, { resolve, reject, cleanup });
+      this.#pending.set(requestId, { resolve, reject, cleanup, method, requestId, mayPublish });
       try {
         this.#transport.postMessage(kind === "rpc-init" ? { version: protocolVersion, requestId, kind, payload: args[0] } : { version: protocolVersion, requestId, kind, handleId, method, args }, transfer === void 0 ? void 0 : { transfer });
       } catch (error) {
@@ -560,6 +607,24 @@ class MinnowDatabaseClient {
       if (response.event === "change") {
         const { result, delivery } = response.payload;
         route.onChange?.(decodeQueryResult(result), delivery);
+      } else if (response.event === "patch") {
+        const { result: payload, delivery } = response.payload;
+        const result = decodeQueryResult(payload);
+        const retained = delivery.retained;
+        if (!(retained instanceof Int32Array))
+          throw new TypeError("Live patch is missing retained positions");
+        const changedRows = [];
+        for (let index = 0; index < retained.length; index += 1) {
+          if ((retained[index] ?? -1) >= 0)
+            continue;
+          const row = result.rows[changedRows.length];
+          if (row === void 0)
+            throw new TypeError("Live patch is missing a changed row");
+          changedRows.push({ index, row });
+        }
+        if (changedRows.length !== result.rows.length)
+          throw new TypeError("Live patch has excess rows");
+        route.onPatch?.({ type: "patch", retained, changedRows }, delivery);
       } else if (response.event === "invalidate") {
         route.onInvalidate?.(response.payload);
       } else if (response.event === "error") {
@@ -597,7 +662,7 @@ class MinnowDatabaseClient {
     }
     this.#pending.delete(requestId);
     pending.cleanup?.();
-    pending.reject(error);
+    pending.reject(pending.mayPublish ? new DatabaseWorkerOutcomeUnknownError(pending.method, requestId, { cause: error }) : error);
   }
   #fail(error) {
     this.#fatal = error;
@@ -606,10 +671,20 @@ class MinnowDatabaseClient {
     this.#events.clear();
     for (const call of pending) {
       call.cleanup?.();
-      call.reject(error);
+      call.reject(call.mayPublish ? new DatabaseWorkerOutcomeUnknownError(call.method, call.requestId, { cause: error }) : error);
     }
   }
 }
+function clientDeadline(value) {
+  if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647)
+    throw new RangeError("Worker timeout must be a positive timer interval");
+  return value;
+}
+function rpcMayPublish(method, args) {
+  if (method === "execute" && typeof args[0] === "string" && /^\s*SELECT\b/iu.test(args[0]))
+    return false;
+  return /^(?:insert|upsert|update|delete|create|drop|migrate|commit|flush|execute|runStatement|import|finish|add|close|dispose)/u.test(method);
+}
 class ClientBufferedWriter {
   client;
   handleId;
@@ -660,11 +735,17 @@ class ClientLiveQuerySet {
   }
   #created;
   async subscribe(query, options) {
+    return this.#subscribe(query, options);
+  }
+  async #subscribe(query, options, onPatch) {
+    if (typeof query !== "string")
+      query = structuredClone(query);
     await this.#created;
     const subscriptionId = crypto.randomUUID();
     const state = { completed: false };
     this.client._routeEvents(subscriptionId, {
       onChange: options.onChange.bind(options),
+      ...onPatch === void 0 ? {} : { onPatch },
       ...options.onError === void 0 ? {} : { onError: options.onError.bind(options) },
       onComplete: () => {
         state.completed = true;
@@ -675,7 +756,8 @@ class ClientLiveQuerySet {
     try {
       const created = await this.client._invoke(this.handleId, "subscribe", [
         subscriptionId,
-        query
+        query,
+        ...onPatch === void 0 ? [] : [{ patches: true }]
       ]);
       this.#subscriptionIds.add(subscriptionId);
       return new ClientLiveSubscription(this.client, subscriptionId, created.dependencyTableIds, () => this.#subscriptionIds.delete(subscriptionId), state);
@@ -685,13 +767,15 @@ class ClientLiveQuerySet {
     }
   }
   subscribePatches(query, options) {
-    return this.subscribe(query, {
+    return this.#subscribe(query, {
       onChange: (result, delivery) => options.onPatch(createLiveQueryPatch(result, delivery), delivery),
       ...options.onError === void 0 ? {} : { onError: options.onError.bind(options) },
       ...options.onComplete === void 0 ? {} : { onComplete: options.onComplete.bind(options) }
-    });
+    }, options.onPatch.bind(options));
   }
   async observe(query, options) {
+    if (typeof query !== "string")
+      query = structuredClone(query);
     await this.#created;
     const subscriptionId = crypto.randomUUID();
     const state = { completed: false };

package/dist/engine/database.d.ts

@@ -257,7 +257,7 @@ export interface QueryOptions {
      * data with the default on measures cache lookups, not query execution.
      */
     memoize?: boolean;
-    readonly version?: number;
+    readonly version?: number | null;
     /**
      * Values for the statement's `?`/`$n` placeholders, in order. Required exactly when the
      * statement has placeholders; the compiled plan is cached on the SQL text and re-bound per
@@ -472,6 +472,8 @@ export interface MinnowDatabaseOptions<TSchema extends AnySchema = UntypedSchema
     targetBlockBytes?: number;
     rowsPerBlock?: number;
     maxCommitRetries?: number;
+    /** Coordinate autocommit writers across instances and, with Web Locks, tabs. Default true. */
+    coordinateWrites?: boolean;
     now?: () => Date;
     createId?: () => string;
     /** Durable spill-owner lease lifetime; renewed while a spilling query runs. */
@@ -812,8 +814,8 @@ export declare class MinnowDatabase<TSchema extends AnySchema = UntypedSchema> {
      * Creates a live-query set over this database. Local commits hint it directly, an optional
      * channel carries cross-tab hints, and an optional poll interval bounds staleness without any
      * hint; every hint path converges on the durable manifest version, so missed messages delay a
-     * refresh but never produce a stale result. Equal subscriptions retain one private exact
-     * result snapshot plus a digest that rejects most inequality before exact comparison.
+     * refresh but never produce a stale result. Equal subscriptions retain one private result
+     * snapshot, compared exactly before delivery.
      */
     liveQueries(options?: LiveQuerySetOptions): LiveQuerySet;
     /**