alepha 0.20.6 → 0.20.8

package/src/websocket/errors/WebSocketError.ts

@@ -1,34 +0,0 @@
-import { AlephaError } from "alepha";
-
-/**
- * Base WebSocket error class
- */
-export class WebSocketError extends AlephaError {
-  constructor(
-    message: string,
-    public readonly code?: number,
-  ) {
-    super(message);
-    this.name = "WebSocketError";
-  }
-}
-
-/**
- * Error thrown when WebSocket connection fails
- */
-export class WebSocketConnectionError extends WebSocketError {
-  constructor(message: string, code?: number) {
-    super(message, code);
-    this.name = "WebSocketConnectionError";
-  }
-}
-
-/**
- * Error thrown when WebSocket message validation fails
- */
-export class WebSocketValidationError extends WebSocketError {
-  constructor(message: string) {
-    super(message);
-    this.name = "WebSocketValidationError";
-  }
-}

package/src/websocket/index.browser.ts

@@ -1,25 +0,0 @@
-import { $module, type Alepha } from "alepha";
-import { AlephaTopic } from "alepha/topic";
-import { $channel } from "./primitives/$channel.ts";
-import { $websocket } from "./primitives/$websocket.ts";
-import { WebSocketClient } from "./services/WebSocketClient.ts";
-
-/**
- * alepha/websocket (Browser)
- *
- * Browser-side WebSocket client module. Provides WebSocketClient service
- * for managing WebSocket connections from the browser.
- *
- * For React applications, use alepha/react/websocket with the useRoom hook.
- */
-export * from "./index.shared.ts";
-
-export const AlephaWebSocket = $module({
-  name: "alepha.websocket",
-  primitives: [$channel, $websocket],
-  services: [WebSocketClient],
-  register: (alepha: Alepha) => {
-    alepha.with(AlephaTopic);
-    alepha.with(WebSocketClient);
-  },
-});

package/src/websocket/index.shared.ts

@@ -1,8 +0,0 @@
-export * from "./errors/WebSocketError.ts";
-export * from "./interfaces/WebSocketInterfaces.ts";
-export * from "./primitives/$channel.ts";
-export * from "./primitives/$websocket.ts";
-export * from "./providers/WebSocketServerProvider.ts";
-export * from "./services/RoomManager.ts";
-export * from "./services/WebSocketClient.ts";
-export * from "./services/WebSocketTopicService.ts";

package/src/websocket/index.ts

@@ -1,85 +0,0 @@
-import { $module, type Alepha } from "alepha";
-import { AlephaServer } from "alepha/server";
-import { AlephaTopic } from "alepha/topic";
-import { $channel } from "./primitives/$channel.ts";
-import { $websocket } from "./primitives/$websocket.ts";
-import { NodeWebSocketServerProvider } from "./providers/NodeWebSocketServerProvider.ts";
-import { WebSocketServerProvider } from "./providers/WebSocketServerProvider.ts";
-import { RoomManager } from "./services/RoomManager.ts";
-import { WebSocketTopicService } from "./services/WebSocketTopicService.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-declare module "alepha" {
-  interface Hooks {
-    /**
-     * Fires when a WebSocket connection is established
-     */
-    "websocket:connect": {
-      connectionId: string;
-      path: string;
-    };
-
-    /**
-     * Fires when a WebSocket connection is closed
-     */
-    "websocket:disconnect": {
-      connectionId: string;
-      path: string;
-      code?: number;
-      reason?: string;
-    };
-
-    /**
-     * Fires when a WebSocket message is received
-     */
-    "websocket:message": {
-      connectionId: string;
-      path: string;
-      message: any;
-    };
-
-    /**
-     * Fires when a WebSocket error occurs
-     */
-    "websocket:error": {
-      connectionId: string;
-      path: string;
-      error: Error;
-    };
-  }
-}
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export * from "./index.shared.ts";
-export * from "./providers/NodeWebSocketServerProvider.ts";
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-/**
- * Real-time bidirectional communication.
- *
- * **Features:**
- * - WebSocket server definition
- * - Named communication channels
- * - Type-safe message handling
- * - Connection lifecycle management
- * - Room/channel grouping
- * - Browser compatibility
- *
- * @module alepha.websocket
- */
-export const AlephaWebSocket = $module({
-  name: "alepha.websocket",
-  primitives: [$channel, $websocket],
-  services: [WebSocketServerProvider, RoomManager, WebSocketTopicService],
-  variants: [NodeWebSocketServerProvider],
-  imports: [AlephaServer, AlephaTopic],
-  register: (alepha: Alepha) => {
-    alepha.with({
-      provide: WebSocketServerProvider,
-      use: NodeWebSocketServerProvider,
-    });
-  },
-});

