@polyphron/viper-react 0.2.1 → 0.4.0

package/dist/db-fetch.js

@@ -0,0 +1,398 @@
+// EXPERIMENTAL: any fetch as a TanStack DB collection.
+//
+// For data that isn't records: settings, keys, logs, anything an endpoint
+// hands back whole. It loads with `fetch`, loads again when told to (or on a
+// timer, or when the window comes back and it's stale), and keeps the order
+// the server gave. Records have realtime, so use `viperCollectionOptions` or
+// `useLivePage` for them.
+import { ViperError } from "@polyphron/viper-client";
+import { createCollection } from "@tanstack/db";
+import { useLiveQuery } from "@tanstack/react-db";
+import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { cacheOf, same, singleFlight } from "./db-shared.js";
+// The key a one-object fetch keeps its row under.
+const ONE = "one";
+// Loads that failed on the network (not "no" or "not found") try again.
+const RETRIES = 2;
+// Every fetched collection that has a reader, for the focus check.
+const watched = new Set();
+if (typeof window !== "undefined") {
+    window.addEventListener("focus", () => watched.forEach((entry) => entry.onFocus()));
+}
+// Waits `ms`, or less if `signal` aborts.
+function wait(ms, signal) {
+    return new Promise((done) => {
+        const timer = setTimeout(done, ms);
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            done();
+        });
+    });
+}
+/**
+ * Options for `createCollection()`: what `fetch` gives, as rows. A list is
+ * keyed by `getKey`; a single object (leave `getKey` out) is one row.
+ */
+export function fetchCollectionOptions(options) {
+    const { key, fetch, getKey, refetchInterval } = options;
+    const staleTime = options.staleTime ?? 30_000;
+    const kind = getKey ? "list" : "one";
+    const keyOf = getKey ?? (() => ONE);
+    const toRows = (data) => kind === "list" ? (data ?? []) : data ? [data] : [];
+    let state = {
+        order: [],
+        error: null,
+        loadedAt: 0,
+        fetching: false,
+    };
+    let last;
+    let readers = 0;
+    // Set by stale(), cleared by the next load.
+    let marked = false;
+    // Bumped by set(), so a load that started before it can't undo it.
+    let generation = 0;
+    const listeners = new Set();
+    const waiting = new Set();
+    const publish = (next) => {
+        state = { ...state, ...next };
+        listeners.forEach((listener) => listener());
+    };
+    // Set while the sync runs.
+    let live = null;
+    const sync = (params) => {
+        const { begin, write, commit, markReady } = params;
+        const rows = new Map();
+        let closed = false;
+        let timer;
+        const controller = new AbortController();
+        // Writes only what changed, so rows that stayed the same keep their
+        // identity and whatever renders them doesn't start over.
+        const apply = (data) => {
+            const next = toRows(data);
+            const keys = next.map(keyOf);
+            const kept = new Set(keys);
+            last = data;
+            marked = false;
+            begin();
+            for (const [k] of rows) {
+                if (!kept.has(k)) {
+                    write({ type: "delete", key: k });
+                    rows.delete(k);
+                }
+            }
+            next.forEach((row, i) => {
+                const k = keys[i];
+                const old = rows.get(k);
+                if (old && same(old, row))
+                    return;
+                write({ type: old ? "update" : "insert", value: row });
+                rows.set(k, row);
+            });
+            commit();
+            markReady();
+            publish({
+                order: same(keys, state.order) ? state.order : keys,
+                error: null,
+                loadedAt: Date.now(),
+            });
+            waiting.forEach((w) => w.done());
+            waiting.clear();
+        };
+        // The next timed load, while someone reads it.
+        const schedule = () => {
+            clearTimeout(timer);
+            const every = typeof refetchInterval === "function"
+                ? last === undefined
+                    ? false
+                    : refetchInterval(last)
+                : refetchInterval;
+            if (every && readers > 0 && !closed) {
+                // A hidden tab waits rather than asking; nobody is looking.
+                timer = setTimeout(() => typeof document !== "undefined" && document.hidden
+                    ? schedule()
+                    : void load(), every);
+            }
+        };
+        const load = singleFlight({
+            start: () => publish({ fetching: true }),
+            pass: async () => {
+                let data;
+                const at = generation;
+                for (let tries = 0;; tries++) {
+                    try {
+                        data = await fetch(controller.signal);
+                        break;
+                    }
+                    catch (error) {
+                        // The server said no. No answer at all (status 0) and
+                        // server trouble are worth another go.
+                        const refused = error instanceof ViperError &&
+                            error.status > 0 &&
+                            error.status < 500;
+                        if (closed || refused || tries >= RETRIES)
+                            throw error;
+                        await wait(1000 * 2 ** tries, controller.signal);
+                    }
+                }
+                if (closed)
+                    return;
+                // set() put newer data in while this was on the way.
+                if (at === generation)
+                    apply(data);
+            },
+            closed: () => closed,
+            fail: (error) => {
+                if (closed)
+                    return;
+                // Ready with no rows, so preload() settles; the error is in state.
+                markReady();
+                publish({ error });
+                waiting.forEach((w) => w.fail(error));
+                waiting.clear();
+            },
+            settle: () => {
+                publish({ fetching: false });
+                schedule();
+            },
+        });
+        live = { load, apply, schedule };
+        void load();
+        return () => {
+            closed = true;
+            live = null;
+            clearTimeout(timer);
+            controller.abort();
+        };
+    };
+    // True when a reader should ask again: an old copy, or a failed first
+    // load (it may have been a blip).
+    const due = () => !state.fetching &&
+        (state.loadedAt
+            ? marked || Date.now() - state.loadedAt > staleTime
+            : !!state.error);
+    const entry = {
+        onFocus: () => {
+            if (options.refetchOnFocus !== false && due())
+                void live?.load();
+        },
+    };
+    const utils = {
+        state: () => state,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        refetch: async () => live?.load(),
+        ready: () => {
+            if (state.loadedAt)
+                return Promise.resolve();
+            // A failed first load is asked again, not handed back as is.
+            if (due())
+                void live?.load();
+            return new Promise((done, fail) => waiting.add({ done, fail }));
+        },
+        set: (data) => {
+            generation++;
+            live?.apply(data);
+        },
+        watch: () => {
+            readers++;
+            watched.add(entry);
+            // A reader that comes back to an old copy asks again.
+            if (due()) {
+                void live?.load();
+            }
+            else {
+                live?.schedule();
+            }
+            return () => {
+                readers--;
+                if (readers === 0)
+                    watched.delete(entry);
+            };
+        },
+        stale: async () => {
+            marked = true;
+            if (readers > 0)
+                await live?.load();
+        },
+    };
+    return {
+        id: `viper-fetch:${JSON.stringify(key)}`,
+        getKey: keyOf,
+        // An endpoint sends whole rows, so an update replaces rather than merges.
+        sync: { sync, rowUpdateMode: "full" },
+        utils,
+    };
+}
+// Fetched collections by owner and key, so every reader of a key shares one
+// collection (and one request). One leaves the cache when TanStack DB cleans
+// it up, after nothing has read it for a while.
+const made = cacheOf();
+/**
+ * The fetched collection for `options.key` under `owner` (a client, say),
+ * made once and shared. For a list pass `getKey`; leave it out for one object.
+ */
+export function fetched(owner, options) {
+    return made(owner, JSON.stringify(options.key), () => {
+        const collection = Object.assign(createCollection(fetchCollectionOptions(options)), { kind: options.getKey ? "list" : "one", key: options.key });
+        // Asking for the data (or putting some in) starts the sync if nothing
+        // has yet, so a route loader can await ready() on its own.
+        const { ready, set } = collection.utils;
+        collection.utils.ready = () => {
+            collection.startSyncImmediate();
+            return ready();
+        };
+        collection.utils.set = (data) => {
+            collection.startSyncImmediate();
+            set(data);
+        };
+        return collection;
+    });
+}
+// True when `key` starts with every part of `prefix`.
+function startsWith(key, prefix) {
+    return prefix.every((part, i) => same(part, key[i]));
+}
+/**
+ * Loads again every fetched collection under `owner` whose key starts with
+ * `prefix`: the ones on screen now, the rest when next read. Call it after a
+ * change, the way you'd invalidate a query.
+ */
+export function refetchFetched(owner, prefix) {
+    const loads = [];
+    for (const collection of made.of(owner)?.values() ?? []) {
+        if (!startsWith(collection.key, prefix))
+            continue;
+        loads.push(collection.utils.stale());
+    }
+    return Promise.all(loads).then(() => undefined);
+}
+/**
+ * Drops every fetched collection under `owner` whose key starts with
+ * `prefix`, so nothing shows its data again (after a project is deleted).
+ */
+export function forgetFetched(owner, prefix) {
+    const byKey = made.of(owner);
+    for (const [hash, collection] of byKey ?? []) {
+        if (!startsWith(collection.key, prefix))
+            continue;
+        byKey?.delete(hash);
+        void collection.cleanup();
+    }
+}
+const IDLE = {
+    order: [],
+    error: null,
+    loadedAt: 0,
+    fetching: false,
+};
+/**
+ * A fetched collection read as a list (or its one object), in the server's
+ * order. Pass null to read nothing yet. With `keepPrevious`, the last data
+ * stays on screen while a new collection (the next page, a new filter) loads.
+ *
+ * ```tsx
+ * const keys = useFetched(fetched(client, { key: ["keys"], fetch, getKey }))
+ * ```
+ */
+export function useFetched(collection, options = {}) {
+    const live = useLiveQuery({
+        query: (q) => collection
+            ? q.from({ row: collection })
+            : undefined,
+    });
+    const state = useSyncExternalStore(collection?.utils.subscribe ?? noSubscribe, collection?.utils.state ?? idle, collection?.utils.state ?? idle);
+    useEffect(() => collection?.utils.watch(), [collection]);
+    // The collection keeps rows by key; the order is the server's.
+    const loaded = state.loadedAt > 0;
+    const data = useMemo(() => {
+        if (!collection || !loaded)
+            return undefined;
+        return read(collection);
+        // live.data changes whenever a row does.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [collection, live.data, state.order, loaded]);
+    // The last data that loaded, shown while the next collection does.
+    const [last, setLast] = useState(undefined);
+    if (options.keepPrevious && data !== undefined && data !== last)
+        setLast(data);
+    const error = (state.error ?? null);
+    const shown = data ?? (options.keepPrevious && !error ? last : undefined);
+    return {
+        data: shown,
+        error,
+        isError: !!error,
+        isPending: !!collection && shown === undefined && !error,
+        isSuccess: shown !== undefined,
+        isFetching: state.fetching,
+        updatedAt: state.loadedAt,
+        refetch: async () => collection?.utils.refetch(),
+    };
+}
+/**
+ * Several fetched collections at once (one per project, say), in the same
+ * order: `{ data, error }` each, with `data` undefined until it loads.
+ */
+export function useFetchedAll(collections) {
+    const [tick, setTick] = useState(0);
+    // The list is usually made fresh each render, so compare by keys.
+    const id = collections.map((c) => JSON.stringify(c.key)).join(" ");
+    useEffect(() => {
+        const undo = collections.flatMap((c) => {
+            // Re-render only when data or an error lands, not on every fetch flag.
+            let seen = c.utils.state();
+            // Nothing else reads these, so start each and hold it, or TanStack DB
+            // would leave it idle, then clean it up.
+            c.startSyncImmediate();
+            const held = c.subscribeChanges(() => { });
+            return [
+                c.utils.watch(),
+                () => held.unsubscribe(),
+                c.utils.subscribe(() => {
+                    const now = c.utils.state();
+                    if (now.loadedAt !== seen.loadedAt || now.error !== seen.error) {
+                        setTick((n) => n + 1);
+                    }
+                    seen = now;
+                }),
+            ];
+        });
+        return () => undo.forEach((u) => u());
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [id]);
+    return useMemo(() => collections.map((c) => {
+        const state = c.utils.state();
+        const data = state.loadedAt ? read(c) : undefined;
+        return { data, error: (state.error ?? null) };
+    }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [id, tick]);
+}
+// A row without the `$synced`, `$key`... fields TanStack DB adds, so a
+// form can send it back as is. Cached, so a row keeps its identity.
+const plainRows = new WeakMap();
+const VIRTUAL = ["$synced", "$origin", "$key", "$collectionId"];
+function plain(row) {
+    let found = plainRows.get(row);
+    if (!found) {
+        const copy = {
+            ...row,
+        };
+        VIRTUAL.forEach((name) => delete copy[name]);
+        found = copy;
+        plainRows.set(row, found);
+    }
+    return found;
+}
+// The rows of `collection` in the server's order, as plain objects.
+function read(collection) {
+    const rows = collection.utils.state().order.flatMap((k) => {
+        const row = collection.get(k);
+        return row ? [plain(row)] : [];
+    });
+    return (collection.kind === "one" ? rows[0] : rows);
+}
+// For a null collection: nothing to hear, nothing loaded.
+const noSubscribe = () => () => { };
+const idle = () => IDLE;

package/dist/db-page.js

@@ -1,6 +1,7 @@
 import { createCollection } from "@tanstack/db";
 import { useLiveQuery } from "@tanstack/react-db";
 import { useMemo, useState, useSyncExternalStore } from "react";
+import { cacheOf, sendOps, singleFlight } from "./db-shared.js";
 import { pageComparator, planPage } from "./page-plan.js";
 import { useViper } from "./provider.js";
 // A burst of changes (an import, a batch) asks for the page once.
@@ -12,14 +13,6 @@ const EMPTY = {
     totalItems: 0,
     totalPages: 0,
 };
-// A delete of several rows, as one all-or-nothing batch.
-async function deleteAll(viper, collection, ids) {
-    if (ids.length === 1) {
-        await viper.collection(collection).records.delete(ids[0]);
-        return;
-    }
-    await viper.batch(ids.map((id) => ({ method: "delete", collection, id })));
-}
 /**
  * Options for `createCollection()`: one server page of `collection`, kept
  * fresh from realtime. Its totals and row order are under `utils.info()`.
@@ -42,59 +35,42 @@ export function viperPageOptions(options) {
     const sync = (params) => {
         const { begin, write, commit, truncate, markReady, markError } = params;
         let closed = false;
-        let loading = null;
-        let again = false;
         let timer;
-        const load = async () => {
-            // One load at a time; a change during a load reloads after it.
-            if (loading) {
-                again = true;
-                return loading;
-            }
-            loading = (async () => {
-                try {
-                    do {
-                        again = false;
-                        const result = await records.list(query);
-                        if (closed)
-                            return;
-                        // Truncate and rewrite in one transaction, so a reload never
-                        // shows an empty page in between.
-                        begin();
-                        truncate();
-                        rows.clear();
-                        for (const record of result.items) {
-                            write({ type: "insert", value: record });
-                            rows.set(record.id, record);
-                        }
-                        commit();
-                        markReady();
-                        publish({
-                            order: result.items.map((r) => r.id),
-                            page: result.page,
-                            perPage: result.perPage,
-                            totalItems: result.totalItems,
-                            totalPages: result.totalPages,
-                        });
-                    } while (again && !closed);
-                }
-                catch (error) {
-                    markError(error);
-                }
-                finally {
-                    loading = null;
+        const load = singleFlight({
+            pass: async () => {
+                const result = await records.list(query);
+                if (closed)
+                    return;
+                // Truncate and rewrite in one transaction, so a reload never
+                // shows an empty page in between.
+                begin();
+                truncate();
+                rows.clear();
+                for (const record of result.items) {
+                    write({ type: "insert", value: record });
+                    rows.set(record.id, record);
                 }
-            })();
-            return loading;
-        };
+                commit();
+                markReady();
+                publish({
+                    order: result.items.map((r) => r.id),
+                    page: result.page,
+                    perPage: result.perPage,
+                    totalItems: result.totalItems,
+                    totalPages: result.totalPages,
+                });
+            },
+            closed: () => closed,
+            fail: markError,
+        });
         const loadSoon = () => {
             clearTimeout(timer);
             timer = setTimeout(() => void load(), SETTLE);
         };
         const take = (event) => {
             // The page on screen may be about to change; plan against the next one.
-            if (loading) {
-                again = true;
+            if (load.busy()) {
+                void load();
                 return;
             }
             const plan = planPage(event, {
@@ -158,7 +134,11 @@ export function viperPageOptions(options) {
         sync: { sync, rowUpdateMode: "full" },
         utils,
         onDelete: async ({ transaction }) => {
-            await deleteAll(viper, collection, transaction.mutations.map((m) => String(m.key)));
+            await sendOps(viper, transaction.mutations.map((m) => ({
+                method: "delete",
+                collection,
+                id: String(m.key),
+            })));
             // The rows after them move up.
             await live?.load();
         },
@@ -166,32 +146,16 @@ export function viperPageOptions(options) {
 }
 // Page collections by client and page, so the route that preloads a page and
 // the table that shows it share one collection (and one fetch). One leaves
-// here when its sync stops, after nothing has read it for a while.
-const pages = new WeakMap();
+// the cache when its sync stops, after nothing has read it for a while, and
+// the next ask makes a fresh one.
+const pages = cacheOf();
 /**
  * The page collection for `collection` and `query` on `viper`, made once and
  * shared. Outside React (a route loader, say) call `.preload()` on it to
  * start the fetch early.
  */
 export function viperPage(viper, collection, query) {
-    let byKey = pages.get(viper);
-    if (!byKey) {
-        byKey = new Map();
-        pages.set(viper, byKey);
-    }
-    const key = `${collection}:${JSON.stringify(query)}`;
-    const found = byKey.get(key);
-    if (found)
-        return found;
-    const made = createCollection(viperPageOptions({ viper, collection, query }));
-    // Once it is cleaned up it can't be read again, so the next ask makes a
-    // new one.
-    made.on("status:change", ({ status }) => {
-        if (status === "cleaned-up")
-            byKey.delete(key);
-    });
-    byKey.set(key, made);
-    return made;
+    return pages(viper, `${collection}:${JSON.stringify(query)}`, () => createCollection(viperPageOptions({ viper, collection, query })));
 }
 /**
  * One server page of `collection` as a live list: `records.list` once, then

package/dist/db-query.d.ts

@@ -6,12 +6,6 @@ export type Translated = {
     /** True when the filter matches exactly what the query does. */
     exact: boolean;
 };
-/**
- * A string as a Viper string literal. Backslash escapes the next character
- * in Viper's lexer, so escaping `\` and `"` is enough to keep a value from
- * ever ending its own quotes.
- */
-export declare function quote(value: string): string;
 /**
  * A subset's `where` as a Viper filter. Anything Viper cannot say is left out
  * (so more rows load), and the query filters again in the browser.

package/dist/db-query.js

@@ -1,3 +1,11 @@
+// EXPERIMENTAL: turns a TanStack DB subset request (`where`, `orderBy`) into
+// the `filter` and `sort` strings of Viper's records API.
+//
+// Everything here may load MORE than the query asks for, never less: TanStack
+// DB runs every live query's own `where` again over what is loaded, so a
+// wider load only costs bandwidth. `exact` says whether the load is the
+// query's exact answer; only then is it safe to ask for a limited window.
+import { quote } from "@polyphron/viper-client";
 /** A field name is a plain word, so it can go into a filter unquoted. */
 const FIELD = /^[A-Za-z_][A-Za-z0-9_]*$/;
 /** The comparisons Viper writes the same way TanStack DB names them. */
@@ -17,14 +25,6 @@ const FLIP = {
     lte: "gte",
 };
 const ANY = { text: null, exact: false };
-/**
- * A string as a Viper string literal. Backslash escapes the next character
- * in Viper's lexer, so escaping `\` and `"` is enough to keep a value from
- * ever ending its own quotes.
- */
-export function quote(value) {
-    return `"${value.replace(/[\\"]/g, "\\$&")}"`;
-}
 // A value as a Viper literal, or null for one Viper has no way to write.
 function literal(value) {
     if (typeof value === "string")

package/dist/db-shared.d.ts

@@ -0,0 +1,50 @@
+import type { BatchOp, RecordModel, Viper } from "@polyphron/viper-client";
+/** What `singleFlight` needs from an adapter. */
+export type FlightOptions = {
+    /** One load: fetch and put the answer into the collection. */
+    pass: () => Promise<void>;
+    /** True once the sync has stopped; a stopped sync drops its answers. */
+    closed: () => boolean;
+    /** Called with whatever a pass threw (the pass is not retried here). */
+    fail: (error: unknown) => void;
+    /** Runs before the first pass of a flight. */
+    start?: () => void;
+    /** Runs after a flight ends, whether it worked or failed. */
+    settle?: () => void;
+};
+/** A `load()` that runs one pass at a time; `busy()` says whether one runs. */
+export type Flight = (() => Promise<void>) & {
+    busy: () => boolean;
+};
+/**
+ * Makes a `load()` that runs one pass at a time. A call during a pass does
+ * not start a second one; it asks for another pass right after the first, so
+ * a change that landed mid-load is never missed. Every caller gets the
+ * promise of the flight it joined.
+ */
+export declare function singleFlight(options: FlightOptions): Flight;
+/** The bits of a TanStack DB collection that `cacheOf` listens to. */
+type Evictable = {
+    on: (event: "status:change", callback: (change: {
+        status: string;
+    }) => void) => unknown;
+};
+/** A cache of collections; `of(owner)` lists what an owner holds now. */
+export type Cache<V> = ((owner: object, key: string, make: () => V) => V) & {
+    of: (owner: object) => Map<string, V> | undefined;
+};
+/**
+ * A cache of collections by owner (a client, say) and key, so every reader
+ * of a key shares one collection and one request. A collection leaves the
+ * cache once TanStack DB cleans it up, after nothing has read it for a while:
+ * the next ask builds a fresh one rather than waking the old one.
+ */
+export declare function cacheOf<V extends Evictable>(): Cache<V>;
+/**
+ * Sends writes: one call for one, a single all-or-nothing batch for several.
+ * Resolves to the saved records, in order (null for a delete).
+ */
+export declare function sendOps(viper: Viper, ops: BatchOp[]): Promise<(RecordModel | null)[]>;
+/** True when two values are the same, lists and objects included. */
+export declare function same(a: unknown, b: unknown): boolean;
+export {};