@crvouga/mockingbird-service-postgres 3.11.0 → 3.12.1

package/dist/shared/core/durability-browser.d.ts

@@ -0,0 +1,52 @@
+import { type DurabilityBackend, type DurableImage, type DurablePatch } from "./durability.js";
+import type { DurabilityLifecycle } from "./durability-buffered.js";
+/** Best effort only; browsers do not wait for asynchronous pagehide work. */
+export declare const browserDurabilityLifecycle: DurabilityLifecycle;
+export interface IndexedDBDurabilityOptions {
+    name?: string;
+    /** Inject for workers, tests or a different browser realm. */
+    indexedDB?: {
+        open(name: string, version?: number): unknown;
+    };
+    /** Default strict: acknowledgement follows the browser's durable commit. */
+    durability?: "default" | "strict" | "relaxed";
+}
+/** Binary pages, changed-page writes and revision checks in one IndexedDB transaction. */
+export declare class IndexedDBDurabilityBackend implements DurabilityBackend {
+    private database;
+    private readonly factory;
+    private readonly name;
+    private readonly durability;
+    constructor(options?: IndexedDBDurabilityOptions);
+    private open;
+    load(key: string): Promise<DurableImage | undefined>;
+    commit(key: string, expectedRevision: number, patch: DurablePatch): Promise<number>;
+    /** Release this adapter's connection; does not delete any saved images. */
+    close(): Promise<void>;
+}
+export interface LocalStorageDurabilityOptions {
+    storage?: {
+        getItem(key: string): string | null;
+        setItem(key: string, value: string): void;
+    };
+    prefix?: string;
+    /** Inject navigator.locks for cross-tab compare-and-swap. Required for safe shared writers. */
+    locks?: {
+        request<T>(name: string, run: () => T | PromiseLike<T>): Promise<T>;
+    };
+}
+/**
+ * Small-image fallback. Each commit replaces one base64 image atomically. IndexedDB avoids
+ * this full-image encoding and synchronous main-thread IO and is preferred for performance.
+ * With no Web Locks support, use one writer per key (localStorage has no native CAS).
+ */
+export declare class LocalStorageDurabilityBackend implements DurabilityBackend {
+    private readonly storage;
+    private readonly prefix;
+    private readonly locks;
+    constructor(options?: LocalStorageDurabilityOptions);
+    load(key: string): Promise<DurableImage | undefined>;
+    private read;
+    commit(key: string, expectedRevision: number, patch: DurablePatch): Promise<number>;
+}
+//# sourceMappingURL=durability-browser.d.ts.map

package/dist/shared/core/durability-buffered.d.ts

@@ -0,0 +1,65 @@
+import { type DurabilityBackend, type DurabilityCodec, type Durable } from "./durability.js";
+export interface DurabilityScheduler {
+    schedule(run: () => void, delayMs: number): unknown;
+    cancel(handle: unknown): void;
+}
+export interface DurabilityLifecycle {
+    subscribe(onSuspend: () => void): () => void;
+}
+export interface BufferedDurabilityObserver {
+    changed(): void;
+    exposed(): void;
+    assertWritable(): void;
+    /** An independently closed engine cannot keep a background persistence loop alive. */
+    closed?(): void;
+}
+export interface IncrementalCapture<Token> {
+    token: Token;
+    checkpoint: boolean;
+    /** Omit when the committed state has not changed. Bytes must be independently owned. */
+    bytes?: Uint8Array;
+}
+/** Engine port: capture physical committed state, never SQL text for replay. */
+export interface IncrementalDurabilityCodec<T, Token> extends DurabilityCodec<T> {
+    decodeJournal(records: readonly Uint8Array[]): T;
+    /** Initialize comparison state after recovery without re-encoding the checkpoint. */
+    baseline?(value: T): Token;
+    capture(value: T, previous: Token | undefined, checkpoint: boolean): IncrementalCapture<Token>;
+    acknowledge(value: T, token: Token): void;
+    canCapture(value: T): boolean;
+    subscribe(value: T, observer: BufferedDurabilityObserver): () => void;
+}
+export interface BufferedDurabilityOptions {
+    /** First-change deadline, not a debounce. Default 1,000 ms; suspension can delay it. */
+    flushIntervalMs?: number;
+    scheduler?: DurabilityScheduler;
+    lifecycle?: DurabilityLifecycle;
+    onError?: (error: unknown) => void;
+    /** Default 256 successful delta batches. */
+    compactAfterBatches?: number;
+    /** Default max(4 MiB, checkpoint size). */
+    compactAfterBytes?: number;
+}
+export interface BufferedDurable<T> extends Durable<T> {
+    readonly pending: boolean;
+    readonly lastError: unknown;
+}
+export declare function isDurableJournal(bytes: Uint8Array): boolean;
+/** A legacy immediate writer can retain a buffered image's richer checkpoint metadata. */
+export declare function encodeDurableCheckpoint(record: Uint8Array): Uint8Array;
+/** Undefined identifies an unchanged legacy image; malformed envelopes fail closed. */
+export declare function readDurableJournal(bytes: Uint8Array): readonly Uint8Array[] | undefined;
+/** Single-writer buffered persistence. Only the last append page is retained between saves. */
+export declare function openBufferedDurable<T, Token>(options: BufferedDurabilityOptions & {
+    key: string;
+    backend: DurabilityBackend;
+    codec: IncrementalDurabilityCodec<T, Token>;
+    pageSize?: number;
+}): Promise<BufferedDurable<T>>;
+/** Pack engine-specific metadata alongside a standard SQLM/PGMM snapshot. */
+export declare function packDurableRecord(metadata: unknown, snapshot: Uint8Array): Uint8Array;
+export declare function unpackDurableRecord<Metadata>(bytes: Uint8Array): {
+    metadata: Metadata;
+    snapshot: Uint8Array;
+};
+//# sourceMappingURL=durability-buffered.d.ts.map

