@minnowdb/core 0.7.7 → 0.7.10

package/dist/engine/schema.d.ts

@@ -1,5 +1,8 @@
 import { type ColumnDefault, type SqlDomain, type TableColumnRecord, type TableRecord } from "../storage/types.js";
+import type { ComparisonOperator } from "../plan/model.js";
+import type { BatchRow, BatchValue, InsertBatchInput } from "./batch.js";
 import { type Catalog, type CatalogColumn, type CatalogTable } from "./catalog.js";
+import type { DatabaseRow, DeleteBatchInput, UpdateBatchInput, UpsertOptions } from "./database.js";
 import { type Expression, type QueryValue } from "./query.js";
 /**
  * Typed schema DSL and catalog migration planning. Column builders carry compile-time value and
@@ -313,8 +316,8 @@ export declare function schema<TTables extends readonly AnyTable[], TViews exten
 }): SchemaDefinition<TTables, TViews>;
 type ColumnTypeMetadata<TColumn> = TColumn extends {
     readonly "~types"?: infer TMetadata extends {
-        readonly select: unknown;
-        readonly input: unknown;
+        readonly select: SchemaValue;
+        readonly input: SchemaValue;
     };
 } ? NonNullable<TMetadata> : never;
 type ColumnValue<TColumn extends AnyColumn> = TColumn["isNullable"] extends true ? ColumnTypeMetadata<TColumn>["select"] | null : ColumnTypeMetadata<TColumn>["select"];
@@ -359,6 +362,86 @@ export type PrimaryKeyKeys<TTable extends AnyTable> = {
 export type InferUpdateChanges<TTable extends AnyTable> = {
     [K in keyof TTable["columns"] as K extends PrimaryKeyKeys<TTable> | GeneratedKeys<TTable> ? never : K]?: ColumnInputValue<TTable["columns"][K]> | undefined;
 };
+/** The bound every schema type parameter carries. */
+export type AnySchema = SchemaDefinition<readonly AnyTable[]>;
+/**
+ * The schema type parameter's default: no declaration, so the batch API addresses tables by
+ * plain string. It is `any` rather than `AnySchema` so that a database declared against a schema
+ * remains assignable to the undeclared class — `MinnowDatabase<typeof mine>` is a
+ * `MinnowDatabase` — which no ordinary type argument can express once table names are checked.
+ * Every type below resolves to its erased branch for it, so nothing else about it is `any`.
+ */
+export type UntypedSchema = any;
+type SchemaTable<TSchema extends AnySchema> = TSchema["tables"][number];
+/** True when the schema carries no literal table names — the untyped default. */
+type ErasedSchema<TSchema extends AnySchema> = string extends SchemaTable<TSchema>["name"] ? true : false;
+/** The declared table names; `string` for an untyped database. */
+export type TableName<TSchema extends AnySchema> = SchemaTable<TSchema>["name"];
+/** The declaration behind one table name. */
+export type TableOf<TSchema extends AnySchema, TName extends TableName<TSchema>> = Extract<SchemaTable<TSchema>, {
+    readonly name: TName;
+}>;
+/** A declared table's column names; `string` for an untyped database. */
+export type BatchColumnName<TSchema extends AnySchema, TName extends TableName<TSchema>> = ErasedSchema<TSchema> extends true ? string : keyof TableOf<TSchema, TName>["columns"] & string;
+/** The columnar form of `InferInsertRow`: one vector per column, optional where the row is. */
+export interface ColumnarInsertBatch<TTable extends AnyTable> {
+    readonly columns: {
+        readonly [K in RequiredInsertKeys<TTable>]: ReadonlyArray<ColumnInputValue<TTable["columns"][K]>>;
+    } & {
+        readonly [K in OptionalInsertKeys<TTable>]?: ReadonlyArray<ColumnInputValue<TTable["columns"][K]>>;
+    };
+    /** Per row, whether the column was omitted (takes its default) rather than set to NULL. */
+    readonly omitted?: Partial<Readonly<Record<OptionalInsertKeys<TTable>, readonly boolean[]>>>;
+    readonly rowCount?: number;
+}
+/** What `insertBatch` and `upsertBatch` accept for one table: typed rows, or a typed columnar batch. */
+export type BatchInsertInput<TSchema extends AnySchema, TName extends TableName<TSchema>> = ErasedSchema<TSchema> extends true ? InsertBatchInput : ReadonlyArray<InferInsertRow<TableOf<TSchema, TName>>> | ColumnarInsertBatch<TableOf<TSchema, TName>>;
+/** One row for `insert`, `upsert`, or a buffered writer's `add`. */
+export type BatchInsertRow<TSchema extends AnySchema, TName extends TableName<TSchema>> = ErasedSchema<TSchema> extends true ? BatchRow : InferInsertRow<TableOf<TSchema, TName>>;
+/** What `readTable` returns per row. */
+export type BatchReadRow<TSchema extends AnySchema, TName extends TableName<TSchema>> = ErasedSchema<TSchema> extends true ? DatabaseRow : InferRow<TableOf<TSchema, TName>>;
+/**
+ * The key a batch write addresses a row by: the `.unique()` column or a one-column table-level
+ * primary key. A composite primary key is addressed through its hidden locator, which the batch
+ * API does not expose, so those tables get `never` here and are written through SQL instead.
+ */
+type BatchKey<TTable extends AnyTable> = TTable["primaryKey"] extends readonly [
+    unknown,
+    unknown,
+    ...unknown[]
+] ? never : TTable["primaryKey"] extends readonly [infer TOnly extends keyof TTable["columns"]] ? NonNullable<ColumnValue<TTable["columns"][TOnly]>> : NonNullable<ScalarUniqueKeyValue<TTable>>;
+/** One key value for `update` and `delete`. */
+export type BatchKeyValue<TSchema extends AnySchema, TName extends TableName<TSchema>> = ErasedSchema<TSchema> extends true ? Exclude<BatchValue, null> : BatchKey<TableOf<TSchema, TName>>;
+/** The changes object `update` takes: every non-key, non-generated column, each optional. */
+export type BatchUpdateChanges<TSchema extends AnySchema, TName extends TableName<TSchema>> = ErasedSchema<TSchema> extends true ? Readonly<Record<string, BatchValue>> : InferUpdateChanges<TableOf<TSchema, TName>>;
+/** What `updateBatch` takes: typed keys and one vector per changed column. */
+export type BatchUpdateInput<TSchema extends AnySchema, TName extends TableName<TSchema>> = ErasedSchema<TSchema> extends true ? UpdateBatchInput : {
+    readonly keys: ReadonlyArray<BatchKey<TableOf<TSchema, TName>>>;
+    readonly changes: {
+        readonly [K in keyof InferUpdateChanges<TableOf<TSchema, TName>>]?: ReadonlyArray<Exclude<InferUpdateChanges<TableOf<TSchema, TName>>[K], undefined>>;
+    };
+};
+/** What `deleteBatch` takes. */
+export type BatchDeleteInput<TSchema extends AnySchema, TName extends TableName<TSchema>> = ErasedSchema<TSchema> extends true ? DeleteBatchInput : {
+    readonly keys: ReadonlyArray<BatchKey<TableOf<TSchema, TName>>>;
+};
+/** A `conflictWhere` guard whose `value` follows the column it names. */
+export type BatchConflictWhere<TTable extends AnyTable> = {
+    [K in keyof TTable["columns"] & string]: {
+        readonly column: K;
+        readonly operator: ComparisonOperator;
+        readonly value: ColumnInputValue<TTable["columns"][K]>;
+    };
+}[keyof TTable["columns"] & string];
+/** `upsertBatch`/`upsert` options, with the guard typed against the table. */
+export type BatchUpsertOptions<TSchema extends AnySchema, TName extends TableName<TSchema>> = ErasedSchema<TSchema> extends true ? UpsertOptions : {
+    readonly conflictWhere?: BatchConflictWhere<TableOf<TSchema, TName>>;
+};
+/** `readTable` options; naming `columns` narrows the returned rows to those columns. */
+export interface BatchReadOptions<TSchema extends AnySchema, TName extends TableName<TSchema>, TColumns extends ReadonlyArray<BatchColumnName<TSchema, TName>> = ReadonlyArray<BatchColumnName<TSchema, TName>>> {
+    readonly version?: number;
+    readonly columns?: TColumns;
+}
 export type MigrationStep = {
     kind: "create-table";
     table: AnyTable;

package/dist/engine/typed-live.d.ts

@@ -1,7 +1,10 @@
-import type { LiveQueryInput, LiveQueryObserveOptions } from "./live.js";
+import type { LiveQueryInput, LiveQueryObserveOptions, LiveQuerySubscribeOptions } from "./live.js";
+import type { QueryResult } from "./query.js";
 /** The structural live-query surface shared by MinnowDatabase and its worker client. */
 export interface LiveQueryBackend {
     observe(query: LiveQueryInput, options: LiveQueryObserveOptions): Promise<LiveQuerySubscriptionLike>;
+    /** Result delivery, used when the source can decode the engine's result itself. */
+    subscribe?(query: LiveQueryInput, options: LiveQuerySubscribeOptions): Promise<LiveQuerySubscriptionLike>;
     refresh(): Promise<void>;
     close(): void | Promise<void>;
 }
@@ -22,6 +25,14 @@ export interface LiveQueryDriver {
 export interface LiveQuerySource<out TRow> {
     readonly query: LiveQueryInput;
     execute(signal?: AbortSignal): Promise<readonly TRow[]>;
+    /**
+     * Turns a result the engine delivered into the adapter's rows. With it, the query subscribes
+     * for results rather than invalidations: the engine executes or patches the statement where
+     * the data is, compares, and hands over a changed result once — over a worker channel, as
+     * one columnar transfer — and `execute` is never called after the statement is registered.
+     * Without it, an invalidation is followed by `execute`, which the engine's memo serves.
+     */
+    decode?(result: QueryResult): readonly TRow[] | Promise<readonly TRow[]>;
 }
 export type LiveSnapshot<TRow> = {
     readonly status: "loading";

package/dist/engine/typed-live.js

@@ -1,6 +1,26 @@
 import { sameLiveValue } from "./live-equal.js";
-function immutableRows(rows) {
-  return Object.freeze([...rows]);
+function reconcileRows(previous, next, retained) {
+  const rows = new Array(next.length);
+  let changed = previous.length !== next.length;
+  const provenance = retained?.length === next.length ? retained : void 0;
+  for (let index = 0; index < next.length; index += 1) {
+    const row = next[index];
+    const was = provenance?.[index] ?? -1;
+    if (was >= 0 && was < previous.length) {
+      rows[index] = previous[was];
+      if (was !== index)
+        changed = true;
+      continue;
+    }
+    const before = previous[index];
+    if (index < previous.length && sameLiveValue(before, row))
+      rows[index] = before;
+    else {
+      rows[index] = row;
+      changed = true;
+    }
+  }
+  return changed ? Object.freeze(rows) : void 0;
 }
 class LiveQuery {
   #listeners = /* @__PURE__ */ new Set();
@@ -11,6 +31,9 @@ class LiveQuery {
   #subscription;
   #observationGeneration = 0;
   #queued;
+  #lastDelivered;
+  #deliveriesReceived = 0;
+  #rowsFromDelivery = 0;
   #execution;
   #executionAbort;
   #invalidationSequence = 0;
@@ -52,10 +75,24 @@ class LiveQuery {
     }
     if (this.#invalidationSequence === sequence) {
       const version = this.#snapshot.status === "loading" ? null : this.#snapshot.version;
-      this.#schedule({ manifestVersion: version, catalogEpoch: 0, initial: false });
+      if (this.#decodes()) {
+        const last = this.#lastDelivered;
+        if (this.#snapshot.status === "error" && last !== void 0)
+          this.#schedule(last);
+      } else
+        this.#schedule({ manifestVersion: version, catalogEpoch: 0, initial: false });
     }
     await this.#waitForIdle();
   }
+  #decodes() {
+    return this.#source.decode !== void 0 && this.#backend.subscribe !== void 0;
+  }
+  async #decodeDelivered(result) {
+    const source = this.#source;
+    if (source.decode === void 0)
+      throw new TypeError("Live query source lost its decoder");
+    return source.decode(result);
+  }
   close() {
     if (this.#closed)
       return;
@@ -75,7 +112,36 @@ class LiveQuery {
     if (this.#subscription !== void 0 || this.#closed)
       return;
     const generation = this.#observationGeneration += 1;
+    if (this.#source.decode !== void 0 && this.#backend.subscribe !== void 0) {
+      const subscription2 = this.#backend.subscribe(this.#source.query, {
+        onChange: (result, delivery) => {
+          if (generation !== this.#observationGeneration || this.#closed)
+            return;
+          this.#deliveriesReceived += 1;
+          this.#schedule({ result, delivery, sequence: this.#deliveriesReceived });
+        },
+        onError: (error) => {
+          if (generation !== this.#observationGeneration || this.#closed)
+            return;
+          this.#setError(error, this.#currentVersion());
+        },
+        onComplete: () => {
+          if (generation !== this.#observationGeneration)
+            return;
+          this.#subscription = void 0;
+        }
+      });
+      this.#subscription = subscription2;
+      subscription2.catch((error) => {
+        if (generation !== this.#observationGeneration || this.#closed)
+          return;
+        this.#subscription = void 0;
+        this.#setError(error, this.#currentVersion());
+      });
+      return;
+    }
     const subscription = this.#backend.observe(this.#source.query, {
+      suppressUnchanged: true,
       onInvalidate: (invalidation) => {
         if (generation !== this.#observationGeneration || this.#closed)
           return;
@@ -109,9 +175,9 @@ class LiveQuery {
       void subscription.then((handle) => handle.close()).catch(() => void 0);
     }
   }
-  #schedule(invalidation) {
+  #schedule(work) {
     this.#invalidationSequence += 1;
-    this.#queued = invalidation;
+    this.#queued = work;
     if (this.#execution !== void 0)
       return;
     const execution = this.#drain();
@@ -125,24 +191,35 @@ class LiveQuery {
   }
   async #drain() {
     while (this.#queued !== void 0 && !this.#closed) {
-      const invalidation = this.#queued;
+      const work = this.#queued;
       this.#queued = void 0;
       const abort = new AbortController();
       this.#executionAbort = abort;
+      const invalidation = "result" in work ? work.delivery : work;
       try {
-        const rows = immutableRows(await this.#source.execute(abort.signal));
+        let executed;
+        if ("result" in work) {
+          this.#lastDelivered = work;
+          executed = await this.#decodeDelivered(work.result);
+          this.#lastDelivered = void 0;
+        } else
+          executed = await this.#source.execute(abort.signal);
         if (this.#executionWasCancelled(abort))
           continue;
         if (this.#hasQueuedInvalidation())
           continue;
         const previous = this.#snapshot.rows;
-        if (this.#snapshot.status === "ready" && this.#snapshot.version === invalidation.manifestVersion && sameLiveValue(previous, rows)) {
-          continue;
-        }
-        if (sameLiveValue(previous, rows) && this.#snapshot.status !== "loading") {
+        const provenance = "result" in work && this.#rowsFromDelivery === work.sequence - 1 ? work.delivery.retained : void 0;
+        const rows = reconcileRows(previous, executed, provenance);
+        if ("result" in work)
+          this.#rowsFromDelivery = work.sequence;
+        if (rows === void 0) {
+          if (this.#snapshot.status === "ready" && this.#snapshot.version === invalidation.manifestVersion) {
+            continue;
+          }
           this.#snapshot = {
             status: "ready",
-            rows: previous,
+            rows: this.#snapshot.status === "loading" ? Object.freeze([...previous]) : previous,
             version: invalidation.manifestVersion
           };
         } else {

package/dist/engine/worker-server.js

@@ -379,7 +379,8 @@ class DatabaseRpcServer {
         try {
           set = this.database.liveQueries({
             ...channelName === void 0 ? {} : { channelName },
-            ...pollIntervalMs === void 0 ? {} : { pollIntervalMs }
+            ...pollIntervalMs === void 0 ? {} : { pollIntervalMs },
+            sharedResults: true
           });
           this.#publishHandle(handleId, { type: "live-set", set, subscriptionIds: /* @__PURE__ */ new Set() });
         } catch (error) {
@@ -667,11 +668,15 @@ class DatabaseRpcServer {
         let subscription;
         try {
           subscription = await handle.set.subscribe(query, {
-            onChange: (result) => {
+            onChange: (result, delivery) => {
               const encoded = encodeQueryResult(result);
-              this.scope.postMessage(rpcEvent(subscriptionId, "change", encoded.payload), {
-                transfer: encoded.transfer
-              });
+              const retained = delivery.retained?.slice();
+              if (retained !== void 0)
+                encoded.transfer.push(retained.buffer);
+              this.scope.postMessage(rpcEvent(subscriptionId, "change", {
+                result: encoded.payload,
+                delivery: retained === void 0 ? delivery : { ...delivery, retained }
+              }), { transfer: encoded.transfer });
             },
             onError: (error) => {
               this.scope.postMessage(rpcEvent(subscriptionId, "error", serializeError(error)));
@@ -700,9 +705,11 @@ class DatabaseRpcServer {
       case "observe": {
         const subscriptionId = this.#claimHandleId(args[0]);
         const query = args[1];
+        const { suppressUnchanged } = args[2] ?? {};
         let subscription;
         try {
           subscription = await handle.set.observe(query, {
+            ...suppressUnchanged === true ? { suppressUnchanged: true } : {},
             onInvalidate: (invalidation) => {
               this.scope.postMessage(rpcEvent(subscriptionId, "invalidate", invalidation));
             },

package/dist/worker-protocol/index.d.ts

@@ -1,4 +1,4 @@
-export declare const protocolVersion: 3;
+export declare const protocolVersion: 6;
 /** Outstanding request/response pairs retained by either side of one database RPC connection. */
 export declare const MAX_DATABASE_RPC_IN_FLIGHT = 256;
 export type RpcRequest = {

package/dist/worker-protocol/index.js

@@ -1,4 +1,4 @@
-const protocolVersion = 3;
+const protocolVersion = 6;
 const MAX_DATABASE_RPC_IN_FLIGHT = 256;
 function serializeError(error) {
   if (!(error instanceof Error)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minnowdb/core",
-  "version": "0.7.7",
+  "version": "0.7.10",
   "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",