@minnowdb/core 0.2.1 → 0.4.0

package/dist/engine/database.d.ts

@@ -1,18 +1,35 @@
 import { type BatchRow, type BatchValue, type InsertBatchInput } from "./batch.js";
 import { BufferedTableWriter, type BufferedWriterOptions } from "./buffered-writer.js";
-export { attachLifecycleFlush, BufferedTableWriter, type BufferedFlushResult, type BufferedWriterOptions, type LifecycleDocumentTarget, type LifecycleFlushOptions, type LifecycleFlushRequester, type LifecyclePageTarget, } from "./buffered-writer.js";
-import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MissingKeyError, SqlCompileError, UniqueConstraintError } from "./errors.js";
+export { attachLifecycleFlush, BufferedTableWriter, MAX_BUFFERED_WRITER_PENDING_ADDS, type BufferedFlushResult, type BufferedWriterOptions, type LifecycleDocumentTarget, type LifecycleFlushOptions, type LifecycleFlushRequester, type LifecyclePageTarget, } from "./buffered-writer.js";
+import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UniqueConstraintError, VisibleSegmentCursorStaleError } from "./errors.js";
 import { type Compression } from "../block-format/index.js";
-import { type BlockStore, type ColumnDefault, type CompactionJobRecord, type CompactionJobState, type GarbageCollectionJobRecord, type GarbageCollectionJobState, type SimpleDataType, type SnapshotExportProgress, type SnapshotLoadProgress } from "../storage/index.js";
-import { type CompiledQuery, type CompiledStatement, type ForeignKeyDefinition, type QueryResult, type QueryRow, type QueryValue } from "./query.js";
+import { type BlockStore, type ColumnDefault, CompactionBacklogError, type CompactionJobRecord, type CompactionJobState, type GarbageCollectionJobRecord, type GarbageCollectionJobState, type SimpleDataType, type SqlDomain, type StorageIntegrityMode, type StorageIntegrityReport, type StorageStats, type InterruptedSnapshotImport, type InterruptedSnapshotImportAbortResult, TableInUseError } from "../storage/types.js";
+import type { SnapshotExportProgress, SnapshotLoadProgress } from "../storage/snapshot.js";
+import { type CompiledQuery, type CompiledStatement, type ForeignKeyDefinition, type QueryResult, type QueryRow, type QueryValue, type UniqueConstraintDefinition } from "./query.js";
 import { LiveQuerySet, type LiveQuerySetOptions } from "./live.js";
 import { type Catalog } from "./catalog.js";
 import { type AnyTable, type MigrationStep, type SchemaDefinition } from "./schema.js";
