ump-plugin-websocket

DOM-style WebSocket(url, protocols) for UMP apps — RFC 6455 + WHATWG-shaped, backed by each platform's native WebSocket (OkHttp on Android, NSURLSessionWebSocketTask on iOS, @ohos.net.webSocket on HarmonyOS).

Install

npm install ump-plugin-websocket

Peer dependencies (must already be installed in your app):

• ump-core
• ump-native

Usage

import { WebSocket, CloseEvent } from 'ump-plugin-websocket';

const ws = new WebSocket('wss://example.com/echo', 'graphql-ws');

ws.addEventListener('open', () => ws.send('hello'));
ws.addEventListener('message', (ev) => console.log('got', ev.data));
ws.addEventListener('close', (ev: CloseEvent) => {
  console.log('closed', ev.code, ev.reason, ev.wasClean);
});
ws.addEventListener('error', () => console.log('error'));

// Binary frames — Uint8Array or ArrayBuffer
ws.binaryType = 'arraybuffer';
ws.send(new Uint8Array([1, 2, 3, 4]));

// Application-level close codes (1000 or 3000-4999)
ws.close(3999, 'app-level reason');

Importing this module also installs globalThis.WebSocket and globalThis.CloseEvent when the host doesn't already provide them, so libraries that look up the bare global names (RxJS, graphql-ws, MQTT, EventSource fallbacks) just work.

API surface

DOM WebSocket interface honoured:

| Member | Notes | |-------------------------------------------|--------------------------------------------------------| | new WebSocket(url, protocols?) | protocols may be string or string[] | | Static + instance CONNECTING/OPEN/CLOSING/CLOSED | 0/1/2/3 | | url, protocol, readyState | protocol reflects what the server selected | | bufferedAmount | Always 0 (deferred to v2 — see source comments) | | binaryType | 'blob' (default) or 'arraybuffer'. 'blob' falls back to ArrayBuffer delivery (Hermes ships no Blob). | | onopen / onmessage / onerror / onclose | Property setters | | addEventListener / removeEventListener | 'open' \| 'message' \| 'error' \| 'close' | | send(data) | Accepts string, ArrayBuffer, ArrayBufferView (Uint8Array). No Blob. | | close(code?, reason?) | Code must be 1000 or in [3000, 4999]; reason ≤123 UTF-8 bytes |

Close events

CloseEvent exposes code, reason, and wasClean per spec.

Migration from ump-native

In ump-native 0.1.x, WebSocket and CloseEvent were bundled with the main package. Starting 0.2.x, they ship as this separate plugin.

- import { WebSocket, CloseEvent } from 'ump-native';
+ import { WebSocket, CloseEvent } from 'ump-plugin-websocket';

The global install side-effect (globalThis.WebSocket) still fires on import, so existing code that relies on the bare global continues to work — just import this plugin once at app boot.

No API changes.