package/dist/shared/core/durability.d.ts

@@ -0,0 +1,78 @@
+/** Atomic binary image port. Implementations must reject stale revisions without writing. */
+export interface DurabilityBackend {
+    load(key: string): Promise<DurableImage | undefined>;
+    commit(key: string, expectedRevision: number, patch: DurablePatch): Promise<number>;
+}
+/**
+ * Give a Fetch emulator a durable acknowledgement boundary. Inject the handle's value into
+ * the service, then send every request through this wrapper. Requests serialize through the
+ * response's commit, so another request cannot mutate the database during a pending save.
+ */
+export declare function withDurability<RequestType, ResponseType>(api: {
+    fetch(request: RequestType): Promise<ResponseType>;
+}, durable: Pick<Durable<unknown>, "flush">): {
+    fetch(request: RequestType): Promise<ResponseType>;
+};
+export interface DurableImage {
+    revision: number;
+    bytes: Uint8Array;
+    pageSize: number;
+}
+export interface DurablePatch {
+    byteLength: number;
+    pageSize: number;
+    /** Only changed pages; data is owned by the caller until commit resolves. */
+    pages: readonly {
+        index: number;
+        bytes: Uint8Array;
+    }[];
+}
+/** A second writer changed the image. Reopen before writing; never silently overwrite it. */
+export declare class DurabilityConflictError extends Error {
+    constructor();
+}
+/** An emulator owns its codec; storage adapters know nothing about SQL or service state. */
+export interface DurabilityCodec<T> {
+    create(): T;
+    decode(bytes: Uint8Array): T;
+    encode(value: T): Uint8Array;
+    close?(value: T): void | Promise<void>;
+}
+export interface DurableOptions<T> {
+    backend: DurabilityBackend;
+    key: string;
+    codec: DurabilityCodec<T>;
+    /** Binary comparison/write granularity. Default 16 KiB. */
+    pageSize?: number;
+}
+export interface Durable<T> {
+    readonly value: T;
+    /** Capture and atomically save the current state. Resolve only after storage commits. */
+    flush(): Promise<void>;
+    /** Serialize a synchronous batch and save it with one encode and storage transaction. */
+    write<R>(run: (value: T) => R): Promise<R>;
+    /** Save before closing. A failed save leaves the handle open for retry. */
+    close(): Promise<void>;
+}
+/**
+ * Keeps the synchronous emulator hot path free of storage IO. Batch any number of mutations,
+ * then await flush(), or await write(batch). A successful synchronous mutation alone is not
+ * durable. No unload handlers, background timers or unhandled persistence failures.
+ */
+export declare function openDurable<T>(options: DurableOptions<T>): Promise<Durable<T>>;
+/** Apply a validated patch to an independently owned image. Also used by custom adapters. */
+export declare function applyDurablePatch(previous: Uint8Array, patch: DurablePatch): Uint8Array;
+/** Validate before starting storage writes so invalid custom patches cannot partially commit. */
+export declare function validateDurablePatch(patch: DurablePatch): void;
+/** Reject missing replacement/new pages before an adapter changes the saved image. */
+export declare function validateDurableCommit(patch: DurablePatch, previous?: {
+    byteLength: number;
+    pageSize: number;
+}): void;
+/** Reference adapter for tests and server-side ephemeral use. */
+export declare class MemoryDurabilityBackend implements DurabilityBackend {
+    private readonly images;
+    load(key: string): Promise<DurableImage | undefined>;
+    commit(key: string, expectedRevision: number, patch: DurablePatch): Promise<number>;
+}
+//# sourceMappingURL=durability.d.ts.map

