@pylonsync/react 0.3.211 → 0.3.213

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.3.211",
+  "version": "0.3.213",
   "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.211",
-    "@pylonsync/sync": "0.3.211"
+    "@pylonsync/sdk": "0.3.213",
+    "@pylonsync/sync": "0.3.213"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/useRoom.test.ts

@@ -0,0 +1,216 @@
+// Regression coverage for the useRoom refcounted room registry.
+//
+// The chat app mounts useRoom from 3+ components per channel (presence
+// count, presence avatars, composer). Without deduping, that produced N
+// joins + N heartbeats + N leaves per channel view. These tests pin the
+// contract that the module-scoped registry collapses identical
+// (baseUrl, roomId, userId, token) tuples into a single network
+// footprint regardless of how many React subscribers there are.
+//
+// We drive the registry directly via `__roomRegistryInternals` instead
+// of mounting React because the react package doesn't ship a renderer
+// dep. The registry IS the contract under test — the hook is a thin
+// subscriber on top of it.
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+
+import { __roomRegistryInternals } from "./useRoom";
+
+// --- fetch stub --------------------------------------------------------
+
+interface RecordedRequest {
+  url: string;
+  method: string;
+  body: any;
+}
+
+let recorded: RecordedRequest[];
+let originalFetch: typeof globalThis.fetch;
+
+function installFetchStub(): void {
+  recorded = [];
+  originalFetch = globalThis.fetch;
+  globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = typeof input === "string" ? input : input.toString();
+    const method = (init?.method ?? "GET").toUpperCase();
+    let body: any = null;
+    if (typeof init?.body === "string") {
+      try {
+        body = JSON.parse(init.body);
+      } catch {
+        body = init.body;
+      }
+    }
+    recorded.push({ url, method, body });
+    // All room endpoints return JSON; the snapshot/members shape is what
+    // useRoom unpacks. An empty object is enough to exercise the
+    // "joined" success path without inventing peers.
+    const responseBody = JSON.stringify({ snapshot: { peers: [] }, members: [] });
+    return new Response(responseBody, {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  }) as typeof fetch;
+}
+
+function restoreFetch(): void {
+  globalThis.fetch = originalFetch;
+}
+
+function count(predicate: (r: RecordedRequest) => boolean): number {
+  return recorded.filter(predicate).length;
+}
+
+function isJoin(r: RecordedRequest): boolean {
+  return r.method === "POST" && r.url.endsWith("/api/rooms/join");
+}
+function isLeave(r: RecordedRequest): boolean {
+  return r.method === "POST" && r.url.endsWith("/api/rooms/leave");
+}
+function isHeartbeat(r: RecordedRequest): boolean {
+  return r.method === "GET" && /\/api\/rooms\/[^/]+$/.test(r.url);
+}
+
+// Wait until `pred()` returns true, polling on a microtask cadence. The
+// join + leave paths are promise-chained off pylonFetch, so a couple of
+// microtask flushes is all we need.
+async function flush(): Promise<void> {
+  for (let i = 0; i < 5; i++) {
+    await Promise.resolve();
+  }
+}
+
+// --- harness -----------------------------------------------------------
+
+const BASE = "http://stub.invalid";
+const ROOM = "room-1";
+const USER = "user-1";
+const TOKEN = "tok-1";
+
+beforeEach(() => {
+  installFetchStub();
+  __roomRegistryInternals.reset();
+});
+
+afterEach(() => {
+  __roomRegistryInternals.reset();
+  restoreFetch();
+});
+
+// --- tests -------------------------------------------------------------
+
+describe("useRoom shared registry", () => {
+  test("three hooks for the same room → 1 join, 1 leave, N (not 3N) heartbeats", async () => {
+    // Use a short interval so the test runs fast — semantics are the same.
+    const interval = 25;
+
+    const r1 = __roomRegistryInternals.acquire(BASE, ROOM, USER, TOKEN, {}, interval);
+    const r2 = __roomRegistryInternals.acquire(BASE, ROOM, USER, TOKEN, {}, interval);
+    const r3 = __roomRegistryInternals.acquire(BASE, ROOM, USER, TOKEN, {}, interval);
+
+    // All three resolved to the SAME shared room instance.
+    expect(r1).toBe(r2);
+    expect(r2).toBe(r3);
+    expect(__roomRegistryInternals.size()).toBe(1);
+
+    await flush();
+    // Exactly one join across 3 mounts.
+    expect(count(isJoin)).toBe(1);
+
+    // Let the heartbeat fire a few times.
+    await new Promise((res) => setTimeout(res, interval * 3 + 10));
+    const heartbeatsAfter3Ticks = count(isHeartbeat);
+    // 3 hooks × 3 ticks would be 9. Shared registry should land at ~3
+    // (one per tick). Allow off-by-one for scheduling jitter.
+    expect(heartbeatsAfter3Ticks).toBeGreaterThanOrEqual(2);
+    expect(heartbeatsAfter3Ticks).toBeLessThanOrEqual(4);
+
+    // Release all three. The first two are no-ops (refcount → 2, → 1);
+    // the third schedules teardown.
+    __roomRegistryInternals.release(r1);
+    __roomRegistryInternals.release(r2);
+    expect(count(isLeave)).toBe(0); // no leave while refs still > 0
+    __roomRegistryInternals.release(r3);
+
+    // Teardown is deferred via setTimeout(0); wait for it.
+    await new Promise((res) => setTimeout(res, 10));
+    await flush();
+
+    expect(count(isLeave)).toBe(1);
+    expect(__roomRegistryInternals.size()).toBe(0);
+
+    // Heartbeats stop after teardown — capture, wait, verify no growth.
+    const heartbeatsAtTeardown = count(isHeartbeat);
+    await new Promise((res) => setTimeout(res, interval * 2 + 10));
+    expect(count(isHeartbeat)).toBe(heartbeatsAtTeardown);
+  });
+
+  test("StrictMode double-mount race: release+acquire in same tick keeps room alive", async () => {
+    const interval = 1_000; // long — we don't care about heartbeats here.
+    const a = __roomRegistryInternals.acquire(BASE, ROOM, USER, TOKEN, {}, interval);
+    await flush();
+    expect(count(isJoin)).toBe(1);
+
+    // StrictMode cleanup: refcount → 0, teardown SCHEDULED but not fired.
+    __roomRegistryInternals.release(a);
+    // Synchronous remount lands before the setTimeout(0) callback runs.
+    const b = __roomRegistryInternals.acquire(BASE, ROOM, USER, TOKEN, {}, interval);
+    expect(b).toBe(a); // cancelled teardown — same shared room
+
+    // Wait long enough for any pending teardown to have fired.
+    await new Promise((res) => setTimeout(res, 20));
+    await flush();
+
+    // No leave ever shipped — the room stayed alive across the cycle.
+    expect(count(isLeave)).toBe(0);
+    expect(count(isJoin)).toBe(1); // and no extra join either
+
+    __roomRegistryInternals.release(b);
+    await new Promise((res) => setTimeout(res, 20));
+    await flush();
+    expect(count(isLeave)).toBe(1);
+  });
+
+  test("different room ids do NOT dedupe (separate joins, separate leaves)", async () => {
+    const a = __roomRegistryInternals.acquire(BASE, "room-A", USER, TOKEN, {}, 1_000);
+    const b = __roomRegistryInternals.acquire(BASE, "room-B", USER, TOKEN, {}, 1_000);
+    expect(a).not.toBe(b);
+    expect(__roomRegistryInternals.size()).toBe(2);
+
+    await flush();
+    expect(count(isJoin)).toBe(2);
+
+    __roomRegistryInternals.release(a);
+    __roomRegistryInternals.release(b);
+    await new Promise((res) => setTimeout(res, 20));
+    await flush();
+    expect(count(isLeave)).toBe(2);
+  });
+
+  test("different tokens do NOT dedupe (auth context differs)", async () => {
+    const a = __roomRegistryInternals.acquire(BASE, ROOM, USER, "tok-A", {}, 1_000);
+    const b = __roomRegistryInternals.acquire(BASE, ROOM, USER, "tok-B", {}, 1_000);
+    expect(a).not.toBe(b);
+    expect(__roomRegistryInternals.size()).toBe(2);
+
+    await flush();
+    expect(count(isJoin)).toBe(2);
+  });
+
+  test("acquire+release before join resolves still pairs join with leave once join lands", async () => {
+    // Microtask ordering: the join fetch resolves before the setTimeout(0)
+    // teardown fires, so even an immediate release waits for the join
+    // landing before shipping leave. That's the contract — every join
+    // we ship gets paired with a leave (server is idempotent regardless).
+    const interval = 1_000;
+    const a = __roomRegistryInternals.acquire(BASE, ROOM, USER, TOKEN, {}, interval);
+    __roomRegistryInternals.release(a);
+
+    await new Promise((res) => setTimeout(res, 20));
+    await flush();
+
+    expect(__roomRegistryInternals.size()).toBe(0);
+    expect(count(isJoin)).toBe(1);
+    expect(count(isLeave)).toBe(1);
+  });
+});