package/src/websocket/interfaces/WebSocketInterfaces.ts

@@ -1,252 +0,0 @@
-import type { Static } from "alepha";
-import type { ChannelPrimitive, TWSObject } from "../primitives/$channel.ts";
-
-/**
- * WebSocket connection interface
- */
-export interface WebSocketConnection {
-  /**
-   * Unique connection ID
-   */
-  id: string;
-
-  /**
-   * User ID (if authenticated and security module is used)
-   */
-  userId?: string;
-
-  /**
-   * Channel path this connection belongs to
-   */
-  channelPath: string;
-
-  /**
-   * Room IDs that this connection is currently in
-   */
-  roomIds: string[];
-
-  /**
-   * Send a message to this connection
-   */
-  send(message: any): Promise<void>;
-
-  /**
-   * Close this connection
-   */
-  close(code?: number, reason?: string): Promise<void>;
-
-  /**
-   * Connection metadata (custom data)
-   */
-  metadata?: Record<string, any>;
-
-  /**
-   * Connection state
-   */
-  readyState: WebSocketState;
-}
-
-/**
- * WebSocket state enum
- */
-export enum WebSocketState {
-  CONNECTING = 0,
-  OPEN = 1,
-  CLOSING = 2,
-  CLOSED = 3,
-}
-
-/**
- * WebSocket endpoint configuration (server-side)
- */
-export interface WebSocketPrimitiveOptions<
-  TClient extends TWSObject,
-  TServer extends TWSObject,
-> {
-  /**
-   * Channel definition with schema and path
-   */
-  channel: ChannelPrimitive<TClient, TServer>;
-
-  /**
-   * Handler for incoming messages from clients
-   */
-  handler: WebSocketHandler<TClient, TServer>;
-
-  /**
-   * Optional connection handler (called when a client connects)
-   */
-  onConnect?: (params: {
-    /**
-     * Unique connection ID of the client
-     */
-    connectionId: string;
-
-    /**
-     * User ID of the connected client (if authenticated and security module is used)
-     */
-    userId?: string;
-
-    /**
-     * Room IDs that the client is connecting to
-     */
-    roomIds: string[];
-  }) => Promise<void> | void;
-
-  /**
-   * Optional disconnection handler (called when a client disconnects)
-   */
-  onDisconnect?: (params: {
-    /**
-     * Unique connection ID of the client
-     */
-    connectionId: string;
-
-    /**
-     * User ID of the connected client (if authenticated and security module is used)
-     */
-    userId?: string;
-
-    /**
-     * Room IDs that the client was connected to
-     */
-    roomIds: string[];
-  }) => Promise<void> | void;
-
-  /**
-   * Change WebSocket server provider (for custom implementations)
-   */
-  provider?: any;
-
-  /**
-   * Whether to enforce security (authentication, authorization) on this WebSocket endpoint
-   * Requires alepha/security integration
-   */
-  secure?: boolean;
-
-  /**
-   * Limit number of connections per user (if authenticated)
-   */
-  maxConnectionsPerUser?: number;
-}
-
-/**
- * WebSocket message handler
- */
-export type WebSocketHandler<
-  TClient extends TWSObject,
-  TServer extends TWSObject,
-> = (
-  context: WebSocketHandlerContext<TClient, TServer>,
-) => Promise<void> | void;
-
-/**
- * WebSocket handler context
- */
-export interface WebSocketHandlerContext<
-  TClient extends TWSObject,
-  TServer extends TWSObject,
-> {
-  /**
-   * Unique connection ID of the client
-   */
-  connectionId: string;
-
-  /**
-   * User ID of the connected client (if authenticated and security module is used)
-   */
-  userId?: string;
-
-  /**
-   * Room ID that the client sent the message from
-   */
-  roomId: string;
-
-  /**
-   * The parsed and validated message from the client
-   */
-  message: Static<TServer>;
-
-  /**
-   * Reply function tailored to current context (connectionId, roomId)
-   */
-  reply: (options: {
-    /**
-     * Message to send
-     */
-    message: Static<TClient>;
-
-    /**
-     * Optional: specify room ID to send to (defaults to sender's room ID)
-     */
-    roomId?: string;
-
-    /**
-     * Optional: exclude the sender connection from receiving the message
-     * Will populate exceptConnectionIds with sender connection ID behind the scenes
-     */
-    exceptSelf?: boolean;
-
-    /**
-     * Optional: exclude specific connection IDs from receiving the message
-     */
-    exceptConnectionIds?: string[];
-
-    /**
-     * Optional: exclude specific user IDs from receiving the message
-     * Requires alepha/security integration
-     */
-    exceptUserIds?: string[];
-  }) => Promise<void>;
-}
-
-/**
- * Emit options for sending messages from the server
- */
-export interface EmitOptions<TClient extends TWSObject> {
-  /**
-   * Message to send to clients
-   */
-  message: Static<TClient>;
-
-  /**
-   * Room ID to send the message to
-   */
-  roomId?: string;
-
-  /**
-   * Room IDs to send the message to
-   */
-  roomIds?: string[];
-
-  /**
-   * User ID to send the message to (if authenticated)
-   */
-  userId?: string;
-
-  /**
-   * User IDs to send the message to (if authenticated)
-   */
-  userIds?: string[];
-
-  /**
-   * Connection ID to send the message to
-   */
-  connectionId?: string;
-
-  /**
-   * Connection IDs to send the message to
-   */
-  connectionIds?: string[];
-
-  /**
-   * Optional: exclude specific connection IDs from receiving the message
-   */
-  exceptConnectionIds?: string[];
-
-  /**
-   * Optional: exclude specific user IDs from receiving the message
-   * Requires alepha/security integration
-   */
-  exceptUserIds?: string[];
-}

