@minnowdb/core 0.3.0 → 0.4.0

package/dist/storage/opfs/store.d.ts

@@ -1,18 +1,20 @@
-import { type BeginTransactionInput, type BeginTransactionResult, type BlockStore, type BlockWrite, type CatalogProbe, type CommitTransactionInput, type CompactionJobRecord, type CompactionJobRecordUpdate, type CreateGarbageCollectionJobInput, type FtsCandidates, type FtsColumnIndexRecord, type FtsPostingQuery, type GarbageCollectionJobRecord, type GarbageCollectionStepResult, type LeaseRecord, type Manifest, type ManifestSummary, type PublishManifestInput, type QueryCatalogState, type RowIdRange, type RunGarbageCollectionStepInput, type SegmentRecord, type StageTransactionArtifactsInput, type StoragePage, type TableColumnRecord, type TableRecord, type SecondaryIndexRecord, type TempOwnerRecord, type TempRunPage, type TransactionRecord, type TransactionRecordUpdate, type TriggerRecord, type FtsPosting, type WriteTransactionInput } from "../types.js";
-import type { DatabaseSnapshot, SnapshotLoadProgress } from "../snapshot.js";
+import { type BlockStore, type TempRunPage } from "../types.js";
 export interface OpfsBlockStoreOptions {
     /** Databases live under `minnowdb/<name>` in the origin's private file system. */
     name: string;
     /**
-     * `"relaxed"` (the default, matching the IndexedDB store) lets the operating system
-     * schedule the final flush to disk; `"strict"` flushes every log frame and payload write
-     * before the operation resolves.
+     * `"strict"` (the default) flushes the payload before flushing its publishing WAL frame,
+     * both before the operation resolves. `"relaxed"` writes the complete payload and
+     * WAL frame before resolving but lets the operating system schedule their final flush; a
+     * power loss may roll back a fully consistent suffix.
      */
     durability?: "relaxed" | "strict";
     /** The storage root; defaults to `navigator.storage.getDirectory()`. Tests inject a shim. */
     root?: FileSystemDirectoryHandle;
     /** @internal Test seam: checkpoint after this many WAL entries (default 1024). */
     checkpointEntries?: number;
+    /** @internal Test seam: cleanup-debt backpressure limit (default 64 MiB). */
+    cleanupLimitBytes?: number;
     /** @internal Test seam: how long a follower waits for the leader (default 1000ms). */
     rpcTimeoutMs?: number;
 }
@@ -31,145 +33,49 @@ export interface OpfsBlockStoreOptions {
  * Leadership is the write-ahead log's own exclusive sync-access handle — enforced by the
  * browser against the actual resource, released the instant its holder dies. Elections are
  * simply attempts to open it. Correctness never rides on a message: an operation is
- * acknowledged only after the leader's WAL holds it, a lost message costs a retry (request
- * ids deduplicate retries while the same leader serves), and a dead leader costs a failover
- * in which the next acquirer replays checkpoint-plus-WAL. A retry that crosses a failover is
- * the one case a duplicate can execute — the same "committed but the response was lost"
- * class the IndexedDB store has — and it resolves the same way: compare-and-swap operations
- * surface a conflict the engine's recovery already reconciles. The channel affects how fast
- * multi-tab work moves, never whether it is right.
+ * acknowledged only after the leader's WAL holds it. Request ids deduplicate delivery retries
+ * while the same leader serves. A dead leader costs a failover in which the next acquirer
+ * replays checkpoint-plus-WAL; an in-flight read moves to it, while an in-flight mutation fails
+ * with `OpfsUncertainOutcomeError` instead of risking a second execution after a lost reply.
+ * The channel affects how fast multi-tab work moves, never whether it is right.
  *
  * `setForeground(true)` marks this connection as the one the user is looking at; a background
  * leader yields to a foreground bidder, so the tab doing the work is normally the tab holding
  * the microsecond-fast path.
  */
