@minnowdb/core 0.9.1 → 0.10.1

package/dist/transactions/index.js

@@ -1,5 +1,5 @@
 import { dateIsoString, dateMilliseconds } from "../date-value.js";
-import { assertTransactionArtifactBatchLimits, assertTransactionArtifactJournalLimits, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, MAX_LEVEL_ZERO_SEGMENTS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_LEASE_TTL_MS, MAX_TRANSACTION_STAGE_BLOCKS, MAX_TRANSACTION_STAGE_BYTES, MAX_TRANSACTION_STAGE_SEGMENTS, MAX_TRANSACTION_COMMIT_DELTA_BYTES, MAX_TRANSACTION_COMMIT_DELTA_ENTRIES, transactionCommitDeltaRetainedBytes, SnapshotManifestMissingError, TransactionRecordConflictError, WriteConflictError } from "../storage/types.js";
+import { assertTransactionArtifactBatchLimits, GarbageCollectionJobConflictError, LeaseConflictError, LeaseExpiredError, MAX_LEVEL_ZERO_SEGMENTS, MAX_MANIFEST_BLOCK_PRESENCE_IDS, MAX_LEASE_TTL_MS, MAX_TRANSACTION_STAGE_BLOCKS, MAX_TRANSACTION_STAGE_BYTES, MAX_TRANSACTION_STAGE_SEGMENTS, MAX_TRANSACTION_COMMIT_DELTA_BYTES, MAX_TRANSACTION_COMMIT_DELTA_ENTRIES, transactionCommitDeltaRetainedBytes, SnapshotManifestMissingError, TransactionRecordConflictError, UnknownOutcomeError, WriteConflictError } from "../storage/types.js";
 const DEFAULT_TRANSACTION_TTL_MS = 3e4;
 class TransactionClosedError extends Error {
   transactionId;
@@ -118,6 +118,7 @@ class DatabaseTransaction {
   #deferredBlocks = [];
   #deferredSegments = [];
   #knownSegments = /* @__PURE__ */ new Map();
+  #stagedSegmentsView;
   #persisted;
   #coalesceArtifacts;
   #snapshotLease;
@@ -156,14 +157,56 @@ class DatabaseTransaction {
   get snapshotVersion() {
     return this.#record.snapshotVersion;
   }
+  #journalView;
+  #journal() {
+    const view = this.#journalView;
+    if (view?.record === this.#record && view.deferredBlocks === this.#deferredBlocks.length && view.deferredSegments === this.#deferredSegments.length) {
+      return view;
+    }
+    const journaledBlocks = view?.record === this.#record ? view.journaledBlocks : new Set(this.#record.pendingBlockIds);
+    const next = {
+      record: this.#record,
+      deferredBlocks: this.#deferredBlocks.length,
+      deferredSegments: this.#deferredSegments.length,
+      blockIds: [...this.#record.pendingBlockIds, ...this.#deferredBlocks.map((block) => block.id)],
+      segmentIds: [
+        ...this.#record.pendingSegmentIds,
+        ...this.#deferredSegments.map((segment) => segment.id)
+      ],
+      journaledBlocks
+    };
+    this.#journalView = next;
+    return next;
+  }
+  #journalAppended(previous, blockIds) {
+    const view = this.#journalView;
+    if (view?.record !== previous || this.#record.pendingBlockIds.length !== previous.pendingBlockIds.length + blockIds.length) {
+      this.#journalView = void 0;
+      return;
+    }
+    for (const id of blockIds)
+      view.journaledBlocks.add(id);
+    view.record = this.#record;
+    view.deferredBlocks = -1;
+  }
   get pendingBlockIds() {
-    return [...this.#record.pendingBlockIds, ...this.#deferredBlocks.map((block) => block.id)];
+    return [...this.#journal().blockIds];
   }
   get pendingSegmentIds() {
-    return [
-      ...this.#record.pendingSegmentIds,
-      ...this.#deferredSegments.map((segment) => segment.id)
-    ];
+    return [...this.#journal().segmentIds];
+  }
+  hasPendingBlock(id) {
+    return this.#journal().journaledBlocks.has(id) || this.#deferredBlocks.some((block) => block.id === id);
+  }
+  get stagedSegments() {
+    this.#stagedSegmentsView ??= [...this.#knownSegments.values()];
+    return this.#stagedSegmentsView;
+  }
+  get pendingBlockCount() {
+    return this.#record.pendingBlockIds.length + this.#deferredBlocks.length;
+  }
+  get pendingSegmentCount() {
+    return this.#record.pendingSegmentIds.length + this.#deferredSegments.length;
   }
   get deferredSegments() {
     return structuredClone(this.#deferredSegments);
@@ -190,8 +233,13 @@ class DatabaseTransaction {
     this.#assertActive();
     await this.#renewOwnership(true);
   }
+  async renewIfDue() {
+    if (this.#record.status !== "active")
+      return;
+    await this.#renewOwnership(false);
+  }
   get stagedWorkCount() {
-    return this.pendingBlockIds.length + this.pendingSegmentIds.length + this.#uniqueKeyChanges.length + this.#ftsChanges.size + this.#compactionSourceBlockIds.size;
+    return this.pendingBlockCount + this.pendingSegmentCount + this.#uniqueKeyChanges.length + this.#ftsChanges.size + this.#compactionSourceBlockIds.size;
   }
   checkpoint() {
     this.#assertActive();
@@ -218,9 +266,9 @@ class DatabaseTransaction {
       bytes = checkpointByteSum(bytes, 16 + value.length * 2);
     };
     addString(this.id);
-    for (const id of this.pendingBlockIds)
+    for (const id of this.#journal().blockIds)
       addString(id);
-    for (const id of this.pendingSegmentIds)
+    for (const id of this.#journal().segmentIds)
       addString(id);
     for (const change of this.#uniqueKeyChanges) {
       addString(change.tableId);
@@ -258,9 +306,11 @@ class DatabaseTransaction {
     const segmentPrefix = checkpoint.pendingSegmentIds;
     const retainedBlocks = new Set(blockPrefix);
     const retainedSegments = new Set(segmentPrefix);
-    const currentBlockIds = this.pendingBlockIds;
-    const currentSegmentIds = this.pendingSegmentIds;
-    if (blockPrefix.some((id) => !currentBlockIds.includes(id)) || segmentPrefix.some((id) => !currentSegmentIds.includes(id))) {
+    const currentBlockIds = this.#journal().blockIds;
+    const currentSegmentIds = this.#journal().segmentIds;
+    const currentBlocks = new Set(currentBlockIds);
+    const currentSegments = new Set(currentSegmentIds);
+    if (blockPrefix.some((id) => !currentBlocks.has(id)) || segmentPrefix.some((id) => !currentSegments.has(id))) {
       throw new TypeError("A transaction checkpoint is no longer reachable");
     }
     const removedBlockIds = currentBlockIds.filter((id) => !retainedBlocks.has(id));
@@ -290,6 +340,7 @@ class DatabaseTransaction {
     }
     for (const id of removedSegmentIds)
       this.#knownSegments.delete(id);
+    this.#stagedSegmentsView = void 0;
     this.#uniqueKeyChanges.splice(0);
     this.#ftsChanges.clear();
     this.#commitDeltaBytes = 0;
@@ -319,20 +370,23 @@ class DatabaseTransaction {
     const deferred = this.#deferredBlocks.find((block) => block.id === id);
     if (deferred !== void 0)
       return new Uint8Array(deferred.bytes);
-    if (this.#record.pendingBlockIds.includes(id))
+    if (this.#journal().journaledBlocks.has(id))
       return this.store.getBlock(id);
     return (await this.snapshot()).getBlock(id);
   }
   #assertProspectiveArtifactJournal(blocks, segments) {
-    const blockIds = new Set(this.pendingBlockIds);
-    const segmentIds = new Set(this.pendingSegmentIds);
+    const journal = this.#journal();
+    const blockIds = /* @__PURE__ */ new Set();
+    const deferredBlocks = new Set(this.#deferredBlocks.map((block) => block.id));
     for (const block of blocks) {
       if (block.id.length === 0)
         throw new TypeError("Block ID cannot be empty");
-      if (blockIds.has(block.id))
+      if (journal.journaledBlocks.has(block.id) || deferredBlocks.has(block.id) || blockIds.has(block.id)) {
         throw new Error(`Block already exists: ${block.id}`);
+      }
       blockIds.add(block.id);
     }
+    const segmentIds = new Set(journal.segmentIds);
     for (const segment of segments) {
       if (segment.id.length === 0)
         throw new TypeError("Segment ID cannot be empty");
@@ -340,7 +394,6 @@ class DatabaseTransaction {
         throw new Error(`Segment already exists: ${segment.id}`);
       segmentIds.add(segment.id);
     }
-    assertTransactionArtifactJournalLimits([...blockIds], [...segmentIds]);
   }
   async #stageArtifactBatch(blocks, segments) {
     if (blocks.length === 0 && segments.length === 0)
@@ -348,6 +401,7 @@ class DatabaseTransaction {
     assertTransactionArtifactBatchLimits(blocks, segments);
     await this.#ensurePersisted();
     await this.#renewOwnership();
+    const previous = this.#record;
     try {
       this.#record = await this.store.stageTransactionArtifacts({
         transactionId: this.id,
@@ -357,8 +411,9 @@ class DatabaseTransaction {
         updatedAt: dateIsoString(this.now())
       });
     } catch (error) {
-      await this.#recoverStagedAcknowledgement(error, blocks, segments);
+      this.#record = await this.#recoverStagedAcknowledgement(error, blocks, segments);
     }
+    this.#journalAppended(previous, blocks.map((block) => block.id));
   }
   async stageBlock(id, bytes) {
     return this.stageBlocks([{ id, bytes }]);
@@ -376,7 +431,7 @@ class DatabaseTransaction {
         throw new Error(`Segment ${segment.id} belongs to another transaction`);
       }
     }
-    const ordinalBase = this.pendingSegmentIds.length;
+    const ordinalBase = this.pendingSegmentCount;
     const ordered = segments.map((segment, index) => ({
       ...segment,
       commitOrdinal: ordinalBase + index
@@ -392,6 +447,7 @@ class DatabaseTransaction {
       this.#deferredSegments.push(...structuredClone(ordered));
       for (const segment of ordered)
         this.#knownSegments.set(segment.id, structuredClone(segment));
+      this.#stagedSegmentsView = void 0;
       for (const segment of ordered)
         this.#changedTableIds.add(segment.tableId);
       return;
@@ -402,6 +458,7 @@ class DatabaseTransaction {
     }
     for (const segment of ordered)
       this.#knownSegments.set(segment.id, structuredClone(segment));
+    this.#stagedSegmentsView = void 0;
     for (const segment of ordered)
       this.#changedTableIds.add(segment.tableId);
   }
@@ -412,6 +469,17 @@ class DatabaseTransaction {
         throw new Error(`Segment ${segment.id} belongs to another transaction`);
       }
     }
+    if (this.#deferredBlocks.length > 0 || this.#deferredSegments.length > 0) {
+      const combined = transactionArtifactBatches([...this.#deferredBlocks, ...blocks], [...this.#deferredSegments, ...segments]);
+      if (combined.length === 1) {
+        blocks = [...this.#deferredBlocks, ...blocks];
+        segments = [...this.#deferredSegments, ...segments];
+        this.#deferredBlocks.length = 0;
+        this.#deferredSegments.length = 0;
+      } else {
+        await this.#persistDeferredArtifacts();
+      }
+    }
     const pendingBlockIds = new Set(this.#record.pendingBlockIds);
     const pendingSegmentIds = new Set(this.#record.pendingSegmentIds);
     await this.#assertRetainedArtifactsUnchanged(blocks.filter((block) => pendingBlockIds.has(block.id)), segments.filter((segment) => pendingSegmentIds.has(segment.id)));
@@ -446,6 +514,7 @@ class DatabaseTransaction {
     const ftsChanges = this.#materializedFtsChanges();
     for (const segment of ordered)
       this.#knownSegments.set(segment.id, structuredClone(segment));
+    this.#stagedSegmentsView = void 0;
     for (const segment of ordered)
       this.#changedTableIds.add(segment.tableId);
     try {
@@ -496,7 +565,6 @@ class DatabaseTransaction {
     if (additions.some((id) => id.length === 0)) {
       throw new TypeError("Block ID cannot be empty");
     }
-    assertTransactionArtifactJournalLimits([...this.#record.pendingBlockIds, ...additions], this.#record.pendingSegmentIds);
     for (const id of additions) {
       if (await this.store.getBlock(id) === void 0) {
         throw new Error(`Cannot stage a missing existing block: ${id}`);
@@ -530,10 +598,6 @@ class DatabaseTransaction {
     if (record.commitOrdinal !== this.#record.pendingSegmentIds.length) {
       throw new Error(`Existing segment ${segmentId} is not the next journal ordinal`);
     }
-    assertTransactionArtifactJournalLimits(this.#record.pendingBlockIds, [
-      ...this.#record.pendingSegmentIds,
-      segmentId
-    ]);
     this.#registerLevelZeroSegments([record]);
     this.#changedTableIds.add(record.tableId);
     await this.#ensurePersisted();
@@ -821,6 +885,7 @@ class DatabaseTransaction {
       this.#deferredBlocks.length = 0;
       this.#deferredSegments.length = 0;
       this.#knownSegments.clear();
+      this.#stagedSegmentsView = void 0;
       this.#record = { ...this.#record, status: "aborted", updatedAt: dateIsoString(this.now()) };
       this.#stopHeartbeat();
       await this.#releaseSnapshotLease().catch(() => void 0);
@@ -852,7 +917,14 @@ class DatabaseTransaction {
       if (error instanceof SnapshotManifestMissingError) {
         throw new WriteConflictError(this.#record.snapshotVersion, await this.store.getCurrentManifestVersion());
       }
-      throw error;
+      const persisted = await this.store.getTransaction(this.id).catch(() => void 0);
+      if (persisted?.status !== "active" || persisted.ownerId !== this.#record.ownerId || persisted.revision !== this.#record.revision || persisted.snapshotVersion !== this.#record.snapshotVersion || persisted.pendingBlockIds.length !== 0 || persisted.pendingSegmentIds.length !== 0) {
+        throw error;
+      }
+      this.#record = persisted;
+      this.#persisted = true;
+      if (!(error instanceof UnknownOutcomeError))
+        throw error;
     }
     this.#persisted = true;
     void this.#releaseSnapshotLease().catch(() => void 0);
@@ -1010,6 +1082,8 @@ class DatabaseTransaction {
         })) {
           this.#record = persisted;
           this.#persisted = true;
+          if (error instanceof UnknownOutcomeError)
+            return persisted;
         }
       }
     } catch {

package/dist/worker-protocol/index.d.ts

@@ -40,15 +40,63 @@ export type RpcResponse = {
 };
 /**
  * A structured-clone-safe error carrying the constructor name and every cloneable own property,
- * so typed engine errors survive the channel and can be rehydrated for instanceof checks.
+ * so typed engine errors survive the channel and can be rehydrated for instanceof checks. The
+ * `cause` chain travels to a bounded depth, and a platform exception keeps its `DOMException`
+ * identity, so a quota refusal is still a `DOMException` named `QuotaExceededError` on the
+ * other side.
  */
 export interface SerializedError {
     name: string;
     message: string;
     stack?: string;
     props?: Record<string, unknown>;
+    /** True for platform exceptions, which rehydrate as `DOMException` rather than `Error`. */
+    domException?: true;
+    cause?: SerializedError;
 }
-export declare function serializeError(error: unknown): SerializedError;
+/** How many `cause` links a serialized error carries before the chain is cut. */
+export declare const MAX_SERIALIZED_CAUSE_DEPTH = 8;
+export declare function serializeError(error: unknown, depth?: number): SerializedError;
+/** Constructors whose prototype a rehydrated error adopts, keyed by the `name` they carry. */
+export type ErrorRegistry = ReadonlyMap<string, new (...args: never[]) => Error>;
+/**
+ * Rebuilds an `Error` from its serialized form: a registry hit adopts that class's prototype,
+ * a platform exception becomes a `DOMException`, a built-in subclass name (`TypeError`) keeps
+ * its built-in prototype, and anything else is a plain `Error` carrying the original name.
+ * Own properties and the `cause` chain are restored; the stack stays the worker's.
+ */
+export declare function rehydrateError(serialized: SerializedError, registry: ErrorRegistry): Error;
+/** The event-frame handle id that carries worker diagnostics. Never issued for a real handle. */
+export declare const WORKER_DIAGNOSTIC_HANDLE_ID = "$worker";
+export type WorkerErrorKind = 
+/** A script error nobody caught, in a timer, a channel listener, or another callback. */
+"uncaught"
+/** A promise rejected with no handler attached. */
+ | "unhandled-rejection"
+/** A frame the worker could not deserialize. */
+ | "messageerror"
+/** Background maintenance: a checkpoint, cleanup, or collection step that failed. */
+ | "maintenance"
+/** Multi-tab coordination: an election, handover, or served request that failed. */
+ | "coordination";
+export interface WorkerErrorReport {
+    kind: WorkerErrorKind;
+    /** Where in the worker it happened, for a log line: "opfs election", "auto collection". */
+    context: string;
+    error: SerializedError;
+}
+export declare function workerErrorEvent(report: WorkerErrorReport): RpcResponse;
+/**
+ * How often the worker tells the client that a call is still being worked on. The client's
+ * request deadline counts silence, not wall time, so a large batch write is not cut off — and
+ * its client left permanently failed — merely for being large.
+ */
+export declare const WORKER_KEEPALIVE_INTERVAL_MS = 5000;
+/** The shortest pace a client may ask for; below this the reports would be the load. */
+export declare const MIN_WORKER_KEEPALIVE_INTERVAL_MS = 100;
+/** A keepalive for one in-flight request: the worker is alive and still holds it. */
+export declare function workerKeepaliveEvent(requestId: string): RpcResponse;
+export declare function isWorkerErrorReport(value: unknown): value is WorkerErrorReport;
 export declare function rpcResult(requestId: string, result: unknown): RpcResponse;
 export declare function rpcFailure(requestId: string, error: unknown): RpcResponse;
 export declare function rpcEvent(handleId: string, event: string, payload: unknown): RpcResponse;

package/dist/worker-protocol/index.js

@@ -1,12 +1,21 @@
 const protocolVersion = 7;
 const MAX_DATABASE_RPC_IN_FLIGHT = 256;
-function serializeError(error) {
+const MAX_SERIALIZED_CAUSE_DEPTH = 8;
+function serializeError(error, depth = 0) {
+  if (typeof DOMException !== "undefined" && error instanceof DOMException) {
+    return {
+      name: error.name,
+      message: error.message,
+      domException: true,
+      ...typeof error.stack === "string" ? { stack: error.stack } : {}
+    };
+  }
   if (!(error instanceof Error)) {
     return { name: "Error", message: String(error) };
   }
   const props = {};
   for (const key of Object.keys(error)) {
-    if (key === "name" || key === "message" || key === "stack")
+    if (key === "name" || key === "message" || key === "stack" || key === "cause")
       continue;
     const value = error[key];
     try {
@@ -15,13 +24,98 @@ function serializeError(error) {
     } catch {
     }
   }
+  const cause = error.cause === void 0 || depth >= MAX_SERIALIZED_CAUSE_DEPTH ? void 0 : serializeError(error.cause, depth + 1);
   return {
     name: error.name,
     message: error.message,
     ...error.stack === void 0 ? {} : { stack: error.stack },
-    ...Object.keys(props).length === 0 ? {} : { props }
+    ...Object.keys(props).length === 0 ? {} : { props },
+    ...cause === void 0 ? {} : { cause }
   };
 }
+const builtinErrorNames = /* @__PURE__ */ new Set([
+  "TypeError",
+  "RangeError",
+  "SyntaxError",
+  "ReferenceError",
+  "EvalError",
+  "URIError",
+  "AggregateError"
+]);
+function rehydrateError(serialized, registry) {
+  const cause = serialized.cause === void 0 ? void 0 : rehydrateError(serialized.cause, registry);
+  if (serialized.domException === true) {
+    const exception = new DOMException(serialized.message, serialized.name);
+    if (cause !== void 0) {
+      Object.defineProperty(exception, "cause", {
+        value: cause,
+        writable: true,
+        configurable: true
+      });
+    }
+    return exception;
+  }
+  const constructor = registry.get(serialized.name);
+  let error;
+  if (constructor !== void 0) {
+    error = Object.create(constructor.prototype);
+  } else if (builtinErrorNames.has(serialized.name)) {
+    const builtin = globalThis[serialized.name];
+    error = typeof builtin === "function" ? Object.create(builtin.prototype) : new Error(serialized.message);
+  } else {
+    error = new Error(serialized.message);
+  }
+  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 (cause !== void 0) {
+    Object.defineProperty(error, "cause", { value: cause, writable: true, configurable: true });
+  }
+  if (serialized.props !== void 0)
+    Object.assign(error, serialized.props);
+  return error;
+}
+const WORKER_DIAGNOSTIC_HANDLE_ID = "$worker";
+function workerErrorEvent(report) {
+  return rpcEvent(WORKER_DIAGNOSTIC_HANDLE_ID, "error", report);
+}
+const WORKER_KEEPALIVE_INTERVAL_MS = 5e3;
+const MIN_WORKER_KEEPALIVE_INTERVAL_MS = 100;
+function workerKeepaliveEvent(requestId) {
+  return {
+    version: protocolVersion,
+    requestId,
+    kind: "rpc-event",
+    handleId: WORKER_DIAGNOSTIC_HANDLE_ID,
+    event: "keepalive",
+    payload: null
+  };
+}
+function isWorkerErrorReport(value) {
+  if (typeof value !== "object" || value === null)
+    return false;
+  const report = value;
+  if (typeof report.kind !== "string" || typeof report.context !== "string")
+    return false;
+  if (typeof report.error !== "object" || report.error === null)
+    return false;
+  const error = report.error;
+  return typeof error.name === "string" && typeof error.message === "string";
+}
 function rpcResult(requestId, result) {
   return { version: protocolVersion, requestId, kind: "rpc-result", result };
 }
@@ -69,11 +163,19 @@ function parseRpcResponse(value) {
 }
 export {
   MAX_DATABASE_RPC_IN_FLIGHT,
+  MAX_SERIALIZED_CAUSE_DEPTH,
+  MIN_WORKER_KEEPALIVE_INTERVAL_MS,
+  WORKER_DIAGNOSTIC_HANDLE_ID,
+  WORKER_KEEPALIVE_INTERVAL_MS,
+  isWorkerErrorReport,
   parseRpcRequest,
   parseRpcResponse,
   protocolVersion,
+  rehydrateError,
   rpcEvent,
   rpcFailure,
   rpcResult,
-  serializeError
+  serializeError,
+  workerErrorEvent,
+  workerKeepaliveEvent
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minnowdb/core",
-  "version": "0.9.1",
+  "version": "0.10.1",
   "description": "A columnar SQL database for the browser: PostgreSQL-style SQL over durable IndexedDB or OPFS data, with no server or WebAssembly module.",
   "license": "MIT",
   "author": "Eric Wilhite",
@@ -29,7 +29,8 @@
     "./dist/engine/worker.js",
     "./dist/engine/worker-indexeddb.js",
     "./dist/engine/worker-opfs.js",
-    "./dist/engine/worker-memory.js"
+    "./dist/engine/worker-memory.js",
+    "./dist/engine/worker-auto.js"
   ],
   "scripts": {
     "prepack": "node ../../scripts/prepare-package.mjs --strip-comments"
@@ -79,6 +80,10 @@
       "types": "./dist/engine/worker-memory.d.ts",
       "default": "./dist/engine/worker-memory.js"
     },
+    "./worker/auto": {
+      "types": "./dist/engine/worker-auto.d.ts",
+      "default": "./dist/engine/worker-auto.js"
+    },
     "./worker-host": {
       "types": "./dist/engine/worker-host.d.ts",
       "default": "./dist/engine/worker-host.js"