package/src/websocket/primitives/$channel.ts

@@ -1,131 +0,0 @@
-import {
-  createPrimitive,
-  KIND,
-  Primitive,
-  type TObject,
-  type TString,
-  type TUnion,
-} from "alepha";
-
-export type TWSObject = TObject | TUnion;
-
-/**
- * Channel primitive options
- */
-export interface ChannelPrimitiveOptions<
-  TClient extends TWSObject,
-  TServer extends TWSObject,
-> {
-  /**
-   * WebSocket endpoint path (e.g., "/ws/chat")
-   */
-  path: string;
-
-  /**
-   * Optional description for documentation
-   */
-  description?: string;
-
-  /**
-   * Message schemas for bidirectional communication
-   */
-  schema: {
-    /**
-     * Optional room ID schema validation
-     * Default: t.text() (any string)
-     * Can be enforced at application level: t.uuid(), t.regex(/^[a-f0-9\-]{36}$/)
-     */
-    roomId?: TString;
-
-    /**
-     * Messages from server to client
-     * This is what clients will receive
-     */
-    in: TClient;
-
-    /**
-     * Messages from client to server
-     * This is what the server will receive
-     */
-    out: TServer;
-  };
-}
-
-/**
- * Defines a WebSocket channel with specified client and server message schemas.
- *
- * Channels must be defined as class properties to be registered in the Alepha context.
- * They define the "vocabulary" for communication - the schema for messages flowing
- * in both directions (server→client and client→server).
- *
- * @example Server-side with $websocket
- * ```typescript
- * class ChatController {
- *   // Channel must be defined inside a class
- *   chatChannel = $channel({
- *     path: "/ws/chat",
- *     description: "Real-time chat channel",
- *     schema: {
- *       // Server → Client messages
- *       in: t.union([
- *         t.object({
- *           type: t.const("append"),
- *           content: t.text(),
- *           username: t.text()
- *         }),
- *         t.object({
- *           type: t.const("system"),
- *           message: t.text()
- *         })
- *       ]),
- *       // Client → Server messages
- *       out: t.object({
- *         content: t.text()
- *       })
- *     }
- *   });
- *
- *   chat = $websocket({
- *     channel: this.chatChannel,
- *     handler: async ({ message, reply }) => {
- *       await reply({
- *         message: { type: "append", content: message.content, username: "user" }
- *       });
- *     }
- *   });
- * }
- * ```
- *
- * @example Browser-side with useRoom
- * ```typescript
- * // Define channel in a class for browser context
- * class ChatClient {
- *   chatChannel = $channel({
- *     path: "/ws/chat",
- *     schema: { in: inSchema, out: outSchema }
- *   });
- * }
- *
- * // Use in React component
- * function Chat() {
- *   const client = useInject(ChatClient);
- *   const chat = useRoom({ roomId: "lobby", channel: client.chatChannel, handler: ... }, []);
- * }
- * ```
- */
-export const $channel = <TClient extends TWSObject, TServer extends TWSObject>(
-  options: ChannelPrimitiveOptions<TClient, TServer>,
-): ChannelPrimitive<TClient, TServer> => {
-  return createPrimitive(ChannelPrimitive<TClient, TServer>, options);
-};
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export class ChannelPrimitive<
-  TClient extends TWSObject,
-  TServer extends TWSObject,
-> extends Primitive<ChannelPrimitiveOptions<TClient, TServer>> {
-  // Channels are just schema definitions - no initialization logic needed
-}
-
-$channel[KIND] = ChannelPrimitive;

