@holo-js/flux 0.3.27 → 0.4.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Holo-JS contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ 7f23c2abe2d082c78daa49df641f50dfab3c970af3cbe77c254be7bb2a9babc7
package/dist/index.d.ts CHANGED
@@ -65,6 +65,7 @@ interface FluxConnectorChannel {
65
65
  onMembersChange(callback: (members: readonly BroadcastJsonObject[]) => void): () => void;
66
66
  onNotification(callback: (payload: BroadcastJsonObject) => void): () => void;
67
67
  onWhisper(name: string, callback: (payload: BroadcastJsonObject) => void): () => void;
68
+ onError?(callback: (error: Error) => void): () => void;
68
69
  sendWhisper(name: string, payload: BroadcastJsonObject): Promise<void>;
69
70
  leave(): void;
70
71
  }
@@ -80,10 +81,12 @@ interface FluxSubscription<TManifest extends GeneratedBroadcastManifest = Genera
80
81
  readonly type: FluxChannelKind;
81
82
  listen<TEvent extends FluxManifestTypes<TManifest, TChannel>['subscriptionEvent']>(event?: TEvent | readonly TEvent[], callback?: (payload: BroadcastJsonObject) => void): FluxSubscription<TManifest, TChannel>;
82
83
  notification(callback: (payload: BroadcastJsonObject) => void): FluxSubscription<TManifest, TChannel>;
84
+ error(callback: (error: Error) => void): FluxSubscription<TManifest, TChannel>;
83
85
  listenForWhisper<TWhisper extends FluxManifestTypes<TManifest, TChannel>['whisperName']>(name: TWhisper, callback: (payload: BroadcastJsonObject) => void): FluxSubscription<TManifest, TChannel>;
84
86
  whisper<TWhisper extends FluxManifestTypes<TManifest, TChannel>['whisperName']>(name: TWhisper, payload: BroadcastJsonObject): Promise<void>;
85
87
  }
86
88
  interface FluxPresenceSubscription<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest, TChannel extends string = string> extends FluxSubscription<TManifest, TChannel>, FluxPresenceState<FluxManifestTypes<TManifest, TChannel>['presenceMember']>, FluxPresenceListenerControls<TManifest, TChannel> {
89
+ error(callback: (error: Error) => void): FluxPresenceSubscription<TManifest, TChannel>;
87
90
  }
88
91
  interface FluxClient<TManifest extends GeneratedBroadcastManifest = GeneratedBroadcastManifest> extends FluxConnectionControls {
89
92
  readonly options: Readonly<FluxClientOptions<TManifest>>;
@@ -125,4 +128,5 @@ declare const fluxInternals: {
125
128
  createSubscription: typeof createSubscription;
126
129
  };
127
130
 
128
- export { type FluxChannelKind, type FluxClient, type FluxClientOptions, type FluxConnectionControls, type FluxConnectionStatus, type FluxConnector, type FluxConnectorChannel, type FluxListenerControls, type FluxManifestTypes, type FluxPresenceListenerControls, type FluxPresenceState, type FluxPresenceSubscription, type FluxSubscription, configureFluxClient, createFluxClient, flux as default, flux, fluxInternals, getFluxClient, resetFluxClient };
131
+ export { configureFluxClient, createFluxClient, flux as default, flux, fluxInternals, getFluxClient, resetFluxClient };
132
+ export type { FluxChannelKind, FluxClient, FluxClientOptions, FluxConnectionControls, FluxConnectionStatus, FluxConnector, FluxConnectorChannel, FluxListenerControls, FluxManifestTypes, FluxPresenceListenerControls, FluxPresenceState, FluxPresenceSubscription, FluxSubscription };
package/dist/index.mjs CHANGED
@@ -120,6 +120,28 @@ function parseWireData(value) {
120
120
  }
121
121
  return Object.freeze({});
122
122
  }
123
+ function parseFrame(value) {
124
+ try {
125
+ const message = parseJsonObject(value);
126
+ return { message, payload: parseWireData(message.data) };
127
+ } catch {
128
+ return void 0;
129
+ }
130
+ }
131
+ function isDevelopmentBuild() {
132
+ try {
133
+ return process.env.NODE_ENV !== "production";
134
+ } catch {
135
+ return false;
136
+ }
137
+ }
138
+ function toError(value) {
139
+ return value instanceof Error ? value : new Error(String(value));
140
+ }
141
+ function createSubscriptionRefusedError(channel, payload) {
142
+ const detail = typeof payload.error === "string" ? payload.error : "The server refused the subscription.";
143
+ return new Error(`[@holo-js/flux] Subscription to ${channel} was refused: ${detail}`);
144
+ }
123
145
  function normalizeOptionalConnectorString(value) {
124
146
  return typeof value === "string" && value.trim() ? value.trim() : void 0;
125
147
  }
