@zimic/ws 0.1.0-canary.0

package/package.json

@@ -0,0 +1,114 @@
+{
+  "name": "@zimic/ws",
+  "description": "Next-gen TypeScript-first WebSocket client and server",
+  "keywords": [
+    "zimic",
+    "typescript",
+    "types",
+    "typegen",
+    "realtime",
+    "validation",
+    "inference",
+    "websocket",
+    "ws",
+    "api",
+    "static"
+  ],
+  "version": "0.1.0-canary.0",
+  "homepage": "https://zimic.dev/docs/ws",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zimicjs/zimic.git",
+    "directory": "packages/zimic-ws"
+  },
+  "author": {
+    "name": "Diego Aquino",
+    "url": "https://github.com/diego-aquino"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/zimicjs"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "files": [
+    "package.json",
+    "README.md",
+    "LICENSE.md",
+    "src",
+    "!src/**/tests",
+    "!src/**/__tests__",
+    "!src/**/*.test.ts",
+    "dist",
+    "index.d.ts",
+    "server.d.ts"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./server": {
+      "types": "./server.d.ts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.js",
+      "default": "./dist/server.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "lint": "eslint --cache --no-error-on-unmatched-pattern --no-warn-ignored --fix",
+    "lint:turbo": "pnpm lint . --max-warnings 0",
+    "style": "prettier --log-level warn --ignore-unknown --no-error-on-unmatched-pattern --cache",
+    "style:check": "pnpm style --check",
+    "style:format": "pnpm style --write",
+    "test": "dotenv -v NODE_ENV=test -v FORCE_COLOR=1 -- vitest",
+    "test:turbo": "dotenv -v CI=true -- pnpm run test run --coverage",
+    "types:check": "tsc --noEmit",
+    "deps:setup-playwright": "playwright install chromium",
+    "deps:setup": "pnpm deps:setup-playwright"
+  },
+  "dependencies": {
+    "ws": "8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.0",
+    "@types/ws": "^8.18.1",
+    "@vitest/browser": "^4.0.6",
+    "@vitest/browser-playwright": "^4.0.6",
+    "@vitest/coverage-istanbul": "^4.0.6",
+    "@zimic/eslint-config-node": "workspace:*",
+    "@zimic/interceptor": "workspace:*",
+    "@zimic/lint-staged-config": "workspace:*",
+    "@zimic/tsconfig": "workspace:*",
+    "@zimic/utils": "workspace:*",
+    "dotenv-cli": "^11.0.0",
+    "eslint": "^9.39.1",
+    "playwright": "^1.56.1",
+    "tsup": "^8.4.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.6"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
+  }
+}

package/server.d.ts

@@ -0,0 +1 @@
+export * from './dist/server';

package/src/client/ClientSocket.ts

@@ -0,0 +1,7 @@
+import NodeWebSocket from 'ws';
+
+// WebSocket is available natively in browsers and Node.js >=22.
+const isNativeWebSocketAvailable = typeof WebSocket !== 'undefined';
+
+export const ClientSocket = (isNativeWebSocketAvailable ? WebSocket : NodeWebSocket) as typeof WebSocket;
+export type ClientSocket = InstanceType<typeof ClientSocket>;

package/src/client/WebSocketClient.ts

