@bymax-one/nest-realtime 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -7,6 +7,77 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.0.2] - 2026-08-02
11
+
12
+ ### Fixed
13
+
14
+ - **The package could not be imported by an SSE application at all.** The root
15
+ entry statically imported `@nestjs/websockets` and `@nestjs/platform-socket.io`,
16
+ both declared **optional** peers. A consumer who installed only the required
17
+ peers — which is what the manifest asks for, and what an application on SSE, the
18
+ default transport, would do — got `ERR_MODULE_NOT_FOUND` on
19
+ `import '@bymax-one/nest-realtime'`, in ESM and CommonJS alike.
20
+
21
+ The library already carried an `assertWsPeerDeps()` guard written to produce a
22
+ clear message for exactly this case. It was unreachable: the static import
23
+ failed while the module file was still loading, before any function ran.
24
+
25
+ ### Changed
26
+
27
+ - **WebSocket moved to its own entry point, `@bymax-one/nest-realtime/websocket`.**
28
+ It exports `BymaxRealtimeWebSocketModule`, which serves `transport: 'websocket'`
29
+ and `'both'`, together with `WebSocketTransport`, `RealtimeGateway`,
30
+ `RealtimeIoAdapter` and `CompositeTransport` — all removed from the package root.
31
+
32
+ `BymaxRealtimeModule` at the root now serves `'sse'` only, and nothing reachable
33
+ from it imports the Socket.IO stack. That is what makes "opt-in" true of the
34
+ install and not only of the configuration: an SSE application resolves 22
35
+ packages where it previously needed 45.
36
+
37
+ `transport` is narrowed per module rather than validated at runtime, so asking
38
+ the root module for `'websocket'` does not compile. Asking anyway — through a
39
+ cast, or from JavaScript — is refused with an error naming the entry point that
40
+ serves it.
41
+
42
+ - **The single-instance warning no longer fires for `transport: 'websocket'`.**
43
+ `IRealtimePubSub` is read by the SSE transport and its subscriber and by nothing
44
+ else, so telling a WebSocket-only application to provide one named the wrong
45
+ mechanism — it scales horizontally through `websocket.redisAdapter`. `'sse'` and
46
+ `'both'` still warn.
47
+
48
+ - **`transport` is required on `forRootAsync`.** It was an optional hint, and
49
+ omitting it took a path that registered every transport and resolved the active
50
+ one at runtime, which booted Socket.IO regardless of the configured mode. That
51
+ path is gone. Providers and controllers are fixed at decoration time, long
52
+ before a factory runs, so the transport has to be declared for the module to
53
+ register the right ones.
54
+
55
+ - The error raised when an async factory returns nothing now names the method it
56
+ called (`createRealtimeOptions`) instead of describing it.
57
+
58
+ ## [1.0.1] - 2026-08-02
59
+
60
+ ### Fixed
61
+
62
+ - **The npm package page showed no documentation.** `1.0.0` reached the registry
63
+ with an empty `readme` field, so the page rendered nothing — even though
64
+ `README.md` was present in the tarball all along. Every package here published
65
+ under pnpm 11 has an empty `readme`; every one published under pnpm 10, which
66
+ delegated to the npm CLI, carries it. The same split appears in `_npmVersion`,
67
+ present only on the publishes the npm CLI performed. The release workflow now
68
+ calls `npm publish` directly, and this release is what carries the README to
69
+ the registry.
70
+ - **`keywords` were missing from the manifest**, so the package was
71
+ undiscoverable by search on npm. Fourteen added, covering the transports,
72
+ the pub/sub and presence concepts, and the React subpath.
73
+
74
+ ### Removed
75
+
76
+ - **The Roadmap section of the README.** It described work that is not shipping
77
+ and dates the moment it is written; the issues board is where direction
78
+ belongs. `README.md` ships in the package, so the section was on the npm page
79
+ too.
80
+
10
81
  ## [1.0.0] - 2026-08-02
