@zerotal/broadcasting 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog — @zerotal/broadcasting
+
+All notable changes to this package are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/); this package
+follows the Zerotal monorepo's unified versioning.
+
+**Maturity: `beta`**
+
+## [Unreleased]
+
+## [1.0.0] — 2026-08-05
+
+_First public release._
+
+### Fixed
+
+- **Presence: an explicit unsubscribe now removes the member and notifies the channel.** `_unsubscribe` only dropped the connection from the channel's subscriber set — it skipped the presence-member cleanup + `presence:member_removed` broadcast that a full disconnect (`handleClose`) performs. So a member who left via `Echo.leave` (a flow component teardown / SPA navigation, not a tab close) lingered in everyone else's "who's here" until they disconnected. Both leave paths now clean up identically.
+- **The broadcasting WebSocket now coexists with flow's.** `BroadcastProvider` registers its WS handler at the configured `path` (default `/app/ws`; pusher stays catch-all for its dynamic `/app/{key}`), relying on core's new path-multiplexed `withWebSocket`. Before, flow's `/__flow/ws` registration clobbered the broadcasting one, so `/app/ws` never handled connections — real-time presence/private/shared channels silently didn't deliver in apps that also use flow.
+
+### Changed
+
+- Added a typed error vocabulary (`BroadcastError` + `E_BROADCAST_*` codes).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zerotal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @zerotal/broadcasting
+
+> Real-time WebSocket broadcasting with a Pusher-compatible server built into your app process.
+
+Define a `BroadcastingEvent`, dispatch it, and every subscribed client receives the payload over a live WebSocket connection — no separate service required. Supports public, private, and presence channels, a Redis driver for horizontally-scaled deployments, and works unchanged with any Pusher-protocol client.
+
+Part of the [Zerotal](../../README.md) framework. Requires **Bun ≥ 1.3.14**.
+
+## Installation
+
+```bash
+bun add @zerotal/broadcasting
+```
+
+## Setup
+
+Register the provider in `bootstrap/providers.ts`:
+
+```ts
+import { BroadcastProvider } from "@zerotal/broadcasting";
+```
+
+It registers two HTTP endpoints automatically: `GET /app/{appKey}` (WebSocket upgrade) and `POST /broadcasting/auth` (private/presence channel auth).
+
+## Usage
+
+Write a broadcast event — only `broadcastOn()` is required:
+
+```ts
+import { BroadcastingEvent, privateChannel } from "@zerotal/broadcasting";
+
+export class OrderShipmentStatusUpdated extends BroadcastingEvent {
+  constructor(public readonly order: Order) {
+    super();
+  }
+
+  broadcastOn() {
+    return privateChannel(`orders.${this.order.id}`);
+  }
+
+  broadcastWith() {
+    return { id: this.order.id, status: this.order.status };
+  }
+}
+```
+
+Dispatch it — static, fluent, or via the facade:
+
+```ts
+import { broadcast, Broadcast } from "@zerotal/broadcasting";
+
+OrderShipmentStatusUpdated.dispatch(order); // construct + dispatch + broadcast
+await broadcast(new OrderShipmentStatusUpdated(order)).toOthers(); // exclude current socket
+Broadcast.send(new OrderShipmentStatusUpdated(order)); // explicit send
+```
+
+Pick a channel type with the helpers, then authorize private/presence channels in `routes/channels.ts`:
+
+```ts
+import { channel, privateChannel, presenceChannel } from "@zerotal/broadcasting";
+
+channel("posts"); // public
+privateChannel("orders.42"); // private  -> "private-orders.42"
+presenceChannel("chat.room1"); // presence -> "presence-chat.room1"
+```
+
+```ts
+// routes/channels.ts
+import { Broadcast } from "@zerotal/broadcasting";
+
+Broadcast.channel("orders.[orderId]", async (user, orderId) => {
+  return user.id === (await Order.findOrNew(orderId)).userId; // boolean = private
+});
+
+Broadcast.channel("chat.[roomId]", (user, roomId) => {
+  return user.canJoin(roomId) ? { id: user.id, name: user.name } : null; // member data = presence
+});
+```
+
+Testing with the in-memory recorder:
+
+```ts
+import { Broadcast } from "@zerotal/broadcasting";
+
+const fake = Broadcast.fake();
+await PostController.publish({ http: ctx });
+fake.assertBroadcast("PostPublished", "posts", { id: post.id });
+Broadcast.resetFake();
+```
+
+## Exports
+
+- `BroadcastingEvent` / `broadcastOnce` — base class for broadcastable events.
+- `broadcast` / `PendingBroadcast` — fluent dispatch helper (`.toOthers()`, awaitable).
+- `Broadcast` — facade (`send`, `to`, `getMembers`, `channel`, `on`/`private`/`presence`, `fake`/`resetFake`).
+- Channel helpers: `channel`, `privateChannel`, `presenceChannel`, `isPrivateChannel`.
+- `BroadcastManager` — core manager; `TypedBroadcastManager` for compile-time-checked channel maps.
+- `PusherCompatManager` — Pusher/Reverb-compatible protocol manager.
+- `RedisBroadcastDriver` — Redis Pub/Sub fan-out for multi-instance deployments.
+- `broadcastsModelEvents` — wire a model's `created`/`updated`/`deleted` to broadcasts.
+- `AnonymousBroadcast` — inline broadcasts without an event class.
+- `ChannelRegistry` / `channelRegistry` / `compileChannelPattern` — channel auth rule registry.
+- `BroadcastFake` — test double behind `Broadcast.fake()`.
+- `BroadcastProvider` — service provider.
+- `BroadcastConfig` — config factory.
+- Types: `PresenceMember`, `PresenceAuthFn`, `BroadcastChannelMap`, `ChannelParams`, `EventsOf`, `PayloadOf`, `TypedBroadcastEvent`, `BroadcastEvent`, `WsConnectionData`, `ChannelAuthFn`, `RecordedBroadcast`, and more.
+- Typed error vocabulary re-exported from `./errors`.
+
+## Documentation
+
+- [Broadcasting](../../docs/broadcasting/index.md)

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@zerotal/broadcasting",
+  "version": "1.0.0",
+  "license": "MIT",
+  "maturity": "beta",
+  "private": false,
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "CHANGELOG.md",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.spec.ts",
+    "!src/**/__fixtures__/**"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@zerotal/core": "1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  },
+  "description": "Real-time event broadcasting over WebSockets for Zerotal, with public/private/presence channels.",
+  "keywords": [
+    "zerotal",
+    "bun",
+    "typescript",
+    "framework",
+    "broadcasting",
+    "websocket",
+    "realtime"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zerotaldev/zerotal.git",
+    "directory": "packages/broadcasting"
+  },
+  "homepage": "https://github.com/zerotaldev/zerotal/tree/main/packages/broadcasting#readme",
+  "bugs": "https://github.com/zerotaldev/zerotal/issues"
+}

