@polyphron/viper-react 0.1.2 → 0.2.1

package/dist/page-plan.js

@@ -0,0 +1,102 @@
+// Sort fields the browser orders just as Postgres does: times compared as
+// times, and ids (a-z and 0-9) compared as text.
+const TIMES = new Set(["created", "updated"]);
+/**
+ * The sort as the server applies it, with its tie-breaker. The server
+ * breaks ties on `id` ascending, or sorts `-created,-id` when none is given.
+ */
+function sortKeys(sort) {
+    const given = (sort ?? "")
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (!given.length) {
+        return [
+            { field: "created", desc: true },
+            { field: "id", desc: true },
+        ];
+    }
+    return [
+        ...given.map((s) => ({
+            field: s.replace(/^[-+]/, ""),
+            desc: s.startsWith("-"),
+        })),
+        { field: "id", desc: false },
+    ];
+}
+/**
+ * Orders rows as the server does for `sort`, or null when the sort has a
+ * field the browser can't order the same way (text in the database's
+ * collation, numbers, lists).
+ */
+export function pageComparator(sort) {
+    const keys = sortKeys(sort);
+    if (!keys.every((k) => k.field === "id" || TIMES.has(k.field)))
+        return null;
+    return (a, b) => {
+        for (const { field, desc } of keys) {
+            const x = String(a[field]);
+            const y = String(b[field]);
+            const order = field === "id"
+                ? x < y
+                    ? -1
+                    : x > y
+                        ? 1
+                        : 0
+                : Date.parse(x) - Date.parse(y);
+            if (order)
+                return desc ? -order : order;
+        }
+        return 0;
+    };
+}
+// True when two field values are the same, lists and objects included.
+function same(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+/** What `event` does to `page`. */
+export function planPage(event, page) {
+    // A new row, or a view that changed: only the server knows where it goes.
+    if (event.action === "create" || event.action === "refresh") {
+        return { refetch: true };
+    }
+    const { record } = event;
+    const old = page.rows.find((r) => r.id === record.id);
+    // The rows after it move up, and the count changes.
+    if (event.action === "delete") {
+        return { drop: old ? record.id : undefined, refetch: true };
+    }
+    // A row that isn't on the page can only move onto it if its sort values
+    // changed. Its old values aren't known, so only a sort on fields an
+    // update never changes (created, id) is safe to skip.
+    if (!old) {
+        const fixed = sortKeys(page.sort).every((k) => k.field === "created" || k.field === "id");
+        return { refetch: !fixed || !!page.filter || !!page.deleted };
+    }
+    // A change carries no `expand`, so the old one stays while the links do.
+    const relations = (page.expand ?? "")
+        .split(",")
+        .map((path) => path.trim().split(".")[0])
+        .filter(Boolean);
+    const relinked = relations.some((f) => !same(old[f], record[f]));
+    const patch = relinked ? record : { ...record, expand: old.expand };
+    // A filter or the Deleted view may now leave it out, and the filter can't
+    // be run here.
+    if (page.filter || page.deleted || relinked)
+        return { patch, refetch: true };
+    const moved = sortKeys(page.sort).some((k) => !same(old[k.field], record[k.field]));
+    if (!moved)
+        return { patch, refetch: false };
+    // It moved. Order the page here, and ask again only if it may now belong
+    // on the page before or after this one.
+    const compare = pageComparator(page.sort);
+    if (!compare)
+        return { patch, refetch: true };
+    const rows = page.rows
+        .map((r) => (r.id === record.id ? patch : r))
+        .sort(compare);
+    const at = rows.findIndex((r) => r.id === record.id);
+    const more = page.totalPages < 0 || page.page < page.totalPages;
+    const leaves = (at === 0 && page.page > 1) || (at === rows.length - 1 && more);
+    return { patch, refetch: leaves };
+}

package/dist/records.d.ts

@@ -2,8 +2,14 @@ import type { ListOptions, ListResult, RecordModel } from "@polyphron/viper-clie
 export type Query<T> = {
     data: T | null;
     error: unknown;
-    /** True until the first answer arrives, and again during a `reload`. */
+    /**
+     * True until the first answer arrives for what is being shown (a new
+     * collection, or a new record id). A `reload` or a live update does not set
+     * it again, so the last data stays on screen; see `refreshing`.
+     */
     loading: boolean;
+    /** True whenever a request is in flight, first load and reloads included. */
+    refreshing: boolean;
     /** Fetches again now. */
     reload: () => void;
 };

package/dist/records.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyphron/viper-react",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "React provider and hooks for the Viper app API.",
   "license": "MIT",
   "type": "module",
@@ -12,6 +12,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./db": {
+      "types": "./dist/db.d.ts",
+      "default": "./dist/db.js"
     }
   },
   "publishConfig": {
@@ -25,14 +29,17 @@
     "format": "prettier --write \"**/*.{ts,tsx}\"",
     "typecheck": "tsc --noEmit"
   },
-  "dependencies": {
-    "@polyphron/viper-client": "^0.1.0"
-  },
   "peerDependencies": {
+    "@polyphron/viper-client": "^0.2.0",
+    "@tanstack/db": "0.9.2",
+    "@tanstack/react-db": "0.4.1",
     "react": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
     "@eslint/js": "^10",
+    "@polyphron/viper-client": "*",
+    "@tanstack/db": "0.9.2",
+    "@tanstack/react-db": "0.4.1",
     "@types/node": "^24",
     "@types/react": "^19",
     "eslint": "^10",
@@ -43,5 +50,13 @@
   },
   "engines": {
     "node": ">=20"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/db": {
+      "optional": true
+    },
+    "@tanstack/react-db": {
+      "optional": true
+    }
   }
 }