@velajs/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kauan Guesser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/context.d.ts

@@ -0,0 +1,11 @@
+import { createElement } from 'react';
+import type { ReactNode } from 'react';
+import type { LiveClient } from '@velajs/client';
+import type { LiveContract } from '@velajs/client';
+export interface LiveProviderProps {
+    client: LiveClient<LiveContract>;
+    children?: ReactNode;
+}
+/** Provides the LiveClient to the hook tree. `createElement`-based — no JSX toolchain required. */
+export declare function LiveProvider(props: LiveProviderProps): ReturnType<typeof createElement>;
+export declare function useLiveClient<C extends LiveContract = LiveContract>(): LiveClient<C>;

package/dist/context.js

@@ -0,0 +1,17 @@
+import { createContext, createElement, useContext } from "react";
+// Deliberately `any`-typed inside the context: the contract generic is
+// re-applied at the useLiveClient() boundary. One provider serves any app.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const LiveClientContext = createContext(null);
+/** Provides the LiveClient to the hook tree. `createElement`-based — no JSX toolchain required. */ export function LiveProvider(props) {
+    return createElement(LiveClientContext.Provider, {
+        value: props.client
+    }, props.children);
+}
+export function useLiveClient() {
+    const client = useContext(LiveClientContext);
+    if (!client) {
+        throw new Error('useLiveClient: no LiveClient in context — wrap the tree in <LiveProvider client={…}>.');
+    }
+    return client;
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { LiveProvider, useLiveClient } from './context';
+export type { LiveProviderProps } from './context';
+export { useLiveQuery } from './use-live-query';
+export type { UseLiveQueryOptions } from './use-live-query';
+export { useLiveMutation } from './use-live-mutation';
+export type { UseLiveMutationResult } from './use-live-mutation';
+export { useConnectionStatus } from './use-connection-status';
+export { usePresence } from './use-presence';
+export type { UsePresenceOptions } from './use-presence';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { LiveProvider, useLiveClient } from "./context.js";
+export { useLiveQuery } from "./use-live-query.js";
+export { useLiveMutation } from "./use-live-mutation.js";
+export { useConnectionStatus } from "./use-connection-status.js";
+export { usePresence } from "./use-presence.js";

package/dist/use-connection-status.d.ts

@@ -0,0 +1,3 @@
+import type { ConnectionStatus } from '@velajs/client';
+/** The client's aggregate connection status, live. */
+export declare function useConnectionStatus(): ConnectionStatus;

package/dist/use-connection-status.js

@@ -0,0 +1,12 @@
+import { useCallback, useSyncExternalStore } from "react";
+import { useLiveClient } from "./context.js";
+/** The client's aggregate connection status, live. */ export function useConnectionStatus() {
+    const client = useLiveClient();
+    const subscribe = useCallback((onStoreChange)=>client.onConnectionStatus(()=>onStoreChange()), [
+        client
+    ]);
+    const getSnapshot = useCallback(()=>client.connectionStatus(), [
+        client
+    ]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/dist/use-live-mutation.d.ts

@@ -0,0 +1,23 @@
+import type { MutateOptions } from '@velajs/client';
+export interface UseLiveMutationResult<R> {
+    /** Fire the mutation. Per-call options (optimistic targets, method, …) merge over the hook defaults. */
+    mutate: (body?: unknown, options?: MutateOptions) => Promise<R>;
+    pending: boolean;
+    data: R | undefined;
+    error: unknown;
+    reset: () => void;
+}
+/**
+ * HTTP mutation hook with live-aware optimistic updates:
+ *
+ * ```tsx
+ * const { mutate: addTodo, pending } = useLiveMutation('/todos', {
+ *   optimistic: { query: 'todos.list', args: { listId }, apply: (t = []) => [...t, temp] },
+ * });
+ * ```
+ *
+ * The optimistic layer is dropped exactly when a live frame's cursor passes
+ * the mutation's `Vela-Commit-Cursor` (see @velajs/client); failures roll it
+ * back and reject.
+ */
+export declare function useLiveMutation<R = unknown>(path: string, defaults?: MutateOptions): UseLiveMutationResult<R>;

package/dist/use-live-mutation.js

@@ -0,0 +1,59 @@
+import { useCallback, useRef, useState } from "react";
+import { useLiveClient } from "./context.js";
+/**
+ * HTTP mutation hook with live-aware optimistic updates:
+ *
+ * ```tsx
+ * const { mutate: addTodo, pending } = useLiveMutation('/todos', {
+ *   optimistic: { query: 'todos.list', args: { listId }, apply: (t = []) => [...t, temp] },
+ * });
+ * ```
+ *
+ * The optimistic layer is dropped exactly when a live frame's cursor passes
+ * the mutation's `Vela-Commit-Cursor` (see @velajs/client); failures roll it
+ * back and reject.
+ */ export function useLiveMutation(path, defaults) {
+    const client = useLiveClient();
+    const [state, setState] = useState({
+        pending: 0
+    });
+    const defaultsRef = useRef(defaults);
+    defaultsRef.current = defaults;
+    const mutate = useCallback(async (body, options)=>{
+        setState((current)=>({
+                ...current,
+                pending: current.pending + 1
+            }));
+        try {
+            const data = await client.mutate(path, body, {
+                ...defaultsRef.current,
+                ...options
+            });
+            setState((current)=>({
+                    pending: current.pending - 1,
+                    data,
+                    error: undefined
+                }));
+            return data;
+        } catch (error) {
+            setState((current)=>({
+                    ...current,
+                    pending: current.pending - 1,
+                    error
+                }));
+            throw error;
+        }
+    }, [
+        client,
+        path
+    ]);
+    return {
+        mutate,
+        pending: state.pending > 0,
+        data: state.data,
+        error: state.error,
+        reset: useCallback(()=>setState({
+                pending: 0
+            }), [])
+    };
+}

package/dist/use-live-query.d.ts

@@ -0,0 +1,17 @@
+import type { ArgsOf, LiveContract, ResultOf, SubscribeOptions } from '@velajs/client';
+export interface UseLiveQueryOptions extends SubscribeOptions {
+    /** Render without subscribing (conditional queries). */
+    skip?: boolean;
+}
+/**
+ * Subscribe to a live query. Returns `undefined` until the first
+ * snapshot/hydrated value, then re-renders on every server push. Built on
+ * `useSyncExternalStore` — the client guarantees referentially stable
+ * snapshots between notifications, so there is no tearing and no external
+ * cache library.
+ *
+ * ```tsx
+ * const todos = useLiveQuery('todos.list', { listId }) ?? [];
+ * ```
+ */
+export declare function useLiveQuery<C extends LiveContract, Q extends keyof C & string>(query: Q, args: ArgsOf<C, Q>, options?: UseLiveQueryOptions): ResultOf<C, Q> | undefined;

package/dist/use-live-query.js

@@ -0,0 +1,46 @@
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+import { argsKeyOf } from "@velajs/client";
+import { useLiveClient } from "./context.js";
+/**
+ * Subscribe to a live query. Returns `undefined` until the first
+ * snapshot/hydrated value, then re-renders on every server push. Built on
+ * `useSyncExternalStore` — the client guarantees referentially stable
+ * snapshots between notifications, so there is no tearing and no external
+ * cache library.
+ *
+ * ```tsx
+ * const todos = useLiveQuery('todos.list', { listId }) ?? [];
+ * ```
+ */ export function useLiveQuery(query, args, options) {
+    const client = useLiveClient();
+    // Stable identity for the deps array — callers pass fresh object literals.
+    const argsKey = useMemo(()=>argsKeyOf(args), [
+        args
+    ]);
+    const { room, key, skip, onError } = options ?? {};
+    const subscribe = useCallback((onStoreChange)=>{
+        if (skip) return ()=>{};
+        return client.subscribe(query, args, ()=>onStoreChange(), {
+            room,
+            key,
+            onError
+        });
+    }, // eslint-disable-next-line react-hooks/exhaustive-deps -- argsKey stands in for args; onError is deliberately unbound
+    [
+        client,
+        query,
+        argsKey,
+        room,
+        key,
+        skip
+    ]);
+    const getSnapshot = useCallback(()=>skip ? undefined : client.peek(query, args, room), // eslint-disable-next-line react-hooks/exhaustive-deps -- argsKey stands in for args
+    [
+        client,
+        query,
+        argsKey,
+        room,
+        skip
+    ]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}

package/dist/use-presence.d.ts

@@ -0,0 +1,17 @@
+import type { PresenceMember } from '@velajs/client/presence';
+export interface UsePresenceOptions {
+    /** Payload attached to this connection's roster entry (latest render's value rides each beat). */
+    meta?: unknown;
+    /** Keep well under the server TTL (default 10 000 ms vs 30 000 ms). */
+    heartbeatIntervalMs?: number;
+}
+/**
+ * Join a room's presence and observe its roster. Heartbeats ride the room's
+ * live socket; departure is immediate on close; a tab regaining visibility
+ * beats right away so the roster recovers from a throttled background timer.
+ *
+ * ```tsx
+ * const people = usePresence(roomId, { meta: { name: user.name } });
+ * ```
+ */
+export declare function usePresence(room: string, options?: UsePresenceOptions): PresenceMember[];

package/dist/use-presence.js

@@ -0,0 +1,41 @@
+import { useEffect, useRef, useState } from "react";
+import { createPresence } from "@velajs/client/presence";
+import { useLiveClient } from "./context.js";
+/**
+ * Join a room's presence and observe its roster. Heartbeats ride the room's
+ * live socket; departure is immediate on close; a tab regaining visibility
+ * beats right away so the roster recovers from a throttled background timer.
+ *
+ * ```tsx
+ * const people = usePresence(roomId, { meta: { name: user.name } });
+ * ```
+ */ export function usePresence(room, options) {
+    const client = useLiveClient();
+    const [members, setMembers] = useState([]);
+    const metaRef = useRef(options?.meta);
+    metaRef.current = options?.meta;
+    const heartbeatIntervalMs = options?.heartbeatIntervalMs;
+    useEffect(()=>{
+        const handle = createPresence(client, {
+            room,
+            meta: ()=>metaRef.current,
+            heartbeatIntervalMs,
+            onRoster: setMembers
+        });
+        const doc = globalThis.document;
+        const onVisibility = ()=>{
+            if (doc?.visibilityState === 'visible') handle.beat();
+        };
+        doc?.addEventListener?.('visibilitychange', onVisibility);
+        return ()=>{
+            doc?.removeEventListener?.('visibilitychange', onVisibility);
+            handle.stop();
+            setMembers([]);
+        };
+    }, [
+        client,
+        room,
+        heartbeatIntervalMs
+    ]);
+    return members;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@velajs/react",
+  "version": "0.1.0",
+  "description": "React hooks for Vela live queries: useLiveQuery, useLiveMutation, usePresence, useConnectionStatus on useSyncExternalStore",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "keywords": [
+    "vela",
+    "react",
+    "hooks",
+    "live-queries",
+    "realtime",
+    "optimistic-updates"
+  ],
+  "author": "ksh",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velajs/client.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/velajs/client#readme",
+  "bugs": {
+    "url": "https://github.com/velajs/client/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@velajs/client": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@swc/cli": "^0.8.1",
+    "@swc/core": "^1.15.43",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.0.0",
+    "happy-dom": "^20.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^6.0.3",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "build": "rm -rf dist && swc src -d dist --strip-leading-paths && tsc --emitDeclarationOnly",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}