package/src/AnonymousBroadcast.ts

@@ -0,0 +1,52 @@
+import { Broadcast } from "./facades/Broadcast.ts";
+import { currentSocketId } from "./currentSocketId.ts";
+
+/**
+ * Fluent builder for broadcasting without a dedicated event class. Returned by
+ * `Broadcast.on()` / `Broadcast.private()` / `Broadcast.presence()`.
+ *
+ * @example
+ * Broadcast.on(`orders.${order.id}`).as("OrderPlaced").with(order).toOthers().send();
+ * Broadcast.private(`orders.${order.id}`).as("OrderPlaced").with({ id: order.id }).send();
+ */
+export class AnonymousBroadcast {
+  private _event = "AnonymousEvent";
+  private _data: unknown = {};
+  private _toOthers = false;
+
+  constructor(private readonly channel: string) {}
+
+  /** Set the wire event name (default `"AnonymousEvent"`). */
+  as(event: string): this {
+    this._event = event;
+    return this;
+  }
+
+  /** Set the payload. */
+  with(data: unknown): this {
+    this._data = data;
+    return this;
+  }
+
+  /** Exclude the originating connection (its `X-Socket-ID`). */
+  toOthers(): this {
+    this._toOthers = true;
+    return this;
+  }
+
+  /** Broadcast now. (`sendNow()` is an alias; queued sending lands with the broadcast queue.) */
+  send(): void {
+    const exceptSocketId = this._toOthers ? currentSocketId() : undefined;
+    Broadcast.to(
+      this.channel,
+      this._event,
+      this._data,
+      exceptSocketId ? { exceptSocketId } : undefined,
+    );
+  }
+
+  /** Broadcast immediately. */
+  sendNow(): void {
+    this.send();
+  }
+}

