@polyphron/viper-react 0.3.0 → 0.5.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/realtime.d.ts

@@ -1,4 +1,4 @@
-import type { RealtimeEvent, RealtimeStatus, RecordModel } from "@polyphron/viper-client";
+import type { PresenceMember, RealtimeEvent, RealtimeStatus, RecordModel } from "@polyphron/viper-client";
 /**
  * Watches topics and calls `onEvent` for each change. A topic is a collection
  * name for every record in it (`posts`), or `collection/id` for one record.
@@ -8,3 +8,14 @@ import type { RealtimeEvent, RealtimeStatus, RecordModel } from "@polyphron/vipe
 export declare function useRealtime<T extends RecordModel = RecordModel>(topics: string | string[], onEvent: (event: RealtimeEvent<T>) => void): RealtimeStatus;
 /** The realtime connection status, on its own. */
 export declare function useRealtimeStatus(): RealtimeStatus;
+/**
+ * Joins a room (`posts` or `posts/abc123`) while mounted and returns who is
+ * in it. `state` is what others see about you; a new value is sent when its
+ * JSON changes. `onBroadcast` hears what the others send with `broadcast`.
+ */
+export declare function usePresence<S = unknown, D = unknown>(room: string, state?: S, onBroadcast?: (data: D, from: PresenceMember<S>) => void): {
+    members: PresenceMember<S>[];
+    me: string;
+    error: string;
+    broadcast: (data: D) => void;
+};

package/dist/realtime.js

