@bymax-one/nest-realtime 1.2.3 → 1.2.4

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,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
7
7
 
8
8
  ## [Unreleased]
9
9
 
10
+ ## [1.2.4] - 2026-11-01
11
+
12
+ ### Fixed
13
+
14
+ - **A rejection that is not an `Error` no longer makes the handler reporting it fail.** Handlers
15
+ that log a failure read `.message` from whatever was thrown, so a promise that rejected with
16
+ `null` or `undefined`, or with an object that has no prototype, made the `catch` itself throw. In
17
+ a fire-and-forget `.catch` that surfaced as an unhandled rejection. They now describe the reason
18
+ through one function that never throws, and a test fails if a source file goes back to the old
19
+ patterns. The text logged for an `Error` or a string reason is unchanged; a plain object with a
20
+ string `message` now logs that message instead of `[object Object]`.
21
+
22
+ ### Documentation
23
+
24
+ - A local benchmark (`pnpm benchmark`, in `scripts/benchmark/`, not a CI gate) measures connect
25
+ latency, fan-out latency for 1, 100 and 1000 clients, cross-instance latency through Redis, memory
26
+ per idle connection and Redis connections per instance, and writes its tables as Markdown. The
27
+ first results, with the machine, versions and run-to-run noise, are in
28
+ `docs/benchmark_results_2026-10-31.md`.
29
+
10
30
  ## [1.2.3] - 2026-10-31
11
31
 
12
32
  **Apply before upgrading, if you set `websocket.redisAdapter`:** make sure `@socket.io/redis-adapter`
@@ -205,7 +225,7 @@ were routed to a tenant that differed by transport.
205
225
  **Shipped as a minor, and two entries below are strictly speaking breaking.** Both are called
206
226
  out as such rather than hidden: removing the `service` option is a compile error for anyone who
207
227
  passed it, and the new required key on `ConnectionEventMeta` is a compile error for anyone who
208
- *constructs* one. Neither changes runtime behaviour for any working configuration — `service`
228
+ _constructs_ one. Neither changes runtime behaviour for any working configuration — `service`
209
229
  was never read by anything, and reading the meta (what a hook does) is unaffected. The precedent
210
230
  is 1.1.1, which added a required `roles` key to the same type and shipped as a patch. The third
211
231
  item, the new bootstrap throw on a disagreeing SSE endpoint, replaces a silent misconfiguration
@@ -263,7 +283,7 @@ configured.
263
283
  channel, and it is the reason the field was declared in the first place.
264
284
 
265
285
  **This adds a required key** to `ConnectionEventMeta`, exactly as `roles` did in 1.1.1.
266
- Reading the meta is unaffected, which is what a hook does; code that *constructs* one
286
+ Reading the meta is unaffected, which is what a hook does; code that _constructs_ one
267
287
  (typically a test fixture) must now supply `metadata`. `undefined` stays meaningful — an
268
288
  authenticator that returns no bag is not one that returns an empty object. Like `roles`, it is
269
289
  a connect-time snapshot that `revalidate` does not refresh, and the library never reads a key.
@@ -598,7 +618,8 @@ First published release.
598
618
  rather than by the manual sweep that raised the NestJS floors — that sweep
599
619
  asked about NestJS and never put the same question to the other ten peers.
600
620
 
601
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.3...HEAD
621
+ [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.2.4...HEAD
622
+ [1.2.4]: https://github.com/bymaxone/nest-realtime/compare/v1.2.3...v1.2.4
602
623
  [1.2.3]: https://github.com/bymaxone/nest-realtime/compare/v1.2.2...v1.2.3
603
624
  [1.2.2]: https://github.com/bymaxone/nest-realtime/compare/v1.2.1...v1.2.2
604
625
  [1.2.1]: https://github.com/bymaxone/nest-realtime/compare/v1.2.0...v1.2.1
@@ -105,6 +105,18 @@ var REALTIME_PRESENCE_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_PRESENCE");
105
105
  var REALTIME_HOOKS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_HOOKS");
106
106
  var REALTIME_INSTANCE_ID_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_INSTANCE_ID");
107
107
  var DEFAULT_HEARTBEAT_MS = 3e4;
108
+
109
+ // src/server/utils/describe-error.ts
110
+ function describeError(reason) {
111
+ try {
112
+ const message = reason?.message;
113
+ return typeof message === "string" ? message : String(reason);
114
+ } catch {
115
+ return "unprintable error";
116
+ }
117
+ }
118
+
119
+ // src/server/offline-queue/offline-queue-delivery.service.ts
108
120
  var RETRIEVE_LIMIT = 200;
109
121
  exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
110
122
  constructor(storage) {
@@ -131,7 +143,7 @@ exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
131
143
  try {
132
144
  events = await this.storage.retrieveSince(userId, lastEventId, RETRIEVE_LIMIT);
133
145
  } catch (err) {
134
- this.logger.warn(`Offline queue retrieve failed: ${err.message}`);
146
+ this.logger.warn(`Offline queue retrieve failed: ${describeError(err)}`);
135
147
  return [];
136
148
  }
137
149
  if (events.length === RETRIEVE_LIMIT) {
@@ -158,7 +170,7 @@ exports.OfflineQueueDeliveryService = class OfflineQueueDeliveryService {
158
170
  try {
159
171
  await this.storage.acknowledge(userId, lastId);
160
172
  } catch (err) {
161
- this.logger.warn(`Offline queue acknowledge failed: ${err.message}`);
173
+ this.logger.warn(`Offline queue acknowledge failed: ${describeError(err)}`);
162
174
  }
163
175
  }
164
176
  };
@@ -570,7 +582,7 @@ exports.SseTransport = class SseTransport {
570
582
  ...reason !== void 0 ? { reason } : {}
571
583
  });
572
584
  } catch (error) {
573
- this.logger.error(`onDisconnect hook failed: ${error.message}`);
585
+ this.logger.error(`onDisconnect hook failed: ${describeError(error)}`);
574
586
  }
