@rxferrix/client 0.0.0-stage → 0.1.0

package/dist/optimistic_updates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimistic_updates.js","sourceRoot":"","sources":["../src/optimistic_updates.ts"],"names":[],"mappings":"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"}

package/dist/paginated_query.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Reactive pagination on top of {@link RxFerrixClient.watchQuery}.
+ *
+ * A paginated query is a server query that takes `paginationOpts: PaginationOpts` and returns a
+ * `PaginationResult<Item>` (in Rust: `Query::paginate`). The client subscribes to it once per loaded page:
+ *
+ * - Page 0 is `{ ...args, paginationOpts: { numItems: initialNumItems, cursor: null } }`.
+ * - `loadMore(n)` subscribes to the next page, starting at the last page's `continueCursor`.
+ * - When a page gets a successor, it is re-subscribed with `endCursor` pinned to the cursor the successor starts at.
+ *   A pinned page covers a fixed span of the index, so inserts and deletes make it grow or shrink instead of
+ *   shifting documents into (or out of) its neighbours: no duplicates or gaps between pages. The unpinned
+ *   subscription stays visible until the pinned one has a result, so the swap does not flash a loading state.
+ *
+ * Only the last page is unpinned; it grows up to its `numItems` when documents are added after it.
+ */
+import type { ArgsOf, FunctionReference, OutputOf } from "./api.js";
+import type { RxFerrixClient } from "./client.js";
+import type { RxFerrixError } from "./errors.js";
+import type { OptimisticLocalStore } from "./optimistic_updates.js";
+/** Which page to read: the `paginationOpts` argument of a paginated query (Rust `rxferrix::PaginationOpts`). */
+export interface PaginationOpts {
+    /** How many items to return (ignored when `endCursor` is set). */
+    numItems: number;
+    /** Where the page starts: `null` for the start, otherwise a previous page's `continueCursor`. */
+    cursor: string | null;
+    /** Where the page ends. When set, the page holds every item between `cursor` and `endCursor`. */
+    endCursor?: string | null;
+}
+/** One page of results (Rust `rxferrix::PaginationResult<T>`). */
+export interface PaginationResult<T> {
+    page: T[];
+    /** True when there is nothing after this page. */
+    isDone: boolean;
+    /** Where the next page starts. */
+    continueCursor: string;
+}
+/** A reference to a query whose args include `paginationOpts` and whose output is a {@link PaginationResult}. */
+export type PaginatedQueryReference<Item = any> = FunctionReference<"query", {
+    paginationOpts: PaginationOpts;
+}, PaginationResult<Item>>;
+/** The item type of a paginated query. */
+export type PaginatedQueryItem<Q> = OutputOf<Q> extends PaginationResult<infer Item> ? Item : never;
+/** The args of a paginated query without `paginationOpts` (the client manages those). */
+export type PaginatedQueryArgs<Q> = Omit<ArgsOf<Q>, "paginationOpts">;
+export type PaginationStatus = "LoadingFirstPage" | "CanLoadMore" | "LoadingMore" | "Exhausted";
+export interface PaginatedQueryResult<Item> {
+    /** The items of every loaded page, in order. */
+    readonly results: Item[];
+    readonly status: PaginationStatus;
+    /** True while the first page or a further page is loading (and no page failed). */
+    readonly isLoading: boolean;
+    /** The error of the first failed page, if any. A failed page counts as not loaded for `status`. */
+    readonly error: RxFerrixError | undefined;
+    /**
+     * Loads `numItems` more items. Does nothing (and returns false) unless the last page is loaded and not done
+     * (status `"CanLoadMore"`).
+     */
+    loadMore(numItems: number): boolean;
+}
+export interface PaginatedQueryOptions {
+    /** The size of the first page. */
+    initialNumItems: number;
+}
+/** A framework-agnostic paginated query. Pages are subscribed while at least one `subscribe` callback is registered. */
+export interface PaginatedQuery<Item> {
+    /** Registers `callback` to be called whenever {@link getCurrent} changes. Returns the unsubscribe function. */
+    subscribe(callback: () => void): () => void;
+    /** The current results. The object is referentially stable until something visible changes. */
+    getCurrent(): PaginatedQueryResult<Item>;
+}
+/** @internal Created by {@link RxFerrixClient.paginatedQuery}. */
+export declare class PaginatedQueryImpl<Item> implements PaginatedQuery<Item> {
+    private readonly client;
+    private readonly ref;
+    private readonly pages;
+    private readonly listeners;
+    private readonly args;
+    private snapshot;
+    /** The page states `snapshot` was built from. */
+    private snapshotStates;
+    constructor(client: RxFerrixClient, ref: FunctionReference<"query">, args: Record<string, unknown>, options: PaginatedQueryOptions);
+    subscribe(callback: () => void): () => void;
+    getCurrent(): PaginatedQueryResult<Item>;
+    private loadMore;
+    /** The state a page shows: its pinned replacement once that has a result, otherwise the current subscription. */
+    private displayed;
+    private makeSub;
+    private activate;
+    private deactivate;
+    private onPageUpdate;
+    private notify;
+}
+/**
+ * Every loaded page of a paginated query in the optimistic store, with its args (including `paginationOpts`).
+ * Pass `argsToMatch` (args without `paginationOpts`, or a subset of them) to keep only one paginated query's pages.
+ */
+export declare function getAllPages<Q extends PaginatedQueryReference>(localStore: OptimisticLocalStore, ref: Q, argsToMatch?: Partial<PaginatedQueryArgs<Q>>): {
+    args: ArgsOf<Q>;
+    value: PaginationResult<PaginatedQueryItem<Q>>;
+}[];
+/**
+ * Optimistically inserts `item` at the top of the first page of a paginated query (every paginated query of `ref`
+ * whose args match `argsToMatch`). Typical for "newest first" lists:
+ *
+ * ```ts
+ * const send = useMutation(api.messages.send).withOptimisticUpdate((store, args) => {
+ *   insertAtTop({ paginatedQuery: api.messages.list, argsToMatch: { channel: args.channel }, localQueryStore: store,
+ *     item: { _id: "optimistic" as Id<"messages">, _creationTime: Date.now(), ...args } });
+ * });
+ * ```
+ */
+export declare function insertAtTop<Q extends PaginatedQueryReference>(options: {
+    paginatedQuery: Q;
+    argsToMatch?: Partial<PaginatedQueryArgs<Q>>;
+    localQueryStore: OptimisticLocalStore;
+    item: PaginatedQueryItem<Q>;
+}): void;
+//# sourceMappingURL=paginated_query.d.ts.map

