@bymax-one/nest-realtime 1.0.1 → 1.0.3

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,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.0.3] - 2026-08-02
11
+
12
+ ### Fixed
13
+
14
+ - **`transport: 'websocket'` and `'both'` could not resolve a single provider.**
15
+ Registering `BymaxRealtimeWebSocketModule` and then injecting anything the
16
+ package root exports — `RealtimeService`, `ConnectionRegistry`, or any of the
17
+ eight injection tokens — failed with `UnknownElementException` at bootstrap.
18
+ SSE through the root module was unaffected.
19
+
20
+ Each entry point is a separate bundle, so the services and `Symbol` tokens both
21
+ of them reached by a relative path were copied into each. A copied class is a
22
+ different injection token, and the container held one set while the consumer
23
+ imported the other. The shared runtime now lives in one bundle that both entry
24
+ points import by package specifier, which gives it a single identity in
25
+ CommonJS as well as ESM — code splitting could not, since esbuild splits ESM
26
+ only.
27
+
28
+ ### Added
29
+
30
+ - **`pnpm check:surface`** compares every name each subpath exports, read from the
31
+ built `.d.ts`, against a checked-in snapshot, and fails on additions as well as
32
+ removals. A type exported for consumers and referenced nowhere internally is
33
+ invisible to `tsc`, to `attw` and to the README snippets, so it can vanish from
34
+ a barrel with every other gate green.
35
+
36
+ - **`pnpm check:runtime`** packs the tarball, lays it out the way npm would, and
37
+ boots NestJS against it in ESM and in CommonJS, resolving every exported token
38
+ from every transport mode. It runs in `prepublishOnly` and in CI. Every other
39
+ gate reads the source or the type declarations, so a defect in how the entry
40
+ points are bundled was invisible to all of them.
41
+
42
+ - **`pnpm size` now checks bundle boundaries structurally**: the root and shared
43
+ bundles must contain no static reference to the Socket.IO stack, and the root
44
+ and WebSocket bundles must _import_ the shared runtime rather than inline it.
45
+
46
+ ## [1.0.2] - 2026-08-02
47
+
48
+ ### Fixed
49
+
50
+ - **The package could not be imported by an SSE application at all.** The root
51
+ entry statically imported `@nestjs/websockets` and `@nestjs/platform-socket.io`,
52
+ both declared **optional** peers. A consumer who installed only the required
53
+ peers — which is what the manifest asks for, and what an application on SSE, the
54
+ default transport, would do — got `ERR_MODULE_NOT_FOUND` on
55
+ `import '@bymax-one/nest-realtime'`, in ESM and CommonJS alike.
56
+
57
+ The library already carried an `assertWsPeerDeps()` guard written to produce a
58
+ clear message for exactly this case. It was unreachable: the static import
59
+ failed while the module file was still loading, before any function ran.
60
+
61
+ ### Changed
62
+
63
+ - **WebSocket moved to its own entry point, `@bymax-one/nest-realtime/websocket`.**
64
+ It exports `BymaxRealtimeWebSocketModule`, which serves `transport: 'websocket'`
65
+ and `'both'`, together with `WebSocketTransport`, `RealtimeGateway`,
66
+ `RealtimeIoAdapter` and `CompositeTransport` — all removed from the package root.
67
+
68
+ `BymaxRealtimeModule` at the root now serves `'sse'` only, and nothing reachable
69
+ from it imports the Socket.IO stack. That is what makes "opt-in" true of the
70
+ install and not only of the configuration: an SSE application resolves 22
71
+ packages where it previously needed 45.
72
+
73
+ `transport` is narrowed per module rather than validated at runtime, so asking
74
+ the root module for `'websocket'` does not compile. Asking anyway — through a
75
+ cast, or from JavaScript — is refused with an error naming the entry point that
76
+ serves it.
77
+
78
+ - **The single-instance warning no longer fires for `transport: 'websocket'`.**
79
+ `IRealtimePubSub` is read by the SSE transport and its subscriber and by nothing
80
+ else, so telling a WebSocket-only application to provide one named the wrong
81
+ mechanism — it scales horizontally through `websocket.redisAdapter`. `'sse'` and
82
+ `'both'` still warn.
83
+
84
+ - **`transport` is required on `forRootAsync`.** It was an optional hint, and
85
+ omitting it took a path that registered every transport and resolved the active
86
+ one at runtime, which booted Socket.IO regardless of the configured mode. That
87
+ path is gone. Providers and controllers are fixed at decoration time, long
88
+ before a factory runs, so the transport has to be declared for the module to
89
+ register the right ones.
90
+
91
+ - The error raised when an async factory returns nothing now names the method it
92
+ called (`createRealtimeOptions`) instead of describing it.
93
+
10
94
  ## [1.0.1] - 2026-08-02
11
95
 
12
96
  ### Fixed
@@ -83,6 +167,8 @@ First published release.
83
167
  rather than by the manual sweep that raised the NestJS floors — that sweep
84
168
  asked about NestJS and never put the same question to the other ten peers.
85
169
 
86
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.0.1...HEAD
170
+ [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.0.3...HEAD
171
+ [1.0.3]: https://github.com/bymaxone/nest-realtime/compare/v1.0.2...v1.0.3
172
+ [1.0.2]: https://github.com/bymaxone/nest-realtime/compare/v1.0.1...v1.0.2
87
173
  [1.0.1]: https://github.com/bymaxone/nest-realtime/compare/v1.0.0...v1.0.1
88
174
  [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,27 @@ 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
+
110
+ The package also exposes `@bymax-one/nest-realtime/internal`. It is **not public API** and carries no compatibility promise — it is the shared runtime the two server subpaths import so that a service registered through one and injected through the other is the same class. Import the four above; nothing you need is only there.
111
+
107
112
  ---
108
113
 
109
114
  > [!TIP]
@@ -131,7 +136,7 @@ yarn add @bymax-one/nest-realtime
131
136
  # Server subpath (required)
132
137
  pnpm add @nestjs/common @nestjs/core rxjs reflect-metadata
133
138
 
134
- # WebSocket transport (optional — only for transport: 'websocket' | 'both')
139
+ # WebSocket subpath (optional — only when you import @bymax-one/nest-realtime/websocket)
135
140
  pnpm add @nestjs/websockets @nestjs/platform-socket.io socket.io
136
141
 
137
142
  # Horizontal scaling (optional)