@forklaunch/ws 0.1.0

package/lib/index.js

@@ -0,0 +1,521 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  CLOSED: () => CLOSED,
+  CLOSING: () => CLOSING,
+  CONNECTING: () => CONNECTING,
+  EventEmitter: () => import_events.EventEmitter,
+  ForklaunchWebSocket: () => ForklaunchWebSocket,
+  ForklaunchWebSocketServer: () => ForklaunchWebSocketServer,
+  OPEN: () => OPEN,
+  WebSocket: () => import_ws4.WebSocket,
+  WebSocketServer: () => import_ws4.WebSocketServer,
+  default: () => ForklaunchWebSocket
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/webSocket.ts
+var import_ws = require("@forklaunch/core/ws");
+var import_ws2 = require("ws");
+var ForklaunchWebSocket = class extends import_ws2.WebSocket {
+  eventSchemas;
+  schemas;
+  schemaValidator;
+  /**
+   * Creates a new ForklaunchWebSocket instance with schema validation.
+   *
+   * @param schemaValidator - The schema validator instance (e.g., ZodSchemaValidator)
+   * @param eventSchemas - Schema definitions for all WebSocket events
+   * @param websocketParams - Standard WebSocket constructor parameters (address, protocols, options)
+   *
+   * @example
+   * ```typescript
+   * const ws = new ForklaunchWebSocket(
+   *   validator,
+   *   schemas,
+   *   'ws://localhost:8080',
+   *   ['chat-protocol'],
+   *   { handshakeTimeout: 5000 }
+   * );
+   * ```
+   */
+  constructor(schemaValidator, eventSchemas, ...websocketParams) {
+    super(...websocketParams);
+    this.schemaValidator = schemaValidator;
+    this.eventSchemas = eventSchemas;
+    this.schemas = (0, import_ws.createWebSocketSchemas)(
+      schemaValidator,
+      eventSchemas
+    );
+  }
+  /**
+   * Decodes and validates incoming data from the WebSocket.
+   *
+   * This method handles multiple data formats:
+   * - Buffer → decoded to UTF-8 string → parsed as JSON → validated
+   * - ArrayBuffer → converted to Buffer → decoded → parsed → validated
+   * - TypedArray → converted to Buffer → decoded → parsed → validated
+   * - String → parsed as JSON → validated
+   * - Object → validated directly (already parsed)
+   *
+   * @param data - The raw data received from the WebSocket
+   * @param schema - Optional schema to validate against
+   * @returns The validated and decoded data
+   * @throws {Error} If validation fails with pretty-printed error messages
+   *
+   * @internal
+   */
+  decodeAndValidate(data, schema) {
+    return (0, import_ws.decodeSchemaValue)(
+      this.schemaValidator,
+      data,
+      schema,
+      "web socket event"
+    );
+  }
+  /**
+   * Validates and encodes outgoing data for transmission over the WebSocket.
+   *
+   * This method:
+   * 1. Validates data against the provided schema (if present)
+   * 2. Encodes data to Buffer format:
+   *    - Buffer → returned as-is
+   *    - Object/Array → JSON.stringify → Buffer
+   *    - String → Buffer
+   *    - Number/Boolean → JSON.stringify → Buffer
+   *    - null/undefined → returned as-is
+   *
+   * @param data - The data to validate and encode
+   * @param schema - Optional schema to validate against
+   * @returns The validated and encoded data as Buffer, or null/undefined
+   * @throws {Error} If validation fails with pretty-printed error messages
+   *
+   * @internal
+   */
+  validateAndEncode(data, schema, allowUndefined = false, context = "web socket event") {
+    const encoded = (0, import_ws.encodeSchemaValue)(
+      this.schemaValidator,
+      data,
+      schema,
+      context
+    );
+    return (0, import_ws.normalizeEncodedValue)(encoded, context, allowUndefined);
+  }
+  /**
+   * Transforms incoming event arguments by decoding and validating them.
+   *
+   * Applies transformation for:
+   * - `message` events: validates message data
+   * - `close` events: validates close reason
+   * - `ping` events: validates ping data
+   * - `pong` events: validates pong data
+   *
+   * @param event - The event name
+   * @param args - The raw event arguments
+   * @returns Transformed and validated arguments
+   *
+   * @internal
+   */
+  transformIncomingArgs(event, args) {
+    let transformedArgs = args;
+    if (event === "message" && args.length >= 2) {
+      const data = args[0];
+      const isBinary = args[1];
+      const serverSchema = this.schemas.serverMessagesSchema;
+      if (typeof isBinary === "boolean" && isBinary && serverSchema) {
+        const validated = this.decodeAndValidate(data, serverSchema);
+        transformedArgs = [validated, false, ...args.slice(2)];
+      }
+    } else if (event === "close" && args.length >= 2) {
+      const code = args[0];
+      const reason = args[1];
+      const validated = this.decodeAndValidate(
+        reason,
+        this.schemas.closeReasonSchema
+      );
+      transformedArgs = [code, validated, ...args.slice(2)];
+    } else if (event === "ping" && args.length >= 1) {
+      const data = args[0];
+      const validated = this.decodeAndValidate(data, this.schemas.pingSchema);
+      transformedArgs = [validated, ...args.slice(1)];
+    } else if (event === "pong" && args.length >= 1) {
+      const data = args[0];
+      const validated = this.decodeAndValidate(data, this.schemas.pongSchema);
+      transformedArgs = [validated, ...args.slice(1)];
+    }
+    return transformedArgs;
+  }
+  /**
+   * Wraps an event listener with data transformation logic.
+   *
+   * This helper intercepts listener registration to inject automatic
+   * decoding and validation of incoming event data before passing it
+   * to the user's listener function.
+   *
+   * @param superMethod - The parent class method to call (super.on, super.once, etc.)
+   * @param event - The event name
+   * @param listener - The user's listener function
+   * @returns `this` for method chaining
+   *
+   * @internal
+   */
+  wrapListenerWithTransformation(superMethod, event, listener) {
+    return superMethod(event, (ws, ...args) => {
+      const transformedArgs = this.transformIncomingArgs(event, args);
+      return listener(ws, ...transformedArgs);
+    });
+  }
+  on(event, listener) {
+    return this.wrapListenerWithTransformation(
+      super.on.bind(this),
+      event,
+      listener
+    );
+  }
+  once(event, listener) {
+    return this.wrapListenerWithTransformation(
+      super.once.bind(this),
+      event,
+      listener
+    );
+  }
+  off(event, listener) {
+    return this.wrapListenerWithTransformation(
+      super.off.bind(this),
+      event,
+      listener
+    );
+  }
+  addListener(event, listener) {
+    return this.wrapListenerWithTransformation(
+      super.addListener.bind(this),
+      event,
+      listener
+    );
+  }
+  removeListener(event, listener) {
+    return this.wrapListenerWithTransformation(
+      super.removeListener.bind(this),
+      event,
+      listener
+    );
+  }
+  /**
+   * Emits an event with automatic data validation and encoding.
+   *
+   * All outgoing data is automatically:
+   * - Validated against the provided schemas
+   * - Encoded from JavaScript objects to Buffer format
+   * - Transmitted over the WebSocket connection
+   *
+   * @param event - The event name to emit
+   * @param args - The event arguments (type-checked based on event name)
+   * @returns `true` if the event had listeners, `false` otherwise
+   *
+   * @example Emit a message
+   * ```typescript
+   * // Data is validated against clientMessages schema and auto-encoded
+   * ws.emit('message', { type: 'chat', text: 'Hello!' }, true);
+   * ```
+   *
+   * @example Emit other events
+   * ```typescript
+   * ws.emit('ping', { timestamp: Date.now() });
+   * ws.emit('close', 1000, { reason: 'Normal closure' });
+   * ws.emit('error', { code: 500, message: 'Server error' });
+   * ```
+   */
+  emit(event, ...args) {
+    let transformedArgs = args;
+    if (event === "message" && args.length >= 2) {
+      const typedArgs = args;
+      const data = typedArgs[0];
+      const isBinary = typedArgs[1];
+      const clientSchema = this.schemas.clientMessagesSchema;
+      if (typeof isBinary === "boolean" && isBinary && clientSchema) {
+        const encoded = this.validateAndEncode(
+          data,
+          clientSchema,
+          false,
+          "web socket message"
+        );
+        transformedArgs = [encoded, true, ...typedArgs.slice(2)];
+      }
+    } else if (event === "close" && args.length >= 2) {
+      const typedArgs = args;
+      const code = typedArgs[0];
+      const reason = typedArgs[1];
+      const encoded = this.validateAndEncode(
+        reason,
+        this.schemas.closeReasonSchema,
+        false,
+        "web socket close"
+      );
+      transformedArgs = [code, encoded, ...typedArgs.slice(2)];
+    } else if (event === "ping" && args.length >= 1) {
+      const typedArgs = args;
+      const data = typedArgs[0];
+      const encoded = this.validateAndEncode(
+        data,
+        this.schemas.pingSchema,
+        false,
+        "web socket ping"
+      );
+      transformedArgs = [encoded, ...typedArgs.slice(1)];
+    } else if (event === "pong" && args.length >= 1) {
+      const typedArgs = args;
+      const data = typedArgs[0];
+      const encoded = this.validateAndEncode(
+        data,
+        this.schemas.pongSchema,
+        false,
+        "web socket pong"
+      );
+      transformedArgs = [encoded, ...typedArgs.slice(1)];
+    } else if (event === "error" && args.length >= 1) {
+      const typedArgs = args;
+      const error = typedArgs[0];
+      const errorsSchema = this.schemas.errorsSchema;
+      if (errorsSchema) {
+        const encoded = this.validateAndEncode(
+          error,
+          errorsSchema,
+          false,
+          "web socket error"
+        );
+        transformedArgs = [encoded, ...typedArgs.slice(1)];
+      }
+    }
+    return super.emit(event, ...transformedArgs);
+  }
+  // @ts-expect-error - Implementation accepts unknown for internal validation
+  send(data, optionsOrCb, cb) {
+    const options = typeof optionsOrCb === "function" ? void 0 : optionsOrCb;
+    const callback = typeof optionsOrCb === "function" ? optionsOrCb : cb;
+    const encoded = this.validateAndEncode(
+      data,
+      this.schemas.clientMessagesSchema,
+      false,
+      "web socket message"
+    );
+    if (!encoded) {
+      throw new Error("Invalid data");
+    }
+    return super.send(encoded, options || {}, callback);
+  }
+  /**
+   * Closes the WebSocket connection with optional validated close reason.
+   *
+   * @param code - Optional close code (default: 1000 for normal closure)
+   * @param reason - Optional close reason (validated against closeReason schema)
+   *
+   * @example Close with default code
+   * ```typescript
+   * ws.close();
+   * ```
+   *
+   * @example Close with code and reason
+   * ```typescript
+   * ws.close(1000, { reason: 'User logged out' });
+   * ```
+   *
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code|WebSocket Close Codes}
+   */
+  // @ts-expect-error - Intentionally restricting types for compile-time schema validation
+  close(code, reason) {
+    if (reason) {
+      const encoded = this.validateAndEncode(
+        reason,
+        this.schemas.closeReasonSchema,
+        false,
+        "web socket close"
+      );
+      if (encoded) return super.close(code, encoded);
+    }
+    return super.close(code);
+  }
+  /**
+   * Sends a ping frame with optional validated data payload.
+   *
+   * Ping frames are used to check if the connection is alive. The server
+   * should respond with a pong frame.
+   *
+   * @param data - Optional ping data (validated against ping schema)
+   * @param mask - Whether to mask the frame (default: true for clients)
+   * @param cb - Optional callback invoked when ping is sent or errors
+   *
+   * @example Send a ping
+   * ```typescript
+   * ws.ping({ timestamp: Date.now() });
+   * ```
+   *
+   * @example Send ping with callback
+   * ```typescript
+   * ws.ping({ ts: Date.now() }, true, (error) => {
+   *   if (error) console.error('Ping failed:', error);
+   * });
+   * ```
+   */
+  ping(data, mask, cb) {
+    if (data !== void 0) {
+      const encoded = this.validateAndEncode(
+        data,
+        this.schemas.pingSchema,
+        false,
+        "web socket ping"
+      );
+      super.ping(encoded, mask, cb);
+    } else {
+      super.ping(void 0, mask, cb);
+    }
+  }
+  /**
+   * Sends a pong frame with optional validated data payload.
+   *
+   * Pong frames are typically sent in response to ping frames, but can
+   * also be sent unsolicited as a unidirectional heartbeat.
+   *
+   * @param data - Optional pong data (validated against pong schema)
+   * @param mask - Whether to mask the frame (default: true for clients)
+   * @param cb - Optional callback invoked when pong is sent or errors
+   *
+   * @example Send a pong
+   * ```typescript
+   * ws.pong({ timestamp: Date.now() });
+   * ```
+   *
+   * @example Respond to ping
+   * ```typescript
+   * ws.on('ping', (data) => {
+   *   console.log('Received ping:', data);
+   *   ws.pong(data); // Echo the ping data back
+   * });
+   * ```
+   */
+  pong(data, mask, cb) {
+    if (data !== void 0) {
+      const encoded = this.validateAndEncode(
+        data,
+        this.schemas.pongSchema,
+        false,
+        "web socket pong"
+      );
+      super.pong(encoded, mask, cb);
+    } else {
+      super.pong(void 0, mask, cb);
+    }
+  }
+};
+
+// src/webSocketServer.ts
+var import_ws3 = require("ws");
+var ForklaunchWebSocketServer = class extends import_ws3.WebSocketServer {
+  /**
+   * Creates a new ForklaunchWebSocketServer with schema validation.
+   *
+   * @param _schemaValidator - The schema validator instance (e.g., ZodSchemaValidator)
+   * @param _eventSchemas - Schema definitions for all WebSocket events
+   * @param options - Standard WebSocketServer options (port, host, server, etc.)
+   * @param callback - Optional callback invoked when the server starts listening
+   *
+   * @example Create a server on port 8080
+   * ```typescript
+   * const wss = new ForklaunchWebSocketServer(
+   *   validator,
+   *   schemas,
+   *   { port: 8080 },
+   *   () => console.log('Server started on port 8080')
+   * );
+   * ```
+   *
+   * @example Create a server with existing HTTP server
+   * ```typescript
+   * import { createServer } from 'http';
+   *
+   * const httpServer = createServer();
+   * const wss = new ForklaunchWebSocketServer(
+   *   validator,
+   *   schemas,
+   *   { server: httpServer }
+   * );
+   *
+   * httpServer.listen(8080);
+   * ```
+   *
+   * @example No server mode (for upgrade handling)
+   * ```typescript
+   * const wss = new ForklaunchWebSocketServer(
+   *   validator,
+   *   schemas,
+   *   { noServer: true }
+   * );
+   *
+   * httpServer.on('upgrade', (request, socket, head) => {
+   *   wss.handleUpgrade(request, socket, head, (ws) => {
+   *     wss.emit('connection', ws, request);
+   *   });
+   * });
+   * ```
+   */
+  constructor(_schemaValidator, _eventSchemas, options, callback) {
+    super(options, callback);
+  }
+  on(event, listener) {
+    return super.on(event, listener);
+  }
+  once(event, listener) {
+    return super.once(event, listener);
+  }
+  off(event, listener) {
+    return super.off(event, listener);
+  }
+  addListener(event, listener) {
+    return super.addListener(event, listener);
+  }
+  removeListener(event, listener) {
+    return super.removeListener(
+      event,
+      listener
+    );
+  }
+};
+
+// index.ts
+var import_ws4 = require("ws");
+var import_ws5 = require("ws");
+var import_events = require("events");
+var CLOSED = import_ws5.WebSocket.CLOSED;
+var CLOSING = import_ws5.WebSocket.CLOSING;
+var CONNECTING = import_ws5.WebSocket.CONNECTING;
+var OPEN = import_ws5.WebSocket.OPEN;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  CLOSED,
+  CLOSING,
+  CONNECTING,
+  EventEmitter,
+  ForklaunchWebSocket,
+  ForklaunchWebSocketServer,
+  OPEN,
+  WebSocket,
+  WebSocketServer
+});