package/dist/paginated_query.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginated_query.d.ts","sourceRoot":"","sources":["../src/paginated_query.ts"],"names":[],"mappings":"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"}

package/dist/paginated_query.js

@@ -0,0 +1,199 @@
+import { jsonEqual, normalizeArgs } from "./canonical.js";
+function validateNumItems(numItems, what) {
+    if (!Number.isInteger(numItems) || numItems < 1) {
+        throw new Error(`${what} must be a positive integer, got ${numItems}`);
+    }
+}
+/** @internal Created by {@link RxFerrixClient.paginatedQuery}. */
+export class PaginatedQueryImpl {
+    client;
+    ref;
+    pages = [];
+    listeners = new Set();
+    args;
+    snapshot = null;
+    /** The page states `snapshot` was built from. */
+    snapshotStates = [];
+    constructor(client, ref, args, options) {
+        this.client = client;
+        this.ref = ref;
+        validateNumItems(options?.initialNumItems, "initialNumItems");
+        const { paginationOpts: _ignored, ...rest } = normalizeArgs(args);
+        this.args = rest;
+        this.pages.push({ current: this.makeSub({ numItems: options.initialNumItems, cursor: null }), pending: null });
+    }
+    subscribe(callback) {
+        const entry = () => callback();
+        this.listeners.add(entry);
+        if (this.listeners.size === 1) {
+            for (const page of this.pages) {
+                this.activate(page.current);
+                if (page.pending)
+                    this.activate(page.pending);
+            }
+        }
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            this.listeners.delete(entry);
+            if (this.listeners.size === 0) {
+                for (const page of this.pages) {
+                    this.deactivate(page.current);
+                    if (page.pending)
+                        this.deactivate(page.pending);
+                }
+            }
+        };
+    }
+    getCurrent() {
+        const states = this.pages.map((p) => this.displayed(p));
+        if (this.snapshot && states.length === this.snapshotStates.length && states.every((s, i) => s === this.snapshotStates[i])) {
+            return this.snapshot;
+        }
+        let results = [];
+        let loading = false;
+        let error;
+        for (const state of states) {
+            if (state.status === "success")
+                results = results.concat(state.value.page);
+            else if (state.status === "loading")
+                loading = true;
+            else
+                error ??= state.error;
+        }
+        const last = states[states.length - 1];
+        let status;
+        if (loading || error !== undefined) {
+            status = results.length === 0 && states[0]?.status !== "success" ? "LoadingFirstPage" : "LoadingMore";
+        }
+        else if (last?.status === "success" && last.value.isDone) {
+            status = "Exhausted";
+        }
+        else {
+            status = "CanLoadMore";
+        }
+        this.snapshotStates = states;
+        const previous = this.snapshot;
+        // E.g. a page swapped for its pinned copy: new state objects, same items. Keep the snapshot (no re-render).
+        if (previous && previous.status === status && previous.error === error && jsonEqual(previous.results, results)) {
+            return previous;
+        }
+        this.snapshot = {
+            results,
+            status,
+            isLoading: error === undefined && (status === "LoadingFirstPage" || status === "LoadingMore"),
+            error,
+            loadMore: (numItems) => this.loadMore(numItems),
+        };
+        return this.snapshot;
+    }
+    loadMore(numItems) {
+        validateNumItems(numItems, "loadMore(numItems)");
+        const last = this.pages[this.pages.length - 1];
+        if (!last)
+            return false;
+        const state = this.displayed(last);
+        if (state.status !== "success" || state.value.isDone)
+            return false;
+        const cursor = state.value.continueCursor;
+        // Pin the page to where its successor starts (it covers the same span, so it shows the same items).
+        const shown = last.pending && last.pending.watch.localQueryState().status !== "loading" ? last.pending : last.current;
+        if (shown.opts.endCursor == null) {
+            if (last.pending)
+                this.deactivate(last.pending);
+            last.pending = this.makeSub({ ...shown.opts, endCursor: cursor });
+            if (this.listeners.size > 0)
+                this.activate(last.pending);
+        }
+        const next = { current: this.makeSub({ numItems, cursor }), pending: null };
+        this.pages.push(next);
+        if (this.listeners.size > 0)
+            this.activate(next.current);
+        this.notify();
+        return true;
+    }
+    /** The state a page shows: its pinned replacement once that has a result, otherwise the current subscription. */
+    displayed(page) {
+        if (page.pending) {
+            const pending = page.pending.watch.localQueryState();
+            if (pending.status !== "loading")
+                return pending;
+        }
+        return page.current.watch.localQueryState();
+    }
+    makeSub(opts) {
+        const args = { ...this.args, paginationOpts: opts };
+        const watch = this.client.watchQuery(this.ref, args);
+        return { opts, watch, unsubscribe: null };
+    }
+    activate(sub) {
+        if (!sub.unsubscribe)
+            sub.unsubscribe = sub.watch.onUpdate(() => this.onPageUpdate());
+    }
+    deactivate(sub) {
+        sub.unsubscribe?.();
+        sub.unsubscribe = null;
+    }
+    onPageUpdate() {
+        // Complete the swaps whose pinned page has a result. Done here (not in getCurrent) to keep reads side-effect free.
+        for (const page of this.pages) {
+            if (page.pending && page.pending.watch.localQueryState().status !== "loading") {
+                this.deactivate(page.current);
+                page.current = page.pending;
+                page.pending = null;
+            }
+        }
+        this.notify();
+    }
+    notify() {
+        const before = this.snapshot;
+        if (this.getCurrent() === before)
+            return;
+        for (const listener of [...this.listeners])
+            listener();
+    }
+}
+// ---------------------------------------------------------------------------------------------------------------------
+// Optimistic update helpers
+/** Does every key of `argsToMatch` equal the corresponding arg of a page? */
+function argsMatch(args, argsToMatch) {
+    if (!argsToMatch)
+        return true;
+    return Object.entries(argsToMatch).every(([k, v]) => v === undefined || jsonEqual(args[k], v));
+}
+/**
+ * Every loaded page of a paginated query in the optimistic store, with its args (including `paginationOpts`).
+ * Pass `argsToMatch` (args without `paginationOpts`, or a subset of them) to keep only one paginated query's pages.
+ */
+export function getAllPages(localStore, ref, argsToMatch) {
+    const out = [];
+    for (const { args, value } of localStore.getAllQueries(ref)) {
+        if (value === undefined || !argsMatch(args, argsToMatch))
+            continue;
+        out.push({ args, value: value });
+    }
+    return out;
+}
+/**
+ * Optimistically inserts `item` at the top of the first page of a paginated query (every paginated query of `ref`
+ * whose args match `argsToMatch`). Typical for "newest first" lists:
+ *
+ * ```ts
+ * const send = useMutation(api.messages.send).withOptimisticUpdate((store, args) => {
+ *   insertAtTop({ paginatedQuery: api.messages.list, argsToMatch: { channel: args.channel }, localQueryStore: store,
+ *     item: { _id: "optimistic" as Id<"messages">, _creationTime: Date.now(), ...args } });
+ * });
+ * ```
+ */
+export function insertAtTop(options) {
+    const { paginatedQuery, argsToMatch, localQueryStore, item } = options;
+    for (const { args, value } of getAllPages(localQueryStore, paginatedQuery, argsToMatch)) {
+        const opts = args.paginationOpts;
+        if (opts?.cursor !== null)
+            continue;
+        localQueryStore.setQuery(paginatedQuery, args, { ...value, page: [item, ...value.page] });
+    }
+}
+//# sourceMappingURL=paginated_query.js.map

