@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 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.20...HEAD
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
  | -------------------------------------- | ----------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
@@ -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 (Array.isArray(value)) return "an array";
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
- logger[level]({ event, message, ...fields, ...error === void 0 ? {} : { err: error } });
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
 
@@ -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
 
@@ -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 (Array.isArray(value)) return "an array";
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
- logger[level]({ event, message, ...fields, ...error === void 0 ? {} : { err: error } });
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
  },
@@ -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
- `websocket.redisAdapter is set but the Socket.IO Redis adapter could not be installed (${reason}). Install @socket.io/redis-adapter and pass an ioredis client as pubClient.`,
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
  }
@@ -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
- `websocket.redisAdapter is set but the Socket.IO Redis adapter could not be installed (${reason}). Install @socket.io/redis-adapter and pass an ioredis client as pubClient.`,
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.20",
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",