@minnowdb/core 0.2.1 → 0.4.0

package/dist/engine/keyed-live.js

@@ -0,0 +1,226 @@
+import { dateMilliseconds } from "../date-value.js";
+function sameValue(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (left instanceof Date || right instanceof Date) {
+        return (left instanceof Date &&
+            right instanceof Date &&
+            Object.is(dateMilliseconds(left), dateMilliseconds(right)));
+    }
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right) || left.length !== right.length)
+            return false;
+        for (let index = 0; index < left.length; index += 1) {
+            if (!sameValue(left[index], right[index]))
+                return false;
+        }
+        return true;
+    }
+    if (typeof left !== "object" || left === null || typeof right !== "object" || right === null) {
+        return false;
+    }
+    const leftRecord = left;
+    const rightRecord = right;
+    const leftKeys = Object.keys(leftRecord);
+    const rightKeys = Object.keys(rightRecord);
+    if (leftKeys.length !== rightKeys.length)
+        return false;
+    for (let index = 0; index < leftKeys.length; index += 1) {
+        const key = leftKeys[index];
+        if (key === undefined || key !== rightKeys[index])
+            return false;
+        if (!sameValue(leftRecord[key], rightRecord[key]))
+            return false;
+    }
+    return true;
+}
+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 === "number") {
+        if (Number.isNaN(value))
+            return "n:NaN";
+        if (Object.is(value, -0))
+            return "n:-0";
+        return `n:${String(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)}`;
+    }
+    throw new TypeError(`Live query key ${String(name)} must be a non-null string, number, boolean, or Date`);
+}
+function indexRows(rows, key) {
+    const indexed = new Map();
+    for (let index = 0; index < rows.length; index += 1) {
+        const row = rows[index];
+        if (row === undefined)
+            continue;
+        const token = keyToken(row[key], key);
+        if (indexed.has(token)) {
+            throw new TypeError(`Live query key ${String(key)} is not unique: duplicate at row ${String(index)}`);
+        }
+        indexed.set(token, { row, index });
+    }
+    return indexed;
+}
+function diffRows(previousRows, rows, key) {
+    const previous = indexRows(previousRows, key);
+    const current = indexRows(rows, key);
+    const changes = [];
+    for (const [token, old] of previous) {
+        if (current.has(token))
+            continue;
+        changes.push({ type: "delete", key: old.row[key], previous: old.row, index: old.index });
+    }
+    for (const [token, next] of current) {
+        const old = previous.get(token);
+        if (old === undefined) {
+            changes.push({ type: "insert", row: next.row, index: next.index });
+            continue;
+        }
+        if (!sameValue(old.row, next.row)) {
+            changes.push({ type: "update", row: next.row, previous: old.row, index: next.index });
+        }
+        if (old.index !== next.index) {
+            changes.push({
+                type: "move",
+                key: next.row[key],
+                row: next.row,
+                from: old.index,
+                to: next.index,
+            });
+        }
+    }
+    return changes;
+}
+/** Keyed exact diffs over a typed live query, with optional bounded-window enforcement. */
+export class KeyedLiveQuery {
+    #source;
+    #key;
+    #maxRows;
+    #listeners = new Set();
+    #sourceUnsubscribe;
+    #rows = [];
+    #snapshot = { status: "loading", rows: [] };
+    #hasReadySnapshot = false;
+    #closed = false;
+    constructor(source, options) {
+        if (options.maxRows !== undefined &&
+            (!Number.isSafeInteger(options.maxRows) || options.maxRows <= 0)) {
+            throw new RangeError("Live query window maxRows must be a positive whole number");
+        }
+        this.#source = source;
+        this.#key = options.key;
+        this.#maxRows = options.maxRows;
+    }
+    getSnapshot = () => this.#snapshot;
+    subscribe = (listener) => {
+        if (this.#closed)
+            throw new Error("Keyed live query is closed");
+        const registered = () => listener();
+        this.#listeners.add(registered);
+        if (this.#listeners.size === 1) {
+            this.#sourceUnsubscribe = this.#source.subscribe(() => this.#accept(this.#source.getSnapshot()));
+            this.#accept(this.#source.getSnapshot());
+        }
+        let subscribed = true;
+        return () => {
+            if (!subscribed)
+                return;
+            subscribed = false;
+            this.#listeners.delete(registered);
+            if (this.#listeners.size === 0) {
+                this.#sourceUnsubscribe?.();
+                this.#sourceUnsubscribe = undefined;
+            }
+        };
+    };
+    async refresh() {
+        if (this.#closed)
+            throw new Error("Keyed live query is closed");
+        await this.#source.refresh();
+        this.#accept(this.#source.getSnapshot());
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#sourceUnsubscribe?.();
+        this.#sourceUnsubscribe = undefined;
+        this.#source.close();
+        this.#emit();
+        this.#listeners.clear();
+    }
+    #accept(snapshot) {
+        if (this.#closed)
+            return;
+        if (snapshot.status === "loading") {
+            if (this.#snapshot.status === "loading")
+                return;
+            this.#snapshot = { status: "loading", rows: this.#rows };
+            this.#emit();
+            return;
+        }
+        if (snapshot.status === "error") {
+            this.#snapshot = {
+                status: "error",
+                rows: this.#rows,
+                error: snapshot.error,
+                version: snapshot.version,
+            };
+            this.#emit();
+            return;
+        }
+        try {
+            if (this.#maxRows !== undefined && 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) {
+                // Initial snapshots still validate uniqueness even though no previous index is needed.
+                indexRows(snapshot.rows, this.#key);
+                changes = snapshot.rows.map((row, index) => ({ type: "insert", row, index }));
+            }
+            else {
+                // diffRows builds each old/new key index exactly once and validates duplicates as it goes.
+                changes = diffRows(this.#rows, snapshot.rows, this.#key);
+            }
+            this.#rows = snapshot.rows;
+            this.#hasReadySnapshot = true;
+            this.#snapshot = {
+                status: "ready",
+                rows: snapshot.rows,
+                changes: Object.freeze(changes),
+                initial,
+                version: snapshot.version,
+            };
+            this.#emit();
+        }
+        catch (error) {
+            this.#snapshot = {
+                status: "error",
+                rows: this.#rows,
+                error,
+                version: snapshot.version,
+            };
+            this.#emit();
+        }
+    }
+    #emit() {
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener();
+            }
+            catch {
+                // Isolate external-store listeners.
+            }
+        }
+    }
+}

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