package/src/useRoom.ts

@@ -45,6 +45,229 @@ export interface UseRoomReturn {
   error: string | null;
 }
 
+// ---------------------------------------------------------------------------
+// Shared room registry — dedupes joins/heartbeats across components
+// ---------------------------------------------------------------------------
+//
+// Apps routinely call `useRoom(roomId, userId)` from 3+ components for the
+// same channel (presence count, presence avatars, typing indicator,
+// composer, …). Without deduping that explodes into N joins on mount, N
+// leaves on unmount, and N×interval heartbeat polls every tick. This
+// registry collapses all calls with the same identity tuple into a single
+// network footprint: one join, one interval, one leave.
+//
+// Identity key includes everything that would change the network shape:
+// baseUrl + token (different server / auth) + roomId + userId.
+//
+// StrictMode safety: when refcount drops to 0, the leave + interval
+// teardown is scheduled on a microtask. If the same hook re-mounts
+// synchronously in the same tick (StrictMode double-mount, fast tab
+// switch, parent re-key), the pending teardown is cancelled and the room
+// stays alive. The existing `joined` race-fix from the in-effect
+// implementation is preserved here too: leave only fires once the
+// original join has actually landed on the server.
+
+interface SharedRoom {
+  /** Number of live React hooks holding this room. */
+  refs: number;
+  /** Has the join() request resolved with a server response? */
+  joined: boolean;
+  /** Cached snapshot for late subscribers (mounting after the join landed). */
+  peers: RoomPeer[];
+  isConnected: boolean;
+  error: string | null;
+  /** Last presence data the caller pushed via setPresence. */
+  presence: Record<string, any>;
+  /** Active heartbeat poll. */
+  interval: ReturnType<typeof setInterval> | null;
+  /** Pending teardown — set when refcount hit 0 but we haven't actually
+   *  fired leave yet, to absorb StrictMode mount/unmount/mount races. */
+  pendingTeardown: ReturnType<typeof setTimeout> | null;
+  /** Subscriber callbacks; each useRoom hook registers one. */
+  subs: Set<() => void>;
+  /** Transport identity (frozen at create time — changing it changes the key). */
+  baseUrl: string;
+  token: string | undefined;
+  roomId: string;
+  userId: string;
+  heartbeatInterval: number;
+}
+
+const rooms = new Map<string, SharedRoom>();
+
+function roomKey(
+  baseUrl: string,
+  roomId: string,
+  userId: string,
+  token: string | undefined,
+): string {
+  return `${baseUrl}|${roomId}|${userId}|${token ?? ''}`;
+}
+
+function notify(room: SharedRoom): void {
+  for (const cb of room.subs) cb();
+}
+
+function transportFor(room: SharedRoom) {
+  return { baseUrl: room.baseUrl, token: room.token };
+}
+
+function startHeartbeat(room: SharedRoom): void {
+  if (room.interval) return;
+  room.interval = setInterval(async () => {
+    // Guard against late-firing intervals after teardown — if the room
+    // was already evicted from the registry, drop this tick.
+    if (!rooms.has(roomKeyFor(room))) return;
+    try {
+      const body = await pylonFetch<{ members?: RoomPeer[] }>(
+        transportFor(room),
+        `/api/rooms/${encodeURIComponent(room.roomId)}`,
+      );
+      if (!rooms.has(roomKeyFor(room))) return;
+      const next = (body.members ?? []).filter((p) => p.user_id !== room.userId);
+      room.peers = next;
+      notify(room);
+    } catch {
+      // Swallow — next heartbeat will retry. Matches prior behaviour.
+    }
+  }, room.heartbeatInterval);
+}
+
+function roomKeyFor(room: SharedRoom): string {
+  return roomKey(room.baseUrl, room.roomId, room.userId, room.token);
+}
+
+function joinRoom(room: SharedRoom): void {
+  // Fire-and-forget — the join promise resolves into the shared state
+  // and notifies all subscribers. Late subscribers either pick up the
+  // already-resolved snapshot from `room.peers` or the next heartbeat.
+  pylonFetch<{ snapshot?: { peers?: RoomPeer[] } }>(
+    transportFor(room),
+    '/api/rooms/join',
+    {
+      method: 'POST',
+      json: { room: room.roomId, user_id: room.userId, data: room.presence },
+    },
+  )
+    .then((body) => {
+      // The room may have been torn down before join landed (mount →
+      // unmount → no remount). In that case the entry is gone from the
+      // registry; bail and let the leave path (if it ran) do its thing.
+      if (!rooms.has(roomKeyFor(room))) return;
+      room.joined = true;
+      room.isConnected = true;
+      room.error = null;
+      if (body.snapshot?.peers) {
+        room.peers = body.snapshot.peers.filter((p) => p.user_id !== room.userId);
+      }
+      notify(room);
+    })
+    .catch((e: any) => {
+      if (!rooms.has(roomKeyFor(room))) return;
+      room.error = e?.message ?? 'Failed to join room';
+      notify(room);
+    });
+}
+
+function leaveRoom(room: SharedRoom): void {
+  // Only ship leave if join actually landed — matches the original
+  // StrictMode race-fix. Server leave is idempotent now, but skipping
+  // the call still saves a round trip on every double-mount in dev.
+  if (room.joined) {
+    pylonFetch(transportFor(room), '/api/rooms/leave', {
+      method: 'POST',
+      json: { room: room.roomId, user_id: room.userId },
+    }).catch(() => {});
+  }
+}
+
+function acquireRoom(
+  baseUrl: string,
+  roomId: string,
+  userId: string,
+  token: string | undefined,
+  initialPresence: Record<string, any>,
+  heartbeatInterval: number,
+): SharedRoom {
+  const key = roomKey(baseUrl, roomId, userId, token);
+  let room = rooms.get(key);
+  if (room) {
+    // Absorb a pending teardown — caller is about to incref past 0
+    // again before the deferred leave fired. Cancel it so we don't
+    // tear down a still-live room.
+    if (room.pendingTeardown) {
+      clearTimeout(room.pendingTeardown);
+      room.pendingTeardown = null;
+    }
+    room.refs += 1;
+    return room;
+  }
+  room = {
+    refs: 1,
+    joined: false,
+    peers: [],
+    isConnected: false,
+    error: null,
+    presence: initialPresence,
+    interval: null,
+    pendingTeardown: null,
+    subs: new Set(),
+    baseUrl,
+    token,
+    roomId,
+    userId,
+    heartbeatInterval,
+  };
+  rooms.set(key, room);
+  joinRoom(room);
+  startHeartbeat(room);
+  return room;
+}
+
+function releaseRoom(room: SharedRoom): void {
+  room.refs -= 1;
+  if (room.refs > 0) return;
+  // Defer the actual teardown to the next macrotask. React StrictMode
+  // unmounts and re-mounts every effect synchronously in dev; without
+  // this defer we'd ship join → leave → join on every render. A 0ms
+  // setTimeout is enough — the synchronous remount lands first and
+  // cancels the pending teardown via `acquireRoom`.
+  if (room.pendingTeardown) clearTimeout(room.pendingTeardown);
+  room.pendingTeardown = setTimeout(() => {
+    // Re-check refcount — a remount might have incref'd inside the
+    // same tick after the timer was scheduled.
+    if (room.refs > 0) {
+      room.pendingTeardown = null;
+      return;
+    }
+    if (room.interval) {
+      clearInterval(room.interval);
+      room.interval = null;
+    }
+    rooms.delete(roomKeyFor(room));
+    room.pendingTeardown = null;
+    leaveRoom(room);
+  }, 0);
+}
+
+// Exported for tests — lets the regression test reset registry state
+// between cases so leaked rooms from one test can't bleed into the next,
+// and drive the refcount through the same code path the hook uses.
+export const __roomRegistryInternals = {
+  reset(): void {
+    for (const room of rooms.values()) {
+      if (room.pendingTeardown) clearTimeout(room.pendingTeardown);
+      if (room.interval) clearInterval(room.interval);
+    }
+    rooms.clear();
+  },
+  acquire: acquireRoom,
+  release: releaseRoom,
+  size(): number {
+    return rooms.size;
+  },
+};
+
 // ---------------------------------------------------------------------------
 // Hook
 // ---------------------------------------------------------------------------
