@polyphron/viper-react 0.1.0

package/README.md

@@ -0,0 +1,98 @@
+# @polyphron/viper-react
+
+React provider and hooks for a [Viper](../../../README.md) backend. A thin
+layer over [`@polyphron/viper-client`](../client/README.md) — everything the client can
+do is still there, `viper.` and all.
+
+```sh
+npm install @polyphron/viper-react
+```
+
+React 18.3 or 19.
+
+## Use it
+
+Wrap the app once:
+
+```tsx
+import { ViperProvider } from "@polyphron/viper-react"
+
+createRoot(document.getElementById("root")!).render(
+  <ViperProvider url="http://localhost:8090" project="<project id>">
+    <App />
+  </ViperProvider>
+)
+```
+
+Then read records:
+
+```tsx
+import { useRecords } from "@polyphron/viper-react"
+
+function Posts() {
+  const { data, loading, error } = useRecords("posts", {
+    sort: "-created",
+    perPage: 20,
+    live: true, // re-fetch whenever a post changes
+  })
+
+  if (loading) return <p>Loading…</p>
+  if (error) return <p>Something went wrong.</p>
+
+  return <ul>{data?.items.map((p) => <li key={p.id}>{String(p.title)}</li>)}</ul>
+}
+```
+
+Log in:
+
+```tsx
+import { useAuth } from "@polyphron/viper-react"
+
+function SignIn() {
+  const { user, auth } = useAuth("users")
+
+  if (user) return <button onClick={() => auth.logout()}>Sign out</button>
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault()
+        const data = new FormData(e.currentTarget)
+        auth.loginWithPassword(String(data.get("email")), String(data.get("password")))
+      }}
+    >
+      <input name="email" type="email" />
+      <input name="password" type="password" />
+      <button>Sign in</button>
+    </form>
+  )
+}
+```
+
+## The hooks
+
+| 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 }` |
+| `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 |
+| `useRealtime(topics, onEvent)` | Watch changes yourself; returns the connection status |
+| `useRealtimeStatus()` | `"closed"`, `"connecting"` or `"live"` |
+
+`useRecords` and `useRecord` take `live: true` to re-fetch on every change to
+what they are showing. The last good data stays on screen while a reload is in
+flight, so lists don't flash.
+
+## Writes
+
+There is no mutation hook: the client's own methods are already promises.
+
+```tsx
+const viper = useViper()
+const { reload } = useRecords("posts")
+
+await viper.collection("posts").create({ title: "Hello" })
+reload() // or pass live: true and let realtime do it
+```

package/dist/auth.d.ts

@@ -0,0 +1,17 @@
+import type { AuthService, RecordModel, Session } from "@polyphron/viper-client";
+/** The current session, re-rendering on login, logout and refresh. */
+export declare function useSession(): Session | null;
+/** The logged-in user, or null when signed out. */
+export declare function useUser<T extends RecordModel = RecordModel>(): T | null;
+/**
+ * The logins of one auth collection, plus the user they belong to.
+ *
+ * ```tsx
+ * const { user, auth } = useAuth("users")
+ * await auth.loginWithPassword(email, password)
+ * ```
+ */
+export declare function useAuth<T extends RecordModel = RecordModel>(collection: string): {
+    user: T | null;
+    auth: AuthService<T>;
+};

package/dist/auth.js

@@ -0,0 +1,24 @@
+import { useSyncExternalStore } from "react";
+import { useViper } from "./provider.js";
+/** The current session, re-rendering on login, logout and refresh. */
+export function useSession() {
+    const viper = useViper();
+    return useSyncExternalStore((listener) => viper.onSessionChange(listener), () => viper.session, () => null);
+}
+/** The logged-in user, or null when signed out. */
+export function useUser() {
+    return useSession()?.record ?? null;
+}
+/**
+ * The logins of one auth collection, plus the user they belong to.
+ *
+ * ```tsx
+ * const { user, auth } = useAuth("users")
+ * await auth.loginWithPassword(email, password)
+ * ```
+ */
+export function useAuth(collection) {
+    const viper = useViper();
+    const user = useUser();
+    return { user, auth: viper.collection(collection).auth };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { ViperProvider, useViper, type ViperProviderProps } from "./provider.js";
+export { useAuth, useSession, useUser } from "./auth.js";
+export { useRealtime, useRealtimeStatus } from "./realtime.js";
+export { useRecord, useRecords, type Query, type RecordsOptions, } from "./records.js";
+export { Viper, ViperError, fieldError, memoryStorage, type ListOptions, type ListResult, type RealtimeEvent, type RealtimeStatus, type RecordInput, type RecordModel, type Session, type ViperOptions, } from "@polyphron/viper-client";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { ViperProvider, useViper } from "./provider.js";
+export { useAuth, useSession, useUser } from "./auth.js";
+export { useRealtime, useRealtimeStatus } from "./realtime.js";
+export { useRecord, useRecords, } from "./records.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/provider.d.ts

@@ -0,0 +1,20 @@
+import { Viper, type ViperOptions } from "@polyphron/viper-client";
+import { type ReactNode } from "react";
+export type ViperProviderProps = {
+    children: ReactNode;
+} & ({
+    /** An already-built client. Use this when the app makes one at start-up. */
+    client: Viper;
+} | ViperOptions);
+/**
+ * Puts a Viper client in context so every hook below can reach it.
+ *
+ * ```tsx
+ * <ViperProvider url="http://localhost:8090" project="abc123">
+ *   <App />
+ * </ViperProvider>
+ * ```
+ */
+export declare function ViperProvider(props: ViperProviderProps): import("react").JSX.Element;
+/** The client from the nearest ViperProvider. */
+export declare function useViper(): Viper;

package/dist/provider.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Viper } from "@polyphron/viper-client";
+import { createContext, useContext, useState } from "react";
+const ViperContext = createContext(null);
+/**
+ * Puts a Viper client in context so every hook below can reach it.
+ *
+ * ```tsx
+ * <ViperProvider url="http://localhost:8090" project="abc123">
+ *   <App />
+ * </ViperProvider>
+ * ```
+ */
+export function ViperProvider(props) {
+    const { children, ...rest } = props;
+    // A client owns a session and a WebSocket, so it is built once and kept.
+    // The options are read on the first render only, like any constructor's.
+    const [built] = useState(() => "client" in rest ? null : new Viper(rest));
+    const client = "client" in rest ? rest.client : built;
+    return _jsx(ViperContext, { value: client, children: children });
+}
+/** The client from the nearest ViperProvider. */
+export function useViper() {
+    const client = useContext(ViperContext);
+    if (!client) {
+        throw new Error("useViper must be used inside a <ViperProvider>.");
+    }
+    return client;
+}