package/dist/shared/core/fork-map.d.ts

@@ -0,0 +1,51 @@
+type Key = string | number | bigint;
+/**
+ * An insertion-ordered map for primitive storage keys with O(1) forks. Writes detach
+ * two small hash directories, one native hash bucket, and a path of 32-cell order pages.
+ * Values retain ordinary Map reference semantics: callers own value-level copy-on-write.
+ */
+export declare class ForkMap<K extends Key, V> implements Map<K, V> {
+    private owner;
+    private index;
+    private order;
+    private shift;
+    private length;
+    private count;
+    private nextSequence;
+    private layout;
+    private cleared;
+    private version;
+    constructor(entries?: Iterable<readonly [K, V]>);
+    get size(): number;
+    get [Symbol.toStringTag](): string;
+    fork(): ForkMap<K, V>;
+    /** Visit changed hash buckets only. Values must be replaced, rather than mutated in place. */
+    changes(previous?: ForkMap<K, V>): Iterable<{
+        key: K;
+        value: V;
+        deleted: false;
+    } | {
+        key: K;
+        deleted: true;
+    }>;
+    get(key: K): V | undefined;
+    has(key: K): boolean;
+    set(key: K, value: V): this;
+    delete(key: K): boolean;
+    clear(): void;
+    entries(): MapIterator<[K, V]>;
+    keys(): MapIterator<K>;
+    values(): MapIterator<V>;
+    [Symbol.iterator](): MapIterator<[K, V]>;
+    forEach(callback: (value: V, key: K, map: Map<K, V>) => void, thisArg?: unknown): void;
+    private find;
+    private bucket;
+    private writableBucket;
+    private copyBucket;
+    private leaf;
+    private writeOrder;
+    private compact;
+    private iterate;
+}
+export {};
+//# sourceMappingURL=fork-map.d.ts.map

package/dist/shared/core/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./durability.js"
+export * from "./durability-browser.js"
+export * from "./durability-buffered.js"
+export { ForkMap } from "./fork-map.js"

package/dist/shared/core/mount.d.ts

@@ -0,0 +1,17 @@
+import type { FetchAPI, FetchHandler } from "./index.js";
+/** Trusted mount metadata stays on the Request, never in a spoofable HTTP header. */
+export declare const requestBaseUrl: (request: Request) => string;
+export declare const forwardMountContext: (source: Request, target: Request) => Request;
+export type MountedAPI = FetchAPI & {
+    readonly prefix: string;
+    GET: FetchHandler;
+    POST: FetchHandler;
+    PUT: FetchHandler;
+    PATCH: FetchHandler;
+    DELETE: FetchHandler;
+    HEAD: FetchHandler;
+    OPTIONS: FetchHandler;
+};
+/** Embed a native API under an application's origin without owning another listener or state. */
+export declare function mount(api: FetchAPI, path: string, relativePath?: (request: Request) => string): MountedAPI;
+//# sourceMappingURL=mount.d.ts.map

package/dist/shared/core/timeline.d.ts

