@wevu/web-apis 1.1.0 → 1.2.0

package/README.md

@@ -2,7 +2,7 @@
 
 ## 1. 简介
 
-`@wevu/web-apis` 为小程序运行时提供一组 Web API 兼容层，重点解决第三方请求库在小程序环境中缺失 `fetch`、`Request`、`Response`、`AbortController`、`XMLHttpRequest`、`URL` 等全局对象的问题。
+`@wevu/web-apis` 为小程序运行时提供一组 Web API 兼容层，重点解决第三方请求库在小程序环境中缺失 `fetch`、`Request`、`Response`、`AbortController`、`XMLHttpRequest`、`URL`、`WebSocket` 等全局对象的问题。
 
 它主要服务于：
 
@@ -14,7 +14,7 @@
 
 - 按需安装 `fetch`、`Headers`、`Request`、`Response`
 - 提供 `AbortController` / `AbortSignal` 兼容层
-- 提供 `XMLHttpRequest`、`URL`、`URLSearchParams`、`Blob`、`FormData` 兼容层
+- 提供 `XMLHttpRequest`、`URL`、`URLSearchParams`、`Blob`、`FormData`、`WebSocket` 兼容层
 - 自动把能力安装到可用的小程序宿主全局对象
 - 默认基于 `@wevu/api` 的请求能力完成底层转发
 
@@ -33,7 +33,7 @@ import { installRequestGlobals } from '@wevu/web-apis'
 
 installRequestGlobals()
 
-const response = await fetch('https://example.com/data')
+const response = await fetch('https://request-globals.invalid/data')
 console.log(await response.json())
 ```
 
@@ -58,24 +58,58 @@ installRequestGlobals({
 })
 ```
 
+### 4.4 安装并使用 WebSocket
+
+```ts
+import { installRequestGlobals } from '@wevu/web-apis'
+
+installRequestGlobals({
+  targets: ['WebSocket'],
+})
+
+const socket = new WebSocket('wss://example.com/socket', ['chat'])
+
+socket.onopen = () => {
+  socket.send(JSON.stringify({ type: 'ping' }))
+}
+
+socket.onmessage = (event) => {
+  console.log(event.data)
+}
+
+socket.onclose = (event) => {
+  console.log(event.code, event.reason)
+}
+```
+
 ## 5. 主要导出
 
-| 导出                                                       | 说明                                     |
-| ---------------------------------------------------------- | ---------------------------------------- |
-| `installRequestGlobals`                                    | 按需安装请求相关全局对象                 |
-| `installAbortGlobals`                                      | 仅安装 `AbortController` / `AbortSignal` |
-| `fetch`                                                    | 基于小程序请求能力适配的 `fetch` 实现    |
-| `HeadersPolyfill` / `RequestPolyfill` / `ResponsePolyfill` | HTTP 相关兼容类                          |
-| `URLPolyfill` / `URLSearchParamsPolyfill`                  | URL 相关兼容类                           |
-| `XMLHttpRequestPolyfill`                                   | XHR 兼容实现                             |
+| 导出                                                       | 说明                                            |
+| ---------------------------------------------------------- | ----------------------------------------------- |
+| `installRequestGlobals`                                    | 按需安装请求相关全局对象                        |
+| `installAbortGlobals`                                      | 仅安装 `AbortController` / `AbortSignal`        |
+| `fetch`                                                    | 基于小程序请求能力适配的 `fetch` 实现           |
+| `HeadersPolyfill` / `RequestPolyfill` / `ResponsePolyfill` | HTTP 相关兼容类                                 |
+| `URLPolyfill` / `URLSearchParamsPolyfill`                  | URL 相关兼容类                                  |
+| `WebSocketPolyfill`                                        | 基于小程序 `SocketTask` 的 `WebSocket` 兼容实现 |
+| `XMLHttpRequestPolyfill`                                   | XHR 兼容实现                                    |
 
 ## 6. 适用场景
 
 - 在小程序环境中运行 `axios` 的 `fetch` 适配器
 - 在小程序环境中运行 `graphql-request`