package/dist/realtime.d.ts

@@ -0,0 +1,10 @@
+import type { 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.
+ *
+ * Returns the connection status. The subscription is dropped on unmount.
+ */
+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;

package/dist/realtime.js

@@ -0,0 +1,25 @@
+import { useEffect, useRef, useSyncExternalStore } from "react";
+import { useViper } from "./provider.js";
+/**
+ * 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.
+ *
+ * Returns the connection status. The subscription is dropped on unmount.
+ */
+export function useRealtime(topics, onEvent) {
+    const viper = useViper();
+    // Keep the latest callback without resubscribing when it changes.
+    const onEventRef = useRef(onEvent);
+    useEffect(() => {
+        onEventRef.current = onEvent;
+    });
+    // A new array literal every render would resubscribe every render.
+    const key = (Array.isArray(topics) ? topics : [topics]).join("\n");
+    useEffect(() => viper.realtime.subscribe(key.split("\n"), (e) => onEventRef.current(e)), [viper, key]);
+    return useRealtimeStatus();
+}
+/** The realtime connection status, on its own. */
+export function useRealtimeStatus() {
+    const viper = useViper();
+    return useSyncExternalStore((listener) => viper.realtime.onStatus(listener), () => viper.realtime.status, () => "closed");
+}

package/dist/records.d.ts

@@ -0,0 +1,26 @@
+import type { ListOptions, ListResult, RecordModel } from "@polyphron/viper-client";
+export type Query<T> = {
+    data: T | null;
+    error: unknown;
+    /** True until the first answer arrives, and again during a `reload`. */
+    loading: boolean;
+    /** Fetches again now. */
+    reload: () => void;
+};
+export type RecordsOptions = ListOptions & {
+    /** Re-fetch when anything in the collection changes. Off by default. */
+    live?: boolean;
+};
+/**
+ * One page of records, re-fetched when the options change.
+ *
+ * ```tsx
+ * const { data, loading } = useRecords("posts", { sort: "-created", live: true })
+ * ```
+ */
+export declare function useRecords<T extends RecordModel = RecordModel>(collection: string, options?: RecordsOptions): Query<ListResult<T>>;
+/** One record, re-fetched when the id changes. */
+export declare function useRecord<T extends RecordModel = RecordModel>(collection: string, id: string | undefined, options?: {
+    expand?: string;
+    live?: boolean;
+}): Query<T>;

package/dist/records.js

@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useState } from "react";
+import { useViper } from "./provider.js";
+import { useRealtime } from "./realtime.js";
+/**
+ * One page of records, re-fetched when the options change.
+ *
+ * ```tsx
+ * const { data, loading } = useRecords("posts", { sort: "-created", live: true })
+ * ```
+ */
+export function useRecords(collection, options = {}) {
+    const viper = useViper();
+    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
+        .collection(collection)
+        .list({ ...JSON.parse(key), signal }), [viper, collection, key]));
+    useLiveReload(live, collection, query.reload);
+    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
+        ? viper.collection(collection).view(id, { expand, signal })
+        : Promise.resolve(null), [viper, collection, id, expand]));
+    useLiveReload(live && Boolean(id), `${collection}/${id}`, query.reload);
+    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) {
+    const [attempt, setAttempt] = useState(0);
+    const [answer, setAnswer] = useState({ 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 });
+            }
+        }, (error) => {
+            if (!controller.signal.aborted) {
+                setAnswer({ run, attempt, data: null, error });
+            }
+        });
+        return () => controller.abort();
+    }, [run, attempt]);
+    const current = answer.run === run && answer.attempt === attempt;
+    return {
+        // The last good data stays on screen while a reload is in flight.
+        data: answer.data,
+        error: current ? answer.error : null,
+        loading: !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) {
+    useRealtime(live ? topic : [], reload);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@polyphron/viper-react",
+  "version": "0.1.0",
+  "description": "React provider and hooks for the Viper app API.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build && node ../publish-exports.mjs pre",
+    "postpack": "node ../publish-exports.mjs post",
+    "lint": "eslint",
+    "format": "prettier --write \"**/*.{ts,tsx}\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@polyphron/viper-client": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^18.3.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10",
+    "@types/node": "^24",
+    "@types/react": "^19",
+    "eslint": "^10",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "react": "^19.2.8",
+    "typescript": "~6",
+    "typescript-eslint": "^8"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}