@@ -0,0 +1,228 @@
+import { WebSocketEvent, WebSocketEventType, WebSocketMessageData, WebSocketSchema } from '@/types/schema';
+
+import { ClientSocket } from './ClientSocket';
+import { closeClientSocket, openClientSocket } from './utils/lifecycle';
+
+export type WebSocketClientEventListener<Schema extends WebSocketSchema, Type extends WebSocketEventType<Schema>> = (
+  this: WebSocketClient<Schema>,
+  event: WebSocketEvent<Schema, Type>,
+) => unknown;
+
+type WebSocketClientRawEventListener = (this: ClientSocket, event: Event) => unknown;
+
+class WebSocketClient<Schema extends WebSocketSchema> implements Omit<
+  WebSocket,
+  `${string}EventListener` | `on${string}`
+> {
+  private socket?: ClientSocket;
+  private _binaryType: BinaryType = 'blob';
+
+  private _onopen: WebSocketClientEventListener<Schema, 'open'> | null = null;
+  private _onmessage: WebSocketClientEventListener<Schema, 'message'> | null = null;
+  private _onclose: WebSocketClientEventListener<Schema, 'close'> | null = null;
+  private _onerror: WebSocketClientEventListener<Schema, 'error'> | null = null;
+
+  private listeners: {
+    [Type in WebSocketEventType<Schema>]: Map<
+      WebSocketClientEventListener<Schema, Type>,
+      WebSocketClientRawEventListener
+    >;
+  } = {
+    open: new Map(),
+    message: new Map(),
+    close: new Map(),
+    error: new Map(),
+  };
+
+  constructor(
+    private _url: string,
+    private protocols?: string | string[],
+  ) {}
+
+  static CONNECTING = ClientSocket.CONNECTING;
+
+  get CONNECTING() {
+    return WebSocketClient.CONNECTING;
+  }
+
+  static OPEN = ClientSocket.OPEN;
+
+  get OPEN() {
+    return WebSocketClient.OPEN;
+  }
+
+  static CLOSING = ClientSocket.CLOSING;
+
+  get CLOSING() {
+    return WebSocketClient.CLOSING;
+  }
+
+  static CLOSED = ClientSocket.CLOSED;
+
+  get CLOSED() {
+    return WebSocketClient.CLOSED;
+  }
+
+  get binaryType() {
+    return this.socket?.binaryType ?? this._binaryType;
+  }
+
+  set binaryType(value: 'blob' | 'arraybuffer') {
+    this._binaryType = value;
+
+    if (this.socket) {
+      this.socket.binaryType = value;
+    }
+  }
+
+  get url() {
+    return this.socket?.url ?? this._url;
+  }
+
+  get protocol() {
+    return this.socket?.protocol ?? '';
+  }
+
+  get extensions() {
+    return this.socket?.extensions ?? '';
+  }
+
+  get readyState() {
+    return this.socket?.readyState ?? ClientSocket.CLOSED;
+  }
+
+  get bufferedAmount() {
+    return this.socket?.bufferedAmount ?? 0;
+  }
+
+  async open(options: { timeout?: number } = {}) {
+    this.socket = new ClientSocket(this._url, this.protocols);
+
+    if (this.socket.binaryType !== this._binaryType) {
+      this.socket.binaryType = this._binaryType;
+    }
+
+    await openClientSocket(this.socket, options);
+  }
+
+  async close(code?: number, reason?: string, options: { timeout?: number } = {}) {
+    if (!this.socket) {
+      return;
+    }
+
+    try {
+      await closeClientSocket(this.socket, { ...options, code, reason });
+    } finally {
+      this.onopen = null;
+      this.onmessage = null;
+      this.onclose = null;
+      this.onerror = null;
+
+      for (const [type, listenerToRawListener] of Object.entries(this.listeners)) {
+        for (const rawListener of listenerToRawListener.values()) {
+          this.socket.removeEventListener(type, rawListener);
+        }
+
+        listenerToRawListener.clear();
+      }
+
+      this.socket = undefined;
+    }
+  }
+
+  send(data: WebSocketMessageData<Schema>) {
+    this.socket?.send(data);
+  }
+
+  addEventListener<Type extends WebSocketEventType<Schema>>(
+    type: Type,
+    listener: (this: WebSocketClient<Schema>, event: WebSocketEvent<Schema, Type>) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ) {
+    const rawListener = listener.bind(this) as WebSocketClientRawEventListener;
+
+    this.socket?.addEventListener(type, rawListener, options);
+    this.listeners[type].set(listener, rawListener);
+  }
+
+  removeEventListener<Type extends WebSocketEventType<Schema>>(
+    type: Type,
+    listener: (this: WebSocketClient<Schema>, event: WebSocketEvent<Schema, Type>) => unknown,
+    options?: boolean | EventListenerOptions,
+  ) {
+    const rawListener = this.listeners[type].get(listener);
+
+    if (rawListener) {
+      this.socket?.removeEventListener(type, rawListener, options);
+      this.listeners[type].delete(listener);
+    }
+  }
+
+  get onopen() {
+    return this._onopen;
+  }
+
+  set onopen(listener: WebSocketClientEventListener<Schema, 'open'> | null) {
+    this.setUnitaryEventListener('open', listener);
+  }
+
+  get onmessage() {
+    return this._onmessage;
+  }
+
+  set onmessage(listener: WebSocketClientEventListener<Schema, 'message'> | null) {
+    this.setUnitaryEventListener('message', listener);
+  }
+
+  get onclose() {
+    return this._onclose;
+  }
+
+  set onclose(listener: WebSocketClientEventListener<Schema, 'close'> | null) {
+    this.setUnitaryEventListener('close', listener);
+  }
+
+  get onerror() {
+    return this._onerror;
+  }
+
+  set onerror(listener: WebSocketClientEventListener<Schema, 'error'> | null) {
+    this.setUnitaryEventListener('error', listener);
+  }
+
+  private setUnitaryEventListener<Type extends WebSocketEventType<Schema>>(
+    type: Type,
+    listener: WebSocketClientEventListener<Schema, Type> | null,
+  ) {
+    type PrivateUnitaryListener = typeof listener;
+
+    if (listener) {
+      const rawListener = listener.bind(this) as WebSocketClientRawEventListener;
+      this.listeners[type].set(listener, rawListener);
+
+      if (this.socket) {
+        this.socket[`on${type}`] = rawListener;
+      }
+
+      (this[`_on${type}`] as PrivateUnitaryListener) = listener;
+    } else {
+      const currentListener = this[`_on${type}`] as PrivateUnitaryListener;
+
+      if (currentListener) {
+        this.listeners[type].delete(currentListener);
+      }
+
+      if (this.socket) {
+        this.socket[`on${type}`] = null;
+      }
+
+      (this[`_on${type}`] as PrivateUnitaryListener) = null;
+    }
+  }
+
+  dispatchEvent<Type extends WebSocketEventType<Schema>>(event: WebSocketEvent<Schema, Type>) {
+    return this.socket?.dispatchEvent(event) ?? false;
+  }
+}
+
+export default WebSocketClient;

