@minnowdb/core 0.5.0 → 0.6.1

package/README.md

@@ -8,8 +8,9 @@ npm install @minnowdb/core
 ```
 
 - Direct SQL through `MinnowDatabase.query()` and `execute()`.
-- Joins, CTEs, window functions, grouping sets, upserts, `RETURNING`, triggers, exact decimals,
-  JSON/JSONB, zoneless DATE, arrays, enums, sequences, and savepoints.
+- Joins, CTEs, window functions, grouping sets, nested correlated subqueries, subquery-backed
+  mutations, upserts, `RETURNING`, triggers, exact decimals, nested JSON/JSONB, stored generated
+  columns, zoneless DATE, arrays, enums, sequences, and savepoints.
 - Compressed column storage, secondary indexes, full-text search, and snapshot reads.
 - Atomic writes across tabs through IndexedDB or OPFS, strict durability by default, and explicit
   origin-eviction persistence policy.

package/dist/engine/cancellation.d.ts

@@ -0,0 +1,2 @@
+/** One compact check shared by every bounded query-execution path. */
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;

package/dist/engine/cancellation.js

@@ -0,0 +1,4 @@
+/** One compact check shared by every bounded query-execution path. */
+export function throwIfAborted(signal) {
+    signal?.throwIfAborted();
+}

package/dist/engine/catalog.d.ts

@@ -1,4 +1,4 @@
-import { type ColumnDefault, type SecondaryIndexState, type SimpleDataType, type SqlDomain, type TableRecord } from "../storage/types.js";
+import { type ColumnDefault, type ColumnGenerated, type SecondaryIndexState, type SimpleDataType, type SqlDomain, type TableRecord } from "../storage/types.js";
 /**
  * The published shape of the catalog: everything a schema tool needs to diff a live database
  * against a desired schema, without reading engine internals.
@@ -20,6 +20,8 @@ export interface CatalogColumn {
     readonly nullable: boolean;
     /** Filled for omitted or SQL DEFAULT insert slots; never applied at read time. */
     readonly defaultValue?: ColumnDefault;
+    /** Stored expression maintained by the engine; callers cannot assign this column. */
+    readonly generatedValue?: ColumnGenerated;
     /** String columns only: the closed set of values writes may draw from. */
     readonly enumValues?: readonly string[];
     /** Derived from the default spec, because a planner should not have to decode one. */

package/dist/engine/catalog.js

@@ -9,6 +9,7 @@ function toCatalogColumn(column) {
         ...(column.sqlDomain === undefined ? {} : { sqlDomain: structuredClone(column.sqlDomain) }),
         nullable: column.nullable,
         ...(column.defaultValue === undefined ? {} : { defaultValue: column.defaultValue }),
+        ...(column.generatedValue === undefined ? {} : { generatedValue: column.generatedValue }),
         ...(column.enumValues === undefined ? {} : { enumValues: [...column.enumValues] }),
         ...(column.backfill === undefined
             ? {}

package/dist/engine/client.d.ts

@@ -1,7 +1,7 @@
 import { type CompactionJobRecord, type GarbageCollectionJobRecord, type StorageIntegrityMode, type StorageIntegrityReport, type StorageStats, type InterruptedSnapshotImport, type InterruptedSnapshotImportAbortResult } from "../storage/types.js";
 import { type BatchRow, type InsertBatchInput } from "./batch.js";
 import type { Catalog } from "./catalog.js";
-import type { BatchValue, BufferPoolStats, StagedWriteResult, BufferedFlushResult, BufferedWriterOptions, CancelCompactionJobResult, CollectGarbageOptions, CollectGarbageStepOptions, CompactTableOptions, CompactTableResult, CompactTableStepOptions, CompactionJobProgress, CreateTableInput, DatabaseRow, MigrateOptions, DeleteBatchInput, DeleteBatchResult, ExecuteResult, GarbageCollectionProgress, GarbageCollectionResult, MaintenanceStatus, InsertBatchResult, QueryOptions, QueryCursorOptions, QuerySpillCleanupOptions, QuerySpillCleanupResult, ReadTableOptions, RunStatementOptions, SnapshotExportOptions, SnapshotImportOptions, TableDefinition, UpdateBatchInput, UpdateBatchResult, UpsertBatchResult, UpsertOptions, VisibleSegmentPage, VisibleSegmentPageOptions } from "./database.js";
+import type { BatchValue, BufferPoolStats, StagedWriteResult, BufferedFlushResult, BufferedWriterOptions, CancelCompactionJobResult, CollectGarbageOptions, CollectGarbageStepOptions, CompactTableOptions, CompactTableResult, CompactTableStepOptions, CompactionJobProgress, CreateTableInput, DatabaseRow, MigrateOptions, DeleteBatchInput, DeleteBatchResult, ExecuteResult, GarbageCollectionProgress, GarbageCollectionResult, MaintenanceStatus, InsertBatchResult, QueryOptions, QueryExecutionStats, QueryCursorOptions, QuerySpillCleanupOptions, QuerySpillCleanupResult, ReadTableOptions, RunStatementOptions, SnapshotExportOptions, SnapshotImportOptions, TableDefinition, UpdateBatchInput, UpdateBatchResult, UpsertBatchResult, UpsertOptions, VisibleSegmentPage, VisibleSegmentPageOptions } from "./database.js";
 import type { LiveQueryInput, LiveQueryInvalidation, LiveQueryObserveOptions, LiveQueryStats, LiveQuerySubscribeOptions } from "./live.js";
 import type { CompiledQuery, CompiledStatement, QueryResult, QueryValue } from "./query.js";
 import type { AnyTable, SchemaDefinition } from "./schema.js";
@@ -65,6 +65,11 @@ interface EventRoute {
     onComplete?: () => void;
     /** Payload shape is the handle's own; only snapshot loads emit these today. */
     onProgress?: (progress: unknown) => void;
+    onStats?: (stats: QueryExecutionStats) => void;
+}
+interface RpcCallControls {
+    signal?: AbortSignal | undefined;
+    onStats?: ((stats: QueryExecutionStats) => void) | undefined;
 }
 export declare class MinnowDatabaseClient {
     #private;
@@ -72,6 +77,29 @@ export declare class MinnowDatabaseClient {
     /** Resolves once the worker has opened the store and constructed the database. */
     ready(): Promise<void>;
     createTable(input: CreateTableInput): Promise<void>;
+    createView(name: string, sql: string, options?: {
+        orReplace?: boolean;
+        managed?: boolean;
+    }): Promise<void>;
+    dropView(name: string, options?: {
+        ifExists?: boolean;
+    }): Promise<boolean>;
+    dropColumn(tableName: string, columnName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<boolean>;
+    dropTable(tableName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<boolean>;
+    createIndex(indexName: string, tableName: string, requestedColumns: string | ReadonlyArray<{
+        name: string;
+        direction: "asc" | "desc";
+    }>, options?: {
+        unique?: boolean;
+    }): Promise<void>;
+    dropIndex(indexName: string, options?: {
+        ifExists?: boolean;
+    }): Promise<boolean>;
+    buildFtsIndex(tableName: string, columnName: string): Promise<void>;
     /** The published catalog; see `MinnowDatabase.introspect()`. */
     introspect(): Promise<Catalog>;
     listTables(): Promise<TableDefinition[]>;
@@ -166,6 +194,8 @@ export declare class MinnowDatabaseClient {
     /** @internal */
     _invoke(handleId: string, method: string, args: unknown[]): Promise<unknown>;
     /** @internal */
+    _invokeControlled(handleId: string, method: string, args: unknown[], controls: RpcCallControls): Promise<unknown>;
+    /** @internal */
     _routeEvents(handleId: string, route: EventRoute): void;
     /** @internal */
     _unrouteEvents(handleId: string): void;
@@ -177,9 +207,7 @@ export declare class MinnowDatabaseClient {
 /** The scope handed to the client `write()`; mirrors the in-worker WriteSession. */
 export interface ClientWriteSession {
     /** Read-your-writes: observes the pre-scope snapshot plus everything staged so far. */
-    query(sql: string, options?: {
-        params?: QueryValue[];
-    }): Promise<QueryResult>;
+    query(sql: string, options?: QueryOptions): Promise<QueryResult>;
     execute(sql: string, params?: readonly QueryValue[]): Promise<ExecuteResult>;
     insertBatch(tableName: string, input: InsertBatchInput): Promise<StagedWriteResult>;
     upsertBatch(tableName: string, input: InsertBatchInput): Promise<StagedWriteResult>;

package/dist/engine/client.js

@@ -2,7 +2,7 @@ import { BlockReadBatchTooLargeError, CompactionBacklogError, CompactionJobConfl
 import { MAX_SNAPSHOT_STREAM_CHUNK_BYTES } from "../storage/snapshot.js";
 import { parseRpcResponse, MAX_DATABASE_RPC_IN_FLIGHT, protocolVersion, } from "../worker-protocol/index.js";
 import { toColumnarBatch } from "./batch.js";
-import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError, } from "./errors.js";
+import { CompactionJobCancelledError, CompactionMemoryBudgetError, CompactionWriteAmplificationError, MaintenanceBacklogError, DatabaseReadBacklogError, LiveQueryLimitError, MissingKeyError, SqlCompileError, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError, } from "./errors.js";
 import { QueryMemoryBudgetError } from "./memory.js";
 import { decodeQueryResult } from "./result-wire.js";
 import { serializeSchema } from "./schema-wire.js";
@@ -36,6 +36,8 @@ const errorRegistry = new Map([
     CompactionWriteAmplificationError,
     CompactionJobCancelledError,
     MaintenanceBacklogError,
+    DatabaseReadBacklogError,
+    LiveQueryLimitError,
     SqlCompileError,
     QueryMemoryBudgetError,
     VisibleSegmentCursorStaleError,
@@ -142,6 +144,27 @@ export class MinnowDatabaseClient {
     async createTable(input) {
         await this.#call("createTable", [input]);
     }
+    async createView(name, sql, options = {}) {
+        await this.#call("createView", [name, sql, options]);
+    }
+    async dropView(name, options = {}) {
+        return (await this.#call("dropView", [name, options]));
+    }
+    async dropColumn(tableName, columnName, options = {}) {
+        return (await this.#call("dropColumn", [tableName, columnName, options]));
+    }
+    async dropTable(tableName, options = {}) {
+        return (await this.#call("dropTable", [tableName, options]));
+    }
+    async createIndex(indexName, tableName, requestedColumns, options = {}) {
+        await this.#call("createIndex", [indexName, tableName, requestedColumns, options]);
+    }
+    async dropIndex(indexName, options = {}) {
+        return (await this.#call("dropIndex", [indexName, options]));
+    }
+    async buildFtsIndex(tableName, columnName) {
+        await this.#call("buildFtsIndex", [tableName, columnName]);
+    }
     /** The published catalog; see `MinnowDatabase.introspect()`. */
     async introspect() {
         return (await this.#call("introspect", []));
@@ -201,17 +224,17 @@ export class MinnowDatabaseClient {
      * datetimes) and are rebuilt into row objects here; see `result-wire.ts`.
      */
     async query(sql, options) {
-        return decodeQueryResult(await this.#call("query", options === undefined ? [sql] : [sql, options]));
+        const { signal, onStats, ...wireOptions } = options ?? {};
+        return decodeQueryResult(await this.#call("query", [sql, wireOptions, onStats !== undefined], { signal, onStats }));
     }
     /** Pulls one transferred columnar page at a time, preserving worker backpressure. */
     queryCursor(sql, options = {}) {
         const call = this.#call.bind(this);
         const invoke = this._invoke.bind(this);
+        const routeEvents = this._routeEvents.bind(this);
+        const unrouteEvents = this._unrouteEvents.bind(this);
         const handleId = crypto.randomUUID();
         const { signal, onStats, ...wireOptions } = options;
-        if (onStats !== undefined) {
-            throw new TypeError("Query cursor onStats callbacks are not available across a worker");
-        }
         async function* batches() {
             let opened = false;
             let closing;
@@ -225,9 +248,11 @@ export class MinnowDatabaseClient {
                 void close();
             };
             signal?.addEventListener("abort", onAbort, { once: true });
+            if (onStats !== undefined)
+                routeEvents(handleId, { onStats });
             try {
                 signal?.throwIfAborted();
-                await call("queryCursorOpen", [handleId, sql, wireOptions]);
+                await call("queryCursorOpen", [handleId, sql, wireOptions, onStats !== undefined]);
                 opened = true;
                 if (signal?.aborted === true) {
                     await close();
@@ -243,6 +268,7 @@ export class MinnowDatabaseClient {
             finally {
                 signal?.removeEventListener("abort", onAbort);
                 await close();
+                unrouteEvents(handleId);
             }
         }
         return batches();
@@ -291,7 +317,10 @@ export class MinnowDatabaseClient {
         const opened = (await this.#call("writeOpen", []));
         const stage = (op, tableName, input) => this._invoke(opened.handleId, "stage", [op, tableName, input]);
         const session = {
-            query: async (sql, options) => decodeQueryResult(await this._invoke(opened.handleId, "query", [sql, options])),
+            query: async (sql, options = {}) => {
+                const { signal, onStats, ...wireOptions } = options;
+                return decodeQueryResult(await this._invokeControlled(opened.handleId, "query", [sql, wireOptions, onStats !== undefined], { signal, onStats }));
+            },
             execute: (sql, params) => this._invoke(opened.handleId, "execute", params === undefined ? [sql] : [sql, params]),
             insertBatch: (tableName, input) => stage("insertBatch", tableName, input),
             upsertBatch: (tableName, input) => stage("upsertBatch", tableName, input),
@@ -502,6 +531,12 @@ export class MinnowDatabaseClient {
         return this.#post("rpc-call", handleId, method, args);
     }
     /** @internal */
+    async _invokeControlled(handleId, method, args, controls) {
+        if (this.#closed)
+            throw new Error("Database client is closed");
+        return this.#post("rpc-call", handleId, method, args, undefined, false, controls);
+    }
+    /** @internal */
     _routeEvents(handleId, route) {
         this.#events.set(handleId, route);
     }
@@ -509,23 +544,49 @@ export class MinnowDatabaseClient {
     _unrouteEvents(handleId) {
         this.#events.delete(handleId);
     }
-    async #call(method, args) {
+    async #call(method, args, controls = {}) {
         if (this.#closed)
             throw new Error("Database client is closed");
-        return this.#post("rpc-call", null, method, args);
+        return this.#post("rpc-call", null, method, args, undefined, false, controls);
     }
-    async #post(kind, handleId, method, args, transfer, bypassLimit = kind === "rpc-init" || method === "dispose") {
+    async #post(kind, handleId, method, args, transfer, bypassLimit = kind === "rpc-init" || method === "dispose", controls = {}) {
         if (this.#fatal !== undefined)
             throw this.#fatal;
+        controls.signal?.throwIfAborted();
         if (!bypassLimit && this.#pending.size >= MAX_DATABASE_RPC_IN_FLIGHT) {
             throw new RangeError(`A database worker connection cannot hold more than ${String(MAX_DATABASE_RPC_IN_FLIGHT)} in-flight requests`);
         }
         const requestId = crypto.randomUUID();
         return new Promise((resolve, reject) => {
-            this.#pending.set(requestId, { resolve, reject });
-            this.#transport.postMessage(kind === "rpc-init"
-                ? { version: protocolVersion, requestId, kind, payload: args[0] }
-                : { version: protocolVersion, requestId, kind, handleId, method, args }, transfer === undefined ? undefined : { transfer });
+            const onAbort = () => {
+                try {
+                    this.#transport.postMessage({ version: protocolVersion, requestId, kind: "rpc-cancel" });
+                }
+                catch {
+                    // The original RPC still owns completion. A transport failure also reaches #fail via
+                    // its error event; throwing from an AbortSignal listener would only be unhandled noise.
+                }
+            };
+            const cleanup = () => {
+                controls.signal?.removeEventListener("abort", onAbort);
+                if (controls.onStats !== undefined)
+                    this.#events.delete(requestId);
+            };
+            controls.signal?.addEventListener("abort", onAbort, { once: true });
+            if (controls.onStats !== undefined) {
+                this.#events.set(requestId, { onStats: controls.onStats });
+            }
+            this.#pending.set(requestId, { resolve, reject, cleanup });
+            try {
+                this.#transport.postMessage(kind === "rpc-init"
+                    ? { version: protocolVersion, requestId, kind, payload: args[0] }
+                    : { version: protocolVersion, requestId, kind, handleId, method, args }, transfer === undefined ? undefined : { transfer });
+            }
+            catch (error) {
+                this.#pending.delete(requestId);
+                cleanup();
+                reject(error instanceof Error ? error : new Error("Database request failed", { cause: error }));
+            }
         });
     }
     #receive(message) {
@@ -546,6 +607,9 @@ export class MinnowDatabaseClient {
             }
             else if (response.event === "progress")
                 route.onProgress?.(response.payload);
+            else if (response.event === "stats") {
+                route.onStats?.(response.payload);
+            }
             else if (response.event === "complete") {
                 this.#events.delete(response.handleId);
                 route.onComplete?.();
@@ -556,6 +620,7 @@ export class MinnowDatabaseClient {
         if (pending === undefined)
             return;
         this.#pending.delete(response.requestId);
+        pending.cleanup?.();
         if (response.kind === "rpc-result")
             pending.resolve(response.result);
         else
@@ -566,8 +631,10 @@ export class MinnowDatabaseClient {
         const pending = [...this.#pending.values()];
         this.#pending.clear();
         this.#events.clear();
-        for (const call of pending)
+        for (const call of pending) {
+            call.cleanup?.();
             call.reject(error);
+        }
     }
 }
 /**

package/dist/engine/database.d.ts

@@ -2,8 +2,9 @@ import { type BatchRow, type BatchValue, type InsertBatchInput } from "./batch.j
 import { BufferedTableWriter, type BufferedWriterOptions } from "./buffered-writer.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, UnknownTableError, UniqueConstraintError, VisibleSegmentCursorStaleError } from "./errors.js";
+export { DatabaseReadBacklogError } from "./errors.js";
 import { type Compression } from "../block-format/index.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 BlockStore, type ColumnDefault, type ColumnGenerated, 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 ComparisonOperator, type CompiledQuery, type CompiledStatement, type ForeignKeyDefinition, type QueryResult, type QueryRow, type QueryValue, type UniqueConstraintDefinition } from "./query.js";
 import { LiveQuerySet, type LiveQuerySetOptions } from "./live.js";
@@ -16,11 +17,6 @@ export declare const MAX_TRANSACTION_SAVEPOINT_BYTES: number;
 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;
@@ -31,6 +27,8 @@ export interface ColumnDefinition {
     nullable?: boolean;
     /** Fills omitted or SQL DEFAULT slots at insert time; never applied at read time. */
     defaultValue?: ColumnDefault;
+    /** Stored expression over sibling columns; callers cannot assign this column. */
+    generatedValue?: ColumnGenerated;
     /** String columns only: the closed set of values writes must draw from. */
     enumValues?: readonly string[];
     /** What rows written before this column existed read as, instead of NULL. */
@@ -125,6 +123,8 @@ export interface UpdateBatchResult {
     storedBytes: number;
     version: number;
     metrics: WriteMetrics;
+    /** Recomputed generated-column vectors in input key order. */
+    generatedColumns?: Record<string, BatchValue[]>;
 }
 export interface WriteMetrics {
     logicalBytes: number;
@@ -230,6 +230,11 @@ export interface MaintenanceStatus {
     } | null;
 }
 export interface QueryOptions {
+    /**
+     * Stops a read between bounded execution or storage batches. An abort never returns a partial
+     * result and releases any reader lease and temporary spill owner before the promise rejects.
+     */
+    readonly signal?: AbortSignal;
     /**
      * Called once with what this execution cost, before the result is returned. Additive and
      * optional: the engine can report its own memory because it reserves before it allocates,
@@ -268,8 +273,6 @@ export interface QueryOptions {
 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. */
@@ -584,26 +587,30 @@ export type ExecuteResult = {
 } | {
     kind: "drop-trigger";
     name: string;
-} | {
+} | ({
     kind: "insert";
     table: string;
     rowCount: number;
     /** Absent when the statement affected no rows (an INSERT ... SELECT of an empty set). */
     version?: number;
-    returnedRows?: QueryRow[];
-} | {
+} & ReturningExecuteFields) | ({
     kind: "update";
     table: string;
     rowCount: number;
     version?: number;
-    returnedRows?: QueryRow[];
-} | {
+} & ReturningExecuteFields) | ({
     kind: "delete";
     table: string;
     rowCount: number;
     version?: number | null;
+} & ReturningExecuteFields);
+interface ReturningExecuteFields {
     returnedRows?: QueryRow[];
-};
+    /** RETURNING projection order; present with returnedRows, including for an empty result. */
+    returnedColumns?: string[];
+    /** Logical domains aligned with returnedColumns. */
+    returnedColumnDomains?: Array<SqlDomain | null>;
+}
 export interface RunStatementOptions {
     /**
      * Projects the affected rows back: column names, or "*" for every table column. Inserts echo
@@ -740,6 +747,8 @@ export declare class MinnowDatabase {
     upsert(tableName: string, row: BatchRow, options?: UpsertOptions): Promise<UpsertBatchResult>;
     updateBatch(tableName: string, input: UpdateBatchInput): Promise<UpdateBatchResult>;
     update(tableName: string, key: Exclude<BatchValue, null>, changes: Readonly<Record<string, BatchValue>>): Promise<UpdateBatchResult>;
+    /** Deletes one row by the table's unique key. */
+    delete(tableName: string, key: Exclude<BatchValue, null>): Promise<DeleteBatchResult>;
     deleteBatch(tableName: string, input: DeleteBatchInput): Promise<DeleteBatchResult>;
     bufferedWriter(tableName: string, options?: BufferedWriterOptions): BufferedTableWriter;
     readTable(tableName: string, versionOrOptions?: number | ReadTableOptions): Promise<DatabaseRow[]>;