@polyphron/viper-react 0.4.0 → 0.5.0

package/README.md

@@ -90,12 +90,11 @@ to refresh the email shown by `useUser()`.
 | `useAuth(collection)` | `{ user, auth }` for an auth collection |
 | `useSession()` / `useUser()` | The session / the logged-in user, re-rendering on change |
 | `useSessionOf(client, read)` | The same for any client with `onSessionChange` (the admin client, say); `read` returns what to show, like `() => admin.user` |
-| `useAuthMethods({ collection?, enabled? })` | How to sign in here (methods, sign-up, sub-app branding), or `null` while it loads |
+| `useAuthMethods({ collection?, enabled? })` | How to sign in here (methods, sign-up, project branding), or `null` while it loads |
 | `useSessions()` | The user's active sessions: `{ sessions, error, loading, refresh, revoke, logoutEverywhere }` |
 | `useInvites()` | Invites the user sent: `{ invites, error, loading, refresh, invite, cancel }` |
 | `useTenants(name)` | The user's memberships of tenant collection `name`; never the last user's list |
 | `useRun(name, started, { every? })` | Follows a background workflow's run until it ends: `{ data, error, pending }` |
-| `useAppIdentity()` / `useAppManagement()` | The user's app role and ceilings; opt-in role and member edits. Both give `{ identity, error, loading, refresh }`, management adds `roles`, `members` and the writes. A 403 on the management calls keeps `identity` |
 | `useRealtime(topics, onEvent)` | Watch changes yourself; returns the connection status |
 | `useRealtimeStatus()` | `"closed"`, `"connecting"` or `"live"` |
 
@@ -113,7 +112,7 @@ flight, so lists don't flash.
 - 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.
 
-`useSessions`, `useInvites` and `useAppIdentity` all give `loading` (true
+`useSessions` and `useInvites` both give `loading` (true
 until the first answer for this user), `error` (an `Error` or `null`) and
 `refresh()`, which resolves once the new answer is in. They key their state on
 the signed-in user, so after a user switch you never see the last user's data.

package/dist/auth.d.ts

@@ -50,15 +50,15 @@ export declare function useAuth<T extends RecordModel = RecordModel>(collection?
     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
+ * How to sign in here: the ways on offer, sign-up, and the project's
+ * branding. Null while
  * it loads, and when the load fails: the sign-in calls report their own
  * errors. Name an auth `collection` when the project has several, and pass
  * `enabled: false` to hold the request back. For a sign-in page.
  *
  * ```tsx
  * const methods = useAuthMethods()
- * return <h1>{methods?.app?.branding.name ?? methods?.app?.name}</h1>
+ * return <h1>{methods?.branding?.name}</h1>
  * ```
  */
 export declare function useAuthMethods(options?: {

package/dist/auth.js

@@ -81,15 +81,15 @@ export function useAuth(collection) {
     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
+ * How to sign in here: the ways on offer, sign-up, and the project's
+ * branding. Null while
  * it loads, and when the load fails: the sign-in calls report their own
  * errors. Name an auth `collection` when the project has several, and pass
  * `enabled: false` to hold the request back. For a sign-in page.
  *
  * ```tsx
  * const methods = useAuthMethods()
- * return <h1>{methods?.app?.branding.name ?? methods?.app?.name}</h1>
+ * return <h1>{methods?.branding?.name}</h1>
  * ```
  */
 export function useAuthMethods(options = {}) {

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { ViperProvider, useViper, type ViperProviderProps } from "./provider.js";
 export { useAuth, useAuthMethods, useSession, useSessionOf, useInvites, useSessions, useTenants, useUser, } from "./auth.js";
-export { useRealtime, useRealtimeStatus } from "./realtime.js";
+export { usePresence, useRealtime, useRealtimeStatus } from "./realtime.js";
 export { useLoaded, type Query } from "./loaded.js";
-export { useRecord, useRecords, type RecordsOptions } from "./records.js";
+export { useAggregate, useRecord, useRecords, type AggregateHookOptions, type RecordsOptions, } from "./records.js";
+export { useUpload, type UploadState } from "./upload.js";
 export { useRun, type RunState } from "./runs.js";
-export { useAppIdentity, useAppManagement } from "./identity.js";
-export { type AppIdentity, type AppMember, type AppRole, type AppLevel, Viper, ViperError, fieldError, memoryStorage, type ListOptions, type ListResult, type RealtimeEvent, type RealtimeStatus, type RecordInput, type RecordModel, type Session, type UserSession, type StartedRun, type ViperOptions, type WorkflowRun, } from "@polyphron/viper-client";
+export { Viper, ViperError, fieldError, memoryStorage, type AggregateOptions, type AggregateResult, type AggregateRow, type ListOptions, type ListResult, type PresenceMember, type RealtimeEvent, type RealtimeStatus, type Room, type RoomListener, type RecordInput, type RecordModel, type Session, type UserSession, type StartedRun, type ViperOptions, type WorkflowRun, } from "@polyphron/viper-client";

package/dist/index.js

@@ -1,9 +1,9 @@
 export { ViperProvider, useViper } from "./provider.js";
 export { useAuth, useAuthMethods, useSession, useSessionOf, useInvites, useSessions, useTenants, useUser, } from "./auth.js";
-export { useRealtime, useRealtimeStatus } from "./realtime.js";
+export { usePresence, useRealtime, useRealtimeStatus } from "./realtime.js";
 export { useLoaded } from "./loaded.js";
-export { useRecord, useRecords } from "./records.js";
+export { useAggregate, useRecord, useRecords, } from "./records.js";
+export { useUpload } from "./upload.js";
 export { useRun } from "./runs.js";
-export { useAppIdentity, useAppManagement } from "./identity.js";
 // Re-exported so an app only needs @polyphron/viper-react in its imports.
 export { Viper, ViperError, fieldError, memoryStorage, } from "@polyphron/viper-client";

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,4 +1,4 @@
-import type { ListOptions, ListResult, RecordModel } from "@polyphron/viper-client";
+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. */
@@ -12,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

@@ -20,15 +20,34 @@ export function useRecords(collection, options = {}) {
     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 { 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;
 }

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.4.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.4.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"