---
id: update-pubsub-doc
name: Update pubsub-redis.md for @alkdev/pubsub
status: completed
depends_on: []
scope: moderate
risk: low
impact: component
level: implementation
---

## Description

`docs/architecture/pubsub-redis.md` describes code that's now in `@alkdev/pubsub`. The doc needs a substantial rewrite to reflect the new package's API surface, including EventEnvelope, WebSocket and Worker event targets, the `prefix`/`close()` Redis API, and the expanded operator set.

### Key changes

1. **Source location** — Change from `packages/core/pubsub/` to `@alkdev/pubsub` npm package
2. **createPubSub API** — Document `PubSubEventMap` pattern (simple `{ [eventType: string]: payload }`) replacing `PubSubPublishArgsByKey`. `publish(type, id, payload)` always takes 3 explicit args.
3. **EventEnvelope** — New concept: `{ type, id, payload }` is the universal cross-process message format. Types starting with `__` are reserved for adapter control messages (used by WS event targets for `__subscribe`/`__unsubscribe`).
4. **Redis EventTarget** — Add `prefix` option (e.g., `"alk:events:"`) and `close()` method. Remove the "configure serializer or wrap event target" workaround — `prefix` is now a parameter.
5. **WebSocket EventTarget** — No longer "Not started" / "Deferred". Document both:
   - `@alkdev/pubsub/event-target-websocket-client` — spoke-side adapter
   - `@alkdev/pubsub/event-target-websocket-server` — hub-side adapter with `addConnection()`/`removeConnection()`, per-connection `SpokeEventTarget`, backpressure handling
6. **Worker EventTarget** — New adapter: host (`createWorkerHostEventTarget(worker)`) and thread (`createWorkerThreadEventTarget()`)
7. **Operators** — List all 13: `filter`, `map`, `pipe`, `take`, `reduce`, `toArray`, `batch`, `dedupe`, `window`, `flat`, `groupBy`, `chain`, `join`
8. **Repeater** — Inlined, no external `@repeaterjs/repeater` dependency
9. **Package exports** — Document the 5 subpath exports: `.`, `./event-target-redis`, `./event-target-websocket-client`, `./event-target-websocket-server`, `./event-target-worker`
10. **Prior Art** — Update to reflect `@alkdev/pubsub` is a standalone package, not forked graphql-yoga code

## Acceptance Criteria

- [ ] Source location references `@alkdev/pubsub` throughout
- [ ] `createPubSub` API docs use `PubSubEventMap` pattern
- [ ] EventEnvelope concept is documented
- [ ] Redis EventTarget docs include `prefix` and `close()`
- [ ] WebSocket client and server event targets are documented (not marked as deferred)
- [ ] Worker event target is documented
- [ ] All 13 operators are listed
- [ ] No references to `packages/core/pubsub/` remain
- [ ] Prior Art section reflects standalone package, not in-repo fork

## References

- docs/reviews/core-library-extraction-sync-2026-05-18.md (Section 2.6)