@hedystia/ws 2.3.1

package/dist/types.d.mts

@@ -0,0 +1,208 @@
+//#region src/types.d.ts
+/**
+ * Payload accepted by every `send`/`publish` method.
+ *
+ * @remarks
+ * Matches the WHATWG `WebSocket.send` signature plus the `Uint8Array`
+ * convenience accepted by Bun and the `ws` package.
+ */
+type WSMessage = string | ArrayBuffer | Uint8Array;
+/**
+ * Bag of arbitrary, user-supplied state attached to a connection on
+ * upgrade and exposed to handlers as `ws.data`.
+ *
+ * @typeParam K - String key
+ * @typeParam V - Stored value
+ */
+type WSData = Record<string, any>;
+/**
+ * The per-connection wrapper passed to every handler.
+ *
+ * @remarks
+ * The interface intentionally mirrors `Bun.ServerWebSocket` so that the
+ * same handler code works on Bun (native) and on Node.js (via
+ * {@link WebSocketServer}). Topic-based pub/sub is implemented in
+ * user-space when running outside Bun.
+ *
+ * @typeParam Data - Shape of the user-attached `data` field
+ *
+ * @example
+ * ```ts
+ * const handlers: WebSocketHandlers<{ user: string }> = {
+ *   open: (ws) => ws.subscribe(`user:${ws.data.user}`),
+ *   message: (ws, msg) => ws.publish(`user:${ws.data.user}`, msg),
+ * };
+ * ```
+ */
+interface ServerWebSocket<Data extends WSData = WSData> {
+  /** User-supplied state attached to the socket on upgrade. */
+  readonly data: Data;
+  /** Standard WHATWG ready-state (`0` connecting, `1` open, `2` closing, `3` closed). */
+  readonly readyState: number;
+  /** Remote IP, taken from `X-Forwarded-For` when present. */
+  readonly remoteAddress: string;
+  /**
+   * Send a message to this socket only.
+   *
+   * @param message - Payload to send
+   * @param compress - Whether to compress (honoured on Bun, ignored on Node)
+   * @returns Number of bytes written (best-effort on Node)
+   */
+  send(message: WSMessage, compress?: boolean): number;
+  /**
+   * Close the connection.
+   *
+   * @param code - Close code (defaults to 1000)
+   * @param reason - Optional human-readable reason
+   */
+  close(code?: number, reason?: string): void;
+  /**
+   * Subscribe this socket to a topic so it receives subsequent
+   * {@link ServerWebSocket.publish | publish} or
+   * {@link WebSocketServer.publish | server.publish} broadcasts.
+   *
+   * @param topic - Topic name
+   */
+  subscribe(topic: string): void;
+  /**
+   * Unsubscribe this socket from a previously joined topic.
+   *
+   * @param topic - Topic name
+   */
+  unsubscribe(topic: string): void;
+  /**
+   * Broadcast a message to every other socket subscribed to `topic`.
+   *
+   * @remarks
+   * The sender is excluded by default — matching Bun's default behaviour.
+   *
+   * @param topic - Topic name
+   * @param message - Payload to broadcast
+   * @param compress - Whether to compress (honoured on Bun, ignored on Node)
+   */
+  publish(topic: string, message: WSMessage, compress?: boolean): void;
+  /**
+   * Check whether this socket is currently subscribed to `topic`.
+   *
+   * @param topic - Topic name
+   * @returns `true` when subscribed
+   */
+  isSubscribed(topic: string): boolean;
+  /**
+   * Batch multiple writes inside `cb`.
+   *
+   * @remarks
+   * On Bun this corresponds to `corked()`; on Node it is a no-op alias
+   * that simply invokes `cb(this)` synchronously.
+   *
+   * @param cb - Function invoked with the same socket
+   */
+  cork(cb: (ws: ServerWebSocket<Data>) => void): void;
+}
+/**
+ * Bun-style compression dictionary identifier.
+ *
+ * @remarks
+ * Used by Bun's `perMessageDeflate` configuration. The `@hedystia/ws`
+ * server forwards the value to the underlying implementation, which only
+ * Bun interprets natively; Node falls back to defaults when the value is
+ * not a recognised `ws` shape.
+ */
+type Compressor = "disable" | "shared" | "dedicated" | "3KB" | "4KB" | "8KB" | "16KB" | "32KB" | "64KB" | "128KB" | "256KB";
+/**
+ * Per-message deflate configuration.
+ *
+ * @remarks
+ * Accepts either a boolean (`true` enables defaults, `false` disables it)
+ * or a free-form object whose shape is forwarded verbatim to the underlying
+ * implementation. Bun's {@link Compressor} strings (`"3KB"`, `"shared"`, …)
+ * and the [`ws`](https://github.com/websockets/ws) package's
+ * `PerMessageDeflateOptions` (`zlibDeflateOptions`, `threshold`, …) are
+ * both supported by simply matching whatever the runtime expects.
+ */
+type PerMessageDeflate = boolean | (Record<string, any> & {
+  compress?: boolean | Compressor;
+  decompress?: boolean | Compressor;
+});
+/**
+ * Construction options for {@link WebSocketServer}.
+ */
+interface WebSocketServerOptions {
+  /** Maximum allowed payload in bytes. Defaults to the underlying library's default. */
+  maxPayload?: number;
+  /** Per-message deflate configuration. */
+  perMessageDeflate?: PerMessageDeflate;
+}
+/**
+ * Lifecycle handlers passed to {@link WebSocketServer}.
+ *
+ * @typeParam Data - Shape of the user-attached `data` field
+ */
+interface WebSocketHandlers<Data extends WSData = WSData> {
+  /** Called for every inbound message. */
+  message: (ws: ServerWebSocket<Data>, message: WSMessage) => void | Promise<void>;
+  /** Called once the handshake completes successfully. */
+  open?: (ws: ServerWebSocket<Data>) => void | Promise<void>;
+  /** Called after the connection closes (clean or otherwise). */
+  close?: (ws: ServerWebSocket<Data>, code: number, reason: string) => void | Promise<void>;
+  /** Called when the underlying transport raises an error. */
+  error?: (ws: ServerWebSocket<Data>, error: Error) => void | Promise<void>;
+  /**
+   * Called when back-pressure is relieved.
+   *
+   * @remarks
+   * Only fired by Bun; Node-backed servers never invoke it.
+   */
+  drain?: (ws: ServerWebSocket<Data>) => void | Promise<void>;
+}
+/**
+ * Options accepted by {@link createWebSocket}.
+ */
+interface ClientWebSocketOptions {
+  /** Sub-protocols negotiated during the handshake. */
+  protocols?: string | string[];
+  /**
+   * Custom request headers.
+   *
+   * @remarks
+   * Honoured on Node via the `ws` package; runtimes that ship a WHATWG
+   * `WebSocket` (Bun, Deno, browsers, Node ≥ 22) ignore them — matching
+   * standard WebSocket semantics.
+   */
+  headers?: Record<string, string>;
+}
+/**
+ * Raw upgrade tuple consumed by {@link WebSocketServer.upgrade}.
+ *
+ * @remarks
+ * Mirrors what `node:http`'s `'upgrade'` event emits and what the `ws`
+ * package's `WebSocketServer.handleUpgrade` consumes.
+ */
+interface UpgradeRequest {
+  /** Raw `IncomingMessage`-like object exposing `headers`, `method`, `url`. */
+  rawRequest: any;
+  /** Raw duplex socket (e.g. `node:net.Socket`). */
+  socket: any;
+  /** Initial buffer captured by the HTTP parser. */
+  head: Buffer | Uint8Array;
+}
+/**
+ * Options forwarded to {@link WebSocketServer.upgrade}.
+ *
+ * @typeParam Data - Shape of the user-attached `data` field
+ */
+interface UpgradeOptions<Data extends WSData = WSData> {
+  /** Initial value of `ws.data` for the new connection. */
+  data?: Data;
+  /**
+   * Extra response headers.
+   *
+   * @remarks
+   * Forwarded to the underlying handshake when supported (Bun); ignored on
+   * Node-backed upgrades, which control headers via the `ws` package.
+   */
+  headers?: Record<string, string> | Headers;
+}
+//#endregion
+export { ClientWebSocketOptions, ServerWebSocket, UpgradeOptions, UpgradeRequest, WSData, WSMessage, WebSocketHandlers, WebSocketServerOptions };
+//# sourceMappingURL=types.d.mts.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@hedystia/ws",
+  "version": "2.3.1",
+  "description": "Universal WebSocket primitives for Hedystia (Bun, Node.js, Deno)",
+  "homepage": "https://docs.hedystia.com/plugins/websocket",
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "@types/ws": "^8.5.13",
+    "typescript": "6.0.2"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "private": false,
+  "keywords": [
+    "hedystia",
+    "websocket",
+    "ws",
+    "bun",
+    "nodejs",
+    "node",
+    "deno",
+    "realtime",
+    "framework"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsdown --config-loader unrun",
+    "release:pkg": "bun publish --provenance --access public",
+    "dev": "tsdown --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Hedystia/Hedystia"
+  },
+  "author": {
+    "name": "Zastinian",
+    "email": "contact@zastinian.com",
+    "url": "https://github.com/Zastinian"
+  },
+  "type": "commonjs",
+  "types": "./dist/index.d.cts",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.cts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./client": {
+      "types": "./dist/client.d.cts",
+      "import": "./dist/client.mjs",
+      "require": "./dist/client.cjs"
+    },
+    "./server": {
+      "types": "./dist/server.d.cts",
+      "import": "./dist/server.mjs",
+      "require": "./dist/server.cjs"
+    }
+  }
+}

