@minnowdb/core 0.2.1 → 0.4.0

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

@@ -0,0 +1,67 @@
+import type { LiveQueryInput, LiveQueryObserveOptions } from "./live.js";
+/** The structural live-query surface shared by MinnowDatabase and its worker client. */
+export interface LiveQueryBackend {
+    observe(query: LiveQueryInput, options: LiveQueryObserveOptions): Promise<LiveQuerySubscriptionLike>;
+    refresh(): Promise<void>;
+    close(): void | Promise<void>;
+}
+export interface LiveQuerySubscriptionLike {
+    readonly dependencyTableIds: readonly string[];
+    close(): void | Promise<void>;
+}
+export interface LiveQueryDriver {
+    liveQueries(options?: {
+        channelName?: string;
+        pollIntervalMs?: number;
+    }): LiveQueryBackend;
+}
+/**
+ * Adapter-neutral query boundary. `query` drives dependency tracking in Minnow; `execute`
+ * deliberately stays with the adapter so its result transforms and inferred row type survive.
+ */
+export interface LiveQuerySource<out TRow> {
+    readonly query: LiveQueryInput;
+    execute(signal?: AbortSignal): Promise<readonly TRow[]>;
+}
+export type LiveSnapshot<TRow> = {
+    readonly status: "loading";
+    readonly rows: readonly TRow[];
+} | {
+    readonly status: "ready";
+    readonly rows: readonly TRow[];
+    readonly version: number | null;
+} | {
+    readonly status: "error";
+    readonly rows: readonly TRow[];
+    readonly error: unknown;
+    readonly version: number | null;
+};
+/**
+ * One typed live SELECT. It is also a framework-neutral external store: getSnapshot is stable
+ * until state changes and subscribe returns synchronous cleanup. Slow consumers coalesce to the
+ * newest invalidation; errors retain the last good rows.
+ */
+export declare class LiveQuery<out TRow> implements AsyncIterable<LiveSnapshot<TRow>> {
+    #private;
+    /** Type-only row helper (`typeof query.$inferRow`). */
+    readonly $inferRow: TRow;
+    constructor(backend: LiveQueryBackend, source: LiveQuerySource<TRow>, onClose?: () => void);
+    getSnapshot: () => LiveSnapshot<TRow>;
+    subscribe: (listener: () => void) => (() => void);
+    refresh(): Promise<void>;
+    close(): void;
+    [Symbol.asyncIterator](): AsyncIterator<LiveSnapshot<TRow>, undefined>;
+}
+export interface LiveQueryManagerOptions {
+    readonly channelName?: string;
+    readonly pollIntervalMs?: number;
+}
+/** Owns one shared low-level set and every typed query created from it. */
+export declare class LiveQueryManager {
+    #private;
+    constructor(driver: LiveQueryDriver, options?: LiveQueryManagerOptions);
+    watch<TRow>(source: LiveQuerySource<TRow>): LiveQuery<TRow>;
+    refresh(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createLiveQueryManager(driver: LiveQueryDriver, options?: LiveQueryManagerOptions): LiveQueryManager;

package/dist/engine/typed-live.js

@@ -0,0 +1,349 @@
+import { dateMilliseconds } from "../date-value.js";
+function sameLiveValue(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 (!sameLiveValue(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 (!sameLiveValue(leftRecord[key], rightRecord[key]))
+            return false;
+    }
+    return true;
+}
+function sameRows(left, right) {
+    return sameLiveValue(left, right);
+}
+function immutableRows(rows) {
+    // Adapters own their values. Copy the array so mutating the returned builder result cannot
+    // change the snapshot identity retained for exact suppression.
+    return Object.freeze([...rows]);
+}
+/**
+ * One typed live SELECT. It is also a framework-neutral external store: getSnapshot is stable
+ * until state changes and subscribe returns synchronous cleanup. Slow consumers coalesce to the
+ * newest invalidation; errors retain the last good rows.
+ */
+export class LiveQuery {
+    #listeners = new Set();
+    #source;
+    #backend;
+    #onClose;
+    #snapshot = { status: "loading", rows: [] };
+    #subscription;
+    #observationGeneration = 0;
+    #queued;
+    #execution;
+    #executionAbort;
+    #invalidationSequence = 0;
+    #closed = false;
+    constructor(backend, source, onClose) {
+        this.#backend = backend;
+        this.#source = source;
+        this.#onClose = onClose;
+    }
+    getSnapshot = () => this.#snapshot;
+    subscribe = (listener) => {
+        if (this.#closed)
+            throw new Error("Live query is closed");
+        // A subscription is a lease, even when a framework reuses the same callback function.
+        const registered = () => listener();
+        this.#listeners.add(registered);
+        if (this.#listeners.size === 1)
+            this.#startObservation();
+        let subscribed = true;
+        return () => {
+            if (!subscribed)
+                return;
+            subscribed = false;
+            this.#listeners.delete(registered);
+            if (this.#listeners.size === 0)
+                this.#stopObservation();
+        };
+    };
+    async refresh() {
+        if (this.#closed)
+            throw new Error("Live query is closed");
+        const sequence = this.#invalidationSequence;
+        if (this.#listeners.size > 0) {
+            // A transient dependency/observer setup failure must not strand existing subscribers.
+            // Re-open first so this refresh and future commits reach the query again.
+            if (this.#subscription === undefined)
+                this.#startObservation();
+            const opening = this.#subscription;
+            if (opening !== undefined)
+                await opening.catch(() => undefined);
+            await this.#backend.refresh();
+        }
+        // A backend refresh normally invalidates observers itself. Only synthesize an execution
+        // when it did not, which preserves manual retry without running every refreshed query twice.
+        if (this.#invalidationSequence === sequence) {
+            const version = this.#snapshot.status === "loading" ? null : this.#snapshot.version;
+            this.#schedule({ manifestVersion: version, catalogEpoch: 0, initial: false });
+        }
+        await this.#waitForIdle();
+    }
+    close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#observationGeneration += 1;
+        this.#executionAbort?.abort(new Error("Live query is closed"));
+        const subscription = this.#subscription;
+        this.#subscription = undefined;
+        if (subscription !== undefined) {
+            void subscription.then((handle) => handle.close()).catch(() => undefined);
+        }
+        // Wake iterators before removing their listeners so a parked next() terminates.
+        this.#emit();
+        this.#listeners.clear();
+        this.#onClose?.();
+    }
+    #startObservation() {
+        if (this.#subscription !== undefined || this.#closed)
+            return;
+        const generation = (this.#observationGeneration += 1);
+        const subscription = this.#backend.observe(this.#source.query, {
+            onInvalidate: (invalidation) => {
+                if (generation !== this.#observationGeneration || this.#closed)
+                    return;
+                this.#schedule(invalidation);
+            },
+            onError: (error) => {
+                if (generation !== this.#observationGeneration || this.#closed)
+                    return;
+                this.#setError(error, this.#currentVersion());
+            },
+            onComplete: () => {
+                if (generation !== this.#observationGeneration)
+                    return;
+                this.#subscription = undefined;
+            },
+        });
+        this.#subscription = subscription;
+        subscription.catch((error) => {
+            if (generation !== this.#observationGeneration || this.#closed)
+                return;
+            this.#subscription = undefined;
+            this.#setError(error, this.#currentVersion());
+        });
+    }
+    #stopObservation() {
+        this.#observationGeneration += 1;
+        this.#executionAbort?.abort(new Error("Live query has no subscribers"));
+        const subscription = this.#subscription;
+        this.#subscription = undefined;
+        if (subscription !== undefined) {
+            void subscription.then((handle) => handle.close()).catch(() => undefined);
+        }
+    }
+    #schedule(invalidation) {
+        this.#invalidationSequence += 1;
+        this.#queued = invalidation;
+        if (this.#execution !== undefined)
+            return;
+        const execution = this.#drain();
+        this.#execution = execution;
+        void execution.finally(() => {
+            if (this.#execution === execution)
+                this.#execution = undefined;
+            if (this.#queued !== undefined && !this.#closed)
+                this.#schedule(this.#queued);
+        });
+    }
+    async #drain() {
+        while (this.#queued !== undefined && !this.#closed) {
+            const invalidation = this.#queued;
+            this.#queued = undefined;
+            const abort = new AbortController();
+            this.#executionAbort = abort;
+            try {
+                const rows = immutableRows(await this.#source.execute(abort.signal));
+                if (this.#executionWasCancelled(abort))
+                    continue;
+                // A newer invalidation arrived while this ran. Skip the intermediate snapshot and let
+                // the loop execute once more against the newest durable state.
+                if (this.#hasQueuedInvalidation())
+                    continue;
+                const previous = this.#snapshot.rows;
+                if (this.#snapshot.status === "ready" &&
+                    this.#snapshot.version === invalidation.manifestVersion &&
+                    sameRows(previous, rows)) {
+                    continue;
+                }
+                if (sameRows(previous, rows) && this.#snapshot.status !== "loading") {
+                    // Advance the version without replacing the immutable row array.
+                    this.#snapshot = {
+                        status: "ready",
+                        rows: previous,
+                        version: invalidation.manifestVersion,
+                    };
+                }
+                else {
+                    this.#snapshot = {
+                        status: "ready",
+                        rows,
+                        version: invalidation.manifestVersion,
+                    };
+                }
+                this.#emit();
+            }
+            catch (error) {
+                if (this.#executionWasCancelled(abort) || this.#hasQueuedInvalidation())
+                    continue;
+                this.#setError(error, invalidation.manifestVersion);
+            }
+            finally {
+                if (this.#executionAbort === abort)
+                    this.#executionAbort = undefined;
+            }
+        }
+    }
+    #executionWasCancelled(abort) {
+        return abort.signal.aborted || this.#closed;
+    }
+    #hasQueuedInvalidation() {
+        return this.#queued !== undefined;
+    }
+    async #waitForIdle() {
+        for (;;) {
+            const execution = this.#execution;
+            if (execution === undefined)
+                return;
+            await execution;
+            if (this.#execution === undefined && this.#queued === undefined)
+                return;
+        }
+    }
+    #currentVersion() {
+        return this.#snapshot.status === "loading" ? null : this.#snapshot.version;
+    }
+    #setError(error, version) {
+        this.#snapshot = { status: "error", rows: this.#snapshot.rows, error, version };
+        this.#emit();
+    }
+    #emit() {
+        for (const listener of [...this.#listeners]) {
+            try {
+                listener();
+            }
+            catch {
+                // One framework listener must not prevent the others from observing the same snapshot.
+            }
+        }
+    }
+    [Symbol.asyncIterator]() {
+        const inbox = {
+            latest: this.#snapshot,
+            hasLatest: true,
+            stopped: false,
+            notify: undefined,
+        };
+        const wake = () => {
+            const notify = inbox.notify;
+            inbox.notify = undefined;
+            notify?.();
+        };
+        const unsubscribe = this.subscribe(() => {
+            inbox.latest = this.#snapshot;
+            inbox.hasLatest = true;
+            wake();
+        });
+        const done = { done: true, value: undefined };
+        const read = async () => {
+            for (;;) {
+                if (inbox.stopped || this.#closed)
+                    return done;
+                if (inbox.hasLatest) {
+                    inbox.hasLatest = false;
+                    return { done: false, value: inbox.latest };
+                }
+                await new Promise((resolve) => {
+                    inbox.notify = resolve;
+                });
+            }
+        };
+        let queue = Promise.resolve();
+        return {
+            next: () => {
+                const result = queue.then(read, read);
+                queue = result.then(() => undefined, () => undefined);
+                return result;
+            },
+            return: async () => {
+                inbox.stopped = true;
+                wake();
+                unsubscribe();
+                return done;
+            },
+            throw: async (error) => {
+                inbox.stopped = true;
+                wake();
+                unsubscribe();
+                throw error;
+            },
+        };
+    }
+}
+/** Owns one shared low-level set and every typed query created from it. */
+export class LiveQueryManager {
+    #backend;
+    #queries = new Set();
+    #closed = false;
+    constructor(driver, options = {}) {
+        this.#backend = driver.liveQueries(options);
+    }
+    watch(source) {
+        if (this.#closed)
+            throw new Error("Live query manager is closed");
+        const query = new LiveQuery(this.#backend, source, () => {
+            this.#queries.delete(query);
+        });
+        this.#queries.add(query);
+        return query;
+    }
+    async refresh() {
+        if (this.#closed)
+            throw new Error("Live query manager is closed");
+        // The shared backend sweep remains selective. Queries that were already in an adapter-level
+        // error also run their local retry path; concurrent backend refresh calls collapse into the
+        // same low-level sweep, so this does not multiply durable probes.
+        const failed = [...this.#queries].filter((query) => query.getSnapshot().status === "error");
+        await Promise.all([this.#backend.refresh(), ...failed.map((query) => query.refresh())]);
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        for (const query of [...this.#queries])
+            query.close();
+        this.#queries.clear();
+        await this.#backend.close();
+    }
+}
+export function createLiveQueryManager(driver, options = {}) {
+    return new LiveQueryManager(driver, options);
+}

package/dist/engine/vector.d.ts

@@ -43,11 +43,16 @@ export interface ColumnarTable {
     readonly rowCount: number;
     readonly columns: ReadonlyMap<string, ColumnVector>;
     readonly uniqueKey?: string;
+    /** Optional physical-row permutation supplied by an exact index-ordered materialization. */
+    readonly scanOrder?: Uint32Array;
+    /** True only when that permutation satisfies this prepared plan's complete ORDER BY. */
+    readonly orderedForPlan?: true;
 }
 export interface PreparedVectorQuery {
     readonly memoryUsage: QueryMemoryUsage;
     execute(): QueryResult;
     executeAsync(options?: AsyncQueryExecutionOptions): Promise<QueryResult>;
+    executeBatches(options: QueryBatchExecutionOptions, consume: (batch: QueryResult) => void | Promise<void>): Promise<readonly string[]>;
     close(): void;
 }
 export interface QuerySpillStore {
@@ -80,6 +85,12 @@ export interface AsyncQueryExecutionOptions {
      */
     readonly loadScanWindow?: (start: number, length: number) => number | Promise<number>;
 }
+export interface QueryBatchExecutionOptions extends AsyncQueryExecutionOptions {
+    /** Maximum result rows handed to the consumer at once. */
+    readonly batchRows: number;
+    /** Stops before the next scan batch and is checked after every awaited storage read. */
+    readonly signal?: AbortSignal;
+}
 export interface PrepareVectorQueryOptions {
     readonly memoryContext?: QueryMemoryContext;
     /**
@@ -91,8 +102,7 @@ export interface PrepareVectorQueryOptions {
     readonly ftsStats?: ReadonlyMap<string, FtsStats>;
 }
 export declare function createColumnarTable(name: string, columns: ReadonlyMap<string, ColumnarColumnInput>, uniqueKey?: string): ColumnarTable;
-export declare function columnarTableFromRows(name: string, rows: readonly DatabaseRow[], projectedColumnNames?: readonly string[]): ColumnarTable;
+export declare function columnarTableFromRows(name: string, rows: readonly DatabaseRow[], projectedColumnNames?: readonly string[], protectText?: boolean): ColumnarTable;
 export declare function prepareVectorQuery(plan: CompiledQuery, inputTables: ReadonlyMap<string, ColumnarTable>, options?: PrepareVectorQueryOptions): PreparedVectorQuery;
 export declare function vectorValue(vector: ColumnVector, rowIndex: number): QueryValue;
 export {};
-//# sourceMappingURL=vector.d.ts.map