Skip to content

Commit c8814cb

Browse files
DenisValckeDenisValcke
authored
feat(utils): the utils now contain a service that wraps around the BroadcastChannel API
* feat(utils): the utils now contain a service that wraps around the BroadcastChannel API * feat(utils): several improvements have been made to the NgxBroadcastChannelService including simplified safety and fully supporting the spec * feat(utils): updated the NgxBroadcastChannelService README to reflex recent changes * feat(utils): updated the NgxUtils README to reflex recent changes --------- Co-authored-by: Denis Valcke <[email protected]>
1 parent 1bc43ce commit c8814cb

File tree

6 files changed

+552
-0
lines changed

6 files changed

+552
-0
lines changed

‎libs/utils/README.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,12 @@ This service provides a SSR proof way to set and subscribe to the window's media
193193

194194
[Full documentation.](src/lib/services/media-query/query.service.md)
195195

196+
#### NgxBroadcastChannelService
197+
198+
This service provides a SSR proof way to create channels for the BroadcastChannel API, post messages on those channels and subscribe to the events.
199+
200+
[Full documentation.](src/lib/services/broadcast-channel/broadcast-channel.md)
201+
196202
### Abstracts
197203

198204
#### NgxQueryParamFormSyncComponent

‎libs/utils/package.json

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
"utils",
99
"storage",
1010
"storage service",
11+
"broadcast channel",
12+
"bradcast channel service",
1113
"consent",
1214
"join",
1315
"iban",