575
587
  }
576
588
  /** Replay the events a user missed after `lastEventId`. */
@@ -601,7 +613,7 @@ exports.SseTransport = class SseTransport {
601
613
  this.emitToUserLocal(userId, event, data, id);
602
614
  if (this.offlineQueue && this.connections.byUser(userId, "sse").length === 0) {
603
615
  void this.offlineQueue.append(userId, { id, event, data, emittedAt: /* @__PURE__ */ new Date() }).catch(
604
- (error) => this.logger.warn(`Offline queue append failed: ${error.message}`)
616
+ (error) => this.logger.warn(`Offline queue append failed: ${describeError(error)}`)
605
617
  );
606
618
  }
607
619
  await this.publish({ op: "emitToUser", args: { userId, event, data, id } });
@@ -707,7 +719,7 @@ exports.SseTransport = class SseTransport {
707
719
  try {
708
720
  conn.subject?.next(message);
709
721
  } catch (error) {
710
- this.logger.warn(`SSE delivery failed for ${conn.connectionId}: ${error.message}`);
722
+ this.logger.warn(`SSE delivery failed for ${conn.connectionId}: ${describeError(error)}`);
711
723
  }
712
724
  }
713
725
  /** Publish once to the bus; pub/sub failures never affect the live emit path. */
@@ -715,7 +727,7 @@ exports.SseTransport = class SseTransport {
715
727
  try {
716
728
  await this.pubsub.publish({ ...message, origin: this.instanceId });
717
729
  } catch (error) {
718
- this.logger.warn(`pubsub.publish failed: ${error.message}`);
730
+ this.logger.warn(`pubsub.publish failed: ${describeError(error)}`);
719
731
  }
720
732
  }
721
733
  /** Evict a user's oldest connections (FIFO) when over `maxConnectionsPerUser`. */
@@ -849,7 +861,7 @@ exports.SseSubscriptionHandler = class SseSubscriptionHandler {
849
861
  try {
850
862
  assertIdentityIsNotBlank(resolvedAuth);
851
863
  } catch (err) {
852
- this.logger.error(`SSE connection refused \u2014 responding 500: ${err.message}`);
864
+ this.logger.error(`SSE connection refused \u2014 responding 500: ${describeError(err)}`);
853
865
  throw new common.InternalServerErrorException();
854
866
  }
855
867
  return resolvedAuth;
@@ -932,9 +944,7 @@ exports.SseSubscriptionHandler = class SseSubscriptionHandler {
932
944
  return err instanceof common.HttpException ? err : this.serverError(err, what);
933
945
  }
934
946
  serverError(err, what) {
935
- this.logger.error(
936
- `${what} \u2014 responding 500: ${err instanceof Error ? err.message : String(err)}`
937
- );
947
+ this.logger.error(`${what} \u2014 responding 500: ${describeError(err)}`);
938
948
  return new common.InternalServerErrorException();
939
949
  }
940
950
  async authenticateRequest(req) {
@@ -1031,7 +1041,7 @@ exports.SseSubscriptionHandler = class SseSubscriptionHandler {
1031
1041
  */
1032
1042
  fireHook(invoke) {
1033
1043
  void Promise.resolve(invoke()).catch((err) => {
1034
- this.logger.warn(`Lifecycle hook failed: ${err.message}`);
1044
+ this.logger.warn(`Lifecycle hook failed: ${describeError(err)}`);
1035
1045
  });
1036
1046
  }
1037
1047
  };
@@ -1265,9 +1275,7 @@ exports.ReauthenticationService = class ReauthenticationService {
1265
1275
  }
1266
1276
  await this.handleFailure(conn);
1267
1277
  } catch (err) {
1268
- this.logger.warn(
1269
- `Reauthentication errored for ${conn.connectionId}: ${err.message}`
1270
- );
1278
+ this.logger.warn(`Reauthentication errored for ${conn.connectionId}: ${describeError(err)}`);
1271
1279
  await this.handleFailure(conn);
1272
1280
  }
1273
1281
  }
@@ -1293,7 +1301,7 @@ exports.ReauthenticationService = class ReauthenticationService {
1293
1301
  connectedAt: conn.connectedAt
1294
1302
  })
