@bymax-one/nest-realtime 1.0.1 → 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,54 @@ 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
+
10
58
  ## [1.0.1] - 2026-08-02
11
59
 
12
60
  ### Fixed
@@ -83,6 +131,7 @@ First published release.
83
131
  rather than by the manual sweep that raised the NestJS floors — that sweep
84
132
  asked about NestJS and never put the same question to the other ten peers.
85
133
 
86
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.0.1...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
87
136
  [1.0.1]: https://github.com/bymaxone/nest-realtime/compare/v1.0.0...v1.0.1
88
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)