11
82
 
12
83
  First published release.
@@ -60,5 +131,7 @@ First published release.
60
131
  rather than by the manual sweep that raised the NestJS floors — that sweep
61
132
  asked about NestJS and never put the same question to the other ten peers.
62
133
 
63
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.0.0...HEAD
134
+ [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.0.2...HEAD
135
+ [1.0.2]: https://github.com/bymaxone/nest-realtime/compare/v1.0.1...v1.0.2
136
+ [1.0.1]: https://github.com/bymaxone/nest-realtime/compare/v1.0.0...v1.0.1
64
137
  [1.0.0]: https://github.com/bymaxone/nest-realtime/releases/tag/v1.0.0
package/README.md CHANGED
@@ -33,7 +33,7 @@
33
33
 
34
34
  ## ✨ Overview
35
35
 
36
- `@bymax-one/nest-realtime` is a **transport-agnostic realtime channel** shipped as a single npm package with **3 subpath exports** — covering the NestJS server module, the shared type contracts, and the React hooks that consume them.
36
+ `@bymax-one/nest-realtime` is a **transport-agnostic realtime channel** shipped as a single npm package with **4 subpath exports** — covering the SSE server module, the WebSocket module, the shared type contracts, and the React hooks that consume them.
37
37
 
38
38
  The default transport is **Server-Sent Events**: browser-native, plain HTTP, no client library to ship. WebSocket via Socket.IO is one config flag away, and `'both'` runs them side by side. Your application code calls the same `RealtimeService` either way — the transport is a deployment decision, not an architectural one.
39
39
 
@@ -56,8 +56,8 @@ pnpm add @bymax-one/nest-realtime
56
56
  ### 📡 Transports
57
57
 
58
58
  - ✅ **SSE (default)** — native browser reconnect, `Last-Event-ID` replay, `: keepalive` heartbeat tuned for real proxies
59
- - ✅ **WebSocket (opt-in)** — Socket.IO gateway behind `transport: 'websocket'`, with full-duplex `emit`
60
- - ✅ **Composite mode** — `transport: 'both'` fans a single emit out to clients on either transport
59
+ - ✅ **WebSocket (opt-in)** — Socket.IO gateway behind the `/websocket` subpath, with full-duplex `emit`; an SSE app never installs it
60
+ - ✅ **Composite mode** — `transport: 'both'`, also on the `/websocket` subpath, fans a single emit out to clients on either transport
61
61
  - ✅ **Unified contract** — every transport implements `ITransport`, so `RealtimeService` never branches
62
62
 
63
63
  ### 🔐 Security & Auth
@@ -78,7 +78,7 @@ pnpm add @bymax-one/nest-realtime
78
78
 
79
79
  ### 🧩 Developer Experience
80
80
 
81
- - ✅ **3 subpath exports** — server, shared types, and React; tree-shakeable, ESM + CJS dual output
81
+ - ✅ **4 subpath exports** — server, WebSocket, shared types, and React; tree-shakeable, ESM + CJS dual output
82
82
  - ✅ **Dynamic module** — `forRoot()` and `forRootAsync()` with `useFactory` / `useClass` / `useExisting`
83
83
  - ✅ **Strict TypeScript, zero `any`** — `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` on
84
84
  - ✅ **Horizontal scaling** — `IRealtimePubSub` for SSE fan-out, `@socket.io/redis-adapter` for WebSocket
@@ -88,22 +88,25 @@ pnpm add @bymax-one/nest-realtime
88
88
 
89
89
  ## 📦 Subpath Exports
90
90
 
91
- One package, three entry points — import only what your app needs:
91
+ One package, four entry points — import only what your app needs:
92
92
 
93
- | Subpath | Import | Purpose | Dependencies |
94
- | ---------- | --------------------------------- | ---------------------------------------------- | :-------------: |
95
- | **Server** | `@bymax-one/nest-realtime` | NestJS module, transports, services, contracts | NestJS 11, rxjs |
96
- | **Shared** | `@bymax-one/nest-realtime/shared` | Types, room prefixes, event names, error codes | None |
97
- | **React** | `@bymax-one/nest-realtime/react` | Hooks & `RealtimeProvider` | React 19 |
93
+ | Subpath | Import | Purpose | Dependencies |
94
+ | ------------- | ------------------------------------ | ---------------------------------------------- | :---------------------------------------------------------------: |
95
+ | **Server** | `@bymax-one/nest-realtime` | NestJS module for SSE, services, contracts | NestJS 11, rxjs |
96
+ | **WebSocket** | `@bymax-one/nest-realtime/websocket` | NestJS module for `'websocket'` and `'both'` | + `@nestjs/websockets`, `@nestjs/platform-socket.io`, `socket.io` |
97
+ | **Shared** | `@bymax-one/nest-realtime/shared` | Types, room prefixes, event names, error codes | None |
98
+ | **React** | `@bymax-one/nest-realtime/react` | Hooks & `RealtimeProvider` | React 19 |
98
99
 
99
100
  ```
100
- shared (zero deps)
101
- ↗ ↖
102
- server react
101
+ shared (zero deps)
102
+ ↗ ↑ ↖
103
+ server websocket react
103
104
  ```
104
105
 
105
106
  The `shared` subpath carries no Node or NestJS import, so the same event names and error codes are used on both sides of the wire without duplicating a constant.
106
107
 
108
+ **The `websocket` subpath exists so the server one costs nothing extra.** Everything that touches `@nestjs/websockets`, `@nestjs/platform-socket.io` and `socket.io` is reachable only through it, so an application on SSE — the default transport — never installs the Socket.IO stack. Importing it is what opts in, in the install as much as in the configuration.
109
+
107
110
  ---
108
111
 
109
112
  > [!TIP]
@@ -131,7 +134,7 @@ yarn add @bymax-one/nest-realtime
131
134
  # Server subpath (required)
132
135
  pnpm add @nestjs/common @nestjs/core rxjs reflect-metadata
133
136
 
134
- # WebSocket transport (optional — only for transport: 'websocket' | 'both')
137
+ # WebSocket subpath (optional — only when you import @bymax-one/nest-realtime/websocket)
135
138
  pnpm add @nestjs/websockets @nestjs/platform-socket.io socket.io
136
139
 
137
140
  # Horizontal scaling (optional)
@@ -607,23 +610,6 @@ Platform-specific configuration is in [docs/proxies-cheat-sheet.md](./docs/proxi
607
610
 
608
611
  ---
609
612
 
610
- ## 🗺️ Roadmap
611
-
612
- The items below are directional — none are shipping today. The list exists so contributors can see where the library is headed and where help is most useful. Open an issue to discuss priorities or propose a design.
613
-
614
- | Area | Item | Status |
615
- | ----------------------- | -------------------------------------------------------------------------------------------- | --------- |
616
- | Presence | Redis reference implementation of `IPresenceStorage` — today the interface ships without one | Planned |
617
- | Pub/sub adapters | Reference implementations beyond Redis (NATS, Redis Streams) for `IRealtimePubSub` | Exploring |
618
- | Observability | Built-in metrics for connection counts, emit latency, and replay-buffer misses | Planned |
619
- | Backpressure | Per-connection send queues with a configurable policy for slow consumers | Exploring |
620
- | Client acknowledgements | Optional delivery receipts on the WebSocket transport | Exploring |
621
- | Framework adapters | Vue and Svelte subpaths built on the same shared contracts | Exploring |
622
-
623
- > Track progress and discuss proposals on the [issues board](https://github.com/bymaxone/nest-realtime/issues).
624
-
625
- ---
626
-
627
613
  ## 🤝 Contributing
628
614
 
629
615
  Contributions are welcome! Please open an issue to discuss substantial changes before submitting a pull request.