@polyphron/viper-react 0.3.0 → 0.5.0

package/README.md

@@ -71,6 +71,17 @@ function SignIn() {
 
 ## The hooks
 
+With personal tokens or device sign-in enabled, `useAuth().auth` exposes
+`createToken`, `tokens`, `revokeToken`, `startDeviceSignIn`, `authorizeDevice`
+and `pollDeviceSignIn`. Polling an approved device saves its normal session,
+so `useUser()` updates. Only display the user code and verification URI;
+keep the device code private and honor each polling result's interval.
+
+With email change confirmation enabled, `useAuth()` exposes
+`auth.requestEmailChange(newEmail)` and `auth.confirmEmailChange(token)`.
+Both need the current user's session. After confirming, call `auth.me()`
+to refresh the email shown by `useUser()`.
+
 | Hook | What it gives you |
 | --- | --- |
 | `useViper()` | The `Viper` client — writes go through it: `viper.collection("posts").create(…)` |
@@ -78,6 +89,12 @@ function SignIn() {
 | `useRecord(collection, id, options)` | One record, same shape |
 | `useAuth(collection)` | `{ user, auth }` for an auth collection |
 | `useSession()` / `useUser()` | The session / the logged-in user, re-rendering on change |
+| `useSessionOf(client, read)` | The same for any client with `onSessionChange` (the admin client, say); `read` returns what to show, like `() => admin.user` |
+| `useAuthMethods({ collection?, enabled? })` | How to sign in here (methods, sign-up, project branding), or `null` while it loads |
+| `useSessions()` | The user's active sessions: `{ sessions, error, loading, refresh, revoke, logoutEverywhere }` |
+| `useInvites()` | Invites the user sent: `{ invites, error, loading, refresh, invite, cancel }` |
+| `useTenants(name)` | The user's memberships of tenant collection `name`; never the last user's list |
+| `useRun(name, started, { every? })` | Follows a background workflow's run until it ends: `{ data, error, pending }` |
 | `useRealtime(topics, onEvent)` | Watch changes yourself; returns the connection status |
 | `useRealtimeStatus()` | `"closed"`, `"connecting"` or `"live"` |
 
@@ -95,6 +112,14 @@ flight, so lists don't flash.
 - With `live: true`, the list is also re-fetched once after the socket comes
   back from a drop, since events may have been missed while it was down.
 
+`useSessions` and `useInvites` both give `loading` (true
+until the first answer for this user), `error` (an `Error` or `null`) and
+`refresh()`, which resolves once the new answer is in. They key their state on
+the signed-in user, so after a user switch you never see the last user's data.
+`useLoaded(subject, load)` is the helper they and `useRecords` are built on;
+use it to write your own fetching hook. It returns the same `Query` shape as
+`useRecords`.
+
 `@polyphron/viper-client` is a peer dependency: install it next to this
 package, so the app and the hooks share one client.
 

package/dist/auth.d.ts

@@ -1,10 +1,19 @@
 import type { AuthMethods, AuthService, Invite, InviteInput, RecordModel, Session, UserSession } from "@polyphron/viper-client";
+/**
+ * The session of any client that announces changes (`Viper`, `ViperAdmin`),
+ * re-rendering when it changes. `read` returns what to show from the client,
+ * like `() => admin.user`. It must be stable between changes.
+ */
+export declare function useSessionOf<S>(client: {
+    onSessionChange(listener: () => void): () => void;
+}, read: () => S | null): S | null;
 /** 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;
+    loading: boolean;
     refresh: () => Promise<void>;
     revoke: (sessionId: string) => Promise<void>;
     logoutEverywhere: () => Promise<void>;
@@ -13,6 +22,7 @@ export declare function useSessions(): {
 export declare function useInvites(): {
     invites: Invite[] | null;
     error: Error | null;
+    loading: boolean;
     refresh: () => Promise<void>;
     invite: (input: InviteInput) => Promise<Invite>;
     cancel: (id: string) => Promise<void>;
@@ -27,6 +37,12 @@ export declare function useUser<T extends RecordModel = RecordModel>(): T | null
  * ```tsx
  * const { user, auth } = useAuth()
  * await auth.loginWithPassword(email, password)
+ * await auth.requestEmailChange(newEmail)
+ * await auth.confirmEmailChange(token)
+ * await auth.me() // refresh the user after confirmation
+ * const proof = await auth.beginOAuth2("google", location.href)
+ * // Keep proof.codeVerifier across navigation to proof.url.
+ * const links = await auth.oauth2Links()
  * ```
  */
 export declare function useAuth<T extends RecordModel = RecordModel>(collection?: string): {
@@ -34,21 +50,26 @@ export declare function useAuth<T extends RecordModel = RecordModel>(collection?
     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.
+ * How to sign in here: the ways on offer, sign-up, and the project's
+ * branding. Null while
+ * it loads, and when the load fails: the sign-in calls report their own
+ * errors. Name an auth `collection` when the project has several, and pass
+ * `enabled: false` to hold the request back. For a sign-in page.
  *
  * ```tsx
  * const methods = useAuthMethods()
- * return <h1>{methods?.app?.branding.name ?? methods?.app?.name}</h1>
+ * return <h1>{methods?.branding?.name}</h1>
  * ```
  */
-export declare function useAuthMethods(): AuthMethods | null;
+export declare function useAuthMethods(options?: {
+    collection?: string;
+    enabled?: boolean;
+}): 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.
+ * while signed out, null while it loads (and when the load fails). It
+ * loads again when the user changes, and never shows the last user's list.
  *
  * ```tsx
  * const orgs = useTenants("orgs")

package/dist/auth.js

@@ -1,127 +1,55 @@
-import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import { useCallback, useSyncExternalStore } from "react";
+import { asError, useLoaded } from "./loaded.js";
 import { useViper } from "./provider.js";
+/**
+ * The session of any client that announces changes (`Viper`, `ViperAdmin`),
+ * re-rendering when it changes. `read` returns what to show from the client,
+ * like `() => admin.user`. It must be stable between changes.
+ */
+export function useSessionOf(client, read) {
+    return useSyncExternalStore((listener) => client.onSessionChange(listener), read, () => null);
+}
 /** 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);
+    return useSessionOf(viper, () => viper.session);
 }
 /** 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;
+    const userId = useUser()?.id ?? null;
+    const { data, error, loading, reload } = useLoaded(userId, useCallback((signal) => userId ? viper.auth.sessions({ signal }) : Promise.resolve(null), [viper, userId]));
     return {
-        sessions: current?.sessions ?? null,
-        error: current?.error ?? null,
-        refresh,
-        revoke,
-        logoutEverywhere,
+        sessions: data,
+        error: error ? asError(error) : null,
+        loading,
+        refresh: reload,
+        revoke: async (sessionId) => {
+            await viper.auth.revokeSession(sessionId);
+            await reload();
+        },
+        logoutEverywhere: () => viper.auth.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;
+    const userId = useUser()?.id ?? null;
+    const { data, error, loading, reload } = useLoaded(userId, useCallback((signal) => userId ? viper.auth.invites({ signal }) : Promise.resolve(null), [viper, userId]));
     return {
-        invites: current?.invites ?? null,
-        error: current?.error ?? null,
-        refresh,
-        invite,
-        cancel,
+        invites: data,
+        error: error ? asError(error) : null,
+        loading,
+        refresh: reload,
+        invite: async (input) => {
+            const made = await viper.auth.invite(input);
+            await reload();
+            return made;
+        },
+        cancel: async (id) => {
+            await viper.auth.cancelInvite(id);
+            await reload();
+        },
     };
 }
 /** The logged-in user, or null when signed out. */
@@ -136,6 +64,12 @@ export function useUser() {
  * ```tsx
  * const { user, auth } = useAuth()
  * await auth.loginWithPassword(email, password)
+ * await auth.requestEmailChange(newEmail)
+ * await auth.confirmEmailChange(token)
+ * await auth.me() // refresh the user after confirmation
+ * const proof = await auth.beginOAuth2("google", location.href)
+ * // Keep proof.codeVerifier across navigation to proof.url.
+ * const links = await auth.oauth2Links()
  * ```
  */
 export function useAuth(collection) {
@@ -147,34 +81,32 @@ export function useAuth(collection) {
     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.
+ * How to sign in here: the ways on offer, sign-up, and the project's
+ * branding. Null while
+ * it loads, and when the load fails: the sign-in calls report their own
+ * errors. Name an auth `collection` when the project has several, and pass
+ * `enabled: false` to hold the request back. For a sign-in page.
  *
  * ```tsx
  * const methods = useAuthMethods()
- * return <h1>{methods?.app?.branding.name ?? methods?.app?.name}</h1>
+ * return <h1>{methods?.branding?.name}</h1>
  * ```
  */
-export function useAuthMethods() {
+export function useAuthMethods(options = {}) {
     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;
+    const { collection, enabled = true } = options;
+    const { data } = useLoaded(`${collection ?? ""}/${enabled}`, useCallback((signal) => enabled
+        ? (collection
+            ? viper.collection(collection).auth
+            : viper.auth).methods({ signal })
+        : Promise.resolve(null), [viper, collection, enabled]));
+    return data;
 }
 /**
  * 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.
+ * while signed out, null while it loads (and when the load fails). It
+ * loads again when the user changes, and never shows the last user's list.
  *
  * ```tsx
  * const orgs = useTenants("orgs")
@@ -183,16 +115,7 @@ export function useAuthMethods() {
  */
 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;
+    const userId = useUser()?.id ?? "";
+    const { data } = useLoaded(`${name}/${userId}`, useCallback((signal) => viper.tenants(name, { signal }), [viper, name]));
+    return data;
 }

package/dist/db-fetch.js

@@ -9,6 +9,7 @@ import { ViperError } from "@polyphron/viper-client";
 import { createCollection } from "@tanstack/db";
 import { useLiveQuery } from "@tanstack/react-db";
 import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { cacheOf, same, singleFlight } from "./db-shared.js";
 // The key a one-object fetch keeps its row under.
 const ONE = "one";
 // Loads that failed on the network (not "no" or "not found") try again.
@@ -18,10 +19,6 @@ 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) => {
@@ -66,8 +63,6 @@ export function fetchCollectionOptions(options) {
         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
@@ -118,59 +113,48 @@ export function fetchCollectionOptions(options) {
                     : 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();
+        const load = singleFlight({
+            start: () => publish({ fetching: true }),
+            pass: async () => {
+                let data;
+                const at = generation;
+                for (let tries = 0;; tries++) {
+                    try {
+                        data = await fetch(controller.signal);
+                        break;
+                    }
+                    catch (error) {
+                        // The server said no. No answer at all (status 0) and
+                        // server trouble are worth another go.
+                        const refused = error instanceof ViperError &&
+                            error.status > 0 &&
+                            error.status < 500;
+                        if (closed || refused || tries >= RETRIES)
+                            throw error;
+                        await wait(1000 * 2 ** tries, controller.signal);
+                    }
                 }
-            })();
-            return loading;
-        };
+                if (closed)
+                    return;
+                // set() put newer data in while this was on the way.
+                if (at === generation)
+                    apply(data);
+            },
+            closed: () => closed,
+            fail: (error) => {
+                if (closed)
+                    return;
+                // Ready with no rows, so preload() settles; the error is in state.
+                markReady();
+                publish({ error });
+                waiting.forEach((w) => w.fail(error));
+                waiting.clear();
+            },
+            settle: () => {
+                publish({ fetching: false });
+                schedule();
+            },
+        });
         live = { load, apply, schedule };
         void load();
         return () => {
@@ -242,41 +226,29 @@ export function fetchCollectionOptions(options) {
     };
 }
 // 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();
+// collection (and one request). One leaves the cache when TanStack DB cleans
+// it up, after nothing has read it for a while.
+const made = cacheOf();
 /**
  * The fetched collection for `options.key` under `owner` (a client, say),
  * made once and shared. For a list pass `getKey`; leave it out for one object.
  */
 export function fetched(owner, options) {
-    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);
+    return made(owner, JSON.stringify(options.key), () => {
+        const collection = Object.assign(createCollection(fetchCollectionOptions(options)), { kind: options.getKey ? "list" : "one", key: options.key });
+        // Asking for the data (or putting some in) starts the sync if nothing
+        // has yet, so a route loader can await ready() on its own.
+        const { ready, set } = collection.utils;
+        collection.utils.ready = () => {
+            collection.startSyncImmediate();
+            return ready();
+        };
+        collection.utils.set = (data) => {
+            collection.startSyncImmediate();
+            set(data);
+        };
+        return collection;
     });
-    byKey.set(hash, collection);
-    return collection;
 }
 // True when `key` starts with every part of `prefix`.
 function startsWith(key, prefix) {
@@ -289,7 +261,7 @@ function startsWith(key, prefix) {
  */
 export function refetchFetched(owner, prefix) {
     const loads = [];
-    for (const collection of made.get(owner)?.values() ?? []) {
+    for (const collection of made.of(owner)?.values() ?? []) {
         if (!startsWith(collection.key, prefix))
             continue;
         loads.push(collection.utils.stale());
@@ -301,7 +273,7 @@ export function refetchFetched(owner, prefix) {
  * `prefix`, so nothing shows its data again (after a project is deleted).
  */
 export function forgetFetched(owner, prefix) {
-    const byKey = made.get(owner);
+    const byKey = made.of(owner);
     for (const [hash, collection] of byKey ?? []) {
         if (!startsWith(collection.key, prefix))
             continue;