-export declare class OpfsBlockStore implements BlockStore {
+export interface OpfsBlockStore extends Required<BlockStore> {
+}
+export declare class OpfsBlockStore {
     #private;
+    readonly liveQueryChannelName: string;
     private constructor();
     static open(options: OpfsBlockStoreOptions): Promise<OpfsBlockStore>;
     /** Marks this connection as the one the user is looking at — a leadership preference. */
     setForeground(foreground: boolean): void;
-    addBlock(id: string, bytes: Uint8Array): Promise<void>;
-    addBlocks(blocks: readonly BlockWrite[]): Promise<void>;
-    getBlock(id: string): Promise<Uint8Array | undefined>;
-    getBlocks(ids: readonly string[]): Promise<Array<Uint8Array | undefined>>;
-    removeBlock(id: string): Promise<void>;
-    listBlockIds(): Promise<string[]>;
     putTempRunPage(page: TempRunPage): Promise<void>;
     putTempRunPages(pages: readonly TempRunPage[]): Promise<void>;
     getTempRunPage(ownerId: string, runId: string, pageIndex: number): Promise<Uint8Array | undefined>;
     removeTempRun(ownerId: string, runId: string): Promise<void>;
-    removeTempOwner(ownerId: string): Promise<void>;
-    createTempOwner(record: TempOwnerRecord): Promise<void>;
-    getTempOwner(ownerId: string): Promise<TempOwnerRecord | undefined>;
-    renewTempOwner(ownerId: string, expectedRevision: number, expiresAt: string): Promise<TempOwnerRecord>;
-    removeTempOwnerIfExpired(ownerId: string, expiresAtCutoff: string): Promise<boolean>;
-    listTempOwnerIdsPage(afterOwnerId: string | null, limit: number): Promise<StoragePage<string, string>>;
-    addTable(record: TableRecord): Promise<void>;
-    getTable(id: string): Promise<TableRecord | undefined>;
-    getTableByName(name: string): Promise<TableRecord | undefined>;
-    listTables(): Promise<TableRecord[]>;
-    updateTable(id: string, expectedRevision: number, update: {
-        columns?: TableColumnRecord[];
-        ftsColumns?: Record<string, FtsColumnIndexRecord> | null;
-        secondaryIndexes?: Record<string, SecondaryIndexRecord> | null;
-        expectedManifestVersion?: {
-            value: number | null;
-        };
-        uniqueKeySeed?: {
-            namespaceId: string;
-            keyTokens: readonly string[];
-        };
-        triggers?: TriggerRecord[] | null;
-    }): Promise<TableRecord>;
-    removeTable(id: string, expectedRevision: number): Promise<void>;
-    writeFtsBase(tableId: string, columnId: string, input: {
-        coversVersion: number;
-        chunks: FtsPosting[][];
-        totalTokens: number;
-    }): Promise<void>;
-    removeFtsColumn(tableId: string, columnId: string): Promise<void>;
-    beginFtsBaseBuild(tableId: string, columnId: string, buildId: string): Promise<void>;
-    writeFtsBaseBuildChunk(tableId: string, columnId: string, buildId: string, ordinal: number, chunk: FtsPosting[]): Promise<void>;
-    finishFtsBaseBuild(tableId: string, columnId: string, buildId: string, input: {
-        coversVersion: number;
-        chunkCount: number;
-        totalTokens: number;
-    }): Promise<void>;
-    abortFtsBaseBuild(tableId: string, columnId: string, buildId: string): Promise<void>;
-    readFtsCandidates(tableId: string, columnId: string, terms: readonly FtsPostingQuery[], upToVersion: number): Promise<FtsCandidates & {
-        deltaChunkCount: number;
-        totalTokens: number;
-        coversVersion: number;
-        hasBase: boolean;
-    }>;
-    readFtsPostings(tableId: string, columnId: string, upToVersion: number): Promise<{
-        postings: FtsPosting[];
-        deltaChunkCount: number;
-        coversVersion: number;
-        hasBase: boolean;
-    }>;
-    addSegment(record: SegmentRecord): Promise<void>;
-    getSegment(id: string): Promise<SegmentRecord | undefined>;
-    listSegments(tableId?: string): Promise<SegmentRecord[]>;
-    listSegmentPage(afterId: string | null, limit: number): Promise<StoragePage<SegmentRecord, string>>;
-    removeSegment(id: string): Promise<void>;
-    reserveRowIds(tableId: string, count: number): Promise<RowIdRange>;
-    reserveAutoIncrement(tableId: string, columnId: string, count: number, atLeast?: bigint): Promise<RowIdRange>;
-    getExistingUniqueKeys(tableId: string, keyTokens: readonly string[]): Promise<string[]>;
-    getCurrentManifest(): Promise<Manifest | undefined>;
-    getCurrentManifestVersion(): Promise<number | null>;
-    getCatalogProbe(): Promise<CatalogProbe>;
-    getQueryCatalogState(tableNames: readonly string[]): Promise<QueryCatalogState>;
-    getManifest(version: number): Promise<Manifest | undefined>;
-    listManifests(): Promise<Manifest[]>;
-    listManifestPage(afterVersion: number | null, limit: number): Promise<StoragePage<Manifest, number>>;
-    publishManifest(input: PublishManifestInput): Promise<Manifest>;
-    createTransaction(record: TransactionRecord): Promise<void>;
-    beginTransaction(input: BeginTransactionInput): Promise<BeginTransactionResult>;
-    getTransaction(id: string): Promise<TransactionRecord | undefined>;
-    getTransactions(ids: readonly string[]): Promise<Array<TransactionRecord | undefined>>;
-    listTransactions(): Promise<TransactionRecord[]>;
-    listTransactionPage(afterId: string | null, limit: number): Promise<StoragePage<TransactionRecord, string>>;
-    updateTransaction(id: string, expectedRevision: number, update: TransactionRecordUpdate): Promise<TransactionRecord>;
-    stageTransactionArtifacts(input: StageTransactionArtifactsInput): Promise<TransactionRecord>;
-    commitTransaction(input: CommitTransactionInput): Promise<ManifestSummary>;
-    writeTransaction(input: WriteTransactionInput): Promise<ManifestSummary>;
-    createLease(record: LeaseRecord): Promise<void>;
-    getLease(id: string): Promise<LeaseRecord | undefined>;
-    listLeases(): Promise<LeaseRecord[]>;
-    renewLease(id: string, expectedRevision: number, expiresAt: string): Promise<LeaseRecord>;
-    moveLease(id: string, expectedRevision: number, manifestVersion: number | null, expiresAt: string): Promise<LeaseRecord>;
-    removeLeaseIfExpired(id: string, expectedRevision: number, expiresAtCutoff: string): Promise<boolean>;
-    removeLease(id: string): Promise<void>;
-    createCompactionJob(record: CompactionJobRecord): Promise<void>;
-    getCompactionJob(id: string): Promise<CompactionJobRecord | undefined>;
-    listCompactionJobs(tableId?: string): Promise<CompactionJobRecord[]>;
-    listCompactionJobPage(afterId: string | null, limit: number): Promise<StoragePage<CompactionJobRecord, string>>;
-    updateCompactionJob(id: string, expectedRevision: number, update: CompactionJobRecordUpdate): Promise<CompactionJobRecord>;
-    cancelCompactionJob(id: string, expectedRevision: number, cancelledAt: string): Promise<CompactionJobRecord>;
-    removeCompactionJob(id: string): Promise<void>;
-    createGarbageCollectionJob(input: CreateGarbageCollectionJobInput): Promise<GarbageCollectionJobRecord>;
-    getGarbageCollectionJob(id: string): Promise<GarbageCollectionJobRecord | undefined>;
-    listGarbageCollectionJobs(): Promise<GarbageCollectionJobRecord[]>;
-    runGarbageCollectionStep(input: RunGarbageCollectionStepInput): Promise<GarbageCollectionStepResult>;
-    removeGarbageCollectionJob(id: string): Promise<void>;
-    removePrunedManifestRecords(): Promise<number>;
-    getLogicalStorageBytes(): Promise<number>;
-    exportSnapshot(): Promise<DatabaseSnapshot>;
-    importSnapshot(snapshot: DatabaseSnapshot, options?: {
-        onProgress?: (progress: SnapshotLoadProgress) => void;
-    }): Promise<void>;
+    /** @internal Shared implementation installed for every ordinary RPC method below. */
+    _dispatchGenerated(method: string, args: unknown[]): Promise<unknown>;
     close(): void;
     /** Test-only: whether this connection currently holds the database's handles. */
     _isLeaderForTests(): boolean;
     /** Test-only: the id that names this connection's inbox channel. */
     _instanceIdForTests(): string;
+    /** Test-only: simulates an acknowledgement lost after the served operation settles. */
+    _dropNextRpcResultForTests(): void;
+    /** Test-only: holds newly admitted served mutations until the returned release is called. */
+    _holdServedMutationsForTests(): () => void;
+    /** Test-only: retransmits the oldest request with its stable deduplication identity. */
+    _resendOldestPendingForTests(): void;
     /** Test-only counters that pin the connection's bounded RPC state and close-time cleanup. */
     _residentStateForTests(): {
         answerChannels: number;
         dedupeEntries: number;
+        inFlightMutations: number;
         pendingRequests: number;
+        retainedRpcBytes: number;
         closed: boolean;
     };
     /** Test-only: what tab death looks like — locks release, nothing flushes, no goodbyes. */
@@ -180,4 +86,3 @@ export declare function deleteOpfsDatabase(options: {
     name: string;
     root?: FileSystemDirectoryHandle;
 }): Promise<void>;
-//# sourceMappingURL=store.d.ts.map