@rlanz/socket 0.0.1-5 → 0.0.1-7

package/build/{types-C7Q36ryo.d.ts → base_channel-Dr40l7CW.d.ts}

@@ -72,161 +72,6 @@ declare class PresenceManager {
     getLocalSockets(channel: string): PresenceSocket[];
 }
 
-interface ChannelBroadcaster {
-    to(channel: string): {
-        emit(event: string, data: unknown): void;
-        except(socketId: string): {
-            emit(event: string, data: unknown): void;
-        };
-    };
-}
-/**
- * Error whose message may intentionally be returned to a socket client.
- */
-declare class SocketResponseError extends Error {
-}
-/**
- * Abstract class used to define a channel.
- *
- * @example
- * ```ts
- * export default class ChatChannel extends BaseChannel {
- *   static pattern = 'chat/:roomId'
- *   static middlewares = [
- *     async (ctx, next) => {
- *       // Authorize access to the channel through middleware.
- *       // if (!Room.isMember(ctx.params.roomId, ctx.socket.user.id)) throw new Error('Forbidden')
- *       await next()
- *     },
- *   ]
- * }
- * ```
- *
- * @example With presence and decorated handlers
- * ```ts
- * import { onMessage } from '@rlanz/socket/decorators'
- *
- * export default class ChatChannel extends BaseChannel {
- *   static pattern = 'chat/:roomId'
- *   static options = { presence: true }
- *
- *   static middlewares = [
- *     async (ctx, next) => {
- *       if (!ctx.socket.user.isVerified) throw new Error('Not verified')
- *       await next()
- *     }
- *   ]
- *
- *   @onMessage('chat:send')
- *   async handleSend(socket: AuthenticatedSocket<User>, data: unknown) {
- *     // Handle chat:send event
- *   }
- *
- *   @onMessage('chat:typing')
- *   async handleTyping(socket: AuthenticatedSocket<User>, data: unknown) {
- *     // Handle chat:typing event
- *   }
- * }
- * ```
- */
-declare class BaseChannel<User = unknown, ServerEvents = unknown> {
-    /** Type-only server event declarations consumed by generated browser client types. */
-    readonly $serverEvents: ServerEvents;
-    /**
-     * URL-like channel pattern, for example: 'chat/:roomId'.
-     */
-    static pattern: string;
-    /**
-     * Channel options.
-     */
-    static options?: ChannelOptions;
-    /**
-     * Middlewares to run before subscription.
-     */
-    static middlewares?: Middleware<any>[];
-    /**
-     * Event handler map.
-     * Ex: { 'chat:send': 'handleSend' }
-     */
-    protected handlers: ChannelHandlerMap<User>;
-    /**
-     * Injected socket service.
-     */
-    protected socket: ChannelBroadcaster;
-    /**
-     * Full channel name, for example: 'chat/general'.
-     */
-    protected channelName: string;
-    /**
-     * Parameters extracted from the pattern, for example: { roomId: 'general' }.
-     */
-    protected params: Record<string, string>;
-    /**
-     * Injected presence manager when presence is enabled.
-     */
-    protected presence: PresenceManager;
-    /**
-     * Injects dependencies.
-     */
-    $setContext(socket: ChannelBroadcaster, channelName: string, params: Record<string, string>, presence?: PresenceManager): void;
-    /**
-     * Emits to every channel member.
-     */
-    protected broadcast<K extends unknown extends ServerEvents ? string : keyof ServerEvents & string>(event: K, data: unknown extends ServerEvents ? unknown : ServerEvents[K & keyof ServerEvents]): void;
-    /**
-     * Emits to every channel member except one socket.
-     */
-    protected broadcastExcept<K extends unknown extends ServerEvents ? string : keyof ServerEvents & string>(socketId: string, event: K, data: unknown extends ServerEvents ? unknown : ServerEvents[K & keyof ServerEvents]): void;
-    /**
-     * Runs the middleware chain.
-     *
-     * middleware[0] -> middleware[1] -> ... -> subscribe
-     */
-    $runMiddlewares(ctx: MiddlewareContext<User>): Promise<void>;
-    /**
-     * Returns member information for presence.
-     * Implement when options.presence = true.
-     */
-    getPresenceInfo?(socket: AuthenticatedSocket<User>): PresenceInfo;
-    /**
-     * Hook called when a socket joins the channel.
-     */
-    onJoin?(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>;
-    /**
-     * Hook called when a socket leaves the channel.
-     */
-    onLeave?(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>;
-    /**
-     * Hook called when a message is received on the channel.
-     * Used as fallback when no event handler matches.
-     */
-    onMessage?(socket: AuthenticatedSocket<User>, event: string, data: unknown): Promise<void>;
-    /**
-     * Hook called when a member joins a presence channel.
-     */
-    onMemberJoin?(socket: AuthenticatedSocket<User>, member: PresenceMember, ...params: string[]): Promise<void>;
-    /**
-     * Hook called when a member leaves a presence channel.
-     */
-    onMemberLeave?(socket: AuthenticatedSocket<User>, member: PresenceMember, ...params: string[]): Promise<void>;
-    /**
-     * Dispatches a message to the matching handler.
-     * Called by SocketService. Do not override.
-     */
-    $handleMessage(socket: AuthenticatedSocket<User>, event: string, data: unknown): Promise<unknown>;
-    /**
-     * Runs the generic join hook. ChannelSubscriptions owns subscription lifecycle.
-     */
-    $handleJoin(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>;
-    /**
-     * Runs the generic leave hook. ChannelSubscriptions owns subscription lifecycle.
-     */
-    $handleLeave(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>;
-    $getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceInfo;
-}
-/** Constructor for any BaseChannel specialization. */
-type BaseChannelConstructor = typeof BaseChannel<any, any>;
-
 /**
  * Duration can be specified as milliseconds or as a human-readable string.
  */
@@ -239,6 +84,19 @@ interface SocketTransportConfig {
      * How long to wait for other instances to answer a presence snapshot request.
      */
     presenceTimeout?: Duration;
+    /**
+     * In-memory retry policy for transport publications that fail.
+     *
+     * The queue is enabled and limited to 1000 distinct messages by default.
+     * Set maxSize to null only when an unbounded queue is explicitly desired.
+     */
+    retryQueue?: SocketRetryQueueConfig;
+}
+interface SocketRetryQueueConfig {
+    enabled?: boolean;
+    removeDuplicates?: boolean;
+    maxSize?: number | null;
+    retryInterval?: Duration | false;
 }
 
 /**
@@ -281,17 +139,13 @@ interface AuthenticatedSocket<User = unknown> {
      */
     user: User | undefined;
     /**
-     * Emits an event to this socket.
+     * Returns the authenticated user or throws a client-safe unauthorized error.
      */
-    emit(event: string, data: unknown): void;
-    /**
-     * Joins the user target used by SocketService.toUser().
-     */
-    joinUserRoom(userId: string | number): Promise<void>;
+    getUserOrFail(): User;
     /**
-     * Leaves the current SocketService.toUser() target.
+     * Emits an event to this socket.
      */
-    leaveUserRoom(): Promise<void>;
+    emit(event: string, data: unknown): void;
     /**
      * Disconnects the socket.
      */
@@ -310,6 +164,8 @@ interface SocketUpgradeContext {
 }
 type SocketAuthenticationResult<User = unknown> = User | false | null;
 type SocketAuthenticationHandler<User = unknown> = (ctx: SocketUpgradeContext) => SocketAuthenticationResult<User> | Promise<SocketAuthenticationResult<User>>;
+type SocketOriginValues = boolean | string | string[];
+type SocketOriginResolver = (origin: string, httpContext: HttpContext) => SocketOriginValues;
 /**
  * AdonisJS HTTP middleware executed for the WebSocket upgrade request.
  */
@@ -373,8 +229,6 @@ type Middleware<User = unknown> = MiddlewareFn<User> | MiddlewareClass<User>;
 type ChannelServerEventsOf<T> = T extends {
     readonly $serverEvents: infer Events;
 } ? Events : unknown;
-type ChannelHandlerFn<User = unknown> = (socket: AuthenticatedSocket<User>, data: any) => unknown | Promise<unknown>;
-type ChannelHandlerMap<User = unknown> = Record<string, ChannelHandlerFn<User>>;
 /**
  * Package configuration.
  */
@@ -382,10 +236,14 @@ interface SocketConfig<User = unknown> {
     websocket?: {
         path?: string;
         /**
-         * Additional browser origins allowed to open a WebSocket connection.
-         * Same-origin requests and clients without an Origin header are allowed by default.
+         * Browser origin policy for opening a WebSocket connection.
+         *
+         * Uses the same value shapes as the AdonisJS CORS `origin` option. A resolver
+         * receives the request origin and HTTP context and may return any static value.
+         * Same-origin requests are allowed by default when this option is not defined.
+         * Clients without an Origin header are always allowed.
          */
-        allowedOrigins?: string[];
+        origin?: SocketOriginValues | SocketOriginResolver;
         /**
          * HTTP middleware executed only for the WebSocket upgrade request.
          *
@@ -473,4 +331,155 @@ interface SocketEvents<User = unknown> {
     };
 }
 
-export { type AuthenticatedSocket as A, BaseChannel as B, type ChannelHandlerMap as C, type Duration as D, type Middleware as M, PresenceManager as P, type RawSocket as R, type SocketConfig as S, type ChannelServerEventsOf as a, type ChannelAck as b, type ChannelMessage as c, type SocketAuthenticationHandler as d, type BaseChannelConstructor as e, type ChannelHandlerFn as f, type ChannelMatch as g, type ChannelOptions as h, type MiddlewareClass as i, type MiddlewareContext as j, type MiddlewareFn as k, type PresenceInfo as l, type PresenceMember as m, type SocketAuthenticationResult as n, type SocketEvents as o, type SocketHealthSnapshot as p, type SocketHttpMiddleware as q, SocketResponseError as r, type SocketServiceStatus as s, type SocketUpgradeContext as t, type PresenceData as u };
+interface ChannelBroadcaster {
+    to(channel: string): {
+        emit(event: string, data: unknown): void;
+        except(socketId: string): {
+            emit(event: string, data: unknown): void;
+        };
+    };
+}
+/**
+ * Error whose message may intentionally be returned to a socket client.
+ */
+declare class SocketResponseError extends Error {
+}
+/**
+ * Abstract class used to define a channel.
+ *
+ * @example
+ * ```ts
+ * export default class ChatChannel extends BaseChannel {
+ *   static pattern = 'chat/:roomId'
+ *   static middlewares = [
+ *     async (ctx, next) => {
+ *       // Authorize access to the channel through middleware.
+ *       // if (!Room.isMember(ctx.params.roomId, ctx.socket.user.id)) throw new Error('Forbidden')
+ *       await next()
+ *     },
+ *   ]
+ * }
+ * ```
+ *
+ * @example With presence and decorated handlers
+ * ```ts
+ * import { onMessage } from '@rlanz/socket/decorators'
+ *
+ * export default class ChatChannel extends BaseChannel {
+ *   static pattern = 'chat/:roomId'
+ *   static options = { presence: true }
+ *
+ *   static middlewares = [
+ *     async (ctx, next) => {
+ *       if (!ctx.socket.user.isVerified) throw new Error('Not verified')
+ *       await next()
+ *     }
+ *   ]
+ *
+ *   @onMessage('chat:send')
+ *   async handleSend(socket: AuthenticatedSocket<User>, data: unknown) {
+ *     // Handle chat:send event
+ *   }
+ *
+ *   @onMessage('chat:typing')
+ *   async handleTyping(socket: AuthenticatedSocket<User>, data: unknown) {
+ *     // Handle chat:typing event
+ *   }
+ * }
+ * ```
+ */
+declare class BaseChannel<User = unknown, ServerEvents = Record<never, never>> {
+    /** Type-only server event declarations consumed by generated browser client types. */
+    readonly $serverEvents: ServerEvents;
+    /**
+     * URL-like channel pattern, for example: 'chat/:roomId'.
+     */
+    static pattern: string;
+    /**
+     * Channel options.
+     */
+    static options?: ChannelOptions;
+    /**
+     * Middlewares to run before subscription.
+     */
+    static middlewares?: Middleware<any>[];
+    /**
+     * Injected socket service.
+     */
+    protected socket: ChannelBroadcaster;
+    /**
+     * Full channel name, for example: 'chat/general'.
+     */
+    protected channelName: string;
+    /**
+     * Parameters extracted from the pattern, for example: { roomId: 'general' }.
+     */
+    protected params: Record<string, string>;
+    /**
+     * Injected presence manager when presence is enabled.
+     */
+    protected presence: PresenceManager;
+    /**
+     * Injects dependencies.
+     */
+    $setContext(socket: ChannelBroadcaster, channelName: string, params: Record<string, string>, presence?: PresenceManager): void;
+    /**
+     * Emits to every channel member.
+     */
+    protected broadcast<K extends keyof ServerEvents & string>(event: K, data: ServerEvents[K]): void;
+    /**
+     * Emits to every channel member except one socket.
+     */
+    protected broadcastExcept<K extends keyof ServerEvents & string>(socketId: string, event: K, data: ServerEvents[K]): void;
+    /**
+     * Runs the middleware chain.
+     *
+     * middleware[0] -> middleware[1] -> ... -> subscribe
+     */
+    $runMiddlewares(ctx: MiddlewareContext<User>): Promise<void>;
+    /**
+     * Returns member information for presence.
+     * Implement when options.presence = true.
+     */
+    getPresenceInfo?(socket: AuthenticatedSocket<User>): PresenceInfo;
+    /**
+     * Hook called when a socket joins the channel.
+     */
+    onJoin?(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>;
+    /**
+     * Hook called when a socket leaves the channel.
+     */
+    onLeave?(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>;
+    /**
+     * Hook called when a member joins a presence channel.
+     */
+    onMemberJoin?(socket: AuthenticatedSocket<User>, member: PresenceMember, ...params: string[]): Promise<void>;
+    /**
+     * Hook called when a member leaves a presence channel.
+     */
+    onMemberLeave?(socket: AuthenticatedSocket<User>, member: PresenceMember, ...params: string[]): Promise<void>;
+    /**
+     * Dispatches a message to the matching handler.
+     * Called by SocketService. Do not override.
+     */
+    $handleMessage(socket: AuthenticatedSocket<User>, event: string, data: unknown): Promise<unknown>;
+    /**
+     * Runs the generic join hook. ChannelSubscriptions owns subscription lifecycle.
+     */
+    $handleJoin(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>;
+    /**
+     * Runs the generic leave hook. ChannelSubscriptions owns subscription lifecycle.
+     */
+    $handleLeave(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>;
+    $getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceInfo;
+}
+/** Constructor for any BaseChannel specialization, including container-injected dependencies. */
+interface BaseChannelConstructor {
+    new (...args: any[]): BaseChannel<any, any>;
+    readonly name: string;
+    pattern: string;
+    options?: ChannelOptions;
+    middlewares?: Middleware<any>[];
+}
+
+export { type AuthenticatedSocket as A, BaseChannel as B, type ChannelServerEventsOf as C, type Duration as D, type Middleware as M, PresenceManager as P, type RawSocket as R, type SocketAuthenticationHandler as S, type ChannelAck as a, type ChannelMessage as b, type SocketConfig as c, type ChannelOptions as d, type MiddlewareClass as e, type MiddlewareContext as f, type MiddlewareFn as g, type PresenceInfo as h, type PresenceMember as i, type SocketAuthenticationResult as j, type SocketEvents as k, type SocketHealthSnapshot as l, type SocketHttpMiddleware as m, type SocketOriginResolver as n, type SocketOriginValues as o, SocketResponseError as p, type SocketRetryQueueConfig as q, type SocketServiceStatus as r, type SocketTransportConfig as s, type SocketUpgradeContext as t, type BaseChannelConstructor as u, type ChannelMatch as v, type PresenceData as w };

package/build/chunk-2X6WGCH5.js

@@ -0,0 +1,120 @@
+import {
+  getDecoratedChannelHandlers
+} from "./chunk-G75J233Z.js";
+
+// src/base_channel.ts
+var SocketResponseError = class extends Error {
+};
+var MissingPresenceInfoError = class extends SocketResponseError {
+  constructor() {
+    super("Presence channels must implement getPresenceInfo(socket)");
+  }
+};
+var BaseChannel = class {
+  /**
+   * URL-like channel pattern, for example: 'chat/:roomId'.
+   */
+  static pattern;
+  /**
+   * Channel options.
+   */
+  static options;
+  /**
+   * Middlewares to run before subscription.
+   */
+  static middlewares;
+  /**
+   * Injected socket service.
+   */
+  socket;
+  /**
+   * Full channel name, for example: 'chat/general'.
+   */
+  channelName;
+  /**
+   * Parameters extracted from the pattern, for example: { roomId: 'general' }.
+   */
+  params;
+  /**
+   * Injected presence manager when presence is enabled.
+   */
+  presence;
+  /**
+   * Injects dependencies.
+   */
+  $setContext(socket, channelName, params, presence) {
+    this.socket = socket;
+    this.channelName = channelName;
+    this.params = params;
+    if (presence) {
+      this.presence = presence;
+    }
+  }
+  /**
+   * Emits to every channel member.
+   */
+  broadcast(event, data) {
+    this.socket.to(this.channelName).emit(event, data);
+  }
+  /**
+   * Emits to every channel member except one socket.
+   */
+  broadcastExcept(socketId, event, data) {
+    this.socket.to(this.channelName).except(socketId).emit(event, data);
+  }
+  /**
+   * Runs the middleware chain.
+   *
+   * middleware[0] -> middleware[1] -> ... -> subscribe
+   */
+  async $runMiddlewares(ctx) {
+    const middlewares = this.constructor.middlewares || [];
+    let index = 0;
+    const next = async () => {
+      if (index >= middlewares.length) return;
+      const middleware = middlewares[index++];
+      if (typeof middleware === "function") {
+        await middleware(ctx, next);
+      } else {
+        await middleware.handle(ctx, next);
+      }
+    };
+    await next();
+  }
+  /**
+   * Dispatches a message to the matching handler.
+   * Called by SocketService. Do not override.
+   */
+  async $handleMessage(socket, event, data) {
+    const handlers = getDecoratedChannelHandlers(this);
+    const handler = handlers[event];
+    if (typeof handler === "function") {
+      return Reflect.apply(handler, this, [socket, data]);
+    }
+    throw new SocketResponseError(`Unknown channel event: ${event}`);
+  }
+  /**
+   * Runs the generic join hook. ChannelSubscriptions owns subscription lifecycle.
+   */
+  async $handleJoin(socket, ...params) {
+    await this.onJoin?.(socket, ...params);
+  }
+  /**
+   * Runs the generic leave hook. ChannelSubscriptions owns subscription lifecycle.
+   */
+  async $handleLeave(socket, ...params) {
+    await this.onLeave?.(socket, ...params);
+  }
+  $getPresenceInfo(socket) {
+    if (!this.getPresenceInfo) {
+      throw new MissingPresenceInfoError();
+    }
+    return this.getPresenceInfo(socket);
+  }
+};
+
+export {
+  SocketResponseError,
+  BaseChannel
+};
+//# sourceMappingURL=chunk-2X6WGCH5.js.map

package/build/chunk-2X6WGCH5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/base_channel.ts"],"sourcesContent":["import type {\n  AuthenticatedSocket,\n  ChannelOptions,\n  PresenceInfo,\n  PresenceMember,\n  Middleware,\n  MiddlewareContext,\n} from './types.js'\nimport type { PresenceManager } from './presence_manager.js'\nimport { getDecoratedChannelHandlers } from './decorators.js'\n\ninterface ChannelBroadcaster {\n  to(channel: string): {\n    emit(event: string, data: unknown): void\n    except(socketId: string): {\n      emit(event: string, data: unknown): void\n    }\n  }\n}\n\n/**\n * Error whose message may intentionally be returned to a socket client.\n */\nexport class SocketResponseError extends Error {}\n\nexport class MissingPresenceInfoError extends SocketResponseError {\n  constructor() {\n    super('Presence channels must implement getPresenceInfo(socket)')\n  }\n}\n\n/**\n * Abstract class used to define a channel.\n *\n * @example\n * ```ts\n * export default class ChatChannel extends BaseChannel {\n *   static pattern = 'chat/:roomId'\n *   static middlewares = [\n *     async (ctx, next) => {\n *       // Authorize access to the channel through middleware.\n *       // if (!Room.isMember(ctx.params.roomId, ctx.socket.user.id)) throw new Error('Forbidden')\n *       await next()\n *     },\n *   ]\n * }\n * ```\n *\n * @example With presence and decorated handlers\n * ```ts\n * import { onMessage } from '@rlanz/socket/decorators'\n *\n * export default class ChatChannel extends BaseChannel {\n *   static pattern = 'chat/:roomId'\n *   static options = { presence: true }\n *\n *   static middlewares = [\n *     async (ctx, next) => {\n *       if (!ctx.socket.user.isVerified) throw new Error('Not verified')\n *       await next()\n *     }\n *   ]\n *\n *   @onMessage('chat:send')\n *   async handleSend(socket: AuthenticatedSocket<User>, data: unknown) {\n *     // Handle chat:send event\n *   }\n *\n *   @onMessage('chat:typing')\n *   async handleTyping(socket: AuthenticatedSocket<User>, data: unknown) {\n *     // Handle chat:typing event\n *   }\n * }\n * ```\n */\nexport class BaseChannel<User = unknown, ServerEvents = Record<never, never>> {\n  /** Type-only server event declarations consumed by generated browser client types. */\n  declare readonly $serverEvents: ServerEvents\n  /**\n   * URL-like channel pattern, for example: 'chat/:roomId'.\n   */\n  static pattern: string\n\n  /**\n   * Channel options.\n   */\n  static options?: ChannelOptions\n\n  /**\n   * Middlewares to run before subscription.\n   */\n  static middlewares?: Middleware<any>[]\n\n  /**\n   * Injected socket service.\n   */\n  protected socket!: ChannelBroadcaster\n\n  /**\n   * Full channel name, for example: 'chat/general'.\n   */\n  protected channelName!: string\n\n  /**\n   * Parameters extracted from the pattern, for example: { roomId: 'general' }.\n   */\n  protected params!: Record<string, string>\n\n  /**\n   * Injected presence manager when presence is enabled.\n   */\n  protected presence!: PresenceManager\n\n  /**\n   * Injects dependencies.\n   */\n  $setContext(\n    socket: ChannelBroadcaster,\n    channelName: string,\n    params: Record<string, string>,\n    presence?: PresenceManager\n  ): void {\n    this.socket = socket\n    this.channelName = channelName\n    this.params = params\n    if (presence) {\n      this.presence = presence\n    }\n  }\n\n  /**\n   * Emits to every channel member.\n   */\n  protected broadcast<K extends keyof ServerEvents & string>(\n    event: K,\n    data: ServerEvents[K]\n  ): void {\n    this.socket.to(this.channelName).emit(event, data)\n  }\n\n  /**\n   * Emits to every channel member except one socket.\n   */\n  protected broadcastExcept<K extends keyof ServerEvents & string>(\n    socketId: string,\n    event: K,\n    data: ServerEvents[K]\n  ): void {\n    this.socket.to(this.channelName).except(socketId).emit(event, data)\n  }\n\n  /**\n   * Runs the middleware chain.\n   *\n   * middleware[0] -> middleware[1] -> ... -> subscribe\n   */\n  async $runMiddlewares(ctx: MiddlewareContext<User>): Promise<void> {\n    const middlewares = (this.constructor as typeof BaseChannel).middlewares || []\n\n    let index = 0\n\n    const next = async (): Promise<void> => {\n      if (index >= middlewares.length) return\n\n      const middleware = middlewares[index++]\n\n      if (typeof middleware === 'function') {\n        await middleware(ctx, next)\n      } else {\n        await middleware.handle(ctx, next)\n      }\n    }\n\n    await next()\n  }\n\n  /**\n   * Returns member information for presence.\n   * Implement when options.presence = true.\n   */\n  getPresenceInfo?(socket: AuthenticatedSocket<User>): PresenceInfo\n\n  /**\n   * Hook called when a socket joins the channel.\n   */\n  onJoin?(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>\n\n  /**\n   * Hook called when a socket leaves the channel.\n   */\n  onLeave?(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void>\n\n  /**\n   * Hook called when a member joins a presence channel.\n   */\n  onMemberJoin?(\n    socket: AuthenticatedSocket<User>,\n    member: PresenceMember,\n    ...params: string[]\n  ): Promise<void>\n\n  /**\n   * Hook called when a member leaves a presence channel.\n   */\n  onMemberLeave?(\n    socket: AuthenticatedSocket<User>,\n    member: PresenceMember,\n    ...params: string[]\n  ): Promise<void>\n\n  /**\n   * Dispatches a message to the matching handler.\n   * Called by SocketService. Do not override.\n   */\n  async $handleMessage(\n    socket: AuthenticatedSocket<User>,\n    event: string,\n    data: unknown\n  ): Promise<unknown> {\n    const handlers = getDecoratedChannelHandlers<User>(this)\n    const handler = handlers[event]\n\n    if (typeof handler === 'function') {\n      return Reflect.apply(handler, this, [socket, data])\n    }\n\n    throw new SocketResponseError(`Unknown channel event: ${event}`)\n  }\n\n  /**\n   * Runs the generic join hook. ChannelSubscriptions owns subscription lifecycle.\n   */\n  async $handleJoin(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void> {\n    await this.onJoin?.(socket, ...params)\n  }\n\n  /**\n   * Runs the generic leave hook. ChannelSubscriptions owns subscription lifecycle.\n   */\n  async $handleLeave(socket: AuthenticatedSocket<User>, ...params: string[]): Promise<void> {\n    await this.onLeave?.(socket, ...params)\n  }\n\n  $getPresenceInfo(socket: AuthenticatedSocket<User>): PresenceInfo {\n    if (!this.getPresenceInfo) {\n      throw new MissingPresenceInfoError()\n    }\n\n    return this.getPresenceInfo(socket)\n  }\n}\n\n/** Constructor for any BaseChannel specialization, including container-injected dependencies. */\nexport interface BaseChannelConstructor {\n  new (...args: any[]): BaseChannel<any, any>\n  readonly name: string\n  pattern: string\n  options?: ChannelOptions\n  middlewares?: Middleware<any>[]\n}\n"],"mappings":";;;;;AAuBO,IAAM,sBAAN,cAAkC,MAAM;AAAC;AAEzC,IAAM,2BAAN,cAAuC,oBAAoB;AAAA,EAChE,cAAc;AACZ,UAAM,0DAA0D;AAAA,EAClE;AACF;AA8CO,IAAM,cAAN,MAAuE;AAAA;AAAA;AAAA;AAAA,EAM5E,OAAO;AAAA;AAAA;AAAA;AAAA,EAKP,OAAO;AAAA;AAAA;AAAA;AAAA,EAKP,OAAO;AAAA;AAAA;AAAA;AAAA,EAKG;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA;AAAA;AAAA;AAAA,EAKA;AAAA;AAAA;AAAA;AAAA,EAKV,YACE,QACA,aACA,QACA,UACM;AACN,SAAK,SAAS;AACd,SAAK,cAAc;AACnB,SAAK,SAAS;AACd,QAAI,UAAU;AACZ,WAAK,WAAW;AAAA,IAClB;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKU,UACR,OACA,MACM;AACN,SAAK,OAAO,GAAG,KAAK,WAAW,EAAE,KAAK,OAAO,IAAI;AAAA,EACnD;AAAA;AAAA;AAAA;AAAA,EAKU,gBACR,UACA,OACA,MACM;AACN,SAAK,OAAO,GAAG,KAAK,WAAW,EAAE,OAAO,QAAQ,EAAE,KAAK,OAAO,IAAI;AAAA,EACpE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAM,gBAAgB,KAA6C;AACjE,UAAM,cAAe,KAAK,YAAmC,eAAe,CAAC;AAE7E,QAAI,QAAQ;AAEZ,UAAM,OAAO,YAA2B;AACtC,UAAI,SAAS,YAAY,OAAQ;AAEjC,YAAM,aAAa,YAAY,OAAO;AAEtC,UAAI,OAAO,eAAe,YAAY;AACpC,cAAM,WAAW,KAAK,IAAI;AAAA,MAC5B,OAAO;AACL,cAAM,WAAW,OAAO,KAAK,IAAI;AAAA,MACnC;AAAA,IACF;AAEA,UAAM,KAAK;AAAA,EACb;AAAA;AAAA;AAAA;AAAA;AAAA,EAwCA,MAAM,eACJ,QACA,OACA,MACkB;AAClB,UAAM,WAAW,4BAAkC,IAAI;AACvD,UAAM,UAAU,SAAS,KAAK;AAE9B,QAAI,OAAO,YAAY,YAAY;AACjC,aAAO,QAAQ,MAAM,SAAS,MAAM,CAAC,QAAQ,IAAI,CAAC;AAAA,IACpD;AAEA,UAAM,IAAI,oBAAoB,0BAA0B,KAAK,EAAE;AAAA,EACjE;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,YAAY,WAAsC,QAAiC;AACvF,UAAM,KAAK,SAAS,QAAQ,GAAG,MAAM;AAAA,EACvC;AAAA;AAAA;AAAA;AAAA,EAKA,MAAM,aAAa,WAAsC,QAAiC;AACxF,UAAM,KAAK,UAAU,QAAQ,GAAG,MAAM;AAAA,EACxC;AAAA,EAEA,iBAAiB,QAAiD;AAChE,QAAI,CAAC,KAAK,iBAAiB;AACzB,YAAM,IAAI,yBAAyB;AAAA,IACrC;AAEA,WAAO,KAAK,gBAAgB,MAAM;AAAA,EACpC;AACF;","names":[]}

package/build/chunk-6PJ4ALJD.js

@@ -0,0 +1,115 @@
+import {
+  ChannelPatternSyntax
+} from "./chunk-E6ILCRL3.js";
+
+// src/bindable_channel_pattern.ts
+var BindableChannelPattern = class _BindableChannelPattern extends ChannelPatternSyntax {
+  constructor(source) {
+    super(source);
+    this.source = source;
+    const bindingSegments = [];
+    const parameters = [];
+    const parameterNames = /* @__PURE__ */ new Set();
+    const serializedSegments = [];
+    let bindable = true;
+    if (this.canonicalPattern !== "/" && (this.segments.length === 0 || this.segments.length !== this.canonicalPattern.split("/").length)) {
+      bindable = false;
+    }
+    for (const [index, segment] of this.segments.entries()) {
+      const final = index === this.segments.length - 1;
+      if (segment.kind === "static") {
+        if (segment.value.length === 0 || /[:*?]/.test(segment.value)) {
+          bindable = false;
+          break;
+        }
+        bindingSegments.push({ kind: "static", value: segment.value });
+        serializedSegments.push(segment.value);
+        continue;
+      }
+      if (segment.kind === "parameter") {
+        const unsupportedParameter = segment.suffix !== "" || !/^[^.:?/*]+$/.test(segment.name) || segment.optional && !final || segment.name === "wildcard" || parameterNames.has(segment.name);
+        if (unsupportedParameter) {
+          bindable = false;
+          break;
+        }
+        parameterNames.add(segment.name);
+        parameters.push({ name: segment.name, optional: segment.optional });
+        bindingSegments.push({
+          kind: "parameter",
+          name: segment.name,
+          optional: segment.optional,
+          wildcard: false
+        });
+        serializedSegments.push(`:${segment.name}${segment.optional ? "?" : ""}`);
+        continue;
+      }
+      if (!final || segment.name !== "*" || parameterNames.has("wildcard")) {
+        bindable = false;
+        break;
+      }
+      parameterNames.add("wildcard");
+      parameters.push({ name: "wildcard", optional: false });
+      bindingSegments.push({
+        kind: "parameter",
+        name: "wildcard",
+        optional: false,
+        wildcard: true
+      });
+      serializedSegments.push(segment.name);
+    }
+    if (this.canonicalPattern !== "/" && serializedSegments.join("/") !== this.canonicalPattern) {
+      bindable = false;
+    }
+    this.#bindable = bindable;
+    this.parameters = Object.freeze(parameters.map((parameter) => Object.freeze(parameter)));
+    this.#bindingSegments = Object.freeze(bindingSegments.map((segment) => Object.freeze(segment)));
+    Object.freeze(this);
+  }
+  parameters;
+  #bindable;
+  #bindingSegments;
+  /**
+   * Parse and validate the pattern subset that generated clients can bind.
+   */
+  static parse(value) {
+    const pattern = new _BindableChannelPattern(value);
+    return pattern.#bindable ? pattern : null;
+  }
+  /**
+   * Bind all required parameters and return one concrete channel name.
+   */
+  bind(parameters = {}) {
+    if (this.canonicalPattern === "/") {
+      return "/";
+    }
+    const values = [];
+    for (const segment of this.#bindingSegments) {
+      if (segment.kind === "static") {
+        values.push(segment.value);
+        continue;
+      }
+      const value = Reflect.get(parameters, segment.name);
+      if (value === void 0 && segment.optional) {
+        continue;
+      }
+      if (value === void 0) {
+        const label = segment.wildcard ? "wildcard parameter" : `"${segment.name}" parameter`;
+        throw new Error(`Missing ${label} for channel: ${this.source}`);
+      }
+      if (typeof value !== "string" && typeof value !== "number") {
+        throw new Error(`Invalid "${segment.name}" parameter for channel: ${this.source}`);
+      }
+      const bound = String(value);
+      if (bound.length === 0 || !segment.wildcard && bound.includes("/")) {
+        throw new Error(`Invalid "${segment.name}" parameter for channel: ${this.source}`);
+      }
+      values.push(bound);
+    }
+    return values.join("/") || "/";
+  }
+};
+
+export {
+  BindableChannelPattern
+};
+//# sourceMappingURL=chunk-6PJ4ALJD.js.map

package/build/chunk-6PJ4ALJD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/bindable_channel_pattern.ts"],"sourcesContent":["import { ChannelPatternSyntax } from './channel_pattern_syntax.js'\n\nexport interface BindableChannelParameter {\n  readonly name: string\n  readonly optional: boolean\n}\n\ntype BindableChannelSegment =\n  | { readonly kind: 'static'; readonly value: string }\n  | {\n      readonly kind: 'parameter'\n      readonly name: string\n      readonly optional: boolean\n      readonly wildcard: boolean\n    }\n\n/**\n * The deliberately small subset of channel patterns that generated clients can bind.\n * Runtime routing keeps using the complete grammar through ChannelPattern.\n */\nexport class BindableChannelPattern extends ChannelPatternSyntax {\n  readonly parameters: readonly BindableChannelParameter[]\n  readonly #bindable: boolean\n  readonly #bindingSegments: readonly BindableChannelSegment[]\n\n  private constructor(private readonly source: string) {\n    super(source)\n\n    const bindingSegments: BindableChannelSegment[] = []\n    const parameters: BindableChannelParameter[] = []\n    const parameterNames = new Set<string>()\n    const serializedSegments: string[] = []\n    let bindable = true\n\n    // Reject syntax that does not map to one complete segment per slash.\n    if (\n      this.canonicalPattern !== '/' &&\n      (this.segments.length === 0 ||\n        this.segments.length !== this.canonicalPattern.split('/').length)\n    ) {\n      bindable = false\n    }\n\n    for (const [index, segment] of this.segments.entries()) {\n      const final = index === this.segments.length - 1\n\n      if (segment.kind === 'static') {\n        if (segment.value.length === 0 || /[:*?]/.test(segment.value)) {\n          bindable = false\n          break\n        }\n        bindingSegments.push({ kind: 'static', value: segment.value })\n        serializedSegments.push(segment.value)\n        continue\n      }\n\n      if (segment.kind === 'parameter') {\n        // Generated parameters do not support suffixes or intermediate optional values.\n        // The wildcard name is reserved for the final wildcard segment.\n        const unsupportedParameter =\n          segment.suffix !== '' ||\n          !/^[^.:?/*]+$/.test(segment.name) ||\n          (segment.optional && !final) ||\n          segment.name === 'wildcard' ||\n          parameterNames.has(segment.name)\n\n        if (unsupportedParameter) {\n          bindable = false\n          break\n        }\n\n        parameterNames.add(segment.name)\n        parameters.push({ name: segment.name, optional: segment.optional })\n        bindingSegments.push({\n          kind: 'parameter',\n          name: segment.name,\n          optional: segment.optional,\n          wildcard: false,\n        })\n        serializedSegments.push(`:${segment.name}${segment.optional ? '?' : ''}`)\n        continue\n      }\n\n      // A generated wildcard must be the final segment and must use the reserved key.\n      if (!final || segment.name !== '*' || parameterNames.has('wildcard')) {\n        bindable = false\n        break\n      }\n\n      parameterNames.add('wildcard')\n      parameters.push({ name: 'wildcard', optional: false })\n      bindingSegments.push({\n        kind: 'parameter',\n        name: 'wildcard',\n        optional: false,\n        wildcard: true,\n      })\n      serializedSegments.push(segment.name)\n    }\n\n    // Reject syntax that the parser cannot reproduce without a change.\n    if (this.canonicalPattern !== '/' && serializedSegments.join('/') !== this.canonicalPattern) {\n      bindable = false\n    }\n\n    this.#bindable = bindable\n    this.parameters = Object.freeze(parameters.map((parameter) => Object.freeze(parameter)))\n    this.#bindingSegments = Object.freeze(bindingSegments.map((segment) => Object.freeze(segment)))\n    Object.freeze(this)\n  }\n\n  /**\n   * Parse and validate the pattern subset that generated clients can bind.\n   */\n  static parse(value: string): BindableChannelPattern | null {\n    const pattern = new BindableChannelPattern(value)\n    return pattern.#bindable ? pattern : null\n  }\n\n  /**\n   * Bind all required parameters and return one concrete channel name.\n   */\n  bind(parameters: object = {}): string {\n    if (this.canonicalPattern === '/') {\n      return '/'\n    }\n\n    const values: string[] = []\n    for (const segment of this.#bindingSegments) {\n      if (segment.kind === 'static') {\n        values.push(segment.value)\n        continue\n      }\n\n      const value = Reflect.get(parameters, segment.name) as unknown\n\n      // Omit only an optional parameter. All other segments need one value.\n      if (value === undefined && segment.optional) {\n        continue\n      }\n      if (value === undefined) {\n        const label = segment.wildcard ? 'wildcard parameter' : `\"${segment.name}\" parameter`\n        throw new Error(`Missing ${label} for channel: ${this.source}`)\n      }\n      if (typeof value !== 'string' && typeof value !== 'number') {\n        throw new Error(`Invalid \"${segment.name}\" parameter for channel: ${this.source}`)\n      }\n\n      const bound = String(value)\n\n      // An ordinary parameter must stay in one segment. A wildcard can contain slashes.\n      if (bound.length === 0 || (!segment.wildcard && bound.includes('/'))) {\n        throw new Error(`Invalid \"${segment.name}\" parameter for channel: ${this.source}`)\n      }\n      values.push(bound)\n    }\n\n    return values.join('/') || '/'\n  }\n}\n"],"mappings":"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","names":[]}