package/src/client/utils/lifecycle.ts

@@ -0,0 +1,89 @@
+import { WebSocketCloseTimeoutError } from '@/errors/WebSocketCloseTimeoutError';
+import { WebSocketOpenTimeoutError } from '@/errors/WebSocketOpenTimeoutError';
+
+import { ClientSocket } from '../ClientSocket';
+
+export async function openClientSocket(socket: ClientSocket, options: { timeout?: number } = {}) {
+  const { timeout: timeoutDuration } = options;
+
+  const isAlreadyOpen = socket.readyState === socket.OPEN;
+
+  if (isAlreadyOpen) {
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    function removeAllSocketListeners() {
+      socket.removeEventListener('open', handleOpenSuccess); // eslint-disable-line @typescript-eslint/no-use-before-define
+      socket.removeEventListener('error', handleError); // eslint-disable-line @typescript-eslint/no-use-before-define
+      socket.removeEventListener('close', handleError); // eslint-disable-line @typescript-eslint/no-use-before-define
+    }
+
+    function handleError(error: unknown) {
+      removeAllSocketListeners();
+      reject(error);
+    }
+
+    const openTimeout =
+      timeoutDuration === undefined
+        ? undefined
+        : setTimeout(() => {
+            const timeoutError = new WebSocketOpenTimeoutError(timeoutDuration);
+            handleError(timeoutError);
+          }, timeoutDuration);
+
+    function handleOpenSuccess() {
+      removeAllSocketListeners();
+      clearTimeout(openTimeout);
+      resolve();
+    }
+
+    socket.addEventListener('open', handleOpenSuccess);
+    socket.addEventListener('error', handleError);
+    socket.addEventListener('close', handleError);
+  });
+}
+
+export async function closeClientSocket(
+  socket: ClientSocket,
+  options: { code?: number; reason?: string; timeout?: number } = {},
+) {
+  const { timeout: timeoutDuration } = options;
+
+  const isAlreadyClosed = socket.readyState === socket.CLOSED;
+
+  if (isAlreadyClosed) {
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    function removeAllSocketListeners() {
+      socket.removeEventListener('error', handleError); // eslint-disable-line @typescript-eslint/no-use-before-define
+      socket.removeEventListener('close', handleClose); // eslint-disable-line @typescript-eslint/no-use-before-define
+    }
+
+    function handleError(error: unknown) {
+      removeAllSocketListeners();
+      reject(error);
+    }
+
+    const closeTimeout =
+      timeoutDuration === undefined
+        ? undefined
+        : setTimeout(() => {
+            const timeoutError = new WebSocketCloseTimeoutError(timeoutDuration);
+            handleError(timeoutError);
+          }, timeoutDuration);
+
+    function handleClose() {
+      removeAllSocketListeners();
+      clearTimeout(closeTimeout);
+      resolve();
+    }
+
+    socket.addEventListener('error', handleError);
+    socket.addEventListener('close', handleClose);
+
+    socket.close(options.code, options.reason);
+  });
+}

