reactivando / use-pubsub-js / 28132971601

100%

master: 80%

push

github

feat: retained-value bus mode + useBusState hook (useSyncExternalStore) (#86)

* feat: retained-value bus mode + useBusState hook (useSyncExternalStore)

Adds the most-requested pub/sub capability — read a topic's latest value as
React state — backed by useSyncExternalStore (tear-free under concurrent
rendering, SSR-safe via a server snapshot).

Bus:
- `createPubSub({ retained: true })` keeps the last value published per exact
  token; `getSnapshot(token)` reads it (undefined when retained is off, to avoid
  unbounded growth for dynamic topic sets). Cleared by clearAllSubscriptions.
- `getSnapshot` added to PubSubBus/TypedPubSub.

Hook:
- `useBusState({ bus, token, initialValue })` (new `./hooks/useBusState`
  subpath). On a retained bus the value is available on first render; on any bus
  it tracks publishes while mounted. `initialValue` doubles as the SSR snapshot.

Tests: retained getSnapshot semantics (last value, no-subscriber retain, off →
undefined, cleared); useBusState initial/update/mount-read/unmount/SSR. 118
tests, 100% coverage, attw + publint green for the new subpath.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* fix(useBusState): key latest-value ref by (bus, token); strengthen tests + docs

Adversarial review fixes:
- MAJOR: the latest-value ref could surface a stale value for one render after
  the `bus` or `token` prop changed (non-retained bus). Tag the ref with the
  (bus, token) it came from and ignore it on mismatch. Mutation-verified: the
  new "no stale value after bus change" test fails without the guard.
- Unmount test now spies the bus.on cleanup to prove the subscription is removed
  (not just that the frozen result stops updating).
- Document the SSR hydration-mismatch caveat (server snapshot is always
  initialValue) and the retained-bus memory caution (README + hook TSDoc), and
  note that a value published as `undefined` is treated as "no value".
- Comment the intentional empty dep array on g... (continued)

29 of 29 branches covered (100.0%)

Branch coverage included in aggregate %.

24 of 24 new or added lines in 2 files covered. (100.0%)

191 of 191 relevant lines covered (100.0%)

37.6 hits per line