@polyphron/viper-react 0.2.1 → 0.3.0

package/README.md

@@ -200,6 +200,50 @@ collection.utils.refetch() // ask for the page again
 - `collection.utils.apply(event)` shows a change you made yourself (a save)
   without waiting for its realtime event.
 
+### Any endpoint as a collection
+
+For data that isn't records (settings, keys, logs, anything an endpoint hands
+back whole), `fetched(owner, options)` makes a TanStack DB collection from a
+fetch, and `useFetched(collection)` reads it as
+`{ data, error, isPending, isFetching, updatedAt, refetch }`.
+
+```tsx
+import { fetched, refetchFetched, useFetched } from "@polyphron/viper-react/db"
+
+const settings = (p: string) =>
+  fetched<Settings>(client, {
+    key: ["projects", p, "settings"],
+    fetch: (signal) => api.settings(p, { signal }),
+  })
+
+const { data } = useFetched(settings(projectId))
+
+await save(input)
+await refetchFetched(client, ["projects", projectId]) // every key under it
+```
+
+- The same `owner` and `key` always give the same collection, so every
+  reader shares one load. A list (pass `getKey`) keeps the server's order; a
+  single object is one row.
+- It loads again when told to (`refetchFetched` by key prefix, or
+  `collection.utils.refetch()`), on `refetchInterval` while read, and when
+  the window comes back after `staleTime` (30 seconds by default). Only
+  changed rows are rewritten, so the rest keep their identity.
+- `collection.utils.set(data)` puts in a save's answer with no request.
+  `await collection.utils.ready()` waits for the first load, from a route
+  loader say. `forgetFetched(owner, prefix)` drops collections (after a
+  delete).
+- Network errors retry twice; a "no" or "not found" doesn't. The error is
+  in `error`, and the last good data stays.
+- `useFetched(collection, { keepPrevious: true })` keeps the last data on
+  screen while a new collection (the next page, a new filter) loads.
+  `useFetchedAll(collections)` reads several, one per project say.
+
+The Viper dashboard reads the whole admin API this way, through
+`@polyphron/viper-react/db/admin` (`adminCollections(admin)`). That entry
+stays in the workspace, like the admin client it wraps, and isn't
+published.
+
 ### Recipe: typed collections, a join and an optimistic insert
 
 1. Write the types once with `viper typegen --out src/viper-types.ts` (see

package/dist/auth.d.ts

@@ -1,17 +1,58 @@
-import type { AuthService, RecordModel, Session } from "@polyphron/viper-client";
+import type { AuthMethods, AuthService, Invite, InviteInput, RecordModel, Session, UserSession } from "@polyphron/viper-client";
 /** The current session, re-rendering on login, logout and refresh. */
 export declare function useSession(): Session | null;
+/** The signed-in user's active sessions, with revoke and log-out actions. */
+export declare function useSessions(): {
+    sessions: UserSession[] | null;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    revoke: (sessionId: string) => Promise<void>;
+    logoutEverywhere: () => Promise<void>;
+};
+/** The invites the signed-in user sent, with send and take-back actions. */
+export declare function useInvites(): {
+    invites: Invite[] | null;
+    error: Error | null;
+    refresh: () => Promise<void>;
+    invite: (input: InviteInput) => Promise<Invite>;
+    cancel: (id: string) => Promise<void>;
+};
 /** The logged-in user, or null when signed out. */
 export declare function useUser<T extends RecordModel = RecordModel>(): T | null;
 /**
- * The logins of one auth collection, plus the user they belong to.
+ * The project's sign-in, plus the user it belongs to. Without a
+ * collection it is the users table's (`viper.auth`); an old project with
+ * several auth collections names one.
  *
  * ```tsx
- * const { user, auth } = useAuth("users")
+ * const { user, auth } = useAuth()
  * await auth.loginWithPassword(email, password)
  * ```
  */
-export declare function useAuth<T extends RecordModel = RecordModel>(collection: string): {
+export declare function useAuth<T extends RecordModel = RecordModel>(collection?: string): {
     user: T | null;
     auth: AuthService<T>;
 };
+/**
+ * How to sign in here: the ways on offer, sign-up, and the sub-app's name
+ * and branding when the client has one (`new Viper({ app })`). Null while
+ * it loads. For a sign-in page.
+ *
+ * ```tsx
+ * const methods = useAuthMethods()
+ * return <h1>{methods?.app?.branding.name ?? methods?.app?.name}</h1>
+ * ```
+ */
+export declare function useAuthMethods(): AuthMethods | null;
+/**
+ * The signed-in user's memberships of tenant collection `name` (like
+ * "orgs"), each with its role and the tenant under `expand.tenant`. Empty
+ * while signed out, null while it loads. It loads again when the user
+ * changes.
+ *
+ * ```tsx
+ * const orgs = useTenants("orgs")
+ * return orgs?.map((m) => <li key={m.id}>{m.expand?.tenant?.name}</li>)
+ * ```
+ */
+export declare function useTenants(name: string): RecordModel[] | null;

package/dist/auth.js

@@ -1,24 +1,198 @@
-import { useSyncExternalStore } from "react";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
 import { useViper } from "./provider.js";
 /** The current session, re-rendering on login, logout and refresh. */
 export function useSession() {
     const viper = useViper();
     return useSyncExternalStore((listener) => viper.onSessionChange(listener), () => viper.session, () => null);
 }
+/** The signed-in user's active sessions, with revoke and log-out actions. */
+export function useSessions() {
+    const viper = useViper();
+    const user = useUser();
+    const [loaded, setLoaded] = useState(null);
+    const refresh = useCallback(async () => {
+        const userId = user?.id;
+        if (!userId)
+            return;
+        try {
+            setLoaded({
+                userId,
+                sessions: await viper.auth.sessions(),
+                error: null,
+            });
+        }
+        catch (cause) {
+            setLoaded({
+                userId,
+                sessions: [],
+                error: cause instanceof Error ? cause : new Error(String(cause)),
+            });
+        }
+    }, [user?.id, viper]);
+    useEffect(() => {
+        const ctl = new AbortController();
+        const userId = user?.id;
+        if (userId) {
+            viper.auth
+                .sessions({ signal: ctl.signal })
+                .then((sessions) => setLoaded({ userId, sessions, error: null }))
+                .catch((cause) => {
+                if (!ctl.signal.aborted) {
+                    setLoaded({
+                        userId,
+                        sessions: [],
+                        error: cause instanceof Error ? cause : new Error(String(cause)),
+                    });
+                }
+            });
+        }
+        return () => ctl.abort();
+    }, [viper, user?.id]);
+    const revoke = async (sessionId) => {
+        await viper.auth.revokeSession(sessionId);
+        await refresh();
+    };
+    const logoutEverywhere = () => viper.auth.logoutEverywhere();
+    const current = loaded?.userId === user?.id ? loaded : null;
+    return {
+        sessions: current?.sessions ?? null,
+        error: current?.error ?? null,
+        refresh,
+        revoke,
+        logoutEverywhere,
+    };
+}
+/** The invites the signed-in user sent, with send and take-back actions. */
+export function useInvites() {
+    const viper = useViper();
+    const user = useUser();
+    const [loaded, setLoaded] = useState(null);
+    const refresh = useCallback(async () => {
+        const userId = user?.id;
+        if (!userId)
+            return;
+        try {
+            setLoaded({ userId, invites: await viper.auth.invites(), error: null });
+        }
+        catch (cause) {
+            setLoaded({
+                userId,
+                invites: [],
+                error: cause instanceof Error ? cause : new Error(String(cause)),
+            });
+        }
+    }, [user?.id, viper]);
+    useEffect(() => {
+        let live = true;
+        const userId = user?.id;
+        if (userId) {
+            viper.auth
+                .invites()
+                .then((invites) => {
+                if (live)
+                    setLoaded({ userId, invites, error: null });
+            })
+                .catch((cause) => {
+                if (live) {
+                    setLoaded({
+                        userId,
+                        invites: [],
+                        error: cause instanceof Error ? cause : new Error(String(cause)),
+                    });
+                }
+            });
+        }
+        return () => {
+            live = false;
+        };
+    }, [viper, user?.id]);
+    const invite = async (input) => {
+        const made = await viper.auth.invite(input);
+        await refresh();
+        return made;
+    };
+    const cancel = async (id) => {
+        await viper.auth.cancelInvite(id);
+        await refresh();
+    };
+    const current = loaded?.userId === user?.id ? loaded : null;
+    return {
+        invites: current?.invites ?? null,
+        error: current?.error ?? null,
+        refresh,
+        invite,
+        cancel,
+    };
+}
 /** The logged-in user, or null when signed out. */
 export function useUser() {
     return useSession()?.record ?? null;
 }
 /**
- * The logins of one auth collection, plus the user they belong to.
+ * The project's sign-in, plus the user it belongs to. Without a
+ * collection it is the users table's (`viper.auth`); an old project with
+ * several auth collections names one.
  *
  * ```tsx
- * const { user, auth } = useAuth("users")
+ * const { user, auth } = useAuth()
  * await auth.loginWithPassword(email, password)
  * ```
  */
 export function useAuth(collection) {
     const viper = useViper();
     const user = useUser();
-    return { user, auth: viper.collection(collection).auth };
+    const auth = collection
+        ? viper.collection(collection).auth
+        : viper.auth;
+    return { user, auth };
+}
+/**
+ * How to sign in here: the ways on offer, sign-up, and the sub-app's name
+ * and branding when the client has one (`new Viper({ app })`). Null while
+ * it loads. For a sign-in page.
+ *
+ * ```tsx
+ * const methods = useAuthMethods()
+ * return <h1>{methods?.app?.branding.name ?? methods?.app?.name}</h1>
+ * ```
+ */
+export function useAuthMethods() {
+    const viper = useViper();
+    const [methods, setMethods] = useState(null);
+    useEffect(() => {
+        const ctl = new AbortController();
+        viper.auth
+            .methods({ signal: ctl.signal })
+            .then(setMethods)
+            // A failed load stays null; the sign-in calls report their own errors.
+            .catch(() => { });
+        return () => ctl.abort();
+    }, [viper]);
+    return methods;
+}
+/**
+ * The signed-in user's memberships of tenant collection `name` (like
+ * "orgs"), each with its role and the tenant under `expand.tenant`. Empty
+ * while signed out, null while it loads. It loads again when the user
+ * changes.
+ *
+ * ```tsx
+ * const orgs = useTenants("orgs")
+ * return orgs?.map((m) => <li key={m.id}>{m.expand?.tenant?.name}</li>)
+ * ```
+ */
+export function useTenants(name) {
+    const viper = useViper();
+    const user = useUser();
+    const [tenants, setTenants] = useState(null);
+    useEffect(() => {
+        const ctl = new AbortController();
+        viper
+            .tenants(name, { signal: ctl.signal })
+            .then(setTenants)
+            // A failed load stays null; record calls report their own errors.
+            .catch(() => { });
+        return () => ctl.abort();
+    }, [viper, name, user?.id]);
+    return tenants;
 }

package/dist/db-fetch.d.ts

@@ -0,0 +1,121 @@
+import type { Collection, CollectionConfig } from "@tanstack/db";
+type Key = string | number;
+/** Names what a fetch is, like `["projects", id, "keys"]`. */
+export type FetchKey = readonly unknown[];
+/** Where a fetch stands. */
+export type FetchState = {
+    /** The row keys, in the server's order. */
+    order: Key[];
+    /** The last load's error, or null when it worked. */
+    error: unknown;
+    /** When the last good load finished (ms), or 0 before one. */
+    loadedAt: number;
+    /** True while a load is under way. */
+    fetching: boolean;
+};
+/** What a fetched collection adds under `collection.utils`. */
+export type FetchUtils<D> = {
+    /** Where the fetch stands now. */
+    state: () => FetchState;
+    /** Calls `listener` whenever `state()` changes. Returns the unsubscribe. */
+    subscribe: (listener: () => void) => () => void;
+    /** Asks the server again. */
+    refetch: () => Promise<void>;
+    /** Resolves once a load has worked, or rejects if the first one failed. */
+    ready: () => Promise<void>;
+    /**
+     * Puts `data` in as if the server had sent it, with no request: the
+     * answer of a save, say.
+     */
+    set: (data: D) => void;
+    /** Counts a reader, so the timer and focus checks run. Returns the undo. */
+    watch: () => () => void;
+    /**
+     * Marks it stale: it loads again now if something reads it, else when
+     * something next does.
+     */
+    stale: () => Promise<void>;
+};
+/** A fetched collection: one list (or one object) from an endpoint. */
+export type Fetched<D> = Collection<Row<D>, Key, FetchUtils<D>> & {
+    /** "list" for an array, "one" for a single object held as one row. */
+    kind: "list" | "one";
+    key: FetchKey;
+};
+/** The row type of a fetch: an item of a list, or the one object. */
+export type Row<D> = D extends readonly (infer R extends object)[] ? R : D extends object ? D : never;
+/** How to fetch, and how fresh to keep it. */
+export type FetchOptions<D> = {
+    key: FetchKey;
+    fetch: (signal: AbortSignal) => Promise<D>;
+    /** Load again this often while read (ms), or from the data. */
+    refetchInterval?: number | false | ((data: D) => number | false);
+    /** How long a load counts as fresh (ms). Default 30 seconds. */
+    staleTime?: number;
+    /** Load a stale one again when the window comes back. Default true. */
+    refetchOnFocus?: boolean;
+};
+/**
+ * Options for `createCollection()`: what `fetch` gives, as rows. A list is
+ * keyed by `getKey`; a single object (leave `getKey` out) is one row.
+ */
+export declare function fetchCollectionOptions<D>(options: FetchOptions<D> & {
+    getKey?: (row: Row<D>) => Key;
+}): CollectionConfig<Row<D>, Key, never, FetchUtils<D>> & {
+    utils: FetchUtils<D>;
+};
+/**
+ * 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 declare function fetched<D>(owner: object, options: FetchOptions<D> & {
+    getKey?: (row: Row<D>) => Key;
+}): Fetched<D>;
+/**
+ * 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 declare function refetchFetched(owner: object, prefix: FetchKey): Promise<void>;
+/**
+ * Drops every fetched collection under `owner` whose key starts with
+ * `prefix`, so nothing shows its data again (after a project is deleted).
+ */
+export declare function forgetFetched(owner: object, prefix: FetchKey): void;
+/** What `useFetched` gives back. */
+export type FetchedResult<D> = {
+    /** The list (or the one object), or undefined until it loads. */
+    data: D | undefined;
+    /** The last load's error, or null. */
+    error: Error | null;
+    isError: boolean;
+    /** True until the first load works or fails. */
+    isPending: boolean;
+    isSuccess: boolean;
+    /** True while any load is under way, the first or a later one. */
+    isFetching: boolean;
+    /** When the data last loaded (ms), or 0 before it has. */
+    updatedAt: number;
+    refetch: () => Promise<void>;
+};
+/**
+ * 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 declare function useFetched<D>(collection: Fetched<D> | null | undefined, options?: {
+    keepPrevious?: boolean;
+}): FetchedResult<D>;
+/**
+ * Several fetched collections at once (one per project, say), in the same
+ * order: `{ data, error }` each, with `data` undefined until it loads.
+ */
+export declare function useFetchedAll<D>(collections: readonly Fetched<D>[]): {
+    data: D | undefined;
+    error: Error | null;
+}[];
+export {};

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.d.ts

@@ -4,6 +4,7 @@ import { useLiveQuery } from "@tanstack/react-db";
 export { toViperFilter, toViperSort } from "./db-query.js";
 export { useLivePage, viperPage, viperPageOptions, type LivePage, type PageCollection, type PageInfo, type PageQuery, type PageUtils, type ViperPageOptions, } from "./db-page.js";
 export { pageComparator, planPage, type PagePlan, type PageState, } from "./page-plan.js";
+export { fetchCollectionOptions, fetched, forgetFetched, refetchFetched, useFetched, useFetchedAll, type FetchKey, type FetchOptions, type FetchState, type FetchUtils, type Fetched, type FetchedResult, type Row, } from "./db-fetch.js";
 export { useLiveQuery };
 export type ViperCollectionOptions = {
     viper: Viper;

package/dist/db.js

@@ -5,6 +5,7 @@ import { useViper } from "./provider.js";
 export { toViperFilter, toViperSort } from "./db-query.js";
 export { useLivePage, viperPage, viperPageOptions, } from "./db-page.js";
 export { pageComparator, planPage, } from "./page-plan.js";
+export { fetchCollectionOptions, fetched, forgetFetched, refetchFetched, useFetched, useFetchedAll, } from "./db-fetch.js";
 export { useLiveQuery };
 /**
  * Options for `createCollection()`: a TanStack DB collection that holds every
@@ -318,9 +319,7 @@ export function useLiveRecords(name, options = {}) {
     const rows = useViperCollection(name, options);
     const { query } = options;
     const live = useLiveQuery({
-        query: (q) => query
-            ? query(q, rows)
-            : q.from({ row: rows }),
+        query: (q) => (query ? query(q, rows) : q.from({ row: rows })),
     });
     return {
         data: live.isReady ? live.data : null,

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { ViperProvider, useViper, type ViperProviderProps } from "./provider.js";
-export { useAuth, useSession, useUser } from "./auth.js";
+export { useAuth, useAuthMethods, useSession, useInvites, useSessions, useTenants, useUser, } from "./auth.js";
 export { useRealtime, useRealtimeStatus } from "./realtime.js";
 export { useRecord, useRecords, type Query, type RecordsOptions, } from "./records.js";
-export { Viper, ViperError, fieldError, memoryStorage, type ListOptions, type ListResult, type RealtimeEvent, type RealtimeStatus, type RecordInput, type RecordModel, type Session, type ViperOptions, } from "@polyphron/viper-client";
+export { useRun, type RunState } from "./runs.js";
+export { Viper, ViperError, fieldError, memoryStorage, type ListOptions, type ListResult, type RealtimeEvent, type RealtimeStatus, type RecordInput, type RecordModel, type Session, type UserSession, type StartedRun, type ViperOptions, type WorkflowRun, } from "@polyphron/viper-client";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { ViperProvider, useViper } from "./provider.js";
-export { useAuth, useSession, useUser } from "./auth.js";
+export { useAuth, useAuthMethods, useSession, useInvites, useSessions, useTenants, useUser, } from "./auth.js";
 export { useRealtime, useRealtimeStatus } from "./realtime.js";
 export { useRecord, useRecords, } from "./records.js";
+export { useRun } from "./runs.js";
 // Re-exported so an app only needs @polyphron/viper-react in its imports.
 export { Viper, ViperError, fieldError, memoryStorage, } from "@polyphron/viper-client";

package/dist/runs.d.ts

@@ -0,0 +1,23 @@
+import type { StartedRun, WorkflowRun } from "@polyphron/viper-client";
+export type RunState<T> = {
+    /** The run as last read, or null before the first answer. */
+    data: WorkflowRun<T> | null;
+    error: unknown;
+    /** True from the start until the run is done or failed, or can't be read. */
+    pending: boolean;
+};
+/**
+ * Watches a background workflow's run until it's done or failed, reading
+ * it every `every` milliseconds (a second by default). Pass the
+ * `StartedRun` its call returned; nothing is read while it's empty.
+ *
+ * ```tsx
+ * const [started, setStarted] = useState<StartedRun>()
+ * const { data, pending } = useRun<{ text: string }>("forge", started)
+ * // on click: setStarted(await viper.workflows.call<StartedRun>("forge", input))
+ * // when done: data.response.body.text
+ * ```
+ */
+export declare function useRun<T = unknown>(name: string, started: StartedRun | null | undefined, options?: {
+    every?: number;
+}): RunState<T>;

package/dist/runs.js

@@ -0,0 +1,58 @@
+import { useEffect, useState } from "react";
+import { useViper } from "./provider.js";
+/**
+ * Watches a background workflow's run until it's done or failed, reading
+ * it every `every` milliseconds (a second by default). Pass the
+ * `StartedRun` its call returned; nothing is read while it's empty.
+ *
+ * ```tsx
+ * const [started, setStarted] = useState<StartedRun>()
+ * const { data, pending } = useRun<{ text: string }>("forge", started)
+ * // on click: setStarted(await viper.workflows.call<StartedRun>("forge", input))
+ * // when done: data.response.body.text
+ * ```
+ */
+export function useRun(name, started, options = {}) {
+    const viper = useViper();
+    const every = options.every ?? 1000;
+    const run = started?.run;
+    const token = started?.token;
+    // The answer carries the run it's for, so another run's never shows.
+    const [state, setState] = useState({ key: "", data: null, error: null });
+    useEffect(() => {
+        if (run === undefined || token === undefined)
+            return;
+        const key = `${name}/${run}`;
+        const controller = new AbortController();
+        let timer;
+        const read = async () => {
+            try {
+                const data = await viper.workflows.run(name, { run, token }, { signal: controller.signal });
+                setState({ key, data, error: null });
+                if (data.status !== "done" && data.status !== "failed") {
+                    timer = setTimeout(() => void read(), every);
+                }
+            }
+            catch (error) {
+                if (!controller.signal.aborted)
+                    setState({ key, data: null, error });
+            }
+        };
+        void read();
+        return () => {
+            controller.abort();
+            clearTimeout(timer);
+        };
+    }, [viper, name, run, token, every]);
+    const mine = run !== undefined && state.key === `${name}/${run}`;
+    const data = mine ? state.data : null;
+    const error = mine ? state.error : null;
+    return {
+        data,
+        error,
+        pending: run !== undefined &&
+            !error &&
+            data?.status !== "done" &&
+            data?.status !== "failed",
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyphron/viper-react",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "React provider and hooks for the Viper app API.",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@polyphron/viper-client": "^0.2.0",
+    "@polyphron/viper-client": "^0.3.0",
     "@tanstack/db": "0.9.2",
     "@tanstack/react-db": "0.4.1",
     "react": "^18.3.0 || ^19.0.0"
@@ -42,6 +42,7 @@
     "@tanstack/react-db": "0.4.1",
     "@types/node": "^24",
     "@types/react": "^19",
+    "@viper/admin": "*",
     "eslint": "^10",
     "eslint-plugin-react-hooks": "^7.1.1",
     "react": "^19.2.8",