@polyphron/viper-react 0.1.2 → 0.3.0

package/README.md

@@ -74,7 +74,7 @@ function SignIn() {
 | Hook | What it gives you |
 | --- | --- |
 | `useViper()` | The `Viper` client — writes go through it: `viper.collection("posts").create(…)` |
-| `useRecords(collection, options)` | One page of records: `{ data, loading, error, reload }` |
+| `useRecords(collection, options)` | One page of records: `{ data, loading, refreshing, error, reload }` |
 | `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 |
@@ -85,6 +85,19 @@ function SignIn() {
 what they are showing. The last good data stays on screen while a reload is in
 flight, so lists don't flash.
 
+- `loading` is true only until the first answer for what is shown. A reload
+  or a live update does not set it again. Changing the collection (or the
+  record id, for `useRecord`) clears `data` and sets it again, so a form never
+  sees the previous record.
+- `refreshing` is true whenever a request is in flight, first load included.
+  Use it for a small spinner. (Before, `loading` was also true during
+  reloads; read `refreshing` if you relied on that.)
+- 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.
+
+`@polyphron/viper-client` is a peer dependency: install it next to this
+package, so the app and the hooks share one client.
+
 ## Writes
 
 There is no mutation hook: the client's own methods are already promises.
@@ -96,3 +109,214 @@ const { reload } = useRecords("posts")
 await viper.collection("posts").create({ title: "Hello" })
 reload() // or pass live: true and let realtime do it
 ```
+
+## Viper collections (experimental)
+
+`@polyphron/viper-react/db` puts a Viper collection into
+[TanStack DB](https://tanstack.com/db), so you can run live queries over
+records kept in the browser. It is opt-in: the client and the hooks above
+don't need it, and the API may change. Install the peers, pinned to the
+versions it is tested with:
+
+```sh
+npm install @tanstack/db@0.9.2 @tanstack/react-db@0.4.1
+```
+
+```tsx
+import { createCollection, eq } from "@tanstack/db"
+import { useLiveQuery, viperCollectionOptions } from "@polyphron/viper-react/db"
+
+const posts = createCollection(
+  viperCollectionOptions<Post>({ viper, collection: "posts" })
+)
+
+function Live() {
+  const { data } = useLiveQuery((q) =>
+    q.from({ p: posts }).where(({ p }) => eq(p.status, "live"))
+  )
+
+  return <ul>{data.map((p) => <li key={p.id}>{p.title}</li>)}</ul>
+}
+
+// Shows at once, is saved in the background, and is rolled back if the
+// server refuses it. Give it your own 15-character id.
+posts.insert({ id, title: "Hi" })
+```
+
+- It loads every record the list rule lets the user see, then applies
+  realtime events straight to the copy: no request per change. After a
+  dropped connection, or a `refresh` from a view collection, it loads again.
+- Writes call the records API. Several in one transaction go to
+  `viper.batch()` and succeed or fail together. The server's answer (`id`,
+  `created`, `updated`, stamped defaults) replaces the optimistic row.
+- A realtime event older than the row's `updated` is ignored, so an echo of
+  your own write can't undo a newer one.
+- Eager (the default) suits small collections. For big ones pass
+  `syncMode: "on-demand"`: nothing loads until a live query asks, and then
+  only its `where`, `orderBy` and `limit` are sent, as a Viper `filter`,
+  `sort` and page. What Viper can't say (`not`, nested paths, `null`) is
+  left out, so a little more loads and the query filters it again; `like`
+  and `ilike` become `~` (a case-insensitive contains). A `limit` is only
+  sent when the whole `where` and `orderBy` could be. Realtime events are
+  applied for every row the user may see, and a reload fetches the queries
+  again. Paging is by page number with `skipTotal`, so the server never
+  counts; a keyset cursor cannot be used, because TanStack DB asks for an
+  offset and Viper's cursor is a token only the previous page hands out.
+- Rules stay on the server; the copy holds only what the list rule and
+  realtime allow.
+
+### Hooks
+
+`useViperCollection<Row>(name, { syncMode? })` gives the collection for the
+client in `<ViperProvider>`, made once and shared by every component that asks
+for the same name and mode. `useLiveRecords<Row>(name, { syncMode?, query? })`
+reads it as `{ data, error, loading }` (`data` is null until loaded), with
+`query` for a filter, sort or join. Both are opt-in; `useRecords` and
+`useRecord` work as before.
+
+### A live server page
+
+For a table that pages on the server (a text filter, totals, `expand`, the
+Deleted view), `useLivePage<Row>(name, query)` holds one page of
+`records.list` in a TanStack DB collection and keeps it fresh. `query` takes
+what `records.list` takes: `page`, `perPage`, `sort`, `filter`, `expand`,
+`deleted`.
+
+```tsx
+const { items, totalItems, totalPages, loading, collection } =
+  useLivePage<Post>("posts", { page, perPage: 30, sort: "-updated", filter })
+
+collection.delete(ids) // hidden at once, one batch, put back if refused
+collection.utils.refetch() // ask for the page again
+```
+
+- A change that can't move rows between pages (an edit that keeps the sort
+  values, on a page with no filter) patches its row; no request. Anything
+  else (a create, a delete, a filter the browser can't run) asks for the
+  page again, once per burst. `expand` is kept while the links don't change.
+- While a new `query` loads, the last page stays on screen.
+- `viperPage(viper, name, query).preload()` starts the fetch early, from a
+  route loader say; the hook then reads the same collection.
+- `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
+   the root README). Each collection gets a row type and a `Collections` map.
+2. Get each collection with `useViperCollection<Collections["posts"]>("posts")`.
+3. Read with `useLiveQuery`, joining collections in the browser.
+4. Write with `collection.insert`. The row shows at once, and is rolled back
+   if the server refuses it, so put the form text back in that case.
+
+```tsx
+import { eq } from "@tanstack/db"
+import { useLiveQuery, useViperCollection } from "@polyphron/viper-react/db"
+import { useState, type FormEvent } from "react"
+
+import type { Collections, PostCreate } from "./viper-types"
+
+// Viper ids are 15 characters. The row needs one before the server answers.
+const newId = () =>
+  Array.from(
+    { length: 15 },
+    () => "abcdefghijklmnopqrstuvwxyz0123456789"[Math.floor(Math.random() * 36)]
+  ).join("")
+
+export function LivePosts({ authorId }: { authorId: string }) {
+  const posts = useViperCollection<Collections["posts"]>("posts")
+  const authors = useViperCollection<Collections["authors"]>("authors")
+  const [title, setTitle] = useState("")
+
+  // A join between two collections; only changed rows re-render.
+  const { data = [], isLoading } = useLiveQuery((q) =>
+    q
+      .from({ p: posts })
+      .innerJoin({ a: authors }, ({ p, a }) => eq(p.author, a.id))
+      .where(({ p }) => eq(p.status, "live"))
+      .orderBy(({ p }) => p.created, "desc")
+      .select(({ p, a }) => ({ id: p.id, title: p.title, by: a.name }))
+  )
+
+  const add = async (event: FormEvent) => {
+    event.preventDefault()
+
+    const draft: PostCreate & { id: string } = {
+      id: newId(),
+      title,
+      status: "live",
+      author: authorId,
+    }
+    // The cast is because insert wants a whole row; the server fills in
+    // `created`, `updated` and defaults.
+    const tx = posts.insert(draft as Collections["posts"])
+
+    setTitle("")
+
+    try {
+      await tx.isPersisted.promise
+    } catch {
+      setTitle(draft.title)
+    }
+  }
+
+  if (isLoading) return <p>Loading</p>
+
+  return (
+    <form onSubmit={add}>
+      <ul>
+        {data.map((row) => (
+          <li key={row.id}>
+            {row.title} by {row.by}
+          </li>
+        ))}
+      </ul>
+      <input value={title} onChange={(e) => setTitle(e.target.value)} />
+    </form>
+  )
+}
+```

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