rust-fetch 1.0.4 → 2.0.0

package/README.md

@@ -1,267 +1,445 @@
 # rust-fetch
 
 [![npm version](https://img.shields.io/npm/v/rust-fetch.svg)](https://www.npmjs.com/package/rust-fetch)
-[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](LICENSE)
+[![CI](https://github.com/asemqaffaf/rust-fetch/actions/workflows/rust.yml/badge.svg)](https://github.com/asemqaffaf/rust-fetch/actions/workflows/rust.yml)
+[![Coverage: 100% (enforced)](https://img.shields.io/badge/coverage-100%25%20enforced-brightgreen.svg)](https://github.com/asemqaffaf/rust-fetch/actions/workflows/rust.yml)
+[![codecov](https://codecov.io/gh/asemqaffaf/rust-fetch/branch/main/graph/badge.svg)](https://codecov.io/gh/asemqaffaf/rust-fetch)
+[![License: MIT OR Apache-2.0](https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue.svg)](#license)
 [![WebAssembly](https://img.shields.io/badge/WebAssembly-654FF0?style=flat&logo=WebAssembly&logoColor=white)](https://webassembly.org/)
 
-A high-performance, world-class HTTP client for JavaScript/TypeScript powered by WebAssembly. Built with Rust for blazing-fast, memory-safe HTTP operations in both browser and Node.js environments.
+**A reliable HTTP client for JavaScript and TypeScript, written in Rust and compiled to WebAssembly.**
+It runs in browsers, Web Workers and Node.js, and adds what `fetch()` leaves to you: timeouts, retries with backoff, typed errors, interceptors, multipart uploads and download progress.
 
-## 🚀 Features
+```js
+import { WasmClient } from 'rust-fetch';
 
-- **Type-safe HTTP Client**: Builder pattern for constructing requests with compile-time safety
-- **Comprehensive Error Handling**: Detailed error types with context and proper error chaining
-- **Automatic Retries**: Built-in retry logic with exponential backoff for transient failures
-- **Multiple Response Formats**: Support for JSON, text, and binary responses
-- **Platform Optimized**: Specific optimizations for both WASM and native targets
-- **Developer Friendly**: Clean API with both simple functions and advanced client builders
-- **Backward Compatible**: Maintains compatibility with legacy API while providing modern alternatives
-
-## 📦 Installation
-
-```bash
-npm install rust-fetch
+const api = new WasmClient({ baseUrl: 'https://api.example.com/v1', timeoutMs: 10_000, retries: 3 });
+const { body: user } = await api.get('/users/42');
 ```
 
-or
+## Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Guide](#guide): [client options](#client-options) · [requests](#making-requests) · [bodies](#request-bodies) · [responses](#responses) · [errors](#errors) · [timeouts](#timeouts) · [retries](#retries) · [cancellation](#cancellation) · [streaming](#streaming) · [progress](#download-progress) · [uploads](#file-uploads) · [interceptors](#interceptors) · [TypeScript](#typescript)
+- [Legacy functions](#legacy-functions)
+- [Using it from Rust](#using-it-from-rust)
+- [Performance](#performance)
+- [Roadmap](#roadmap)
+- [Upgrading to 2.0](#upgrading-to-20)
+- [Development](#development)
+- [License](#license)
+
+## Features
+
+- **Works everywhere**: browsers (directly or through bundlers like Vite and webpack), Web Workers and Node.js 20+. In Node.js there's no setup: `import` and go.
+- **Timeouts** per attempt, covering the response body, not just the headers. The default is 30 s.
+- **Retries** with exponential backoff and jitter. `Retry-After` is honoured, and POST/PATCH aren't retried unless you opt in.
+- **Typed errors**: every rejection is a real `Error` with a `kind` (`HttpError`, `TimeoutError`, …) and details like `status` and `body`.
+- **Cancellation** with `AbortSignal`, including during retry backoff and while streaming.
+- **Request bodies** from strings, bytes, `Blob`/`File`, `FormData` (multipart with files), `URLSearchParams`, or JSON.
+- **Response decoding** by `Content-Type` (including `application/*+json`), or forced to `json`, `text`, `binary` or `stream`.
+- **Streaming** responses as a `ReadableStream`, and **download progress** callbacks.
+- **Interceptors** for requests and responses, e.g. auth headers and token refresh.
+- **TypeScript** definitions for the whole API.
+- **Tested**: 100% line coverage of the Rust core, plus wasm tests and end-to-end tests of the packed npm package. See [Development](#development).
+
+## Installation
 
 ```bash
-yarn add rust-fetch
+npm install rust-fetch
 ```
 
-## 🔧 Usage
+## Quick start
 
-### Simple API
+**Node.js** (20+): the WebAssembly module loads on import.
 
-For quick and easy HTTP requests:
+```js
+import { WasmClient } from 'rust-fetch';
 
-### WASM Client Example
-How to use the imported `WasmClient` to make HTTP requests from the browser or Node.js environment:
+const client = new WasmClient();
+const res = await client.get('https://jsonplaceholder.typicode.com/todos/1');
+console.log(res.status, res.body.title);
+```
 
-#### Simple GET Request
-Here's how to make a simple GET request using `WasmClient`:
+**Browsers and bundlers**: call `init()` once before the first request. It downloads and compiles the `.wasm` file.
 
-```javascript
+```js
 import init, { WasmClient } from 'rust-fetch';
 
 await init();
-
 const client = new WasmClient();
-
-client.get('https://jsonplaceholder.typicode.com/posts/1')
-    .then(response => console.log(response))
-    .catch(error => console.error('Error:', error));
 ```
 
-#### POST Request with JSON
-Here's how to make a POST request with a JSON body:
+`init()` is safe to call more than once, and calling it in Node.js is harmless, so shared code can always call it.
 
-```javascript
-const data = { title: 'foo', body: 'bar', userId: 1 };
+## Guide
 
-client.post_json('https://jsonplaceholder.typicode.com/posts', data)
-    .then(response => console.log(response))
-    .catch(error => console.error('Error:', error));
-```
+### Client options
 
-### Using Fetch Functions
+```ts
+const client = new WasmClient({
+  baseUrl: 'https://api.example.com/v1', // relative request URLs are appended to this
+  headers: { Authorization: 'Bearer …' }, // sent with every request
+  timeoutMs: 10_000,                      // per attempt; 0 disables. Default: 30000
+  retries: 3,                             // or a RetryOptions object, see Retries
+});
+```
 
-```javascript
-import init, { fetch_json, fetch_text } from 'rust-fetch';
+Invalid options throw an `InvalidInputError` right away, from the constructor.
 
-// Initialize WASM module
-await init();
+### Making requests
 
-// Fetch JSON data
-try {
-  const data = await fetch_json('https://api.example.com/data');
-  console.log('JSON data:', data);
-} catch (error) {
-  console.error('Error fetching JSON:', error);
-}
+| Method | Use |
+| --- | --- |
+| `get(url, options?)`, `head(url, options?)`, `delete(url, options?)` | Requests without a body |
+| `post(url, init?)`, `put(url, init?)`, `patch(url, init?)` | `init.body` is the body; any other [request option](#request-options) can go next to it |
+| `fetch(url, init?)` | `fetch`-style, with `init.method` (default `GET`) |
+| `post_json`, `put_json`, `patch_json(url, body, options?)` | Always send `body` as JSON |
+| `request(method, url, headers?, body?, options?)` | Fully positional |
 
-// Fetch text/HTML
-try {
-  const html = await fetch_text('https://example.com');
-  console.log('HTML content:', html);
-} catch (error) {
-  console.error('Error fetching HTML:', error);
-}
+```js
+await client.post('/users', { body: { name: 'Zoë' } });
+await client.get('/search', { params: { q: 'rust wasm', page: 2, tag: ['a', 'b'] } }); // ?q=rust+wasm&page=2&tag=a&tag=b
+await client.fetch('/users/1', { method: 'DELETE', headers: { 'X-Reason': 'cleanup' } });
 ```
 
-### Advanced Client API
+Relative URLs need a `baseUrl`. In a browser page without one, they resolve against the page URL. Absolute URLs always win over `baseUrl`. `TRACE` and `CONNECT` are rejected because `fetch()` forbids them.
+
+#### Request options
 
-For more control and enhanced configurations, use the `fetch_with_options` to fine-tune HTTP requests:
+| Option | Type | Description |
+| --- | --- | --- |
+| `headers` | object, `Headers`, `Map` or `[name, value][]` | Override client headers with the same name. Numbers and booleans are converted to strings. |
+| `params` | object or `URLSearchParams` | Appended to the query string. Arrays repeat the key; `null`/`undefined` are skipped. |
+| `timeoutMs` | number | Overrides the client timeout; `0` disables it |
+| `responseType` | `'auto'` \| `'json'` \| `'text'` \| `'binary'` \| `'stream'` | See [Responses](#responses) |
+| `signal` | `AbortSignal` | See [Cancellation](#cancellation) |
+| `onDownloadProgress` | `({ loaded, total }) => void` | See [Download progress](#download-progress) |
 
-#### Using Advanced Options
-You can specify HTTP method, headers, and body:
+### Request bodies
 
-```javascript
-import { fetch_with_options } from 'rust-fetch';
+The body's type decides how it's sent. A `Content-Type` header you set yourself is always kept, except for `FormData`, which needs its own boundary.
 
-const url = 'https://jsonplaceholder.typicode.com/posts';
-const method = 'POST';
-const headers = { 'Content-Type': 'application/json' };
-const body = JSON.stringify({ userId: 1, title: 'foo', body: 'bar' });
+| Body | Sent as | Default `Content-Type` |
+| --- | --- | --- |
+| `string` | as-is | `text/plain` |
+| `Uint8Array`, `ArrayBuffer`, `DataView`, `Buffer` | bytes | `application/octet-stream` |
+| `Blob` / `File` | bytes | the blob's `type` |
+| `FormData` | `multipart/form-data`, including files | `multipart/form-data; boundary=…` |
+| `URLSearchParams` | form-encoded | `application/x-www-form-urlencoded;charset=UTF-8` |
+| anything else (objects, arrays, numbers, booleans) | `JSON.stringify` | `application/json` |
 
-fetch_with_options(url, method, headers, body)
-    .then(response => console.log(response))
-    .catch(error => console.error('Error:', error));
+`null` and `undefined` mean no body. The `*_json` methods are the exception: they always send JSON, so `post_json(url, null)` sends `null`. `ReadableStream` request bodies aren't supported; send a `Blob` or bytes instead.
+
+### Responses
+
+Successful (2xx) requests resolve to:
+
+```ts
+interface HttpResponse<T = any> {
+  status: number;          // 200
+  statusText: string;      // "OK"
+  ok: boolean;             // always true: non-2xx responses reject with an HttpError
+  url: string;             // final URL after redirects
+  headers: Record<string, string>; // lower-cased names; repeated headers joined with ", "
+  body: T;
+}
 ```
 
-## 🏗️ Architecture
+With the default `responseType: 'auto'`, `body` is:
+- **parsed JSON** for `application/json` and `application/*+json` (e.g. `problem+json`), falling back to text if it isn't valid JSON
+- **a string** for `text/*`, XML, JavaScript and form-encoded responses
+- **a `Uint8Array`** for anything else
+- **`null`** when the body is empty (e.g. `204` or `HEAD`)
 
-The library is organized into several modules:
+Force a type with `responseType: 'json'` (fails with a `ParseError` if the body isn't JSON), `'text'`, `'binary'` or `'stream'`. JSON is parsed by the JS engine's `JSON.parse`, exactly like `Response.json()`.
 
-- **`error`**: Comprehensive error types with detailed context
-- **`types`**: Core types like `Method`, `Headers`, `Response`, etc.
-- **`client`**: The main HTTP client with builder pattern
-- **`http`**: High-level convenience functions for common use cases
+### Errors
 
-### Error Handling
+Every rejection is an `Error` whose `name` and `kind` are one of:
 
-The library provides rich error types that preserve context:
+| `kind` | When | Extra fields |
+| --- | --- | --- |
+| `HttpError` | Non-2xx response | `status`, `statusText`, `body` (full response body as text) |
+| `TimeoutError` | An attempt exceeded `timeoutMs` | `timeoutMs` |
+| `NetworkError` | DNS, connection, TLS or CORS failure, or a body cut off mid-transfer | |
+| `CancelledError` | The `signal` was aborted | |
+| `InvalidInputError` | Bad URL, method, header, option or body. Rejected before anything is sent. | `parameter` |
+| `ParseError` | `responseType: 'json'` and the body isn't JSON | |
+| `JsInteropError` | Unexpected JS ↔ Wasm conversion failure | |
 
-```javascript
+```js
 try {
-  const data = await fetch_json(url);
-  console.log('Success:', data);
+  await client.get('/users/9');
 } catch (error) {
-  // Error handling with detailed context
-  console.error('Failed to fetch:', error.message);
+  if (error.kind === 'HttpError' && error.status === 404) {
+    // not found
+  } else if (error.kind === 'TimeoutError') {
+    console.warn(`gave up after ${error.timeoutMs} ms`);
+  } else {
+    throw error;
+  }
 }
 ```
 
-## API Reference
+Long error bodies (such as an HTML error page) are truncated to 200 characters in `message`. `error.body` always has the full text.
 
-### HTTP Functions
+### Timeouts
 
-#### `fetch_json(url: string): Promise<any>`
-Fetches JSON data from the specified URL and returns it as a JavaScript object.
+`timeoutMs` limits each attempt, from sending the request to receiving the last byte of the body. When retries are on, each attempt gets the full timeout. For `responseType: 'stream'`, the timeout covers only the wait for the headers; after that, reading the stream is up to you.
 
-```javascript
-import { fetch_json } from 'rust-fetch';
+### Retries
 
-const data = await fetch_json('https://jsonplaceholder.typicode.com/todos/1');
+Retries are off by default. `retries: 3` enables them with these defaults; pass an object to change them:
+
+```ts
+new WasmClient({
+  retries: {
+    maxRetries: 3,          // retries after the first attempt
+    initialDelayMs: 100,    // first backoff
+    maxDelayMs: 10_000,     // cap for any delay, including Retry-After
+    multiplier: 2,          // exponential backoff: 100, 200, 400 … ms, each randomized to 50–100%
+    retryOn: [408, 429, 500, 502, 503, 504],
+    retryOnNetworkError: true,
+    retryOnTimeout: true,
+    retryNonIdempotent: false, // set to true to also retry POST and PATCH
+  },
+});
 ```
 
-#### `fetch_text(url: string): Promise<string>`
-Fetches text/HTML content from the specified URL and returns it as a string.
+- A `Retry-After` header in seconds is honoured, capped at `maxDelayMs`.
+- POST and PATCH aren't retried by default. The server may already have acted on a failed attempt, so retrying can duplicate work.
+- `InvalidInputError`, `ParseError` and unlisted statuses are never retried.
 
-```javascript
-import { fetch_text } from 'rust-fetch';
+### Cancellation
 
-const html = await fetch_text('https://example.com');
+```js
+const controller = new AbortController();
+const promise = client.get('/report', { signal: controller.signal });
+controller.abort(); // rejects with a CancelledError
+
+await client.get('/report', { signal: AbortSignal.timeout(5_000) }); // total deadline, including retries
 ```
 
-#### `fetch_with_options(url: string, method: string, headers: object, body?: string): Promise<object>`
-Advanced fetch function with full control over the request.
+Aborting cancels the underlying `fetch`, any pending retry delay, and a body being streamed.
+
+### Streaming
 
-```javascript
-import { fetch_with_options } from 'rust-fetch';
+`responseType: 'stream'` resolves as soon as the headers arrive. `body` is then a `ReadableStream<Uint8Array>`:
 
-const response = await fetch_with_options(
-    'https://api.example.com/users',
-    'POST',
-    { 'Content-Type': 'application/json' },
-    JSON.stringify({ name: 'John Doe' })
-);
+```js
+const res = await client.get('/export.csv', { responseType: 'stream' });
+for await (const chunk of res.body) {
+  process(chunk); // Uint8Array
+}
 ```
 
-### WasmClient Class
+`for await` over a stream works in Node.js, Chrome and Firefox. Safari doesn't support it yet, so use `res.body.getReader()` there. Retries apply until the headers arrive, and error statuses still reject with an `HttpError`.
 
-#### `new WasmClient()`
-Creates a new HTTP client instance.
+### Download progress
 
-```javascript
-const client = new WasmClient();
+```js
+await client.get('/video.mp4', {
+  responseType: 'binary',
+  onDownloadProgress: ({ loaded, total }) => {
+    console.log(total ? `${Math.round((loaded / total) * 100)}%` : `${loaded} bytes`);
+  },
+});
 ```
 
-#### `client.get(url: string): Promise<object>`
-Performs a GET request.
+The callback runs after each chunk of a successful response, including streamed ones. `total` comes from `Content-Length` and is `null` when the server doesn't send it. Exceptions thrown by the callback are ignored.
+
+Upload progress isn't available, because `fetch()` doesn't report it.
 
-```javascript
-const response = await client.get('https://api.example.com/data');
+### File uploads
+
+Pass a `FormData` and it's sent as `multipart/form-data`, files included:
+
+```js
+const form = new FormData();
+form.append('title', 'Quarterly report');
+form.append('file', fileInput.files[0]); // or new File([bytes], 'report.pdf', { type: 'application/pdf' })
+await client.post('/upload', { body: form });
 ```
 
-#### `client.post_json(url: string, body: object): Promise<object>`
-Performs a POST request with JSON body.
+A single `Blob` or `File` body is sent as raw bytes with the blob's type.
+
+### Interceptors
+
+```js
+// Add a header to every request (may be async)
+client.addRequestInterceptor((request) => {
+  request.headers.authorization = `Bearer ${getToken()}`;
+  // mutate in place, or return a new { method, url, headers, body }
+});
+
+// Resolve to the body instead of the whole response
+client.addResponseInterceptor((response) => response.body);
 
-```javascript
-const response = await client.post_json('https://api.example.com/users', {
-    name: 'Jane Doe',
-    email: 'jane@example.com'
+// Report failures, then keep rejecting
+client.addResponseInterceptor(undefined, (error) => {
+  reportError(error);
+  throw error;
 });
 ```
 
+An `onRejected` handler can also recover by returning a value, for example the result of retrying the request after refreshing a token.
+
+- Request interceptors run in order before each request. They see `{ method, url, headers, body }`, where `headers` holds the per-request headers. Client default headers are added afterwards, and a request header with the same name wins.
+- Response interceptors chain like `promise.then(onFulfilled, onRejected)`. Their return values are what the call resolves to. Throw to reject.
+- `addRequestInterceptor` and `addResponseInterceptor` return an id for `ejectInterceptor(id)`. `clearInterceptors()` removes all of them.
+- A request uses the interceptors registered when it started.
+
+### TypeScript
 
-## Performance Considerations
+Type definitions ship with the package and need TypeScript 5.2 or newer. Besides `WasmClient`, it exports the option and result types `ClientOptions`, `RequestOptions`, `FetchInit`, `RetryOptions`, `HttpResponse`, `RustFetchError`, `DownloadProgress` and `InterceptedRequest`.
 
-- The WASM module adds a small overhead for initialization (~100-200ms on first load)
-- Once loaded, HTTP operations benefit from Rust's efficient memory management
-- Best suited for applications that make multiple HTTP requests or need predictable performance
+```ts
+import { WasmClient, type HttpResponse, type RustFetchError } from 'rust-fetch';
 
-## Browser Support
+interface User { id: number; name: string }
 
-- Chrome 57+
-- Firefox 52+
-- Safari 11+
-- Edge 16+
-- Node.js 14+
+const res: HttpResponse<User> = await client.get('/users/42');
+res.body.name; // string
 
-## Contributing
+try {
+  await client.get('/users/9');
+} catch (e) {
+  const error = e as RustFetchError;
+  if (error.kind === 'HttpError') console.log(error.status);
+}
+```
 
-Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
+## Legacy functions
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add some amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
+These standalone functions still work. Each call uses a default client: 30 s timeout, no retries.
 
-## License
+| Function | Resolves to |
+| --- | --- |
+| `fetch_json(url)` / `fetch_json_promise(url)` | Parsed JSON, whatever the `Content-Type`; `null` for an empty body |
+| `fetch_text(url)` | The body as a string |
+| `fetch_with_options(url, method, headers, body?)` | The full `HttpResponse` |
+| `create_client()` | `new WasmClient()` |
+| `fetch_wasm_json`, `fetch_wasm_map`, `fetch_wasm_api`, `fetch_wasm_html` | Deprecated aliases of `fetch_json` / `fetch_text` |
 
-This project is licensed under the ISC License - see the LICENSE file for details.
+## Using it from Rust
 
-## Troubleshooting
+The same client is a Rust library, for native code (on tokio) and for your own wasm crates:
 
-### WASM Module Not Loading
+```rust
+use rust_fetch::{Client, Multipart, types::RetryConfig};
+use std::time::Duration;
 
-If you encounter issues with the WASM module not loading:
+let client = Client::builder()
+    .base_url("https://api.example.com/v1")
+    .timeout(Duration::from_secs(10))
+    .retry_config(RetryConfig { max_retries: 3, ..Default::default() })
+    .build()?;
 
-1. Ensure your server supports the `application/wasm` MIME type
-2. Check that the WASM file is being served correctly
-3. Verify you're awaiting the `initWasm()` call before using any functions
+let user = client.get("users/42").await?;
+println!("{}", user.json().unwrap()["name"]);
 
-### CORS Issues
+let pdf: Vec<u8> = std::fs::read("report.pdf")?;
+let form = Multipart::new().text("title", "Report").file("file", "report.pdf", Some("application/pdf".into()), pdf);
+client.post("upload").multipart(&form).send().await?;
 
-When fetching from external APIs, ensure:
+let mut chunks = client.get_streaming("export.csv").await?.into_stream(); // a futures::Stream of Vec<u8>
+```
 
-1. The target server allows CORS requests
-2. You're using HTTPS URLs in production
-3. Consider using a proxy server for APIs that don't support CORS
+Request futures are `Send`, so you can `tokio::spawn` them. Progress callbacks (`on_download_progress`) must be `Send + Sync` on native targets.
 
-### Node.js Path Issues
+## Performance
 
-If you encounter path resolution issues in Node.js:
+rust-fetch makes its requests through the runtime's own `fetch()`, so the network work is the same as plain `fetch`. The extra cost comes from crossing the JS ↔ Wasm boundary and copying bodies. It is **not faster than native `fetch`**. Use it for the reliability features, not for speed.
 
-1. Ensure the package is installed correctly
-2. Check that the WASM file exists in `node_modules/rust-fetch/wasm-module/pkg/`
-3. Try reinstalling the package
+`npm run bench` (Node 22.13, Apple M1 Pro, local server):
 
-## Acknowledgments
+| Scenario | native `fetch` | rust-fetch | rust-fetch / native |
+| --- | ---: | ---: | ---: |
+| Small JSON, sequential | 5,465 req/s | 4,015 req/s | 73% |
+| Small JSON, 50 concurrent | 12,155 req/s | 6,035 req/s | 50% |
+| JSON 0.6 MB | 219 req/s | 212 req/s | 97% |
+| Binary 8 MB | 189 req/s | 147 req/s | 77% |
 
-- Built with [wasm-bindgen](https://github.com/rustwasm/wasm-bindgen)
-- Uses [reqwest](https://github.com/seanmonstar/reqwest) for HTTP operations
-- Inspired by the Rust and WebAssembly community
+The overhead per request is a fraction of a millisecond, which matters little once a request crosses a real network.
 
 ## Roadmap
 
-- [ ] Add support for POST, PUT, DELETE methods
-- [ ] Implement request headers customization
-- [ ] Add streaming support for large responses
-- [ ] Implement request cancellation
-- [ ] Add comprehensive test suite
-- [ ] Performance benchmarks against native fetch
-- [ ] Support for form data and file uploads
+- [x] POST, PUT, PATCH, DELETE, HEAD, OPTIONS
+- [x] Request header customization
+- [x] Comprehensive test suite: Rust unit and integration tests (100% line coverage, enforced in CI), wasm tests, and JS end-to-end tests
+- [x] Streaming responses (`responseType: 'stream'`; `send_streaming()` in Rust)
+- [x] Request cancellation (`AbortSignal`)
+- [x] Performance benchmarks against native fetch (`npm run bench`)
+- [x] Multipart form data and file uploads
+- [x] Request/response interceptors
+- [x] Download progress tracking
+- [ ] Upload progress tracking: not possible on top of `fetch()`, which has no upload progress events
 - [ ] WebSocket support
-- [ ] Request/response interceptors
+- Handled by the runtime, not by rust-fetch:
+  - **Connection pooling:** browsers and Node.js pool connections for `fetch()` themselves.
+  - **Proxies:** set them up in the runtime, e.g. with undici's `setGlobalDispatcher(new ProxyAgent(url))` in Node.js, or with system settings in browsers.
+  - **HTTP/2:** browsers negotiate it automatically; in Node.js it depends on undici's dispatcher (`allowH2`).
+
+## Upgrading to 2.0
+
+2.0 fixes long-standing bugs, and some code may have depended on the old behaviour. Check these points:
+
+- **Timeouts are enforced** in browsers and Node.js. In 1.x the 30 s default was silently ignored, so slow requests never failed. For long downloads, set `timeoutMs` higher, or to `0` to disable it.
+- **`WasmClient` JSON bodies are plain objects**, not `Map`s: use `body.title`, not `body.get('title')`. JSON with integers above 2^53 no longer fails the request.
+- **More responses are decoded:** `application/*+json` (e.g. `problem+json`) is parsed as JSON instead of returned as bytes, and empty bodies are `null`.
+- **Errors are real `Error` objects.** `kind`, `message`, `status` and the other fields are unchanged, and `name` equals `kind`. Like any `Error`, `message` isn't enumerable, so `JSON.stringify(error)` leaves it out.
+- **Invalid `headers` values reject** with an `InvalidInputError`; they used to be dropped silently. Numbers and booleans are converted to strings.
+- **Text is decoded as UTF-8**, whatever the `charset` in `Content-Type`. Invalid bytes become `�`.
+- **The package uses an `exports` map.** Import `rust-fetch`, `rust-fetch/rust_fetch.js` or `rust-fetch/rust_fetch_bg.wasm`.
+- **Node.js 20+ is required.** In Node.js you no longer need to load the `.wasm` file yourself; `init()` is optional there.
+
+These changed too, but are unlikely to break anything:
+- POST and PATCH aren't retried by default (`retryNonIdempotent: true` re-enables it).
+- Your `Content-Type` is no longer duplicated.
+- `fetch_json` parses JSON whatever the `Content-Type`.
+- Invalid URLs, and `TRACE`/`CONNECT`, fail fast with an `InvalidInputError`.
+
+Rust crate users:
+- `RetryConfig` has a new field, so add `..Default::default()` to struct literals.
+- `Method::to_reqwest()` returns reqwest 0.12's `Method`.
+- `RequestBuilder::header()` replaces a default header with the same name instead of adding a second value.
+
+1.x keeps receiving critical fixes on the [`v1.x`](https://github.com/asemqaffaf/rust-fetch/tree/v1.x) branch (`npm install rust-fetch@1`).
+
+## Development
+
+The npm package is built from `wasm-module/` with [wasm-pack](https://rustwasm.github.io/wasm-pack/). The repository root is a private workspace.
+
+```bash
+npm run build      # wasm-pack build + package metadata (wasm-module/pkg)
+npm test           # Rust unit + integration tests, then the JS tests
+npm run test:js    # JS end-to-end tests against the built package (requires a build)
+npm run bench      # rust-fetch vs native fetch (requires a build)
+npm run size       # size budget for the built package
+npm run api:check  # public TypeScript API vs the committed snapshot
+
+cd wasm-module
+wasm-pack test --node    # wasm unit tests for the JS bindings
+cargo llvm-cov --ignore-filename-regex 'src/(wasm/|http\.rs)|tests/'   # coverage
+```
+
+| Suite | Where | What |
+| --- | --- | --- |
+| Rust unit tests | `wasm-module/src/**` | URL handling, retry policy, decoding, errors, multipart |
+| Rust integration tests | `wasm-module/tests/integration_tests.rs` | Real HTTP against a local server: retries, timeouts, redirects, chunked/truncated/large bodies, streaming, progress, concurrency |
+| Wasm unit tests | `wasm-module/src/wasm/tests.rs` | JS conversions, bodies, options, interceptors, timers and abort signals in Node.js |
+| JS end-to-end tests | `wasm-module/js/test/client.test.mjs` | The built package against a local server |
+| Package tests | `wasm-module/js/test/package.test.mjs` | Installs the packed tarball and uses it via `import`, `require`, the browser entry and its types |
+
+CI runs the Rust suites with a coverage gate that fails if line or function coverage of the Rust core drops below 100%. It also runs the wasm and JS suites on Node 20, 22 and 24, and checks formatting, dependencies (security advisories and licenses), API compatibility and the size budget. See [CONTRIBUTING.md](CONTRIBUTING.md#pull-requests). The JS-only bindings in `src/wasm/` and `src/http.rs` need a JS engine, so they're covered by the wasm and JS suites instead.
+
+Releases are published by CI when a version tag is pushed. See [CONTRIBUTING.md](CONTRIBUTING.md#releasing).
+
+## License
+
+Licensed under either of [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE), at your option.
+
+Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the development and release process, and [SECURITY.md](SECURITY.md) to report a vulnerability.

package/node.js

@@ -0,0 +1,13 @@
+// Node.js entry point (selected through the "node" export condition).
+//
+// Browsers load the .wasm file with fetch(), which Node.js can't do for
+// file: URLs. Here the module is compiled synchronously on import instead, so
+// the API is ready to use immediately; calling `init()` is optional and
+// returns the already-initialized module.
+import { readFileSync } from 'node:fs';
+import { initSync } from './rust_fetch.js';
+
+initSync({ module: readFileSync(new URL('./rust_fetch_bg.wasm', import.meta.url)) });
+
+export { default } from './rust_fetch.js';
+export * from './rust_fetch.js';