@@ -261,6 +283,9 @@ function createHoloWebSocketConnector(options = {}) {
261
283
  if (state.subscribed) {
262
284
  continue;
263
285
  }
286
+ if (state.kind !== "public" && resolvedOptions?.authEndpoint && !socketId) {
287
+ continue;
288
+ }
264
289
  state.subscribed = true;
265
290
  if (state.kind === "public" || !resolvedOptions?.authEndpoint) {
266
291
  sendMessage({
@@ -271,7 +296,11 @@ function createHoloWebSocketConnector(options = {}) {
271
296
  });
272
297
  continue;
273
298
  }
299
+ const flushedSocket = connection?.socket;
274
300
  void authorizeSubscription(state).then((auth) => {
301
+ if (connection?.socket !== flushedSocket || channels.get(`${state.kind}:${state.name}`) !== state) {
302
+ return;
303
+ }
275
304
  sendMessage({
276
305
  event: "pusher:subscribe",
277
306
  data: {
@@ -279,8 +308,13 @@ function createHoloWebSocketConnector(options = {}) {
279
308
  ...auth
280
309
  }
281
310
  });
282
- }, () => {
283
- state.subscribed = false;
311
+ }, (error) => {
312
+ if (connection?.socket === flushedSocket) {
313
+ state.subscribed = false;
314
+ for (const listener of [...state.errorListeners]) {
315
+ listener(toError(error));
316
+ }
317
+ }
284
318
  });
285
319
  }
286
320
  };
@@ -288,10 +322,16 @@ function createHoloWebSocketConnector(options = {}) {
288
322
  if (typeof event.data !== "string") {
289
323
  return;
290
324
  }
291
- const message = parseJsonObject(event.data);
325
+ const frame = parseFrame(event.data);
326
+ if (!frame) {
327
+ if (isDevelopmentBuild()) {
328
+ console.warn("[@holo-js/flux] Dropped a WebSocket frame that is not valid JSON.");
329
+ }
330
+ return;
331
+ }
332
+ const { message, payload } = frame;
292
333
  const eventName = typeof message.event === "string" ? message.event : "";
293
334
  const channel = typeof message.channel === "string" ? message.channel : void 0;
294
- const payload = parseWireData(message.data);
295
335
  if (eventName === "pusher:connection_established") {
296
336
  socketId = typeof payload.socket_id === "string" ? payload.socket_id : void 0;
297
337
  flushSubscriptions();
@@ -304,6 +344,14 @@ function createHoloWebSocketConnector(options = {}) {
304
344
  if (!state) {
305
345
  return;
306
346
  }
347
+ if (eventName === "pusher:subscription_error") {
348
+ state.subscribed = false;
349
+ const error = createSubscriptionRefusedError(state.name, payload);
350
+ for (const listener of [...state.errorListeners]) {
351
+ listener(error);
352
+ }
353
+ return;
354
+ }
307
355
  if (eventName === "pusher_internal:subscription_succeeded") {
308
356
  const presence = payload.presence;
309
357
  if (presence && typeof presence === "object" && !Array.isArray(presence)) {
@@ -361,18 +409,24 @@ function createHoloWebSocketConnector(options = {}) {
361
409
  WebSocket: WebSocketConstructor,
362
410
  failureMessage: "[@holo-js/flux] WebSocket connection failed.",
363
411
  resolveUrl() {
364
- const format = (config) => ({
365
- url: broadcastBrowserInternals.formatUrl({
366
- scheme: resolveWebSocketScheme(config.scheme, globals),
367
- host: resolveBrowserHost(config.host, globals),
368
- port: config.port ?? 8080,
369
- path: config.path?.trim() || "/app",
370
- key: config.key?.trim() || "app-key"
371
- }),
372
- activate() {
373
- resolvedOptions = config;
412
+ const format = (config) => {
413
+ const key = config.key?.trim();
414
+ if (!key) {
415
+ throw new Error("[@holo-js/flux] Broadcast app key is not configured.");
374
416
  }
375
- });
417
+ return {
418
+ url: broadcastBrowserInternals.formatUrl({
419
+ scheme: resolveWebSocketScheme(config.scheme, globals),
420
+ host: resolveBrowserHost(config.host, globals),
421
+ port: config.port ?? 8080,
422
+ path: config.path?.trim() || "/app",
423
+ key
424
+ }),
425
+ activate() {
426
+ resolvedOptions = config;
427
+ }
428
+ };
429
+ };
376
430
  return canDiscoverHoloWebSocketConnectorOptions(globals) ? resolveHoloWebSocketConnectorOptions(options, globals).then(format) : format(options);
377
431
  },
378
432
  onOpen() {
@@ -389,7 +443,12 @@ function createHoloWebSocketConnector(options = {}) {
389
443
  }
390
444
  });
391
445
  setStatus("connecting");
392
- await connection.connect();
446
+ try {
447
+ await connection.connect();
448
+ } catch (error) {
449
+ setStatus("disconnected");
450
+ throw error;
451
+ }
393
452
  };
394
453
  const ensureChannel = (name, kind) => {
395
454
  const key = `${kind}:${name}`;
@@ -405,7 +464,8 @@ function createHoloWebSocketConnector(options = {}) {
405
464
  notificationListeners: /* @__PURE__ */ new Set(),
406
465
  memberListeners: /* @__PURE__ */ new Set(),
407
466
  members: Object.freeze([]),
408
- subscribed: false
467
+ subscribed: false,
468
+ errorListeners: /* @__PURE__ */ new Set()
409
469
  };
410
470
  channels.set(key, state);
411
471
  return state;
@@ -456,6 +516,12 @@ function createHoloWebSocketConnector(options = {}) {
456
516
  onWhisper(name, callback) {
457
517
  return addCallback(state.whisperListeners, name, callback);
458
518
  },
519
+ onError(callback) {
520
+ state.errorListeners.add(callback);
521
+ return () => {
522
+ state.errorListeners.delete(callback);
523
+ };
524
+ },
459
525
  async sendWhisper(name, payload) {
460
526
  await ensureConnected();
461
527
  sendMessage({
@@ -489,6 +555,8 @@ function createSubscription(channelName, kind, connector, registry) {
489
555
  const registryKey = `${kind}:${channelName.replace(/^private-/, "").replace(/^presence-/, "")}`;
490
556
  let left = false;
491
557
  const notificationHandlers = /* @__PURE__ */ new Set();
558
+ const errorHandlers = /* @__PURE__ */ new Set();
559
+ let isErrorAttached = false;
492
560
  const registeredSubscriptions = registry.get(registryKey) ?? /* @__PURE__ */ new Set();
493
561
  registry.set(registryKey, registeredSubscriptions);
494
562
  const runWhenActive = (callback) => {
@@ -525,6 +593,20 @@ function createSubscription(channelName, kind, connector, registry) {
525
593
  detachCallbacks.add(stop);
526
594
  }
527
595
  };
596
+ const ensureError = (callback) => {
597
+ errorHandlers.add(callback);
598
+ if (!isErrorAttached) {
599
+ isErrorAttached = true;
600
+ const stop = connectorChannel.onError?.((error) => {
601
+ for (const listener of [...errorHandlers]) {
602
+ listener(error);
603
+ }
604
+ });
605
+ if (stop) {
606
+ detachCallbacks.add(stop);
607
+ }
608
+ }
609
+ };
528
610
  const ensureWhisper = (event, callback) => {
529
611
  const normalizedEvent = normalizeRequiredString(event, "Flux whisper event");
530
612
  const listeners = whisperHandlers.get(normalizedEvent) ?? /* @__PURE__ */ new Set();
@@ -588,6 +670,10 @@ function createSubscription(channelName, kind, connector, registry) {
588
670
  ensureNotification(callback);
589
671
  return this;
590
672
  },
673
+ error(callback) {
674
+ ensureError(callback);
675
+ return this;
676
+ },
591
677
  listenForWhisper(name, callback) {
592
678
  ensureWhisper(name, callback);
593
679
  return this;
@@ -677,6 +763,10 @@ function createPresenceSubscription(name, connector, registry) {
677
763
  notification(callback) {
678
764
  return base.notification(callback);
679
765
  },
766
+ error(callback) {
767
+ base.error(callback);
768
+ return subscription;
769
+ },
680
770
  listenForWhisper(name2, callback) {
681
771
  return base.listenForWhisper(name2, callback);
682
772
  },
package/package.json CHANGED
@@ -1,9 +1,14 @@
1
1
  {
2
2
  "name": "@holo-js/flux",
3
- "version": "0.3.27",
3
+ "version": "0.4.0",
4
4
  "description": "Holo-JS Framework - framework-agnostic realtime client skeleton for broadcast and presence",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
+ "repository": {
8
+ "type": "git",
9
+ "url": "git+https://github.com/cobraprojects/holo-js.git",
10
+ "directory": "packages/flux"
11
+ },
7
12
  "exports": {
8
13
  ".": {
9
14
  "types": "./dist/index.d.ts",
@@ -14,7 +19,8 @@
14
19
  "main": "./dist/index.mjs",
15
20
  "types": "./dist/index.d.ts",
16
21
  "files": [
17
- "dist"
22
+ "dist",
23
+ "LICENSE"
18
24
  ],
19
25
  "scripts": {
20
26
  "build": "tsup",
@@ -23,15 +29,15 @@
23
29
  "test": "vitest --run"
24
30
  },
25
31
  "dependencies": {
26
- "@holo-js/broadcast": "^0.3.27"
32
+ "@holo-js/broadcast": "^0.4.0"
27
33
  },
28
34
  "devDependencies": {
29
- "@types/node": "^22.10.2",
30
- "tsup": "^8.3.5",
31
- "typescript": "^5.7.2",
32
- "vitest": "^4.1.5"
35
+ "@types/node": "^22.20.5",
36
+ "tsup": "^9.0.0",
37
+ "typescript": "^6.0.3",
38
+ "vitest": "^5.0.5"
33
39
  },
34
40
  "engines": {
35
- "node": "^22.12.0 || ^24.0.0 || ^26.0.0"
41
+ "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
36
42
  }
37
43
  }