@minnowdb/core 0.6.2 → 0.6.3

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, QueryExecutionStats, 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, ExecuteOptions, 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";
@@ -127,7 +127,7 @@ export declare class MinnowDatabaseClient {
         __row?: TRow;
     }): Promise<TRow[]>;
     explain(sql: string): Promise<string>;
-    execute(sql: string, params?: readonly QueryValue[]): Promise<ExecuteResult>;
+    execute(sql: string, params?: readonly QueryValue[], options?: ExecuteOptions): Promise<ExecuteResult>;
     /** Executes a compiled statement from the typed mutation builders in the worker. */
     runStatement(statement: CompiledStatement, options?: RunStatementOptions): Promise<ExecuteResult>;
     /**

package/dist/engine/client.js

@@ -279,8 +279,12 @@ export class MinnowDatabaseClient {
     async explain(sql) {
         return (await this.#call("explain", [sql]));
     }
-    async execute(sql, params) {
-        return (await this.#call("execute", params === undefined ? [sql] : [sql, params]));
+    async execute(sql, params, options = {}) {
+        const { signal, onStats, ...wireOptions } = options;
+        return (await this.#call("execute", [sql, params, wireOptions, onStats !== undefined], {
+            signal,
+            onStats,
+        }));
     }
     /** Executes a compiled statement from the typed mutation builders in the worker. */
     async runStatement(statement, options) {

package/dist/engine/database.d.ts

@@ -270,6 +270,13 @@ export interface QueryOptions {
     /** Maximum rows encoded in each merged spill page. */
     readonly spillPageRows?: number;
 }
+/**
+ * Engine controls honored by `execute()`. A SELECT runs through the query pipeline with all of
+ * them; every other statement checks `signal` before it starts running, so an already-aborted
+ * execute never mutates anything. Mutations are not stopped mid-statement — a write either
+ * publishes completely or fails — and only SELECT executions report stats.
+ */
+export type ExecuteOptions = Pick<QueryOptions, "signal" | "onStats" | "memoize" | "executionMemoryBudgetBytes">;
 export interface QueryCursorOptions extends QueryOptions {
     /** Maximum rows in one yielded result batch. Defaults to the vector scan batch size. */
     readonly batchRows?: number;
@@ -823,8 +830,11 @@ export declare class MinnowDatabase {
      * read the matching keys at one snapshot and then apply the keyed mutation. The read and the
      * mutation are two steps, not one serializable transaction: a key changed by a competing writer
      * in between fails the statement explicitly rather than silently mutating other rows.
+     *
+     * `options` carries the engine controls a query takes: a SELECT honors all of them, and every
+     * other statement checks `signal` once before running (see `ExecuteOptions`).
      */
-    execute(sql: string, params?: readonly QueryValue[]): Promise<ExecuteResult>;
+    execute(sql: string, params?: readonly QueryValue[], options?: ExecuteOptions): Promise<ExecuteResult>;
     /**
      * Executes an already-compiled statement — the typed mutation builders call this directly with
      * the same statement structures SQL parses into, sharing every validation and conflict rule.

package/dist/engine/database.js

@@ -6140,8 +6140,12 @@ export class MinnowDatabase {
      * read the matching keys at one snapshot and then apply the keyed mutation. The read and the
      * mutation are two steps, not one serializable transaction: a key changed by a competing writer
      * in between fails the statement explicitly rather than silently mutating other rows.
+     *
+     * `options` carries the engine controls a query takes: a SELECT honors all of them, and every
+     * other statement checks `signal` once before running (see `ExecuteOptions`).
      */
-    async execute(sql, params) {
+    async execute(sql, params, options = {}) {
+        throwIfAborted(options.signal);
         await this.#settleExpiredStatementTransaction();
         const statement = this.#compileStatementCached(sql);
         if (statement.kind === "transaction") {
@@ -6150,7 +6154,10 @@ export class MinnowDatabase {
         if (statement.kind === "select") {
             return {
                 kind: "rows",
-                result: await this.query(statement.sql, params === undefined ? {} : { params }),
+                result: await this.query(statement.sql, {
+                    ...options,
+                    ...(params === undefined ? {} : { params }),
+                }),
             };
         }
         const open = this.#openTransaction;

package/dist/engine/sql-driver.d.ts

@@ -1,5 +1,5 @@
 import type { Catalog } from "./catalog.js";
-import type { ExecuteResult, QueryCursorOptions, QueryOptions } from "./database.js";
+import type { ExecuteOptions, ExecuteResult, QueryCursorOptions, QueryOptions } from "./database.js";
 import type { QueryResult, QueryValue } from "./query.js";
 /**
  * The stable SQL boundary used by clients and third-party adapters.
@@ -7,11 +7,16 @@ import type { QueryResult, QueryValue } from "./query.js";
  * It is structural: both `MinnowDatabase` and `MinnowDatabaseClient` implement it without a
  * wrapper. Adapters should emit PostgreSQL-style SQL and keep engine-specific APIs outside
  * this small contract.
+ *
+ * `execute` takes the same engine controls a `query` does — `signal`, `onStats`, `memoize`,
+ * `executionMemoryBudgetBytes` — as a trailing optional argument, so an adapter can cancel a
+ * buffered statement or observe its cost without reaching around the boundary. A driver written
+ * against the two-argument form remains a valid implementation; it simply ignores the controls.
  */
 export interface MinnowSqlExecutor {
     query(sql: string, options?: QueryOptions): Promise<QueryResult>;
     queryCursor(sql: string, options?: QueryCursorOptions): AsyncIterableIterator<QueryResult>;
-    execute(sql: string, params?: readonly QueryValue[]): Promise<ExecuteResult>;
+    execute(sql: string, params?: readonly QueryValue[], options?: ExecuteOptions): Promise<ExecuteResult>;
 }
 /** SQL execution plus the catalog surface schema-aware adapters need. */
 export interface MinnowSqlDriver extends MinnowSqlExecutor {

package/dist/engine/worker-host.js

@@ -38,7 +38,6 @@ const directRootMethods = [
     "delete",
     "runStatement",
     "explain",
-    "execute",
     "listVisibleSegmentPage",
     "cleanupQuerySpill",
     "compactTable",
@@ -223,7 +222,9 @@ class DatabaseRpcServer {
         }
         if (!bypassLimit)
             this.#inFlightRpcCount += 1;
-        const abort = request.method === "query" ? new AbortController() : undefined;
+        const abort = request.method === "query" || request.method === "execute"
+            ? new AbortController()
+            : undefined;
         if (abort !== undefined)
             this.#requestAborts.set(request.requestId, abort);
         const context = {
@@ -295,6 +296,20 @@ class DatabaseRpcServer {
                         : {}),
                 })));
             }
+            case "execute": {
+                const [sql, params, options, reportStats = false] = args;
+                return this.database.execute(sql, params, {
+                    ...options,
+                    signal: context.signal,
+                    ...(reportStats
+                        ? {
+                            onStats: (stats) => {
+                                this.scope.postMessage(rpcEvent(context.requestId, "stats", stats));
+                            },
+                        }
+                        : {}),
+                });
+            }
             case "queryCursorOpen": {
                 const handleId = this.#claimHandleId(args[0]);
                 const [sql, options, reportStats = false] = args.slice(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minnowdb/core",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "A columnar SQL database for the browser: PostgreSQL-style SQL over durable IndexedDB or OPFS data, with no server or WebAssembly module.",
   "license": "MIT",
   "author": "Eric Wilhite",