@zerotal/broadcasting 1.6.3 → 1.7.0

package/api-surface.md

@@ -0,0 +1,285 @@
+# @zerotal/broadcasting — public API surface
+
+<!-- AUTO-GENERATED by scripts/api-surface.ts. Do not edit by hand.
+     Run `bun run api:surface` to regenerate after an intentional API change. -->
+
+## .  `(./src/index.ts)`
+
+class AnonymousBroadcast = {
+  new (channel: string): AnonymousBroadcast
+  as: (event: string) => AnonymousBroadcast
+  send: () => void
+  sendNow: () => void
+  toOthers: () => AnonymousBroadcast
+  with: (data: unknown) => AnonymousBroadcast
+}
+
+class Broadcast = {
+  new (): Broadcast
+  static channel: (pattern: string, callback: ChannelCallback) => void
+  static channels: () => {    pattern: string;    paramNames: string[];}[]
+  static fake: () => BroadcastFake
+  static getMembers: (channel: string) => PresenceMember[]
+  static on: (channel: string) => AnonymousBroadcast
+  static presence: (channel: string) => AnonymousBroadcast
+  static private: (channel: string) => AnonymousBroadcast
+  static resetFake: () => void
+  static send: (event: BroadcastEvent, opts?: {    exceptSocketId?: string;}) => void
+  static to: (channel: string, eventName: string, data?: unknown, opts?: {    exceptSocketId?: string;}) => void
+}
+
+class BroadcastError = {
+  new (message: string, code?: string, status?: number, context?: Record<string, unknown>): BroadcastError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class BroadcastFake = {
+  new (): BroadcastFake
+  assertBroadcast: (eventName: string, channel?: string, data?: Record<string, unknown>) => void
+  assertBroadcastCount: (count: number) => void
+  assertNotBroadcast: (eventName: string, channel?: string) => void
+  assertNothingBroadcast: () => void
+  recorded: () => RecordedBroadcast[]
+  reset: () => void
+  send: (event: BroadcastEvent, opts?: {    exceptSocketId?: string;}) => void
+  to: (channel: string, eventName: string, data?: unknown, _opts?: {    exceptSocketId?: string;}) => void
+}
+
+class BroadcastingEvent = {
+  new (): BroadcastingEvent
+  static dispatch: <T extends BroadcastingEvent, A extends unknown[]>(this: new (...args: A) => T, ...args: A) => T
+  broadcastAs: () => string
+  broadcastOn: () => string | string[]
+  broadcastWhen: () => boolean
+  broadcastWith: () => object
+}
+
+class BroadcastManager = {
+  new (): BroadcastManager
+  authorizePresenceWith: (fn: PresenceAuthFn) => void
+  authorizeWith: (fn: ChannelAuthFn) => void
+  connectionCount: () => number
+  getMembers: (channel: string) => PresenceMember[]
+  handleClose: (ws: WS) => void
+  handleMessage: (ws: WS, raw: string | Uint8Array) => Promise<void>
+  handleOpen: (ws: WS) => void
+  send: (event: BroadcastEvent, opts?: {    exceptSocketId?: string;}) => void
+  setAuthSecret: (secret: string) => void
+  signAuth: (socketId: string, channel: string, channelData?: string) => string
+  subscriberCount: (channel: string) => number
+  subscriptionsFor: (connectionId: string) => string[]
+  to: (channel: string, eventName: 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: WS) => void;    message: (ws: WS, msg: string | Uint8Array) => undefined;    close: (ws: WS) => void;}
+}
+
+class BroadcastProvider = {
+  new (app: Application): BroadcastProvider
+  static dependsOn?: (new (app: Application) => ServiceProvider)[]
+  static environments: AppEnvironment[]
+  static priority?: number
+  static provides: readonly ['broadcast']
+  devProcesses: () => DevProcessDefinition[]
+  doctorChecks: () => DoctorCheck[]
+  onBooted: () => Promise<void>
+  onBooting: () => Promise<void>
+  onRegister: () => void
+  onRequestProcessed: (_ctx: HttpContext) => Promise<void>
+  onRequestReceived: (_ctx: HttpContext) => Promise<void>
+  onResponseSent: (_ctx: HttpContext) => Promise<void>
+  onStarted: () => Promise<void>
+  onStarting: () => Promise<void>
+  onStopped: () => Promise<void>
+  onStopping: () => Promise<void>
+  replContext: () => Record<string, unknown>
+}
+
+class BroadcastProviderNotRegisteredError = {
+  new (): BroadcastProviderNotRegisteredError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class ChannelRegistry = {
+  new (): ChannelRegistry
+  all: () => {    pattern: string;    paramNames: string[];}[]
+  authorize: (channelName: string, user: unknown) => Promise<AuthorizeResult>
+  clear: () => void
+  register: (pattern: string, callback: ChannelCallback) => void
+}
+
+class MissingChannelParameterError = {
+  new (key: string): MissingChannelParameterError
+  readonly code: string
+  readonly context?: Record<string, unknown> | undefined
+  readonly status: number
+}
+
+class PendingBroadcast = {
+  new (event: BroadcastEvent): PendingBroadcast
+  send: () => void
+  then: <TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null) => PromiseLike<TResult1 | TResult2>
+  toOthers: () => PendingBroadcast
+}
+
+class PusherCompatManager = {
+  new (_appKey: string, _appSecret: string): PusherCompatManager
+  authorizePresenceWith: (fn: PresenceAuthFn) => void
+  authorizeWith: (fn: ChannelAuthFn) => void
+  connectionCount: () => number
+  getMembers: (channel: string) => PresenceMember[]
+  handleClose: (ws: WS) => void
+  handleMessage: (ws: WS, raw: string | Uint8Array) => Promise<void>
+  handleOpen: (ws: WS) => void
+  resolvePresence: (req: Request, channel: string) => Promise<{    id: string | number;    info?: Record<string, unknown>;} | false>
+  resolvePresenceWith: (fn: PusherPresenceResolver) => void
+  send: (event: BroadcastEvent, opts?: {    exceptSocketId?: string;}) => void
+  setAuthSecret: (secret: string) => void
+  signAuth: (socketId: string, channel: string, channelData?: string) => string
+  subscriberCount: (channel: string) => number
+  subscriptionsFor: (connectionId: string) => string[]
+  to: (channel: string, eventName: 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;}
+}
+
+class RedisBroadcastDriver = {
+  new (_url: string): RedisBroadcastDriver
+  authorizePresenceWith: (fn: PresenceAuthFn) => void
+  authorizeWith: (fn: ChannelAuthFn) => void
+  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
+  send: (event: BroadcastEvent, opts?: {    exceptSocketId?: string;}) => void
+  setAuthSecret: (secret: string) => void
+  signAuth: (socketId: string, channel: string, channelData?: string) => string
+  stop: () => Promise<void>
+  subscriberCount: (channel: string) => number
+  subscriptionsFor: (connectionId: string) => string[]
+  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;}
+}
+
+class TypedBroadcastManager = {
+  new <Channels extends BroadcastChannelMap>(): TypedBroadcastManager<Channels>
+  authorizePresenceWith: (fn: PresenceAuthFn) => void
+  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
+  send: (event: TypedBroadcastEvent<Channels, keyof Channels & string> | BroadcastEvent) => void
+  setAuthSecret: (secret: string) => void
+  signAuth: (socketId: string, channel: string, channelData?: string) => string
+  subscriberCount: (channel: string) => number
+  subscriptionsFor: (connectionId: string) => string[]
+  to: {    <Ch extends StaticChannels<Channels>, Ev extends EventsOf<Channels, Ch>>(channel: Ch, event: Ev, data: PayloadOf<Channels, Ch, Ev>, opts?: {        exceptSocketId?: string;    }): void;    (channel: string, event: string, data?: unknown, opts?: {        exceptSocketId?: string;    }): void;}
+  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;}
+}
+
+const channelRegistry = ChannelRegistry
+
+function broadcast = (event: BroadcastEvent) => PendingBroadcast
+
+function BroadcastConfig = (overrides?: Partial<BroadcastConfigShape>) => BroadcastConfigShape
+
+function broadcastOnce = (event: BroadcastEvent) => void
+
+function broadcastsModelEvents = <M extends object>(ModelClass: ModelClassWithEvents<M>, options: BroadcastsModelEventsOptions<M>) => void
+
+function channel = (name: string) => string
+
+function compileChannelPattern = (pattern: string) => {    regex: RegExp;    paramNames: string[];}
+
+function isPrivateChannel = (name: string) => boolean
+
+function presenceChannel = (name: string) => string
+
+function privateChannel = (name: string) => string
+
+interface BroadcastEvent = {
+  broadcastAs?: () => string
+  broadcastOn: () => string | string[]
+  broadcastWith?: () => object
+}
+
+interface BroadcastRecord = {
+  channel: string
+  data: Record<string, unknown>
+  event: string
+}
+
+interface BroadcastsModelEventsOptions = {
+  as?: (modelName: string, event: ModelBroadcastEventName) => string
+  channels: (model: M, event: ModelBroadcastEventName) => string | string[]
+  events?: ModelBroadcastEventName[]
+  with?: (model: M, event: ModelBroadcastEventName) => object
+}
+
+interface PresenceMember = {
+  id: string | number
+  info: Record<string, unknown>
+}
+
+interface PresenceMemberData = {
+  [key: string]: unknown
+  id: string | number
+}
+
+interface RecordedBroadcast = {
+  channel: string
+  data: Record<string, unknown>
+  event: string
+}
+
+interface TypedBroadcastEvent = {
+  broadcastAs: () => Ev
+  broadcastOn: () => Ch | Ch[]
+  broadcastWith: () => PayloadOf<M, Ch, Ev>
+}
+
+interface WsConnectionData = {
+  id: string
+  token?: string
+  userId?: string | number
+}
+
+type AuthorizeResult = {    matched: false;} | {    matched: true;    result: boolean | PresenceMemberData | null | undefined;}
+
+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 ChannelParamRecord = [ChannelParams<Pattern>] extends [never] ? undefined : { [K in ChannelParams<Pattern>]: string | number; }
+
+type ChannelParams = Pattern extends `${string}[${infer Param}]${infer Tail}` ? Param | ChannelParams<Tail> : never
+
+type EventsOf = keyof M[Ch] & string
+
+type ModelBroadcastEventName = 'created' | 'updated' | 'deleted'
+
+type ParameterizedChannels = { [K in keyof M & string]: [ChannelParams<K>] extends [never] ? never : K; }[keyof M & string]
+
+type PayloadOf = M[Ch][Ev]
+
+type PresenceAuthFn = (channel: string, ws: ServerWebSocket<WsConnectionData>) => Promise<PresenceMember | false> | PresenceMember | false
+
+type PusherPresenceResolver = (req: Request, channel: string) => Promise<{    id: string | number;    info?: Record<string, unknown>;} | false> | {    id: string | number;    info?: Record<string, unknown>;} | false
+
+type StaticChannels = { [K in keyof M & string]: [ChannelParams<K>] extends [never] ? K : never; }[keyof M & string]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/broadcasting",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -12,6 +12,7 @@
   },
   "files": [
     "CHANGELOG.md",
+    "api-surface.md",
     "src",
     "!src/**/*.test.ts",
     "!src/**/*.test.tsx",
@@ -29,7 +30,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.6.3"
+    "@zerotal/core": "1.7.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"