@polyphron/viper-react 0.1.1 → 0.2.1

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,170 @@ 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.
+
+### 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/db-page.d.ts

@@ -0,0 +1,74 @@
+import type { ListOptions, RealtimeEvent, RecordModel, Viper } from "@polyphron/viper-client";
+import type { Collection, CollectionConfig } from "@tanstack/db";
+/** Which page: what `records.list` takes, less the count-free options. */
+export type PageQuery = Omit<ListOptions, "skipTotal" | "cursor" | "signal">;
+/** A page's totals and the order its rows go in. */
+export type PageInfo = {
+    /** The row ids, in the server's order. */
+    order: string[];
+    page: number;
+    perPage: number;
+    totalItems: number;
+    totalPages: number;
+};
+/** What a page collection adds under `collection.utils`. */
+export type PageUtils = {
+    /** The totals and the order now. */
+    info: () => PageInfo;
+    /** Calls `listener` whenever `info()` changes. Returns the unsubscribe. */
+    subscribe: (listener: () => void) => () => void;
+    /** Asks the server for the page again. */
+    refetch: () => Promise<void>;
+    /**
+     * Shows a change made outside the collection (a save with files, a
+     * restore) the way a realtime event would, without waiting for one.
+     */
+    apply: (event: RealtimeEvent) => void;
+};
+export type ViperPageOptions = {
+    viper: Viper;
+    /** The Viper collection's name, e.g. `posts`. */
+    collection: string;
+    query: PageQuery;
+};
+/**
+ * Options for `createCollection()`: one server page of `collection`, kept
+ * fresh from realtime. Its totals and row order are under `utils.info()`.
+ * Deleting rows from it hides them at once, sends one all-or-nothing batch,
+ * and puts them back if the server says no.
+ */
+export declare function viperPageOptions<T extends RecordModel = RecordModel>(options: ViperPageOptions): CollectionConfig<T, string, never, PageUtils> & {
+    utils: PageUtils;
+};
+/** A page collection, as `viperPage` and `useLivePage` give it. */
+export type PageCollection<T extends RecordModel = RecordModel> = Collection<T, string, PageUtils>;
+/**
+ * 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 declare function viperPage<T extends RecordModel = RecordModel>(viper: Viper, collection: string, query: PageQuery): PageCollection<T>;
+/** What `useLivePage` gives back. */
+export type LivePage<T extends RecordModel = RecordModel> = {
+    /** The page's rows in order, or null before the first load. */
+    items: T[] | null;
+    totalItems: number;
+    totalPages: number;
+    /** True while a page loads, including the next one after a change of query. */
+    loading: boolean;
+    error: unknown;
+    /** The collection, to delete rows or call `utils.refetch()` and `utils.apply()`. */
+    collection: PageCollection<T>;
+};
+/**
+ * One server page of `collection` as a live list: `records.list` once, then
+ * realtime keeps it fresh, patching rows where it can. While a new `query`
+ * loads, the last page stays on screen.
+ *
+ * ```tsx
+ * const { items, totalPages } = useLivePage<Post>("posts", {
+ *   page, perPage: 30, sort: "-updated", filter,
+ * })
+ * ```
+ */
+export declare function useLivePage<T extends RecordModel = RecordModel>(collection: string, query: PageQuery): LivePage<T>;

package/dist/db-page.js