1295
1303
  ).catch((err) => {
1296
- this.logger.warn(`onReauthenticationFailed hook failed: ${err.message}`);
1304
+ this.logger.warn(`onReauthenticationFailed hook failed: ${describeError(err)}`);
1297
1305
  });
1298
1306
  await this.realtime.disconnect(conn.connectionId, REALTIME_ERROR_CODES.REAUTHENTICATION_FAILED);
1299
1307
  }
@@ -1488,7 +1496,7 @@ exports.RealtimePubSubSubscriber = class RealtimePubSubSubscriber {
1488
1496
  this.unsubscribe = await this.pubsub.subscribe((msg) => this.handle(msg));
1489
1497
  } catch (err) {
1490
1498
  this.logger.warn(
1491
- `Failed to subscribe to pub/sub: ${err.message}. Cross-instance fan-out disabled; remote events will not reach this instance.`
1499
+ `Failed to subscribe to pub/sub: ${describeError(err)}. Cross-instance fan-out disabled; remote events will not reach this instance.`
1492
1500
  );
1493
1501
  }
1494
1502
  }
@@ -1497,7 +1505,7 @@ exports.RealtimePubSubSubscriber = class RealtimePubSubSubscriber {
1497
1505
  try {
1498
1506
  await this.unsubscribe();
1499
1507
  } catch (err) {
1500
- this.logger.warn(`Pub/sub unsubscribe failed: ${err.message}`);
1508
+ this.logger.warn(`Pub/sub unsubscribe failed: ${describeError(err)}`);
1501
1509
  }
1502
1510
  this.unsubscribe = null;
1503
1511
  }
@@ -1537,7 +1545,7 @@ exports.RealtimePubSubSubscriber = class RealtimePubSubSubscriber {
1537
1545
  }
1538
1546
  }
1539
1547
  } catch (err) {
1540
- this.logger.warn(`Pub/sub message handling failed: ${err.message}`);
1548
+ this.logger.warn(`Pub/sub message handling failed: ${describeError(err)}`);
1541
1549
  }
1542
1550
  }
1543
1551
  };
@@ -1822,6 +1830,7 @@ exports.composeForRoot = composeForRoot;
1822
1830
  exports.composeForRootAsync = composeForRootAsync;
1823
1831
  exports.composeRoomId = composeRoomId;
1824
1832
  exports.createSseController = createSseController;
1833
+ exports.describeError = describeError;
1825
1834
  exports.parseCookieHeader = parseCookieHeader;
1826
1835
  exports.resolveAuthTenant = resolveAuthTenant;
1827
1836
  exports.sseWiring = sseWiring;
@@ -1549,6 +1549,13 @@ type RoomPrefix = (typeof ROOM_PREFIXES)[keyof typeof ROOM_PREFIXES];
1549
1549
  */
1550
1550
  declare function composeRoomId(prefix: keyof typeof ROOM_PREFIXES, ...parts: string[]): string;
1551
1551
 
1552
+ /**
1553
+ * @fileoverview Printable text for whatever a `catch` or a rejected promise delivered.
1554
+ * @layer utils
1555
+ */
1556
+ /** Describe a thrown or rejected value without throwing: `.message` on `null`, or `String()` on a prototype-less object, would. */
1557
+ declare function describeError(reason: unknown): string;
1558
+
1552
1559
  /**
1553
1560
  * @fileoverview Parser turning a raw HTTP `Cookie` header into a plain object.
1554
1561
  * @layer utils
@@ -1670,4 +1677,4 @@ declare const REALTIME_ERROR_CODES: {
1670
1677
  /** Union of canonical error code values. */
1671
1678
  type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[keyof typeof REALTIME_ERROR_CODES];
1672
1679
 
