@minnowdb/core 0.7.8 → 0.7.10

package/dist/engine/keyed-live.js

@@ -1,23 +1,29 @@
 import { dateMilliseconds } from "../date-value.js";
 import { sameLiveValue } from "./live-equal.js";
+const dateTokens = /* @__PURE__ */ new Map();
 function keyToken(value, name) {
-  if (typeof value === "string")
-    return `s:${String(value.length)}:${value}`;
-  if (typeof value === "boolean")
-    return value ? "b:1" : "b:0";
+  if (typeof value === "string" || typeof value === "boolean")
+    return value;
   if (typeof value === "number") {
     if (Number.isNaN(value))
-      return "n:NaN";
+      return NaN;
     if (Object.is(value, -0))
-      return "n:-0";
-    return `n:${String(value)}`;
+      return /* @__PURE__ */ Symbol.for("minnow.live.key.-0");
+    return value;
   }
   if (value instanceof Date) {
     const time = dateMilliseconds(value);
     if (!Number.isFinite(time)) {
       throw new TypeError(`Live query key ${String(name)} must be a valid Date`);
     }
-    return `d:${String(time)}`;
+    let token = dateTokens.get(time);
+    if (token === void 0) {
+      token = /* @__PURE__ */ Symbol(`minnow.live.key.date:${String(time)}`);
+      dateTokens.set(time, token);
+      if (dateTokens.size > 65536)
+        dateTokens.clear();
+    }
+    return token;
   }
   throw new TypeError(`Live query key ${String(name)} must be a non-null string, number, boolean, or Date`);
 }
@@ -35,8 +41,7 @@ function indexRows(rows, key) {
   }
   return indexed;
 }
