@bymax-one/nest-realtime 1.2.6 → 1.2.8

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.
@@ -81,16 +81,22 @@ declare class WebSocketTransport implements ITransport {
81
81
  private readonly logger;
82
82
  /** Nullable until the gateway's afterInit wires the instance. */
83
83
  private server;
84
+ private warnedUnattached;
84
85
  constructor(connections: ConnectionRegistry, rooms: RoomRegistry, auth: IConnectionAuthenticator, hooks: IConnectionLifecycleHooks, options: BymaxRealtimeModuleOptions);
85
86
  /**
86
87
  * Wire the Socket.IO server. Called by `RealtimeGateway.afterInit`.
87
88
  *
88
- * All emit methods silently no-op until this is called, so the transport is
89
- * safe to construct before the HTTP server is ready.
89
+ * Until this is called an emit delivers nothing and still resolves, with one warning for
90
+ * the first, so the transport is safe to construct before the HTTP server is ready.
90
91
  *
91
92
  * @param server - The live Socket.IO `Server` instance from the NestJS gateway.
92
93
  */
93
94
  setServer(server: Server): void;
95
+ /**
96
+ * The attached server, or `null` before the gateway attaches one. An emit made before
97
+ * then delivers nothing and still resolves; that is logged once, not once per emit.
98
+ */
99
+ private attached;
94
100
  /**
95
101
  * Resolve the map of locally-connected sockets, tolerating both server shapes.
96
102
  *
@@ -193,6 +199,8 @@ declare class WebSocketTransport implements ITransport {
193
199
  *
194
200
  * @param connectionId - The socket `id` of the connection to disconnect.
195
201
  * @param _reason - Optional reason string (unused at the Socket.IO level; passed to `unregisterSocket`).
202
+ * @throws {Error} `REALTIME_TRANSPORT_UNAVAILABLE` when no server is attached or the
203
+ * fan-out throws: the revocation did not leave this node.
196
204
  */
197
205
  disconnect(connectionId: string, _reason?: string): Promise<void>;
198
206
  /**
@@ -344,10 +352,12 @@ declare class RealtimeIoAdapter extends IoAdapter {
344
352
  * parallel via `Promise.allSettled` so a failure in one never aborts the other.
345
353
  * Failures are logged as warnings without rethrowing.
346
354
  *
347
- * `joinRoom`, `leaveRoom`, and `disconnect` attempt both transports tolerantly:
348
- * only the transport that owns the connection will succeed; the other's rejection
349
- * is swallowed. There is no double-delivery because each connection lives on
350
- * exactly one transport.
355
+ * `joinRoom`, `leaveRoom`, and `disconnect` ask both transports and settle both: each
356
+ * transport acts only on a connection it holds, and a connection neither holds is handed
357
+ * to the bus (SSE) and the adapter (WebSocket) for the instance that does. A failure of
358
+ * either one rejects the call, because a revocation or a room change that did not happen
359
+ * must not be reported as done. There is no double-delivery because each connection lives
360
+ * on exactly one transport.
351
361
  *
352
362
  * `kind` reports `'sse'` (the dominant transport); `ITransport.kind` is
353
363
  * `'sse' | 'websocket'` — `'both'` is a module-level `TransportMode`, not a
@@ -393,23 +403,32 @@ declare class CompositeTransport implements ITransport {
393
403
  /**
394
404
  * Join a connection to a room.
395
405
  *
396
- * Both transports are attempted; only the one that owns the connection
397
- * succeeds. The other's failure is expected and swallowed.
406
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
407
+ * failure of whichever transport failed.
398
408
  */
399
409
  joinRoom(connectionId: string, roomId: string): Promise<void>;
400
410
  /**
401
411
  * Remove a connection from a room.
402
412
  *
403
- * Both transports are attempted tolerantly — one will succeed, the other
404
- * may fail silently.
413
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
414
+ * failure of whichever transport failed: a client left in a room it was removed from keeps
415
+ * receiving that room's events.
405
416
  */
406
417
  leaveRoom(connectionId: string, roomId: string): Promise<void>;
407
418
  /**
408
419
  * Disconnect a specific connection.
409
420
  *
410
- * Both transports are attempted; the one owning the connection disconnects it.
421
+ * Both transports are asked; the one that holds the connection disconnects it. Rejects when
422
+ * either one could not: the revocation has not reached the connection.
411
423
  */
412
424
  disconnect(connectionId: string, reason?: string): Promise<void>;
425
+ /**
426
+ * Run a per-connection operation on both transports and reject if either failed.
427
+ *
428
+ * One failure is rethrown as it is; both are reported together under
429
+ * `REALTIME_TRANSPORT_UNAVAILABLE`, with every reason in `cause`.
430
+ */
431
+ private settleBoth;
413
432
  /**
414
433
  * Run two transport tasks in parallel via `Promise.allSettled`.
415
434
  *
@@ -81,16 +81,22 @@ declare class WebSocketTransport implements ITransport {
81
81
  private readonly logger;
82
82
  /** Nullable until the gateway's afterInit wires the instance. */
83
83
  private server;
84
+ private warnedUnattached;
84
85
  constructor(connections: ConnectionRegistry, rooms: RoomRegistry, auth: IConnectionAuthenticator, hooks: IConnectionLifecycleHooks, options: BymaxRealtimeModuleOptions);
85
86
  /**
86
87
  * Wire the Socket.IO server. Called by `RealtimeGateway.afterInit`.
87
88
  *
88
- * All emit methods silently no-op until this is called, so the transport is
89
- * safe to construct before the HTTP server is ready.
89
+ * Until this is called an emit delivers nothing and still resolves, with one warning for
90
+ * the first, so the transport is safe to construct before the HTTP server is ready.
90
91
  *
91
92
  * @param server - The live Socket.IO `Server` instance from the NestJS gateway.
92
93
  */
93
94
  setServer(server: Server): void;
95
+ /**
96
+ * The attached server, or `null` before the gateway attaches one. An emit made before
97
+ * then delivers nothing and still resolves; that is logged once, not once per emit.
98
+ */
99
+ private attached;
94
100
  /**
95
101
  * Resolve the map of locally-connected sockets, tolerating both server shapes.
96
102
  *
@@ -193,6 +199,8 @@ declare class WebSocketTransport implements ITransport {
193
199
  *
194
200
  * @param connectionId - The socket `id` of the connection to disconnect.
195
201
  * @param _reason - Optional reason string (unused at the Socket.IO level; passed to `unregisterSocket`).
202
+ * @throws {Error} `REALTIME_TRANSPORT_UNAVAILABLE` when no server is attached or the
203
+ * fan-out throws: the revocation did not leave this node.
196
204
  */
197
205
  disconnect(connectionId: string, _reason?: string): Promise<void>;
198
206
  /**
@@ -344,10 +352,12 @@ declare class RealtimeIoAdapter extends IoAdapter {
344
352
  * parallel via `Promise.allSettled` so a failure in one never aborts the other.
345
353
  * Failures are logged as warnings without rethrowing.
346
354
  *
347
- * `joinRoom`, `leaveRoom`, and `disconnect` attempt both transports tolerantly:
348
- * only the transport that owns the connection will succeed; the other's rejection
349
- * is swallowed. There is no double-delivery because each connection lives on
350
- * exactly one transport.
355
+ * `joinRoom`, `leaveRoom`, and `disconnect` ask both transports and settle both: each
356
+ * transport acts only on a connection it holds, and a connection neither holds is handed
357
+ * to the bus (SSE) and the adapter (WebSocket) for the instance that does. A failure of
358
+ * either one rejects the call, because a revocation or a room change that did not happen
359
+ * must not be reported as done. There is no double-delivery because each connection lives
360
+ * on exactly one transport.
351
361
  *
352
362
  * `kind` reports `'sse'` (the dominant transport); `ITransport.kind` is
353
363
  * `'sse' | 'websocket'` — `'both'` is a module-level `TransportMode`, not a
@@ -393,23 +403,32 @@ declare class CompositeTransport implements ITransport {
393
403
  /**
394
404
  * Join a connection to a room.
395
405
  *
396
- * Both transports are attempted; only the one that owns the connection
397
- * succeeds. The other's failure is expected and swallowed.
406
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
407
+ * failure of whichever transport failed.
398
408
  */
399
409
  joinRoom(connectionId: string, roomId: string): Promise<void>;
400
410
  /**
401
411
  * Remove a connection from a room.
402
412
  *
403
- * Both transports are attempted tolerantly — one will succeed, the other
404
- * may fail silently.
413
+ * Both transports are asked; the one that holds the connection acts. Rejects with the
414
+ * failure of whichever transport failed: a client left in a room it was removed from keeps
415
+ * receiving that room's events.
405
416
  */
406
417
  leaveRoom(connectionId: string, roomId: string): Promise<void>;
407
418
  /**
408
419
  * Disconnect a specific connection.
409
420
  *
410
- * Both transports are attempted; the one owning the connection disconnects it.
421
+ * Both transports are asked; the one that holds the connection disconnects it. Rejects when
422
+ * either one could not: the revocation has not reached the connection.
411
423
  */
412
424
  disconnect(connectionId: string, reason?: string): Promise<void>;
425
+ /**
426
+ * Run a per-connection operation on both transports and reject if either failed.
427
+ *
428
+ * One failure is rethrown as it is; both are reported together under
429
+ * `REALTIME_TRANSPORT_UNAVAILABLE`, with every reason in `cause`.
430
+ */
431
+ private settleBoth;
413
432
  /**
414
433
  * Run two transport tasks in parallel via `Promise.allSettled`.
415
434
  *