package/readme.md

@@ -0,0 +1,102 @@
+# @hedystia/ws
+
+Universal WebSocket primitives for [Hedystia](https://docs.hedystia.com).
+
+The package ships **no HTTP server**. It only exposes WebSocket pieces that
+work the same way on **Bun**, **Node.js** and **Deno**:
+
+- A runtime-aware **client constructor**.
+- A portable **`WebSocketServer`** that consumes raw HTTP upgrade tuples
+  and offers topic-based pub/sub, mirroring `Bun.ServerWebSocket`.
+- Shared **types** and **runtime detection** helpers.
+
+The HTTP layer (Bun.serve / `node:http`) is intentionally left to the
+caller (`hedystia` server uses it internally).
+
+## Install
+
+```bash
+bun add @hedystia/ws
+# or
+npm install @hedystia/ws
+```
+
+## Client
+
+```ts
+import { createWebSocket } from "@hedystia/ws/client";
+
+const ws = createWebSocket("ws://localhost:3000", {
+  headers: { authorization: "Bearer ..." },
+});
+
+ws.onopen = () => ws.send("hi");
+ws.onmessage = (event) => console.log(event.data);
+```
+
+`createWebSocket()` uses `globalThis.WebSocket` when available (Bun, Deno,
+browsers, Node ≥ 22) and falls back to the [`ws`](https://github.com/websockets/ws)
+package on older Node releases. Custom request headers are honoured on Node
+and ignored elsewhere — matching WHATWG semantics.
+
+A small ergonomic wrapper is also provided:
+
+```ts
+import { WebSocketClient } from "@hedystia/ws/client";
+
+const client = new WebSocketClient("ws://localhost:3000");
+client.onmessage = (e) => console.log(e.data);
+```
+
+## Server
+
+The `WebSocketServer` does **not** open a port. Plug it into any HTTP
+runtime that exposes raw upgrade tuples (`req`, `socket`, `head`).
+
+```ts
+import { createServer } from "node:http";
+import { WebSocketServer } from "@hedystia/ws/server";
+
+const wss = new WebSocketServer({
+  open: (ws) => ws.send("welcome"),
+  message: (ws, message) => ws.publish("room", message),
+});
+
+const http = createServer((_req, res) => res.end("ok"));
+
+http.on("upgrade", (req, socket, head) => {
+  wss.upgrade({ rawRequest: req, socket, head }, { data: { user: "anon" } });
+});
+
+http.listen(3000);
+
+// Broadcast from anywhere
+wss.publish("room", "hello world");
+```
+
+The wrapper exposed to handlers implements:
+
+| Method | Behaviour |
+|--------|-----------|
+| `ws.send(msg)` | Send to a single socket |
+| `ws.subscribe(topic)` | Join a topic |
+| `ws.unsubscribe(topic)` | Leave a topic |
+| `ws.publish(topic, msg)` | Broadcast to peers (excluding self) |
+| `ws.isSubscribed(topic)` | Membership check |
+| `ws.close(code, reason)` | Close the connection |
+| `ws.cork(cb)` | No-op alias for batching writes |
+| `ws.data` | User-supplied state attached on upgrade |
+
+## Runtime detection
+
+```ts
+import { detectRuntime, isBun, isNode, isDeno } from "@hedystia/ws";
+
+if (detectRuntime() === "bun") {
+  // ...
+}
+```
+
+## License
+
+MIT

package/src/client.ts

@@ -0,0 +1,161 @@
+import type { ClientWebSocketOptions } from "./types";
+
+export type { ClientWebSocketOptions } from "./types";
+
+/**
+ * Resolve the best `WebSocket` constructor for the current runtime.
+ *
+ * @remarks
+ * - Bun, Deno, browsers and Node ≥ 22 expose `globalThis.WebSocket`.
+ * - Older Node falls back to the [`ws`](https://github.com/websockets/ws)
+ *   package, which mirrors the WHATWG `WebSocket` API.
+ *
+ * @returns A `WebSocket` constructor compatible with the WHATWG interface.
+ *
+ * @example
+ * ```ts
+ * import { resolveWebSocket } from "@hedystia/ws/client";
+ *
+ * const WS = resolveWebSocket();
+ * const socket = new WS("ws://localhost:3000");
+ * ```
+ */
+export function resolveWebSocket(): typeof WebSocket {
+  if (typeof globalThis !== "undefined" && (globalThis as any).WebSocket) {
+    return (globalThis as any).WebSocket as typeof WebSocket;
+  }
+  const mod = require("ws");
+  return (mod.WebSocket ?? mod) as typeof WebSocket;
+}
+
+/**
+ * Create a `WebSocket` instance using the best available implementation
+ * for the current runtime.
+ *
+ * @remarks
+ * Custom request headers are honoured on Node via the `ws` package; on
+ * runtimes that ship a WHATWG-compliant global `WebSocket` (Bun, Deno,
+ * browsers, Node ≥ 22) headers are ignored — matching standard semantics.
+ *
+ * @param url - Absolute WebSocket URL (`ws://` or `wss://`)
+ * @param options - Optional protocols / headers
+ * @returns A connected (or connecting) `WebSocket` instance.
+ *
+ * @example
+ * ```ts
+ * import { createWebSocket } from "@hedystia/ws/client";
+ *
+ * const ws = createWebSocket("ws://localhost:3000", {
+ *   protocols: "v1",
+ *   headers: { authorization: "Bearer ..." },
+ * });
+ *
+ * ws.onopen = () => ws.send("hi");
+ * ws.onmessage = (event) => console.log(event.data);
+ * ```
+ */
+export function createWebSocket(url: string, options?: ClientWebSocketOptions): WebSocket {
+  const Ctor = resolveWebSocket();
+  const isWhatwg =
+    typeof globalThis !== "undefined" && (globalThis as any).WebSocket === (Ctor as any);
+
+  if (isWhatwg) {
+    return options?.protocols ? new Ctor(url, options.protocols as any) : new Ctor(url);
+  }
+
+  const init: any = {};
+  if (options?.headers) {
+    init.headers = options.headers;
+  }
+  return new (Ctor as any)(url, options?.protocols, init);
+}
+
+/**
+ * Lightweight runtime-agnostic wrapper that mirrors a small, predictable
+ * subset of the WHATWG WebSocket interface.
+ *
+ * @remarks
+ * Useful for higher-level code that wants to assign event handlers by
+ * property (`socket.onmessage = ...`) without caring whether the underlying
+ * implementation comes from `globalThis.WebSocket` or the `ws` package.
+ *
+ * @example
+ * ```ts
+ * import { WebSocketClient } from "@hedystia/ws/client";
+ *
+ * const client = new WebSocketClient("ws://localhost:3000");
+ * client.onopen = () => client.send("hello");
+ * client.onmessage = (event) => console.log(event.data);
+ * ```
+ */
+export class WebSocketClient {
+  /**
+   * Underlying WebSocket instance produced by {@link createWebSocket}.
+   *
+   * @readonly
+   */
+  readonly socket: WebSocket;
+
+  /**
+   * Create a new client and immediately initiate the connection.
+   *
+   * @param url - Absolute WebSocket URL (`ws://` or `wss://`)
+   * @param options - Optional protocols / headers, see {@link ClientWebSocketOptions}
+   */
+  constructor(url: string, options?: ClientWebSocketOptions) {
+    this.socket = createWebSocket(url, options);
+  }
+
+  /**
+   * Current connection state, mirroring {@link WebSocket.readyState}.
+   *
+   * @returns `0` connecting, `1` open, `2` closing, `3` closed.
+   */
+  get readyState(): number {
+    return this.socket.readyState;
+  }
+
+  /**
+   * Send a payload to the server.
+   *
+   * @param data - WHATWG-compatible payload
+   */
+  send(data: string | ArrayBufferLike | Blob | ArrayBufferView): void {
+    this.socket.send(data as any);
+  }
+
+  /**
+   * Close the underlying socket.
+   *
+   * @param code - Close code (defaults to 1000)
+   * @param reason - Optional human-readable reason
+   */
+  close(code?: number, reason?: string): void {
+    this.socket.close(code, reason);
+  }
+
+  /**
+   * Assign the open-event listener.
+   */
+  set onopen(cb: ((ev: Event) => void) | null) {
+    (this.socket as any).onopen = cb;
+  }
+  /**
+   * Assign the message-event listener.
+   */
+  set onmessage(cb: ((ev: MessageEvent) => void) | null) {
+    (this.socket as any).onmessage = cb;
+  }
+  /**
+   * Assign the close-event listener.
+   */
+  set onclose(cb: ((ev: CloseEvent) => void) | null) {
+    (this.socket as any).onclose = cb;
+  }
+  /**
+   * Assign the error-event listener.
+   */
+  set onerror(cb: ((ev: Event) => void) | null) {
+    (this.socket as any).onerror = cb;
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export type { ClientWebSocketOptions } from "./client";
+export { createWebSocket, resolveWebSocket, WebSocketClient } from "./client";
+export type { Runtime } from "./runtime";
+export { detectRuntime, isBrowser, isBun, isDeno, isNode } from "./runtime";
+export type {
+  ServerWebSocket,
+  UpgradeOptions,
+  UpgradeRequest,
+  WebSocketHandlers,
+  WebSocketServerOptions,
+  WSData,
+  WSMessage,
+} from "./server";
+
+import { WebSocketServer } from "./server";
+
+export { WebSocketServer };
+
+export default WebSocketServer;

package/src/runtime.ts

@@ -0,0 +1,66 @@
+/**
+ * String identifier of the JavaScript runtime hosting the current process.
+ */
+export type Runtime = "bun" | "node" | "deno" | "browser" | "unknown";
+
+/**
+ * Detect the host runtime by probing well-known globals.
+ *
+ * @returns A {@link Runtime} discriminator for the active environment.
+ *
+ * @example
+ * ```ts
+ * import { detectRuntime } from "@hedystia/ws";
+ *
+ * if (detectRuntime() === "bun") {
+ *   // ...use Bun-specific APIs
+ * }
+ * ```
+ */
+export function detectRuntime(): Runtime {
+  if (typeof globalThis === "undefined") {
+    return "unknown";
+  }
+  const g = globalThis as any;
+  if (g.Bun?.serve) {
+    return "bun";
+  }
+  if (g.Deno) {
+    return "deno";
+  }
+  if (g.process?.versions?.node) {
+    return "node";
+  }
+  if (typeof g.window !== "undefined" && typeof g.document !== "undefined") {
+    return "browser";
+  }
+  return "unknown";
+}
+
+/**
+ * Convenience predicate.
+ *
+ * @returns `true` when running on Bun.
+ */
+export const isBun = (): boolean => detectRuntime() === "bun";
+
+/**
+ * Convenience predicate.
+ *
+ * @returns `true` when running on Node.js.
+ */
+export const isNode = (): boolean => detectRuntime() === "node";
+
+/**
+ * Convenience predicate.
+ *
+ * @returns `true` when running on Deno.
+ */
+export const isDeno = (): boolean => detectRuntime() === "deno";
+
+/**
+ * Convenience predicate.
+ *
+ * @returns `true` when running inside a browser-like environment.
+ */
+export const isBrowser = (): boolean => detectRuntime() === "browser";