‎libs/utils/src/lib/services/broadcast-channel/broadcast-channel.md

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# NgxBroadcastChannelService
2+
3+
This `NgxBroadcastChannelService` service wraps around the [BroadcastChannel API](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API) and provides some handy functionality on top of some safety measures. It takes SSR into account and will only create channels while in the browser.
4+
5+
It holds a Record of potential BroadcastChannels with the key being their name. By doing this, multiple channels can exist within the same application simultaneously.
6+
7+
## Methods
8+
9+
### initChannel
10+
11+
The `initChannel` method will create a new BroadcastChannel with the given name.
12+
13+
```typescript
14+
import { NgxBroadcastChannelService } from '@studiohyperdrive/ngx-utils';
15+
16+
export class YourComponent {
17+
constructor(private readonly broadcastChannelService: NgxBroadcastChannelService) {}
18+
19+
public ngOnInit(): void {
20+
this.broadcastChannelService.initChannel('your-channel-name');
21+
}
22+
}
23+
```
24+
25+
#### Safety
26+
27+
The `initChannel` uses the `isPlatformBrowser` check to ensure it only runs in the browser, taking SSR into account as the BroadcastChannel API is not available in node by default.
28+
29+
If the channel already exists, it will return the existing channel to avoid overriding existing channels and listeners.
30+
31+
If a name is not provided, it will early return and log an error:
32+
33+
```
34+
NgxUtils: There was an attempt to initialize a BroadcastChannel without providing a name.
35+
```
36+
37+
### closeChannel
38+
39+
The `closeChannel` will close a channel with the given name.
40+
41+
```typescript
42+
import { NgxBroadcastChannelService } from '@studiohyperdrive/ngx-utils';
43+
44+
export class YourComponent {
45+
constructor(private readonly broadcastChannelService: NgxBroadcastChannelService) {}
46+
47+
public ngOnInit(): void {
48+
// Open up a channel for this component OnInit.
49+
this.broadcastChannelService.initChannel('your-channel-name');
50+
}
51+
52+
public ngOnDestroy(): void {
53+
// Close the created channel OnDestroy.
54+
this.broadcastChannelService.closeChannel('your-channel-name');
55+
}
56+
}
57+
```
58+
59+
#### Safety
60+
61+
If the channel does not exist on the Record or the name is not provided, it will early return.
62+
63+
### postMessage
64+
65+
The `postMessage` method will post a message to a channel with the given name.
66+
67+
```typescript
68+
import { NgxBroadcastChannelService } from '@studiohyperdrive/ngx-utils';
69+
70+
export class YourComponent {
71+
constructor(private readonly broadcastChannelService: NgxBroadcastChannelService) {}
72+
73+
public ngOnInit(): void {
74+
// Open up a channel for this component OnInit.
75+
this.broadcastChannelService.initChannel('your-channel-name');
76+
}
77+
78+
public ngOnDestroy(): void {
79+
// Close the created channel OnDestroy.
80+
this.broadcastChannelService.closeChannel('your-channel-name');
81+
}
82+
83+
public sendContextMessage(message: string): void {
84+
// Send a message through the channel.
85+
this.broadcastChannelService.postMessage('your-channel-name', message);
86+
}
87+
}
88+
```
89+
90+
#### Safety
91+
92+
If the channel does not exist on the Record or the name is not provided, it will early return and log an error to give a notice.
93+
94+
```
95+
NgxUtils: There was an attempt to post a message to a channel without providing a name or the selected channel does not exist. The included message was:
96+
```
97+
98+
_This warning will include the message that has been included to give a better understanding of what message was not sent._
99+
100+
### selectChannelMessages
101+
102+
The `selectChannelMessages` method will return a subscription wrapped around the `message` event of the channel with the given name.
103+
104+
```typescript
105+
import { NgxBroadcastChannelService } from '@studiohyperdrive/ngx-utils';
106+
107+
export class YourComponent {
108+
constructor(private readonly broadcastChannelService: NgxBroadcastChannelService) {}
109+
110+
public ngOnInit(): void {
111+
// Open up a channel for this component OnInit.
112+
this.broadcastChannelService.initChannel('your-channel-name');
113+
114+
this.broadcastChannelService.selectChannelMessages('your-channel-name').subscribe({
115+
// Handle the message event.
116+
next: (message: MessageEvent) => {
117+
console.log(message.data);
118+
},
119+
// When the channelName is not provided, an EMPTY is returned to not break the subscription.
120+
complete: () => {
121+
console.log('No channelName provided to the selectChannel method');
122+
},
123+
});
124+
}
125+
126+
public ngOnDestroy(): void {
127+
// Close the created channel OnDestroy.
128+
this.broadcastChannelService.closeChannel('your-channel-name');
129+
}
130+
131+
public sendContextMessage(message: string): void {
132+
// Send a message through the channel.
133+
this.broadcastChannelService.postMessage('your-channel-name', message);
134+
}
135+
}
136+
```
137+
138+
#### Safety
139+
140+
If the channel does not exist on the Record or the name is not provided, it will early return an `EMPTY` and log an error.
141+
142+
```angular2html
143+
NgxUtils: There was an attempt to select a BroadcastChannel's messages without providing a name or the selected channel does not exist.
144+
```
145+
146+
### selectChannelMessageErrors
147+
148+
The `selectChannelMessageErrors` method will return a subscription wrapped around the `message` event of the channel with the given name.
149+
150+
```typescript
151+
import { NgxBroadcastChannelService } from '@studiohyperdrive/ngx-utils';
152+
153+
export class YourComponent {
154+
constructor(private readonly broadcastChannelService: NgxBroadcastChannelService) {}
155+
156+
public ngOnInit(): void {
157+
// Open up a channel for this component OnInit.
158+
this.broadcastChannelService.initChannel('your-channel-name');
159+
160+
this.broadcastChannelService.selectChannelMessageErrors('your-channel-name').subscribe({
161+
// Handle the message event.
162+
next: (messageError: MessageEvent) => {
163+
console.log(messageError.data);
164+
},
165+
// When the channelName is not provided, an EMPTY is returned to not break the subscription.
166+
complete: () => {
167+
console.log('No channelName provided to the selectChannel method');
168+
},
169+
});
170+
}
171+
172+
public ngOnDestroy(): void {
173+
// Close the created channel OnDestroy.
174+
this.broadcastChannelService.closeChannel('your-channel-name');
175+
}
176+
177+
public sendContextMessage(message: string): void {
178+
// Send a message through the channel.
179+
this.broadcastChannelService.postMessage('your-channel-name', message);
180+
}
181+
}
182+
```
183+
184+
#### Safety
185+
186+
If the channel does not exist on the Record or the name is not provided, it will early return an `EMPTY` and log an error.
187+
188+
```angular2html
189+
NgxUtils: There was an attempt to select a BroadcastChannel's message errors without providing a name or the selected channel does not exist.
190+
```

0 commit comments

Comments
 (0)