@gjsify/ws 0.3.12 → 0.3.14

package/lib/esm/websocket.js

@@ -1,249 +1,276 @@
+import { BINARY_TYPES, CLOSED, CLOSING, CONNECTING, OPEN } from "./constants.js";
 import { EventEmitter } from "@gjsify/events";
 import { Buffer } from "@gjsify/buffer";
-import { WebSocket as NativeWebSocket } from "@gjsify/websocket";
-import {
-  BINARY_TYPES,
-  CLOSED,
-  CLOSING,
-  CONNECTING,
-  OPEN
-} from "./constants.js";
-class WebSocket extends EventEmitter {
-  /** Static readyState constants — match the W3C and `ws` values. */
-  static CONNECTING = CONNECTING;
-  static OPEN = OPEN;
-  static CLOSING = CLOSING;
-  static CLOSED = CLOSED;
-  /** Instance-side copies for `ws.readyState === ws.OPEN` style code. */
-  CONNECTING = CONNECTING;
-  OPEN = OPEN;
-  CLOSING = CLOSING;
-  CLOSED = CLOSED;
-  /** Per-instance state. Populated from the underlying native WebSocket as
-   *  events arrive; exposed as properties so that ws-calling code like
-   *  `if (ws.readyState === ws.OPEN)` works identically to Node's `ws`. */
-  readyState = CONNECTING;
-  url = "";
-  protocol = "";
-  extensions = "";
-  bufferedAmount = 0;
-  binaryType = "nodebuffer";
-  /** The real WebSocket we delegate to. Typed as `any` because the W3C
-   *  ambient type comes from multiple realms depending on where this bundle
-   *  ends up (GJS browser-like globals vs. Node's undici). */
-  _native = null;
-  constructor(address, protocols, options = {}) {
-    super();
-    if (address === null) {
-      queueMicrotask(() => this._fail("Constructing ws.WebSocket with null address is not supported on Gjs"));
-      return;
-    }
-    this.url = typeof address === "string" ? address : String(address);
-    const protos = this._resolveProtocols(protocols, options);
-    this._openNative(this.url, protos, options);
-  }
-  /** Merge `protocols` arg and `options.protocols` / `options.protocol`. */
-  _resolveProtocols(protocols, options) {
-    if (protocols !== void 0) {
-      return Array.isArray(protocols) ? protocols : [protocols];
-    }
-    if (options.protocols !== void 0) {
-      return Array.isArray(options.protocols) ? options.protocols : [options.protocols];
-    }
-    if (options.protocol !== void 0) return [options.protocol];
-    return void 0;
-  }
-  /** Lazy-open the underlying native WebSocket. Separated from the constructor
-   *  so subclasses or future socket-adoption paths can bypass it. */
-  _openNative(url, protocols, options) {
-    if (typeof NativeWebSocket !== "function") {
-      queueMicrotask(() => this._fail(
-        "@gjsify/websocket provided no WebSocket constructor. On Node.js 22+ globalThis.WebSocket is native; on older Node install `ws` directly, or ensure globalThis.WebSocket is set before @gjsify/ws is imported."
-      ));
-      return;
-    }
-    const nativeOpts = {
-      perMessageDeflate: options.perMessageDeflate !== false,
-      headers: options.headers,
-      origin: options.origin,
-      handshakeTimeout: options.handshakeTimeout
-    };
-    try {
-      this._native = new NativeWebSocket(url, protocols, nativeOpts);
-    } catch (err) {
-      queueMicrotask(() => this._fail(err instanceof Error ? err : new Error(String(err))));
-      return;
-    }
-    this._native.binaryType = "arraybuffer";
-    this._native.addEventListener("open", () => this._onOpen());
-    this._native.addEventListener("message", (ev) => this._onMessage(ev));
-    this._native.addEventListener("close", (ev) => this._onClose(ev));
-    this._native.addEventListener("error", (ev) => this._onError(ev));
-  }
-  _fail(err) {
-    const error = typeof err === "string" ? new Error(err) : err;
-    this.readyState = CLOSED;
-    this.emit("error", error);
-    this._dispatchEvent("error", { error, message: error.message });
-    this.emit("close", 1006, Buffer.from(error.message));
-    this._dispatchEvent("close", { code: 1006, reason: error.message, wasClean: false });
-  }
-  _onOpen() {
-    this.readyState = OPEN;
-    if (typeof this._native.protocol === "string") this.protocol = this._native.protocol;
-    if (typeof this._native.extensions === "string") this.extensions = this._native.extensions;
-    this.emit("open");
-    this._dispatchEvent("open", {});
-  }
-  _onMessage(ev) {
-    const raw = ev?.data;
-    let data;
-    let isBinary = false;
-    if (typeof raw === "string") {
-      data = raw;
-      isBinary = false;
-    } else if (raw instanceof ArrayBuffer) {
-      isBinary = true;
-      data = this._decodeBinary(raw);
-    } else if (ArrayBuffer.isView(raw)) {
-      isBinary = true;
-      data = this._decodeBinary(raw.buffer);
-    } else {
-      data = raw;
-      isBinary = false;
-    }
-    this.emit("message", data, isBinary);
-    this._dispatchEvent("message", { data, type: isBinary ? "binary" : "text" });
-  }
-  /** Convert an ArrayBuffer to the Buffer flavor requested by `binaryType`. */
-  _decodeBinary(buf) {
-    switch (this.binaryType) {
-      case "arraybuffer":
-        return buf;
-      case "fragments":
-        return [Buffer.from(buf)];
-      // one-fragment approximation
-      case "blob": {
-        const BlobCtor = globalThis.Blob;
-        return BlobCtor ? new BlobCtor([new Uint8Array(buf)]) : Buffer.from(buf);
-      }
-      case "nodebuffer":
-      default:
-        return Buffer.from(buf);
-    }
-  }
-  _onClose(ev) {
-    const code = typeof ev?.code === "number" ? ev.code : 1006;
-    const reason = typeof ev?.reason === "string" ? ev.reason : "";
-    this.readyState = CLOSED;
-    this.emit("close", code, Buffer.from(reason));
-    this._dispatchEvent("close", { code, reason, wasClean: !!ev?.wasClean });
-  }
-  _onError(ev) {
-    const msg = ev?.message || "WebSocket error";
-    const err = ev?.error instanceof Error ? ev.error : new Error(msg);
-    this.emit("error", err);
-    this._dispatchEvent("error", { error: err, message: msg });
-  }
-  send(data, optionsOrCb, cb) {
-    const callback = typeof optionsOrCb === "function" ? optionsOrCb : cb;
-    if (this.readyState === CONNECTING) {
-      throw new Error("WebSocket is not open: readyState 0 (CONNECTING)");
-    }
-    if (this.readyState !== OPEN) {
-      const err = new Error("WebSocket is not open: readyState " + this.readyState);
-      if (callback) queueMicrotask(() => callback(err));
-      else queueMicrotask(() => this.emit("error", err));
-      return;
-    }
-    this._nativeSend(data, callback);
-  }
-  _nativeSend(data, cb) {
-    try {
-      let payload = data;
-      if (typeof data === "number" || typeof data === "boolean") {
-        payload = String(data);
-      } else if (Buffer.isBuffer(data)) {
-        const b = data;
-        payload = b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
-      }
-      this._native.send(payload);
-      if (cb) queueMicrotask(() => cb());
-    } catch (err) {
-      const e = err instanceof Error ? err : new Error(String(err));
-      if (cb) queueMicrotask(() => cb(e));
-      else queueMicrotask(() => this.emit("error", e));
-    }
-  }
-  _sizeOf(data) {
-    if (typeof data === "string") return data.length;
-    if (data instanceof ArrayBuffer) return data.byteLength;
-    if (ArrayBuffer.isView(data)) return data.byteLength;
-    return 0;
-  }
-  close(code, reason) {
-    if (this.readyState === CLOSED) return;
-    if (this.readyState === CLOSING) return;
-    this.readyState = CLOSING;
-    try {
-      const reasonStr = reason === void 0 ? void 0 : Buffer.isBuffer(reason) ? reason.toString("utf8") : String(reason);
-      if (code === void 0) this._native?.close();
-      else if (reasonStr === void 0) this._native?.close(code);
-      else this._native?.close(code, reasonStr);
-    } catch (err) {
-      this.emit("error", err instanceof Error ? err : new Error(String(err)));
-    }
-  }
-  /** ws-only: force-close without sending a Close frame. On Gjs we can't bypass
-   *  Soup's close handshake, so terminate is approximated as close(1006).
-   *  Known gap vs. ws semantics — documented. */
-  terminate() {
-    if (this.readyState === CLOSED) return;
-    this.readyState = CLOSING;
-    try {
-      this._native?.close(1006, "terminated");
-    } catch {
-    }
-  }
-  /** Convenience: returns true if the socket is closed or closing. Matches
-   *  ws.isPaused() / internal state checks that some consumers rely on. */
-  get isPaused() {
-    return this.readyState === CLOSING || this.readyState === CLOSED;
-  }
-  // --- W3C EventTarget compat surface -------------------------------------
-  // ws uses EventEmitter by default, but exposes addEventListener-style
-  // registration for consumers that prefer the W3C API. We mirror it to
-  // stay compat.
-  _eventTargetListeners = /* @__PURE__ */ new Map();
-  addEventListener(type, listener) {
-    let set = this._eventTargetListeners.get(type);
-    if (!set) {
-      set = /* @__PURE__ */ new Set();
-      this._eventTargetListeners.set(type, set);
-    }
-    set.add(listener);
-  }
-  removeEventListener(type, listener) {
-    this._eventTargetListeners.get(type)?.delete(listener);
-  }
-  _dispatchEvent(type, detail) {
-    const set = this._eventTargetListeners.get(type);
-    if (!set || set.size === 0) return;
-    const ev = Object.assign({ type, target: this }, detail);
-    for (const listener of set) {
-      try {
-        listener(ev);
-      } catch (err) {
-        queueMicrotask(() => this.emit("error", err));
-      }
-    }
-  }
-  // Static list of accepted binary types — exposed for parity with ws.
-  static get BINARY_TYPES() {
-    return BINARY_TYPES;
-  }
-}
-WebSocket.WebSocket = WebSocket;
-export {
-  WebSocket
+import { WebSocket as WebSocket$1 } from "@gjsify/websocket";
+
+//#region src/websocket.ts
+/** `ws.WebSocket` — EventEmitter-based WebSocket client.
+*
+*  Events (ws-compatible):
+*    - 'open'                          → ()
+*    - 'message'                       → (data: Buffer | ArrayBuffer | string, isBinary: boolean)
+*    - 'close'                         → (code: number, reason: Buffer)
+*    - 'error'                         → (error: Error)
+*    - 'ping' / 'pong'                 → NOT EMITTED on Gjs (Soup handles control
+*                                        frames internally; no JS hook exposed).
+*                                        Consumers that rely on 'ping'/'pong' for
+*                                        keep-alive application logic need to use
+*                                        data messages instead. Tracked as a
+*                                        known limitation in STATUS.md.
+*    - 'upgrade' / 'unexpected-response' / 'redirect'
+*                                      → NOT EMITTED on Gjs (Soup does not expose
+*                                        the raw HTTP upgrade response). Code
+*                                        that only branches on `open` vs `error`
+*                                        still works.
+*
+*  Also implements W3C DOM `EventTarget` methods (addEventListener /
+*  removeEventListener) so `ws` users who follow W3C-style handlers via the
+*  `ws.EventTarget` flag still work without special-casing the Gjs path.
+*/
+var WebSocket = class extends EventEmitter {
+	/** Static readyState constants — match the W3C and `ws` values. */
+	static CONNECTING = 0;
+	static OPEN = 1;
+	static CLOSING = 2;
+	static CLOSED = 3;
+	/** Instance-side copies for `ws.readyState === ws.OPEN` style code. */
+	CONNECTING = 0;
+	OPEN = 1;
+	CLOSING = 2;
+	CLOSED = 3;
+	/** Per-instance state. Populated from the underlying native WebSocket as
+	*  events arrive; exposed as properties so that ws-calling code like
+	*  `if (ws.readyState === ws.OPEN)` works identically to Node's `ws`. */
+	readyState = 0;
+	url = "";
+	protocol = "";
+	extensions = "";
+	bufferedAmount = 0;
+	binaryType = "nodebuffer";
+	/** The real WebSocket we delegate to. Typed as `any` because the W3C
+	*  ambient type comes from multiple realms depending on where this bundle
+	*  ends up (GJS browser-like globals vs. Node's undici). */
+	_native = null;
+	constructor(address, protocols, options = {}) {
+		super();
+		if (address === null) {
+			queueMicrotask(() => this._fail("Constructing ws.WebSocket with null address is not supported on Gjs"));
+			return;
+		}
+		this.url = typeof address === "string" ? address : String(address);
+		const protos = this._resolveProtocols(protocols, options);
+		this._openNative(this.url, protos, options);
+	}
+	/** Merge `protocols` arg and `options.protocols` / `options.protocol`. */
+	_resolveProtocols(protocols, options) {
+		if (protocols !== undefined) {
+			return Array.isArray(protocols) ? protocols : [protocols];
+		}
+		if (options.protocols !== undefined) {
+			return Array.isArray(options.protocols) ? options.protocols : [options.protocols];
+		}
+		if (options.protocol !== undefined) return [options.protocol];
+		return undefined;
+	}
+	/** Lazy-open the underlying native WebSocket. Separated from the constructor
+	*  so subclasses or future socket-adoption paths can bypass it. */
+	_openNative(url, protocols, options) {
+		if (typeof WebSocket$1 !== "function") {
+			queueMicrotask(() => this._fail("@gjsify/websocket provided no WebSocket constructor. On Node.js 22+ " + "globalThis.WebSocket is native; on older Node install `ws` directly, " + "or ensure globalThis.WebSocket is set before @gjsify/ws is imported."));
+			return;
+		}
+		const nativeOpts = {
+			perMessageDeflate: options.perMessageDeflate !== false,
+			headers: options.headers,
+			origin: options.origin,
+			handshakeTimeout: options.handshakeTimeout
+		};
+		try {
+			this._native = new WebSocket$1(url, protocols, nativeOpts);
+		} catch (err) {
+			queueMicrotask(() => this._fail(err instanceof Error ? err : new Error(String(err))));
+			return;
+		}
+		this._native.binaryType = "arraybuffer";
+		this._native.addEventListener("open", () => this._onOpen());
+		this._native.addEventListener("message", (ev) => this._onMessage(ev));
+		this._native.addEventListener("close", (ev) => this._onClose(ev));
+		this._native.addEventListener("error", (ev) => this._onError(ev));
+	}
+	_fail(err) {
+		const error = typeof err === "string" ? new Error(err) : err;
+		this.readyState = 3;
+		this.emit("error", error);
+		this._dispatchEvent("error", {
+			error,
+			message: error.message
+		});
+		this.emit("close", 1006, Buffer.from(error.message));
+		this._dispatchEvent("close", {
+			code: 1006,
+			reason: error.message,
+			wasClean: false
+		});
+	}
+	_onOpen() {
+		this.readyState = 1;
+		if (typeof this._native.protocol === "string") this.protocol = this._native.protocol;
+		if (typeof this._native.extensions === "string") this.extensions = this._native.extensions;
+		this.emit("open");
+		this._dispatchEvent("open", {});
+	}
+	_onMessage(ev) {
+		const raw = ev?.data;
+		let data;
+		let isBinary = false;
+		if (typeof raw === "string") {
+			data = raw;
+			isBinary = false;
+		} else if (raw instanceof ArrayBuffer) {
+			isBinary = true;
+			data = this._decodeBinary(raw);
+		} else if (ArrayBuffer.isView(raw)) {
+			isBinary = true;
+			data = this._decodeBinary(raw.buffer);
+		} else {
+			data = raw;
+			isBinary = false;
+		}
+		this.emit("message", data, isBinary);
+		this._dispatchEvent("message", {
+			data,
+			type: isBinary ? "binary" : "text"
+		});
+	}
+	/** Convert an ArrayBuffer to the Buffer flavor requested by `binaryType`. */
+	_decodeBinary(buf) {
+		switch (this.binaryType) {
+			case "arraybuffer": return buf;
+			case "fragments": return [Buffer.from(buf)];
+			case "blob": {
+				const BlobCtor = globalThis.Blob;
+				return BlobCtor ? new BlobCtor([new Uint8Array(buf)]) : Buffer.from(buf);
+			}
+			case "nodebuffer":
+			default: return Buffer.from(buf);
+		}
+	}
+	_onClose(ev) {
+		const code = typeof ev?.code === "number" ? ev.code : 1006;
+		const reason = typeof ev?.reason === "string" ? ev.reason : "";
+		this.readyState = 3;
+		this.emit("close", code, Buffer.from(reason));
+		this._dispatchEvent("close", {
+			code,
+			reason,
+			wasClean: !!ev?.wasClean
+		});
+	}
+	_onError(ev) {
+		const msg = ev?.message || "WebSocket error";
+		const err = ev?.error instanceof Error ? ev.error : new Error(msg);
+		this.emit("error", err);
+		this._dispatchEvent("error", {
+			error: err,
+			message: msg
+		});
+	}
+	send(data, optionsOrCb, cb) {
+		const callback = typeof optionsOrCb === "function" ? optionsOrCb : cb;
+		if (this.readyState === 0) {
+			throw new Error("WebSocket is not open: readyState 0 (CONNECTING)");
+		}
+		if (this.readyState !== 1) {
+			const err = new Error("WebSocket is not open: readyState " + this.readyState);
+			if (callback) queueMicrotask(() => callback(err));
+			else queueMicrotask(() => this.emit("error", err));
+			return;
+		}
+		this._nativeSend(data, callback);
+	}
+	_nativeSend(data, cb) {
+		try {
+			let payload = data;
+			if (typeof data === "number" || typeof data === "boolean") {
+				payload = String(data);
+			} else if (Buffer.isBuffer(data)) {
+				const b = data;
+				payload = b.buffer.slice(b.byteOffset, b.byteOffset + b.byteLength);
+			}
+			this._native.send(payload);
+			if (cb) queueMicrotask(() => cb());
+		} catch (err) {
+			const e = err instanceof Error ? err : new Error(String(err));
+			if (cb) queueMicrotask(() => cb(e));
+			else queueMicrotask(() => this.emit("error", e));
+		}
+	}
+	_sizeOf(data) {
+		if (typeof data === "string") return data.length;
+		if (data instanceof ArrayBuffer) return data.byteLength;
+		if (ArrayBuffer.isView(data)) return data.byteLength;
+		return 0;
+	}
+	close(code, reason) {
+		if (this.readyState === 3) return;
+		if (this.readyState === 2) return;
+		this.readyState = 2;
+		try {
+			const reasonStr = reason === undefined ? undefined : Buffer.isBuffer(reason) ? reason.toString("utf8") : String(reason);
+			if (code === undefined) this._native?.close();
+			else if (reasonStr === undefined) this._native?.close(code);
+			else this._native?.close(code, reasonStr);
+		} catch (err) {
+			this.emit("error", err instanceof Error ? err : new Error(String(err)));
+		}
+	}
+	/** ws-only: force-close without sending a Close frame. On Gjs we can't bypass
+	*  Soup's close handshake, so terminate is approximated as close(1006).
+	*  Known gap vs. ws semantics — documented. */
+	terminate() {
+		if (this.readyState === 3) return;
+		this.readyState = 2;
+		try {
+			this._native?.close(1006, "terminated");
+		} catch {}
+	}
+	/** Convenience: returns true if the socket is closed or closing. Matches
+	*  ws.isPaused() / internal state checks that some consumers rely on. */
+	get isPaused() {
+		return this.readyState === 2 || this.readyState === 3;
+	}
+	_eventTargetListeners = new Map();
+	addEventListener(type, listener) {
+		let set = this._eventTargetListeners.get(type);
+		if (!set) {
+			set = new Set();
+			this._eventTargetListeners.set(type, set);
+		}
+		set.add(listener);
+	}
+	removeEventListener(type, listener) {
+		this._eventTargetListeners.get(type)?.delete(listener);
+	}
+	_dispatchEvent(type, detail) {
+		const set = this._eventTargetListeners.get(type);
+		if (!set || set.size === 0) return;
+		const ev = Object.assign({
+			type,
+			target: this
+		}, detail);
+		for (const listener of set) {
+			try {
+				listener(ev);
+			} catch (err) {
+				queueMicrotask(() => this.emit("error", err));
+			}
+		}
+	}
+	static get BINARY_TYPES() {
+		return BINARY_TYPES;
+	}
 };
+WebSocket.WebSocket = WebSocket;
+
+//#endregion
+export { WebSocket };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjsify/ws",
-  "version": "0.3.12",
+  "version": "0.3.14",
   "description": "Drop-in replacement for the `ws` npm package on Gjs — wraps globalThis.WebSocket (Soup.WebsocketConnection) and Soup.Server for the WebSocketServer side",
   "type": "module",
   "module": "lib/esm/index.js",
@@ -31,18 +31,18 @@
     "websocket"
   ],
   "dependencies": {
-    "@girs/gio-2.0": "^2.88.0-4.0.0-rc.9",
-    "@girs/glib-2.0": "^2.88.0-4.0.0-rc.9",
-    "@girs/soup-3.0": "^3.6.6-4.0.0-rc.9",
-    "@gjsify/buffer": "^0.3.12",
-    "@gjsify/crypto": "^0.3.12",
-    "@gjsify/events": "^0.3.12",
-    "@gjsify/utils": "^0.3.12",
-    "@gjsify/websocket": "^0.3.12"
+    "@girs/gio-2.0": "2.88.0-4.0.0-rc.9",
+    "@girs/glib-2.0": "2.88.0-4.0.0-rc.9",
+    "@girs/soup-3.0": "3.6.6-4.0.0-rc.9",
+    "@gjsify/buffer": "^0.3.14",
+    "@gjsify/crypto": "^0.3.14",
+    "@gjsify/events": "^0.3.14",
+    "@gjsify/utils": "^0.3.14",
+    "@gjsify/websocket": "^0.3.14"
   },
   "devDependencies": {
-    "@gjsify/cli": "^0.3.12",
-    "@gjsify/unit": "^0.3.12",
+    "@gjsify/cli": "^0.3.14",
+    "@gjsify/unit": "^0.3.14",
     "@types/node": "^25.6.0",
     "typescript": "^6.0.3"
   }