@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 +74 -1
- package/README.md +17 -31
- package/dist/server/index.cjs +226 -884
- package/dist/server/index.d.cts +45 -636
- package/dist/server/index.d.ts +45 -636
- package/dist/server/index.mjs +227 -884
- package/dist/websocket/index.cjs +2018 -0
- package/dist/websocket/index.d.cts +1083 -0
- package/dist/websocket/index.d.ts +1083 -0
- package/dist/websocket/index.mjs +2016 -0
- package/package.json +54 -23
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.
|
|
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 **
|
|
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,25 @@ 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
|
+
|
|
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
|
|
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.
|