package/src/errors/WebSocketCloseTimeoutError.ts

@@ -0,0 +1,8 @@
+import { WebSocketTimeoutError } from './WebSocketTimeoutError';
+
+export class WebSocketCloseTimeoutError extends WebSocketTimeoutError {
+  constructor(reachedTimeout: number) {
+    super(`Web socket close timed out after ${reachedTimeout}ms.`);
+    this.name = 'WebSocketCloseTimeoutError';
+  }
+}

package/src/errors/WebSocketMessageAbortError.ts

@@ -0,0 +1,8 @@
+import { WebSocketTimeoutError } from './WebSocketTimeoutError';
+
+export class WebSocketMessageAbortError extends WebSocketTimeoutError {
+  constructor() {
+    super('Web socket message was aborted.');
+    this.name = 'WebSocketMessageAbortError';
+  }
+}

package/src/errors/WebSocketOpenTimeoutError.ts

@@ -0,0 +1,8 @@
+import { WebSocketTimeoutError } from './WebSocketTimeoutError';
+
+export class WebSocketOpenTimeoutError extends WebSocketTimeoutError {
+  constructor(reachedTimeout: number) {
+    super(`Web socket open timed out after ${reachedTimeout}ms.`);
+    this.name = 'WebSocketOpenTimeoutError';
+  }
+}

package/src/errors/WebSocketTimeoutError.ts

@@ -0,0 +1,6 @@
+export class WebSocketTimeoutError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'WebSocketTimeoutError';
+  }
+}

package/src/index.ts

@@ -0,0 +1,6 @@
+export { WebSocketCloseTimeoutError } from './errors/WebSocketCloseTimeoutError';
+export { WebSocketMessageAbortError } from './errors/WebSocketMessageAbortError';
+export { WebSocketOpenTimeoutError } from './errors/WebSocketOpenTimeoutError';
+export { WebSocketTimeoutError } from './errors/WebSocketTimeoutError';
+
+export { default as WebSocketClient } from './client/WebSocketClient';

package/src/server/ServerSocket.ts

@@ -0,0 +1 @@
+export { WebSocketServer as ServerSocket } from 'ws';

package/src/server/WebSocketServer.ts

@@ -0,0 +1,45 @@
+import { Server as HttpServer } from 'http';
+import { Server as HttpsServer } from 'https';
+
+import { ServerSocket } from './ServerSocket';
+import { closeServerSocket, openServerSocket } from './utils/lifecycle';
+
+export interface WebSocketServerOptions {
+  server: HttpServer | HttpsServer;
+}
+
+class WebSocketServer {
+  private server: HttpServer | HttpsServer;
+  private socket: ServerSocket;
+  private isSocketOpen: boolean;
+
+  constructor(options: WebSocketServerOptions) {
+    this.server = options.server;
+    this.socket = new ServerSocket({ server: options.server });
+    this.isSocketOpen = options.server.listening;
+  }
+
+  get isRunning() {
+    return this.server.listening && this.isSocketOpen;
+  }
+
+  async start(options: { timeout?: number } = {}) {
+    if (this.isSocketOpen) {
+      return;
+    }
+
+    await openServerSocket(this.server, this.socket, options);
+    this.isSocketOpen = true;
+  }
+
+  async stop(options: { timeout?: number } = {}) {
+    if (!this.isSocketOpen) {
+      return;
+    }
+
+    await closeServerSocket(this.server, this.socket, options);
+    this.isSocketOpen = false;
+  }
+}
+
+export default WebSocketServer;

package/src/server/index.ts

@@ -0,0 +1,2 @@
+export { default as WebSocketServer } from './WebSocketServer';
+export type { WebSocketServerOptions } from './WebSocketServer';