@@ -0,0 +1,80 @@
+/** A stable identifier for a point in a {@link Timeline}. */
+export type CheckpointId = string;
+/** An immutable node in a timeline's checkpoint DAG. */
+export type Checkpoint<T> = Readonly<{
+    id: CheckpointId;
+    branch: string;
+    parent: CheckpointId | null;
+    /** Logical time supplied by the timeline's injected clock. */
+    at: number;
+    value: T;
+}>;
+export type TimelineOptions = {
+    /** Logical clock used to stamp checkpoints. Defaults to a deterministic counter. */
+    now?: () => number;
+    /** Maximum retained checkpoints. Branch heads are never collected. Default 1,000. */
+    maxCheckpoints?: number;
+    /** Customize deterministic checkpoint IDs. */
+    id?: (sequence: number) => CheckpointId;
+};
+export type CommitOptions = {
+    branch?: string;
+    /** Parent checkpoint. Defaults to the selected branch's current head. */
+    parent?: CheckpointId | null;
+};
+export type ForkOptions = {
+    /** Checkpoint to fork from. Defaults to the main branch's head. */
+    from?: CheckpointId;
+};
+/**
+ * Small, storage-agnostic checkpoint DAG shared by service runtimes. Its values may be immutable
+ * records, namespace images, or copy-on-write SQL engine snapshots.
+ *
+ * Values are retained by reference. Engines can therefore use persistent/COW snapshots while
+ * simpler services can use immutable values. IDs and GC order are deterministic, and all IO
+ * (the logical clock) is injected.
+ */
+export declare class Timeline<T> {
+    readonly maxCheckpoints: number;
+    private readonly now;
+    private readonly makeId;
+    private readonly nodes;
+    private readonly heads;
+    /** Unreferenced nodes in the exact order they became collectible. */
+    private readonly evictable;
+    /** Branch heads plus explicit retainers. Absent means zero. */
+    private readonly references;
+    private readonly explicitPins;
+    private sequence;
+    constructor(options?: TimelineOptions);
+    /** Capture a new immutable value and move `branch` to it. */
+    commit(value: T, options?: CommitOptions): Checkpoint<T>;
+    /** Create a branch pointer without copying its checkpoint value. */
+    fork(branch: string, options?: ForkOptions): Checkpoint<T> | undefined;
+    /** Move a branch pointer to an existing checkpoint. */
+    checkout(branch: string, id: CheckpointId): Checkpoint<T>;
+    get(id: CheckpointId): Checkpoint<T>;
+    head(branch?: string): Checkpoint<T> | undefined;
+    hasBranch(branch: string): boolean;
+    branches(): Readonly<Record<string, CheckpointId>>;
+    checkpoints(): readonly Checkpoint<T>[];
+    /** Number of retained checkpoints without allocating an array. */
+    get size(): number;
+    /** Pin a checkpoint independently of branch heads (used by compatibility snapshot handles). */
+    retain(id: CheckpointId): Checkpoint<T>;
+    /** Release one explicit pin. Branch heads remain pinned until moved or deleted. */
+    release(id: CheckpointId): boolean;
+    deleteBranch(branch: string): boolean;
+    /**
+     * Deterministically discard oldest unpinned checkpoints. Collection is O(number removed):
+     * commits never scan pinned nodes or the retained history. Parents are metadata rather than a
+     * storage dependency, so a retained node remains usable after pruning.
+     */
+    gc(max?: number): CheckpointId[];
+    private collect;
+    private moveHead;
+    private addReference;
+    private removeReference;
+    private assertBranch;
+}
+//# sourceMappingURL=timeline.d.ts.map

package/dist/storage/database-state.d.ts

@@ -100,6 +100,16 @@ export interface TriggerMeta {
     funcArgs: string[];
 }
 export declare class TableData {
+    #private;
+    durableNextId: number;
+    durableEpoch: object | undefined;
+    durableUnsafe: boolean;
+    private durableIds;
+    enableDurabilityTracking(ids?: readonly number[], nextId?: number): void;
+    durableRowId(row: Datum[]): number;
+    disableDurabilityTracking(): void;
+    recordDurableRow(row: Datum[], previous?: Datum[]): void;
+    recordDurableDelete(row: Datum[]): void;
     name: string;
     schema: string;
     columns: ColumnMeta[];
@@ -119,9 +129,16 @@ export declare class TableData {
     shareCount: number;
     /** Derived unique/btree index maps; null until built or invalidated. */
     indexStores: Map<string, import("../indexes/index.js").IndexStore> | null;
+    /** DML replaces tuples; DDL must detach them before changing cells in place. */
+    private tuplesShared;
     constructor(schema: string, name: string, columns: ColumnMeta[], oid: number, temp?: boolean);
     rowCount(): number;
     rowAt(index: number): Datum[];
+    /** Replace an existing tuple without copying the array of unchanged row references. */
+    replaceRow(index: number, row: Datum[]): void;
+    private materializedRows;
+    private nativeRows;
+    private setNativeRows;
     /** All rows for scans; materializes slab once into `rows` when needed. */
     allRows(): Datum[][];
     attachSlab(slab: ColumnarSlab): void;
@@ -132,7 +149,12 @@ export declare class TableData {
     freeze(): void;
     thaw(): void;
     columnIndex(name: string): number;
+    private cloneMetadata;
     clone(): TableData;
+    /** DML creates new tuple arrays; retain existing tuples and xmin bindings until DDL. */
+    cloneForDml(): TableData;
+    /** A live DML fork can be unfrozen while its unchanged tuples still belong to history. */
+    ownTuples(): void;
     /** Independent writable copy (row tuples copied so ALTER COLUMN is isolated). */
     cloneForWrite(): TableData;
 }
@@ -324,6 +346,7 @@ export declare class DatabaseState {
     freezeShared(): void;
     thawShared(): void;
     ensureWritableTable(table: TableData): TableData;
+    ensureWritableTableForDml(table: TableData): TableData;
     ensureWritableSequence(seq: SequenceData): SequenceData;
     ensureWritableView(view: ViewData): ViewData;
     ensureWritableEnum(en: EnumData): EnumData;