@minnowdb/core 0.9.0 → 0.10.0

package/dist/engine/auto-store.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The `{ kind: "auto" }` store: OPFS where this context can hold synchronous access handles,
+ * IndexedDB where it cannot (Safari's private browsing, a page context, an older build).
+ *
+ * The choice is made once per database name and remembered in a small IndexedDB record, so a
+ * database created on one store is never silently reopened, empty, on the other: a remembered
+ * store that cannot open now is reported as `DatabaseStoreUnavailableError` instead. Delete the
+ * record with `forgetStoreChoice` when the database itself is deleted.
+ */
+export type AutoStoreKind = "opfs" | "indexeddb";
+/** Test seams: the OPFS probe and the IndexedDB factory that keeps the choices. */
+export declare const autoStoreTestHooks: {
+    opfsAvailable?: () => Promise<boolean>;
+    indexedDB?: IDBFactory;
+};
+/**
+ * Whether OPFS is usable here: the directory handle resolves, and file handles expose
+ * synchronous access — which only a dedicated worker has, and Safari's private browsing never.
+ */
+export declare function opfsAvailable(): Promise<boolean>;
+/**
+ * Resolves `auto` for one database name: the remembered store, or the best one available.
+ * A fresh choice is reserved with an insert-only write, so two workers deciding at the same
+ * instant in contexts that disagree still end up on the one store the record names; the
+ * caller reports through `settleAutoStoreChoice` whether that reservation produced a database.
+ */
+export declare function resolveAutoStoreKind(name: string): Promise<{
+    kind: AutoStoreKind;
+    reserved: boolean;
+}>;
+/**
+ * Opens the store `auto` resolves to. A reservation that produced no database is released
+ * again, so a first open that failed does not pin the name to a store that never held data.
+ */
+export declare function openAutoStore<Store>(name: string, open: (kind: AutoStoreKind) => Promise<Store>): Promise<{
+    store: Store;
+    kind: AutoStoreKind;
+}>;
+/** Forgets which store `auto` chose for a database; call it when deleting the database. */
+export declare function forgetStoreChoice(name: string): Promise<void>;

package/dist/engine/auto-store.js

@@ -0,0 +1,115 @@
+import { DatabaseStoreUnavailableError } from "./errors.js";
+const CHOICE_DATABASE = "minnowdb-store-choice";
+const CHOICE_STORE = "choices";
+const autoStoreTestHooks = {};
+async function opfsAvailable() {
+  if (autoStoreTestHooks.opfsAvailable !== void 0)
+    return autoStoreTestHooks.opfsAvailable();
+  const storage = globalThis.navigator?.storage;
+  if (typeof storage?.getDirectory !== "function")
+    return false;
+  const fileHandle = globalThis.FileSystemFileHandle;
+  if (fileHandle?.prototype === void 0 || typeof fileHandle.prototype.createSyncAccessHandle !== "function") {
+    return false;
+  }
+  try {
+    await storage.getDirectory();
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveAutoStoreKind(name) {
+  const remembered = await readChoice(name);
+  if (remembered === "indexeddb")
+    return { kind: "indexeddb", reserved: false };
+  if (remembered === "opfs") {
+    if (await opfsAvailable())
+      return { kind: "opfs", reserved: false };
+    throw new DatabaseStoreUnavailableError("opfs", name, `Database "${name}" lives on the OPFS store, which this context cannot open; it is not reopened on IndexedDB, where it would be empty`);
+  }
+  const kind = await opfsAvailable() ? "opfs" : "indexeddb";
+  const reserved = await reserveChoice(name, kind);
+  if (reserved)
+    return { kind, reserved: true };
+  return resolveAutoStoreKind(name);
+}
+async function openAutoStore(name, open) {
+  const { kind, reserved } = await resolveAutoStoreKind(name);
+  try {
+    return { store: await open(kind), kind };
+  } catch (error) {
+    if (reserved)
+      await forgetStoreChoice(name).catch(() => void 0);
+    throw error;
+  }
+}
+async function forgetStoreChoice(name) {
+  const database = await openChoices();
+  if (database === void 0)
+    return;
+  try {
+    await complete(database.transaction(CHOICE_STORE, "readwrite").objectStore(CHOICE_STORE).delete(name));
+  } finally {
+    database.close();
+  }
+}
+function choiceFactory() {
+  return autoStoreTestHooks.indexedDB ?? globalThis.indexedDB ?? void 0;
+}
+async function openChoices() {
+  const factory = choiceFactory();
+  if (factory === void 0)
+    return void 0;
+  const request = factory.open(CHOICE_DATABASE, 1);
+  request.addEventListener("upgradeneeded", () => {
+    if (!request.result.objectStoreNames.contains(CHOICE_STORE)) {
+      request.result.createObjectStore(CHOICE_STORE);
+    }
+  });
+  try {
+    return await complete(request);
+  } catch {
+    return void 0;
+  }
+}
+async function readChoice(name) {
+  const database = await openChoices();
+  if (database === void 0)
+    return void 0;
+  try {
+    const value = await complete(database.transaction(CHOICE_STORE, "readonly").objectStore(CHOICE_STORE).get(name));
+    const kind = typeof value === "object" && value !== null ? value.kind : void 0;
+    return kind === "opfs" || kind === "indexeddb" ? kind : void 0;
+  } finally {
+    database.close();
+  }
+}
+async function reserveChoice(name, kind) {
+  const database = await openChoices();
+  if (database === void 0)
+    return true;
+  try {
+    await complete(database.transaction(CHOICE_STORE, "readwrite").objectStore(CHOICE_STORE).add({ kind }, name));
+    return true;
+  } catch (error) {
+    if (error instanceof Error && error.name === "ConstraintError")
+      return false;
+    throw error;
+  } finally {
+    database.close();
+  }
+}
+function complete(request) {
+  return new Promise((resolve, reject) => {
+    request.addEventListener("success", () => resolve(request.result));
+    request.addEventListener("error", () => reject(request.error ?? new Error("IndexedDB request failed")));
+  });
+}
+export {
+  autoStoreTestHooks,
+  forgetStoreChoice,
+  openAutoStore,
+  opfsAvailable,
+  resolveAutoStoreKind
+};

package/dist/engine/buffered-writer.d.ts

@@ -6,6 +6,8 @@ export interface BufferedWriterOptions {
     maxBytes?: number;
     maxAgeMs?: number;
     onError?: (error: unknown) => void;
+    /** @internal The database's background-error hook, heard when no `onError` is given. */
+    onBackgroundError?: (error: unknown, context: string) => void;
 }
 export type BufferedFlushResult = InsertBatchResult | UpsertBatchResult;
 export interface LifecycleFlushRequester {

package/dist/engine/buffered-writer.js

@@ -9,6 +9,7 @@ class BufferedTableWriter {
   #maxBytes;
   #maxAgeMs;
   #onError;
+  #onBackgroundError;
   #rows = [];
   #estimatedBytes = 0;
   #timer;
@@ -25,6 +26,7 @@ class BufferedTableWriter {
     this.#maxBytes = positiveWholeNumber(options.maxBytes ?? 1024 * 1024, "Buffered byte limit");
     this.#maxAgeMs = positiveWholeNumber(options.maxAgeMs ?? 1e3, "Buffered age limit");
     this.#onError = options.onError;
+    this.#onBackgroundError = options.onBackgroundError;
   }
   get pendingRowCount() {
     return this.#rows.length;
@@ -79,7 +81,16 @@ class BufferedTableWriter {
   requestFlush() {
     if (this.#closed)
       return;
-    void this.#flushPending().catch((error) => this.#onError?.(error));
+    void this.#flushPending().catch((error) => {
+      this.#reportFlushError(error);
+    });
+  }
+  #reportFlushError(error) {
+    if (this.#onError !== void 0) {
+      this.#onError(error);
+      return;
+    }
+    this.#onBackgroundError?.(error, `buffered writer flush for ${this.tableName}`);
   }
   async close() {
     if (this.#closed)
@@ -132,7 +143,9 @@ class BufferedTableWriter {
       return;
     this.#timer = setTimeout(() => {
       this.#timer = void 0;
-      void this.#flushPending().catch((error) => this.#onError?.(error));
+      void this.#flushPending().catch((error) => {
+        this.#reportFlushError(error);
+      });
     }, this.#maxAgeMs);
   }
   #clearTimer() {

package/dist/engine/client.d.ts

@@ -1,5 +1,6 @@
 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 CompactionJobRecord, ConnectionLostError, type GarbageCollectionJobRecord, type InterruptedSnapshotImport, type InterruptedSnapshotImportAbortResult, type StorageIntegrityMode, type StorageIntegrityReport, type StorageStats } from "../storage/types.js";
+import { type WorkerErrorKind } from "../worker-protocol/index.js";
 import { type BatchRow } from "./batch.js";
 import type { Catalog } from "./catalog.js";
 import type { BufferPoolStats, StagedWriteResult, StagedUpsertResult, BufferedFlushResult, BufferedWriterOptions, CancelCompactionJobResult, CollectGarbageOptions, CollectGarbageStepOptions, CompactTableOptions, CompactTableResult, CompactTableStepOptions, CompactionJobProgress, CreateTableInput, MigrateOptions, DeleteBatchResult, ExecuteOptions, ExecuteResult, GarbageCollectionProgress, GarbageCollectionResult, MaintenanceStatus, InsertBatchResult, QueryOptions, QueryExecutionStats, QueryCursorOptions, QuerySpillCleanupOptions, QuerySpillCleanupResult, RunStatementOptions, SnapshotExportOptions, SnapshotImportOptions, TableDefinition, UpdateBatchResult, UpsertBatchResult, VisibleSegmentPage, VisibleSegmentPageOptions } from "./database.js";
@@ -7,7 +8,7 @@ import type { LiveQueryDelivery, LiveQueryInput, LiveQueryInvalidation, LiveQuer
 import type { CompiledQuery, CompiledStatement, QueryResult, QueryValue } from "./query.js";
 import type { AnySchema, UntypedSchema, AnyTable, BatchColumnName, BatchDeleteInput, BatchInsertInput, BatchInsertRow, BatchKeyValue, BatchReadOptions, BatchReadRow, BatchUpdateChanges, BatchUpdateInput, BatchUpsertOptions, SchemaDefinition, TableName } from "./schema.js";
 import { type WireMigrationStep } from "./schema-wire.js";
-import type { StoreDescriptor, WireDatabaseOptions } from "./worker-host.js";
+import type { OpenedStoreKind, StoreDescriptor, WireDatabaseOptions } from "./worker-host.js";
 /**
  * Main-thread async proxy of the full database API, talking to a worker that runs
  * `@minnowdb/core/worker` (or a custom entry built on
@@ -27,9 +28,14 @@ export interface ClientTransport {
         transfer: ArrayBuffer[];
     }): void;
     addEventListener(type: "message", listener: (event: MessageEvent<unknown>) => void): void;
-    addEventListener(type: "error" | "messageerror", listener: () => void): void;
+    /**
+     * The client's listeners accept the Worker's own `ErrorEvent` and `MessageEvent`, and read
+     * the message, file, and line off an error event when they are there. A transport that has
+     * no such events to give may invoke them with no argument.
+     */
+    addEventListener(type: "error" | "messageerror", listener: (event?: ErrorEvent | MessageEvent<unknown>) => void): void;
     removeEventListener?(type: "message", listener: (event: MessageEvent<unknown>) => void): void;
-    removeEventListener?(type: "error" | "messageerror", listener: () => void): void;
+    removeEventListener?(type: "error" | "messageerror", listener: (event?: ErrorEvent | MessageEvent<unknown>) => void): void;
     terminate?(): void;
 }
 export interface MinnowDatabaseClientOptions<TSchema extends AnySchema = UntypedSchema> {
@@ -47,8 +53,35 @@ 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. */
+    /**
+     * How long a call may go without a word from the worker before the connection is declared
+     * dead; defaults to 60 seconds and also covers initialization. The worker reports every few
+     * seconds while it works on a call, so a large batch write is bounded by progress, not by wall
+     * time — up to ten times this value in all.
+     */
     requestTimeoutMs?: number;
+    /**
+     * Hears every failure inside the worker that belongs to no call: uncaught exceptions,
+     * unhandled rejections, failed background maintenance, and multi-tab coordination errors,
+     * plus the transport's own error events. Without a handler each one is written to
+     * `console.error`, so nothing that goes wrong in the worker stays in the worker.
+     */
+    onWorkerError?: (event: DatabaseWorkerErrorEvent) => void;
+    /**
+     * Called once when the connection is lost — the worker raised an unhandled error, sent an
+     * unreadable frame, or fell silent past `requestTimeoutMs`. Every later call on this client
+     * fails the same way until `reopen()`; use this hook to reopen and rebuild handles.
+     */
+    onConnectionLost?: (error: ConnectionLostError) => void;
+}
+/** A worker failure that belongs to no call, delivered to `onWorkerError`. */
+export interface DatabaseWorkerErrorEvent {
+    /** `"transport"` is the Worker object's own error or messageerror event. */
+    kind: WorkerErrorKind | "transport";
+    /** Where in the worker it happened: "opfs election", "auto collection", a file and line. */
+    context: string;
+    /** Rehydrated like a call failure: `instanceof` works, the stack is the worker's. */
+    error: Error;
 }
 export interface ClientLiveQueryOptions {
     /** BroadcastChannel name the worker uses to exchange cross-tab commit hints. */
@@ -86,9 +119,23 @@ interface RpcCallControls {
 }
 export declare class MinnowDatabaseClient<TSchema extends AnySchema = UntypedSchema> {
     #private;
-    constructor(transport: ClientTransport, options?: MinnowDatabaseClientOptions<TSchema>);
+    constructor(transport: ClientTransport | (() => ClientTransport), options?: MinnowDatabaseClientOptions<TSchema>);
+    /**
+     * Replaces the connection after it was lost: a fresh worker, the same store and options. Pass
+     * the new transport, or construct the client with a transport factory
+     * (`new MinnowDatabaseClient(() => new Worker(...))`) and call this with no argument. The old
+     * transport is terminated when it can be. Every handle from before — write scopes, live
+     * sets, cursors, writers — belongs to the old worker and must be recreated; a pending call
+     * still in flight fails as a connection loss. Resolves once the new worker is ready.
+     */
+    reopen(transport?: ClientTransport): Promise<void>;
     /** Resolves once the worker has opened the store and constructed the database. */
     ready(): Promise<void>;
+    /**
+     * The kind of store the worker opened: what `{ kind: "auto" }` resolved to, or the kind the
+     * descriptor named. Undefined only when a custom worker entry opened a store without saying.
+     */
+    storeKind(): Promise<OpenedStoreKind | undefined>;
     createTable(input: CreateTableInput): Promise<void>;
     createView(name: string, sql: string, options?: {
         orReplace?: boolean;
@@ -252,6 +299,8 @@ export declare class ClientBufferedWriter<TRow extends BatchRow = BatchRow> {
     private readonly client;
     private readonly handleId;
     constructor(client: MinnowDatabaseClient, handleId: string, created: Promise<unknown>);
+    /** @internal Runs once when the writer closes, however it closes. */
+    _onClose(cleanup: () => void): void;
     add(row: TRow): Promise<BufferedFlushResult | undefined>;
     flush(): Promise<BufferedFlushResult | undefined>;
     /** Fire-and-forget: flush failures surface through onError, matching the in-worker contract. */

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,53 @@ 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);
+    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 +272,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;
@@ -552,8 +618,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 +657,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 +686,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;
@@ -665,6 +764,7 @@ class MinnowDatabaseClient {
     pending.reject(pending.mayPublish ? new DatabaseWorkerOutcomeUnknownError(pending.method, requestId, { cause: error }) : error);
   }
   #fail(error) {
+    const first = this.#fatal === void 0;
     this.#fatal = error;
     const pending = [...this.#pending.values()];
     this.#pending.clear();
@@ -673,8 +773,17 @@ class MinnowDatabaseClient {
       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 +804,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 +833,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;