@polyphron/viper-react 0.2.1 → 0.4.0

package/dist/db-shared.js

@@ -0,0 +1,82 @@
+/**
+ * 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 function singleFlight(options) {
+    let flight = null;
+    let again = false;
+    const load = () => {
+        if (flight) {
+            again = true;
+            return flight;
+        }
+        flight = (async () => {
+            options.start?.();
+            try {
+                do {
+                    again = false;
+                    await options.pass();
+                } while (again && !options.closed());
+            }
+            catch (error) {
+                options.fail(error);
+            }
+            finally {
+                flight = null;
+                options.settle?.();
+            }
+        })();
+        return flight;
+    };
+    return Object.assign(load, { busy: () => flight !== null });
+}
+/**
+ * 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 function cacheOf() {
+    const byOwner = new WeakMap();
+    const get = (owner, key, make) => {
+        let byKey = byOwner.get(owner);
+        if (!byKey) {
+            byKey = new Map();
+            byOwner.set(owner, byKey);
+        }
+        const found = byKey.get(key);
+        if (found)
+            return found;
+        const made = make();
+        const map = byKey;
+        made.on("status:change", ({ status }) => {
+            if (status === "cleaned-up")
+                map.delete(key);
+        });
+        map.set(key, made);
+        return made;
+    };
+    return Object.assign(get, { of: (owner) => byOwner.get(owner) });
+}
+/**
+ * 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 async function sendOps(viper, ops) {
+    if (ops.length !== 1)
+        return viper.batch(ops);
+    const op = ops[0];
+    const records = viper.collection(op.collection).records;
+    if (op.method === "create")
+        return [await records.create(op.body)];
+    if (op.method === "update")
+        return [await records.update(op.id, op.body)];
+    await records.delete(op.id);
+    return [null];
+}
+/** True when two values are the same, lists and objects included. */
+export function same(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}

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

@@ -1,10 +1,12 @@
 import { createCollection } from "@tanstack/db";
 import { useLiveQuery } from "@tanstack/react-db";
+import { cacheOf, sendOps, singleFlight } from "./db-shared.js";
 import { toViperFilter, toViperSort, toWindow } from "./db-query.js";
 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
@@ -29,8 +31,6 @@ export function viperCollectionOptions(options) {
         // event (our own write coming back, say) unable to undo a newer one.
         const versions = new Map();
         let closed = false;
-        let loading = false;
-        let again = false;
         // Events that arrive while a load is in flight, replayed after it.
         let buffered = [];
         // On-demand: subset loads in flight (they buffer events too), and the
@@ -103,40 +103,27 @@ export function viperCollectionOptions(options) {
             });
             return result.items;
         };