@@ -0,0 +1,233 @@
+import { createCollection } from "@tanstack/db";
+import { useLiveQuery } from "@tanstack/react-db";
+import { useMemo, useState, useSyncExternalStore } from "react";
+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.
+const SETTLE = 300;
+const EMPTY = {
+    order: [],
+    page: 1,
+    perPage: 0,
+    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()`.
+ * Deleting rows from it hides them at once, sends one all-or-nothing batch,
+ * and puts them back if the server says no.
+ */
+export function viperPageOptions(options) {
+    const { viper, collection, query } = options;
+    const records = viper.collection(collection).records;
+    const compare = pageComparator(query.sort);
+    let info = EMPTY;
+    const listeners = new Set();
+    const rows = new Map();
+    const publish = (next) => {
+        info = next;
+        listeners.forEach((listener) => listener());
+    };
+    // Set while the sync runs: how to reload, and how to take in an event.
+    let live = null;
+    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;
+                }
+            })();
+            return loading;
+        };
+        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;
+                return;
+            }
+            const plan = planPage(event, {
+                rows: info.order.flatMap((id) => rows.get(id) ?? []),
+                page: info.page,
+                totalPages: info.totalPages,
+                sort: query.sort,
+                filter: query.filter,
+                deleted: query.deleted,
+                expand: query.expand,
+            });
+            if (plan.drop || plan.patch) {
+                begin();
+                if (plan.drop) {
+                    write({ type: "delete", key: plan.drop });
+                    rows.delete(plan.drop);
+                }
+                if (plan.patch) {
+                    write({ type: "update", value: plan.patch });
+                    rows.set(plan.patch.id, plan.patch);
+                }
+                commit();
+                let order = info.order.filter((id) => rows.has(id));
+                if (compare) {
+                    order = order
+                        .map((id) => rows.get(id))
+                        .sort(compare)
+                        .map((r) => r.id);
+                }
+                publish({ ...info, order });
+            }
+            if (plan.refetch)
+                loadSoon();
+        };
+        live = { load, take };
+        // Subscribe before loading, so nothing that happens in between is lost.
+        const off = viper.realtime.subscribe(collection, take);
+        const offResync = viper.realtime.onResync(() => void load());
+        void load();
+        return () => {
+            closed = true;
+            live = null;
+            clearTimeout(timer);
+            off();
+            offResync();
+        };
+    };
+    const utils = {
+        info: () => info,
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        refetch: async () => live?.load(),
+        apply: (event) => live?.take(event),
+    };
+    return {
+        id: `viper-page:${collection}:${JSON.stringify(query)}`,
+        getKey: (record) => record.id,
+        // Records are whole rows, so an update replaces rather than merges.
+        sync: { sync, rowUpdateMode: "full" },
+        utils,
+        onDelete: async ({ transaction }) => {
+            await deleteAll(viper, collection, transaction.mutations.map((m) => String(m.key)));
+            // The rows after them move up.
+            await live?.load();
+        },
+    };
+}
+// 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 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;
+}
+/**
+ * One server page of `collection` as a live list: `records.list` once, then
+ * realtime keeps it fresh, patching rows where it can. While a new `query`
+ * loads, the last page stays on screen.
+ *
+ * ```tsx
+ * const { items, totalPages } = useLivePage<Post>("posts", {
+ *   page, perPage: 30, sort: "-updated", filter,
+ * })
+ * ```
+ */
+export function useLivePage(collection, query) {
+    const viper = useViper();
+    const rows = viperPage(viper, collection, query);
+    // A page is a list, never a single row.
+    const live = useLiveQuery(rows);
+    const info = useSyncExternalStore(rows.utils.subscribe, rows.utils.info, rows.utils.info);
+    const byId = live.state;
+    const ready = live.isReady && !!byId;
+    // The same array until a row or the order changes, so memos below hold.
+    const items = useMemo(() => (ready ? info.order.flatMap((id) => byId.get(id) ?? []) : null), 
+    // live.data changes whenever a row does.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [ready, live.data, info]);
+    // The last page that loaded, shown while the next one does.
+    const [last, setLast] = useState(null);
+    if (items && last?.items !== items)
+        setLast({ items, info });
+    const shown = items ? { items, info } : last;
+    return {
+        items: shown?.items ?? null,
+        totalItems: shown?.info.totalItems ?? 0,
+        totalPages: shown?.info.totalPages ?? 0,
+        loading: !items,
+        error: live.isError ? new Error(`${collection} could not be loaded`) : null,
+        collection: rows,
+    };
+}

package/dist/db-query.d.ts

@@ -0,0 +1,44 @@
+import type { LoadSubsetOptions } from "@tanstack/db";
+/** What a translation produced: a filter (empty when none) and its fidelity. */
+export type Translated = {
+    /** A Viper filter; "" means "no filter", so every row matches. */
+    filter: string;
+    /** 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.
+ */
+export declare function toViperFilter(where: LoadSubsetOptions["where"]): Translated;
+/**
+ * A subset's `orderBy` as Viper's `sort` (`-created,title`), or null when a
+ * clause cannot be said. A partial sort would pick the wrong rows for a
+ * limit, so it is all or nothing.
+ */
+export declare function toViperSort(orderBy: LoadSubsetOptions["orderBy"]): string | null;
+/** One page request: which page, how many. */
+export type Window = {
+    page: number;
+    perPage: number;
+};
+/**
+ * The page that holds rows `offset` to `offset + limit`, or null when they
+ * are not a fit for one page (then the caller loads everything that matches).
+ *
+ * ponytail: paging is by offset (page/perPage), with `skipTotal` so the server
+ * runs no COUNT. It is not keyset: Viper's cursor is an opaque, signed
+ * token that only the previous page hands out, while TanStack DB asks for
+ * rows by `offset` (and cursor expressions on field values) with no token,
+ * and a page may be asked for out of order. Mapping an offset to a cursor
+ * would mean walking every page before it, which costs what OFFSET costs.
+ * Turning the cursor expressions into a filter is unsafe with ties and
+ * nulls. Revisit if Viper grows a token-free `after` filter.
+ */
+export declare function toWindow(offset: number, limit: number): Window | null;