@minnowdb/core 0.9.1 → 0.10.1

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

@@ -0,0 +1,52 @@
+/**
+ * What the composition root knows that this module must not import: whether an OPFS database
+ * directory of a name exists. The OPFS adapter provides it (`opfsDatabaseExists`); a root that
+ * cannot bundle OPFS leaves it out, and OPFS is then never chosen for an unknown name anyway.
+ */
+export interface AutoStoreProbes {
+    opfsDatabaseExists?: (name: string) => Promise<boolean>;
+}
+/**
+ * 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>;
+    /** Whether an OPFS database directory of this name exists; Node has no OPFS to ask. */
+    opfsDatabaseExists?: (name: string) => 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, probes?: AutoStoreProbes): 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 —
+ * but only when the store really holds none: another connection may have opened the same
+ * reservation successfully in the meantime, and its database must keep its memory.
+ */
+export declare function openAutoStore<Store>(name: string, open: (kind: AutoStoreKind) => Promise<Store>, probes?: AutoStoreProbes): 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,157 @@
+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, probes = {}) {
+  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 existing = await existingDatabaseStore(name, probes);
+  let kind;
+  if (existing === "opfs" && !await opfsAvailable()) {
+    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`);
+  } else if (existing !== void 0)
+    kind = existing;
+  else
+    kind = await opfsAvailable() ? "opfs" : "indexeddb";
+  const reserved = await reserveChoice(name, kind);
+  if (reserved)
+    return { kind, reserved: true };
+  return resolveAutoStoreKind(name, probes);
+}
+async function openAutoStore(name, open, probes = {}) {
+  const { kind, reserved } = await resolveAutoStoreKind(name, probes);
+  try {
+    return { store: await open(kind), kind };
+  } catch (error) {
+    if (reserved && await existingDatabaseStore(name, probes).catch(() => kind) !== kind) {
+      await forgetStoreChoice(name).catch(() => void 0);
+    }
+    throw error;
+  }
+}
+async function existingDatabaseStore(name, probes) {
+  const opfsExists = autoStoreTestHooks.opfsDatabaseExists ?? probes.opfsDatabaseExists;
+  if (opfsExists !== void 0 && await opfsExists(name))
+    return "opfs";
+  if (await indexedDbDatabaseExists(name))
+    return "indexeddb";
+  return void 0;
+}
+async function indexedDbDatabaseExists(name) {
+  const factory = choiceFactory();
+  if (factory === void 0)
+    return false;
+  const list = factory.databases;
+  if (typeof list === "function") {
+    try {
+      return (await list.call(factory)).some((entry) => entry.name === name);
+    } catch {
+    }
+  }
+  return new Promise((resolve) => {
+    const request = factory.open(name);
+    let created = false;
+    request.addEventListener("upgradeneeded", () => {
+      created = true;
+      request.transaction?.abort();
+    });
+    request.addEventListener("success", () => {
+      request.result.close();
+      resolve(!created);
+    });
+    request.addEventListener("error", () => resolve(false));
+    request.addEventListener("blocked", () => resolve(true));
+  });
+}
+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-audit-harness.js

@@ -0,0 +1,123 @@
+import { MemoryBlockStore } from "../storage/index.js";
+function createBoundary() {
+  const clientListeners = /* @__PURE__ */ new Map();
+  const workerListeners = /* @__PURE__ */ new Map();
+  let chain = Promise.resolve();
+  let severed = false;
+  const sentByClient = [];
+  const sentByWorker = [];
+  const deliver = (target, message, transfer) => {
+    const data = structuredClone(message, transfer === void 0 ? void 0 : { transfer });
+    if (severed)
+      return;
+    chain = chain.then(() => {
+      if (severed)
+        return;
+      for (const listener of target.get("message") ?? [])
+        listener({ data });
+    });
+  };
+  const add = (map, type, listener) => {
+    const list = map.get(type) ?? [];
+    list.push(listener);
+    map.set(type, list);
+  };
+  const remove = (map, type, listener) => {
+    const list = map.get(type) ?? [];
+    const index = list.indexOf(listener);
+    if (index >= 0)
+      list.splice(index, 1);
+  };
+  const clientSide = {
+    postMessage: (message, options) => {
+      sentByClient.push(structuredClone(message));
+      deliver(workerListeners, message, options?.transfer);
+    },
+    addEventListener: (type, listener) => {
+      add(clientListeners, type, listener);
+    },
+    removeEventListener: (type, listener) => {
+      remove(clientListeners, type, listener);
+    },
+    terminate: () => {
+      severed = true;
+    }
+  };
+  const workerSide = {
+    postMessage: (message, options) => {
+      sentByWorker.push(structuredClone(message));
+      deliver(clientListeners, message, options?.transfer);
+    },
+    addEventListener: (type, listener) => {
+      add(workerListeners, type, listener);
+    }
+  };
+  return {
+    sentByClient,
+    sentByWorker,
+    clientSide,
+    workerSide,
+    sever: () => {
+      severed = true;
+    },
+    injectToClient: (frame) => {
+      for (const listener of clientListeners.get("message") ?? []) {
+        listener({ data: frame });
+      }
+    },
+    injectToWorker: (frame) => {
+      for (const listener of workerListeners.get("message") ?? []) {
+        listener({ data: frame });
+      }
+    },
+    emitWorkerGlobal: (type, event) => {
+      for (const listener of workerListeners.get(type) ?? [])
+        listener(event);
+    },
+    emitTransport: (type, event) => {
+      for (const listener of clientListeners.get(type) ?? [])
+        listener(event);
+    },
+    flush: async () => {
+      await chain;
+      await new Promise((resolve) => setTimeout(resolve, 5));
+    }
+  };
+}
+function settled(ms = 20) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function faultyStore(fault, options = {}) {
+  const inner = new MemoryBlockStore();
+  const calls = [];
+  const hidden = new Set(options.hide ?? []);
+  const store = new Proxy(inner, {
+    get(target, property) {
+      if (typeof property === "string" && hidden.has(property))
+        return void 0;
+      const value = target[property];
+      if (typeof value !== "function" || typeof property !== "string")
+        return value;
+      const method = property;
+      return (...args) => {
+        const run = () => value.apply(inner, args);
+        const isAsync = value.constructor?.name === "AsyncFunction";
+        if (!isAsync)
+          return run();
+        calls.push({ method, args });
+        return fault(method, args, run);
+      };
+    },
+    has(target, property) {
+      if (typeof property === "string" && hidden.has(property))
+        return false;
+      return Reflect.has(target, property);
+    }
+  });
+  return { store, calls };
+}
+export {
+  createBoundary,
+  faultyStore,
+  settled
+};

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. */