@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.
- package/CHANGELOG.md +33 -2
- package/README.md +53 -0
- 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
|
|
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.
|
|
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.
|
|
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",
|