@bymax-one/nest-realtime 1.1.1 → 1.1.2

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.
Files changed (3) hide show
  1. package/CHANGELOG.md +33 -2
  2. package/README.md +53 -0
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -5,6 +5,36 @@ 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.2] - 2026-08-21
9
+
10
+ **Documentation-only.** `dist/` is byte-identical to `1.1.1` — verified by diffing the
11
+ build against the published tarball, not asserted. No runtime path, exported type or
12
+ public surface changed. The release exists because `README.md` ships inside the package
13
+ and renders on npm, so a documentation defect there reaches consumers exactly as a code
14
+ one does.
15
+
16
+ ### Documentation
17
+
18
+ - **The role-scoped room snippet led a careful consumer into a wall.** It called
19
+ `moduleRef.get()` inside the `onConnect` hook, which is correct and runs — and which
20
+ means unit-testing that hook requires faking `ModuleRef`, in practice
21
+ `as unknown as ModuleRef`. That is a suppression many codebases block outright, so the
22
+ documented pattern was unusable for anyone whose policy forbids the cast. Found by a
23
+ consumer adopting `1.1.1`, not by us; "it works" was true and was the reason it
24
+ survived review.
25
+
26
+ The README now also documents the testable shape: give the hook the two capabilities
27
+ it uses, `RoomJoiner` and `ServiceResolver`. `ModuleRef` and `RealtimeService` satisfy
28
+ them structurally, so production passes the real objects and a test passes plain ones,
29
+ with no cast at either end. Both snippets are compiled and executed by
30
+ `realtime.module.documented-patterns.spec.ts` rather than left as prose.
31
+
32
+ - **Role matching is exact membership.** `roles?.includes('admin')` on a
33
+ `readonly string[]` compares whole elements. Reaching for
34
+ `roles?.some((r) => r.includes('admin'))` — for case-insensitivity, say — admits
35
+ `administrator`, `admin-readonly` and `superadmin`. That failure is an authorization
36
+ leak, it fails open, and it appears only for role names nobody declared.
37
+
8
38
  ## [1.1.1] - 2026-08-21
9
39
 
10
40
  ### Added
@@ -20,7 +50,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
20
50
  and absent at disconnect would be a field that lies by omission exactly when a host cleans up.
21
51
 
22
52
  **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`.
53
+ that _constructs_ a `ConnectionEventMeta` (typically a test fixture) must now supply `roles`.
24
54
  `undefined` stays meaningful for an authenticator that returns none.
25
55
 
26
56
  Roles are carried, never interpreted: there is deliberately no `emitToRole`. Indexing a
@@ -293,7 +323,8 @@ First published release.
293
323
  rather than by the manual sweep that raised the NestJS floors — that sweep
294
324
  asked about NestJS and never put the same question to the other ten peers.
295
325
 
296
- [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.1.1...HEAD
326
+ [Unreleased]: https://github.com/bymaxone/nest-realtime/compare/v1.1.2...HEAD
327
+ [1.1.2]: https://github.com/bymaxone/nest-realtime/compare/v1.1.1...v1.1.2
297
328
  [1.1.1]: https://github.com/bymaxone/nest-realtime/compare/v1.1.0...v1.1.1
298
329
  [1.1.0]: https://github.com/bymaxone/nest-realtime/compare/v1.0.6...v1.1.0
299
330
  [1.0.6]: https://github.com/bymaxone/nest-realtime/compare/v1.0.5...v1.0.6
package/README.md CHANGED
@@ -588,6 +588,59 @@ the connection alive does not refresh it. When a role can be revoked mid-session
588
588
  make `revalidate` return `false` so the connection is torn down and re-established
589
589
  with the new roles.
590
590
 
591
+ ##### Make the hook testable: depend on the capability, not the injector
592
+
593
+ The snippet above works, and it still walks a careful consumer into a wall: a
594
+ `moduleRef.get()` call inside the hook means unit-testing that hook requires
595
+ faking `ModuleRef`, which in practice means `as unknown as ModuleRef` — a
596
+ suppression many codebases block outright.
597
+
598
+ Give the hook the two capabilities it actually uses instead. `ModuleRef` and
599
+ `RealtimeService` satisfy these shapes **structurally**, so the module passes the
600
+ real objects and a test passes plain ones, with no cast at either end:
601
+
602
+ ```typescript
603
+ interface RoomJoiner {
604
+ joinRoom(connectionId: string, roomId: string): Promise<void>
605
+ }
606
+
607
+ interface ServiceResolver {
608
+ get(token: typeof RealtimeService): RoomJoiner
609
+ }
610
+
611
+ function joinRoleRoom(resolver: ServiceResolver, role: string, roomId: string) {
612
+ return async (meta: ConnectionEventMeta): Promise<void> => {
613
+ if (!meta.roles?.includes(role)) return
614
+ await resolver.get(RealtimeService).joinRoom(meta.connectionId, roomId)
615
+ }
616
+ }
617
+ ```
618
+
619
+ Wire it with the real injector:
620
+
621
+ ```typescript
622
+ inject: [ModuleRef],
623
+ useFactory: (moduleRef: ModuleRef) => ({
624
+ transport: 'sse' as const,
625
+ authenticator: new CookieAuthenticator(),
626
+ hooks: { onConnect: joinRoleRoom(moduleRef, 'admin', 'role:admin') },
627
+ }),
628
+ ```
629
+
630
+ and test it without booting NestJS:
631
+
632
+ ```typescript
633
+ const joinRoom = jest.fn()
634
+ const onConnect = joinRoleRoom({ get: () => ({ joinRoom }) }, 'admin', 'role:admin')
635
+ ```
636
+
637
+ > [!NOTE]
638
+ > Match roles by exact membership. `roles?.includes('admin')` on a `readonly string[]`
639
+ > compares whole elements; reaching for `roles?.some((r) => r.includes('admin'))` —
640
+ > for case-insensitivity, say — admits `administrator`, `admin-readonly` and
641
+ > `superadmin`. That failure is an authorization leak, it fails open, and it only
642
+ > shows up for role names nobody declared.
643
+
591
644
  ### Reserved Events
592
645
 
593
646
  Emitted by the library. Do not reuse these names for application events.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@bymax-one/nest-realtime",
3
- "version": "1.1.1",
3
+ "version": "1.1.2",
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",