package/src/websocket/primitives/$websocket.ts

@@ -1,107 +0,0 @@
-import { $inject, createPrimitive, KIND, Primitive } from "alepha";
-import type {
-  EmitOptions,
-  WebSocketPrimitiveOptions,
-} from "../interfaces/WebSocketInterfaces.ts";
-import { WebSocketServerProvider } from "../providers/WebSocketServerProvider.ts";
-import type { TWSObject } from "./$channel.ts";
-
-/**
- * Defines a WebSocket server endpoint for a specific channel.
- *
- * Server-side only. Creates a WebSocket endpoint that:
- * - Accepts connections from clients
- * - Validates incoming messages against the channel schema
- * - Provides room-based messaging
- * - Integrates with alepha/security for authentication (optional)
- * - Supports horizontal scaling via alepha/topic
- *
- * @example
- * ```typescript
- * class ChatController {
- *   chat = $websocket({
- *     channel: chatChannel,
- *     handler: async ({ connectionId, userId, roomId, message, reply }) => {
- *       // Broadcast to all in room except sender
- *       await reply({
- *         message: {
- *           type: "append",
- *           username: userId,
- *           content: message.content
- *         },
- *         exceptSelf: true
- *       });
- *     }
- *   });
- *
- *   async broadcastAnnouncement(roomId: string, text: string) {
- *     await this.chat.emit({
- *       roomId,
- *       message: {
- *         type: "append",
- *         username: "System",
- *         content: text
- *       }
- *     });
- *   }
- * }
- * ```
- */
-export const $websocket = <
-  TClient extends TWSObject,
-  TServer extends TWSObject,
->(
-  options: WebSocketPrimitiveOptions<TClient, TServer>,
-): WebSocketPrimitive<TClient, TServer> => {
-  return createPrimitive(WebSocketPrimitive<TClient, TServer>, options);
-};
-
-// ---------------------------------------------------------------------------------------------------------------------
-
-export class WebSocketPrimitive<
-  TClient extends TWSObject,
-  TServer extends TWSObject,
-> extends Primitive<WebSocketPrimitiveOptions<TClient, TServer>> {
-  protected readonly webSocketServerProvider = $inject(WebSocketServerProvider);
-
-  protected onInit() {
-    this.webSocketServerProvider.registerEndpoint(this.options);
-  }
-
-  /**
-   * Emit message to clients
-   *
-   * Send messages from the server to connected clients based on targeting criteria.
-   * Messages are distributed across all server instances via pub/sub.
-   *
-   * @example
-   * ```typescript
-   * // Send to specific room
-   * await websocket.emit({
-   *   roomId: "room-123",
-   *   message: { type: "update", data: {...} }
-   * });
-   *
-   * // Send to specific user (all their connections)
-   * await websocket.emit({
-   *   userId: "user-456",
-   *   message: { type: "notification", text: "Hello!" }
-   * });
-   *
-   * // Send to multiple rooms, except certain users
-   * await websocket.emit({
-   *   roomIds: ["room-1", "room-2"],
-   *   exceptUserIds: ["user-123"],
-   *   message: { type: "broadcast", content: "System announcement" }
-   * });
-   * ```
-   */
-  public async emit(options: EmitOptions<TClient>): Promise<void> {
-    await this.webSocketServerProvider.emit(
-      this.options.channel.options.path,
-      options,
-    );
-  }
-}
-
-$websocket[KIND] = WebSocketPrimitive;