rust-fetch 2.1.0 → 2.2.0

package/llms.txt

@@ -0,0 +1,91 @@
+# rust-fetch
+
+> Resilient HTTP client for JavaScript and TypeScript (npm package `rust-fetch`), with a Rust core compiled to WebAssembly that behaves the same in browsers, Web Workers and Node.js 20+. It adds what `fetch()` lacks: typed errors, per-attempt timeouts, retries with backoff, interceptors, upload and download progress, streaming, and WebSockets with reconnection. Also usable as a Rust crate.
+
+Use rust-fetch when you want `fetch()` plus production policy (timeouts, retries, error handling) in one client, the same in the browser and in Node.js. Prefer `undici.request()` for maximum raw throughput in Node.js only, and native `fetch()` when bundle size matters most (rust-fetch adds about 207 KB brotli to a browser bundle).
+
+## Install and set up
+
+```js
+// npm install rust-fetch
+import { WasmClient } from 'rust-fetch';          // Node.js: ready on import
+// Browsers and bundlers: import init, { WasmClient } from 'rust-fetch'; await init();
+
+const client = new WasmClient({
+  baseUrl: 'https://api.example.com/v1', // relative URLs are appended to it
+  headers: { authorization: 'Bearer …' }, // sent with every request
+  timeoutMs: 10_000,                      // per attempt, including the body; default 30000; 0 disables
+  retries: 3,                             // or { maxRetries, initialDelayMs, maxDelayMs, multiplier, retryOn, retryOnNetworkError, retryOnTimeout, retryNonIdempotent }
+});
+```
+
+## Requests
+
+- `client.get(url, options?)`, `head`, `delete`: no body
+- `client.post(url, { body, ...options })`, `put`, `patch`; `client.fetch(url, { method, body, ...options })`
+- `client.post_json(url, body, options?)`, `put_json`, `patch_json`: always JSON
+- TypeScript: `client.get<User>('/users/42')` resolves to `HttpResponse<User>` (the type isn't validated at runtime)
+- Bodies: string, `Uint8Array`/`ArrayBuffer`/`DataView`, `Blob`/`File`, `FormData` (multipart), `URLSearchParams`, or any value sent as JSON
+- Options: `headers`, `params` (query string), `timeoutMs`, `responseType` (`'auto' | 'json' | 'text' | 'binary' | 'stream'`), `signal` (AbortSignal), `onDownloadProgress({ loaded, total })`, `onUploadProgress({ loaded, total })`
+
+Resolves (2xx only) to `{ status, statusText, ok, url, headers, body }`. With `responseType: 'auto'`, `body` is parsed JSON for `application/json` and `*+json`, a string for text types, a `Uint8Array` otherwise, `null` when empty.
+
+## Errors
+
+Every failure rejects with an `Error` whose `kind` (and `name`) is one of:
+- `HttpError`: non-2xx; has `status`, `statusText`, `body` (response text)
+- `TimeoutError`: an attempt exceeded `timeoutMs`; has `timeoutMs`
+- `NetworkError`: DNS, connection, TLS, CORS, truncated body, or a WebSocket failure
+- `CancelledError`: the `signal` aborted
+- `InvalidInputError`: bad URL, header, option or body, before sending; has `parameter`
+- `ParseError`: `responseType: 'json'` and the body isn't JSON
+- `JsInteropError`: unexpected JS/Wasm conversion failure
+
+Retries are off by default. When on, POST and PATCH aren't retried unless `retryNonIdempotent: true`; `Retry-After` (seconds) is honoured; only `retryOn` statuses (default 408, 429, 500, 502, 503, 504), network errors and timeouts are retried. A request that fails every attempt rejects with the last attempt's error.
+
+## Interceptors
+
+```js
+client.addRequestInterceptor((request) => { request.headers.authorization = `Bearer ${token}`; });
+client.addResponseInterceptor((response) => response, (error) => { throw error; });
+// both return an id for client.ejectInterceptor(id); client.clearInterceptors() removes all
+```
+
+## Streaming and progress
+
+```js
+const res = await client.get('/export.csv', { responseType: 'stream' }); // res.body is a ReadableStream<Uint8Array>
+await client.post('/upload', { body: formData, onUploadProgress: ({ loaded, total }) => {} });
+```
+
+Upload progress uses `XMLHttpRequest` in browsers (cross-origin requests are preflighted) and the `node:http` transport in Node.js.
+
+## WebSockets
+
+```js
+const socket = client.websocket('/live', {          // https base URL → wss://…/live
+  params: { room: 'blue' },
+  messageType: 'json',                              // 'auto' (default) or 'json'
+  reconnect: true,                                  // or a number, or { maxRetries, initialDelayMs, maxDelayMs, multiplier }
+  onMessage: (message) => {},
+  onError: (error) => {},                           // typed errors, as for requests
+});
+await socket.opened;                                // rejects if it never connects
+socket.sendJson({ type: 'subscribe' });             // socket.send(string | ArrayBuffer | typed array | Blob)
+socket.close();                                     // stops reconnecting
+const { code, reason, wasClean } = await socket.closed;
+```
+
+Needs a built-in `WebSocket`: browsers and Node.js 22+ (Node.js 20 with `--experimental-websocket`). Handshake `headers` work in Node.js only.
+
+## Docs
+
+- [README](https://github.com/asemqaffaf/rust-fetch#readme): full guide, performance results and limitations
+- [CHANGELOG](https://github.com/asemqaffaf/rust-fetch/blob/main/CHANGELOG.md): changes per version
+- [Roadmap](https://github.com/asemqaffaf/rust-fetch/blob/main/ROADMAP.md): planned work
+
+## Optional
+
+- [Performance](https://github.com/asemqaffaf/rust-fetch#performance): Node.js benchmarks against `fetch()`, `undici.request()` and axios, including an independent benchmark
+- [Using it from Rust](https://github.com/asemqaffaf/rust-fetch#using-it-from-rust): the same client as a Rust crate (no interceptors, upload progress or WebSockets there)
+- [npm package](https://www.npmjs.com/package/rust-fetch)

package/node.js

@@ -9,14 +9,70 @@
 // fetch() implements browser semantics (WHATWG streams) on top of the same
 // sockets and is considerably slower; this transport only moves bytes.
 // Retries, timeouts, validation and decoding stay in the Rust core.
+//
+// Where the native addon (rust-fetch-native.<platform>-<arch>.node) loads,
+// requests go through it instead: the same rules, implemented in Rust on
+// Tokio threads, so the JS thread only builds requests and decodes bodies.
 import { readFileSync } from 'node:fs';
 import http from 'node:http';
 import https from 'node:https';
+import { createRequire } from 'node:module';
 import zlib from 'node:zlib';
 import { initSync } from './rust_fetch.js';
 
 initSync({ module: readFileSync(new URL('./rust_fetch_bg.wasm', import.meta.url)) });
 
+/**
+ * The native addon, or undefined. RUST_FETCH_NATIVE overrides its path;
+ * anything that doesn't load (e.g. `0`) keeps the node:http transport.
+ */
+function loadNative() {
+  const path = process.env.RUST_FETCH_NATIVE ?? `./rust-fetch-native.${process.platform}-${process.arch}.node`;
+  try {
+    const addon = createRequire(import.meta.url)(path);
+    const extraCaCerts = process.env.NODE_EXTRA_CA_CERTS;
+    addon.configure({
+      zstd: typeof zlib.zstdDecompressSync === 'function',
+      rejectUnauthorized: process.env.NODE_TLS_REJECT_UNAUTHORIZED !== '0',
+      extraCaCerts: extraCaCerts ? readFileSync(extraCaCerts) : undefined,
+    });
+    return addon;
+  } catch {
+    return undefined;
+  }
+}
+
+const native = loadNative();
+
+// Node's default global agents open a socket for every request that finds no
+// idle one, but keep only 256 of them idle afterwards. Under a burst the rest
+// are closed and sit in TIME_WAIT, and once the ephemeral port range is used
+// up every connect fails with EADDRNOTAVAIL. A bounded pool that keeps all of
+// its sockets queues requests instead, reusing the same connections.
+const MAX_SOCKETS = 256;
+const POOL_OPTIONS = { keepAlive: true, scheduling: 'lifo', timeout: 5000, maxSockets: MAX_SOCKETS, maxFreeSockets: MAX_SOCKETS };
+const pools = new Map([
+  [http, new http.Agent(POOL_OPTIONS)],
+  [https, new https.Agent(POOL_OPTIONS)],
+]);
+// The options Node's own global agents are created with. Newer versions also
+// list unset ones (e.g. `proxyEnv: undefined` unless NODE_USE_ENV_PROXY is on).
+const NODE_AGENT_OPTIONS = { keepAlive: true, scheduling: 'lifo', timeout: 5000, noDelay: true, defaultPort: 443, protocol: 'https:' };
+
+/**
+ * The bounded pool while `globalAgent` is still Node's unbounded default;
+ * an agent the application installed (a proxy, TLS options, its own limits)
+ * is used as is.
+ */
+function agentFor(transport) {
+  const global = transport.globalAgent;
+  const isNodeDefault =
+    global.constructor === transport.Agent &&
+    global.maxSockets === Infinity &&
+    Object.entries(global.options).every(([key, value]) => value == null || NODE_AGENT_OPTIONS[key] === value);
+  return isNodeDefault ? pools.get(transport) : global;
+}
+
 const MAX_REDIRECTS = 20;
 const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
 const ACCEPT_ENCODING = typeof zlib.zstdDecompressSync === 'function' ? 'gzip, deflate, br, zstd' : 'gzip, deflate, br';
@@ -117,6 +173,36 @@ function ownedBytes(bytes) {
     : new Uint8Array(bytes);
 }
 
+/** Call a progress callback with `{ loaded, total }`, ignoring its exceptions */
+function report(callback, loaded, total) {
+  try {
+    callback({ loaded, total });
+  } catch {}
+}
+
+// Request bodies are written in chunks of this size when upload progress is reported
+const UPLOAD_CHUNK = 64 * 1024;
+
+/**
+ * Send the body and end the request. With `onProgress`, the body is written
+ * a chunk at a time, reporting each chunk once it has been handed to the OS.
+ */
+function writeBody(request, body, onProgress) {
+  if (!onProgress || !body) return request.end(body);
+  let loaded = 0;
+  const next = () => {
+    const chunk = body.subarray(loaded, loaded + UPLOAD_CHUNK);
+    request.write(chunk, (error) => {
+      if (error) return; // the request's 'error' event rejects
+      loaded += chunk.length;
+      report(onProgress, loaded, body.length);
+      if (loaded < body.length) next();
+      else request.end();
+    });
+  };
+  next();
+}
+
 function withoutHeaders(headers, names) {
   const copy = { ...headers };
   for (const name of names) delete copy[name];
@@ -126,7 +212,7 @@ function withoutHeaders(headers, names) {
 function send(state, method, url, headers, body, redirects, resolve, reject) {
   if (state.cancelled) return;
   const transport = url.protocol === 'https:' ? https : http;
-  const request = transport.request(url, { method, headers }, (response) => {
+  const request = transport.request(url, { method, headers, agent: agentFor(transport) }, (response) => {
     const status = response.statusCode;
     const location = response.headers.location;
 
@@ -165,10 +251,13 @@ function send(state, method, url, headers, body, redirects, resolve, reject) {
     const buffer = preallocated ? new Uint8Array(expected) : undefined;
     let received = 0;
     const chunks = [];
+    const onProgress = status >= 200 && status < 300 ? state.onDownloadProgress : undefined;
+    const total = Number.isSafeInteger(expected) ? expected : null;
     response.on('data', (chunk) => {
       if (buffer && received + chunk.length <= expected) buffer.set(chunk, received);
       else chunks.push(chunk);
       received += chunk.length;
+      if (onProgress) report(onProgress, received, total);
     });
     response.on('error', reject);
     // A socket closed mid-body may emit 'close' without 'end' (a settled promise ignores this)
@@ -192,13 +281,13 @@ function send(state, method, url, headers, body, redirects, resolve, reject) {
     });
   });
   request.on('error', reject);
-  request.end(body);
+  writeBody(request, body, state.onUploadProgress);
   state.request = request;
 }
 
 /**
  * One attempt, called by the Rust core with
- * `{ method, url, headers, body?, timeout?, bodyType }`. Resolves to the
+ * `{ method, url, headers, body?, timeout?, bodyType, onUploadProgress?, onDownloadProgress? }`. Resolves to the
  * finished `{ status, statusText, ok, url, headers, body }` (the core fills
  * in statusText). Rejects with code RUST_FETCH_TIMEOUT or RUST_FETCH_PARSE,
  * or any other error for network failures.
@@ -208,7 +297,16 @@ function send(state, method, url, headers, body, redirects, resolve, reject) {
  * AbortSignal into every request.
  */
 function nodeTransport(request) {
-  const state = { cancelled: false, request: undefined, bodyType: request.bodyType ?? AUTO };
+  // The native transport makes its own connections, so only where the
+  // node:http transport would use its own pool too, not an installed agent.
+  // Progress callbacks run on this thread, so those requests stay here.
+  const { onUploadProgress, onDownloadProgress } = request;
+  const transport = request.url.startsWith('https:') ? https : request.url.startsWith('http:') ? http : undefined;
+  if (native && transport && !onUploadProgress && !onDownloadProgress && agentFor(transport) === pools.get(transport)) {
+    return nativeTransport(request);
+  }
+
+  const state = { cancelled: false, request: undefined, bodyType: request.bodyType ?? AUTO, onUploadProgress, onDownloadProgress };
   let timer;
   const promise = new Promise((resolve, reject) => {
     if (request.timeout > 0) {
@@ -225,16 +323,11 @@ function nodeTransport(request) {
       clearTimeout(timer);
       return reject(error);
     }
-    const headers = { ...request.headers };
-    headers['accept'] ??= '*/*';
-    headers['accept-encoding'] ??= ACCEPT_ENCODING;
-    headers['user-agent'] ??= 'rust-fetch';
-    if (request.body) headers['content-length'] ??= String(request.body.length);
     const settle = (fn) => (value) => {
       clearTimeout(timer);
       fn(value);
     };
-    send(state, request.method, url, headers, request.body, 0, settle(resolve), settle(reject));
+    send(state, request.method, url, withDefaultHeaders(request), request.body, 0, settle(resolve), settle(reject));
   });
   const cancel = () => {
     state.cancelled = true;
@@ -251,6 +344,46 @@ function nodeTransport(request) {
   return finished;
 }
 
+/** The request's headers plus fetch()-like defaults */
+function withDefaultHeaders(request) {
+  const headers = { ...request.headers };
+  headers['accept'] ??= '*/*';
+  headers['accept-encoding'] ??= ACCEPT_ENCODING;
+  headers['user-agent'] ??= 'rust-fetch';
+  if (request.body) headers['content-length'] ??= String(request.body.length);
+  return headers;
+}
+
+let nextNativeId = 0;
+
+/** `nodeTransport` through the native addon: same contract, same rules */
+function nativeTransport(request) {
+  const id = (nextNativeId = (nextNativeId + 1) >>> 0);
+  const headers = withDefaultHeaders(request);
+  // Names and values alternating; a repeated header is sent once per value
+  const pairs = [];
+  for (const name in headers) {
+    const value = headers[name];
+    if (Array.isArray(value)) for (const item of value) pairs.push(name, item);
+    else pairs.push(name, value);
+  }
+  const bodyType = request.bodyType ?? AUTO;
+  const finished = native
+    .send({ id, method: request.method, url: request.url, headers: pairs, body: request.body, timeout: request.timeout })
+    .then((response) => {
+      if (response.error != null) throw coded(new Error(response.error), response.code);
+      const headers = {};
+      const raw = response.headers;
+      for (let i = 0; i < raw.length; i += 2) {
+        const name = raw[i];
+        headers[name] = Object.hasOwn(headers, name) ? `${headers[name]}, ${raw[i + 1]}` : raw[i + 1];
+      }
+      return finishResponse({ status: response.status, url: response.url, headers, body: ownedBytes(response.body) }, bodyType);
+    });
+  finished.cancel = () => native.cancel(id);
+  return finished;
+}
+
 /** The response object handed to the Rust core (which fills in statusText) */
 function finishResponse({ status, url, headers, body }, bodyType) {
   const ok = status >= 200 && status < 300;

package/package.json

@@ -4,8 +4,8 @@
   "collaborators": [
     "Asem Qaffaf <asem@qaffaf.com>"
   ],
-  "description": "A reliable HTTP client for JavaScript and TypeScript, written in Rust and compiled to WebAssembly: timeouts, retries, typed errors and interceptors, faster than fetch() in Node.js",
-  "version": "2.1.0",
+  "description": "Resilient HTTP client for JavaScript, TypeScript and Rust: fetch() with timeouts, retries, typed errors, interceptors, upload and download progress, and WebSockets, from one Rust core compiled to WebAssembly for browsers and Node.js",
+  "version": "2.2.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",
@@ -17,20 +17,46 @@
     "rust_fetch.js",
     "rust_fetch.d.ts",
     "node.js",
+    "llms.txt",
     "LICENSE-MIT",
     "LICENSE-APACHE"
   ],
   "main": "rust_fetch.js",
+  "homepage": "https://github.com/asemqaffaf/rust-fetch#readme",
   "types": "rust_fetch.d.ts",
   "sideEffects": [
     "./snippets/*"
   ],
   "keywords": [
-    "wasm",
     "http",
-    "client",
+    "http-client",
     "fetch",
-    "webassembly"
+    "fetch-api",
+    "request",
+    "rest",
+    "api-client",
+    "axios-alternative",
+    "retry",
+    "retries",
+    "backoff",
+    "timeout",
+    "interceptors",
+    "typed-errors",
+    "abortcontroller",
+    "upload-progress",
+    "download-progress",
+    "streaming",
+    "websocket",
+    "websockets",
+    "reconnect",
+    "typescript",
+    "nodejs",
+    "browser",
+    "isomorphic",
+    "webassembly",
+    "wasm",
+    "rust",
+    "napi"
   ],
   "exports": {
     ".": {
@@ -48,7 +74,6 @@
   "engines": {
     "node": ">=20"
   },
-  "homepage": "https://github.com/asemqaffaf/rust-fetch#readme",
   "bugs": {
     "url": "https://github.com/asemqaffaf/rust-fetch/issues"
   }

package/rust_fetch.d.ts

@@ -50,6 +50,12 @@ export interface DownloadProgress {
     total: number | null;
 }
 
+/** Upload progress: bytes of the request body sent so far, and the body's size. */
+export interface UploadProgress {
+    loaded: number;
+    total: number;
+}
+
 export interface RetryOptions {
     /** Maximum number of retries after the first attempt. Default: 3 */
     maxRetries?: number;
@@ -93,6 +99,12 @@ export interface RequestOptions {
     signal?: AbortSignal;
     /** Called after each received chunk of a successful response */
     onDownloadProgress?: (progress: DownloadProgress) => void;
+    /**
+     * Called as the request body is sent; starts again from 0 if the request is retried.
+     * Browsers send these requests with `XMLHttpRequest` (cross-origin ones are preflighted).
+     * Can't be combined with `responseType: 'stream'`.
+     */
+    onUploadProgress?: (progress: UploadProgress) => void;
 }
 
 export interface FetchInit extends RequestOptions {
@@ -155,6 +167,70 @@ export interface RustFetchError extends Error {
 
 
 
+/** Reconnection after a connection fails or drops, with jittered exponential backoff. */
+export interface ReconnectOptions {
+    /** Reconnection attempts in a row before giving up; reset once a connection opens. Default: unlimited */
+    maxRetries?: number;
+    /** Delay before the first attempt, in ms. Default: 1000 */
+    initialDelayMs?: number;
+    /** Upper bound for any delay, in ms. Default: 30000 */
+    maxDelayMs?: number;
+    /** Exponential backoff multiplier. Default: 2 */
+    multiplier?: number;
+}
+
+/** What `send()` accepts; use `sendJson()` for other values. */
+export type WebSocketData = string | ArrayBuffer | ArrayBufferView | Blob;
+
+export type WebSocketState = 'connecting' | 'open' | 'reconnecting' | 'closing' | 'closed';
+
+export interface WebSocketCloseInfo {
+    code: number;
+    reason: string;
+    wasClean: boolean;
+}
+
+export interface WebSocketReconnectInfo {
+    /** 1 for the first attempt after a failure */
+    attempt: number;
+    delayMs: number;
+    /** Why the previous connection failed or dropped */
+    error: RustFetchError;
+}
+
+export interface WebSocketOptions {
+    /** Subprotocols to offer */
+    protocols?: string | string[];
+    params?: QueryParams;
+    /**
+     * Handshake headers, merged over the client's headers. Node.js only: browsers don't allow
+     * WebSocket headers, so there this rejects with an `InvalidInputError` (client headers are skipped).
+     */
+    headers?: HeadersLike;
+    /** Time allowed for each connection attempt, in ms. `0` disables it. Default: the client's `timeoutMs` */
+    timeoutMs?: number;
+    /**
+     * Reconnect when a connection fails or drops unexpectedly (close codes 1001, 1006, 1011-1014):
+     * `true` for the defaults, a maximum number of attempts in a row, or options. Default: off
+     */
+    reconnect?: boolean | number | ReconnectOptions;
+    /** Closes the connection and stops reconnecting when aborted */
+    signal?: AbortSignal;
+    /** `auto` (default): text messages as strings, binary ones as `Uint8Array`. `json`: text messages parsed as JSON */
+    messageType?: 'auto' | 'json';
+    /** Called each time a connection opens, including after reconnecting */
+    onOpen?: () => void;
+    onMessage?: (data: any) => void;
+    /** Called on every failure: a failed or timed-out attempt, an unexpected drop, a message that isn't JSON */
+    onError?: (error: RustFetchError) => void;
+    /** Called before waiting to reconnect */
+    onReconnect?: (info: WebSocketReconnectInfo) => void;
+    /** Called once, when the connection is closed for good */
+    onClose?: (info: WebSocketCloseInfo) => void;
+}
+
+
+
 export class IntoUnderlyingByteSource {
     private constructor();
     free(): void;
@@ -205,7 +281,7 @@ export class WasmClient {
     /**
      * Make a DELETE request
      */
-    delete(url: string, options?: RequestOptions | null): Promise<HttpResponse>;
+    delete<T = any>(url: string, options?: RequestOptions | null): Promise<HttpResponse<T>>;
     /**
      * Remove an interceptor; returns whether it was registered
      */
@@ -213,15 +289,15 @@ export class WasmClient {
     /**
      * Make a request described by a `fetch`-style init object
      */
-    fetch(url: string, init?: FetchInit | null): Promise<HttpResponse>;
+    fetch<T = any>(url: string, init?: FetchInit | null): Promise<HttpResponse<T>>;
     /**
      * Make a GET request
      */
-    get(url: string, options?: RequestOptions | null): Promise<HttpResponse>;
+    get<T = any>(url: string, options?: RequestOptions | null): Promise<HttpResponse<T>>;
     /**
      * Make a HEAD request
      */
-    head(url: string, options?: RequestOptions | null): Promise<HttpResponse>;
+    head<T = any>(url: string, options?: RequestOptions | null): Promise<HttpResponse<T>>;
     /**
      * Create a new client
      */
@@ -229,31 +305,83 @@ export class WasmClient {
     /**
      * Make a PATCH request; the body is taken from `init.body`
      */
-    patch(url: string, init?: FetchInit | null): Promise<HttpResponse>;
+    patch<T = any>(url: string, init?: FetchInit | null): Promise<HttpResponse<T>>;
     /**
      * Make a PATCH request with a JSON body
      */
-    patch_json(url: string, body: any, options?: RequestOptions | null): Promise<HttpResponse>;
+    patch_json<T = any>(url: string, body: any, options?: RequestOptions | null): Promise<HttpResponse<T>>;
     /**
      * Make a POST request; the body is taken from `init.body`
      */
-    post(url: string, init?: FetchInit | null): Promise<HttpResponse>;
+    post<T = any>(url: string, init?: FetchInit | null): Promise<HttpResponse<T>>;
     /**
      * Make a POST request with a JSON body
      */
-    post_json(url: string, body: any, options?: RequestOptions | null): Promise<HttpResponse>;
+    post_json<T = any>(url: string, body: any, options?: RequestOptions | null): Promise<HttpResponse<T>>;
     /**
      * Make a PUT request; the body is taken from `init.body`
      */
-    put(url: string, init?: FetchInit | null): Promise<HttpResponse>;
+    put<T = any>(url: string, init?: FetchInit | null): Promise<HttpResponse<T>>;
     /**
      * Make a PUT request with a JSON body
      */
-    put_json(url: string, body: any, options?: RequestOptions | null): Promise<HttpResponse>;
+    put_json<T = any>(url: string, body: any, options?: RequestOptions | null): Promise<HttpResponse<T>>;
     /**
      * Make a request with any method, headers and body
      */
-    request(method: string, url: string, headers?: HeadersLike | null, body?: RequestBody | null, options?: RequestOptions | null): Promise<HttpResponse>;
+    request<T = any>(method: string, url: string, headers?: HeadersLike | null, body?: RequestBody | null, options?: RequestOptions | null): Promise<HttpResponse<T>>;
+    /**
+     * Open a WebSocket connection. Relative URLs are resolved against the
+     * base URL, with `http:` and `https:` becoming `ws:` and `wss:`.
+     */
+    websocket(url: string, options?: WebSocketOptions | null): WebSocketConnection;
+}
+
+/**
+ * A WebSocket connection created by `WasmClient.websocket()`
+ */
+export class WebSocketConnection {
+    private constructor();
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Close the connection and stop reconnecting. `code` is 1000 (the
+     * default) or 3000-4999; `reason` is at most 123 bytes of UTF-8.
+     */
+    close(code?: number | null, reason?: string | null): void;
+    /**
+     * Send a value as JSON text
+     */
+    sendJson(value: any): void;
+    /**
+     * Send a message. Before the connection opens (or while reconnecting),
+     * messages are queued and sent once it does.
+     */
+    send(data: WebSocketData): void;
+    /**
+     * Bytes queued by the socket but not yet sent
+     */
+    readonly bufferedAmount: number;
+    /**
+     * Resolves with the close code and reason once the connection is closed for good
+     */
+    readonly closed: Promise<WebSocketCloseInfo>;
+    /**
+     * Resolves when the first connection opens; rejects if it never does
+     */
+    readonly opened: Promise<void>;
+    /**
+     * The subprotocol the server selected, or `""`
+     */
+    readonly protocol: string;
+    /**
+     * `connecting`, `open`, `reconnecting`, `closing` or `closed`
+     */
+    readonly state: WebSocketState;
+    /**
+     * The connection URL (`ws:` or `wss:`)
+     */
+    readonly url: string;
 }
 
 /**
@@ -312,6 +440,7 @@ export interface InitOutput {
     readonly __wbg_intounderlyingsink_free: (a: number, b: number) => void;
     readonly __wbg_intounderlyingsource_free: (a: number, b: number) => void;
     readonly __wbg_wasmclient_free: (a: number, b: number) => void;
+    readonly __wbg_websocketconnection_free: (a: number, b: number) => void;
     readonly create_client: () => [number, number, number];
     readonly fetch_json: (a: number, b: number) => any;
     readonly fetch_json_promise: (a: number, b: number) => any;
@@ -347,9 +476,20 @@ export interface InitOutput {
     readonly wasmclient_put: (a: number, b: number, c: number, d: number) => any;
     readonly wasmclient_put_json: (a: number, b: number, c: number, d: any, e: number) => any;
     readonly wasmclient_request: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => any;
+    readonly wasmclient_websocket: (a: number, b: number, c: number, d: number) => [number, number, number];
+    readonly websocketconnection_buffered_amount: (a: number) => number;
+    readonly websocketconnection_close: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly websocketconnection_closed: (a: number) => any;
+    readonly websocketconnection_opened: (a: number) => any;
+    readonly websocketconnection_protocol: (a: number) => [number, number];
+    readonly websocketconnection_send: (a: number, b: any) => [number, number];
+    readonly websocketconnection_sendJson: (a: number, b: any) => [number, number];
+    readonly websocketconnection_state: (a: number) => any;
+    readonly websocketconnection_url: (a: number) => [number, number];
     readonly wasm_bindgen_6b82e471f4a4091b___convert__closures_____invoke___js_sys_6c670598d03a71fc___Function_fn_wasm_bindgen_6b82e471f4a4091b___JsValue_____wasm_bindgen_6b82e471f4a4091b___sys__Undefined___js_sys_6c670598d03a71fc___Function_fn_wasm_bindgen_6b82e471f4a4091b___JsValue_____wasm_bindgen_6b82e471f4a4091b___sys__Undefined_______true_: (a: number, b: number, c: any, d: any) => void;
     readonly wasm_bindgen_6b82e471f4a4091b___convert__closures_____invoke___wasm_bindgen_6b82e471f4a4091b___JsValue__core_37ee0ce0c4cd57d5___result__Result_____wasm_bindgen_6b82e471f4a4091b___JsError___true_: (a: number, b: number, c: any) => [number, number];
     readonly wasm_bindgen_6b82e471f4a4091b___convert__closures_____invoke___wasm_bindgen_6b82e471f4a4091b___JsValue______true_: (a: number, b: number, c: any) => void;
+    readonly wasm_bindgen_6b82e471f4a4091b___convert__closures_____invoke___web_sys_697c1c02b79bdc2c___features__gen_ProgressEvent__ProgressEvent______true_: (a: number, b: number, c: any) => void;
     readonly wasm_bindgen_6b82e471f4a4091b___convert__closures_____invoke_______true_: (a: number, b: number) => void;
     readonly __wbindgen_malloc: (a: number, b: number) => number;
     readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
@@ -358,6 +498,7 @@ export interface InitOutput {
     readonly __wbindgen_externrefs: WebAssembly.Table;
     readonly __wbindgen_destroy_closure: (a: number, b: number) => void;
     readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
     readonly __wbindgen_start: () => void;
 }