@bymax-one/nest-realtime 1.2.24 → 1.2.25

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,18 @@ Versioning is **not** strict [SemVer](https://semver.org/spec/v2.0.0.html) while
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.2.25] - 2026-11-21
11
+
12
+ ### Fixed
13
+
14
+ - **A `tenantResolver` is given the authenticator's own result again, and the library keeps its own record.** From 1.2.22 to 1.2.24 the resolver received a copy of the result, and every shape of host object turned out to lose something in a copy: a hidden or symbol-keyed field, a field a class default or `Object.create` supplies from the prototype, an accessor that shadows one, a getter over a private field that throws on the copy. The resolver is now handed the object the authenticator returned, so none of that applies. The record the library keeps is built by name (`userId`, `tenantId`, `roles`, `rooms`, `metadata`), each field read once, before the resolver runs; what a resolver writes to the result does not change it, and `roles`, `rooms` and `metadata` stay shared. What the resolver returns is what routes, so the tenant that was tested and the tenant that is used stay one value.
15
+ - **The entries of `extraProviders` are read under the guard, and a value whose type cannot be read says so.** An entry that throws when its type or its `provide` is read raised the host's own error or a refusal without it; it is now refused with the library's code and the error as the `cause`. A refusal of the options, a group or an entry whose type could not be read says `received an object that could not be read`, where it said `a built-in object` or `an object` according to a second read of the value.
16
+ - **A log field named `service` or `version` can no longer reach a log line.** A logger that stamps those on every line would have been given two answers; `logEvent` drops them with the other names it reserves.
17
+
18
+ #### Apply to a derived backend
19
+
20
+ A `tenantResolver` now receives the authenticator's original result, not a copy: it sees a `null` or absent `tenantId` as the authenticator returned it, and a resolver that wrote to the copy it was given from 1.2.22 to 1.2.24 now writes to the authenticator's object. The record the library keeps is built by name from `userId`, `tenantId`, `roles`, `rooms` and `metadata`, and is read the way JavaScript reads a property: a field supplied by a class default, `Object.create` or an accessor on the prototype is now honoured, where 1.2.22 to 1.2.24 dropped it, so a result whose `userId` exists only on its prototype is admitted, and a blank one is still refused. Properties of the result beyond those five were never exposed to hooks and are not kept.
21
+
10
22
  ## [1.2.24] - 2026-11-20
11
23
 
12
24
  ### Fixed
@@ -1274,7 +1286,8 @@ First published release.
1274
1286
  rather than by the manual sweep that raised the NestJS floors — that sweep
1275
1287
  asked about NestJS and never put the same question to the other ten peers.
1276
1288
 