1673
- export { type AuthenticationResult, BymaxRealtimeModule, type BymaxRealtimeModuleAsyncOptions, type BymaxRealtimeModuleOptions, type BymaxRealtimeModuleOptionsFactory, type ConnectionAuthContext, type ConnectionEventMeta, ConnectionRegistry, type CorsConfig, EventIdGenerator, EventReplayBuffer, HeartbeatService, type IConnectionAuthenticator, type IConnectionLifecycleHooks, type IOfflineQueueStorage, type IPresenceStorage, type IRealtimePubSub, type ITransport, InMemoryPubSub, OfflineQueueDeliveryService, type OfflineQueuedEvent, type PublicConnectionMeta, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, RESERVED_EVENT_NAMES, ROOM_PREFIXES, type RealtimeErrorCode, type RealtimeEvent, type RealtimePubSubMessage, RealtimePubSubSubscriber, RealtimeService, type ReauthenticationPolicy, ReauthenticationService, RedisOfflineQueue, type RedisOfflineQueueOptions, RedisRealtimePubSub, type RedisRealtimePubSubOptions, type ReservedEventName, type RoomPrefix, RoomRegistry, type SseOptions, type SseRealtimeModuleAsyncOptions, type SseRealtimeModuleOptions, SseSubscriptionHandler, SseTransport, type TransportMode, type TransportRegistration, type TransportWiring, type WebSocketOptions, type WebSocketRealtimeModuleAsyncOptions, type WebSocketRealtimeModuleOptions, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, parseCookieHeader, resolveAuthTenant, sseWiring };
1680
+ export { type AuthenticationResult, BymaxRealtimeModule, type BymaxRealtimeModuleAsyncOptions, type BymaxRealtimeModuleOptions, type BymaxRealtimeModuleOptionsFactory, type ConnectionAuthContext, type ConnectionEventMeta, ConnectionRegistry, type CorsConfig, EventIdGenerator, EventReplayBuffer, HeartbeatService, type IConnectionAuthenticator, type IConnectionLifecycleHooks, type IOfflineQueueStorage, type IPresenceStorage, type IRealtimePubSub, type ITransport, InMemoryPubSub, OfflineQueueDeliveryService, type OfflineQueuedEvent, type PublicConnectionMeta, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, RESERVED_EVENT_NAMES, ROOM_PREFIXES, type RealtimeErrorCode, type RealtimeEvent, type RealtimePubSubMessage, RealtimePubSubSubscriber, RealtimeService, type ReauthenticationPolicy, ReauthenticationService, RedisOfflineQueue, type RedisOfflineQueueOptions, RedisRealtimePubSub, type RedisRealtimePubSubOptions, type ReservedEventName, type RoomPrefix, RoomRegistry, type SseOptions, type SseRealtimeModuleAsyncOptions, type SseRealtimeModuleOptions, SseSubscriptionHandler, SseTransport, type TransportMode, type TransportRegistration, type TransportWiring, type WebSocketOptions, type WebSocketRealtimeModuleAsyncOptions, type WebSocketRealtimeModuleOptions, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, resolveAuthTenant, sseWiring };
@@ -1549,6 +1549,13 @@ type RoomPrefix = (typeof ROOM_PREFIXES)[keyof typeof ROOM_PREFIXES];
1549
1549
  */
1550
1550
  declare function composeRoomId(prefix: keyof typeof ROOM_PREFIXES, ...parts: string[]): string;
1551
1551
 
1552
+ /**
1553
+ * @fileoverview Printable text for whatever a `catch` or a rejected promise delivered.
1554
+ * @layer utils
1555
+ */
1556
+ /** Describe a thrown or rejected value without throwing: `.message` on `null`, or `String()` on a prototype-less object, would. */
1557
+ declare function describeError(reason: unknown): string;
1558
+
1552
1559
  /**
1553
1560
  * @fileoverview Parser turning a raw HTTP `Cookie` header into a plain object.
1554
1561
  * @layer utils
@@ -1670,4 +1677,4 @@ declare const REALTIME_ERROR_CODES: {
1670
1677
  /** Union of canonical error code values. */
1671
1678
  type RealtimeErrorCode = (typeof REALTIME_ERROR_CODES)[keyof typeof REALTIME_ERROR_CODES];
1672
1679
 
