@zerotal/broadcasting 1.7.0 → 1.7.3

package/api-surface.md

@@ -16,7 +16,7 @@ class AnonymousBroadcast = {
 
 class Broadcast = {
   new (): Broadcast
-  static channel: (pattern: string, callback: ChannelCallback) => void
+  static channel: <User = unknown>(pattern: string, callback: ChannelCallback<User>) => void
   static channels: () => {    pattern: string;    paramNames: string[];}[]
   static fake: () => BroadcastFake
   static getMembers: (channel: string) => PresenceMember[]
@@ -109,7 +109,7 @@ class ChannelRegistry = {
   all: () => {    pattern: string;    paramNames: string[];}[]
   authorize: (channelName: string, user: unknown) => Promise<AuthorizeResult>
   clear: () => void
-  register: (pattern: string, callback: ChannelCallback) => void
+  register: <User = unknown>(pattern: string, callback: ChannelCallback<User>) => void
 }
 
 class MissingChannelParameterError = {
@@ -155,9 +155,9 @@ class RedisBroadcastDriver = {
   boot: () => Promise<void>
   connectionCount: () => number
   getMembers: (channel: string) => PresenceMember[]
-  handleClose: (ws: ServerWebSocket<WsConnectionData>) => void
-  handleMessage: (ws: ServerWebSocket<WsConnectionData>, raw: string | Uint8Array) => Promise<void>
-  handleOpen: (ws: ServerWebSocket<WsConnectionData>) => void
+  handleClose: (ws: Bun.ServerWebSocket<WsConnectionData>) => void
+  handleMessage: (ws: Bun.ServerWebSocket<WsConnectionData>, raw: string | Uint8Array) => Promise<void>
+  handleOpen: (ws: Bun.ServerWebSocket<WsConnectionData>) => void
   send: (event: BroadcastEvent, opts?: {    exceptSocketId?: string;}) => void
   setAuthSecret: (secret: string) => void
   signAuth: (socketId: string, channel: string, channelData?: string) => string
@@ -167,7 +167,7 @@ class RedisBroadcastDriver = {
   to: (channel: string, event: string, data?: unknown, opts?: {    exceptSocketId?: string;}) => void
   upgradeData: (req: Request) => Record<string, unknown>
   verifyAuth: (socketId: string, channel: string, auth: string, channelData?: string) => boolean
-  wsHandlers: {    open: (ws: ServerWebSocket<WsConnectionData>) => void;    message: (ws: ServerWebSocket<WsConnectionData>, msg: string | Uint8Array) => undefined;    close: (ws: ServerWebSocket<WsConnectionData>) => void;}
+  wsHandlers: {    open: (ws: Bun.ServerWebSocket<WsConnectionData>) => void;    message: (ws: Bun.ServerWebSocket<WsConnectionData>, msg: string | Uint8Array) => undefined;    close: (ws: Bun.ServerWebSocket<WsConnectionData>) => void;}
 }
 
 class TypedBroadcastManager = {
@@ -176,9 +176,9 @@ class TypedBroadcastManager = {
   authorizeWith: (fn: ChannelAuthFn) => void
   connectionCount: () => number
   getMembers: (channel: string) => PresenceMember[]
-  handleClose: (ws: ServerWebSocket<WsConnectionData>) => void
-  handleMessage: (ws: ServerWebSocket<WsConnectionData>, raw: string | Uint8Array) => Promise<void>
-  handleOpen: (ws: ServerWebSocket<WsConnectionData>) => void
+  handleClose: (ws: Bun.ServerWebSocket<WsConnectionData>) => void
+  handleMessage: (ws: Bun.ServerWebSocket<WsConnectionData>, raw: string | Uint8Array) => Promise<void>
+  handleOpen: (ws: Bun.ServerWebSocket<WsConnectionData>) => void
   send: (event: TypedBroadcastEvent<Channels, keyof Channels & string> | BroadcastEvent) => void
   setAuthSecret: (secret: string) => void
   signAuth: (socketId: string, channel: string, channelData?: string) => string
@@ -188,7 +188,7 @@ class TypedBroadcastManager = {
   toChannel: <Pattern extends ParameterizedChannels<Channels>, Ev extends EventsOf<Channels, Pattern>>(pattern: Pattern, params: ChannelParamRecord<Pattern>, event: Ev, data: PayloadOf<Channels, Pattern, Ev>) => void
   upgradeData: (req: Request) => Record<string, unknown>
   verifyAuth: (socketId: string, channel: string, auth: string, channelData?: string) => boolean
-  wsHandlers: {    open: (ws: ServerWebSocket<WsConnectionData>) => void;    message: (ws: ServerWebSocket<WsConnectionData>, msg: string | Uint8Array) => undefined;    close: (ws: ServerWebSocket<WsConnectionData>) => void;}
+  wsHandlers: {    open: (ws: Bun.ServerWebSocket<WsConnectionData>) => void;    message: (ws: Bun.ServerWebSocket<WsConnectionData>, msg: string | Uint8Array) => undefined;    close: (ws: Bun.ServerWebSocket<WsConnectionData>) => void;}
 }
 
 const channelRegistry = ChannelRegistry
@@ -211,6 +211,14 @@ function presenceChannel = (name: string) => string
 
 function privateChannel = (name: string) => string
 
+interface BroadcastConfigShape = {
+  channels?: string
+  driver: 'null' | 'ws' | 'redis' | 'pusher'
+  path: string
+  pusher?: {    appKey: string;    appSecret: string;}
+  redis?: {    url: string;}
+}
+
 interface BroadcastEvent = {
   broadcastAs?: () => string
   broadcastOn: () => string | string[]
@@ -264,7 +272,7 @@ type BroadcastChannelMap = {    [x: string]: Record<string, object>;}
 
 type ChannelAuthFn = (channel: string, ws: ServerWebSocket<WsConnectionData>) => boolean | Promise<boolean>
 
-type ChannelCallback = (user: unknown, ...params: string[]) => boolean | PresenceMemberData | null | undefined | Promise<boolean | PresenceMemberData | null | undefined>
+type ChannelCallback = (user: User, ...params: string[]) => boolean | PresenceMemberData | null | undefined | Promise<boolean | PresenceMemberData | null | undefined>
 
 type ChannelParamRecord = [ChannelParams<Pattern>] extends [never] ? undefined : { [K in ChannelParams<Pattern>]: string | number; }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/broadcasting",
-  "version": "1.7.0",
+  "version": "1.7.3",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.7.0"
+    "@zerotal/core": "1.7.3"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/BroadcastManager.ts

@@ -1,3 +1,4 @@
+import type { ServerWebSocket } from "bun";
 import { safeEqual, hmacHex } from "@zerotal/core";
 import { isPrivateChannel } from "./Channel.ts";
 import type { BroadcastEvent, WsConnectionData, ClientMessage, ChannelAuthFn } from "./types.ts";
@@ -290,8 +291,13 @@ export class BroadcastManager {
     channelData?: string,
   ): Promise<void> {
     const isPresence = channel.startsWith("presence-");
-    const deny = () =>
+    // Block body, not an expression body: `ServerWebSocket.send` returns a send
+    // status, and `return deny()` in a `Promise<void>` method would otherwise
+    // try to return that number. The status is not useful here — a client that
+    // failed to receive its own denial is already gone.
+    const deny = (): void => {
       ws.send(JSON.stringify({ event: "subscription_error", channel, message: "Unauthorized" }));
+    };
 
     if (isPresence) {
       // Two ways to authorize a presence subscription:
@@ -352,7 +358,7 @@ export class BroadcastManager {
 
   private _unsubscribe(ws: WS, channel: string): void {
     this._subs.get(channel)?.delete(ws.data.id);
-    // Presence: an explicit leave (e.g. Echo.leave on a component teardown / SPA navigation) must
+    // Presence: an explicit leave (e.g. Socket.leave on a component teardown / SPA navigation) must
     // remove the member and notify the remaining subscribers — the same cleanup a full disconnect
     // does in handleClose. Without this, a member who navigated away lingers in others' "who's here"
     // until they close the tab.

package/src/BroadcastsModelEvents.ts

@@ -45,7 +45,7 @@ type ModelClassWithEvents<M> = (new (...args: never[]) => M) & {
  *   // optional: with: (order) => ({ id: order.id, status: order.status }),
  * });
  *
- * // Client: Echo.private(`orders.${id}`).listen("OrderUpdated", (e) => ...)
+ * // Client: Socket.private(`orders.${id}`).listen("OrderUpdated", (e) => ...)
  */
 export function broadcastsModelEvents<M extends object>(
   ModelClass: ModelClassWithEvents<M>,

package/src/ChannelRegistry.ts

@@ -21,8 +21,19 @@ export interface PresenceMemberData {
  * - Presence channel: return a member-data object to authorize + publish presence, or
  *   `false`/`null`/`undefined` to deny.
  */
-export type ChannelCallback = (
-  user: unknown,
+/**
+ * `User` is a type parameter so a rule can annotate the user it expects:
+ *
+ * ```ts
+ * Broadcast.channel("orders.[orderId]", (user: User, orderId: string) => …);
+ * ```
+ *
+ * infers `User` from the callback rather than failing against a fixed `unknown`.
+ * The default keeps every existing rule — and the registry's own storage, which
+ * cannot know the app's user model — working unchanged.
+ */
+export type ChannelCallback<User = unknown> = (
+  user: User,
   ...params: string[]
 ) =>
   | boolean
@@ -77,9 +88,11 @@ export class ChannelRegistry {
    * @example
    * registry.register("orders.[orderId]", (user, orderId) => user.id === ownerOf(orderId));
    */
-  register(pattern: string, callback: ChannelCallback): void {
+  register<User = unknown>(pattern: string, callback: ChannelCallback<User>): void {
     const { regex, paramNames } = compileChannelPattern(pattern);
-    this._channels.push({ pattern, regex, paramNames, callback });
+    // Stored as the unknown-user form: the registry calls every rule with whatever
+    // the auth middleware produced, which it has no way to type.
+    this._channels.push({ pattern, regex, paramNames, callback: callback as ChannelCallback });
   }
 
   /** Registered channel patterns (for `channel:list` / introspection). */

package/src/PusherCompatManager.ts

@@ -1,3 +1,4 @@
+import type { ServerWebSocket } from "bun";
 import { safeEqual, hmacHex } from "@zerotal/core";
 import { BroadcastManager, _isValidChannel } from "./BroadcastManager.ts";
 import type { PresenceMember } from "./BroadcastManager.ts";
@@ -44,9 +45,9 @@ export type PusherPresenceResolver = (
  *  - Auth for private/presence channels uses HMAC-SHA256 signatures
  *
  * Auth flow:
- *  1. Echo calls POST /broadcasting/auth with socket_id + channel_name
+ *  1. The client calls POST /broadcasting/auth with socket_id + channel_name
  *  2. Server signs with `signAuth()` and returns `{auth: "key:sig"}`
- *  3. Echo includes `auth` in the pusher:subscribe message
+ *  3. The client includes `auth` in the pusher:subscribe message
  *  4. Manager verifies HMAC before allowing subscription
  *
  * @example

package/src/config.ts

@@ -31,6 +31,19 @@ export interface BroadcastConfigShape {
     appKey: string;
     appSecret: string;
   };
+  /**
+   * Where the `Broadcast.channel(...)` authorization rules live, relative to the
+   * project root (or absolute).
+   *
+   * Defaults to `routes/channels.ts`. Set it when the app keeps its routes
+   * somewhere else — an app that scaffolded its HTTP routes into `app/routes`
+   * would otherwise grow a second, unrelated `routes/` directory holding one
+   * file.
+   *
+   * @example
+   * channels: "app/routes/channels.ts"
+   */
+  channels?: string;
 }
 
 const defaults: BroadcastConfigShape = {

package/src/currentSocketId.ts

@@ -1,6 +1,6 @@
 import { RequestContext } from "@zerotal/core";
 
-/** Read the client's Echo socket id from the current request's `X-Socket-ID` header, if any. */
+/** Read the client's socket id from the current request's `X-Socket-ID` header, if any. */
 export function currentSocketId(): string | undefined {
   return RequestContext.tryGet()?.header("x-socket-id") ?? undefined;
 }

package/src/facades/Broadcast.ts

@@ -58,7 +58,7 @@ export class Broadcast {
    *   return user.canJoin(roomId) ? { id: user.id, name: user.name } : null;
    * });
    */
-  static channel(pattern: string, callback: ChannelCallback): void {
+  static channel<User = unknown>(pattern: string, callback: ChannelCallback<User>): void {
     channelRegistry.register(pattern, callback);
   }
 

package/src/index.ts

@@ -18,6 +18,9 @@ export { BroadcastFake } from "./BroadcastFake.ts";
 export { Broadcast } from "./facades/Broadcast.ts";
 export { BroadcastProvider } from "./provider/BroadcastProvider.ts";
 export { BroadcastConfig } from "./config.ts";
+// Exported so an app can cast an `env()`-derived driver to the literal union it
+// has to satisfy, the way `config/queue.ts` does with `QueueConfigShape`.
+export type { BroadcastConfigShape } from "./config.ts";
 export { channel, privateChannel, presenceChannel, isPrivateChannel } from "./Channel.ts";
 export { BroadcastingEvent, broadcastOnce } from "./BroadcastingEvent.ts";
 export { broadcastsModelEvents } from "./BroadcastsModelEvents.ts";

package/src/provider/BroadcastProvider.ts

@@ -19,11 +19,21 @@ declare module "@zerotal/core" {
   }
 }
 
+/** Where channel rules live when `config.broadcasting.channels` says nothing. */
+const DEFAULT_CHANNELS_PATH = "routes/channels.ts";
+
+/** POSIX `/…` and Windows `C:\…` both, since this joins a path by hand. */
+function isAbsolutePath(path: string): boolean {
+  return path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path);
+}
+
 export class BroadcastProvider extends ServiceProvider {
   static override provides = ["broadcast"] as const;
   static override environments: AppEnvironment[] = ["web", "worker", "test", "console"];
 
   private _redisDriver: RedisBroadcastDriver | undefined;
+  /** Resolved in `onRegister`, read in `onBooting`, so config is read once. */
+  private _channelsPath = DEFAULT_CHANNELS_PATH;
 
   override onRegister(): void {
     // Refuse a production boot when the configured driver is missing the
@@ -36,6 +46,7 @@ export class BroadcastProvider extends ServiceProvider {
     const configManager = this.app.container.tryMake("config") as ConfigManager | null;
     const raw = configManager?.get<Partial<BroadcastConfigShape>>("broadcasting") ?? {};
     const cfg = BroadcastConfig(raw);
+    this._channelsPath = cfg.channels ?? DEFAULT_CHANNELS_PATH;
 
     let manager: BroadcastManager;
 
@@ -104,11 +115,15 @@ export class BroadcastProvider extends ServiceProvider {
    * rules register before the first `/broadcasting/auth` request. Missing file is fine.
    */
   private async _loadChannelRoutes(): Promise<void> {
-    const path = `${process.cwd()}/routes/channels.ts`;
+    const configured = this._channelsPath;
+    // Absolute stays as given; relative resolves from the project root, so an app
+    // that keeps its routes under `app/routes` can point at
+    // `app/routes/channels.ts` instead of growing a second `routes/` directory.
+    const path = isAbsolutePath(configured) ? configured : `${process.cwd()}/${configured}`;
     try {
       if (await Bun.file(path).exists()) await import(path);
     } catch (err) {
-      frameworkLog("broadcast").error("Failed to load routes/channels.ts", undefined, err);
+      frameworkLog("broadcast").error(`Failed to load ${configured}`, undefined, err);
     }
   }
 

package/src/types.ts

@@ -1,3 +1,5 @@
+import type { ServerWebSocket } from "bun";
+
 // ── BroadcastEvent ────────────────────────────────────────────────────────────
 
 /**

package/src/global.d.ts

@@ -1,10 +0,0 @@
-// Ambient declarations specific to this package.
-// Bun, Node (node:*), and bun:test types come from @types/bun (→ bun-types).
-// Only declarations bun-types does NOT provide are kept here.
-
-interface ServerWebSocket<T = unknown> {
-  readonly data: T;
-  send(message: string | Uint8Array): void;
-  close(code?: number, reason?: string): void;
-  readyState: number;
-}