+- 在小程序环境中直接复用浏览器风格的 `WebSocket` 客户端代码
 - 给依赖 `URL` / `FormData` / `Blob` 的库补齐基础全局对象
 
-## 7. 本地开发
+## 7. WebSocket 兼容说明
+
+- 当前 `WebSocket` 兼容层底层桥接的是小程序 `SocketTask`
+- 支持 `new WebSocket(url, protocols?)`、`send`、`close`、`readyState`、`binaryType`
+- 支持 `onopen` / `onmessage` / `onerror` / `onclose` 以及 `addEventListener`
+- 当前不会模拟浏览器里完整的 `bufferedAmount`、协商后的 `protocol`、`extensions`
+- 如果运行时没有可用的 `connectSocket` 能力，构造时会直接抛错
+
+## 8. 本地开发
 
 ```bash
 pnpm --filter @wevu/web-apis build
@@ -83,7 +117,7 @@ pnpm --filter @wevu/web-apis test
 pnpm --filter @wevu/web-apis typecheck
 ```
 
-## 8. 相关链接
+## 9. 相关链接
 
 - `@wevu/api`：[../weapi/README.md](../weapi/README.md)
 - `wevu`：[../wevu/README.md](../wevu/README.md)

package/dist/index.d.mts

@@ -4,10 +4,11 @@ import { fetch } from "./fetch.mjs";
 import { HeadersPolyfill, RequestPolyfill, ResponsePolyfill } from "./http.mjs";
 import { URLPolyfill, URLSearchParamsPolyfill } from "./url.mjs";
 import { BlobPolyfill, FormDataPolyfill } from "./web.mjs";
+import { WebSocketPolyfill } from "./websocket.mjs";
 import { XMLHttpRequestPolyfill } from "./xhr.mjs";
 
 //#region src/index.d.ts
-type WeappInjectRequestGlobalsTarget = 'fetch' | 'Headers' | 'Request' | 'Response' | 'AbortController' | 'AbortSignal' | 'XMLHttpRequest';
+type WeappInjectRequestGlobalsTarget = 'fetch' | 'Headers' | 'Request' | 'Response' | 'AbortController' | 'AbortSignal' | 'XMLHttpRequest' | 'WebSocket';
 interface InstallRequestGlobalsOptions {
   targets?: WeappInjectRequestGlobalsTarget[];
 }
@@ -20,4 +21,4 @@ declare function installRequestGlobals(options?: InstallRequestGlobalsOptions):
  */
 declare function installAbortGlobals(): Record<string, any>;
 //#endregion
-export { AbortControllerPolyfill, AbortSignalPolyfill, BlobPolyfill, FormDataPolyfill, HeadersPolyfill, InstallRequestGlobalsOptions, RequestGlobalsEventTarget, RequestPolyfill, ResponsePolyfill, URLPolyfill, URLSearchParamsPolyfill, WeappInjectRequestGlobalsTarget, XMLHttpRequestPolyfill, fetch, installAbortGlobals, installRequestGlobals };
+export { AbortControllerPolyfill, AbortSignalPolyfill, BlobPolyfill, FormDataPolyfill, HeadersPolyfill, InstallRequestGlobalsOptions, RequestGlobalsEventTarget, RequestPolyfill, ResponsePolyfill, URLPolyfill, URLSearchParamsPolyfill, WeappInjectRequestGlobalsTarget, WebSocketPolyfill, XMLHttpRequestPolyfill, fetch, installAbortGlobals, installRequestGlobals };

package/dist/index.mjs

@@ -4,8 +4,18 @@ import { HeadersPolyfill, RequestPolyfill, ResponsePolyfill } from "./http.mjs";
 import { fetch } from "./fetch.mjs";
 import { URLPolyfill, URLSearchParamsPolyfill } from "./url.mjs";
 import { BlobPolyfill, FormDataPolyfill } from "./web.mjs";