1673
- export { type AuthenticationResult, BymaxRealtimeModule, type BymaxRealtimeModuleAsyncOptions, type BymaxRealtimeModuleOptions, type BymaxRealtimeModuleOptionsFactory, type ConnectionAuthContext, type ConnectionEventMeta, ConnectionRegistry, type CorsConfig, EventIdGenerator, EventReplayBuffer, HeartbeatService, type IConnectionAuthenticator, type IConnectionLifecycleHooks, type IOfflineQueueStorage, type IPresenceStorage, type IRealtimePubSub, type ITransport, InMemoryPubSub, OfflineQueueDeliveryService, type OfflineQueuedEvent, type PublicConnectionMeta, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, RESERVED_EVENT_NAMES, ROOM_PREFIXES, type RealtimeErrorCode, type RealtimeEvent, type RealtimePubSubMessage, RealtimePubSubSubscriber, RealtimeService, type ReauthenticationPolicy, ReauthenticationService, RedisOfflineQueue, type RedisOfflineQueueOptions, RedisRealtimePubSub, type RedisRealtimePubSubOptions, type ReservedEventName, type RoomPrefix, RoomRegistry, type SseOptions, type SseRealtimeModuleAsyncOptions, type SseRealtimeModuleOptions, SseSubscriptionHandler, SseTransport, type TransportMode, type TransportRegistration, type TransportWiring, type WebSocketOptions, type WebSocketRealtimeModuleAsyncOptions, type WebSocketRealtimeModuleOptions, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, parseCookieHeader, resolveAuthTenant, sseWiring };
1680
+ export { type AuthenticationResult, BymaxRealtimeModule, type BymaxRealtimeModuleAsyncOptions, type BymaxRealtimeModuleOptions, type BymaxRealtimeModuleOptionsFactory, type ConnectionAuthContext, type ConnectionEventMeta, ConnectionRegistry, type CorsConfig, EventIdGenerator, EventReplayBuffer, HeartbeatService, type IConnectionAuthenticator, type IConnectionLifecycleHooks, type IOfflineQueueStorage, type IPresenceStorage, type IRealtimePubSub, type ITransport, InMemoryPubSub, OfflineQueueDeliveryService, type OfflineQueuedEvent, type PublicConnectionMeta, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, RESERVED_EVENT_NAMES, ROOM_PREFIXES, type RealtimeErrorCode, type RealtimeEvent, type RealtimePubSubMessage, RealtimePubSubSubscriber, RealtimeService, type ReauthenticationPolicy, ReauthenticationService, RedisOfflineQueue, type RedisOfflineQueueOptions, RedisRealtimePubSub, type RedisRealtimePubSubOptions, type ReservedEventName, type RoomPrefix, RoomRegistry, type SseOptions, type SseRealtimeModuleAsyncOptions, type SseRealtimeModuleOptions, SseSubscriptionHandler, SseTransport, type TransportMode, type TransportRegistration, type TransportWiring, type WebSocketOptions, type WebSocketRealtimeModuleAsyncOptions, type WebSocketRealtimeModuleOptions, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, resolveAuthTenant, sseWiring };
@@ -103,6 +103,18 @@ var REALTIME_PRESENCE_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_PRESENCE");
103
103
  var REALTIME_HOOKS_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_HOOKS");
104
104
  var REALTIME_INSTANCE_ID_TOKEN = /* @__PURE__ */ Symbol("BYMAX_REALTIME_INSTANCE_ID");
105
105
  var DEFAULT_HEARTBEAT_MS = 3e4;
106
+
107
+ // src/server/utils/describe-error.ts
108
+ function describeError(reason) {
109
+ try {
110
+ const message = reason?.message;
111
+ return typeof message === "string" ? message : String(reason);
112
+ } catch {
113
+ return "unprintable error";
114
+ }
115
+ }
116
+
117
+ // src/server/offline-queue/offline-queue-delivery.service.ts
106
118
  var RETRIEVE_LIMIT = 200;
107
119
  var OfflineQueueDeliveryService = class {
108
120
  constructor(storage) {
@@ -129,7 +141,7 @@ var OfflineQueueDeliveryService = class {
129
141
  try {
130
142
  events = await this.storage.retrieveSince(userId, lastEventId, RETRIEVE_LIMIT);
131
143
  } catch (err) {
132
- this.logger.warn(`Offline queue retrieve failed: ${err.message}`);
144
+ this.logger.warn(`Offline queue retrieve failed: ${describeError(err)}`);
133
145
  return [];
134
146
  }
135
147
  if (events.length === RETRIEVE_LIMIT) {
@@ -156,7 +168,7 @@ var OfflineQueueDeliveryService = class {
156
168
  try {
157
169
  await this.storage.acknowledge(userId, lastId);
158
170
  } catch (err) {
159
- this.logger.warn(`Offline queue acknowledge failed: ${err.message}`);
171
+ this.logger.warn(`Offline queue acknowledge failed: ${describeError(err)}`);
160
172
  }
161
173
  }
162
174
  };
@@ -568,7 +580,7 @@ var SseTransport = class {
568
580
  ...reason !== void 0 ? { reason } : {}
569
581
  });
570
582
  } catch (error) {
571
- this.logger.error(`onDisconnect hook failed: ${error.message}`);
583
+ this.logger.error(`onDisconnect hook failed: ${describeError(error)}`);
572
584
  }
573
585
  }
