@polyphron/viper-react 0.1.2 → 0.3.0

package/dist/db-fetch.js

@@ -0,0 +1,426 @@
+// 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";
+// 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()));
+}
+// True when two rows hold the same values.
+function same(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+// 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 loading = null;
+        let again = 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 = async () => {
+            // One load at a time; a call during one loads again after it.
+            if (loading) {
+                again = true;
+                return loading;
+            }
+            loading = (async () => {
+                publish({ fetching: true });
+                try {
+                    do {
+                        again = false;
+                        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);
+                    } while (again && !closed);
+                }
+                catch (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();
+                }
+                finally {
+                    loading = null;
+                    publish({ fetching: false });
+                    schedule();
+                }
+            })();
+            return loading;
+        };
+        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 here when TanStack DB cleans it up,
+// after nothing has read it for a while.
+const made = new WeakMap();
+/**
+ * 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) {
+    let byKey = made.get(owner);
+    if (!byKey) {
+        byKey = new Map();
+        made.set(owner, byKey);
+    }
+    const hash = JSON.stringify(options.key);
+    const found = byKey.get(hash);
+    if (found)
+        return found;
+    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);
+    };
+    collection.on("status:change", ({ status }) => {
+        if (status === "cleaned-up")
+            byKey.delete(hash);
+    });
+    byKey.set(hash, collection);
+    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.get(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.get(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.d.ts

@@ -0,0 +1,74 @@
+import type { ListOptions, RealtimeEvent, RecordModel, Viper } from "@polyphron/viper-client";
+import type { Collection, CollectionConfig } from "@tanstack/db";
+/** Which page: what `records.list` takes, less the count-free options. */
+export type PageQuery = Omit<ListOptions, "skipTotal" | "cursor" | "signal">;
+/** A page's totals and the order its rows go in. */
+export type PageInfo = {
+    /** The row ids, in the server's order. */
+    order: string[];
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+};
+/** What a page collection adds under `collection.utils`. */
+export type PageUtils = {
+    /** The totals and the order now. */
+    info: () => PageInfo;
+    /** Calls `listener` whenever `info()` changes. Returns the unsubscribe. */
+    subscribe: (listener: () => void) => () => void;
+    /** Asks the server for the page again. */
+    refetch: () => Promise<void>;
+    /**
+     * Shows a change made outside the collection (a save with files, a
+     * restore) the way a realtime event would, without waiting for one.
+     */
+    apply: (event: RealtimeEvent) => void;
+};
+export type ViperPageOptions = {
+    viper: Viper;
+    /** The Viper collection's name, e.g. `posts`. */
+    collection: string;
+    query: PageQuery;
+};
+/**
+ * Options for `createCollection()`: one server page of `collection`, kept
+ * fresh from realtime. Its totals and row order are under `utils.info()`.
+ * Deleting rows from it hides them at once, sends one all-or-nothing batch,
+ * and puts them back if the server says no.
+ */
+export declare function viperPageOptions<T extends RecordModel = RecordModel>(options: ViperPageOptions): CollectionConfig<T, string, never, PageUtils> & {
+    utils: PageUtils;
+};
+/** A page collection, as `viperPage` and `useLivePage` give it. */
+export type PageCollection<T extends RecordModel = RecordModel> = Collection<T, string, PageUtils>;
+/**
+ * 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 declare function viperPage<T extends RecordModel = RecordModel>(viper: Viper, collection: string, query: PageQuery): PageCollection<T>;
+/** What `useLivePage` gives back. */
+export type LivePage<T extends RecordModel = RecordModel> = {
+    /** The page's rows in order, or null before the first load. */
+    items: T[] | null;
+    totalItems: number;
+    totalPages: number;
+    /** True while a page loads, including the next one after a change of query. */
+    loading: boolean;
+    error: unknown;
+    /** The collection, to delete rows or call `utils.refetch()` and `utils.apply()`. */
+    collection: PageCollection<T>;
+};
+/**
+ * One server page of `collection` as a live list: `records.list` once, then
+ * realtime keeps it fresh, patching rows where it can. While a new `query`
+ * loads, the last page stays on screen.
+ *
+ * ```tsx
+ * const { items, totalPages } = useLivePage<Post>("posts", {
+ *   page, perPage: 30, sort: "-updated", filter,
+ * })
+ * ```
+ */
+export declare function useLivePage<T extends RecordModel = RecordModel>(collection: string, query: PageQuery): LivePage<T>;