@polyphron/viper-react 0.3.0 → 0.4.0

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 {};

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.js

@@ -1,5 +1,6 @@
 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";
@@ -30,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
@@ -104,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,
@@ -152,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 {
@@ -198,7 +184,7 @@ export function viperCollectionOptions(options) {
                 }
                 finally {
                     pending--;
-                    if (pending === 0 && !loading)
+                    if (pending === 0 && !load.busy())
                         buffered = [];
                 }
             },
@@ -227,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);
@@ -248,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) {
@@ -273,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
@@ -289,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

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,6 +1,8 @@
 export { ViperProvider, useViper, type ViperProviderProps } from "./provider.js";
-export { useAuth, useAuthMethods, useSession, useInvites, useSessions, useTenants, 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 { useLoaded, type Query } from "./loaded.js";
+export { useRecord, useRecords, type RecordsOptions } from "./records.js";
 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";
+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,7 +1,9 @@
 export { ViperProvider, useViper } from "./provider.js";
-export { useAuth, useAuthMethods, useSession, useInvites, useSessions, useTenants, 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>;