package/src/server/utils/lifecycle.ts

@@ -0,0 +1,81 @@
+import { Server as HttpServer } from 'http';
+import { Server as HttpsServer } from 'https';
+
+import { WebSocketCloseTimeoutError } from '@/errors/WebSocketCloseTimeoutError';
+import { WebSocketOpenTimeoutError } from '@/errors/WebSocketOpenTimeoutError';
+
+import { ServerSocket } from '../ServerSocket';
+
+export async function openServerSocket(
+  server: HttpServer | HttpsServer,
+  socket: ServerSocket,
+  options: { timeout?: number } = {},
+) {
+  const { timeout: timeoutDuration } = options;
+
+  const isAlreadyOpen = server.listening;
+
+  if (isAlreadyOpen) {
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const openTimeout =
+      timeoutDuration === undefined
+        ? undefined
+        : setTimeout(() => {
+            const timeoutError = new WebSocketOpenTimeoutError(timeoutDuration);
+            reject(timeoutError);
+          }, timeoutDuration);
+
+    socket.once('listening', () => {
+      clearTimeout(openTimeout);
+      resolve();
+    });
+
+    socket.once('error', (error) => {
+      clearTimeout(openTimeout);
+      reject(error);
+    });
+  });
+}
+
+export async function closeServerSocket(
+  server: HttpServer | HttpsServer,
+  socket: ServerSocket,
+  options: { timeout?: number } = {},
+) {
+  const { timeout: timeoutDuration } = options;
+
+  const isAlreadyClosed = !server.listening;
+
+  if (isAlreadyClosed) {
+    return;
+  }
+
+  await new Promise<void>((resolve, reject) => {
+    const closeTimeout =
+      timeoutDuration === undefined
+        ? undefined
+        : setTimeout(() => {
+            const timeoutError = new WebSocketCloseTimeoutError(timeoutDuration);
+            reject(timeoutError);
+          }, timeoutDuration);
+
+    for (const client of socket.clients) {
+      client.close();
+    }
+
+    socket.close((error) => {
+      clearTimeout(closeTimeout);
+
+      /* istanbul ignore if -- @preserve
+       * This is not expected since the server is not stopped unless it is running. */
+      if (error) {
+        reject(error);
+      } else {
+        resolve();
+      }
+    });
+  });
+}

package/src/types/json.ts

@@ -0,0 +1,8 @@
+import { JSONStringified as InternalJSONStringified } from '@zimic/utils/types/json';
+
+/**
+ * Represents a value stringified by `JSON.stringify`, maintaining a type reference to the original type.
+ *
+ * This type is used to validate that the expected stringified body is passed in WebSocket messages.
+ */
+export type JSONStringified<Value> = InternalJSONStringified<Value>;

package/src/types/schema.ts

@@ -0,0 +1,35 @@
+import { Branded } from '@zimic/utils/types';
+import { JSONValue } from '@zimic/utils/types/json';
+
+import { JSONStringified } from './json';
+
+type BaseWebSocketSchema = JSONValue | string | Blob | ArrayBufferLike | ArrayBufferView;
+
+export type WebSocketSchema<Schema extends BaseWebSocketSchema = BaseWebSocketSchema> = Branded<
+  Schema,
+  'WebSocketSchema'
+>;
+
+export type WebSocketMessageData<Schema extends WebSocketSchema> = Schema extends Blob
+  ? Schema
+  : Schema extends ArrayBufferLike
+    ? Schema
+    : Schema extends ArrayBufferView
+      ? Schema
+      : Schema extends string
+        ? Schema
+        : JSONStringified<Schema>;
+
+export interface WebSocketEventMap<Schema extends WebSocketSchema> {
+  open: Event;
+  message: MessageEvent<WebSocketMessageData<Schema>>;
+  close: CloseEvent;
+  error: Event;
+}
+
+export type WebSocketEventType<Schema extends WebSocketSchema = WebSocketSchema> = keyof WebSocketEventMap<Schema>;
+
+export type WebSocketEvent<
+  Schema extends WebSocketSchema = WebSocketSchema,
+  Type extends WebSocketEventType = WebSocketEventType,
+> = WebSocketEventMap<Schema>[Type];