@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 +87 -1
- package/README.md +19 -14
- package/dist/internal/index.cjs +1621 -0
- package/dist/internal/index.d.cts +1407 -0
- package/dist/internal/index.d.ts +1407 -0
- package/dist/internal/index.mjs +1601 -0
- package/dist/server/index.cjs +73 -2271
- package/dist/server/index.d.cts +1 -1437
- package/dist/server/index.d.ts +1 -1437
- package/dist/server/index.mjs +1 -2260
- package/dist/websocket/index.cjs +675 -0
- package/dist/websocket/index.d.cts +402 -0
- package/dist/websocket/index.d.ts +402 -0
- package/dist/websocket/index.mjs +673 -0
- package/package.json +31 -3
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.
|
|
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 **
|
|
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
|
|
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
|
-
- ✅ **
|
|
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,
|
|
91
|
+
One package, four entry points — import only what your app needs:
|
|
92
92
|
|
|
93
|
-
| Subpath
|
|
94
|
-
|
|
|
95
|
-
| **Server**
|
|
96
|
-
| **
|
|
97
|
-
| **
|
|
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
|
|
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
|
|
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)
|