package/src/BroadcastFake.ts

@@ -0,0 +1,114 @@
+import type { BroadcastEvent } from "./types.ts";
+
+export interface RecordedBroadcast {
+  channel: string;
+  event: string;
+  data: Record<string, unknown>;
+}
+
+/**
+ * In-test fake that records broadcast calls without requiring a WS server.
+ *
+ * @example
+ * const fake = Broadcast.fake();
+ *
+ * // ... controller action that calls Broadcast.send(new PostUpdated(post))
+ *
+ * fake.assertBroadcast('PostUpdated', 'posts');
+ * fake.assertNothingBroadcast();
+ */
+export class BroadcastFake {
+  private _broadcasts: RecordedBroadcast[] = [];
+
+  to(
+    channel: string,
+    eventName: string,
+    data: unknown = {},
+    _opts?: { exceptSocketId?: string },
+  ): void {
+    this._broadcasts.push({ channel, event: eventName, data: data as Record<string, unknown> });
+  }
+
+  send(event: BroadcastEvent, opts?: { exceptSocketId?: string }): void {
+    const channels = [event.broadcastOn()].flat();
+    const name = event.broadcastAs?.() ?? event.constructor.name;
+    const data = event.broadcastWith?.() ?? {};
+    for (const ch of channels) {
+      this.to(ch, name, data, opts);
+    }
+  }
+
+  /** Return all recorded broadcasts. */
+  recorded(): RecordedBroadcast[] {
+    return [...this._broadcasts];
+  }
+
+  /** Reset recorded broadcasts. */
+  reset(): void {
+    this._broadcasts = [];
+  }
+
+  // ── Assertions ────────────────────────────────────────────────────────────
+
+  /**
+   * Assert that an event was broadcast on the given channel (and optionally with given data).
+   *
+   * @example
+   * fake.assertBroadcast('PostUpdated', 'posts');
+   * fake.assertBroadcast('PostUpdated', 'posts', { id: 1 });
+   */
+  assertBroadcast(eventName: string, channel?: string, data?: Record<string, unknown>): void {
+    const match = this._broadcasts.find((b) => {
+      if (b.event !== eventName) return false;
+      if (channel && b.channel !== channel) return false;
+      if (data) {
+        for (const [k, v] of Object.entries(data)) {
+          if ((b.data as Record<string, unknown>)[k] !== v) return false;
+        }
+      }
+      return true;
+    });
+    if (!match) {
+      const desc = channel ? ` on channel "${channel}"` : "";
+      throw new Error(
+        `Expected event "${eventName}"${desc} to have been broadcast, but it was not.\n` +
+          `Recorded: ${JSON.stringify(
+            this._broadcasts.map((b) => `${b.event}@${b.channel}`),
+            null,
+            2,
+          )}`,
+      );
+    }
+  }
+
+  /**
+   * Assert that the given event was NOT broadcast.
+   */
+  assertNotBroadcast(eventName: string, channel?: string): void {
+    const match = this._broadcasts.find((b) => {
+      if (b.event !== eventName) return false;
+      if (channel && b.channel !== channel) return false;
+      return true;
+    });
+    if (match) {
+      throw new Error(`Expected event "${eventName}" NOT to have been broadcast, but it was.`);
+    }
+  }
+
+  /** Assert that no broadcasts were recorded. */
+  assertNothingBroadcast(): void {
+    if (this._broadcasts.length > 0) {
+      throw new Error(
+        `Expected nothing to be broadcast, but ${this._broadcasts.length} broadcast(s) were recorded:\n` +
+          this._broadcasts.map((b) => `  ${b.event}@${b.channel}`).join("\n"),
+      );
+    }
+  }
+
+  /** Assert that exactly `count` broadcasts were recorded. */
+  assertBroadcastCount(count: number): void {
+    if (this._broadcasts.length !== count) {
+      throw new Error(`Expected ${count} broadcast(s) but got ${this._broadcasts.length}.`);
+    }
+  }
+}