-        const load = async () => {
-            // One load at a time; a request during a load runs another after it.
-            if (loading) {
-                again = true;
-                return;
-            }
-            loading = true;
-            try {
-                do {
-                    again = false;
-                    const items = await fetchAll();
-                    if (closed)
-                        return;
-                    // Truncate and rewrite in one transaction, so a reload never
-                    // shows an empty list in between.
-                    begin();
-                    truncate();
-                    versions.clear();
-                    items.forEach(put);
-                    const missed = buffered;
-                    if (pending === 0)
-                        buffered = [];
-                    missed.forEach(apply);
-                    commit();
-                    markReady();
-                } while (again);
-            }
-            catch (error) {
-                markError(error);
-            }
-            finally {
-                loading = false;
-            }
-        };
+        const load = singleFlight({
+            pass: async () => {
+                const items = await fetchAll();
+                if (closed)
+                    return;
+                // Truncate and rewrite in one transaction, so a reload never
+                // shows an empty list in between.
+                begin();
+                truncate();
+                versions.clear();
+                items.forEach(put);
+                const missed = buffered;
+                if (pending === 0)
+                    buffered = [];
+                missed.forEach(apply);
+                commit();
+                markReady();
+            },
+            closed: () => closed,
+            fail: markError,
+        });
         sink = {
             put,
             remove,
@@ -151,7 +138,7 @@ export function viperCollectionOptions(options) {
             if (event.action === "refresh") {
                 void load();
             }
-            else if (loading || pending > 0) {
+            else if (load.busy() || pending > 0) {
                 buffered.push(event);
             }
             else {
@@ -197,7 +184,7 @@ export function viperCollectionOptions(options) {
                 }
                 finally {
                     pending--;
-                    if (pending === 0 && !loading)
+                    if (pending === 0 && !load.busy())
                         buffered = [];
                 }
             },
@@ -226,15 +213,15 @@ export function viperCollectionOptions(options) {
         sync: { sync, rowUpdateMode: "full" },
         syncMode: onDemand ? "on-demand" : "eager",
         onInsert: async ({ transaction }) => {
-            const saved = await save(viper, records, collection, transaction.mutations);
+            const saved = await sendOps(viper, toOps(collection, transaction.mutations));
             store(saved);
         },
         onUpdate: async ({ transaction }) => {
-            const saved = await save(viper, records, collection, transaction.mutations);
+            const saved = await sendOps(viper, toOps(collection, transaction.mutations));
             store(saved);
         },
         onDelete: async ({ transaction }) => {
-            await save(viper, records, collection, transaction.mutations);
+            await sendOps(viper, toOps(collection, transaction.mutations));
             sink?.write(() => {
                 for (const m of transaction.mutations)
                     sink?.remove(m.key);
@@ -247,19 +234,9 @@ export function viperCollectionOptions(options) {
 function hiddenAnswer(record) {
     return Object.keys(record).every((key) => key === "id" || key === "collectionId" || key === "collectionName");
 }
-// Sends the mutations: one call for one, a single all-or-nothing batch for
-// several. Resolves to the saved records, in order (null for a delete).
-async function save(viper, records, collection, mutations) {
-    if (mutations.length > 1) {
-        return viper.batch(mutations.map((m) => toOp(collection, m)));
-    }
-    const m = mutations[0];
-    if (m.type === "insert")
-        return [await records.create(m.modified)];
-    if (m.type === "update")
-        return [await records.update(m.key, m.changes)];
-    await records.delete(m.key);
-    return [null];
+// The mutations as batch writes; `sendOps` sends one alone when it can.
+function toOps(collection, mutations) {
+    return mutations.map((m) => toOp(collection, m));
 }
 // One mutation as a batch write.
 function toOp(collection, m) {
@@ -272,8 +249,9 @@ function toOp(collection, m) {
     return { method: "delete", collection, id: m.key };
 }
 // Collections made by `useViperCollection`, one per client, name and mode, so
-// two components asking for `posts` share one copy of it (and one fetch).
-const made = new WeakMap();
+// two components asking for `posts` share one copy of it (and one fetch). One
+// leaves when TanStack DB cleans it up, so the next ask gets a fresh one.
+const made = cacheOf();
 /**
  * The Viper collection `name` for the client in `<ViperProvider>`, made once
  * and shared: every component asking for the same name and mode gets the same
@@ -288,18 +266,11 @@ const made = new WeakMap();
 export function useViperCollection(name, options = {}) {
     const viper = useViper();
     const mode = options.syncMode ?? "eager";
-    let byName = made.get(viper);
-    if (!byName) {
-        byName = new Map();
-        made.set(viper, byName);
-    }
-    const key = `${mode}:${name}`;
-    let found = byName.get(key);
-    if (!found) {
-        found = createCollection(viperCollectionOptions({ viper, collection: name, syncMode: mode }));
-        byName.set(key, found);
-    }
-    return found;
+    return made(viper, `${mode}:${name}`, () => createCollection(viperCollectionOptions({
+        viper,
+        collection: name,
+        syncMode: mode,
+    })));
 }
 /**
  * The rows of a Viper collection as a live list, like `useRecords` but read
@@ -318,9 +289,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/identity.d.ts

@@ -0,0 +1,21 @@
+import type { AppIdentity, AppMember, AppRole } from "@polyphron/viper-client";
+/** The signed-in user's current app role and collection permission ceilings. */
+export declare function useAppIdentity(): {
+    identity: AppIdentity | null;
+    error: Error | null;
+    loading: boolean;
+    refresh: () => Promise<void>;
+};
+/** Opt-in app-admin role/member operations; successful edits refresh all data. */
+export declare function useAppManagement(): {
+    putRole: (name: string, grid: AppRole["grid"], options?: Pick<import("@polyphron/viper-client").RequestOptions, "signal">) => Promise<void>;
+    deleteRole: (name: string, options?: Pick<import("@polyphron/viper-client").RequestOptions, "signal">) => Promise<void>;
+    putMember: (user: string, role: string, options?: Pick<import("@polyphron/viper-client").RequestOptions, "signal">) => Promise<void>;
+    deleteMember: (user: string, options?: Pick<import("@polyphron/viper-client").RequestOptions, "signal">) => Promise<void>;
+    identity: AppIdentity | null;
+    roles: AppRole[] | null;
+    members: AppMember[] | null;
+    error: Error | null;
+    loading: boolean;
+    refresh: () => Promise<void>;
+};

package/dist/identity.js

@@ -0,0 +1,54 @@
+import { useCallback, useEffect } from "react";
+import { useSession } from "./auth.js";
+import { asError, useLoaded } from "./loaded.js";
+import { useViper } from "./provider.js";
+/** Loads identity data scoped to this exact client and session. */
+function useIdentityData(manage) {
+    const viper = useViper();
+    const session = useSession();
+    const { data, error, loading, reload } = useLoaded(session, useCallback(async (signal) => {
+        if (!session)
+            return null;
+        const identity = await viper.identity.me({ signal });
+        if (!manage)
+            return { identity, roles: null, members: null, error: null };
+        // A 403 on roles or members mustn't drop the role me() just gave.
+        try {
+            const [roles, members] = await Promise.all([
+                viper.identity.roles({ signal }),
+                viper.identity.members({ signal }),
+            ]);
+            return { identity, roles, members, error: null };
+        }
+        catch (cause) {
+            return { identity, roles: null, members: null, error: asError(cause) };
+        }
+    }, [viper, session, manage]));
+    // Sign-in and role changes elsewhere in the app ask for a fresh load.
+    useEffect(() => viper.identity.onChange(reload), [viper, reload]);
+    return {
+        identity: data?.identity ?? null,
+        roles: data?.roles ?? null,
+        members: data?.members ?? null,
+        error: data?.error ?? (error ? asError(error) : null),
+        loading,
+        refresh: reload,
+    };
+}
+/** The signed-in user's current app role and collection permission ceilings. */
+export function useAppIdentity() {
+    const { identity, error, loading, refresh } = useIdentityData(false);
+    return { identity, error, loading, refresh };
+}
+/** Opt-in app-admin role/member operations; successful edits refresh all data. */
+export function useAppManagement() {
+    const viper = useViper();
+    const state = useIdentityData(true);
+    return {
+        ...state,
+        putRole: viper.identity.putRole,
+        deleteRole: viper.identity.deleteRole,
+        putMember: viper.identity.putMember,
+        deleteMember: viper.identity.deleteMember,
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { ViperProvider, useViper, type ViperProviderProps } from "./provider.js";
-export { useAuth, useSession, useUser } from "./auth.js";
+export { useAuth, useAuthMethods, useSession, useSessionOf, 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 { useLoaded, type Query } from "./loaded.js";
+export { useRecord, useRecords, type RecordsOptions } from "./records.js";
+export { useRun, type RunState } from "./runs.js";
+export { useAppIdentity, useAppManagement } from "./identity.js";
+export { type AppIdentity, type AppMember, type AppRole, type AppLevel, 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,9 @@
 export { ViperProvider, useViper } from "./provider.js";
-export { useAuth, useSession, useUser } from "./auth.js";
+export { useAuth, useAuthMethods, useSession, useSessionOf, useInvites, useSessions, useTenants, useUser, } from "./auth.js";
 export { useRealtime, useRealtimeStatus } from "./realtime.js";
-export { useRecord, useRecords, } from "./records.js";
+export { useLoaded } from "./loaded.js";
+export { useRecord, useRecords } from "./records.js";
+export { useRun } from "./runs.js";
+export { useAppIdentity, useAppManagement } from "./identity.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/loaded.d.ts

@@ -0,0 +1,30 @@
+/** What a loading hook hands back. */
+export type Query<T> = {
+    data: T | null;
+    error: unknown;
+    /**
+     * True until the first answer arrives for what is being shown (a new
+     * collection, a new record id, another user). A `reload` or a live update
+     * does not set it again, so the last data stays on screen; see
+     * `refreshing`.
+     */
+    loading: boolean;
+    /** True whenever a request is in flight, first load and reloads included. */
+    refreshing: boolean;
+    /** Fetches again now. The promise settles once the new answer is in. */
+    reload: () => Promise<void>;
+};
+/** Makes an `Error` out of whatever a failed load threw. */
+export declare function asError(cause: unknown): Error;
+/**
+ * The one fetch hook: runs `run` whenever it or `subject` changes, and gives
+ * back its state. Answers from a call that has already been replaced are
+ * dropped, so a slow first request can't overwrite a fast second one.
+ *
+ * `subject` names what is being shown (a collection, a user, a session);
+ * data from another subject is never handed back, only data from a reload of
+ * the same one. Subjects are compared with `Object.is`. `reload` fetches in
+ * its own call, not through a render, so awaiting it inside React's `act`
+ * (or any batched update) can't deadlock.
+ */
+export declare function useLoaded<T>(subject: unknown, run: (signal: AbortSignal) => Promise<T | null>): Query<T>;

package/dist/loaded.js

@@ -0,0 +1,64 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+/** Makes an `Error` out of whatever a failed load threw. */
+export function asError(cause) {
+    return cause instanceof Error ? cause : new Error(String(cause));
+}
+/**
+ * The one fetch hook: runs `run` whenever it or `subject` changes, and gives
+ * back its state. Answers from a call that has already been replaced are
+ * dropped, so a slow first request can't overwrite a fast second one.
+ *
+ * `subject` names what is being shown (a collection, a user, a session);
+ * data from another subject is never handed back, only data from a reload of
+ * the same one. Subjects are compared with `Object.is`. `reload` fetches in
+ * its own call, not through a render, so awaiting it inside React's `act`
+ * (or any batched update) can't deadlock.
+ */
+export function useLoaded(subject, run) {
+    const [inFlight, setInFlight] = useState(0);
+    const [answer, setAnswer] = useState({ subject: null, run: null, data: null, error: null });
+    // The newest request's controller and promise: starting one replaces the
+    // last, and a replaced request waits for the one that replaced it.
+    const controller = useRef(null);
+    const newest = useRef(Promise.resolve());
+    const fetchNow = useCallback((forSubject, forRun) => {
+        controller.current?.abort();
+        const mine = new AbortController();
+        controller.current = mine;
+        const request = (async () => {
+            // After a tick, so starting from an effect sets no state in it.
+            await Promise.resolve();
+            setInFlight((n) => n + 1);
+            try {
+                const data = await forRun(mine.signal);
+                if (!mine.signal.aborted) {
+                    setAnswer({ subject: forSubject, run: forRun, data, error: null });
+                }
+            }
+            catch (error) {
+                if (!mine.signal.aborted) {
+                    setAnswer({ subject: forSubject, run: forRun, data: null, error });
+                }
+            }
+            finally {
+                setInFlight((n) => n - 1);
+            }
+        })();
+        newest.current = request;
+        return request.then(() => mine.signal.aborted ? newest.current : undefined);
+    }, []);
+    useEffect(() => {
+        void fetchNow(subject, run);
+        return () => controller.current?.abort();
+    }, [subject, run, fetchNow]);
+    const sameSubject = answer.run !== null && Object.is(answer.subject, subject);
+    const current = answer.run === run && inFlight === 0;
+    return {
+        // The last good data stays on screen while a reload is in flight.
+        data: sameSubject ? answer.data : null,
+        error: current ? answer.error : null,
+        loading: !sameSubject,
+        refreshing: !current,
+        reload: useCallback(() => fetchNow(subject, run), [fetchNow, subject, run]),
+    };
+}

package/dist/page-plan.js

@@ -1,3 +1,4 @@
+import { same } from "./db-shared.js";
 // Sort fields the browser orders just as Postgres does: times compared as
 // times, and ids (a-z and 0-9) compared as text.
 const TIMES = new Set(["created", "updated"]);
@@ -50,10 +51,6 @@ export function pageComparator(sort) {
         return 0;
     };
 }
-// True when two field values are the same, lists and objects included.
-function same(a, b) {
-    return a === b || JSON.stringify(a) === JSON.stringify(b);
-}
 /** What `event` does to `page`. */
 export function planPage(event, page) {
     // A new row, or a view that changed: only the server knows where it goes.

package/dist/records.d.ts

@@ -1,18 +1,5 @@
 import type { ListOptions, ListResult, RecordModel } from "@polyphron/viper-client";
-export type Query<T> = {
-    data: T | null;
-    error: unknown;
-    /**
-     * True until the first answer arrives for what is being shown (a new
-     * collection, or a new record id). A `reload` or a live update does not set
-     * it again, so the last data stays on screen; see `refreshing`.
-     */
-    loading: boolean;
-    /** True whenever a request is in flight, first load and reloads included. */
-    refreshing: boolean;
-    /** Fetches again now. */
-    reload: () => void;
-};
+import { type Query } from "./loaded.js";
 export type RecordsOptions = ListOptions & {
     /** Re-fetch when anything in the collection changes. Off by default. */
     live?: boolean;

package/dist/records.js

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect } from "react";
+import { useLoaded } from "./loaded.js";
 import { useViper } from "./provider.js";
 import { useRealtime } from "./realtime.js";
 /**
@@ -13,7 +14,7 @@ export function useRecords(collection, options = {}) {
     const { live = false, ...list } = options;
     // Options are a fresh object every render; compare them by value.
     const key = JSON.stringify(list);
-    const query = useFetch(collection, useCallback((signal) => viper
+    const query = useLoaded(collection, useCallback((signal) => viper
         .collection(collection)
         .list({ ...JSON.parse(key), signal }), [viper, collection, key]));
     useLiveReload(live, collection, query.reload, viper);
@@ -23,7 +24,7 @@ export function useRecords(collection, options = {}) {
 export function useRecord(collection, id, options = {}) {
     const viper = useViper();
     const { live = false, expand } = options;
-    const query = useFetch(
+    const query = useLoaded(
     // A different record must never show the last one's data.
     `${collection}/${id ?? ""}`, useCallback((signal) => id
         ? viper.collection(collection).view(id, { expand, signal })
@@ -31,42 +32,6 @@ export function useRecord(collection, id, options = {}) {
     useLiveReload(live && Boolean(id), `${collection}/${id}`, query.reload, viper);
     return query;
 }
-// Runs `run` whenever it changes, and gives back its state. Answers from a
-// call that has already been replaced are dropped, so a slow first request
-// can't overwrite a fast second one.
-//
-// `refreshing` and `loading` are worked out rather than stored: the answer
-// carries the request it belongs to, so anything older than the current
-// request means "still waiting" — and no state has to be set while the effect
-// is starting. `subject` names what is being shown; data from another subject
-// is never handed back, only data from a reload of the same one.
-function useFetch(subject, run) {
-    const [attempt, setAttempt] = useState(0);
-    const [answer, setAnswer] = useState({ subject: "", run: null, attempt: -1, data: null, error: null });
-    useEffect(() => {
-        const controller = new AbortController();
-        run(controller.signal).then((data) => {
-            if (!controller.signal.aborted) {
-                setAnswer({ subject, run, attempt, data, error: null });
-            }
-        }, (error) => {
-            if (!controller.signal.aborted) {
-                setAnswer({ subject, run, attempt, data: null, error });
-            }
-        });
-        return () => controller.abort();
-    }, [subject, run, attempt]);
-    const current = answer.run === run && answer.attempt === attempt;
-    const sameSubject = answer.run !== null && answer.subject === subject;
-    return {
-        // The last good data stays on screen while a reload is in flight.
-        data: sameSubject ? answer.data : null,
-        error: current ? answer.error : null,
-        loading: !sameSubject,
-        refreshing: !current,
-        reload: useCallback(() => setAttempt((n) => n + 1), []),
-    };
-}
 // Reloads on every realtime event for `topic`, when `live` is on, and once
 // more after the socket comes back from a drop, since events may have been
 // missed while it was down. The hooks are always called, because hooks can't

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 has ended, or can't be read. */
+    pending: boolean;
+};
+/**
+ * Watches a background workflow's run until it's done, failed or cancelled, 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>;