ras-stack 0.13.0 → 0.14.0

package/README.md

@@ -182,6 +182,20 @@ live.close()
 disconnect()
 ```
 
+React applications can keep transport ownership equally small while retaining the native client and subscription:
+
+```tsx
+import { useCallback } from 'react'
+import { useConnectedRealtimeClient, useRealtimePresence, useRealtimeSubscription } from 'ras-stack/realtime/react'
+
+const createClient = useCallback(() => createSameOriginRealtimeClient({ getToken }), [workspaceId])
+const client = useConnectedRealtimeClient(createClient)
+const subscription = useRealtimeSubscription({ client, channel, options, configure })
+const clients = useRealtimePresence(subscription)
+```
+
+The factory, subscription options, and configure callback should have stable identities and change only when their corresponding lifecycle should restart.
+
 The client helpers return the underlying Centrifuge client and subscription. React ownership, channel conventions, ticket validation, event parsing, presence models, and query invalidation remain application code. `publish()` returns `false` when the publisher is closed, disabled, or at capacity. `close()` rejects new work and waits for accepted publications and their bounded retries to finish.
 
 ## Email and uploads

package/dist/realtime/react.d.ts

@@ -0,0 +1,13 @@
+import type { Centrifuge, ClientInfo, Subscription, SubscriptionOptions } from 'centrifuge';
+export declare function useConnectedRealtimeClient(create: () => Centrifuge, enabled?: boolean): Centrifuge | undefined;
+export type RealtimeSubscriptionHookOptions = {
+    client?: Centrifuge;
+    channel?: string;
+    enabled?: boolean;
+    options?: SubscriptionOptions;
+    configure?: (subscription: Subscription) => void | (() => void);
+};
+export declare function useRealtimeSubscription(options: RealtimeSubscriptionHookOptions): Subscription | undefined;
+export declare function useRealtimePresence(subscription: Subscription | undefined, options?: {
+    onError?: (error: unknown) => void;
+}): Record<string, ClientInfo>;

package/dist/realtime/react.js

@@ -0,0 +1,50 @@
+import { useEffect, useState } from 'react';
+import { connectRealtimeClient, openRealtimeSubscription, watchSubscriptionPresence } from './client.js';
+export function useConnectedRealtimeClient(create, enabled = true) {
+    const [client, setClient] = useState();
+    useEffect(() => {
+        if (!enabled) {
+            setClient(undefined);
+            return undefined;
+        }
+        const next = create();
+        setClient(next);
+        return connectRealtimeClient(next);
+    }, [create, enabled]);
+    return client;
+}
+export function useRealtimeSubscription(options) {
+    const [subscription, setSubscription] = useState();
+    const { channel, client, configure, enabled = true, options: subscriptionOptions } = options;
+    useEffect(() => {
+        if (!enabled || !client || !channel) {
+            setSubscription(undefined);
+            return undefined;
+        }
+        const opened = openRealtimeSubscription(client, channel, subscriptionOptions, configure);
+        setSubscription(opened.subscription);
+        return opened.close;
+    }, [channel, client, configure, enabled, subscriptionOptions]);
+    return subscription;
+}
+export function useRealtimePresence(subscription, options = {}) {
+    const [clients, setClients] = useState({});
+    const onError = options.onError;
+    useEffect(() => {
+        if (!subscription) {
+            setClients({});
+            return undefined;
+        }
+        let active = true;
+        const stop = watchSubscriptionPresence(subscription, (next) => {
+            if (active)
+                setClients(next);
+        }, onError ? { onError } : {});
+        return () => {
+            active = false;
+            stop();
+        };
+    }, [onError, subscription]);
+    return clients;
+}
+//# sourceMappingURL=react.js.map

package/dist/realtime/react.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.js","sourceRoot":"","sources":["../../src/realtime/react.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AAC3C,OAAO,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAA;AAExG,MAAM,UAAU,0BAA0B,CAAC,MAAwB,EAAE,OAAO,GAAG,IAAI;IACjF,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,EAAc,CAAA;IAClD,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,SAAS,CAAC,SAAS,CAAC,CAAA;YACpB,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAA;QACrB,SAAS,CAAC,IAAI,CAAC,CAAA;QACf,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAA;IACpC,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACrB,OAAO,MAAM,CAAA;AACf,CAAC;AAUD,MAAM,UAAU,uBAAuB,CAAC,OAAwC;IAC9E,MAAM,CAAC,YAAY,EAAE,eAAe,CAAC,GAAG,QAAQ,EAAgB,CAAA;IAChE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,EAAE,OAAO,EAAE,mBAAmB,EAAE,GAAG,OAAO,CAAA;IAC5F,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACpC,eAAe,CAAC,SAAS,CAAC,CAAA;YAC1B,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,MAAM,MAAM,GAAG,wBAAwB,CAAC,MAAM,EAAE,OAAO,EAAE,mBAAmB,EAAE,SAAS,CAAC,CAAA;QACxF,eAAe,CAAC,MAAM,CAAC,YAAY,CAAC,CAAA;QACpC,OAAO,MAAM,CAAC,KAAK,CAAA;IACrB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,mBAAmB,CAAC,CAAC,CAAA;IAC9D,OAAO,YAAY,CAAA;AACrB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,YAAsC,EAAE,OAAO,GAA2C,EAAE;IAC9H,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAA6B,EAAE,CAAC,CAAA;IACtE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAA;IAC/B,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,UAAU,CAAC,EAAE,CAAC,CAAA;YACd,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,IAAI,MAAM,GAAG,IAAI,CAAA;QACjB,MAAM,IAAI,GAAG,yBAAyB,CACpC,YAAY,EACZ,CAAC,IAAI,EAAE,EAAE;YACP,IAAI,MAAM;gBAAE,UAAU,CAAC,IAAI,CAAC,CAAA;QAC9B,CAAC,EACD,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAC3B,CAAA;QACD,OAAO,GAAG,EAAE;YACV,MAAM,GAAG,KAAK,CAAA;YACd,IAAI,EAAE,CAAA;QACR,CAAC,CAAA;IACH,CAAC,EAAE,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAA;IAC3B,OAAO,OAAO,CAAA;AAChB,CAAC","sourcesContent":["import type { Centrifuge, ClientInfo, Subscription, SubscriptionOptions } from 'centrifuge'\nimport { useEffect, useState } from 'react'\nimport { connectRealtimeClient, openRealtimeSubscription, watchSubscriptionPresence } from './client.js'\n\nexport function useConnectedRealtimeClient(create: () => Centrifuge, enabled = true) {\n  const [client, setClient] = useState<Centrifuge>()\n  useEffect(() => {\n    if (!enabled) {\n      setClient(undefined)\n      return undefined\n    }\n    const next = create()\n    setClient(next)\n    return connectRealtimeClient(next)\n  }, [create, enabled])\n  return client\n}\n\nexport type RealtimeSubscriptionHookOptions = {\n  client?: Centrifuge\n  channel?: string\n  enabled?: boolean\n  options?: SubscriptionOptions\n  configure?: (subscription: Subscription) => void | (() => void)\n}\n\nexport function useRealtimeSubscription(options: RealtimeSubscriptionHookOptions) {\n  const [subscription, setSubscription] = useState<Subscription>()\n  const { channel, client, configure, enabled = true, options: subscriptionOptions } = options\n  useEffect(() => {\n    if (!enabled || !client || !channel) {\n      setSubscription(undefined)\n      return undefined\n    }\n    const opened = openRealtimeSubscription(client, channel, subscriptionOptions, configure)\n    setSubscription(opened.subscription)\n    return opened.close\n  }, [channel, client, configure, enabled, subscriptionOptions])\n  return subscription\n}\n\nexport function useRealtimePresence(subscription: Subscription | undefined, options: { onError?: (error: unknown) => void } = {}) {\n  const [clients, setClients] = useState<Record<string, ClientInfo>>({})\n  const onError = options.onError\n  useEffect(() => {\n    if (!subscription) {\n      setClients({})\n      return undefined\n    }\n    let active = true\n    const stop = watchSubscriptionPresence(\n      subscription,\n      (next) => {\n        if (active) setClients(next)\n      },\n      onError ? { onError } : {},\n    )\n    return () => {\n      active = false\n      stop()\n    }\n  }, [onError, subscription])\n  return clients\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ras-stack",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "description": "Composable full-stack primitives shared across Richard Solomou's applications.",
   "keywords": [
     "authentication",
@@ -58,6 +58,10 @@
       "types": "./dist/realtime/client.d.ts",
       "default": "./dist/realtime/client.js"
     },
+    "./realtime/react": {
+      "types": "./dist/realtime/react.d.ts",
+      "default": "./dist/realtime/react.js"
+    },
     "./server": {
       "types": "./dist/server/index.d.ts",
       "default": "./dist/server/index.js"
@@ -109,6 +113,8 @@
     "@types/better-sqlite3": "9.6.0",
     "@types/node": "^26.0.0",
     "@types/nodemailer": "^8.0.1",
+    "@types/react": "19.2.8",
+    "@types/react-test-renderer": "19.1.0",
     "better-sqlite3": "12.11.1",
     "centrifuge": "5.7.0",
     "drizzle-orm": "0.45.2",
@@ -117,6 +123,8 @@
     "oxlint": "^1.74.0",
     "oxlint-tsgolint": "^7.0.2001",
     "postgres": "3.4.9",
+    "react": "19.2.8",
+    "react-test-renderer": "19.2.8",
     "tus-js-client": "^4.3.1",
     "typescript": "^7.0.2",
     "vite": "8.2.1",
@@ -130,6 +138,7 @@
     "drizzle-orm": ">=0.45 <1",
     "nodemailer": ">=9 <10",
     "postgres": ">=3.4 <4",
+    "react": ">=19 <20",
     "tus-js-client": ">=4 <5"
   },
   "peerDependenciesMeta": {
@@ -154,6 +163,9 @@
     "postgres": {
       "optional": true
     },
+    "react": {
+      "optional": true
+    },
     "tus-js-client": {
       "optional": true
     }