@@ -0,0 +1,4 @@
+/** Optional typed and keyed live-query APIs. */
+export * from "./live.js";
+export * from "./typed-live.js";
+export * from "./keyed-live.js";

package/dist/engine/live-api.js

@@ -0,0 +1,4 @@
+/** Optional typed and keyed live-query APIs. */
+export * from "./live.js";
+export * from "./typed-live.js";
+export * from "./keyed-live.js";

package/dist/engine/live.d.ts

@@ -1,16 +1,13 @@
-import { type Manifest, type StoragePage } from "../storage/index.js";
+import { type CatalogProbe, type Manifest, type StoragePage } from "../storage/types.js";
 import { type CompiledQuery, type QueryResult, type QueryValue } from "./query.js";
 /**
- * Correctness-first live queries with selective re-execution. Every hint path — a local commit,
- * a cross-tab channel message, a poll tick, or an explicit refresh — converges on the same
- * authoritative check: read the durable manifest version, and when it moved, derive the changed
- * tables from the persisted per-commit change sets in bounded pages. Missed hints therefore delay
- * a refresh but can never produce a stale result, and a manifest without a change set (written
- * before tracking, or outside a transaction) conservatively affects every subscription.
+ * Live-query invalidation is a hint-driven cache-coherence problem, not a notification problem.
+ * Every hint path converges on the store's durable manifest/catalog probe; persisted per-commit
+ * table sets then decide which prepared queries may be stale. Hints may be lost, duplicated, or
+ * reordered without changing correctness.
  *
- * Memory discipline: a subscription retains its plan text, dependency table IDs, and a numeric
- * result digest — never result rows. Results flow to the subscriber and are dropped; unchanged
- * digests suppress the notification entirely.
+ * 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.
  */
 export interface LiveQueryHintChannel {
     postMessage(message: unknown): void;
@@ -20,22 +17,43 @@ export interface LiveQueryHintChannel {
 }
 export interface LiveQuerySetOptions {
     readonly channel?: LiveQueryHintChannel;
-    /**
-     * Convenience form of `channel`: the set creates (and owns, closing it with the set) a
-     * BroadcastChannel of this name when the platform provides one. Ignored when `channel` is
-     * given or BroadcastChannel is unavailable.
-     */
+    /** Creates and owns a BroadcastChannel of this name when the platform provides one. */
     readonly channelName?: string;
     readonly pollIntervalMs?: number;
+    /** Maximum distinct query groups retained by this set. Defaults to 256. */
+    readonly maxGroups?: number;
+    /** Maximum result/observer subscriptions retained by this set. Defaults to 1,024. */
+    readonly maxSubscriptions?: number;
     /** Called once when the set closes; the owner uses this to drop its reference. */
     readonly onClosed?: () => void;
 }
+export declare const DEFAULT_LIVE_QUERY_MAX_GROUPS = 256;
+export declare const DEFAULT_LIVE_QUERY_MAX_SUBSCRIPTIONS = 1024;
+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 declare class LiveQueryLimitError extends Error {
+    readonly resource: "set" | "group" | "subscription";
+    readonly limit: number;
+    readonly name = "LiveQueryLimitError";
+    constructor(resource: "set" | "group" | "subscription", limit: number);
+}
 export interface LiveQuerySubscribeOptions {
     onChange(result: QueryResult): void;
     onError?(error: unknown): void;
     /** Called once when the subscription ends because the subscription or its set closed. */
     onComplete?(): void;
 }
+export interface LiveQueryInvalidation {
+    readonly manifestVersion: number | null;
+    readonly catalogEpoch: number;
+    readonly initial: boolean;
+}
+export interface LiveQueryObserveOptions {
+    onInvalidate(invalidation: LiveQueryInvalidation): void;
+    onError?(error: unknown): void;
+    onComplete?(): void;
+}
 export interface LiveQuerySubscription {
     readonly dependencyTableIds: readonly string[];
     close(): void;
@@ -49,6 +67,10 @@ export interface LiveQueryStats {
     /** Re-runs skipped because the data layer proved the commits could not change the result. */
     zoneSkips: number;
     notificationsSuppressed: number;
+    /** Observer-only invalidations delivered without executing the statement inside the set. */
+    invalidations: number;
+    /** Work avoided because equal statements shared one query group or in-flight execution. */
+    sharedExecutions: number;
     lastSweepMs: number;
 }
 /** A live query: plain SQL, parameterized SQL, or a compiled-plan envelope. */
@@ -61,30 +83,25 @@ export type LiveQueryInput = string | {
     plan: CompiledQuery;
 };
 interface LiveQueryHost {
-    currentVersion(): Promise<number | null>;
+    currentProbe(): Promise<CatalogProbe>;
     manifestPage(afterVersion: number | null, limit: number): Promise<StoragePage<Manifest, number>>;
     dependencyTableIds(query: LiveQueryInput): Promise<Set<string>>;
     execute(query: LiveQueryInput): Promise<QueryResult>;
-    /**
-     * Optional data-layer selectivity: whether commits in (after, until] to the given
-     * dependency tables can possibly change this query's result. A host answers false only
-     * on proof — e.g. every introduced segment is a data-neutral compaction rewrite, or every
-     * new insert block's zone statistics reject the query's predicates — so a false skips the
-     * re-run entirely. Errors and unknown shapes must answer true.
-     */
+    /** 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>;
 }
 export declare class LiveQuerySet {
     #private;
     constructor(host: LiveQueryHost, options?: LiveQuerySetOptions);
     get stats(): LiveQueryStats;
-    /** Registers a query, delivers its initial result, and re-runs it when its tables change. */
+    /** 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. */
+    observe(query: LiveQueryInput, options: LiveQueryObserveOptions): Promise<LiveQuerySubscription>;
     /** Called by the owning database after each local write commit; also hints other tabs. */
     notifyLocalCommit(): void;
-    /** Runs one authoritative version check and selective re-execution sweep. */
+    /** Runs one authoritative probe and selective re-execution sweep. */
     refresh(): Promise<void>;
     close(): void;
 }
 export {};
-//# sourceMappingURL=live.d.ts.map