@forklaunch/ws 0.1.0

package/lib/index.mjs

@@ -0,0 +1,491 @@
+// src/webSocket.ts
+import {
+  createWebSocketSchemas,
+  decodeSchemaValue,
+  encodeSchemaValue,
+  normalizeEncodedValue
+} from "@forklaunch/core/ws";
+import { WebSocket } from "ws";
+var ForklaunchWebSocket = class extends 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 = 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 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 = encodeSchemaValue(
+      this.schemaValidator,
+      data,
+      schema,
+      context
+    );
+    return 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
+import { WebSocketServer } from "ws";
+var ForklaunchWebSocketServer = class extends 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
+import { WebSocket as WebSocket2, WebSocketServer as WebSocketServer2 } from "ws";
+import { WebSocket as WebSocket3 } from "ws";
+import { EventEmitter } from "events";
+var CLOSED = WebSocket3.CLOSED;
+var CLOSING = WebSocket3.CLOSING;
+var CONNECTING = WebSocket3.CONNECTING;
+var OPEN = WebSocket3.OPEN;
+export {
+  CLOSED,
+  CLOSING,
+  CONNECTING,
+  EventEmitter,
+  ForklaunchWebSocket,
+  ForklaunchWebSocketServer,
+  OPEN,
+  WebSocket2 as WebSocket,
+  WebSocketServer2 as WebSocketServer,
+  ForklaunchWebSocket as default
+};

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@forklaunch/ws",
+  "version": "0.1.0",
+  "description": "Typed framework for ws, by ForkLaunch.",
+  "homepage": "https://github.com/forklaunch/forklaunch-js#readme",
+  "bugs": {
+    "url": "https://github.com/forklaunch/forklaunch-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forklaunch/forklaunch-js.git"
+  },
+  "license": "MIT",
+  "author": "Rohin Bhargava",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.mjs",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    }
+  },
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib/**"
+  ],
+  "dependencies": {
+    "@asyncapi/parser": "^3.4.0",
+    "@forklaunch/fastmcp-fork": "^1.0.5",
+    "@types/ws": "^8.18.1",
+    "ws": "^8.18.3",
+    "@forklaunch/common": "0.6.22",
+    "@forklaunch/core": "0.16.0",
+    "@forklaunch/validator": "0.10.22"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.38.0",
+    "@typescript/native-preview": "7.0.0-dev.20251027.1",
+    "jest": "^30.2.0",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.4.5",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.0",
+    "typedoc": "^0.28.14",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.46.2",
+    "zod": "^4.1.12"
+  },
+  "scripts": {
+    "build": "tsgo --noEmit && tsup index.ts --format cjs,esm --no-splitting --tsconfig tsconfig.json --outDir lib --dts --clean",
+    "clean": "rm -rf lib pnpm.lock.yaml node_modules",
+    "docs": "typedoc --out docs *",
+    "format": "prettier --ignore-path=.prettierignore --config .prettierrc '**/*.{ts,tsx,json}' --write",
+    "lint": "eslint . -c eslint.config.mjs",
+    "lint:fix": "eslint . -c eslint.config.mjs --fix",
+    "publish:package": "./publish-package.bash",
+    "test": "vitest --passWithNoTests"
+  }
+}