-function diffRows(previousRows, rows, key) {
-  const previous = indexRows(previousRows, key);
+function diffRows(previous, previousRows, rows, key) {
   const current = indexRows(rows, key);
   const changes = [];
   for (const [token, old] of previous) {
@@ -44,26 +49,44 @@ function diffRows(previousRows, rows, key) {
       continue;
     changes.push({ type: "delete", key: old.row[key], previous: old.row, index: old.index });
   }
+  let reused = 0;
+  const reconciled = new Array(rows.length);
   for (const [token, next] of current) {
     const old = previous.get(token);
     if (old === void 0) {
+      reconciled[next.index] = next.row;
       changes.push({ type: "insert", row: next.row, index: next.index });
       continue;
     }
-    if (!sameLiveValue(old.row, next.row)) {
+    let kept = next.row;
+    if (old.row === next.row || sameLiveValue(old.row, next.row)) {
+      kept = old.row;
+      if (old.row !== next.row) {
+        current.set(token, { row: old.row, index: next.index });
+        reused += 1;
+      }
+    } else {
       changes.push({ type: "update", row: next.row, previous: old.row, index: next.index });
     }
+    reconciled[next.index] = kept;
     if (old.index !== next.index) {
       changes.push({
         type: "move",
         key: next.row[key],
-        row: next.row,
+        row: kept,
         from: old.index,
         to: next.index
       });
     }
   }
-  return changes;
+  if (changes.length === 0 && rows.length === previousRows.length) {
+    return { changes, rows: previousRows, index: current };
+  }
+  return {
+    changes,
+    rows: reused === 0 ? rows : Object.freeze(reconciled),
+    index: current
+  };
 }
 class KeyedLiveQuery {
   #source;
@@ -72,6 +95,8 @@ class KeyedLiveQuery {
   #listeners = /* @__PURE__ */ new Set();
   #sourceUnsubscribe;
   #rows = [];
+  #sourceRows;
+  #index;
   #snapshot = { status: "loading", rows: [] };
   #hasReadySnapshot = false;
   #closed = false;
@@ -141,23 +166,35 @@ class KeyedLiveQuery {
       this.#emit();
       return;
     }
+    if (this.#snapshot.status === "ready" && snapshot.rows === this.#sourceRows && this.#snapshot.version === snapshot.version) {
+      return;
+    }
     try {
       if (this.#maxRows !== void 0 && snapshot.rows.length > this.#maxRows) {
         throw new RangeError(`Live query window returned ${String(snapshot.rows.length)} rows; maximum is ${String(this.#maxRows)}`);
       }
       const initial = !this.#hasReadySnapshot;
       let changes;
-      if (initial) {
-        indexRows(snapshot.rows, this.#key);
+      let rows;
+      if (initial || this.#index === void 0) {
+        this.#index = indexRows(snapshot.rows, this.#key);
+        rows = snapshot.rows;
         changes = snapshot.rows.map((row, index) => ({ type: "insert", row, index }));
+      } else if (snapshot.rows === this.#sourceRows) {
+        rows = this.#rows;
+        changes = [];
       } else {
-        changes = diffRows(this.#rows, snapshot.rows, this.#key);
+        const diff = diffRows(this.#index, this.#rows, snapshot.rows, this.#key);
+        this.#index = diff.index;
+        rows = diff.rows;
+        changes = diff.changes;
       }
-      this.#rows = snapshot.rows;
+      this.#rows = rows;
+      this.#sourceRows = snapshot.rows;
       this.#hasReadySnapshot = true;
       this.#snapshot = {
         status: "ready",
-        rows: snapshot.rows,
+        rows,
         changes: Object.freeze(changes),
         initial,
         version: snapshot.version

package/dist/engine/live.d.ts

@@ -6,8 +6,11 @@ import { type CompiledQuery, type QueryResult, type QueryValue } from "./query.j
  * table sets then decide which prepared queries may be stale. Hints may be lost, duplicated, or
  * reordered without changing correctness.
  *
- * Equal statements share one dependency record and one execution per sweep. Results retain an
- * exact private snapshot: a 32-bit digest is only a fast inequality check, never proof of equality.
+ * A sweep costs what changed, not what is subscribed: the commit window's table set selects the
+ * groups to visit through a per-table index, and a group nobody visits keeps its result on the
+ * strength of the invariant that every window touching one of its tables would have visited it.
+ * Equal statements share one dependency record and one execution per sweep. Results are compared
+ * exactly, row by row, so an unchanged result never reaches a subscriber.
  */
 export interface LiveQueryHintChannel {
     postMessage(message: unknown): void;
@@ -24,6 +27,20 @@ export interface LiveQuerySetOptions {
     readonly maxGroups?: number;
     /** Maximum result/observer subscriptions retained by this set. Defaults to 1,024. */
     readonly maxSubscriptions?: number;
+    /**
+     * Hand `onChange` the set's retained result instead of a private copy. The result is shared
+     * with every equal subscription and with the next change comparison, so a subscriber must
+     * treat it as read-only. A consumer that only reads it synchronously — the worker host that
+     * encodes it for the channel, a renderer that copies what it displays — saves one full copy
+     * per subscriber per change.
+     */
+    readonly sharedResults?: boolean;
+    /**
+     * Whether the set may patch a retained result from a commit's rows instead of re-running the
+     * statement, for statements the host can maintain that way. Defaults to true; false makes
+     * every relevant commit a full execution, which is useful when comparing the two.
+     */
+    readonly incremental?: boolean;
     /** Called once when the set closes; the owner uses this to drop its reference. */
     readonly onClosed?: () => void;
 }
@@ -33,8 +50,21 @@ export declare const MAX_LIVE_QUERY_GROUPS = 4096;
 export declare const MAX_LIVE_QUERY_SUBSCRIPTIONS = 16384;
 export declare const MAX_LIVE_QUERY_SETS_PER_DATABASE = 256;
 export { LiveQueryLimitError } from "./errors.js";
+/** What a delivered result reflects: the probe it is current as of, and whether it is the first. */
+export interface LiveQueryDelivery {
+    readonly manifestVersion: number | null;
+    readonly catalogEpoch: number;
+    readonly initial: boolean;
+    /**
+     * For each row, the index it held in this subscription's previous delivery, or -1 for a row
+     * that is new or changed. Present when the engine kept row objects across the change — a
+     * patched result keeps every untouched row — and absent after a full execution or on the
+     * first delivery. A consumer that keys on row identity substitutes its own previous objects.
+     */
+    readonly retained?: Int32Array;
+}
 export interface LiveQuerySubscribeOptions {
-    onChange(result: QueryResult): void;
+    onChange(result: QueryResult, delivery: LiveQueryDelivery): void;
     onError?(error: unknown): void;
     /** Called once when the subscription ends because the subscription or its set closed. */
     onComplete?(): void;
@@ -48,6 +78,14 @@ export interface LiveQueryObserveOptions {
     onInvalidate(invalidation: LiveQueryInvalidation): void;
     onError?(error: unknown): void;
     onComplete?(): void;
+    /**
+     * Execute the statement inside the set on every relevant commit and invalidate only when the
+     * rows changed. The engine keeps that execution in its result memo, so an adapter that then
+     * re-executes the same statement at the same version is served from cache rather than from a
+     * second scan. A commit that leaves the rows as they were costs one execution and reaches no
+     * observer at all — nothing crosses a worker channel and nothing re-renders.
+     */
+    readonly suppressUnchanged?: boolean;
 }
 export interface LiveQuerySubscription {
     readonly dependencyTableIds: readonly string[];
@@ -58,12 +96,24 @@ export interface LiveQueryStats {
     versionChecks: number;
     sweeps: number;
     reruns: number;
+    /** Subscribed groups a sweep did not re-run: nothing they read changed, or a proof said so. */
     rerunsAvoided: number;
     /** Re-runs skipped because the data layer proved the commits could not change the result. */
     zoneSkips: number;
+    /** Deliveries withheld because an execution produced exactly the rows already delivered. */
     notificationsSuppressed: number;
-    /** Observer-only invalidations delivered without executing the statement inside the set. */
+    /** Observer invalidations delivered. */
     invalidations: number;
+    /** Re-runs answered by patching the retained result with the commit's rows instead. */
+    maintained: number;
+    /** Groups a sweep looked at: those whose tables the commits changed, plus any left lagging. */
+    groupsVisited: number;
+    /**
+     * Rows the set currently retains across every group's last result — what its subscriptions
+     * display, counted once per distinct statement. A window's margin beyond its visible rows is
+     * bounded by the engine at 64 rows and is not included.
+     */
+    retainedRows: number;
     /** Work avoided because equal statements shared one query group or in-flight execution. */
     sharedExecutions: number;
     lastSweepMs: number;
@@ -77,11 +127,48 @@ export type LiveQueryInput = string | {
     kind: "typed-query";
     plan: CompiledQuery;
 };
-interface LiveQueryHost {
+/** What the set already knows when it asks the host to execute a statement. */
+export interface LiveQueryExecuteContext {
+    /**
+     * A freshness probe the set read moments ago. The host may start execution from it instead of
+     * reading its own; a result may still observe a newer commit, and the set treats the probe as
+     * a lower bound on what the result reflects.
+     */
+    readonly probe: CatalogProbe;
+    /**
+     * Whether the host should keep the result in its memo. The set retains its own copy, so a
+     * memo entry only pays off when another caller — an adapter re-executing after an
+     * invalidation — will ask for the same statement at the same version.
+     */
+    readonly memoize: boolean;
+}
+/** A maintainable statement's execution: its result and the host's opaque state for patching it. */
+export interface LiveMaintainedExecution {
+    readonly result: QueryResult;
+    readonly state: unknown;
+}
+export interface LiveMaintainedChange extends LiveMaintainedExecution {
+    readonly changed: boolean;
+    /** For each row of `result`, its index in the previous result, or -1; see `LiveQueryDelivery`. */
+    readonly retained?: Int32Array;
+}
+export interface LiveQueryHost {
     currentProbe(): Promise<CatalogProbe>;
     manifestPage(afterVersion: number | null, limit: number): Promise<StoragePage<Manifest, number>>;
-    dependencyTableIds(query: LiveQueryInput): Promise<Set<string>>;
-    execute(query: LiveQueryInput): Promise<QueryResult>;
+    /** The base tables the statement reads, resolved through views; `probe` is a recent read. */
+    dependencyTableIds(query: LiveQueryInput, probe?: CatalogProbe): Promise<Set<string>>;
+    /** Executes the statement; the returned result belongs to the set and is never shared. */
+    execute(query: LiveQueryInput, context?: LiveQueryExecuteContext): Promise<QueryResult>;
+    /**
+     * Executes a statement the host can later maintain incrementally, or returns undefined when
+     * the statement's shape rules that out; the set then executes it in full from then on.
+     */
+    executeMaintainable?(query: LiveQueryInput, context?: LiveQueryExecuteContext): Promise<LiveMaintainedExecution | undefined>;
+    /**
+     * Patches a retained result with the row changes the commits in (after, until] made to
+     * `tableIds`, or returns undefined when only a full execution can answer.
+     */
+    maintain?(query: LiveQueryInput, result: QueryResult, state: unknown, tableIds: readonly string[], after: number | null, until: number, probe: CatalogProbe): Promise<LiveMaintainedChange | undefined>;
     /** Returns false only on proof that the commit window cannot affect the statement. */
     changeCanAffect?(query: LiveQueryInput, tableIds: readonly string[], after: number | null, until: number): Promise<boolean>;
 }
@@ -91,7 +178,7 @@ export declare class LiveQuerySet {
     get stats(): LiveQueryStats;
     /** Registers a query, delivers its current result, and shares work with equal statements. */
     subscribe(query: LiveQueryInput, options: LiveQuerySubscribeOptions): Promise<LiveQuerySubscription>;
-    /** Observes invalidation without executing the statement inside the set. */
+    /** Observes invalidation; the statement executes inside the set only when asked to compare. */
     observe(query: LiveQueryInput, options: LiveQueryObserveOptions): Promise<LiveQuerySubscription>;
     /** Called by the owning database after each local write commit; also hints other tabs. */
     notifyLocalCommit(): void;