@pylonsync/react 0.3.130 → 0.3.133

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.130",
+  "version": "0.3.133",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,8 +12,8 @@
     "check": "tsc -p tsconfig.json --noEmit"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.3.130",
-    "@pylonsync/sync": "0.3.130"
+    "@pylonsync/sdk": "0.3.133",
+    "@pylonsync/sync": "0.3.133"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/db.ts

@@ -4,6 +4,7 @@ import { SyncEngine, createSyncEngine, type Row, type SyncEngineConfig } from "@
 import {
   useQuery as useQueryHook,
   useQueryOne as useQueryOneHook,
+  useReactiveQuery as useReactiveQueryHook,
   useMutation as useMutationHook,
   useInfiniteQuery as useInfiniteQueryHook,
   useAggregate as useAggregateHook,
@@ -12,6 +13,7 @@ import {
   type QueryOptions,
   type UseQueryReturn,
   type UseQueryOneReturn,
+  type UseReactiveQueryReturn,
   type UseMutationReturn,
   type UseInfiniteQueryReturn,
   type AggregateSpec,
@@ -99,6 +101,31 @@ export const db = {
     return useQueryOneHook<T>(getSync(), entity, id);
   },
 
+  /**
+   * Reactive query — Convex-style auto-rerunning server handler.
+   *
+   * The server runs your `query()` handler with dependency tracking
+   * (every `ctx.db.*` read is recorded), registers the subscription,
+   * and pushes the initial result. Any future mutation touching the
+   * dep set triggers a re-run + push.
+   *
+   * ```tsx
+   * const { data: feed, loading } = db.useReactiveQuery<FeedItem[]>(
+   *   "getFeed",
+   *   { userId: currentUser.id },
+   * );
+   * ```
+   *
+   * Authoring side: define the handler with `query()` from
+   * `@pylonsync/functions`. Any handler is eligible — no opt-in flag.
+   */
+  useReactiveQuery<T = unknown>(
+    fnName: string,
+    args?: unknown,
+  ): UseReactiveQueryReturn<T> {
+    return useReactiveQueryHook<T>(getSync(), fnName, args);
+  },
+
   /**
    * Server-side function call with mutation state (loading, data, error).
    *

package/src/hooks.ts

@@ -184,6 +184,88 @@ export function useQueryOne<T = Row>(
   return { data, loading: loading.current, error: error.current, refetch };
 }
 
+// ---------------------------------------------------------------------------
+// useReactiveQuery — Convex-style auto-rerunning server query
+// ---------------------------------------------------------------------------
+
+export interface UseReactiveQueryReturn<T> {
+  /** Latest server-pushed result. `null` until the initial run lands. */
+  data: T | null;
+  /** True until the first result lands (or the first error). */
+  loading: boolean;
+  /** Most recent error from the server-side handler, if any. */
+  error: Error | null;
+}
+
+/**
+ * Subscribe to a server-side `query()` handler with automatic re-run
+ * on dependency changes. Mirrors Convex's reactive query model:
+ *
+ * 1. Mount: client sends `reactive-subscribe` over WS with `fn_name`
+ *    + `args`. Server runs the handler under the connection's auth,
+ *    records which entities the handler read via `ctx.db.*`, registers
+ *    the subscription, and pushes the initial result.
+ * 2. On every server-side mutation, the runtime's reactive registry
+ *    looks up subs whose dep set overlaps the changed entity, re-runs
+ *    them, hashes the result, and pushes only when the hash changed.
+ * 3. Unmount: client sends `reactive-unsubscribe`; server tears down
+ *    the registration and stops re-running.
+ *
+ * Auth context for re-runs is captured at subscribe time — the
+ * subscriber's identity, not the mutating user's. Policy gates the
+ * handler runs at first execution apply on every re-run.
+ *
+ * ```tsx
+ * const { data, loading } = useReactiveQuery<MessageWithAuthor[]>(
+ *   sync,
+ *   "getMessagesWithAuthors",
+ *   { channelId: "c_1" },
+ * );
+ * ```
+ *
+ * Args object identity matters: changing the args reference triggers
+ * an unsubscribe + resubscribe with a fresh sub_id. Stabilize via
+ * `useMemo` if you build args inline on every render.
+ */
+export function useReactiveQuery<T = unknown>(
+  sync: SyncEngine,
+  fnName: string,
+  args?: unknown,
+): UseReactiveQueryReturn<T> {
+  const [data, setData] = useState<T | null>(null);
+  const [loading, setLoading] = useState<boolean>(true);
+  const [error, setError] = useState<Error | null>(null);
+  // Stable serialization of args — when the JSON shape changes we
+  // re-subscribe. Object identity changes alone don't re-subscribe.
+  const argsKey = useMemo(() => JSON.stringify(args ?? null), [args]);
+
+  useEffect(() => {
+    const sub_id = generateId();
+    setLoading(true);
+    setError(null);
+    sync.subscribeReactive(sub_id, fnName, args ?? null, (msg) => {
+      if (msg.kind === "result") {
+        setData(msg.result as T);
+        setLoading(false);
+        setError(null);
+      } else {
+        // Reactive error pushes (e.g. handler unavailable) — surface
+        // to the consumer and stop spinning.
+        setError(
+          Object.assign(new Error(msg.message || msg.code), { code: msg.code }),
+        );
+        setLoading(false);
+      }
+    });
+    return () => {
+      sync.unsubscribeReactive(sub_id);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sync, fnName, argsKey]);
+
+  return { data, loading, error };
+}
+
 // ---------------------------------------------------------------------------
 // Client-side filter application (matches the server's operator set)
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -7,6 +7,7 @@ import { defaultStorage, type Storage as PylonStorage } from "@pylonsync/sync";
 export {
   useQuery,
   useQueryOne,
+  useReactiveQuery,
   useMutation,
   useInfiniteQuery,
   usePaginatedQuery,
@@ -29,6 +30,7 @@ export type {
   IncludeSpec,
   UseQueryReturn,
   UseQueryOneReturn,
+  UseReactiveQueryReturn,
   UseMutationReturn,
   UseInfiniteQueryReturn,
   UsePaginatedQueryReturn,