@minnowdb/core 0.9.1 → 0.10.1

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, OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError } from "../storage/types.js";
+import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConflictError, ConnectionLostError, GarbageCollectionJobConflictError, IndexedDbSchemaUpgradeBlockedError, LeaseConflictError, LeaseExpiredError, LeaseOwnerConflictError, OpfsCoordinationError, OpfsDatabaseInUseError, OpfsUncertainOutcomeError, PostingBuildConflictError, SchemaConflictError, SnapshotImportConflictError, SnapshotManifestMissingError, StorageCorruptionError, StorageFormatVersionError, StorageResourceLimitError, TableInUseError, TableRecordConflictError, TempOwnerConflictError, TransactionRecordConflictError, UniqueIndexCoverageError, UniqueKeyBuildConflictError, UniqueKeyConflictError, UnknownOutcomeError, WriteConflictError } 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 { MAX_DATABASE_RPC_IN_FLIGHT, WORKER_DIAGNOSTIC_HANDLE_ID, isWorkerErrorReport, parseRpcResponse, MIN_WORKER_KEEPALIVE_INTERVAL_MS, WORKER_KEEPALIVE_INTERVAL_MS, protocolVersion, rehydrateError as rehydrateSerializedError } from "../worker-protocol/index.js";
 import { definedVectors, toColumnarBatch } from "./batch.js";
-import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, DatabaseReadBacklogError, TransactionExpiredError, DatabaseWorkerTimeoutError, DatabaseWorkerOutcomeUnknownError, LiveQueryLimitError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError } from "./errors.js";
+import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, DatabaseReadBacklogError, TransactionExpiredError, DatabaseWorkerTimeoutError, DatabaseWorkerFailedError, DatabaseStoreUnavailableError, 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";
@@ -23,6 +23,7 @@ function throwIfClientSnapshotAborted(signal) {
   error.name = "AbortError";
   throw error;
 }
