@polyphron/viper-react 0.3.0 → 0.4.0

package/dist/loaded.js

@@ -0,0 +1,64 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+/** Makes an `Error` out of whatever a failed load threw. */
+export function asError(cause) {
+    return cause instanceof Error ? cause : new Error(String(cause));
+}
+/**
+ * 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 function useLoaded(subject, run) {
+    const [inFlight, setInFlight] = useState(0);
+    const [answer, setAnswer] = useState({ subject: null, run: null, data: null, error: null });
+    // The newest request's controller and promise: starting one replaces the
+    // last, and a replaced request waits for the one that replaced it.
+    const controller = useRef(null);
+    const newest = useRef(Promise.resolve());
+    const fetchNow = useCallback((forSubject, forRun) => {
+        controller.current?.abort();
+        const mine = new AbortController();
+        controller.current = mine;
+        const request = (async () => {
+            // After a tick, so starting from an effect sets no state in it.
+            await Promise.resolve();
+            setInFlight((n) => n + 1);
+            try {
+                const data = await forRun(mine.signal);
+                if (!mine.signal.aborted) {
+                    setAnswer({ subject: forSubject, run: forRun, data, error: null });
+                }
+            }
+            catch (error) {
+                if (!mine.signal.aborted) {
+                    setAnswer({ subject: forSubject, run: forRun, data: null, error });
+                }
+            }
+            finally {
+                setInFlight((n) => n - 1);
+            }
+        })();
+        newest.current = request;
+        return request.then(() => mine.signal.aborted ? newest.current : undefined);
+    }, []);
+    useEffect(() => {
+        void fetchNow(subject, run);
+        return () => controller.current?.abort();
+    }, [subject, run, fetchNow]);
+    const sameSubject = answer.run !== null && Object.is(answer.subject, subject);
+    const current = answer.run === run && inFlight === 0;
+    return {
+        // The last good data stays on screen while a reload is in flight.
+        data: sameSubject ? answer.data : null,
+        error: current ? answer.error : null,
+        loading: !sameSubject,
+        refreshing: !current,
+        reload: useCallback(() => fetchNow(subject, run), [fetchNow, subject, run]),
+    };
+}

package/dist/page-plan.js

@@ -1,3 +1,4 @@
+import { same } from "./db-shared.js";
 // 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"]);
@@ -50,10 +51,6 @@ export function pageComparator(sort) {
         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.

package/dist/records.d.ts

@@ -1,18 +1,5 @@
 import type { ListOptions, ListResult, RecordModel } from "@polyphron/viper-client";
-export type Query<T> = {
-    data: T | null;
-    error: unknown;
-    /**
-     * 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;
-};
+import { type Query } from "./loaded.js";
 export type RecordsOptions = ListOptions & {
     /** Re-fetch when anything in the collection changes. Off by default. */
     live?: boolean;

package/dist/records.js

@@ -1,4 +1,5 @@
-import { useCallback, useEffect, useState } from "react";
+import { useCallback, useEffect } from "react";
+import { useLoaded } from "./loaded.js";
 import { useViper } from "./provider.js";
 import { useRealtime } from "./realtime.js";
 /**
@@ -13,7 +14,7 @@ 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(collection, useCallback((signal) => viper
+    const query = useLoaded(collection, useCallback((signal) => viper
         .collection(collection)
         .list({ ...JSON.parse(key), signal }), [viper, collection, key]));
     useLiveReload(live, collection, query.reload, viper);
@@ -23,7 +24,7 @@ export function useRecords(collection, options = {}) {
 export function useRecord(collection, id, options = {}) {
     const viper = useViper();
     const { live = false, expand } = options;
-    const query = useFetch(
+    const query = useLoaded(
     // A different record must never show the last one's data.
     `${collection}/${id ?? ""}`, useCallback((signal) => id
         ? viper.collection(collection).view(id, { expand, signal })
@@ -31,42 +32,6 @@ export function useRecord(collection, id, options = {}) {
     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.
-//
-// `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({ subject: "", run: null, attempt: -1, data: null, error: null });
-    useEffect(() => {
-        const controller = new AbortController();
-        run(controller.signal).then((data) => {
-            if (!controller.signal.aborted) {
-                setAnswer({ subject, run, attempt, data, error: null });
-            }
-        }, (error) => {
-            if (!controller.signal.aborted) {
-                setAnswer({ subject, run, attempt, data: null, error });
-            }
-        });
-        return () => controller.abort();
-    }, [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: sameSubject ? answer.data : null,
-        error: current ? answer.error : null,
-        loading: !sameSubject,
-        refreshing: !current,
-        reload: useCallback(() => setAttempt((n) => n + 1), []),
-    };
-}
 // 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

package/dist/runs.d.ts

@@ -3,11 +3,11 @@ export type RunState<T> = {
     /** The run as last read, or null before the first answer. */
     data: WorkflowRun<T> | null;
     error: unknown;
-    /** True from the start until the run is done or failed, or can't be read. */
+    /** True from the start until the run has ended, or can't be read. */
     pending: boolean;
 };
 /**
- * Watches a background workflow's run until it's done or failed, reading
+ * Watches a background workflow's run until it's done, failed or cancelled, reading
  * it every `every` milliseconds (a second by default). Pass the
  * `StartedRun` its call returned; nothing is read while it's empty.
  *

package/dist/runs.js

@@ -1,7 +1,11 @@
 import { useEffect, useState } from "react";
 import { useViper } from "./provider.js";
+/** A run is still going while it runs or waits; done, failed and cancelled are final. */
+function unfinished(run) {
+    return run.status === "running" || run.status === "waiting";
+}
 /**
- * Watches a background workflow's run until it's done or failed, reading
+ * Watches a background workflow's run until it's done, failed or cancelled, reading
  * it every `every` milliseconds (a second by default). Pass the
  * `StartedRun` its call returned; nothing is read while it's empty.
  *
@@ -29,7 +33,7 @@ export function useRun(name, started, options = {}) {
             try {
                 const data = await viper.workflows.run(name, { run, token }, { signal: controller.signal });
                 setState({ key, data, error: null });
-                if (data.status !== "done" && data.status !== "failed") {
+                if (unfinished(data)) {
                     timer = setTimeout(() => void read(), every);
                 }
             }
@@ -50,9 +54,6 @@ export function useRun(name, started, options = {}) {
     return {
         data,
         error,
-        pending: run !== undefined &&
-            !error &&
-            data?.status !== "done" &&
-            data?.status !== "failed",
+        pending: run !== undefined && !error && (data === null || unfinished(data)),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyphron/viper-react",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "React provider and hooks for the Viper app API.",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@polyphron/viper-client": "^0.3.0",
+    "@polyphron/viper-client": "^0.4.0",
     "@tanstack/db": "0.9.2",
     "@tanstack/react-db": "0.4.1",
     "react": "^18.3.0 || ^19.0.0"