574
586
  /** Replay the events a user missed after `lastEventId`. */
@@ -599,7 +611,7 @@ var SseTransport = class {
599
611
  this.emitToUserLocal(userId, event, data, id);
600
612
  if (this.offlineQueue && this.connections.byUser(userId, "sse").length === 0) {
601
613
  void this.offlineQueue.append(userId, { id, event, data, emittedAt: /* @__PURE__ */ new Date() }).catch(
602
- (error) => this.logger.warn(`Offline queue append failed: ${error.message}`)
614
+ (error) => this.logger.warn(`Offline queue append failed: ${describeError(error)}`)
603
615
  );
604
616
  }
605
617
  await this.publish({ op: "emitToUser", args: { userId, event, data, id } });
@@ -705,7 +717,7 @@ var SseTransport = class {
705
717
  try {
706
718
  conn.subject?.next(message);
707
719
  } catch (error) {
708
- this.logger.warn(`SSE delivery failed for ${conn.connectionId}: ${error.message}`);
720
+ this.logger.warn(`SSE delivery failed for ${conn.connectionId}: ${describeError(error)}`);
709
721
  }
710
722
  }
711
723
  /** Publish once to the bus; pub/sub failures never affect the live emit path. */
@@ -713,7 +725,7 @@ var SseTransport = class {
713
725
  try {
714
726
  await this.pubsub.publish({ ...message, origin: this.instanceId });
715
727
  } catch (error) {
716
- this.logger.warn(`pubsub.publish failed: ${error.message}`);
728
+ this.logger.warn(`pubsub.publish failed: ${describeError(error)}`);
717
729
  }
718
730
  }
719
731
  /** Evict a user's oldest connections (FIFO) when over `maxConnectionsPerUser`. */
@@ -847,7 +859,7 @@ var SseSubscriptionHandler = class {
847
859
  try {
848
860
  assertIdentityIsNotBlank(resolvedAuth);
849
861
  } catch (err) {
850
- this.logger.error(`SSE connection refused \u2014 responding 500: ${err.message}`);
862
+ this.logger.error(`SSE connection refused \u2014 responding 500: ${describeError(err)}`);
851
863
  throw new InternalServerErrorException();
852
864
  }
853
865
  return resolvedAuth;
@@ -930,9 +942,7 @@ var SseSubscriptionHandler = class {
930
942
  return err instanceof HttpException ? err : this.serverError(err, what);
931
943
  }
932
944
  serverError(err, what) {
933
- this.logger.error(
934
- `${what} \u2014 responding 500: ${err instanceof Error ? err.message : String(err)}`
935
- );
945
+ this.logger.error(`${what} \u2014 responding 500: ${describeError(err)}`);
936
946
  return new InternalServerErrorException();
937
947
  }
938
948
  async authenticateRequest(req) {
@@ -1029,7 +1039,7 @@ var SseSubscriptionHandler = class {
1029
1039
  */
1030
1040
  fireHook(invoke) {
1031
1041
  void Promise.resolve(invoke()).catch((err) => {
1032
- this.logger.warn(`Lifecycle hook failed: ${err.message}`);
1042
+ this.logger.warn(`Lifecycle hook failed: ${describeError(err)}`);
1033
1043
  });
1034
1044
  }
1035
1045
  };
@@ -1263,9 +1273,7 @@ var ReauthenticationService = class {
1263
1273
  }
1264
1274
  await this.handleFailure(conn);
1265
1275
  } catch (err) {
1266
- this.logger.warn(
1267
- `Reauthentication errored for ${conn.connectionId}: ${err.message}`
1268
- );
1276
+ this.logger.warn(`Reauthentication errored for ${conn.connectionId}: ${describeError(err)}`);
1269
1277
  await this.handleFailure(conn);
1270
1278
  }
1271
1279
  }
@@ -1291,7 +1299,7 @@ var ReauthenticationService = class {
1291
1299
  connectedAt: conn.connectedAt
1292
1300
  })
1293
1301
  ).catch((err) => {
1294
- this.logger.warn(`onReauthenticationFailed hook failed: ${err.message}`);
1302
+ this.logger.warn(`onReauthenticationFailed hook failed: ${describeError(err)}`);
1295
1303
  });
1296
1304
  await this.realtime.disconnect(conn.connectionId, REALTIME_ERROR_CODES.REAUTHENTICATION_FAILED);
1297
1305
  }
@@ -1486,7 +1494,7 @@ var RealtimePubSubSubscriber = class {
1486
1494
  this.unsubscribe = await this.pubsub.subscribe((msg) => this.handle(msg));
1487
1495
  } catch (err) {
1488
1496
  this.logger.warn(
1489
- `Failed to subscribe to pub/sub: ${err.message}. Cross-instance fan-out disabled; remote events will not reach this instance.`
1497
+ `Failed to subscribe to pub/sub: ${describeError(err)}. Cross-instance fan-out disabled; remote events will not reach this instance.`
1490
1498
  );
1491
1499
  }