+/** Nested SQL savepoints and their total cloned transaction state are both hard bounded. */
+export declare const MAX_TRANSACTION_SAVEPOINTS = 64;
+export declare const MAX_TRANSACTION_SAVEPOINT_BYTES: number;
+/** Outstanding simple writes retained by one database instance before callers must await. */
+export declare const MAX_DATABASE_PENDING_WRITES = 64;
+/** Concurrent direct reads retained by one database instance. Reads still execute in parallel. */
+export declare const MAX_DATABASE_ACTIVE_READS = 256;
+export declare class DatabaseReadBacklogError extends Error {
+    readonly limit: number;
+    readonly name = "DatabaseReadBacklogError";
+    constructor(limit?: number);
+}
 export interface ColumnDefinition {
     name: string;
     type: SimpleDataType;
+    /** SQL integer-domain guard; ordinary API number columns remain finite Float64 values. */
+    integer?: true;
+    /** PostgreSQL logical domain over the primitive storage type. */
+    sqlDomain?: SqlDomain;
     nullable?: boolean;
-    /** Fills null-or-absent slots at insert time; never applied at read time. */
+    /** Fills omitted or SQL DEFAULT slots at insert time; never applied at read time. */
     defaultValue?: ColumnDefault;
     /** String columns only: the closed set of values writes must draw from. */
     enumValues?: readonly string[];
@@ -33,6 +50,14 @@ export interface MigrateOptions {
      */
     readonly schemaOwnsDatabase?: boolean;
 }
+export interface MigrateResult {
+    createdTables: string[];
+    alteredTables: string[];
+    droppedTables: string[];
+    replacedViews: string[];
+    droppedViews: string[];
+    steps: MigrationStep[];
+}
 export interface CreateTableInput {
     name: string;
     columns: readonly ColumnDefinition[];
@@ -43,9 +68,13 @@ export interface CreateTableInput {
     }>;
     /** Marks the table as created from a schema, which lets a later migration drop it. */
     managed?: boolean;
-    /** Single-column references to another table's unique key (E141-04). */
+    /** References to a parent PRIMARY/unique row-addressing key. */
     foreignKeys?: readonly ForeignKeyDefinition[];
     uniqueKey?: string;
+    /** PostgreSQL composite PRIMARY KEY, backed by a hidden canonical tuple locator. */
+    compositePrimaryKey?: readonly string[];
+    /** Independently enforced PostgreSQL UNIQUE constraints. */
+    uniqueConstraints?: readonly UniqueConstraintDefinition[];
 }
 export type { BatchRow, BatchValue, ColumnarBatch, InsertBatchInput } from "./batch.js";
 export interface InsertBatchResult {
@@ -67,7 +96,9 @@ export interface UpsertBatchResult extends InsertBatchResult {
     updatedRowCount: number;
 }
 export interface UpdateBatchInput {
+    /** Stable ordinary arrays; do not mutate or expose changing accessors until the write settles. */
     keys: readonly BatchValue[];
+    /** Stable ordinary arrays; do not mutate or expose changing accessors until the write settles. */
     changes: Readonly<Record<string, readonly BatchValue[]>>;
 }
 export interface UpdateBatchResult {
@@ -145,9 +176,7 @@ export interface WriteSession {
      * Read-your-writes: the query observes the pre-scope snapshot PLUS everything this scope
      * has staged so far, ordered after all committed data — without publishing anything.
      */
-    query(sql: string, options?: {
-        params?: QueryOptions["params"];
-    }): Promise<QueryResult>;
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
     /** Runs a SELECT, INSERT, UPDATE, or DELETE inside this write scope. */
     execute(sql: string, params?: readonly QueryValue[]): Promise<ExecuteResult>;
     insertBatch(tableName: string, input: InsertBatchInput): Promise<StagedWriteResult>;
@@ -165,6 +194,27 @@ export interface QueryExecutionStats {
      */
     readonly peakMemoryBytes: number;
 }
+export interface MaintenanceStatus {
+    readonly autoCollectionEnabled: boolean;
+    readonly collectionRunning: boolean;
+    readonly collectionRequested: boolean;
+    /** Commits since collection last proved there was no immediately reclaimable work. */
+    readonly pendingCommitDebt: number;
+    readonly consecutiveFailures: number;
+    /** In-memory posting-tail retry markers; bounded and cleared with their catalog owner. */
+    readonly postingDeltaTailMarkers: number;
+    /** SQL text caches retain only inputs below the fixed cacheability ceiling. */
+    readonly retainedPlanEntries: number;
+    readonly retainedStatementEntries: number;
+    readonly lastStartedAt: Date | null;
+    readonly lastCompletedAt: Date | null;
+    readonly nextRetryAt: Date | null;
+    readonly lastError: {
+        readonly name: string;
+        readonly message: string;
+        readonly at: Date;
+    } | null;
+}
 export interface QueryOptions {
     /**
      * Called once with what this execution cost, before the result is returned. Additive and
@@ -201,7 +251,14 @@ export interface QueryOptions {
     /** Maximum rows encoded in each merged spill page. */
     readonly spillPageRows?: number;
 }
+export interface QueryCursorOptions extends QueryOptions {
+    /** Maximum rows in one yielded result batch. Defaults to the vector scan batch size. */
+    readonly batchRows?: number;
+    /** Cancels the scan and releases its snapshot lease. */
+    readonly signal?: AbortSignal;
+}
 export interface DeleteBatchInput {
+    /** Stable ordinary array; do not mutate or expose changing accessors until the write settles. */
     keys: readonly BatchValue[];
 }
 export interface DeleteBatchResult {
@@ -215,8 +272,6 @@ export interface DeleteBatchResult {
     metrics: WriteMetrics;
 }
 export interface CompactTableOptions {
-    /** @deprecated Use minimumLevel0Segments. */
-    minimumSegments?: number;
     /** Minimum L0 segments promoted; one also permits a direct L0 -> L2 promotion. */
     minimumLevel0Segments?: number;
     /** Target maximum L0 segments promoted by one job. Equal-order groups remain indivisible. */
@@ -327,6 +382,7 @@ export interface CollectGarbageStepOptions {
     /** See `CollectGarbageOptions.retainRecentVersions`; applies when this step plans a job. */
     retainRecentVersions?: number;
 }
+export declare const MAX_GARBAGE_COLLECTION_RETAIN_RECENT_VERSIONS = 1024;
 export interface GarbageCollectionResult {
     jobId: string;
     prunedManifestCount: number;
@@ -359,7 +415,7 @@ export interface TableDefinition {
     uniqueKey?: string;
 }
 export type DatabaseRow = Record<string, Exclude<BatchValue, null> | null>;
-export { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MissingKeyError, SqlCompileError, UniqueConstraintError, };
+export { CompactionBacklogError, CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, TableInUseError, UniqueConstraintError, VisibleSegmentCursorStaleError, };
 export interface MinnowDatabaseOptions {
     /**
      * Block codec for newly written blocks; defaults to "gzip", which is also what compaction
@@ -373,12 +429,20 @@ export interface MinnowDatabaseOptions {
      * storage quota; the browser usually makes the opposite trade worth it.
      */
     compression?: Compression;
+    /**
+     * Target maximum uncompressed bytes in a newly written column block. `rowsPerBlock` remains a
+     * second ceiling. A single value may exceed this target when it still fits the format's 64 MiB
+     * hard limit. Defaults to 2 MiB, matching compaction output.
+     */
+    targetBlockBytes?: number;
     rowsPerBlock?: number;
     maxCommitRetries?: number;
     now?: () => Date;
     createId?: () => string;
     /** Durable spill-owner lease lifetime; renewed while a spilling query runs. */
     spillOwnerLeaseMs?: number;
+    /** Durable active-writer deadline; renewed every third while the writer is live. */
+    transactionOwnerLeaseMs?: number;
     /**
      * How long a statement-level transaction (`BEGIN` … `COMMIT`) may sit untouched before it
      * rolls itself back; 30 seconds by default. A scope nobody ever closes would otherwise hold
@@ -394,6 +458,12 @@ export interface MinnowDatabaseOptions {
      * LRU. 0 disables the pool. Defaults to 64 MiB.
      */
     bufferPoolBytes?: number;
+    /**
+     * Default modeled execution-memory budget for every query, including mutation selection,
+     * triggers, subqueries, and read-your-writes scopes. Eligible sorts and groups spill
+     * automatically. Defaults to 64 MiB; `null` explicitly restores unbounded mode.
+     */
+    executionMemoryBudgetBytes?: number | null;
     /**
      * Visible-row threshold at which a full-text MATCH on an unindexed append-only column
      * schedules a background index build (fire-and-forget; correctness never waits on it).
@@ -412,10 +482,15 @@ export interface MinnowDatabaseOptions {
      * Background collection: a garbage-collection pass after every background fold, and one
      * every 64 commits, each keeping the 64 most recent versions readable. Without it the
      * blocks a fold supersedes and the manifest every commit writes stay on disk until the
-     * caller runs `collectGarbage`. Defaults to `autoCompact`; false leaves collection to the
-     * caller.
+     * caller runs `collectGarbage`. Defaults to true independently of compaction; false leaves
+     * collection to the caller.
      */
     autoCollect?: boolean;
+    /**
+     * Successful commits tolerated while automatic collection is failing before a foreground
+     * write assists and, if maintenance still fails, is refused. Defaults to 4096.
+     */
+    autoCollectDebtLimitCommits?: number;
     /**
      * Defaults for every compaction this database plans, background folds included. A call's
      * own `CompactTableOptions` override them.
@@ -440,10 +515,33 @@ export type ExecuteResult = {
 } | {
     kind: "create-table";
     table: string;
+} | {
+    kind: "create-type";
+    name: string;
+} | {
+    kind: "create-sequence";
+    name: string;
+} | {
+    kind: "create-index";
+    index: string;
+    table: string;
+    /** First key column, retained for compatibility with the original single-column result. */
+    column: string;
+    columns: string[];
+    unique: boolean;
+} | {
+    kind: "drop-index";
+    index: string;
+    dropped: boolean;
 } | {
     kind: "add-column";
     table: string;
     column: string;
+} | {
+    kind: "drop-column";
+    table: string;
+    column: string;
+    dropped: boolean;
 } | {
     kind: "drop-table";
     table: string;
@@ -455,7 +553,8 @@ export type ExecuteResult = {
     version?: number;
 } | {
     kind: "transaction";
-    action: "begin" | "commit" | "rollback";
+    action: "begin" | "commit" | "rollback" | "savepoint" | "rollback-to" | "release";
+    name?: string;
     version?: number;
 } | {
     kind: "create-view";
@@ -517,18 +616,67 @@ export interface VisibleSegment {
     rowCount: number;
     columnBlockIds: Readonly<Record<string, readonly string[]>>;
 }
+export interface VisibleSegmentPageRecord extends VisibleSegment {
+    /** Stable logical scan order, exposed so bounded-page consumers can order a completed fold. */
+    readonly logicalOrder: number;
+    /** The commit that made the segment eligible at the captured manifest version. */
+    readonly committedVersion: number;
+    /** Stable order among segments from the same commit. */
+    readonly commitOrdinal: number;
+}
+/** One public segment-inspection page; kept small for direct and worker callers alike. */
+export declare const MAX_VISIBLE_SEGMENT_PAGE_ITEMS = 64;
+/**
+ * Opaque continuation state for a visible-segment scan. The manifest version and table identity
+ * are captured on the first page, so later commits cannot move an in-progress scan onto different
+ * data. Dropping or replacing the table makes this cursor stale and fails the next page.
+ */
+export interface VisibleSegmentPageCursor {
+    readonly tableName: string;
+    readonly tableId: string;
+    readonly version: number | null;
+    readonly afterId: string;
+}
+export interface VisibleSegmentPageOptions {
+    /** First page only. Omit for the current committed version; null names the empty version. */
+    readonly version?: number | null;
+    /** Use the exact cursor returned by the previous page; do not combine with `version`. */
+    readonly cursor?: VisibleSegmentPageCursor;
+    /** Defaults to and may not exceed MAX_VISIBLE_SEGMENT_PAGE_ITEMS. */
+    readonly limit?: number;
+}
+export interface VisibleSegmentPage {
+    /** Visible records from this bounded physical segment-ID window, in lexical ID order. */
+    readonly records: VisibleSegmentPageRecord[];
+    /** The exact manifest version captured for every page in this scan. */
+    readonly version: number | null;
+    /** May be non-null when `records` is empty because historical records were filtered out. */
+    readonly nextCursor: VisibleSegmentPageCursor | null;
+}
 export interface SnapshotExportOptions {
     /** Called as the export moves through its phases; see SnapshotExportProgress. */
     onProgress?: (progress: SnapshotExportProgress) => void;
+    /** Cancels transfer and releases the durable export pin. */
+    signal?: AbortSignal;
 }
 export interface SnapshotImportOptions {
     /** Called as blocks land, for a progress bar over a multi-megabyte file. */
     onProgress?: (progress: SnapshotLoadProgress) => void;
+    /** Cancels transfer and atomically removes this caller's staged import. */
+    signal?: AbortSignal;
 }
 export declare class MinnowDatabase {
     #private;
     private readonly store;
     constructor(store: BlockStore, options?: MinnowDatabaseOptions);
+    /**
+     * Stops timers and background scheduling, rolls back an abandoned statement transaction,
+     * closes live-query resources, releases the engine's reader lease, and drops resident caches.
+     * The injected block store remains caller-owned and must be closed separately.
+     */
+    close(): Promise<void>;
+    /** Current background-collection health, returned as a defensive snapshot. */
+    maintenanceStatus(): MaintenanceStatus;
     createTable(input: CreateTableInput): Promise<void>;
     /**
      * The published catalog: stable column IDs, key identity, constraints, triggers, and view
@@ -551,6 +699,14 @@ export declare class MinnowDatabase {
     dropView(name: string, options?: {
         ifExists?: boolean;
     }): Promise<boolean>;
+    /**
+     * Drops one non-key column in one storage transaction: catalog metadata and segment references
+     * change with the successor manifest that retires the column's exclusively owned live blocks.
+     * Payload bytes remain readable to historical leases until ordinary collection reclaims them.
+     */
+    dropColumn(tableName: string, columnName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<boolean>;
     /**
      * Drops a table: its rows, its catalog record, its full-text index, and its triggers. The
      * blocks are retired through an ordinary commit rather than deleted, so a reader pinned to an
@@ -586,6 +742,12 @@ export declare class MinnowDatabase {
     snapshot<T>(action: (session: SnapshotSession) => Promise<T>): Promise<T>;
     /** Executes a read-only SELECT statement through the public query API. */
     query(sql: string, options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Pull-driven query batches. Cursor-safe scans emit directly from vector batches; blocking
+     * plans (sorts, groups, joins, derived sources) use the ordinary correct execution and page
+     * its result. In both cases the iterator applies backpressure and owns one snapshot at a time.
+     */
+    queryCursor(sql: string, options?: QueryCursorOptions): AsyncIterableIterator<QueryResult, undefined>;
     /**
      * Reclaims temp spill pages whose owner lease is expired or missing at a cutoff fixed when the
      * pass starts. Owners with an unexpired lease are retained; each owner is removed atomically
@@ -596,7 +758,8 @@ export declare class MinnowDatabase {
      * Creates a live-query set over this database. Local commits hint it directly, an optional
      * channel carries cross-tab hints, and an optional poll interval bounds staleness without any
      * hint; every hint path converges on the durable manifest version, so missed messages delay a
-     * refresh but never produce a stale result. Subscriptions retain a result digest, not rows.
+     * refresh but never produce a stale result. Equal subscriptions retain one private exact
+     * result snapshot plus a digest that rejects most inequality before exact comparison.
      */
     liveQueries(options?: LiveQuerySetOptions): LiveQuerySet;
     /**
@@ -625,14 +788,7 @@ export declare class MinnowDatabase {
      * steps — and every catalog alteration is one atomic compare-and-swap, so a concurrent
      * migrator fails explicitly with a conflict instead of interleaving.
      */
-    migrate(definition: SchemaDefinition<readonly AnyTable[]>, options?: MigrateOptions): Promise<{
-        createdTables: string[];
-        alteredTables: string[];
-        droppedTables: string[];
-        replacedViews: string[];
-        droppedViews: string[];
-        steps: MigrationStep[];
-    }>;
+    migrate(definition: SchemaDefinition<readonly AnyTable[]>, options?: MigrateOptions): Promise<MigrateResult>;
     /**
      * Renders the optimized logical plan for a SELECT statement plus the physical strategy notes
      * the prepared execution would choose, without executing it.
@@ -654,27 +810,41 @@ export declare class MinnowDatabase {
      * (the snapshot row with assignments applied — the exact values the mutation wrote).
      */
     runStatement(statement: CompiledStatement, options?: RunStatementOptions): Promise<ExecuteResult>;
-    listVisibleSegments(tableName: string, version?: number): Promise<VisibleSegment[]>;
     /**
-     * Copies the current committed version out as a portable snapshot file — the byte array
-     * `../storage/snapshot.ts` describes, which `importSnapshot()` loads back into any store.
-     *
-     * The bytes are the unit here rather than the structured `DatabaseSnapshot` the store returns,
-     * because that is what a caller does with a snapshot: write it to disk, hand it to a colleague,
-     * ship it as an asset. Reach for `store.exportSnapshot()` directly when you want the records
-     * instead. Either way the whole snapshot is materialized in memory, so a database of hundreds
-     * of megabytes needs the headroom for a copy of itself.
-     *
-     * Stores differ in how they hold still while this runs: see the note on exporting safely in the
-     * snapshots guide.
+     * Inspects exactly one bounded physical segment-ID window at a stable manifest version.
+     * Historical records that are not visible are filtered rather than replaced from later
+     * windows, so callers must follow `nextCursor` even when a page returns no records.
+     */
+    listVisibleSegmentPage(tableName: string, options?: VisibleSegmentPageOptions): Promise<VisibleSegmentPage>;
+    /**
+     * Collects the pull-driven framed snapshot stream into one portable byte array. This helper is
+     * convenient for small and medium databases, but it necessarily retains the complete file and
+     * has the Uint8Array 4-GiB ceiling. Use `exportSnapshotStream()` for larger databases or direct
+     * file/network transfer. See the snapshots guide for framing and durability guarantees.
      */
     exportSnapshot(options?: SnapshotExportOptions): Promise<Uint8Array>;
+    /**
+     * Streams one pinned committed snapshot with at most one payload block resident. Stopping the
+     * iterator releases its durable backup lease in `finally`.
+     */
+    exportSnapshotStream(options?: SnapshotExportOptions): AsyncGenerator<Uint8Array, void, void>;
     /**
      * Loads a snapshot file into this database's store, which must be empty. Every block is
-     * authenticated while decoding, so a corrupt file fails here rather than mid-query, and a store
-     * that already holds a database throws rather than merging two histories.
+     * integrity-checked while decoding, so a corrupt file fails here rather than mid-query, and a
+     * store that already holds a database throws rather than merging two histories.
      */
     importSnapshot(bytes: Uint8Array, options?: SnapshotImportOptions): Promise<void>;
+    /** Incrementally validates and stages a snapshot; only the final adapter CAS makes it visible. */
+    importSnapshotStream(source: AsyncIterable<Uint8Array>, options?: SnapshotImportOptions): Promise<void>;
+    /** Verifies adapter metadata, or metadata plus every live payload, without changing storage. */
+    checkIntegrity(options?: {
+        mode?: StorageIntegrityMode;
+        maxIssues?: number;
+    }): Promise<StorageIntegrityReport>;
+    /** Explicit, potentially storage-scanning accounting for live, obsolete, temp, and WAL bytes. */
+    storageStats(): Promise<StorageStats>;
+    inspectInterruptedImport(): Promise<InterruptedSnapshotImport | null>;
+    abortInterruptedImport(identity: string): Promise<InterruptedSnapshotImportAbortResult>;
     compactTable(tableName: string, options?: CompactTableOptions): Promise<CompactTableResult>;
     /** Plans or advances one restart-safe physical compaction job. */
     compactTableStep(tableName: string, options?: CompactTableStepOptions): Promise<CompactionJobProgress>;
@@ -698,6 +868,22 @@ export declare class MinnowDatabase {
      * derived results, memoized results). Use it to size bufferPoolBytes from real workloads.
      */
     bufferPoolStats(): BufferPoolStats;
+    /**
+     * Creates and fully builds a durable secondary index. The catalog's global
+     * index-name namespace matches the SQL DDL: a duplicate name is rejected even on another
+     * table. The building state makes the operation crash-safe; readers scan until the base and
+     * every concurrent commit delta are known to be covered.
+     */
+    createIndex(indexName: string, tableName: string, requestedColumns: string | ReadonlyArray<{
+        name: string;
+        direction: "asc" | "desc";
+    }>, options?: {
+        unique?: boolean;
+    }): Promise<void>;
+    /** Drops one globally named secondary index. */
+    dropIndex(indexName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<boolean>;
     /**
      * Builds (or rebuilds) the persisted full-text pruning index for one column from the current
      * snapshot. Append-only tables only. The planner consults the index when the column is
@@ -707,4 +893,3 @@ export declare class MinnowDatabase {
      */
     buildFtsIndex(tableName: string, columnName: string): Promise<void>;
 }
-//# sourceMappingURL=database.d.ts.map