@minnowdb/core 0.0.1 → 0.1.0

package/dist/transactions/index.d.ts

@@ -0,0 +1,148 @@
+import { type BlockStore, type BlockWrite, type LeaseKind, type LeaseRecord, type ManifestSummary, type RowIdRange, type SegmentRecord, type TransactionRecord, type FtsChanges, type UniqueKeyChanges } from "../storage/index.js";
+export interface TransactionManagerOptions {
+    now?: () => Date;
+    createId?: () => string;
+}
+export interface RecoveryOptions {
+    staleBefore: Date;
+    removePendingBlocks?: boolean;
+}
+export interface RecoveryReport {
+    abortedTransactionIds: string[];
+    skippedTransactionIds: string[];
+    removedBlockIds: string[];
+    retainedBlockIds: string[];
+    removedSegmentIds: string[];
+    retainedSegmentIds: string[];
+}
+export interface OpenLeasedSnapshotOptions {
+    /** Optional caller-owned ID used by internal short-lived leases. */
+    id?: string;
+    ownerId: string;
+    ttlMs: number;
+    kind?: LeaseKind;
+    version?: number | null;
+}
+export declare class TransactionClosedError extends Error {
+    readonly transactionId: string;
+    readonly name = "TransactionClosedError";
+    constructor(transactionId: string);
+}
+export declare class Snapshot {
+    #private;
+    private readonly store;
+    readonly version: number | null;
+    constructor(store: BlockStore, version: number | null, blockIds: readonly string[]);
+    listBlockIds(): string[];
+    hasBlock(id: string): boolean;
+    getBlock(id: string): Promise<Uint8Array | undefined>;
+}
+export declare class LeasedSnapshot extends Snapshot {
+    #private;
+    private readonly now;
+    constructor(store: BlockStore, version: number | null, blockIds: readonly string[], record: LeaseRecord, now: () => Date);
+    get leaseId(): string;
+    get expiresAt(): Date;
+    getBlock(id: string): Promise<Uint8Array | undefined>;
+    renew(ttlMs: number): Promise<Date>;
+    release(): Promise<void>;
+}
+export declare class DatabaseTransaction {
+    #private;
+    private readonly store;
+    private readonly now;
+    constructor(store: BlockStore, record: TransactionRecord, now: () => Date);
+    get id(): string;
+    get status(): TransactionRecord["status"];
+    get snapshotVersion(): number | null;
+    get pendingBlockIds(): string[];
+    get pendingSegmentIds(): string[];
+    get supersededBlockIds(): string[];
+    /**
+     * Counts every registration this transaction carries: staged blocks and segments, unique-key
+     * entries, full-text entries, and supersessions. A caller that fails part-way through a
+     * multi-step stage compares this before and after to tell "nothing was registered" (the
+     * statement is cleanly undone) from "partial work landed" (the transaction can only abort),
+     * since there is no statement-level rollback inside a transaction.
+     */
+    get stagedWorkCount(): number;
+    snapshot(): Promise<Snapshot>;
+    getBlock(id: string): Promise<Uint8Array | undefined>;
+    stageBlock(id: string, bytes: Uint8Array): Promise<void>;
+    stageBlocks(blocks: readonly BlockWrite[]): Promise<void>;
+    /**
+     * Stages blocks and segments in one journal step. When the store implements the atomic
+     * combined operation this is a single storage transaction instead of the four the sequential
+     * shape costs (block writes, journal update, segment writes, journal update); either way the
+     * observable journal invariant is identical — a journaled artifact always exists.
+     */
+    stageArtifacts(blocks: readonly BlockWrite[], segments: readonly SegmentRecord[]): Promise<void>;
+    /**
+     * Adds already-persisted immutable blocks to this transaction's journal.
+     *
+     * Resumable background jobs use this to reconcile the narrow crash window
+     * between an immutable block write and the transaction-record update. The
+     * bytes must already exist, and already-journaled IDs are ignored.
+     */
+    stageExistingBlocks(blockIds: readonly string[]): Promise<void>;
+    stageSegment(record: SegmentRecord): Promise<void>;
+    /** Reconciles a persisted segment whose journal update was interrupted. */
+    stageExistingSegment(segmentId: string): Promise<void>;
+    /**
+     * Records that this commit changes a table's logical content without staging a segment for
+     * it — dropping the table, for instance, whose only publish is the retirement of its blocks.
+     * Change-driven readers such as live queries need to see it move.
+     */
+    markTableChanged(tableId: string): void;
+    /**
+     * Marks this commit as logically content-preserving (for example a compaction rewrite), so
+     * change-driven readers such as live queries skip it even though it stages segments.
+     */
+    markLogicallyUnchanged(): void;
+    /** Accumulated key changes in operation order, for in-scope membership overlays. */
+    get accumulatedUniqueKeyChanges(): readonly UniqueKeyChanges[];
+    /** Appends one operation's key changes; entries commit in operation order. */
+    setUniqueKeyChanges(changes: UniqueKeyChanges): void;
+    /**
+     * Attaches one batch's full-text deltas; applied atomically with the publish. A second
+     * batch for the same table merges per column — postings re-sorted by term (each batch's
+     * reserved row ids are strictly above the last, so rowIds stay ascending within a term)
+     * and token totals summed — so a scope can insert into one FTS table any number of times.
+     */
+    setFtsChanges(changes: FtsChanges): void;
+    supersedeBlocks(blockIds: readonly string[]): void;
+    commit(): Promise<ManifestSummary>;
+    rebase(): Promise<Snapshot>;
+    abort(): Promise<void>;
+}
+export declare class TransactionManager {
+    #private;
+    private readonly store;
+    constructor(store: BlockStore, options?: TransactionManagerOptions);
+    begin(): Promise<DatabaseTransaction>;
+    /**
+     * Begins a transaction at the current manifest version and optionally reserves row ids and
+     * auto-increment values in the same step. Stores implementing the atomic `beginTransaction`
+     * pay one storage round trip instead of the version-read/create/reserve sequence; the
+     * read-then-create fallback retries when the version it read is pruned before the record lands.
+     */
+    beginWithReservation(reserveRowIds?: {
+        tableId: string;
+        count: number;
+    }, reserveAutoIncrement?: {
+        tableId: string;
+        columnId: string;
+        count: number;
+        atLeast?: bigint;
+    }): Promise<{
+        transaction: DatabaseTransaction;
+        rowIds?: RowIdRange;
+        autoIncrementValues?: RowIdRange;
+    }>;
+    resume(transactionId: string): Promise<DatabaseTransaction>;
+    openSnapshot(version?: number | null): Promise<Snapshot>;
+    openLeasedSnapshot(options: OpenLeasedSnapshotOptions): Promise<LeasedSnapshot>;
+    removeExpiredLeases(at?: Date): Promise<string[]>;
+    recover(options: RecoveryOptions): Promise<RecoveryReport>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/transactions/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/transactions/index.ts"],"names":[],"mappings":"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"}