1492
1500
  }
@@ -1495,7 +1503,7 @@ var RealtimePubSubSubscriber = class {
1495
1503
  try {
1496
1504
  await this.unsubscribe();
1497
1505
  } catch (err) {
1498
- this.logger.warn(`Pub/sub unsubscribe failed: ${err.message}`);
1506
+ this.logger.warn(`Pub/sub unsubscribe failed: ${describeError(err)}`);
1499
1507
  }
1500
1508
  this.unsubscribe = null;
1501
1509
  }
@@ -1535,7 +1543,7 @@ var RealtimePubSubSubscriber = class {
1535
1543
  }
1536
1544
  }
1537
1545
  } catch (err) {
1538
- this.logger.warn(`Pub/sub message handling failed: ${err.message}`);
1546
+ this.logger.warn(`Pub/sub message handling failed: ${describeError(err)}`);
1539
1547
  }
1540
1548
  }
1541
1549
  };
@@ -1802,4 +1810,4 @@ var RedisOfflineQueue = class _RedisOfflineQueue {
1802
1810
  }
1803
1811
  };
1804
1812
 
1805
- export { BymaxRealtimeModule, ConnectionRegistry, EventIdGenerator, EventReplayBuffer, HeartbeatService, InMemoryPubSub, OfflineQueueDeliveryService, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, RESERVED_EVENT_NAMES, ROOM_PREFIXES, RealtimePubSubSubscriber, RealtimeService, ReauthenticationService, RedisOfflineQueue, RedisRealtimePubSub, RoomRegistry, SseSubscriptionHandler, SseTransport, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, parseCookieHeader, resolveAuthTenant, sseWiring };
1813
+ export { BymaxRealtimeModule, ConnectionRegistry, EventIdGenerator, EventReplayBuffer, HeartbeatService, InMemoryPubSub, OfflineQueueDeliveryService, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_ERROR_CODES, REALTIME_HOOKS_TOKEN, REALTIME_INSTANCE_ID_TOKEN, REALTIME_OFFLINE_QUEUE_TOKEN, REALTIME_OPTIONS_TOKEN, REALTIME_PRESENCE_TOKEN, REALTIME_PUBSUB_TOKEN, REALTIME_TRANSPORT_TOKEN, RESERVED_EVENT_NAMES, ROOM_PREFIXES, RealtimePubSubSubscriber, RealtimeService, ReauthenticationService, RedisOfflineQueue, RedisRealtimePubSub, RoomRegistry, SseSubscriptionHandler, SseTransport, assertIdentityIsNotBlank, composeForRoot, composeForRootAsync, composeRoomId, createSseController, describeError, parseCookieHeader, resolveAuthTenant, sseWiring };
@@ -381,9 +381,7 @@ exports.CompositeTransport = class CompositeTransport {
381
381
  const results = await Promise.allSettled(tasks.map((t) => t()));
382
382
  for (const result of results) {
383
383
  if (result.status === "rejected") {
384
- this.logger.warn(
385
- `Composite ${op} partially failed: ${result.reason.message ?? result.reason}`
386
- );
384
+ this.logger.warn(`Composite ${op} partially failed: ${internal.describeError(result.reason)}`);
387
385
  }
388
386
  }
389
387
  }
@@ -464,7 +462,7 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends platformSocket_io.IoAda
464
462
  const sub = pub.duplicate();
465
463
  server.adapter(createAdapter(pub, sub));
466
464
  } catch (err) {
467
- const reason = err instanceof Error ? err.message : String(err);
465
+ const reason = internal.describeError(err);
468
466
  throw new Error(
469
467
  `[${_RealtimeIoAdapter.name}] ${internal.REALTIME_ERROR_CODES.REDIS_ADAPTER_FAILED}: 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.`,
470
468
  { cause: err }
@@ -506,9 +504,7 @@ exports.RealtimeGateway = class RealtimeGateway {
506
504
  this.authenticated.set(socket, resolvedAuth);
507
505
  next();
508
506
  } catch (err) {
509
- this.logger.error(
510
- `handshake refused for socket ${socket.id}: ${err instanceof Error ? err.message : String(err)}`
511
- );
507
+ this.logger.error(`handshake refused for socket ${socket.id}: ${internal.describeError(err)}`);
512
508
  next(new Error("Internal Server Error"));
513
509
  }
514
510
  };
@@ -602,7 +598,7 @@ exports.RealtimeGateway = class RealtimeGateway {
602
598
  }
603
599
  } catch (err) {
604
600
  this.logger.error(
605
- `handleConnection threw for socket ${socket.id} \u2014 disconnecting: ${err instanceof Error ? err.message : String(err)}`
601
+ `handleConnection threw for socket ${socket.id} \u2014 disconnecting: ${internal.describeError(err)}`
606
602
  );
607
603
  socket.disconnect(true);
608
604
  }
