@bymax-one/nest-realtime 1.2.20 → 1.2.21
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 +20 -1
- package/README.md +2 -2
- package/dist/internal/index.cjs +18 -4
- package/dist/internal/index.d.cts +4 -0
- package/dist/internal/index.d.ts +4 -0
- package/dist/internal/index.mjs +18 -4
- package/dist/websocket/index.cjs +1 -2
- package/dist/websocket/index.mjs +1 -2
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -7,6 +7,24 @@ Versioning is **not** strict [SemVer](https://semver.org/spec/v2.0.0.html) while
|
|
|
7
7
|
|
|
8
8
|
## [Unreleased]
|
|
9
9
|
|
|
10
|
+
## [1.2.21] - 2026-11-20
|
|
11
|
+
|
|
12
|
+
### Fixed
|
|
13
|
+
|
|
14
|
+
- **A proxy whose trap throws on `then`, or one that was revoked, returned by a factory is refused with the typed error.** `await` reads `then` on what a synchronous `useFactory` or `createRealtimeOptions` returns, which ran the trap inside the library before the options were read; a revoked proxy given to `forRoot` or returned by a factory raised the engine's `TypeError`. Both now raise `REALTIME_INVALID_OPTIONS` with the error as the `cause`.
|
|
15
|
+
- **`REALTIME_REDIS_ADAPTER_FAILED` no longer carries the text of the error underneath in its message.** The message names what could not be installed and the remedy; the error that was thrown is the `cause`.
|
|
16
|
+
- **A field named `event`, `message` or `err` cannot replace the event, the message or the error of a log line.** The library's own values are written after the fields.
|
|
17
|
+
- **A logger that throws no longer turns a reported failure into another one.** `logEvent` writes every `warn` and `error` line the library emits, often from a `catch` block or a promise handler; when the host's logger threw there, the error left the handler, and in the timer of the re-authentication service it was an unhandled rejection, which ends a Node process by default. The throw is now absorbed and the line is lost.
|
|
18
|
+
|
|
19
|
+
#### Apply to a derived backend
|
|
20
|
+
|
|
21
|
+
Code that read the reason from the message of a `REALTIME_REDIS_ADAPTER_FAILED` error reads `error.cause` instead.
|
|
22
|
+
|
|
23
|
+
### Documentation
|
|
24
|
+
|
|
25
|
+
- **The README says what a logger that rejects does and what a proxy that throws on its type keeps.** A logger whose method returns a rejected promise is not absorbed, because Nest's `Logger` discards the return value, so the rejection is an unhandled rejection of the host's process, which ends a Node process with exit code 1 unless the application handles `unhandledRejection`. A proxy that throws on every read, its type tag included, is refused as a built-in object without its error as the `cause`.
|
|
26
|
+
- **The README says that an `async` factory's object is read as the factory's own failure, and how a library refusal is recognised.** A factory written as an `async` function that returns a proxy whose trap throws rejects its own promise with that error, which the library cannot tell from the factory failing. A refusal the library raised is recognised by its stable code, so an error of the host's own that carries a `REALTIME_` code is not wrapped.
|
|
27
|
+
|
|
10
28
|
## [1.2.20] - 2026-11-20
|
|
11
29
|
|
|
12
30
|
### Fixed
|
|
@@ -1219,7 +1237,8 @@ First published release.
|
|
|
1219
1237
|
rather than by the manual sweep that raised the NestJS floors — that sweep
|
|
1220
1238
|
asked about NestJS and never put the same question to the other ten peers.
|
|
1221
1239
|
|
|
1222
|
-
[Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.
|
|
1240
|
+
[Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.21...HEAD
|
|
1241
|
+
[1.2.21]: https://github.com/bymaxone/nest-realtime/compare/v1.2.20...v1.2.21
|
|
1223
1242
|
[1.2.20]: https://github.com/bymaxone/nest-realtime/compare/v1.2.19...v1.2.20
|
|
1224
1243
|
[1.2.19]: https://github.com/bymaxone/nest-realtime/compare/v1.2.18...v1.2.19
|
|
1225
1244
|
[1.2.18]: https://github.com/bymaxone/nest-realtime/compare/v1.2.17...v1.2.18
|
package/README.md
CHANGED
|
@@ -412,7 +412,7 @@ An option that holds `undefined` or `null` is read as unset: it takes its defaul
|
|
|
412
412
|
|
|
413
413
|
The shape of what you pass is checked at start-up too, and refused with `REALTIME_INVALID_OPTIONS`: `sse`, `websocket`, `reauthenticationPolicy` and `hooks` must be objects; `pubsub`, `offlineQueue` and `presence` must have every function of their interface (`IRealtimePubSub`, `IOfflineQueueStorage`, `IPresenceStorage`), on the object or its prototype; each hook that is set and `tenantResolver` must be a function; `sse.emitConnectionEvent` and `websocket.emitConnectionEvent` must be booleans; `sse.endpoint` must be a non-blank string, with or without a leading slash. An endpoint holds no whitespace, because no request can reach it, and the `sseEndpoint` of `forRootAsync` gets the same check. The options argument must be an object, and so must what a `forRootAsync` factory returns; an array, a `Date` or a `Map` is refused there and where a group is expected, while an instance of your own class is read by its keys. `new RedisOfflineQueue(options)` refuses options that are not an object and a `client` that is not one.
|
|
414
414
|
|
|
415
|
-
The options are typed per entry point: `SseRealtimeModuleOptions` and `SseRealtimeModuleAsyncOptions` fix `transport: 'sse'`, and `WebSocketRealtimeModuleOptions` and `WebSocketRealtimeModuleAsyncOptions` (from `/websocket`) fix `'websocket' | 'both'`. `forRootAsync` takes `useFactory`, `useClass` (a `BymaxRealtimeModuleOptionsFactory`) or `useExisting`. A `useClass` or `useExisting` provider implements `createRealtimeOptions()`, which returns the options or a promise of them; a provider that does not is refused with `REALTIME_INVALID_OPTIONS`, as is an `extraProviders` that is not an array of providers (a class, or an object with `provide`). An options object, a group, a pluggable piece or a provider whose read throws, such as a getter or a proxy, is refused the same way, with the error it threw as the `cause`.
|
|
415
|
+
The options are typed per entry point: `SseRealtimeModuleOptions` and `SseRealtimeModuleAsyncOptions` fix `transport: 'sse'`, and `WebSocketRealtimeModuleOptions` and `WebSocketRealtimeModuleAsyncOptions` (from `/websocket`) fix `'websocket' | 'both'`. `forRootAsync` takes `useFactory`, `useClass` (a `BymaxRealtimeModuleOptionsFactory`) or `useExisting`. A `useClass` or `useExisting` provider implements `createRealtimeOptions()`, which returns the options or a promise of them; a provider that does not is refused with `REALTIME_INVALID_OPTIONS`, as is an `extraProviders` that is not an array of providers (a class, or an object with `provide`). An options object, a group, a pluggable piece or a provider whose read throws, such as a getter or a proxy, is refused the same way, with the error it threw as the `cause`. The exception is an object that throws when its type is read, such as a proxy whose every read throws: it is refused as a built-in object and its error is not kept. A factory that returns the object itself is covered, including a proxy that throws on `then` or was revoked; one written as an `async` function rejects its own promise with the object's error, which reaches the application as that factory's failure. A refusal is recognised by its stable code, so an error of your own that carries a `REALTIME_` code is not wrapped.
|
|
416
416
|
|
|
417
417
|
> [!IMPORTANT]
|
|
418
418
|
> **`forRootAsync` takes the SSE route on the registration, not from the factory.** NestJS
|
|
@@ -511,7 +511,7 @@ A label is one of the values listed and never an id, a tenant or a user. A revoc
|
|
|
511
511
|
|
|
512
512
|
**Traces.** With `@opentelemetry/api` installed the library starts `realtime.handshake` around the admission and authentication of each connection (attribute `bymax.realtime.transport`, `sse` or `websocket`) and `realtime.reauthenticate` around each re-authentication cycle. A refused handshake ends its span with status ERROR and the library error code, never the message. With no SDK registered the API is a no-op, and without the package nothing is started.
|
|
513
513
|
|
|
514
|
-
**Log events.** Every `warn` and `error` line the library writes is an object, `{ event, message, ...fields }`, with the error that caused a failure, when there is one, under `err` as the error itself and never as text in `message`; so a structured logger writes each as a JSON field and Nest's default logger prints the object. The fields are counts, sizes, configured limits, transport names and a library-made connection id; a user id, a tenant id or a room is never in a message or a field, because the logger's own context carries identity. Lines that report that the library started stay plain strings.
|
|
514
|
+
**Log events.** Every `warn` and `error` line the library writes is an object, `{ event, message, ...fields }`, with the error that caused a failure, when there is one, under `err` as the error itself and never as text in `message`; so a structured logger writes each as a JSON field and Nest's default logger prints the object. The fields are counts, sizes, configured limits, transport names and a library-made connection id; a user id, a tenant id or a room is never in a message or a field, because the logger's own context carries identity. Lines that report that the library started stay plain strings. A logger that throws while the library writes an event is absorbed: the line is lost and the call that was logging goes on. A logger whose method returns a rejected promise is not, because Nest's `Logger` discards what the method returns, so the rejection is an unhandled rejection of your process, which ends a Node process with exit code 1 unless the application handles `unhandledRejection`; such a logger has to catch its own failures.
|
|
515
515
|
|
|
516
516
|
| Event | Level | When | Fields |
|
|
517
517
|
| -------------------------------------- | ----------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
package/dist/internal/index.cjs
CHANGED
|
@@ -166,6 +166,10 @@ function guardHostReads(what, read) {
|
|
|
166
166
|
);
|
|
167
167
|
}
|
|
168
168
|
}
|
|
169
|
+
async function awaitHostResult(returned, what = "the options") {
|
|
170
|
+
guardHostReads(what, () => returned?.then);
|
|
171
|
+
return returned;
|
|
172
|
+
}
|
|
169
173
|
|
|
170
174
|
// src/server/constants/injection-tokens.constants.ts
|
|
171
175
|
var REALTIME_OPTIONS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_OPTIONS");
|
|
@@ -190,12 +194,19 @@ var KIND_OF_TYPE = {
|
|
|
190
194
|
function: "a function",
|
|
191
195
|
undefined: "undefined"
|
|
192
196
|
};
|
|
197
|
+
function isArray(value) {
|
|
198
|
+
try {
|
|
199
|
+
return Array.isArray(value);
|
|
200
|
+
} catch {
|
|
201
|
+
return false;
|
|
202
|
+
}
|
|
203
|
+
}
|
|
193
204
|
function describeReceived(value) {
|
|
194
205
|
if (typeof value === "number") {
|
|
195
206
|
return Number.isFinite(value) ? String(value) : "a number that is not finite";
|
|
196
207
|
}
|
|
197
208
|
if (value === null) return "null";
|
|
198
|
-
if (
|
|
209
|
+
if (isArray(value)) return "an array";
|
|
199
210
|
if (typeof value === "object" && !isPlainObject(value)) return "a built-in object";
|
|
200
211
|
return KIND_OF_TYPE[typeof value] ?? "an object";
|
|
201
212
|
}
|
|
@@ -557,7 +568,10 @@ var REALTIME_LOG_EVENTS = [
|
|
|
557
568
|
"REALTIME_SERVER_NOT_ATTACHED"
|
|
558
569
|
];
|
|
559
570
|
function logEvent(logger, level, event, message, fields = {}, error) {
|
|
560
|
-
|
|
571
|
+
try {
|
|
572
|
+
logger[level]({ ...fields, event, message, ...error === void 0 ? {} : { err: error } });
|
|
573
|
+
} catch {
|
|
574
|
+
}
|
|
561
575
|
}
|
|
562
576
|
|
|
563
577
|
// src/server/utils/describe-error.ts
|
|
@@ -2666,7 +2680,7 @@ function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
|
|
|
2666
2680
|
if (isSet(asyncOptions.useFactory)) {
|
|
2667
2681
|
return {
|
|
2668
2682
|
provide: REALTIME_OPTIONS_TOKEN,
|
|
2669
|
-
useFactory: async (...args) => resolve(await asyncOptions.useFactory(...args), "useFactory"),
|
|
2683
|
+
useFactory: async (...args) => resolve(await awaitHostResult(asyncOptions.useFactory(...args)), "useFactory"),
|
|
2670
2684
|
inject: [...asyncOptions.inject ?? []]
|
|
2671
2685
|
};
|
|
2672
2686
|
}
|
|
@@ -2684,7 +2698,7 @@ function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
|
|
|
2684
2698
|
);
|
|
2685
2699
|
}
|
|
2686
2700
|
return resolve(
|
|
2687
|
-
await create.call(factory),
|
|
2701
|
+
await awaitHostResult(create.call(factory)),
|
|
2688
2702
|
"createRealtimeOptions"
|
|
2689
2703
|
);
|
|
2690
2704
|
},
|
|
@@ -2309,6 +2309,10 @@ type LogFields = Readonly<Record<string, string | number | boolean>>;
|
|
|
2309
2309
|
* @param error - What was thrown, when the event reports a failure. It goes under `err` as the value itself, never
|
|
2310
2310
|
* as text in `message`, so the logger's serializer and redaction apply to it: an error raised by host code can
|
|
2311
2311
|
* carry a user or a tenant, and the library's own line must not.
|
|
2312
|
+
*
|
|
2313
|
+
* A logger that throws while writing is absorbed, since the report of a failure must not become another one. A
|
|
2314
|
+
* logger whose method returns a rejected promise is not: Nest's `Logger` discards what the method returns, so the
|
|
2315
|
+
* rejection is an unhandled rejection of the host's process, and the logger has to catch its own.
|
|
2312
2316
|
*/
|
|
2313
2317
|
declare function logEvent(logger: Pick<Logger, 'warn' | 'error'>, level: 'warn' | 'error', event: RealtimeLogEvent, message: string, fields?: LogFields, error?: unknown): void;
|
|
2314
2318
|
|
package/dist/internal/index.d.ts
CHANGED
|
@@ -2309,6 +2309,10 @@ type LogFields = Readonly<Record<string, string | number | boolean>>;
|
|
|
2309
2309
|
* @param error - What was thrown, when the event reports a failure. It goes under `err` as the value itself, never
|
|
2310
2310
|
* as text in `message`, so the logger's serializer and redaction apply to it: an error raised by host code can
|
|
2311
2311
|
* carry a user or a tenant, and the library's own line must not.
|
|
2312
|
+
*
|
|
2313
|
+
* A logger that throws while writing is absorbed, since the report of a failure must not become another one. A
|
|
2314
|
+
* logger whose method returns a rejected promise is not: Nest's `Logger` discards what the method returns, so the
|
|
2315
|
+
* rejection is an unhandled rejection of the host's process, and the logger has to catch its own.
|
|
2312
2316
|
*/
|
|
2313
2317
|
declare function logEvent(logger: Pick<Logger, 'warn' | 'error'>, level: 'warn' | 'error', event: RealtimeLogEvent, message: string, fields?: LogFields, error?: unknown): void;
|
|
2314
2318
|
|
package/dist/internal/index.mjs
CHANGED
|
@@ -164,6 +164,10 @@ function guardHostReads(what, read) {
|
|
|
164
164
|
);
|
|
165
165
|
}
|
|
166
166
|
}
|
|
167
|
+
async function awaitHostResult(returned, what = "the options") {
|
|
168
|
+
guardHostReads(what, () => returned?.then);
|
|
169
|
+
return returned;
|
|
170
|
+
}
|
|
167
171
|
|
|
168
172
|
// src/server/constants/injection-tokens.constants.ts
|
|
169
173
|
var REALTIME_OPTIONS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_OPTIONS");
|
|
@@ -188,12 +192,19 @@ var KIND_OF_TYPE = {
|
|
|
188
192
|
function: "a function",
|
|
189
193
|
undefined: "undefined"
|
|
190
194
|
};
|
|
195
|
+
function isArray(value) {
|
|
196
|
+
try {
|
|
197
|
+
return Array.isArray(value);
|
|
198
|
+
} catch {
|
|
199
|
+
return false;
|
|
200
|
+
}
|
|
201
|
+
}
|
|
191
202
|
function describeReceived(value) {
|
|
192
203
|
if (typeof value === "number") {
|
|
193
204
|
return Number.isFinite(value) ? String(value) : "a number that is not finite";
|
|
194
205
|
}
|
|
195
206
|
if (value === null) return "null";
|
|
196
|
-
if (
|
|
207
|
+
if (isArray(value)) return "an array";
|
|
197
208
|
if (typeof value === "object" && !isPlainObject(value)) return "a built-in object";
|
|
198
209
|
return KIND_OF_TYPE[typeof value] ?? "an object";
|
|
199
210
|
}
|
|
@@ -555,7 +566,10 @@ var REALTIME_LOG_EVENTS = [
|
|
|
555
566
|
"REALTIME_SERVER_NOT_ATTACHED"
|
|
556
567
|
];
|
|
557
568
|
function logEvent(logger, level, event, message, fields = {}, error) {
|
|
558
|
-
|
|
569
|
+
try {
|
|
570
|
+
logger[level]({ ...fields, event, message, ...error === void 0 ? {} : { err: error } });
|
|
571
|
+
} catch {
|
|
572
|
+
}
|
|
559
573
|
}
|
|
560
574
|
|
|
561
575
|
// src/server/utils/describe-error.ts
|
|
@@ -2664,7 +2678,7 @@ function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
|
|
|
2664
2678
|
if (isSet(asyncOptions.useFactory)) {
|
|
2665
2679
|
return {
|
|
2666
2680
|
provide: REALTIME_OPTIONS_TOKEN,
|
|
2667
|
-
useFactory: async (...args) => resolve(await asyncOptions.useFactory(...args), "useFactory"),
|
|
2681
|
+
useFactory: async (...args) => resolve(await awaitHostResult(asyncOptions.useFactory(...args)), "useFactory"),
|
|
2668
2682
|
inject: [...asyncOptions.inject ?? []]
|
|
2669
2683
|
};
|
|
2670
2684
|
}
|
|
@@ -2682,7 +2696,7 @@ function buildOptionsProvider(asyncOptions, resolve, factoryToken) {
|
|
|
2682
2696
|
);
|
|
2683
2697
|
}
|
|
2684
2698
|
return resolve(
|
|
2685
|
-
await create.call(factory),
|
|
2699
|
+
await awaitHostResult(create.call(factory)),
|
|
2686
2700
|
"createRealtimeOptions"
|
|
2687
2701
|
);
|
|
2688
2702
|
},
|
package/dist/websocket/index.cjs
CHANGED
|
@@ -467,10 +467,9 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends platformSocket_io.IoAda
|
|
|
467
467
|
} catch {
|
|
468
468
|
}
|
|
469
469
|
}
|
|
470
|
-
const reason = internal.describeError(err);
|
|
471
470
|
throw internal.realtimeError(
|
|
472
471
|
internal.REALTIME_ERROR_CODES.REDIS_ADAPTER_FAILED,
|
|
473
|
-
|
|
472
|
+
"websocket.redisAdapter is set but the Socket.IO Redis adapter could not be installed. Install @socket.io/redis-adapter and pass an ioredis client as pubClient.",
|
|
474
473
|
{ who: _RealtimeIoAdapter.name, cause: err }
|
|
475
474
|
);
|
|
476
475
|
}
|
package/dist/websocket/index.mjs
CHANGED
|
@@ -467,10 +467,9 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends IoAdapter {
|
|
|
467
467
|
} catch {
|
|
468
468
|
}
|
|
469
469
|
}
|
|
470
|
-
const reason = describeError(err);
|
|
471
470
|
throw realtimeError(
|
|
472
471
|
REALTIME_ERROR_CODES.REDIS_ADAPTER_FAILED,
|
|
473
|
-
|
|
472
|
+
"websocket.redisAdapter is set but the Socket.IO Redis adapter could not be installed. Install @socket.io/redis-adapter and pass an ioredis client as pubClient.",
|
|
474
473
|
{ who: _RealtimeIoAdapter.name, cause: err }
|
|
475
474
|
);
|
|
476
475
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bymax-one/nest-realtime",
|
|
3
|
-
"version": "1.2.
|
|
3
|
+
"version": "1.2.21",
|
|
4
4
|
"description": "Realtime backend → frontend communication for NestJS — dual-transport SSE (default) and WebSocket (opt-in) with a unified server-side API.",
|
|
5
5
|
"author": "Bymax One <support@bymax.one>",
|
|
6
6
|
"license": "MIT",
|