ras-stack 0.12.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
@@ -208,6 +222,17 @@ await startTusUpload(upload)
 
 Applications retain ownership of email templates, missing-email behavior, upload metadata, authorization, quotas, and completion processing.
 
+Stateful development servers can reuse one typed resource across HMR without application-specific `globalThis` casts:
+
+```ts
+import { clearGlobalSingleton, globalAsyncSingleton } from 'ras-stack/server'
+
+export const app = () => globalAsyncSingleton('my-app.instance', createApp)
+export const resetApp = () => clearGlobalSingleton('my-app.instance', (instance) => instance.close())
+```
+
+Rejected async initialization removes only its own pending value so a later request can retry. Clearing deletes the key before awaiting initialization or disposal, allowing replacement startup without reusing a closing resource.
+
 ## Shared project configuration
 
 Extend the supplied configuration and override anything specific to the application:

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/dist/server/index.d.ts

@@ -1,3 +1,4 @@
 export * from './canonical-host.js';
 export * from './health.js';
 export * from './rpc.js';
+export * from './singleton.js';

package/dist/server/index.js

@@ -1,4 +1,5 @@
 export * from './canonical-host.js';
 export * from './health.js';
 export * from './rpc.js';
+export * from './singleton.js';
 //# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA","sourcesContent":["export * from './canonical-host.js'\nexport * from './health.js'\nexport * from './rpc.js'\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,aAAa,CAAA;AAC3B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA","sourcesContent":["export * from './canonical-host.js'\nexport * from './health.js'\nexport * from './rpc.js'\nexport * from './singleton.js'\n"]}

package/dist/server/singleton.d.ts

@@ -0,0 +1,4 @@
+export declare function globalSingleton<T>(key: string, create: () => T): T;
+export declare function globalAsyncSingleton<T>(key: string, create: () => T | Promise<T>): Promise<T>;
+export declare function peekGlobalSingleton(key: string): unknown;
+export declare function clearGlobalSingleton<T>(key: string, dispose?: (value: Awaited<T>) => void | Promise<void>): Promise<boolean>;

package/dist/server/singleton.js

@@ -0,0 +1,48 @@
+const storeKey = Symbol.for('ras-stack.server.singletons');
+function store() {
+    const target = globalThis;
+    return (target[storeKey] ??= new Map());
+}
+export function globalSingleton(key, create) {
+    const singletons = store();
+    const existing = singletons.get(key);
+    if (existing) {
+        if (existing.kind !== 'sync')
+            throw new Error(`singleton ${key} is asynchronous`);
+        return existing.value;
+    }
+    const value = create();
+    singletons.set(key, { kind: 'sync', value });
+    return value;
+}
+export function globalAsyncSingleton(key, create) {
+    const singletons = store();
+    const existing = singletons.get(key);
+    if (existing) {
+        if (existing.kind !== 'async')
+            throw new Error(`singleton ${key} is synchronous`);
+        return existing.value;
+    }
+    const pending = Promise.resolve().then(create);
+    const guarded = pending.catch((error) => {
+        if (singletons.get(key)?.value === guarded)
+            singletons.delete(key);
+        throw error;
+    });
+    singletons.set(key, { kind: 'async', value: guarded });
+    return guarded;
+}
+export function peekGlobalSingleton(key) {
+    return store().get(key)?.value;
+}
+export async function clearGlobalSingleton(key, dispose) {
+    const singletons = store();
+    if (!singletons.has(key))
+        return false;
+    const value = singletons.get(key)?.value;
+    singletons.delete(key);
+    if (dispose)
+        await dispose(await value);
+    return true;
+}
+//# sourceMappingURL=singleton.js.map

package/dist/server/singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.js","sourceRoot":"","sources":["../../src/server/singleton.ts"],"names":[],"mappings":"AAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,6BAA6B,CAAC,CAAA;AAI1D,SAAS,KAAK;IACZ,MAAM,MAAM,GAAG,UAA6B,CAAA;IAC5C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,IAAI,GAAG,EAAE,CAAC,CAAA;AACzC,CAAC;AAED,MAAM,UAAU,eAAe,CAAI,GAAW,EAAE,MAAe;IAC7D,MAAM,UAAU,GAAG,KAAK,EAAE,CAAA;IAC1B,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACpC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,IAAI,KAAK,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,kBAAkB,CAAC,CAAA;QACjF,OAAO,QAAQ,CAAC,KAAU,CAAA;IAC5B,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,EAAE,CAAA;IACtB,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAA;IAC5C,OAAO,KAAK,CAAA;AACd,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAI,GAAW,EAAE,MAA4B;IAC/E,MAAM,UAAU,GAAG,KAAK,EAAE,CAAA;IAC1B,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACpC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,IAAI,KAAK,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,GAAG,iBAAiB,CAAC,CAAA;QACjF,OAAO,QAAQ,CAAC,KAAmB,CAAA;IACrC,CAAC;IACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;IAC9C,MAAM,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QAC/C,IAAI,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,KAAK,OAAO;YAAE,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAClE,MAAM,KAAK,CAAA;IACb,CAAC,CAAC,CAAA;IACF,UAAU,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAA;IACtD,OAAO,OAAO,CAAA;AAChB,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,GAAW;IAC7C,OAAO,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAA;AAChC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAI,GAAW,EAAE,OAAqD;IAC9G,MAAM,UAAU,GAAG,KAAK,EAAE,CAAA;IAC1B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAA;IACtC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAU,CAAA;IAC7C,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;IACtB,IAAI,OAAO;QAAE,MAAM,OAAO,CAAC,MAAM,KAAK,CAAC,CAAA;IACvC,OAAO,IAAI,CAAA;AACb,CAAC","sourcesContent":["const storeKey = Symbol.for('ras-stack.server.singletons')\ntype SingletonEntry = { kind: 'sync' | 'async'; value: unknown }\ntype SingletonGlobal = typeof globalThis & { [storeKey]?: Map<string, SingletonEntry> }\n\nfunction store() {\n  const target = globalThis as SingletonGlobal\n  return (target[storeKey] ??= new Map())\n}\n\nexport function globalSingleton<T>(key: string, create: () => T): T {\n  const singletons = store()\n  const existing = singletons.get(key)\n  if (existing) {\n    if (existing.kind !== 'sync') throw new Error(`singleton ${key} is asynchronous`)\n    return existing.value as T\n  }\n  const value = create()\n  singletons.set(key, { kind: 'sync', value })\n  return value\n}\n\nexport function globalAsyncSingleton<T>(key: string, create: () => T | Promise<T>): Promise<T> {\n  const singletons = store()\n  const existing = singletons.get(key)\n  if (existing) {\n    if (existing.kind !== 'async') throw new Error(`singleton ${key} is synchronous`)\n    return existing.value as Promise<T>\n  }\n  const pending = Promise.resolve().then(create)\n  const guarded = pending.catch((error: unknown) => {\n    if (singletons.get(key)?.value === guarded) singletons.delete(key)\n    throw error\n  })\n  singletons.set(key, { kind: 'async', value: guarded })\n  return guarded\n}\n\nexport function peekGlobalSingleton(key: string): unknown {\n  return store().get(key)?.value\n}\n\nexport async function clearGlobalSingleton<T>(key: string, dispose?: (value: Awaited<T>) => void | Promise<void>) {\n  const singletons = store()\n  if (!singletons.has(key)) return false\n  const value = singletons.get(key)?.value as T\n  singletons.delete(key)\n  if (dispose) await dispose(await value)\n  return true\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ras-stack",
-  "version": "0.12.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
     }