+const MAX_KEEPALIVE_EXTENSION = 10;
 const errorRegistry = new Map([
   UniqueConstraintError,
   MissingKeyError,
@@ -36,6 +37,8 @@ const errorRegistry = new Map([
   TransactionExpiredError,
   DatabaseWorkerTimeoutError,
   DatabaseWorkerOutcomeUnknownError,
+  DatabaseWorkerFailedError,
+  DatabaseStoreUnavailableError,
   LiveQueryLimitError,
   SqlCompileError,
   QueryMemoryBudgetError,
@@ -64,31 +67,12 @@ const errorRegistry = new Map([
   StorageFormatVersionError,
   OpfsCoordinationError,
   OpfsDatabaseInUseError,
-  OpfsUncertainOutcomeError
+  OpfsUncertainOutcomeError,
+  UnknownOutcomeError,
+  ConnectionLostError
 ].map((constructor) => [constructor.name, constructor]));
 function rehydrateError(serialized) {
-  const constructor = errorRegistry.get(serialized.name);
-  const error = constructor === void 0 ? new Error(serialized.message) : Object.create(constructor.prototype);
-  Object.defineProperty(error, "message", {
-    value: serialized.message,
-    writable: true,
-    configurable: true
-  });
-  Object.defineProperty(error, "name", {
-    value: serialized.name,
-    writable: true,
-    configurable: true
-  });
-  if (serialized.stack !== void 0) {
-    Object.defineProperty(error, "stack", {
-      value: serialized.stack,
-      writable: true,
-      configurable: true
-    });
-  }
-  if (serialized.props !== void 0)
-    Object.assign(error, serialized.props);
-  return error;
+  return rehydrateSerializedError(serialized, errorRegistry);
 }
 function rehydrateResponseError(payload) {
   const candidate = payload;
@@ -103,36 +87,57 @@ class MinnowDatabaseClient {
     return this;
   }
   #transport;
+  #transportFactory;
+  #initPayload;
+  #onConnectionLost;
   #requestTimeoutMs;
   #closePromise;
   #pending = /* @__PURE__ */ new Map();
   #events = /* @__PURE__ */ new Map();
   #ready;
+  #storeKind;
   #fatal;
   #closed = false;
   #onVisibilityChange;
   #onMessage = (event) => {
     this.#receive(event.data);
   };
-  #onError = () => {
-    this.#fail(new Error("The database worker failed; see the worker's own error output"));
+  #onWorkerError;
+  #onError = (event) => {
+    const detail = event !== void 0 && "filename" in event ? event : void 0;
+    const where = detail?.filename === void 0 || detail.filename === "" ? "" : ` at ${detail.filename}:${String(detail.lineno)}:${String(detail.colno)}`;
+    const message = detail?.message === void 0 || detail.message === "" ? "" : `: ${detail.message}`;
+    const error = new DatabaseWorkerFailedError("error", `The database worker failed: it raised an error it did not handle${message}${where}`, detail?.error === void 0 ? void 0 : { cause: detail.error });
+    this.#reportWorkerError({ kind: "transport", context: "worker error event", error });
+    this.#fail(error);
   };
   #onMessageError = () => {
-    this.#fail(new Error("A database worker message could not be deserialized"));
+    const error = new DatabaseWorkerFailedError("messageerror", "A database worker message could not be deserialized");
+    this.#reportWorkerError({ kind: "transport", context: "worker messageerror event", error });
+    this.#fail(error);
   };
+  #reportWorkerError(event) {
+    if (this.#onWorkerError !== void 0) {
+      this.#onWorkerError(event);
+      return;
+    }
+    if (typeof console === "undefined")
+      return;
+    console.error(`[minnowdb] worker ${event.kind} (${event.context}):`, event.error);
+  }
   constructor(transport, options = {}) {
     this.#requestTimeoutMs = clientDeadline(options.requestTimeoutMs ?? 6e4);
     this.#schema = options.schema;
-    this.#transport = transport;
-    transport.addEventListener("message", this.#onMessage);
-    transport.addEventListener("error", this.#onError);
-    transport.addEventListener("messageerror", this.#onMessageError);
-    const payload = {
+    this.#onWorkerError = options.onWorkerError;
+    this.#onConnectionLost = options.onConnectionLost;
+    this.#transportFactory = typeof transport === "function" ? transport : void 0;
+    this.#transport = typeof transport === "function" ? transport() : transport;
+    this.#initPayload = {
       store: options.store ?? { kind: "indexeddb", name: "minnow" },
-      ...options.databaseOptions === void 0 ? {} : { options: options.databaseOptions }
+      ...options.databaseOptions === void 0 ? {} : { options: options.databaseOptions },
+      keepaliveIntervalMs: keepalivePace(this.#requestTimeoutMs)
     };
-    this.#ready = this.#post("rpc-init", null, "init", [payload]).then(() => void 0);
-    this.#ready.catch(() => void 0);
+    this.#ready = this.#attach(this.#transport);
     if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
       const report = () => {
         if (this.#closed)
@@ -146,9 +151,56 @@ class MinnowDatabaseClient {
       report();
     }
   }
+  #attach(transport) {
+    transport.addEventListener("message", this.#onMessage);
+    transport.addEventListener("error", this.#onError);
+    transport.addEventListener("messageerror", this.#onMessageError);
+    const ready = this.#post("rpc-init", null, "init", [this.#initPayload]).then((result) => {
+      const kind = result?.store;
+      this.#storeKind = kind === "indexeddb" || kind === "opfs" || kind === "memory" ? kind : void 0;
+    });
+    ready.catch(() => void 0);
+    return ready;
+  }
+  #detach(transport) {
+    transport.removeEventListener?.("message", this.#onMessage);
+    transport.removeEventListener?.("error", this.#onError);
+    transport.removeEventListener?.("messageerror", this.#onMessageError);
+  }
+  async reopen(transport) {
+    const next = transport ?? this.#transportFactory?.();
+    if (next === void 0) {
+      throw new TypeError("reopen() needs a transport: pass one, or construct the client with a transport factory");
+    }
+    const previous = this.#transport;
+    this.#detach(previous);
+    this.#transport = next;
+    if (this.#fatal === void 0) {
+      this.#fail(new DatabaseWorkerFailedError("reopened", "The database client was reopened"));
+    }
+    try {
+      previous.terminate?.();
+    } catch {
+    }
+    this.#fatal = void 0;
+    this.#closed = false;
+    this.#closePromise = void 0;
+    this.#events.clear();
+    this.#transport = next;
+    this.#ready = this.#attach(next);
+    if (this.#onVisibilityChange !== void 0 && typeof document !== "undefined") {
+      document.addEventListener("visibilitychange", this.#onVisibilityChange);
+    }
+    this.#onVisibilityChange?.();
+    await this.#ready;
+  }
   async ready() {
     return this.#ready;
   }
+  async storeKind() {
+    await this.#ready;
+    return this.#storeKind;
+  }
   async createTable(input) {
     await this.#call("createTable", [input]);
   }
@@ -223,7 +275,24 @@ class MinnowDatabaseClient {
       ...onError === void 0 ? {} : { onError }
     });
     const created = this.#call("bufferedWriter", [handleId, tableName, wireOptions]);
-    return new ClientBufferedWriter(this.#erased, handleId, created);
+    const writer = new ClientBufferedWriter(this.#erased, handleId, created);
+    if (typeof document !== "undefined" && typeof document.addEventListener === "function") {
+      const onHidden = () => {
+        if (document.visibilityState === "hidden")
+          writer.requestFlush();
+      };
+      const onPageHide = () => {
+        writer.requestFlush();
+      };
+      document.addEventListener("visibilitychange", onHidden);
+      const page = typeof window === "undefined" ? void 0 : window;
+      page?.addEventListener("pagehide", onPageHide);
+      writer._onClose(() => {
+        document.removeEventListener("visibilitychange", onHidden);
+        page?.removeEventListener("pagehide", onPageHide);
+      });
+    }
+    return writer;
   }
   async readTable(tableName, versionOrOptions) {
     return decodeQueryResult(await this.#call("readTable", versionOrOptions === void 0 ? [tableName] : [tableName, versionOrOptions])).rows;
@@ -512,7 +581,7 @@ class MinnowDatabaseClient {
     try {
       await this.#post("rpc-call", null, "dispose", [], void 0, true, { timeoutMs });
     } finally {
-      this.#fail(new Error("Database client is closed"));
+      this.#fail(new Error("Database client is closed"), true);
       this.#transport.removeEventListener?.("message", this.#onMessage);
       this.#transport.removeEventListener?.("error", this.#onError);
       this.#transport.removeEventListener?.("messageerror", this.#onMessageError);
@@ -552,8 +621,19 @@ class MinnowDatabaseClient {
     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);
+      const startedAt = Date.now();
+      const expire = () => this.#fail(new DatabaseWorkerTimeoutError(method, timeoutMs));
+      let timer = setTimeout(expire, timeoutMs);
       timer.unref?.();
+      const keepalive = () => {
+        const elapsed = Date.now() - startedAt;
+        const remaining = timeoutMs * MAX_KEEPALIVE_EXTENSION - elapsed;
+        if (remaining <= 0)
+          return;
+        clearTimeout(timer);
+        timer = setTimeout(expire, Math.min(timeoutMs, remaining));
+        timer.unref?.();
+      };
       const onAbort = () => {
         try {
           this.#transport.postMessage({ version: protocolVersion, requestId, kind: "rpc-cancel" });
@@ -580,7 +660,15 @@ class MinnowDatabaseClient {
       if (controls.onStats !== void 0) {
         this.#events.set(requestId, { onStats: controls.onStats });
       }
-      this.#pending.set(requestId, { resolve, reject, cleanup, method, requestId, mayPublish });
+      this.#pending.set(requestId, {
+        resolve,
+        reject,
+        cleanup,
+        method,
+        requestId,
+        mayPublish,
+        keepalive
+      });
       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) {
@@ -601,6 +689,20 @@ class MinnowDatabaseClient {
     if (response === null)
       return;
     if (response.kind === "rpc-event") {
+      if (response.handleId === WORKER_DIAGNOSTIC_HANDLE_ID) {
+        if (response.event === "keepalive" && typeof response.requestId === "string") {
+          this.#pending.get(response.requestId)?.keepalive?.();
+          return;
+        }
+        if (response.event === "error" && isWorkerErrorReport(response.payload)) {
+          this.#reportWorkerError({
+            kind: response.payload.kind,
+            context: response.payload.context,
+            error: rehydrateError(response.payload.error)
+          });
+        }
+        return;
+      }
       const route = this.#events.get(response.handleId);
       if (route === void 0)
         return;
@@ -651,30 +753,52 @@ class MinnowDatabaseClient {
   }
   #rejectUnreadable(message, cause) {
     const reason = cause instanceof Error ? cause.message : String(cause);
-    const error = new Error(`The database worker sent a frame this client cannot read: ${reason}`, {
-      cause
-    });
+    const text = `The database worker sent a frame this client cannot read: ${reason}`;
     const requestId = message.requestId;
     const pending = typeof requestId === "string" ? this.#pending.get(requestId) : void 0;
     if (pending === void 0 || typeof requestId !== "string") {
-      this.#fail(error);
+      this.#fail(new DatabaseWorkerFailedError("messageerror", text, { cause }));
       return;
     }
+    const error = new Error(text, { cause });
     this.#pending.delete(requestId);
     pending.cleanup?.();
     pending.reject(pending.mayPublish ? new DatabaseWorkerOutcomeUnknownError(pending.method, requestId, { cause: error }) : error);
   }
-  #fail(error) {
+  #fail(error, closing = false) {
+    const first = this.#fatal === void 0;
     this.#fatal = error;
     const pending = [...this.#pending.values()];
     this.#pending.clear();
+    const routes = [...this.#events.values()];
     this.#events.clear();
+    for (const route of routes) {
+      if (!closing) {
+        try {
+          route.onError?.(error);
+        } catch {
+        }
+      }
+      try {
+        route.onComplete?.();
+      } catch {
+      }
+    }
     for (const call of pending) {
       call.cleanup?.();
       call.reject(call.mayPublish ? new DatabaseWorkerOutcomeUnknownError(call.method, call.requestId, { cause: error }) : error);
     }
+    if (first && error instanceof ConnectionLostError && !(error instanceof DatabaseWorkerFailedError && error.reason === "reopened") && this.#onConnectionLost !== void 0) {
+      try {
+        this.#onConnectionLost(error);
+      } catch {
+      }
+    }
   }
 }
+function keepalivePace(deadlineMs) {
+  return Math.min(WORKER_KEEPALIVE_INTERVAL_MS, Math.max(MIN_WORKER_KEEPALIVE_INTERVAL_MS, Math.floor(deadlineMs / 3)));
+}
 function clientDeadline(value) {
   if (!Number.isSafeInteger(value) || value < 1 || value > 2147483647)
     throw new RangeError("Worker timeout must be a positive timer interval");
@@ -695,6 +819,10 @@ class ClientBufferedWriter {
     created.catch(() => void 0);
   }
   #created;
+  #onClose;
+  _onClose(cleanup) {
+    this.#onClose = cleanup;
+  }
   async add(row) {
     await this.#created;
     return await this.client._invoke(this.handleId, "add", [row]);
@@ -720,6 +848,8 @@ class ClientBufferedWriter {
       return await this.client._invoke(this.handleId, "close", []);
     } finally {
       this.client._unrouteEvents(this.handleId);
+      this.#onClose?.();
+      this.#onClose = void 0;
     }
   }
 }

package/dist/engine/database.d.ts

@@ -4,7 +4,7 @@ export { attachLifecycleFlush, BufferedTableWriter, MAX_BUFFERED_WRITER_PENDING_
 import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError } from "./errors.js";
 export { DatabaseReadBacklogError } from "./errors.js";
 import { type Compression } from "../block-format/index.js";
-import { type BlockStore, type ColumnDefault, type ColumnGenerated, 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 BlockStore, type ColumnDefault, type ColumnGenerated, CompactionBacklogError, type CompactionJobRecord, type CompactionJobState, type GarbageCollectionJobRecord, type GarbageCollectionJobState, type SimpleDataType, type SqlDomain, type StorageIntegrityMode, type StorageIntegrityReport, type StorageStats, type InterruptedSnapshotImport, type InterruptedSnapshotImportAbortResult, type TableColumnRecord, type TableRecord, TableInUseError } from "../storage/types.js";
 import type { SnapshotExportProgress, SnapshotLoadProgress } from "../storage/snapshot.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";
@@ -476,6 +476,13 @@ export interface MinnowDatabaseOptions<TSchema extends AnySchema = UntypedSchema
     coordinateWrites?: boolean;
     now?: () => Date;
     createId?: () => string;
+    /**
+     * Hears failures in work no caller awaits: a background collection pass that failed, a live
+     * sweep that failed with nobody subscribed. `maintenanceStatus().lastError` still records the
+     * last one; this hook sees every one, as it happens. Inside the worker host it feeds the
+     * client's `onWorkerError`.
+     */
+    onBackgroundError?: (error: unknown, context: string) => void;
     /** Durable spill-owner lease lifetime; renewed while a spilling query runs. */
     spillOwnerLeaseMs?: number;
     /** Durable active-writer deadline; renewed every third while the writer is live. */
@@ -657,6 +664,13 @@ export interface RunStatementOptions {
  */
 export interface StatementWriter extends WriteSession {
     queryPlan(plan: CompiledQuery): Promise<QueryResult>;
+    /**
+     * Which of the given keys the scope sees as present — staged by it and not removed, or
+     * committed — as key tokens, answered from the scope's key ledger and a keyed probe so a plain
+     * INSERT or an `ON CONFLICT DO NOTHING` never has to stage its buffered predecessors just to
+     * find a duplicate. Undefined when the writer cannot answer without a read.
+     */
+    stagedKeyPresence?(table: TableRecord, keyColumn: TableColumnRecord, keys: ReadonlyArray<Exclude<BatchValue, null>>): Promise<ReadonlySet<string> | undefined>;
 }
 export interface VisibleSegment {
     id: string;