@@ -1,4 +1,4 @@
-import { useEffect, useRef, useSyncExternalStore } from "react";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { useViper } from "./provider.js";
 /**
  * Watches topics and calls `onEvent` for each change. A topic is a collection
@@ -23,3 +23,52 @@ export function useRealtimeStatus() {
     const viper = useViper();
     return useSyncExternalStore((listener) => viper.realtime.onStatus(listener), () => viper.realtime.status, () => "closed");
 }
+/**
+ * Joins a room (`posts` or `posts/abc123`) while mounted and returns who is
+ * in it. `state` is what others see about you; a new value is sent when its
+ * JSON changes. `onBroadcast` hears what the others send with `broadcast`.
+ */
+export function usePresence(room, state, onBroadcast) {
+    const viper = useViper();
+    const [members, setMembers] = useState([]);
+    const [error, setError] = useState("");
+    const [joined, setJoined] = useState(null);
+    const onBroadcastRef = useRef(onBroadcast);
+    useEffect(() => {
+        onBroadcastRef.current = onBroadcast;
+    });
+    // The state as JSON, so a new object with the same values sends nothing.
+    const stateKey = JSON.stringify(state ?? null);
+    const stateRef = useRef(state);
+    useEffect(() => {
+        stateRef.current = state;
+    });
+    useEffect(() => {
+        if (!room)
+            return;
+        const r = viper.realtime.join(room, {
+            onPresence: (m) => {
+                setMembers(m);
+                setError("");
+            },
+            onBroadcast: (data, from) => onBroadcastRef.current?.(data, from),
+            onError: setError,
+        }, stateRef.current);
+        setJoined(r);
+        return () => {
+            r.leave();
+            setJoined(null);
+            setMembers([]);
+        };
+    }, [viper, room]);
+    useEffect(() => {
+        if (joined && stateRef.current !== undefined)
+            joined.track(stateRef.current);
+    }, [joined, stateKey]);
+    return {
+        members,
+        me: joined?.me ?? "",
+        error,
+        broadcast: (data) => joined?.broadcast(data),
+    };
+}

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 { AggregateOptions, AggregateResult, ListOptions, ListResult, RecordModel } from "@polyphron/viper-client";
+import { type Query } from "./loaded.js";
 export type RecordsOptions = ListOptions & {
     /** Re-fetch when anything in the collection changes. Off by default. */
     live?: boolean;
@@ -25,8 +12,22 @@ export type RecordsOptions = ListOptions & {
  * ```
  */
 export declare function useRecords<T extends RecordModel = RecordModel>(collection: string, options?: RecordsOptions): Query<ListResult<T>>;
+export type AggregateHookOptions = AggregateOptions & {
+    /** Re-fetch when anything in the collection changes. Off by default. */
+    live?: boolean;
+};
+/**
+ * Counts and sums of a collection, grouped by fields or time buckets,
+ * re-fetched when the options change.
+ *
+ * ```tsx
+ * const { data } = useAggregate("orders", { group: "created:day", agg: "count,sum:amount" })
+ * ```
+ */
+export declare function useAggregate(collection: string, options?: AggregateHookOptions): Query<AggregateResult>;
 /** One record, re-fetched when the id changes. */
 export declare function useRecord<T extends RecordModel = RecordModel>(collection: string, id: string | undefined, options?: {
     expand?: string;
+    fields?: string;
     live?: boolean;
 }): Query<T>;

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,60 +14,43 @@ 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);
     return query;
 }
+/**
+ * Counts and sums of a collection, grouped by fields or time buckets,
+ * re-fetched when the options change.
+ *
+ * ```tsx
+ * const { data } = useAggregate("orders", { group: "created:day", agg: "count,sum:amount" })
+ * ```
+ */
+export function useAggregate(collection, options = {}) {
+    const viper = useViper();
+    const { live = false, ...aggregate } = options;
+    // Options are a fresh object every render; compare them by value.
+    const key = JSON.stringify(aggregate);
+    const query = useLoaded(`${collection}:aggregate`, useCallback((signal) => viper
+        .collection(collection)
+        .aggregate({ ...JSON.parse(key), signal }), [viper, collection, key]));
+    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(
+    const { live = false, expand, fields } = options;
+    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 })
-        : Promise.resolve(null), [viper, collection, id, expand]));
+        ? viper.collection(collection).view(id, { expand, fields, signal })
+        : Promise.resolve(null), [viper, collection, id, expand, fields]));
     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/dist/upload.d.ts

@@ -0,0 +1,24 @@
+import type { RecordModel, UploadLargeOptions, ViperError } from "@polyphron/viper-client";
+/** Where a big upload is: what `useUpload` returns next to `upload`. */
+export type UploadState<T extends RecordModel> = {
+    /** Sends the file; resolves with the record, rejects on failure. */
+    upload: (id: string, field: string, file: Blob, options?: Omit<UploadLargeOptions, "onProgress" | "signal">) => Promise<T>;
+    /** Stops the upload in flight. */
+    cancel: () => void;
+    /** 0 to 1; stays at 1 once done. */
+    progress: number;
+    uploading: boolean;
+    error: ViperError | Error | null;
+    /** The record the last finished upload returned. */
+    data: T | null;
+};
+/**
+ * A big file into a file field, in parts or straight to the bucket (the
+ * project's big-uploads switch must be on), with progress.
+ *
+ * ```tsx
+ * const { upload, progress } = useUpload("videos")
+ * await upload(record.id, "file", input.files[0])
+ * ```
+ */
+export declare function useUpload<T extends RecordModel = RecordModel>(collection: string): UploadState<T>;

package/dist/upload.js

@@ -0,0 +1,44 @@
+import { useCallback, useRef, useState } from "react";
+import { useViper } from "./provider.js";
+/**
+ * A big file into a file field, in parts or straight to the bucket (the
+ * project's big-uploads switch must be on), with progress.
+ *
+ * ```tsx
+ * const { upload, progress } = useUpload("videos")
+ * await upload(record.id, "file", input.files[0])
+ * ```
+ */
+export function useUpload(collection) {
+    const viper = useViper();
+    const [progress, setProgress] = useState(0);
+    const [uploading, setUploading] = useState(false);
+    const [error, setError] = useState(null);
+    const [data, setData] = useState(null);
+    const abort = useRef(null);
+    const upload = useCallback(async (id, field, file, options = {}) => {
+        abort.current = new AbortController();
+        setUploading(true);
+        setProgress(0);
+        setError(null);
+        try {
+            const record = await viper.collection(collection).uploadLarge(id, field, file, {
+                ...options,
+                signal: abort.current.signal,
+                onProgress: (sent, total) => setProgress(total ? sent / total : 1),
+            });
+            setProgress(1);
+            setData(record);
+            return record;
+        }
+        catch (e) {
+            setError(e);
+            throw e;
+        }
+        finally {
+            setUploading(false);
+        }
+    }, [viper, collection]);
+    const cancel = useCallback(() => abort.current?.abort(), []);
+    return { upload, cancel, progress, uploading, error, data };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@polyphron/viper-react",
-  "version": "0.3.0",
+  "version": "0.5.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.5.0",
     "@tanstack/db": "0.9.2",
     "@tanstack/react-db": "0.4.1",
     "react": "^18.3.0 || ^19.0.0"