package/dist/paginated_query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paginated_query.js","sourceRoot":"","sources":["../src/paginated_query.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAiF1D,SAAS,gBAAgB,CAAC,QAAgB,EAAE,IAAY;IACtD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,EAAE,CAAC;QAChD,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,oCAAoC,QAAQ,EAAE,CAAC,CAAC;IACzE,CAAC;AACH,CAAC;AAED,kEAAkE;AAClE,MAAM,OAAO,kBAAkB;IASV;IACA;IATF,KAAK,GAAiB,EAAE,CAAC;IACzB,SAAS,GAAG,IAAI,GAAG,EAAc,CAAC;IAClC,IAAI,CAA0B;IACvC,QAAQ,GAAsC,IAAI,CAAC;IAC3D,iDAAiD;IACzC,cAAc,GAAiB,EAAE,CAAC;IAE1C,YACmB,MAAsB,EACtB,GAA+B,EAChD,IAA6B,EAC7B,OAA8B;QAHb,WAAM,GAAN,MAAM,CAAgB;QACtB,QAAG,GAAH,GAAG,CAA4B;QAIhD,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,iBAAiB,CAAC,CAAC;QAC9D,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;QAClE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,eAAe,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IACjH,CAAC;IAED,SAAS,CAAC,QAAoB;QAC5B,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,QAAQ,EAAE,CAAC;QAC/B,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QAC1B,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;YAC9B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;gBAC9B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC5B,IAAI,IAAI,CAAC,OAAO;oBAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QACD,IAAI,MAAM,GAAG,IAAI,CAAC;QAClB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,MAAM,GAAG,KAAK,CAAC;YACf,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC7B,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;gBAC9B,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;oBAC9B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;oBAC9B,IAAI,IAAI,CAAC,OAAO;wBAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAClD,CAAC;YACH,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED,UAAU;QACR,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;QACxD,IAAI,IAAI,CAAC,QAAQ,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,CAAC,cAAc,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1H,OAAO,IAAI,CAAC,QAAQ,CAAC;QACvB,CAAC;QACD,IAAI,OAAO,GAAW,EAAE,CAAC;QACzB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,KAAgC,CAAC;QACrC,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;gBAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;iBACtE,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS;gBAAE,OAAO,GAAG,IAAI,CAAC;;gBAC/C,KAAK,KAAK,KAAK,CAAC,KAAK,CAAC;QAC7B,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACvC,IAAI,MAAwB,CAAC;QAC7B,IAAI,OAAO,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACnC,MAAM,GAAG,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,aAAa,CAAC;QACxG,CAAC;aAAM,IAAI,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;YAC3D,MAAM,GAAG,WAAW,CAAC;QACvB,CAAC;aAAM,CAAC;YACN,MAAM,GAAG,aAAa,CAAC;QACzB,CAAC;QACD,IAAI,CAAC,cAAc,GAAG,MAAM,CAAC;QAC7B,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC/B,4GAA4G;QAC5G,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,IAAI,QAAQ,CAAC,KAAK,KAAK,KAAK,IAAI,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,CAAC;YAC/G,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,IAAI,CAAC,QAAQ,GAAG;YACd,OAAO;YACP,MAAM;YACN,SAAS,EAAE,KAAK,KAAK,SAAS,IAAI,CAAC,MAAM,KAAK,kBAAkB,IAAI,MAAM,KAAK,aAAa,CAAC;YAC7F,KAAK;YACL,QAAQ,EAAE,CAAC,QAAgB,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;SACxD,CAAC;QACF,OAAO,IAAI,CAAC,QAAQ,CAAC;IACvB,CAAC;IAEO,QAAQ,CAAC,QAAgB;QAC/B,gBAAgB,CAAC,QAAQ,EAAE,oBAAoB,CAAC,CAAC;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QAC/C,IAAI,CAAC,IAAI;YAAE,OAAO,KAAK,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM;YAAE,OAAO,KAAK,CAAC;QACnE,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC;QAC1C,oGAAoG;QACpG,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC;QACtH,IAAI,KAAK,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,EAAE,CAAC;YACjC,IAAI,IAAI,CAAC,OAAO;gBAAE,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAChD,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC;YAClE,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC;gBAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAC3D,CAAC;QACD,MAAM,IAAI,GAAe,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACxF,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,GAAG,CAAC;YAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzD,IAAI,CAAC,MAAM,EAAE,CAAC;QACd,OAAO,IAAI,CAAC;IACd,CAAC;IAED,iHAAiH;IACzG,SAAS,CAAC,IAAgB;QAChC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACjB,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;YACrD,IAAI,OAAO,CAAC,MAAM,KAAK,SAAS;gBAAE,OAAO,OAAO,CAAC;QACnD,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC;IAC9C,CAAC;IAEO,OAAO,CAAC,IAAoB;QAClC,MAAM,IAAI,GAAG,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;QACpD,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,IAAa,CAAuC,CAAC;QACpG,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;IAC5C,CAAC;IAEO,QAAQ,CAAC,GAAkB;QACjC,IAAI,CAAC,GAAG,CAAC,WAAW;YAAE,GAAG,CAAC,WAAW,GAAG,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IACxF,CAAC;IAEO,UAAU,CAAC,GAAkB;QACnC,GAAG,CAAC,WAAW,EAAE,EAAE,CAAC;QACpB,GAAG,CAAC,WAAW,GAAG,IAAI,CAAC;IACzB,CAAC;IAEO,YAAY;QAClB,mHAAmH;QACnH,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAC9B,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,eAAe,EAAE,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBAC9E,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC9B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;gBAC5B,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;YACtB,CAAC;QACH,CAAC;QACD,IAAI,CAAC,MAAM,EAAE,CAAC;IAChB,CAAC;IAEO,MAAM;QACZ,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC;QAC7B,IAAI,IAAI,CAAC,UAAU,EAAE,KAAK,MAAM;YAAE,OAAO;QACzC,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC;YAAE,QAAQ,EAAE,CAAC;IACzD,CAAC;CACF;AAED,wHAAwH;AACxH,4BAA4B;AAE5B,6EAA6E;AAC7E,SAAS,SAAS,CAAC,IAA6B,EAAE,WAAgD;IAChG,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAC9B,OAAO,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AACjG,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CACzB,UAAgC,EAChC,GAAM,EACN,WAA4C;IAE5C,MAAM,GAAG,GAA0E,EAAE,CAAC;IACtF,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,UAAU,CAAC,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5D,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,IAA+B,EAAE,WAAsC,CAAC;YAAE,SAAS;QACzH,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAgD,EAAE,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAoC,OAK9D;IACC,MAAM,EAAE,cAAc,EAAE,WAAW,EAAE,eAAe,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC;IACvE,KAAK,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,WAAW,CAAC,eAAe,EAAE,cAAc,EAAE,WAAW,CAAC,EAAE,CAAC;QACxF,MAAM,IAAI,GAAI,IAA4C,CAAC,cAAc,CAAC;QAC1E,IAAI,IAAI,EAAE,MAAM,KAAK,IAAI;YAAE,SAAS;QACpC,eAAe,CAAC,QAAQ,CAAC,cAAc,EAAE,IAAI,EAAE,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,EAAiB,CAAC,CAAC;IAC3G,CAAC;AACH,CAAC"}

