@bymax-one/nest-realtime 1.1.0 → 1.1.1

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
@@ -5,6 +5,57 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.1.1] - 2026-08-21
9
+
10
+ ### Added
11
+
12
+ - **`ConnectionEventMeta` now carries `roles`.** `IConnectionAuthenticator.authenticate` returns
13
+ `roles` and `ConnectionRecord.originalAuth` stores them, but the meta the lifecycle hooks
14
+ receive dropped them — so a host authenticating by role could not act on the role at
15
+ `onConnect`, the one point that has a `connectionId` and knows the connection is new. With no
16
+ role-scoped fan-out and a registry indexed by id, userId and tenantId, a room is the only
17
+ mechanism for "these connections and not those", and a room could not be built on a value that
18
+ never arrived. Threaded through all five meta construction sites — SSE and WebSocket
19
+ `onConnect`/`onDisconnect` plus `onReauthenticationFailed` — because roles present at connect
20
+ and absent at disconnect would be a field that lies by omission exactly when a host cleans up.
21
+
22
+ **This adds a required key.** Reading the meta is unaffected, which is what a hook does; code
23
+ that *constructs* a `ConnectionEventMeta` (typically a test fixture) must now supply `roles`.
24
+ `undefined` stays meaningful for an authenticator that returns none.
25
+
26
+ Roles are carried, never interpreted: there is deliberately no `emitToRole`. Indexing a
27
+ fan-out on a role would put the consumer's authorization vocabulary into the transport's API,
28
+ and `meta.roles` is a connect-time snapshot — a role-indexed emit would look authoritative
29
+ while reading state that can go stale. Room-plus-`onConnect` leaves that decision with the
30
+ host. The pattern is documented in the README and covered by an executable test.
31
+
32
+ ### Fixed
33
+
34
+ - **`forRootAsync` rejected typed factories and abstract `inject` tokens.** `useFactory` was an
35
+ arrow-property signature, so `strictFunctionTypes` checked it contravariantly and rejected
36
+ every factory whose parameters carried real provider types — including the
37
+ `useFactory: (cfg: ConfigService) => ...` example in this module's own JSDoc, which had never
38
+ typechecked for a consumer. Method shorthand is bivariant, which is what makes `inject` usable.
39
+ Separately, `inject` accepted only `Type<unknown>`, a non-abstract constructor type, which
40
+ excluded Nest's own abstract tokens — `ModuleRef` among them, and therefore the documented
41
+ role-scoped room pattern. Widened with `Abstract<unknown>`.
42
+
43
+ ### Documentation
44
+
45
+ - The README's Rooms section gains a **role-scoped delivery** subsection: how to build a
46
+ role room in `onConnect`, why there is no `emitToRole`, and the snapshot semantics of
47
+ `meta.roles` — a `revalidate` that keeps a connection alive does not refresh it.
48
+ - The `[Unreleased]` compare link pointed at `v1.0.5`, left behind when 1.1.0 shipped, so it
49
+ showed the whole 1.1.0 release as unreleased.
50
+
51
+ ### Tests
52
+
53
+ - The documented role-scoped room pattern is now an executable test rather than prose
54
+ (`realtime.module.documented-patterns.spec.ts`): it boots the module exactly as the README
55
+ shows and asserts both halves — the admin connection reaches `role:admin`, and a `viewer` and
56
+ a roles-`undefined` connection reach nothing. `pnpm typecheck` covers it, so reverting either
57
+ option-type change fails there.
58
+
8
59
  ## [1.1.0] - 2026-08-11
9
60
 
10
61
  ### Changed
@@ -242,7 +293,8 @@ First published release.
242
293
  rather than by the manual sweep that raised the NestJS floors — that sweep
243
294
  asked about NestJS and never put the same question to the other ten peers.
244
295
 