@@ -1,6 +1,6 @@
1
1
  import { createRequire } from 'node:module';
2
2
  import { Injectable, Inject, Logger, Global, Module } from '@nestjs/common';
3
- import { ConnectionRegistry, RoomRegistry, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_HOOKS_TOKEN, REALTIME_OPTIONS_TOKEN, SseTransport, ROOM_PREFIXES, REALTIME_ERROR_CODES, composeForRoot, composeForRootAsync, REALTIME_TRANSPORT_TOKEN, SseSubscriptionHandler, RealtimePubSubSubscriber, createSseController, resolveAuthTenant, assertIdentityIsNotBlank, parseCookieHeader, RESERVED_EVENT_NAMES } from '@bymax-one/nest-realtime/internal';
3
+ import { ConnectionRegistry, RoomRegistry, REALTIME_AUTHENTICATOR_TOKEN, REALTIME_HOOKS_TOKEN, REALTIME_OPTIONS_TOKEN, SseTransport, ROOM_PREFIXES, REALTIME_ERROR_CODES, composeForRoot, composeForRootAsync, REALTIME_TRANSPORT_TOKEN, SseSubscriptionHandler, RealtimePubSubSubscriber, createSseController, resolveAuthTenant, assertIdentityIsNotBlank, describeError, parseCookieHeader, RESERVED_EVENT_NAMES } from '@bymax-one/nest-realtime/internal';
4
4
  import { WebSocketServer, WebSocketGateway } from '@nestjs/websockets';
5
5
  import { IoAdapter } from '@nestjs/platform-socket.io';
6
6
 
@@ -381,9 +381,7 @@ var CompositeTransport = class {
381
381
  const results = await Promise.allSettled(tasks.map((t) => t()));
382
382
  for (const result of results) {
383
383
  if (result.status === "rejected") {
384
- this.logger.warn(
385
- `Composite ${op} partially failed: ${result.reason.message ?? result.reason}`
386
- );
384
+ this.logger.warn(`Composite ${op} partially failed: ${describeError(result.reason)}`);
387
385
  }
388
386
  }
389
387
  }
@@ -464,7 +462,7 @@ var RealtimeIoAdapter = class _RealtimeIoAdapter extends IoAdapter {
464
462
  const sub = pub.duplicate();
465
463
  server.adapter(createAdapter(pub, sub));
466
464
  } catch (err) {
467
- const reason = err instanceof Error ? err.message : String(err);
465
+ const reason = describeError(err);
468
466
  throw new Error(
469
467
  `[${_RealtimeIoAdapter.name}] ${REALTIME_ERROR_CODES.REDIS_ADAPTER_FAILED}: 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.`,
470
468
  { cause: err }
@@ -506,9 +504,7 @@ var RealtimeGateway = class {
506
504
  this.authenticated.set(socket, resolvedAuth);
507
505
  next();
508
506
  } catch (err) {
509
- this.logger.error(
510
- `handshake refused for socket ${socket.id}: ${err instanceof Error ? err.message : String(err)}`
511
- );
507
+ this.logger.error(`handshake refused for socket ${socket.id}: ${describeError(err)}`);
512
508
  next(new Error("Internal Server Error"));
513
509
  }
514
510
  };
@@ -602,7 +598,7 @@ var RealtimeGateway = class {
602
598
  }
603
599
  } catch (err) {
604
600
  this.logger.error(
605
- `handleConnection threw for socket ${socket.id} \u2014 disconnecting: ${err instanceof Error ? err.message : String(err)}`
601
+ `handleConnection threw for socket ${socket.id} \u2014 disconnecting: ${describeError(err)}`
606
602
  );
607
603
  socket.disconnect(true);
608
604
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-realtime",
3
- "version": "1.2.3",
3
+ "version": "1.2.4",
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",
@@ -98,6 +98,7 @@
98
98
  "check:mutants": "node scripts/check-mutation-directives.mjs",
99
99
  "check:published": "node scripts/check-published-surface.mjs",
100
100
  "check:runtime": "node scripts/check-consumer-runtime.mjs",
101
+ "benchmark": "node scripts/benchmark/run.mjs",
101
102
  "check:surface": "node scripts/check-public-surface.mjs",
102
103
  "clean": "rm -rf dist coverage",
103
104
  "lint": "eslint src",