@@ -53,6 +276,11 @@ export interface UseRoomReturn {
  * Subscribe to a real-time room. Joins on mount, leaves on unmount, and
  * polls for peer updates on a configurable interval.
  *
+ * Multiple components calling `useRoom` with the same `(roomId, userId,
+ * baseUrl, token)` tuple share a single underlying join + heartbeat —
+ * mounting it from 5 components costs one POST /api/rooms/join, one
+ * heartbeat poll, and one POST /api/rooms/leave.
+ *
  * ```tsx
  * const { peers, isConnected, setPresence, broadcast, leave, error } = useRoom(
  *   "project-42",
@@ -94,124 +322,97 @@ export function useRoom(
   const [isConnected, setIsConnected] = useState(false);
   const [error, setError] = useState<string | null>(null);
 
-  const presenceRef = useRef(initialPresence);
-  const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null);
+  // Remember the most recent shared room this hook is attached to so
+  // setPresence / broadcast / leave can route through it without
+  // re-running the lifecycle effect on every render.
+  const roomRef = useRef<SharedRoom | null>(null);
 
-  // Transport config — shared across every room API call. The
-  // `pylonFetch` helper owns auth + credentials + JSON handling so
-  // every site here drops the duplicate header builder.
-  const transport = useCallback(
-    () => ({ baseUrl, token }),
-    [baseUrl, token],
-  );
-
-  // ------- lifecycle: join / heartbeat / leave -------
-  //
-  // React StrictMode double-mounts every effect in dev: mount → unmount →
-  // re-mount. The `joined` ref tracks whether the join() call actually
-  // landed before the cleanup ran. If join hadn't completed yet, the
-  // cleanup skips leave entirely — there's nothing to leave on the
-  // server's side. If join did land, leave fires normally. Server-side
-  // leave is also idempotent now (200 with was_present:false on
-  // duplicate), so even a race on this can't error in the network tab.
   useEffect(() => {
-    let mounted = true;
-    let joined = false;
-
-    const join = async () => {
-      try {
-        const body = await pylonFetch<{ snapshot?: { peers?: RoomPeer[] } }>(
-          transport(),
-          '/api/rooms/join',
-          {
-            method: 'POST',
-            json: { room: roomId, user_id: userId, data: presenceRef.current },
-          },
-        );
-        if (!mounted) return;
-        joined = true;
-        setIsConnected(true);
-        setError(null);
-        if (body.snapshot?.peers) {
-          setPeers(
-            body.snapshot.peers.filter((p) => p.user_id !== userId),
-          );
-        }
-      } catch (e: any) {
-        if (mounted) setError(e?.message ?? 'Failed to join room');
-      }
-    };
+    const room = acquireRoom(
+      baseUrl,
+      roomId,
+      userId,
+      token,
+      initialPresence,
+      heartbeatInterval,
+    );
+    roomRef.current = room;
 
-    join();
-
-    // Poll for peer list updates.
-    intervalRef.current = setInterval(async () => {
-      if (!mounted) return;
-      try {
-        const body = await pylonFetch<{ members?: RoomPeer[] }>(
-          transport(),
-          `/api/rooms/${encodeURIComponent(roomId)}`,
-        );
-        if (mounted) {
-          setPeers(
-            (body.members ?? []).filter((p) => p.user_id !== userId),
-          );
-        }
-      } catch {
-        // Swallow -- next heartbeat will retry.
-      }
-    }, heartbeatInterval);
+    // Pull the current shared snapshot immediately so a late subscriber
+    // doesn't have to wait one heartbeat to see who's in the room.
+    setPeers(room.peers);
+    setIsConnected(room.isConnected);
+    setError(room.error);
+
+    const sub = () => {
+      setPeers(room.peers);
+      setIsConnected(room.isConnected);
+      setError(room.error);
+    };
+    room.subs.add(sub);
 
     return () => {
-      mounted = false;
-      if (intervalRef.current) clearInterval(intervalRef.current);
-
-      // Skip the leave call when join never completed — fixes the
-      // StrictMode double-mount race that produced spurious "user
-      // not in this room" errors. Server leave is also idempotent so
-      // a stray duplicate would 200 anyway, but we save the round trip.
-      if (joined) {
-        pylonFetch(transport(), '/api/rooms/leave', {
-          method: 'POST',
-          json: { room: roomId, user_id: userId },
-        }).catch(() => {});
-      }
+      room.subs.delete(sub);
+      if (roomRef.current === room) roomRef.current = null;
+      releaseRoom(room);
     };
-    // Re-run the entire lifecycle when identity or connection details change.
+    // initialPresence is intentionally excluded — it's a "set once on
+    // first mount" value, and treating an inline-literal default as a
+    // dep would thrash the lifecycle on every render.
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [roomId, userId, baseUrl, token, heartbeatInterval]);
 
   // ------- actions -------
+  //
+  // These read from `roomRef.current` so they always hit the live shared
+  // room without needing the effect to re-run when callers change.
 
   const setPresence = useCallback(
     (data: Record<string, any>) => {
-      presenceRef.current = data;
-      pylonFetch(transport(), '/api/rooms/presence', {
-        method: 'POST',
-        json: { room: roomId, user_id: userId, data },
-      }).catch(() => {});
+      const room = roomRef.current;
+      if (room) room.presence = data;
+      pylonFetch(
+        { baseUrl, token },
+        '/api/rooms/presence',
+        {
+          method: 'POST',
+          json: { room: roomId, user_id: userId, data },
+        },
+      ).catch(() => {});
     },
-    [roomId, userId, transport],
+    [roomId, userId, baseUrl, token],
   );
 
   const broadcast = useCallback(
     (topic: string, data: any) => {
-      pylonFetch(transport(), '/api/rooms/broadcast', {
-        method: 'POST',
-        json: { room: roomId, user_id: userId, topic, data },
-      }).catch(() => {});
+      pylonFetch(
+        { baseUrl, token },
+        '/api/rooms/broadcast',
+        {
+          method: 'POST',
+          json: { room: roomId, user_id: userId, topic, data },
+        },
+      ).catch(() => {});
     },
-    [roomId, userId, transport],
+    [roomId, userId, baseUrl, token],
   );
 
   const leave = useCallback(() => {
-    pylonFetch(transport(), '/api/rooms/leave', {
-      method: 'POST',
-      json: { room: roomId, user_id: userId },
-    }).catch(() => {});
+    // Manual leave — bypasses the shared lifecycle and tells the server
+    // we're gone immediately. The next effect cleanup will still try to
+    // release the refcount; the join-guard means a duplicate leave is
+    // skipped if needed, and the server is idempotent anyway.
+    pylonFetch(
+      { baseUrl, token },
+      '/api/rooms/leave',
+      {
+        method: 'POST',
+        json: { room: roomId, user_id: userId },
+      },
+    ).catch(() => {});
     setIsConnected(false);
     setPeers([]);
-  }, [roomId, userId, transport]);
+  }, [roomId, userId, baseUrl, token]);
 
   return { peers, isConnected, setPresence, broadcast, leave, error };
 }

package/tsconfig.json

@@ -1,5 +1,8 @@
 {
   "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "types": ["bun-types"]
+  },
   "include": [
     "src"
   ]