245
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.0.5...HEAD
296
+ [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.1.1...HEAD
297
+ [1.1.1]: https://github.com/bymaxone/nest-realtime/compare/v1.1.0...v1.1.1
246
298
  [1.1.0]: https://github.com/bymaxone/nest-realtime/compare/v1.0.6...v1.1.0
247
299
  [1.0.6]: https://github.com/bymaxone/nest-realtime/compare/v1.0.5...v1.0.6
248
300
  [1.0.5]: https://github.com/bymaxone/nest-realtime/compare/v1.0.4...v1.0.5
package/README.md CHANGED
@@ -544,6 +544,50 @@ composeRoomId('TENANT', tenantId) // → "tenant:t_acme"
544
544
  composeRoomId('RESOURCE', 'invoice', invoiceId) // → "resource:invoice:42"
545
545
  ```
546
546
 
547
+ #### Role-scoped delivery
548
+
549
+ There is no `emitToRole`. Roles are the consumer's authorization vocabulary, not
550
+ the transport's — the library carries them through without interpreting them (see
551
+ [Auth Inversion](#auth-inversion)). To deliver to a subset of connections by role,
552
+ build a room for it in `onConnect`, where `ConnectionEventMeta.roles` carries the
553
+ snapshot the authenticator produced:
554
+
555
+ ```typescript
556
+ import { ModuleRef } from '@nestjs/core'
557
+ import { BymaxRealtimeModule, RealtimeService } from '@bymax-one/nest-realtime'
558
+
559
+ BymaxRealtimeModule.forRootAsync({
560
+ transport: 'sse',
561
+ inject: [ModuleRef],
562
+ useFactory: (moduleRef: ModuleRef) => ({
563
+ transport: 'sse' as const,
564
+ authenticator: new CookieAuthenticator(),
565
+ hooks: {
566
+ onConnect: async (meta) => {
567
+ if (!meta.roles?.includes('admin')) return
568
+ // Resolved lazily: the hook runs per connection, long after bootstrap, so
569
+ // `RealtimeService` — provided by this very module — cannot be injected
570
+ // into the factory that configures it.
571
+ const realtime = moduleRef.get(RealtimeService)
572
+ await realtime.joinRoom(meta.connectionId, 'role:admin')
573
+ },
574
+ },
575
+ }),
576
+ })
577
+ ```
578
+
579
+ Then deliver to exactly those connections from any provider that injects
580
+ `RealtimeService`:
581
+
582
+ ```typescript
583
+ await this.realtime.emitToRoom('role:admin', 'audit.log', entry)
584
+ ```
585
+
586
+ `meta.roles` is a snapshot taken at connect time; a later `revalidate` that keeps
587
+ the connection alive does not refresh it. When a role can be revoked mid-session,
588
+ make `revalidate` return `false` so the connection is torn down and re-established
589
+ with the new roles.
590
+
547
591
  ### Reserved Events
548
592
 
549
593
  Emitted by the library. Do not reuse these names for application events.
@@ -525,6 +525,7 @@ exports.SseTransport = class SseTransport {
525
525
  connectionId: record.connectionId,
526
526
  userId: record.userId,
527
527
  tenantId: record.tenantId,
528
+ roles: record.originalAuth.roles,
528
529
  transport: "sse",
529
530
  ip: record.ip,
530
531
  userAgent: record.userAgent,
@@ -761,6 +762,7 @@ function buildMeta(record) {
761
762
  connectionId: record.connectionId,
762
763
  userId: record.userId,
763
764
  tenantId: record.tenantId,
765
+ roles: record.originalAuth.roles,
764
766
  transport: "sse",
765
767
  ip: record.ip,
766
768
  userAgent: record.userAgent,
@@ -1135,6 +1137,7 @@ exports.ReauthenticationService = class ReauthenticationService {
1135
1137
  connectionId: conn.connectionId,
1136
1138
  userId: conn.userId,
1137
1139
  tenantId: conn.tenantId,
1140
+ roles: conn.originalAuth.roles,
1138
1141
  transport: "sse",
1139
1142
  ip: conn.ip,
1140
1143
  userAgent: conn.userAgent,
@@ -1,4 +1,4 @@
1
- import { ModuleMetadata, Type, Provider, Logger, DynamicModule, MessageEvent, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
1
+ import { ModuleMetadata, Type, Abstract, Provider, Logger, DynamicModule, MessageEvent, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
2
2
  import { Subject, Observable } from 'rxjs';
3
3
  import { Redis } from 'ioredis';
4
4
 
@@ -121,6 +121,16 @@ interface ConnectionEventMeta {
121
121
  readonly connectionId: string;
122
122
  readonly userId: string;
123
123
  readonly tenantId: string | undefined;
124
+ /**
125
+ * Roles the authenticator returned for this connection, as a snapshot taken at
126
+ * connect time — `undefined` when the authenticator returned none.
127
+ *
128
+ * The library never interprets a role; it carries the consumer's own
129
+ * authorization vocabulary through so `onConnect` can act on it (typically by
130
+ * joining the connection to a role-scoped room). A later `revalidate` that
131
+ * keeps the connection alive does not refresh this snapshot.
132
+ */
133
+ readonly roles: readonly string[] | undefined;
124
134
  readonly transport: 'sse' | 'websocket';
125
135
  readonly ip: string;
126
136
  readonly userAgent: string | undefined;
@@ -324,8 +334,24 @@ interface BymaxRealtimeModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'
324
334
  * `transport` the factory resolves; a mismatch fails fast at bootstrap.
325
335
  */
326
336
  transport: TransportMode;
327
- useFactory?: (...args: unknown[]) => BymaxRealtimeModuleOptions | Promise<BymaxRealtimeModuleOptions>;
328
- inject?: readonly (string | symbol | Type<unknown>)[];
337
+ /**
338
+ * Factory producing the options, receiving whatever `inject` resolves.
339
+ *
340
+ * Declared in method shorthand on purpose: that signature is bivariant, so a
341
+ * consumer can annotate the parameters with the real provider types
342
+ * (`(cfg: ConfigService) => ...`) instead of `unknown`. An arrow-property
343
+ * signature would be checked contravariantly under `strictFunctionTypes` and
344
+ * reject every typed factory, which is the whole point of `inject`.
345
+ */
346
+ useFactory?(...args: unknown[]): BymaxRealtimeModuleOptions | Promise<BymaxRealtimeModuleOptions>;
347
+ /**
348
+ * Providers to resolve and pass to `useFactory`, positionally.
349
+ *
350
+ * `Abstract<unknown>` is included because Nest's own injectable tokens are
351
+ * abstract classes — `ModuleRef` among them — and `Type<unknown>` alone is a
352
+ * non-abstract constructor type that excludes them.
353
+ */
354
+ inject?: readonly (string | symbol | Type<unknown> | Abstract<unknown>)[];
329
355
  useExisting?: Type<BymaxRealtimeModuleOptionsFactory>;
330
356
  useClass?: Type<BymaxRealtimeModuleOptionsFactory>;
331
357
  /**
@@ -1,4 +1,4 @@
1
- import { ModuleMetadata, Type, Provider, Logger, DynamicModule, MessageEvent, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
1
+ import { ModuleMetadata, Type, Abstract, Provider, Logger, DynamicModule, MessageEvent, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
2
2
  import { Subject, Observable } from 'rxjs';
3
3
  import { Redis } from 'ioredis';
4
4
 
@@ -121,6 +121,16 @@ interface ConnectionEventMeta {
121
121
  readonly connectionId: string;
122
122
  readonly userId: string;
123
123
  readonly tenantId: string | undefined;
124
+ /**
125
+ * Roles the authenticator returned for this connection, as a snapshot taken at
126
+ * connect time — `undefined` when the authenticator returned none.
127
+ *
128
+ * The library never interprets a role; it carries the consumer's own
129
+ * authorization vocabulary through so `onConnect` can act on it (typically by
130
+ * joining the connection to a role-scoped room). A later `revalidate` that
131
+ * keeps the connection alive does not refresh this snapshot.
132
+ */
133
+ readonly roles: readonly string[] | undefined;
124
134
  readonly transport: 'sse' | 'websocket';
125
135
  readonly ip: string;
126
136
  readonly userAgent: string | undefined;
@@ -324,8 +334,24 @@ interface BymaxRealtimeModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'
324
334
  * `transport` the factory resolves; a mismatch fails fast at bootstrap.
325
335
  */
326
336
  transport: TransportMode;
327
- useFactory?: (...args: unknown[]) => BymaxRealtimeModuleOptions | Promise<BymaxRealtimeModuleOptions>;
328
- inject?: readonly (string | symbol | Type<unknown>)[];
337
+ /**
338
+ * Factory producing the options, receiving whatever `inject` resolves.
339
+ *
340
+ * Declared in method shorthand on purpose: that signature is bivariant, so a
341
+ * consumer can annotate the parameters with the real provider types
342
+ * (`(cfg: ConfigService) => ...`) instead of `unknown`. An arrow-property
343
+ * signature would be checked contravariantly under `strictFunctionTypes` and
344
+ * reject every typed factory, which is the whole point of `inject`.
345
+ */
346
+ useFactory?(...args: unknown[]): BymaxRealtimeModuleOptions | Promise<BymaxRealtimeModuleOptions>;
347
+ /**
348
+ * Providers to resolve and pass to `useFactory`, positionally.
349
+ *
350
+ * `Abstract<unknown>` is included because Nest's own injectable tokens are
351
+ * abstract classes — `ModuleRef` among them — and `Type<unknown>` alone is a
352
+ * non-abstract constructor type that excludes them.
353
+ */
354
+ inject?: readonly (string | symbol | Type<unknown> | Abstract<unknown>)[];
329
355
  useExisting?: Type<BymaxRealtimeModuleOptionsFactory>;
330
356
  useClass?: Type<BymaxRealtimeModuleOptionsFactory>;
331
357
  /**
@@ -523,6 +523,7 @@ var SseTransport = class {
523
523
  connectionId: record.connectionId,
524
524
  userId: record.userId,
525
525
  tenantId: record.tenantId,
526
+ roles: record.originalAuth.roles,
526
527
  transport: "sse",
527
528
  ip: record.ip,
528
529
  userAgent: record.userAgent,
@@ -759,6 +760,7 @@ function buildMeta(record) {
759
760
  connectionId: record.connectionId,
760
761
  userId: record.userId,
761
762
  tenantId: record.tenantId,
763
+ roles: record.originalAuth.roles,
762
764
  transport: "sse",
763
765
  ip: record.ip,
764
766
  userAgent: record.userAgent,
@@ -1133,6 +1135,7 @@ var ReauthenticationService = class {
1133
1135
  connectionId: conn.connectionId,
1134
1136
  userId: conn.userId,
1135
1137
  tenantId: conn.tenantId,
1138
+ roles: conn.originalAuth.roles,
1136
1139
  transport: "sse",
1137
1140
  ip: conn.ip,
1138
1141
  userAgent: conn.userAgent,
@@ -118,6 +118,7 @@ exports.WebSocketTransport = class WebSocketTransport {
118
118
  connectionId: socket.id,
119
119
  userId: auth.userId,
120
120
  tenantId: auth.tenantId,
121
+ roles: auth.roles,
121
122
  transport: "websocket",
122
123
  ip: socket.handshake.address,
123
124
  userAgent: socket.handshake.headers["user-agent"],
@@ -142,6 +143,7 @@ exports.WebSocketTransport = class WebSocketTransport {
142
143
  connectionId,
143
144
  userId: record.userId,
144
145
  tenantId: record.tenantId,
146
+ roles: record.originalAuth.roles,
145
147
  transport: "websocket",
146
148
  ip: record.ip,
147
149
  userAgent: record.userAgent,
@@ -116,6 +116,7 @@ var WebSocketTransport = class {
116
116
  connectionId: socket.id,
117
117
  userId: auth.userId,
118
118
  tenantId: auth.tenantId,
119
+ roles: auth.roles,
119
120
  transport: "websocket",
120
121
  ip: socket.handshake.address,
121
122
  userAgent: socket.handshake.headers["user-agent"],
@@ -140,6 +141,7 @@ var WebSocketTransport = class {
140
141
  connectionId,
141
142
  userId: record.userId,
142
143
  tenantId: record.tenantId,
144
+ roles: record.originalAuth.roles,
143
145
  transport: "websocket",
144
146
  ip: record.ip,
145
147
  userAgent: record.userAgent,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-realtime",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
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",
@@ -187,7 +187,7 @@
187
187
  "eslint-plugin-prettier": "^5.0.0",
188
188
  "eslint-plugin-react-hooks": "^7.1.1",
189
189
  "eslint-plugin-security": "^4.0.1",
190
- "eventsource": "^4.1.0",
190
+ "eventsource": "^5.1.0",
191
191
  "ioredis": "^6.0.0",
192
192
  "ioredis-mock": "^8.0.0",
193
193
  "jest": "^30.0.0",