+import { WebSocketPolyfill } from "./websocket.mjs";
 import { XMLHttpRequestPolyfill } from "./xhr.mjs";
 //#region src/index.ts
+function hasUsableConstructor(value, args = []) {
+	if (typeof value !== "function") return false;
+	try {
+		Reflect.construct(value, args);
+		return true;
+	} catch {
+		return false;
+	}
+}
 function installSingleTarget(host, target) {
 	if (target === "fetch") {
 		if (typeof host.fetch !== "function") host.fetch = fetch;
@@ -31,13 +41,17 @@ function installSingleTarget(host, target) {
 		if (typeof host.AbortSignal !== "function") host.AbortSignal = AbortSignalPolyfill;
 		return;
 	}
+	if (target === "WebSocket") {
+		if (typeof host.WebSocket !== "function") host.WebSocket = WebSocketPolyfill;
+		return;
+	}
 	if (target === "XMLHttpRequest" && typeof host.XMLHttpRequest !== "function") host.XMLHttpRequest = XMLHttpRequestPolyfill;
 }
 function installUrlGlobals(host) {
-	if (typeof host.URL !== "function") host.URL = URLPolyfill;
-	if (typeof host.URLSearchParams !== "function") host.URLSearchParams = URLSearchParamsPolyfill;
-	if (typeof host.Blob !== "function") host.Blob = BlobPolyfill;
-	if (typeof host.FormData !== "function") host.FormData = FormDataPolyfill;
+	if (!hasUsableConstructor(host.URL, ["https://request-globals.invalid"])) host.URL = URLPolyfill;
+	if (!hasUsableConstructor(host.URLSearchParams, ["client=graphql-request"])) host.URLSearchParams = URLSearchParamsPolyfill;
+	if (!hasUsableConstructor(host.Blob)) host.Blob = BlobPolyfill;
+	if (!hasUsableConstructor(host.FormData)) host.FormData = FormDataPolyfill;
 }
 function installGlobalBindingIfNeeded(host, target) {
 	const value = host[target];
@@ -55,7 +69,8 @@ function installRequestGlobals(options = {}) {
 		"Response",
 		"AbortController",
 		"AbortSignal",
-		"XMLHttpRequest"
+		"XMLHttpRequest",
+		"WebSocket"
 	];
 	const hosts = resolveRequestGlobalsHosts();
 	const primaryHost = resolveRequestGlobalsHost();
@@ -80,4 +95,4 @@ function installAbortGlobals() {
 	return installRequestGlobals({ targets: ["AbortController", "AbortSignal"] });
 }
 //#endregion
-export { AbortControllerPolyfill, AbortSignalPolyfill, BlobPolyfill, FormDataPolyfill, HeadersPolyfill, RequestGlobalsEventTarget, RequestPolyfill, ResponsePolyfill, URLPolyfill, URLSearchParamsPolyfill, XMLHttpRequestPolyfill, fetch, installAbortGlobals, installRequestGlobals };
+export { AbortControllerPolyfill, AbortSignalPolyfill, BlobPolyfill, FormDataPolyfill, HeadersPolyfill, RequestGlobalsEventTarget, RequestPolyfill, ResponsePolyfill, URLPolyfill, URLSearchParamsPolyfill, WebSocketPolyfill, XMLHttpRequestPolyfill, fetch, installAbortGlobals, installRequestGlobals };

package/dist/web.d.mts

@@ -7,7 +7,7 @@ declare class BlobPolyfill {
   constructor(parts?: BlobPart[], options?: {
     type?: string;
   });
-  arrayBuffer(): Promise<any>;
+  arrayBuffer(): Promise<ArrayBuffer>;
   text(): Promise<string>;
 }
 type FormDataEntryValue = BlobPolyfill | string;

package/dist/web.mjs

@@ -1,7 +1,7 @@
 import { cloneArrayBuffer, cloneArrayBufferView, decodeText, encodeText } from "./shared.mjs";
 //#region src/web.ts
 function normalizeBlobPart(part) {
-	if (typeof part === "string") return encodeText(part);
+	if (typeof part === "string") return Promise.resolve(encodeText(part));
 	if (part && typeof part === "object" && typeof part.arrayBuffer === "function") return part.arrayBuffer();
 	if (part instanceof ArrayBuffer) return Promise.resolve(cloneArrayBuffer(part));
 	if (ArrayBuffer.isView(part)) return Promise.resolve(cloneArrayBufferView(part));

package/dist/websocket.d.mts

@@ -0,0 +1,53 @@
+import { RequestGlobalsEventTarget } from "./shared.mjs";
+import { BlobPolyfill } from "./web.mjs";
+
+//#region src/websocket.d.ts
+type WebSocketBinaryType = 'blob' | 'arraybuffer';
+type WebSocketSendData = string | ArrayBuffer | ArrayBufferView | Blob;
+type WebSocketMessageData = string | ArrayBuffer | Blob | BlobPolyfill;
+interface WebSocketCloseEventLike {
+  code: number;
+  reason: string;
+  type: 'close';
+  wasClean: boolean;
+}
+interface WebSocketErrorEventLike {
+  error?: unknown;
+  message?: string;
+  type: 'error';
+}
+interface WebSocketMessageEventLike {
+  data: WebSocketMessageData;
+  origin: string;
+  type: 'message';
+}
+declare class WebSocketPolyfill extends RequestGlobalsEventTarget {
+  static readonly CONNECTING = 0;
+  static readonly OPEN = 1;
+  static readonly CLOSING = 2;
+  static readonly CLOSED = 3;
+  readonly CONNECTING = 0;
+  readonly OPEN = 1;
+  readonly CLOSING = 2;
+  readonly CLOSED = 3;
+  readonly extensions = "";
+  readonly protocol = "";
+  readonly url: string;
+  binaryType: WebSocketBinaryType;
+  bufferedAmount: number;
+  readyState: number;
+  onclose: ((event: WebSocketCloseEventLike) => void) | null;
+  onerror: ((event: WebSocketErrorEventLike) => void) | null;
+  onmessage: ((event: WebSocketMessageEventLike) => void) | null;
+  onopen: ((event: {
+    type: 'open';
+  }) => void) | null;
+  private socketTask?;
+  constructor(url: string, protocols?: string | string[]);
+  close(code?: number, reason?: string): void;
+  send(data: WebSocketSendData): void;
+  private closeFromRuntime;
+  private emitError;
+}
+//#endregion
+export { WebSocketPolyfill };

package/dist/websocket.mjs

@@ -0,0 +1,193 @@
+import { RequestGlobalsEventTarget, cloneArrayBuffer, cloneArrayBufferView } from "./shared.mjs";
+import { URLPolyfill } from "./url.mjs";
+import { BlobPolyfill } from "./web.mjs";
+import { wpi } from "@wevu/api";
+//#region src/websocket.ts
+const WHITESPACE_RE = /\s/u;
+function isValidProtocol(protocol) {
+	return [...protocol].every((char) => {
+		const code = char.charCodeAt(0);
+		return code >= 33 && code <= 126 && char !== "," && !WHITESPACE_RE.test(char);
+	});
+}
+function createDomLikeError(name, message) {
+	if (typeof DOMException === "function") return new DOMException(message, name);
+	const error = new Error(message);
+	error.name = name;
+	return error;
+}
+function encodeReasonLength(reason) {
+	if (typeof TextEncoder === "function") return new TextEncoder().encode(reason).byteLength;
+	return unescape(encodeURIComponent(reason)).length;
+}
+function normalizeCloseCode(code) {
+	if (code == null) return;
+	if (code === 1e3 || code >= 3e3 && code <= 4999) return code;
+	throw createDomLikeError("InvalidAccessError", `Failed to execute close: invalid code "${code}"`);
+}
+function normalizeCloseReason(reason) {
+	if (reason == null) return;
+	const normalized = String(reason);
+	if (encodeReasonLength(normalized) > 123) throw createDomLikeError("SyntaxError", "Failed to execute close: reason is longer than 123 bytes");
+	return normalized;
+}
+function resolveUrlConstructor() {
+	return typeof URL === "function" ? URL : URLPolyfill;
+}
+function normalizeProtocols(protocols) {
+	if (protocols == null) return;
+	const normalized = (Array.isArray(protocols) ? [...protocols] : [protocols]).map((protocol) => String(protocol));
+	const unique = /* @__PURE__ */ new Set();
+	for (const protocol of normalized) {
+		if (!isValidProtocol(protocol)) throw new SyntaxError(`Failed to construct 'WebSocket': invalid subprotocol "${protocol}"`);
+		if (unique.has(protocol)) throw new SyntaxError(`Failed to construct 'WebSocket': duplicated subprotocol "${protocol}"`);
+		unique.add(protocol);
+	}
+	return normalized;
+}
+function normalizeUrl(url) {
+	const parsed = new (resolveUrlConstructor())(String(url));
+	if (parsed.protocol !== "ws:" && parsed.protocol !== "wss:") throw new SyntaxError(`Failed to construct 'WebSocket': invalid URL "${url}"`);
+	if (parsed.hash) throw new SyntaxError(`Failed to construct 'WebSocket': URL contains fragment "${url}"`);
+	return parsed.toString();
+}
+function isSocketTask(value) {
+	return typeof value === "object" && value !== null && typeof value.send === "function" && typeof value.close === "function";
+}
+function toBinaryPayload(data) {
+	if (typeof data === "string") return data;
+	if (data instanceof ArrayBuffer) return cloneArrayBuffer(data);
+	if (ArrayBuffer.isView(data)) return cloneArrayBufferView(data);
+	if (typeof Blob !== "undefined" && data instanceof Blob) return data.arrayBuffer();
+	throw new TypeError("Failed to execute send: data must be a string, ArrayBuffer, ArrayBufferView or Blob");
+}
+function createErrorEvent(error) {
+	return {
+		type: "error",
+		error,
+		message: typeof error === "object" && error !== null && "errMsg" in error ? String(error.errMsg ?? "") : error instanceof Error ? error.message : void 0
+	};
+}
+function createCloseEvent(result) {
+	return {
+		type: "close",
+		code: result?.code ?? 1e3,
+		reason: result?.reason ?? "",
+		wasClean: (result?.code ?? 1e3) === 1e3
+	};
+}
+function createMessageEvent(url, data) {
+	return {
+		type: "message",
+		data,
+		origin: new (resolveUrlConstructor())(url).origin
+	};
+}
+function getRawConnectSocket() {
+	const adapter = wpi.getAdapter?.() ?? wpi.raw;
+	const target = wpi.resolveTarget?.("connectSocket");
+	if (!adapter || !target?.supported) return;
+	const method = adapter[target.target];
+	return typeof method === "function" ? method.bind(adapter) : void 0;
+}
+var WebSocketPolyfill = class WebSocketPolyfill extends RequestGlobalsEventTarget {
+	static CONNECTING = 0;
+	static OPEN = 1;
+	static CLOSING = 2;
+	static CLOSED = 3;
+	CONNECTING = WebSocketPolyfill.CONNECTING;
+	OPEN = WebSocketPolyfill.OPEN;
+	CLOSING = WebSocketPolyfill.CLOSING;
+	CLOSED = WebSocketPolyfill.CLOSED;
+	extensions = "";
+	protocol = "";
+	url;
+	binaryType = "blob";
+	bufferedAmount = 0;
+	readyState = WebSocketPolyfill.CONNECTING;
+	onclose = null;
+	onerror = null;
+	onmessage = null;
+	onopen = null;
+	socketTask;
+	constructor(url, protocols) {
+		super();
+		this.url = normalizeUrl(url);
+		const connectSocket = getRawConnectSocket();
+		if (!connectSocket) throw createDomLikeError("NotSupportedError", "WebSocket is not supported in the current mini-program runtime");
+		const normalizedProtocols = normalizeProtocols(protocols);
+		const task = connectSocket({
+			url: this.url,
+			protocols: normalizedProtocols,
+			fail: (error) => {
+				this.emitError(error);
+				this.closeFromRuntime();
+			}
+		});
+		if (!isSocketTask(task)) throw createDomLikeError("NetworkError", "Failed to create mini-program SocketTask");
+		this.socketTask = task;
+		task.onOpen(() => {
+			if (this.readyState !== WebSocketPolyfill.CONNECTING) return;
+			this.readyState = WebSocketPolyfill.OPEN;
+			this.dispatchEvent({ type: "open" });
+		});
+		task.onMessage((result) => {
+			if (this.readyState === WebSocketPolyfill.CLOSED) return;
+			const data = typeof result.data === "string" ? result.data : this.binaryType === "arraybuffer" ? cloneArrayBuffer(result.data) : new BlobPolyfill([cloneArrayBuffer(result.data)]);
+			this.dispatchEvent(createMessageEvent(this.url, data));
+		});
+		task.onError((error) => {
+			this.emitError(error);
+		});
+		task.onClose((result) => {
+			this.closeFromRuntime(result);
+		});
+	}
+	close(code, reason) {
+		if (this.readyState === WebSocketPolyfill.CLOSING || this.readyState === WebSocketPolyfill.CLOSED) return;
+		const normalizedCode = normalizeCloseCode(code);
+		const normalizedReason = normalizeCloseReason(reason);
+		this.readyState = WebSocketPolyfill.CLOSING;
+		this.socketTask?.close({
+			code: normalizedCode,
+			reason: normalizedReason,
+			fail: (error) => {
+				this.emitError(error);
+			}
+		});
+	}
+	send(data) {
+		if (this.readyState === WebSocketPolyfill.CONNECTING) throw createDomLikeError("InvalidStateError", "Failed to execute send: WebSocket is still in CONNECTING state");
+		if (this.readyState !== WebSocketPolyfill.OPEN || !this.socketTask) throw createDomLikeError("InvalidStateError", "Failed to execute send: WebSocket is not open");
+		const payload = toBinaryPayload(data);
+		if (payload instanceof Promise) {
+			payload.then((resolved) => {
+				this.socketTask?.send({
+					data: resolved,
+					fail: (error) => {
+						this.emitError(error);
+					}
+				});
+			}).catch((error) => {
+				this.emitError(error);
+			});
+			return;
+		}
+		this.socketTask.send({
+			data: payload,
+			fail: (error) => {
+				this.emitError(error);
+			}
+		});
+	}
+	closeFromRuntime(result) {
+		if (this.readyState === WebSocketPolyfill.CLOSED) return;
+		this.readyState = WebSocketPolyfill.CLOSED;
+		this.dispatchEvent(createCloseEvent(result));
+	}
+	emitError(error) {
+		this.dispatchEvent(createErrorEvent(error));
+	}
+};
+//#endregion
+export { WebSocketPolyfill };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wevu/web-apis",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Web API polyfills and global installers for mini-program runtimes",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -51,6 +51,10 @@
       "types": "./dist/web.d.mts",
       "import": "./dist/web.mjs"
     },
+    "./websocket": {
+      "types": "./dist/websocket.d.mts",
+      "import": "./dist/websocket.mjs"
+    },
     "./xhr": {
       "types": "./dist/xhr.d.mts",
       "import": "./dist/xhr.mjs"
@@ -66,7 +70,7 @@
     "node": "^20.19.0 || >=22.12.0"
   },
   "dependencies": {
-    "@wevu/api": "0.2.2"
+    "@wevu/api": "0.2.3"
   },
   "publishConfig": {
     "access": "public",