package/dist/protocol.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Wire types for the RxFerrix sync protocol (v1). See `docs/PROTOCOL.md` in the repository; that document is normative.
+ */
+export type QueryId = number;
+export type RequestId = number;
+export type JSONValue = null | boolean | number | string | JSONValue[] | {
+    [key: string]: JSONValue;
+};
+export declare const CLIENT_VERSION = "0.1.0";
+export interface StateVersion {
+    querySet: number;
+    identity: number;
+    ts: number;
+}
+/** `{ code, data }` attached to user errors. */
+export interface ErrorData {
+    code: string;
+    data?: unknown;
+}
+export interface ConnectMessage {
+    type: "Connect";
+    sessionId: string;
+    connectionCount: number;
+    lastCloseReason: string | null;
+    clientVersion: string;
+    /** Optional protocol features this client supports: `"diffs"` (results may arrive as diffs, see `diff.ts`). */
+    features?: string[];
+}
+export type QuerySetModification = {
+    type: "Add";
+    queryId: QueryId;
+    udfPath: string;
+    args: Record<string, unknown>;
+} | {
+    type: "Remove";
+    queryId: QueryId;
+};
+export interface ModifyQuerySetMessage {
+    type: "ModifyQuerySet";
+    baseVersion: number;
+    newVersion: number;
+    modifications: QuerySetModification[];
+}
+export interface MutationMessage {
+    type: "Mutation";
+    requestId: RequestId;
+    udfPath: string;
+    args: Record<string, unknown>;
+}
+export interface ActionMessage {
+    type: "Action";
+    requestId: RequestId;
+    udfPath: string;
+    args: Record<string, unknown>;
+}
+export interface AuthenticateMessage {
+    type: "Authenticate";
+    baseVersion: number;
+    token: string | null;
+}
+export interface PongMessage {
+    type: "Pong";
+}
+export type ClientMessage = ConnectMessage | ModifyQuerySetMessage | MutationMessage | ActionMessage | AuthenticateMessage | PongMessage;
+export type StateModification = {
+    type: "QueryUpdated";
+    queryId: QueryId;
+    value: unknown;
+    logLines?: string[];
+}
+/** The new result as a diff from the result this connection last received for the query (`diff.ts`). */
+ | {
+    type: "QueryUpdated";
+    queryId: QueryId;
+    diff: unknown;
+    logLines?: string[];
+} | {
+    type: "QueryFailed";
+    queryId: QueryId;
+    errorMessage: string;
+    errorData?: ErrorData | null;
+    logLines?: string[];
+} | {
+    type: "QueryRemoved";
+    queryId: QueryId;
+};
+export interface TransitionMessage {
+    type: "Transition";
+    startVersion: StateVersion;
+    endVersion: StateVersion;
+    modifications: StateModification[];
+}
+export type MutationResponseMessage = {
+    type: "MutationResponse";
+    requestId: RequestId;
+    success: true;
+    result: unknown;
+    ts: number;
+    logLines?: string[];
+} | {
+    type: "MutationResponse";
+    requestId: RequestId;
+    success: false;
+    errorMessage: string;
+    errorData?: ErrorData | null;
+    logLines?: string[];
+};
+export type ActionResponseMessage = {
+    type: "ActionResponse";
+    requestId: RequestId;
+    success: true;
+    result: unknown;
+    logLines?: string[];
+} | {
+    type: "ActionResponse";
+    requestId: RequestId;
+    success: false;
+    errorMessage: string;
+    errorData?: ErrorData | null;
+    logLines?: string[];
+};
+export interface FatalErrorMessage {
+    type: "FatalError";
+    error: string;
+}
+export interface AuthErrorMessage {
+    type: "AuthError";
+    error: string;
+}
+export interface PingMessage {
+    type: "Ping";
+}
+export type ServerMessage = TransitionMessage | MutationResponseMessage | ActionResponseMessage | FatalErrorMessage | AuthErrorMessage | PingMessage;
+export declare function versionsEqual(a: StateVersion, b: StateVersion): boolean;
+export declare function formatVersion(v: StateVersion): string;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1,11 @@
+/**
+ * Wire types for the RxFerrix sync protocol (v1). See `docs/PROTOCOL.md` in the repository; that document is normative.
+ */
+export const CLIENT_VERSION = "0.1.0";
+export function versionsEqual(a, b) {
+    return a.querySet === b.querySet && a.identity === b.identity && a.ts === b.ts;
+}
+export function formatVersion(v) {
+    return `{querySet:${v.querySet},identity:${v.identity},ts:${v.ts}}`;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAyItC,MAAM,UAAU,aAAa,CAAC,CAAe,EAAE,CAAe;IAC5D,OAAO,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,CAAe;IAC3C,OAAO,aAAa,CAAC,CAAC,QAAQ,aAAa,CAAC,CAAC,QAAQ,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC;AACtE,CAAC"}

package/dist/query_state.d.ts

@@ -0,0 +1,16 @@
+import type { RxFerrixError } from "./errors.js";
+/**
+ * The local state of a query. Objects are reused while the visible value does not change, so they can be compared
+ * by reference (e.g. as a `useSyncExternalStore` snapshot).
+ */
+export type QueryState<T = unknown> = {
+    readonly status: "loading";
+} | {
+    readonly status: "success";
+    readonly value: T;
+} | {
+    readonly status: "error";
+    readonly error: RxFerrixError;
+};
+export declare const LOADING: QueryState<never>;
+//# sourceMappingURL=query_state.d.ts.map

package/dist/query_state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query_state.d.ts","sourceRoot":"","sources":["../src/query_state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;GAGG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,OAAO,IAC9B;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAA;CAAE,CAAC;AAEhE,eAAO,MAAM,OAAO,EAAE,UAAU,CAAC,KAAK,CAAiD,CAAC"}

package/dist/query_state.js

@@ -0,0 +1,2 @@
+export const LOADING = Object.freeze({ status: "loading" });
+//# sourceMappingURL=query_state.js.map

package/dist/query_state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query_state.js","sourceRoot":"","sources":["../src/query_state.ts"],"names":[],"mappings":"AAWA,MAAM,CAAC,MAAM,OAAO,GAAsB,MAAM,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,SAAkB,EAAE,CAAC,CAAC"}

package/dist/remote_query_set.d.ts

@@ -0,0 +1,37 @@
+import { type QueryId, type StateVersion, type TransitionMessage } from "./protocol.js";
+import type { QueryState } from "./query_state.js";
+export declare class TransitionVersionMismatch extends Error {
+    constructor(expected: StateVersion, got: StateVersion);
+}
+export interface TransitionResult {
+    /** Queries whose server result changed (updated, failed or removed). */
+    changed: QueryId[];
+    logLines: {
+        queryId: QueryId;
+        lines: string[];
+    }[];
+}
+/**
+ * The server's view of the world for the current socket: the StateVersion and the latest result for every query.
+ * Transitions are validated (`startVersion` must equal the current version) and then applied atomically.
+ */
+export declare class RemoteQuerySet {
+    private _version;
+    private readonly results;
+    get version(): StateVersion;
+    result(queryId: QueryId): QueryState | undefined;
+    /**
+     * Applies a transition. Modifications for queries that `isKnown` rejects (removed locally while the transition was
+     * in flight) are ignored. Throws {@link TransitionVersionMismatch} without changing anything when the transition
+     * does not start at the current version, and {@link DiffMismatch} when a result diff doesn't fit the result held.
+     */
+    transition(message: TransitionMessage, isKnown: (queryId: QueryId) => boolean): TransitionResult;
+    /** Forgets a query's result (it was removed from the local query set). */
+    remove(queryId: QueryId): void;
+    /**
+     * A new socket starts from a fresh server state (all versions 0). Results are kept so the UI keeps showing the
+     * last known data until the re-subscribed queries report again.
+     */
+    resetVersion(): void;
+}
+//# sourceMappingURL=remote_query_set.d.ts.map

package/dist/remote_query_set.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote_query_set.d.ts","sourceRoot":"","sources":["../src/remote_query_set.ts"],"names":[],"mappings":"AAEA,OAAO,EAGL,KAAK,OAAO,EAEZ,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,eAAe,CAAC;AACvB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,qBAAa,yBAA0B,SAAQ,KAAK;gBACtC,QAAQ,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY;CAGtD;AAED,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,QAAQ,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,KAAK,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;CACnD;AAED;;;GAGG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAqD;IACrE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D,IAAI,OAAO,IAAI,YAAY,CAE1B;IAED,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS;IAIhD;;;;OAIG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,GAAG,gBAAgB;IA+ChG,0EAA0E;IAC1E,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI9B;;;OAGG;IACH,YAAY,IAAI,IAAI;CAGrB"}