1277
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.24...HEAD
1289
+ [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.25...HEAD
1290
+ [1.2.25]: https://github.com/bymaxone/nest-realtime/compare/v1.2.24...v1.2.25
1278
1291
  [1.2.24]: https://github.com/bymaxone/nest-realtime/compare/v1.2.23...v1.2.24
1279
1292
  [1.2.23]: https://github.com/bymaxone/nest-realtime/compare/v1.2.22...v1.2.23
1280
1293
  [1.2.22]: https://github.com/bymaxone/nest-realtime/compare/v1.2.21...v1.2.22
package/README.md CHANGED
@@ -342,23 +342,23 @@ With `redisAdapter`, the adapter registers `@socket.io/redis-adapter` and calls
342
342
 
343
343
  All options are passed to `forRoot()` / `forRootAsync()`. Only `transport` and `authenticator` are required.
344
344
 
345
- | Group | Key Options | Default |
346
- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
347
- | **transport** | `'sse'` \| `'websocket'` \| `'both'` | — (**required**) |
348
- | **authenticator** | `IConnectionAuthenticator` | — (**required**) |
349
- | **tenantResolver** | `(auth) => string \| undefined \| null` — derives `tenantId` from the auth result (it receives a plain copy of that result, which has no `tenantId` when the tenant is absent or `null`), on **both** transports; `undefined` and `null` mean "no opinion" and fall back | `auth.tenantId` |
350
- | **hooks** | `onConnect`, `onDisconnect`, `onError`, `onReauthenticationFailed`, `onDeliveryFailure` (fire-and-forget) | — |
351
- | **hookTimeoutMs** | How long the library waits for a hook it awaits (`onDisconnect` on both transports, WebSocket `onConnect`) before giving up on it; integer from 1 to 2147483647 | `5000` |
352
- | **onConnectFailure** | What a failing `onConnect` does to its connection: `'ignore'` logs it and keeps the connection, `'close'` logs it and closes the connection on both transports, after the hook has run; anything else is refused at start-up | `'ignore'` |
353
- | **authenticateTimeoutMs** | How long a handshake waits for `authenticate` before it is refused (SSE `503`, WebSocket the generic error); integer from 1 to 2147483647 | `10000` |
354
- | **maxPendingHandshakes** | How many calls to `authenticate` may be waiting at once, across both transports; over it a handshake is refused at once without calling it; integer >= 1 | `1000` |
355
- | **maxConnections** | How many connections one instance holds, both transports together; a handshake past it is refused before `authenticate` is called (SSE `503`, WebSocket the generic error); integer >= 1, no way to switch it off | `10000` |
356
- | **pubsub** | `IRealtimePubSub` — cross-instance fan-out for SSE | `InMemoryPubSub` |
357
- | **offlineQueue** | `IOfflineQueueStorage` — events held while a user is away | — (disabled) |
358
- | **presence** | `IPresenceStorage` — contract for your own presence tracking; the library never calls it | — (disabled) |
359
- | **sse** | `endpoint`, `heartbeatMs`, `replayBufferSize`, `replayTtlMs`, `replayMaxIdleUsers`, `maxConnectionsPerUser`, `emitConnectionEvent`, `maxQueuedBytes`, `maxQueuedEvents`, `stallHeartbeats` | `/realtime/sse`, `30000`, `100`, `300000`, `1000`, `5`, `true`, `2097152`, `1000`, `3` |
360
- | **websocket** | `namespace`, `cors`, `maxHttpBufferSize`, `pingIntervalMs`, `pingTimeoutMs`, `maxConnectionsPerUser`, `emitConnectionEvent`, `redisAdapter` | `'/'`, — (Socket.IO defaults), `5` for `maxConnectionsPerUser` |
361
- | **reauthenticationPolicy** | `intervalSeconds`, `onFailure` (`'disconnect'` \| `'event'`), `cacheTtlMs`, `revalidateTimeoutMs`, `concurrency` | `300`, `'disconnect'`, `60000`, `10000`, `8` |
345
+ | Group | Key Options | Default |
346
+ | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
347
+ | **transport** | `'sse'` \| `'websocket'` \| `'both'` | — (**required**) |
348
+ | **authenticator** | `IConnectionAuthenticator` | — (**required**) |
349
+ | **tenantResolver** | `(auth) => string \| undefined \| null` — derives `tenantId` from the auth result (it receives the authenticator's own result, not a copy), on **both** transports; `undefined` and `null` mean "no opinion" and fall back | `auth.tenantId` |
350
+ | **hooks** | `onConnect`, `onDisconnect`, `onError`, `onReauthenticationFailed`, `onDeliveryFailure` (fire-and-forget) | — |
351
+ | **hookTimeoutMs** | How long the library waits for a hook it awaits (`onDisconnect` on both transports, WebSocket `onConnect`) before giving up on it; integer from 1 to 2147483647 | `5000` |
352
+ | **onConnectFailure** | What a failing `onConnect` does to its connection: `'ignore'` logs it and keeps the connection, `'close'` logs it and closes the connection on both transports, after the hook has run; anything else is refused at start-up | `'ignore'` |
353
+ | **authenticateTimeoutMs** | How long a handshake waits for `authenticate` before it is refused (SSE `503`, WebSocket the generic error); integer from 1 to 2147483647 | `10000` |
354
+ | **maxPendingHandshakes** | How many calls to `authenticate` may be waiting at once, across both transports; over it a handshake is refused at once without calling it; integer >= 1 | `1000` |
355
+ | **maxConnections** | How many connections one instance holds, both transports together; a handshake past it is refused before `authenticate` is called (SSE `503`, WebSocket the generic error); integer >= 1, no way to switch it off | `10000` |
356
+ | **pubsub** | `IRealtimePubSub` — cross-instance fan-out for SSE | `InMemoryPubSub` |
357
+ | **offlineQueue** | `IOfflineQueueStorage` — events held while a user is away | — (disabled) |
358
+ | **presence** | `IPresenceStorage` — contract for your own presence tracking; the library never calls it | — (disabled) |
359
+ | **sse** | `endpoint`, `heartbeatMs`, `replayBufferSize`, `replayTtlMs`, `replayMaxIdleUsers`, `maxConnectionsPerUser`, `emitConnectionEvent`, `maxQueuedBytes`, `maxQueuedEvents`, `stallHeartbeats` | `/realtime/sse`, `30000`, `100`, `300000`, `1000`, `5`, `true`, `2097152`, `1000`, `3` |
360
+ | **websocket** | `namespace`, `cors`, `maxHttpBufferSize`, `pingIntervalMs`, `pingTimeoutMs`, `maxConnectionsPerUser`, `emitConnectionEvent`, `redisAdapter` | `'/'`, — (Socket.IO defaults), `5` for `maxConnectionsPerUser` |
361
+ | **reauthenticationPolicy** | `intervalSeconds`, `onFailure` (`'disconnect'` \| `'event'`), `cacheTtlMs`, `revalidateTimeoutMs`, `concurrency` | `300`, `'disconnect'`, `60000`, `10000`, `8` |
362
362
 
363
363
  `sse.heartbeatMs` must be between 5,000 and 90,000 ms. Any other value, including `NaN` and a non-number, stops the application at start-up with `REALTIME_INVALID_OPTIONS`. `websocket.pingIntervalMs` and `websocket.pingTimeoutMs` must be integers from 1 to 2147483647 (Socket.IO runs both as timers, and Node runs a longer one as 1 ms). `sse.replayTtlMs` must be an integer from 1 to 2147483647 and `sse.replayMaxIdleUsers` an integer of 1 or more. `sse.maxQueuedBytes`, `sse.maxQueuedEvents` and `sse.stallHeartbeats` must be integers of 0 or more, and `0` switches that bound off.
364
364
 
@@ -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`. The same holds for the keys of a `forRootAsync` registration and for 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, with the error it threw as the `cause`. 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.
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 same holds for the keys of a `forRootAsync` registration and for an object that throws when its type is read, such as a proxy whose every read throws: it is refused as an object that could not be read, with the error it threw as the `cause`. 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
@@ -777,7 +777,7 @@ Reference implementations shipped: `InMemoryPubSub` (default), `RedisRealtimePub
777
777
 
778
778
  To place a connection in no tenant, **omit `tenantId`**. The runtime also accepts `undefined` or `null`, but whether those type-check depends on the consumer's `tsconfig` (`exactOptionalPropertyTypes` rejects `undefined`, `strictNullChecks` rejects `null`), so omission is the only form that compiles everywhere.
779
779
 
780
- `tenantResolver` cannot clear a tenant. It receives a plain copy of the authentication result, not the authenticator's original object: the result's own enumerable properties, and the `tenantId` as the library read it, which counts when an accessor on the prototype supplies it and is missing when the tenant is absent or `null`. The copy is its own object and is shallow: a resolver that assigns to one of its top-level properties changes nothing the library keeps, while nested objects are shared with the original, so a write inside them changes what the library keeps. Resolution is `tenantResolver?.(auth) ?? auth.tenantId`, so a resolver returning `undefined` or `null` means "no opinion" and the authenticator's tenant stays. Decide the absent case in the authenticator.
780
+ `tenantResolver` cannot clear a tenant. It receives the authenticator's own result, the object it returned and not a copy, so everything on it works as it does for the authenticator's code. The library keeps its own record of `userId`, `tenantId`, `roles`, `rooms` and `metadata`, built by name before the resolver runs and read the way JavaScript reads a property, so a field that a class default, `Object.create` or an accessor on the prototype supplies counts. What a resolver writes to the result does not change that record, which is another object; `roles`, `rooms` and `metadata` are shared, so a write inside them changes what the library keeps. Resolution is `tenantResolver?.(auth) ?? tenantId`, where `tenantId` is what the result held before the resolver ran, so a resolver returning `undefined` or `null` means "no opinion" and the authenticator's tenant stays. Decide the absent case in the authenticator.
781
781
 
782
782
  #### Carrying handshake context into the hooks
783
783
 
@@ -221,7 +221,7 @@ function describeReceived(value) {
221
221
  function refuseObject(who, path, value, cause) {
222
222
  throw realtimeError(
223
223
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
224
- `${path} must be an object, received ${describeReceived(value)}`,
224
+ `${path} must be an object, received ${cause === void 0 ? describeReceived(value) : "an object that could not be read"}`,
225
225
  cause === void 0 ? { who } : { who, cause: cause.error }
226
226
  );
227
227
  }
@@ -240,10 +240,11 @@ var HOOK_NAMES = [
240
240
  "onDeliveryFailure"
241
241
  ];
242
242
  var GROUP_NAMES = ["sse", "websocket", "reauthenticationPolicy"];
243
+ var UNREADABLE = "an object that could not be read";
243
244
  function refuse(path, expected, received, cause) {
244
245
  throw realtimeError(
245
246
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
246
- `options.${path} must be ${expected}, received ${describeReceived(received)}`,
247
+ `options.${path} must be ${expected}, received ${cause === void 0 ? describeReceived(received) : UNREADABLE}`,
247
248
  cause === void 0 ? { who: "BymaxRealtimeModule" } : { who: "BymaxRealtimeModule", cause: cause.error }
248
249
  );
249
250
  }
@@ -308,14 +309,14 @@ function assertExtraProviders(value) {
308
309
  );
309
310
  }
310
311
  value.forEach((entry, index) => {
311
- const isClass = typeof entry === "function";
312
- const hasProvide = isPlainObject(entry) && "provide" in entry;
313
- if (isClass || hasProvide) return;
314
- const received = isPlainObject(entry) && !Array.isArray(entry) ? "an object with no provide" : describeReceived(entry);
312
+ if (typeof entry === "function") return;
313
+ const read = readPlainObject(entry);
314
+ if (read.plain && "provide" in entry) return;
315
+ const received = read.threw ? UNREADABLE : read.plain && !Array.isArray(entry) ? "an object with no provide" : describeReceived(entry);
315
316
  throw realtimeError(
316
317
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
317
318
  `extraProviders[${index}] must be a provider (a class or an object with provide), received ${received}`,
318
- { who: "BymaxRealtimeModule" }
319
+ read.threw ? { who: "BymaxRealtimeModule", cause: read.error } : { who: "BymaxRealtimeModule" }
319
320
  );
320
321
  });
321
322
  }
@@ -587,7 +588,9 @@ var RESERVED_KEYS = [
587
588
  "name",
588
589
  "v",
589
590
  "req",
590
- "res"
591
+ "res",
592
+ "service",
593
+ "version"
591
594
  ];
592
595
  function logEvent(logger, level, event, message, fields = {}, error) {
593
596
  try {
@@ -882,12 +885,25 @@ function isBlank(value) {
882
885
  return typeof value !== "string" || value.trim().length === 0;
883
886
  }
884
887
  function resolveAuthTenant(options, auth) {
885
- const { tenantId: own, ...rest } = auth;
886
- const resolved = options.tenantResolver?.(
887
- own === void 0 || own === null ? { ...rest } : { ...rest, tenantId: own }
888
- ) ?? own;
889
- if (resolved === void 0 || resolved === null) return rest;
890
- return { ...rest, tenantId: resolved };
888
+ const own = auth.tenantId;
889
+ const kept = keepByName(auth);
890
+ const resolved = options.tenantResolver?.(auth) ?? own;
891
+ if (resolved === void 0 || resolved === null) return kept;
892
+ return { ...kept, tenantId: resolved };
893
+ }
894
+ function keepByName(auth) {
895
+ const kept = {};
896
+ for (const key of ["userId", "roles", "rooms", "metadata"]) {
897
+ const value = auth[key];
898
+ if (value === void 0) continue;
899
+ Object.defineProperty(kept, key, {
900
+ value,
901
+ enumerable: true,
902
+ writable: true,
903
+ configurable: true
904
+ });
905
+ }
906
+ return kept;
891
907
  }
892
908
  function assertIdentityIsNotBlank(auth) {
893
909
  if (isBlank(auth.userId)) {
@@ -2781,7 +2797,7 @@ function composeForRootAsync(moduleClass, wiring, logger, asyncOptions) {
2781
2797
  assertModeSupported(wiring, registration.transport, moduleName);
2782
2798
  assertSseEndpoint("sseEndpoint", registration.sseEndpoint);
2783
2799
  assertSseEndpointApplies(registration, moduleName);
2784
- assertExtraProviders(registration.extraProviders);
2800
+ guardHostReads("the registration", () => assertExtraProviders(registration.extraProviders));
2785
2801
  const FACTORY_TOKEN = /* @__PURE__ */ Symbol("REALTIME_OPTIONS_FACTORY");
2786
2802
  const instanceId = crypto.randomUUID();
2787
2803
  const boundSseEndpoint = registration.sseEndpoint ?? DEFAULT_ASYNC_SSE_ENDPOINT;
@@ -479,14 +479,15 @@ interface BymaxRealtimeModuleOptions {
479
479
  /**
480
480
  * Derive the tenant a connection routes on from the authenticated result.
481
481
  *
482
- * Applied on **both** transports. It receives a plain copy of the authentication
483
- * result, not the authenticator's original object: the result's own enumerable
484
- * properties and the `tenantId` as the library read it, which counts when an accessor
485
- * on the prototype supplies it and is missing when the tenant is absent or `null`.
486
- * The copy is its own object and is shallow: a resolver that assigns to one of its
487
- * top-level properties changes nothing the library keeps, while `roles`, `rooms` and
488
- * `metadata` are shared with the original, so a write inside them changes what the
489
- * library keeps. `undefined` and
482
+ * Applied on **both** transports. It receives the authenticator's own result, the
483
+ * object it returned and not a copy, so everything on it works as it does for the
484
+ * authenticator's code. The library keeps its own record of `userId`, `tenantId`,
485
+ * `roles`, `rooms` and `metadata`, built by name before the resolver runs and read the
486
+ * way JavaScript reads a property, so a field that a class default, `Object.create` or
487
+ * an accessor on the prototype supplies counts. What a resolver writes to the result
488
+ * does not change that record, which is another object; `roles`, `rooms` and
489
+ * `metadata` are shared, so a write inside them changes what the library keeps.
490
+ * `undefined` and
490
491
  * `null` both mean "no opinion"
491
492
  * and fall back to `auth.tenantId` rather than clearing it; to place a connection
492
493
  * in no tenant, return a result without one from the authenticator. `null` is in
@@ -2314,7 +2315,7 @@ type LogFields = Readonly<Record<string, string | number | boolean>>;
2314
2315
  * @param event - The stable code of the condition.
2315
2316
  * @param message - Human text; the library's own wording, with no host-supplied value in it.
2316
2317
  * @param fields - Closed or numeric fields, built by the library. A key named `event` or `message` is replaced by the
2317
- * library's own value, and one named `err`, `msg`, `level`, `time`, `pid`, `hostname`, `name`, `v`, `req` or `res` is dropped, and a field whose read throws, such as a getter, loses the line like any other
2318
+ * library's own value, and one named `err`, `msg`, `level`, `time`, `pid`, `hostname`, `name`, `v`, `req`, `res`, `service` or `version` is dropped, and a field whose read throws, such as a getter, loses the line like any other
2318
2319
  * throw while writing.
2319
2320
  * @param error - What was thrown, when the event reports a failure. It goes under `err` as the value itself, never
2320
2321
  * as text in `message`, so the logger's serializer and redaction apply to it: an error raised by host code can
@@ -479,14 +479,15 @@ interface BymaxRealtimeModuleOptions {
479
479
  /**
480
480
  * Derive the tenant a connection routes on from the authenticated result.
481
481
  *
482
- * Applied on **both** transports. It receives a plain copy of the authentication
483
- * result, not the authenticator's original object: the result's own enumerable
484
- * properties and the `tenantId` as the library read it, which counts when an accessor
485
- * on the prototype supplies it and is missing when the tenant is absent or `null`.
486
- * The copy is its own object and is shallow: a resolver that assigns to one of its
487
- * top-level properties changes nothing the library keeps, while `roles`, `rooms` and
488
- * `metadata` are shared with the original, so a write inside them changes what the
489
- * library keeps. `undefined` and
482
+ * Applied on **both** transports. It receives the authenticator's own result, the
483
+ * object it returned and not a copy, so everything on it works as it does for the
484
+ * authenticator's code. The library keeps its own record of `userId`, `tenantId`,
485
+ * `roles`, `rooms` and `metadata`, built by name before the resolver runs and read the
486
+ * way JavaScript reads a property, so a field that a class default, `Object.create` or
487
+ * an accessor on the prototype supplies counts. What a resolver writes to the result
488
+ * does not change that record, which is another object; `roles`, `rooms` and
489
+ * `metadata` are shared, so a write inside them changes what the library keeps.
490
+ * `undefined` and
490
491
  * `null` both mean "no opinion"
491
492
  * and fall back to `auth.tenantId` rather than clearing it; to place a connection
492
493
  * in no tenant, return a result without one from the authenticator. `null` is in
@@ -2314,7 +2315,7 @@ type LogFields = Readonly<Record<string, string | number | boolean>>;
2314
2315
  * @param event - The stable code of the condition.
2315
2316
  * @param message - Human text; the library's own wording, with no host-supplied value in it.
2316
2317
  * @param fields - Closed or numeric fields, built by the library. A key named `event` or `message` is replaced by the
2317
- * library's own value, and one named `err`, `msg`, `level`, `time`, `pid`, `hostname`, `name`, `v`, `req` or `res` is dropped, and a field whose read throws, such as a getter, loses the line like any other
2318
+ * library's own value, and one named `err`, `msg`, `level`, `time`, `pid`, `hostname`, `name`, `v`, `req`, `res`, `service` or `version` is dropped, and a field whose read throws, such as a getter, loses the line like any other
2318
2319
  * throw while writing.
2319
2320
  * @param error - What was thrown, when the event reports a failure. It goes under `err` as the value itself, never
2320
2321
  * as text in `message`, so the logger's serializer and redaction apply to it: an error raised by host code can
@@ -219,7 +219,7 @@ function describeReceived(value) {
219
219
  function refuseObject(who, path, value, cause) {
220
220
  throw realtimeError(
221
221
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
222
- `${path} must be an object, received ${describeReceived(value)}`,
222
+ `${path} must be an object, received ${cause === void 0 ? describeReceived(value) : "an object that could not be read"}`,
223
223
  cause === void 0 ? { who } : { who, cause: cause.error }
224
224
  );
225
225
  }
@@ -238,10 +238,11 @@ var HOOK_NAMES = [
238
238
  "onDeliveryFailure"
239
239
  ];
240
240
  var GROUP_NAMES = ["sse", "websocket", "reauthenticationPolicy"];
241
+ var UNREADABLE = "an object that could not be read";
241
242
  function refuse(path, expected, received, cause) {
242
243
  throw realtimeError(
243
244
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
244
- `options.${path} must be ${expected}, received ${describeReceived(received)}`,
245
+ `options.${path} must be ${expected}, received ${cause === void 0 ? describeReceived(received) : UNREADABLE}`,
245
246
  cause === void 0 ? { who: "BymaxRealtimeModule" } : { who: "BymaxRealtimeModule", cause: cause.error }
246
247
  );
247
248
  }
@@ -306,14 +307,14 @@ function assertExtraProviders(value) {
306
307
  );
307
308
  }
308
309
  value.forEach((entry, index) => {
309
- const isClass = typeof entry === "function";
310
- const hasProvide = isPlainObject(entry) && "provide" in entry;
311
- if (isClass || hasProvide) return;
312
- const received = isPlainObject(entry) && !Array.isArray(entry) ? "an object with no provide" : describeReceived(entry);
310
+ if (typeof entry === "function") return;
311
+ const read = readPlainObject(entry);
312
+ if (read.plain && "provide" in entry) return;
313
+ const received = read.threw ? UNREADABLE : read.plain && !Array.isArray(entry) ? "an object with no provide" : describeReceived(entry);
313
314
  throw realtimeError(
314
315
  REALTIME_ERROR_CODES.INVALID_OPTIONS,
315
316
  `extraProviders[${index}] must be a provider (a class or an object with provide), received ${received}`,
316
- { who: "BymaxRealtimeModule" }
317
+ read.threw ? { who: "BymaxRealtimeModule", cause: read.error } : { who: "BymaxRealtimeModule" }
317
318
  );
318
319
  });
319
320
  }
@@ -585,7 +586,9 @@ var RESERVED_KEYS = [
585
586
  "name",
586
587
  "v",
587
588
  "req",
588
- "res"
589
+ "res",
590
+ "service",
591
+ "version"
589
592
  ];
590
593
  function logEvent(logger, level, event, message, fields = {}, error) {
591
594
  try {
@@ -880,12 +883,25 @@ function isBlank(value) {
880
883
  return typeof value !== "string" || value.trim().length === 0;
881
884
  }
882
885
  function resolveAuthTenant(options, auth) {
883
- const { tenantId: own, ...rest } = auth;
884
- const resolved = options.tenantResolver?.(
885
- own === void 0 || own === null ? { ...rest } : { ...rest, tenantId: own }
886
- ) ?? own;
887
- if (resolved === void 0 || resolved === null) return rest;
888
- return { ...rest, tenantId: resolved };
886
+ const own = auth.tenantId;
887
+ const kept = keepByName(auth);
888
+ const resolved = options.tenantResolver?.(auth) ?? own;
889
+ if (resolved === void 0 || resolved === null) return kept;
890
+ return { ...kept, tenantId: resolved };
891
+ }
892
+ function keepByName(auth) {
893
+ const kept = {};
894
+ for (const key of ["userId", "roles", "rooms", "metadata"]) {
895
+ const value = auth[key];
896
+ if (value === void 0) continue;
897
+ Object.defineProperty(kept, key, {
898
+ value,
899
+ enumerable: true,
900
+ writable: true,
901
+ configurable: true
902
+ });
903
+ }
904
+ return kept;
889
905
  }
890
906
  function assertIdentityIsNotBlank(auth) {
891
907
  if (isBlank(auth.userId)) {
@@ -2779,7 +2795,7 @@ function composeForRootAsync(moduleClass, wiring, logger, asyncOptions) {
2779
2795
  assertModeSupported(wiring, registration.transport, moduleName);
2780
2796
  assertSseEndpoint("sseEndpoint", registration.sseEndpoint);
2781
2797
  assertSseEndpointApplies(registration, moduleName);
2782
- assertExtraProviders(registration.extraProviders);
2798
+ guardHostReads("the registration", () => assertExtraProviders(registration.extraProviders));
2783
2799
  const FACTORY_TOKEN = /* @__PURE__ */ Symbol("REALTIME_OPTIONS_FACTORY");
2784
2800
  const instanceId = randomUUID();
2785
2801
  const boundSseEndpoint = registration.sseEndpoint ?? DEFAULT_ASYNC_SSE_ENDPOINT;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-realtime",
3
- "version": "1.2.24",
3
+ "version": "1.2.25",
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",