easy-web-worker 7.0.6 → 8.0.0

package/README.md

@@ -8,1093 +8,1045 @@
 
 <div align="center">
 
-**Real Web Workers. Simple API. Cancelable work.** 🚀
+## **Web Workers are powerful. Now they're also easy.**
 
-_Heavy computation off the main thread — without fighting the native Worker API._ ✨
+Let `easy-web-worker` handle everything between the threads.
+
+You keep the power of native Web Workers without dealing with all the complexity that usually comes with them.
+
+`easy-web-worker` handles the plumbing between both sides: message routing, request matching, promises, errors, cancellation, progress, transferable objects, lifecycle management, and worker pools.
 
 [![npm version](https://img.shields.io/npm/v/easy-web-worker.svg)](https://www.npmjs.com/package/easy-web-worker)
 [![Downloads](https://img.shields.io/npm/dm/easy-web-worker.svg)](https://www.npmjs.com/package/easy-web-worker)
 [![License](https://img.shields.io/github/license/johnny-quesada-developer/easy-web-worker)](https://github.com/johnny-quesada-developer/easy-web-worker/blob/main/LICENSE)
 
-[**Live Demo**](https://johnny-quesada-developer.github.io/easy-web-workers-example/) • [**Video Tutorial**](https://www.youtube.com/watch?v=CK-Uri9lDOE) • [**CodePen**](https://codepen.io/johnnynabetes/full/wvOvygW)
+[**Website**](https://johnny-quesada-developer.github.io/easy-web-worker/) · [**Documentation**](https://johnny-quesada-developer.github.io/easy-web-worker/docs/) · [**Examples**](https://johnny-quesada-developer.github.io/easy-web-worker/examples/) · [**API reference**](https://johnny-quesada-developer.github.io/easy-web-worker/docs/api-reference/) · [**Video Tutorial**](https://www.youtube.com/watch?v=CK-Uri9lDOE)
+
+Created by [Johnny Quesada](https://github.com/johnny-quesada-developer).
 
 </div>
 
 ---
 
-## 🎯 The One-Liner
+## Start with a single worker
+
+**Imagine defining your worker like this:**
 
 ```ts
-import { createEasyWebWorker } from 'easy-web-worker';
+export const worker = defineWorker(() => ({
+  fibonacci,
+}));
 
-const worker = createEasyWebWorker<number, number>(({ onMessage }) => {
-  onMessage((message) => message.resolve(message.payload * 2));
-});
+function fibonacci(n: number): number {
+  return n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
+}
 ```
 
-**That's it.** No separate worker file. No message-ID plumbing. No manual promise bridge. 🧵
+**And calling it like this:**
 
 ```ts
-const result = await worker.send(21);
+import type { worker as MathWorker } from './math.worker';
+import mathWorkerUrl from './math.worker?worker&url';
+
+/**
+ * The type of the worker is inferred from it's declaration,
+ * so everything is typed on the main thread.
+ */
+const mathWorker = createWorker<typeof MathWorker>(mathWorkerUrl);
 
-console.log(result); // 42
+const result = await mathWorker.fibonacci(40); // 102334155
 ```
 
-Your code runs inside a **real native Web Worker**, while the main thread receives a `CancelablePromise`.
+The computation runs inside a real native Web Worker. The page keeps scrolling, typing and animating while it runs.
+
+No manual `postMessage`.
+No message IDs.
+No response matching.
+No hand-written promise bridge.
+
+Just functions.
+
+> **[See it live →](https://johnny-quesada-developer.github.io/easy-web-worker/#live)** Same task, two ways to run it. On the main thread the page freezes. In a Worker it never stops. It runs in your browser, with real Workers.
 
 ---
 
-## 🚀 Why Developers Love This Library
+## Built for work that should not block the page
 
-### 🎓 **Small API Surface**
+### **Functions, not messages**
 
-If you already understand native Web Workers, the mental model stays familiar:
+Every key you return from `defineWorker` becomes a typed method on the main thread.
 
 ```ts
-const worker = createEasyWebWorker(({ onMessage }) => {
-  onMessage((message) => {
-    // Work inside the Worker
-    message.resolve('done');
-  });
-});
+// The worker does the heavy lifting
+const worker = defineWorker(() => ({
+  countWords: (text: string) => text.trim().split(/\s+/).length,
+}));
+```
 
-await worker.send();
+```ts
+// The main thread remains 100% responsive
+await text.countWords(article); // CancelablePromise<number>
 ```
 
-### ⚡ **Real Background Execution**
+[**How typed workers work →**](https://johnny-quesada-developer.github.io/easy-web-worker/docs/typed-workers/)
+
+### **Return a value, get a promise**
 
-Move CPU-heavy work away from the browser's main thread so rendering and user interaction can stay responsive.
+A method resolves with what it returns and rejects with what it throws. `async` works the same way.
 
 ```ts
-const worker = createEasyWebWorker<number, number>(({ onMessage }) => {
-  const fibonacci = (n: number): number => {
-    if (n <= 1) return n;
-    return fibonacci(n - 1) + fibonacci(n - 2);
-  };
+const worker = defineWorker(() => ({
+  parseReport: async (url: string) => {
+    const response = await fetch(url);
 
-  onMessage((message) => {
-    message.resolve(fibonacci(message.payload));
-  });
-});
+    if (!response.ok) throw new Error('Report not available');
+
+    return buildReport(await response.text());
+  },
+}));
 ```
 
-### 🛑 **Cancelable Promises**
+[**Return values and errors →**](https://johnny-quesada-developer.github.io/easy-web-worker/docs/typed-workers/#return-values-and-errors)
+
+### **Cancellation that reaches the Worker**
 
-Every `send()` returns a `CancelablePromise` from [`easy-cancelable-promise`](https://www.npmjs.com/package/easy-cancelable-promise).
+Every call returns a `CancelablePromise`. Canceling it tells the Worker to stop.
 
 ```ts
-const task = worker.send(45);
+const task = math.findPrimes(50_000_000);
 
-task.cancel('No longer needed');
+task.cancel('Canceled by user');
 ```
 
-Cancellation can travel **from the main thread into the Worker**, allowing the Worker to react and release resources.
+[**Run it live →**](https://johnny-quesada-developer.github.io/easy-web-worker/examples/progress-and-cancellation/) · [Read the guide](https://johnny-quesada-developer.github.io/easy-web-worker/docs/cancellation-and-progress/#cancellation-reaches-the-worker)
 
-### 📊 **Progress Reporting**
+### **Progress on the same call**
 
-Long-running jobs can report progress without resolving the request.
+Long-running methods report progress through the promise they already returned.
 
 ```ts
-worker.send(payload).onProgress((percentage) => {
-  console.log(`${percentage}%`);
+await math.findPrimes(50_000_000).onProgress((percentage) => {
+  progressBar.value = percentage;
 });
 ```
 
-### 🚦 **Built-In Worker Pool**
+[**Run it live →**](https://johnny-quesada-developer.github.io/easy-web-worker/examples/progress-and-cancellation/) · [Read the guide](https://johnny-quesada-developer.github.io/easy-web-worker/docs/cancellation-and-progress/#progress-on-the-same-call)
 
-Scale a single `EasyWebWorker` across multiple native Worker instances.
+### **Every core, one option**
+
+Set `maxWorkers` and the same object spreads calls across several native Workers.
 
 ```ts
-const worker = createEasyWebWorker(workerBody, {
-  maxWorkers: 4,
-});
+const math = createWorker<MathWorker>(source, { maxWorkers: 4 });
+
+// three calls, three threads, at the same time
+await Promise.all([math.fibonacci(40), math.fibonacci(41), math.fibonacci(42)]);
 ```
 
-The public API remains the same — the library manages worker creation and message distribution.
+[**Run it live →**](https://johnny-quesada-developer.github.io/easy-web-worker/examples/worker-pool/) · [Read the guide](https://johnny-quesada-developer.github.io/easy-web-worker/docs/worker-pools/)
 
-### 🧩 **Multiple Worker Sources**
+### **Move large buffers instead of copying them**
 
-Use whichever architecture fits the project:
+Pass transferable objects as the second argument. Ownership moves and nothing is cloned.
 
 ```ts
-createEasyWebWorker(workerBody);        // Runtime Worker template
-createEasyWebWorker('./worker.js');     // Static Worker file
-createEasyWebWorker(new URL(...));      // URL
-createEasyWebWorker(new Worker(...));   // Existing Worker
-createEasyWebWorker([worker1, worker2]); // Existing Worker pool
+const blurred = await images.blur(buffer, [buffer]);
 ```
 
----
+[**Run it live →**](https://johnny-quesada-developer.github.io/easy-web-worker/examples/transferable-buffers/) · [Read the guide](https://johnny-quesada-developer.github.io/easy-web-worker/docs/transferable-objects/)
 
-## 📦 Installation
+### **Any way you create a Worker**
 
-```bash
-npm install easy-web-worker
+A Worker file, a native `Worker`, your own pool, or just a function. The API on top stays the same.
+
+```ts
+createWorker<MathWorker>(new URL('./math.worker.ts', import.meta.url)); // Worker file
+createWorker<MathWorker>(workerUrl); // URL generated by your bundler
+createWorker<MathWorker>(new Worker(...)); // existing Worker
+createWorker<MathWorker>([worker1, worker2]); // existing pool
+createWorker(() => ({ fibonacci })); // a function, no file at all
 ```
 
-`easy-web-worker` uses [`easy-cancelable-promise`](https://www.npmjs.com/package/easy-cancelable-promise) for the promise lifecycle.
+[**Every source, with the setup for each bundler →**](https://johnny-quesada-developer.github.io/easy-web-worker/docs/creating-workers/)
 
-> **Upgrading from an old release?**  
-> If your project still imports `cancelable-promise-jq`, replace it with `easy-cancelable-promise`. The old package name is deprecated.
+### **No Worker file required**
 
----
+Pass a function instead of a file. Same methods, same inferred types, nothing to configure.
 
-## 🎬 Quick Start
+```ts
+const math = createWorker(() => {
+  const fibonacci = (n: number): number =>
+    n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
 
-### 30 Seconds to a Web Worker
+  return { fibonacci };
+});
 
-```ts
-import { createEasyWebWorker } from 'easy-web-worker';
+await math.fibonacci(40); // 102334155, typed as number
+```
 
-const fibonacciWorker = createEasyWebWorker<number, number>(({ onMessage }) => {
-  const fibonacci = (n: number): number => {
-    if (n <= 1) return n;
-    return fibonacci(n - 1) + fibonacci(n - 2);
-  };
+[**Run it live →**](https://johnny-quesada-developer.github.io/easy-web-worker/examples/worker-without-a-file/) · [Read the guide](https://johnny-quesada-developer.github.io/easy-web-worker/docs/runtime-workers/)
 
-  onMessage((message) => {
-    message.resolve(fibonacci(message.payload));
-  });
-});
+---
 
-const result = await fibonacciWorker.send(40);
+## Installation
 
-console.log(result);
+```bash
+npm install easy-web-worker
 ```
 
-The Fibonacci calculation executes in a separate native Worker thread instead of blocking the page's main thread. ⚡
+- **Any framework**: built on the native Worker API of the browser, with no dependency on React, Vue, Angular, Svelte or any other UI library.
+- **Promises**: calls return a `CancelablePromise` from [`easy-cancelable-promise`](https://www.npmjs.com/package/easy-cancelable-promise), installed with the package.
 
-### 60 Seconds to Production-Ready
-
-Run [`jsdiff`](https://www.npmjs.com/package/diff) inside a Web Worker so text comparison never blocks the main thread.
+---
 
-#### 🌐 Simple jsdiff implementation.
+## Quick Start
 
-No Worker file. No extra bundler configuration. Just give `easy-web-worker` the public script URL:
+### Your first typed worker
 
 ```ts
-// example.js
-import { createEasyWebWorker } from 'easy-web-worker';
+// math.worker.ts
+import { defineWorker } from 'easy-web-worker/defineWorker';
 
-const worker = createEasyWebWorker(
-  ({ onMessage }) => {
-    onMessage((message, context) => {
-      const { input1, input2 } = message.payload;
+const fibonacci = (n: number): number =>
+  n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
 
-      message.resolve(context.Diff.diffWords(input1, input2));
-    });
-  },
+// 1. Define it (in the Worker file)
+const worker = defineWorker(() => ({ fibonacci }));
+
+export type MathWorker = typeof worker;
+```
+
+```ts
+// main.ts
+import { createWorker } from 'easy-web-worker/createWorker';
+import type { MathWorker } from './math.worker';
+
+// 2. Create it (on the main thread)
+const math = createWorker<MathWorker>(
+  new URL('./math.worker.ts', import.meta.url),
   {
-    scripts: ['https://cdn.jsdelivr.net/npm/diff@9.0.0/dist/diff.min.js'],
+    workerOptions: { type: 'module' },
   }
 );
 
-const result = await worker.send({
-  input1: 'Web Workers are powerful.',
-  input2: 'Web Workers are incredibly powerful.',
-});
-
-console.log(result);
+// 3. Call it
+const result = await math.fibonacci(40); // 102334155
 ```
 
-**That's it.** The CDN script is loaded inside the Worker, `jsdiff` exposes its `Diff` API there, and your main thread only sends data and awaits the result. 🚀
-
-- ✅ No separate Worker file
-- ✅ No npm import for jsdiff in your application bundle
-- ✅ No manual `importScripts()`
-- ✅ No `postMessage` / `onmessage` plumbing
-- ✅ Type-safe request and result
-- ✅ Real background execution
+The main thread imports only the **type** of the Worker. TypeScript infers both sides: `math.fibonacci` takes a `number` and returns a `CancelablePromise<number>`. Change the Worker, and the main thread stops compiling until it matches.
 
-#### 📄 Static Worker file and specific actions
+> Shipping with a bundler? See [Every way to create a worker](#every-way-to-create-a-worker) for the production setup.
+>
+> Prefer a step-by-step page? [Getting started](https://johnny-quesada-developer.github.io/easy-web-worker/docs/getting-started/) covers the same code, and [Keep the page responsive](https://johnny-quesada-developer.github.io/easy-web-worker/examples/keep-the-page-responsive/) runs it in your browser.
 
-If you prefer normal module imports, your own Worker file, or bundler-controlled dependencies, use `StaticEasyWebWorker`.
+### Progress and cancellation
 
-**`TextDiff.worker.ts`**
+Wrap a method with `onMessage` to receive the message of the call.
 
 ```ts
-import { diffWords, type Change } from 'diff';
-import { StaticEasyWebWorker } from 'easy-web-worker';
-import type { ComparePayload, Change } from './TextDiff.types';
-
-const easyWorker = new StaticEasyWebWorker();
+// math.worker.ts
+const worker = defineWorker(({ onMessage }) => ({
+  findPrimes: onMessage(async (limit: number, message) => {
+    const primes: number[] = [];
 
-// you can define multiple named methods inside the Worker
-easyWorker.onMessage<ComparePayload, Change[]>('compare', (message) => {
-  const { input1, input2 } = message.payload;
+    for (let candidate = 2; candidate <= limit; candidate++) {
+      if (isPrime(candidate)) primes.push(candidate);
 
-  message.resolve(diffWords(input1, input2));
-});
-
-easyWorker.onMessage<string, string>('uppercase', (message) => {
-  message.resolve(message.payload.toUpperCase());
-});
-```
+      if (candidate % 100_000 !== 0) continue;
 
-**That's the whole Worker.** Now connect it to your application:
+      // give the Worker a moment to receive a cancellation
+      await new Promise((resolve) => setTimeout(resolve));
 
-```ts
-import { EasyWebWorker } from 'easy-web-worker';
-import workerUrl from './TextDiff.worker?worker&url';
+      if (!message.isPending()) break;
 
-// For vite, use the Worker URL in production and the TypeScript file in development.
-const isProduction = import.meta.env.MODE === 'production';
+      message.reportProgress((candidate / limit) * 100);
+    }
 
-const worker = new EasyWebWorker(
-  isProduction ? workerUrl : new URL('./TextDiff.worker.ts', import.meta.url),
-  {
-    workerOptions: {
-      type: 'module',
-    },
-  }
-);
+    return primes;
+  }),
+}));
+```
 
-const result = await worker.sendToMethod<ComparePayload, Change[]>('compare', {
-  input1: 'Web Workers are powerful.',
-  input2: 'Web Workers are incredibly powerful.',
+```ts
+// main.ts
+const task = math.findPrimes(50_000_000).onProgress((percentage) => {
+  progressBar.value = percentage;
 });
-```
 
-Both approaches give you the same core result: a normal JavaScript library doing CPU work inside a **Web Worker**, while your application talks to it through a Promise-based API.
+cancelButton.onclick = () => task.cancel('Canceled by user');
 
-| Approach                | Best for                                                                     |
-| ----------------------- | ---------------------------------------------------------------------------- |
-| 🌐 CDN + runtime Worker | Fastest setup, demos, small integrations, no Worker file                     |
-| 📄 Static Worker        | Module imports, larger Worker code, bundler control, production architecture |
+const primes = await task;
+```
 
-And in both cases you still get the `easy-web-worker` features around the Worker:
+Progress and cancellation belong to the call itself, not to a second channel.
 
-- ✅ Promise-based communication
-- ✅ Cancellation
-- ✅ Progress reporting
-- ✅ Named Worker methods
-- ✅ Worker pooling when needed
+> This exact pattern runs live in [Progress and cancellation](https://johnny-quesada-developer.github.io/easy-web-worker/examples/progress-and-cancellation/): start a long search, watch it advance, and cancel it.
 
 ---
 
-## 🌟 Core Features Deep Dive
+## Core Features Deep Dive
 
-### 1️⃣ Runtime Workers with `createEasyWebWorker`
+### Typed workers with `defineWorker` and `createWorker`
 
-Create a Worker directly from a function template.
+Write the Worker as a set of methods and call them from the main thread like local async functions.
 
-#### 🎨 The Basics
+#### The Basics
 
 ```ts
-import { createEasyWebWorker } from 'easy-web-worker';
-
-const backgroundWorker = createEasyWebWorker<string, string>(
-  ({ onMessage }) => {
-    onMessage((message) => {
-      message.resolve(`Message from Worker: ${message.payload}`);
-    });
-  }
-);
+// text.worker.ts
+const worker = defineWorker(() => ({
+  countWords: (text: string) => text.trim().split(/\s+/).length,
 
-const result = await backgroundWorker.send('hello!');
+  findDuplicates: (lines: string[]) =>
+    lines.filter((line, index) => lines.indexOf(line) !== index),
+}));
 
-console.log(result);
+export type TextWorker = typeof worker;
 ```
 
-The first generic controls the `send()` payload. The second controls the value returned when the Worker calls `message.resolve()`.
-
 ```ts
-const worker = createEasyWebWorker<Payload, Result>(workerBody);
-```
-
-#### 🎯 Named Worker Methods
+// main.ts
+const text = createWorker<TextWorker>(source);
 
-A Worker can expose multiple message handlers instead of routing everything through one callback.
+await text.countWords(article); // number
+await text.findDuplicates(lines); // string[]
+```
 
-```ts
-const worker = createEasyWebWorker<string, string>(({ onMessage }) => {
-  onMessage((message) => {
-    message.resolve(`default: ${message.payload}`);
-  });
+The contract between the threads lives next to the code that implements it. There is no second file of message types to keep in sync.
 
-  onMessage<number, number>('double', (message) => {
-    message.resolve(message.payload * 2);
-  });
+How the types cross the threads:
 
-  onMessage<{ first: number; second: number }, number>('sum', (message) => {
-    const { first, second } = message.payload;
-    message.resolve(first + second);
-  });
-});
+| In the Worker                     | On the main thread                                            |
+| --------------------------------- | ------------------------------------------------------------- |
+| `() => string`                    | `() => CancelablePromise<string>`                             |
+| `(value: number) => number`       | `(payload: number, transfer?) => CancelablePromise<number>`   |
+| `async (ids: string[]) => User[]` | `(payload: string[], transfer?) => CancelablePromise<User[]>` |
+| `(value?: number) => number`      | `(payload?: number, transfer?) => CancelablePromise<number>`  |
 
-const defaultResult = await worker.send('hello');
-const doubled = await worker.sendToMethod<number, number>('double', 21);
-const total = await worker.sendToMethod<
-  number,
-  { first: number; second: number }
->('sum', { first: 20, second: 22 });
-```
+A method receives **one payload**. Send several values as an object or a tuple. Required payloads are enforced when TypeScript runs with `strict` or `strictNullChecks`.
 
-This makes it possible to build a small, typed API inside one Worker. 🧩
+#### What it replaces
 
-#### 🧠 Worker Scope — Important!
+`fibonacci(40)` on the main thread freezes the page for about a second. A Web Worker fixes that, but the native API gives you messages, not functions. This is the least you write by hand:
 
-A runtime Worker body becomes the Worker source. It **cannot close over arbitrary variables from the main thread**.
+```ts
+// fibonacci.worker.js
+self.onmessage = ({ data: { id, n } }) => {
+  self.postMessage({ id, result: fibonacci(n) });
+};
+```
 
 ```ts
-const greeting = 'Hello';
+// main.js
+const worker = new Worker(new URL('./fibonacci.worker.js', import.meta.url));
+const pending = new Map();
+let nextId = 0;
+
+worker.onmessage = ({ data: { id, result } }) => {
+  pending.get(id)(result);
+  pending.delete(id);
+};
 
-createEasyWebWorker(({ onMessage }) => {
-  onMessage((message) => {
-    // ❌ `greeting` does not exist inside the Worker scope.
-    message.resolve(greeting);
+const fibonacci = (n) =>
+  new Promise((resolve) => {
+    const id = nextId++;
+
+    pending.set(id, resolve);
+    worker.postMessage({ id, n });
   });
-});
 ```
 
-Everything needed by the Worker must be:
-
-- Defined inside the Worker body
-- Included through reusable Worker templates
-- Imported as a script
-- Sent in a message
-- Passed as a primitive parameter
-
-#### 📦 Primitive Parameters
+And that is before errors, cancellation, progress, types, or a second method.
 
-For small static values that should exist when the runtime Worker is created, use `primitiveParameters`.
+#### Return values and errors
 
 ```ts
-const prefix = 'Result:';
+// report.worker.ts
+const worker = defineWorker(() => ({
+  parseReport: async (url: string) => {
+    const response = await fetch(url);
 
-const worker = createEasyWebWorker<null, string>(
-  ({ onMessage }, context) => {
-    const [prefix] = context.primitiveParameters;
+    if (!response.ok) {
+      throw new Error(`Report not available: ${response.status}`);
+    }
 
-    onMessage((message) => {
-      message.resolve(`${prefix} complete`);
-    });
+    return buildReport(await response.text());
   },
-  {
-    primitiveParameters: [prefix],
-  }
-);
-
-console.log(await worker.send()); // Result: complete
+}));
 ```
 
-Use regular Worker messages for dynamic application data. `primitiveParameters` are best for small initialization values.
+```ts
+// main.ts
+try {
+  const report = await reports.parseReport('/reports/2026.csv');
+} catch (error) {
+  console.log((error as Error).message); // 'Report not available: 404'
+}
+```
 
-#### 📊 Progress Without Resolving
+An error rejects that one call. The Worker keeps serving the next one.
 
-The Worker can report progress as many times as necessary before the message finishes.
+#### Three ways to write a method
 
 ```ts
-const worker = createEasyWebWorker<number[], number>(({ onMessage }) => {
-  onMessage((message) => {
-    let total = 0;
+const worker = defineWorker(({ onMessage }) => ({
+  // 1. a plain function
+  double: (value: number) => value * 2,
+
+  // 2. onMessage: same thing, with the message and the event typed for you
+  count: onMessage(async (to: number, message, event) => {
+    message.reportProgress(50);
+
+    return to;
+  }),
+
+  // 3. onMessage().handle: only the message, you complete it
+  wait: onMessage<number, string>().handle((message, event) => {
+    const timeoutId = setTimeout(
+      () => message.resolve('done'),
+      message.payload
+    );
+
+    message.onCancel(() => clearTimeout(timeoutId));
+  }),
+}));
+```
 
-    message.payload.forEach((value, index, values) => {
-      total += value;
-      message.reportProgress(((index + 1) / values.length) * 100);
-    });
+| Style                                         | Completes the call      | Types                             |
+| --------------------------------------------- | ----------------------- | --------------------------------- |
+| Plain function                                | With the returned value | Inferred                          |
+| `onMessage((payload, message, event) => ...)` | With the returned value | Inferred, `message` typed         |
+| `onMessage<P, R>().handle((message) => ...)`  | You do                  | Explicit, `message.resolve` typed |
 
-    message.resolve(total);
-  });
-});
+All three are called the same way from the main thread. Use the third for timers, streams, event-based APIs, or to transfer a result.
 
-const result = await worker.send([10, 20, 30, 40]).onProgress((percentage) => {
-  console.log(percentage);
-});
-```
+If a method completes the message itself with `resolve`, `reject` or `cancel`, its return value is ignored.
 
-Output:
+#### The message
 
-```text
-25
-50
-75
-100
-```
+Available in `onMessage`, in `.handle(...)`, and in the message API.
 
-#### 🛑 Two-Way Cancellation
+| Member                                            | Purpose                                       |
+| ------------------------------------------------- | --------------------------------------------- |
+| `payload`                                         | Value sent from the main thread               |
+| `resolve(result?, transfer?)`                     | Resolves the call                             |
+| `reject(reason?, transfer?)`                      | Rejects the call                              |
+| `cancel(reason?, transfer?)`                      | Cancels the call from inside the Worker       |
+| `reportProgress(percentage, payload?, transfer?)` | Reports progress and keeps the call pending   |
+| `onCancel`, `onResolve`, `onReject`, `onProgress` | Subscribe to each outcome; return unsubscribe |
+| `onFinalize`                                      | Runs once the call ends, whatever the outcome |
+| `isPending()`, `getStatus()`                      | Current state of the call                     |
 
-Cancellation is more than rejecting a promise on the main thread. The Worker receives the cancellation event too.
+#### Cancellation
 
-```ts
-const worker = createEasyWebWorker<number, number>(({ onMessage }) => {
-  onMessage((message) => {
-    const interval = setInterval(() => {
-      // long-running work...
-    }, 100);
+The cancellation reaches the Worker, so the work stops there instead of finishing for nobody. React to it with `message.onCancel(...)` or check `message.isPending()`.
 
-    message.onCancel((data) => {
-      clearInterval(interval);
+Canceling twice, or after the call finished, does nothing.
 
-      const reason = data.worker_cancelation?.reason ?? data.canceled?.reason;
+A Worker that never pauses cannot receive a cancellation. See [Stop work that never pauses](#stop-work-that-never-pauses).
 
-      console.log('Canceled:', reason);
-    });
-  });
-});
+#### Transferable objects
 
-const task = worker.send(100);
+```ts
+// main.ts
+const buffer = await file.arrayBuffer();
 
-task.cancel('User navigated away');
+const blurred = await images.blur(buffer, [buffer]);
 ```
 
-Inside a Worker, a message can also cancel itself:
+Returned values are cloned. To transfer a result back, complete the call yourself:
 
 ```ts
-onMessage((message) => {
-  if (!isValid(message.payload)) {
-    message.cancel('Invalid payload');
-    return;
-  }
-
-  // continue...
-});
+// images.worker.ts
+const worker = defineWorker(({ onMessage }) => ({
+  blur: onMessage<ArrayBuffer, ArrayBuffer>().handle((message) => {
+    const result = applyBlur(message.payload);
+
+    message.resolve(result, [result]);
+  }),
+}));
 ```
 
-#### 🔄 Message Lifecycle
+#### `unwrap`: the controls behind the methods
 
-Each `IEasyWebWorkerMessage` provides lifecycle hooks:
+The object returned by `createWorker` holds only your methods, so names like `send`, `dispose` or `reboot` stay free for your own API. `unwrap` reaches the `EasyWebWorker` instance behind it.
 
 ```ts
-onMessage((message) => {
-  const unsubscribeResolve = message.onResolve(() => {});
-  const unsubscribeReject = message.onReject(() => {});
-  const unsubscribeCancel = message.onCancel(() => {});
-  const unsubscribeProgress = message.onProgress(() => {});
-  const unsubscribeFinalize = message.onFinalize(() => {});
-
-  const status = message.getStatus();
-  const pending = message.isPending();
-
-  // Unsubscribe whenever you no longer need a listener.
-  unsubscribeResolve();
-  unsubscribeReject();
-  unsubscribeCancel();
-  unsubscribeProgress();
-  unsubscribeFinalize();
+import { createWorker, unwrap } from 'easy-web-worker/createWorker';
 
-  message.resolve();
-});
+const math = createWorker<MathWorker>(source);
+
+await unwrap(math).cancelAll('Leaving the page');
+await unwrap(math).reboot();
+await unwrap(math).dispose();
 ```
 
-#### 🚚 Transferable Objects
+| `EasyWebWorker` method                                         | Purpose                                                         |
+| -------------------------------------------------------------- | --------------------------------------------------------------- |
+| `send(payload?, transfer?)`                                    | Sends a message to the default handler                          |
+| `sendToMethod<TResult, TPayload>(method, payload?, transfer?)` | Sends a message to a named method                               |
+| `cancelAll(reason?, { force? })`                               | Cancels every pending call; `force` restarts instead of waiting |
+| `override(payload?, reason?, { force? })`                      | Cancels the pending calls and sends a new message               |
+| `overrideAfterCurrent(payload?, reason?)`                      | Keeps the current call, cancels the rest, sends a new message   |
+| `reboot(reason?)`                                              | Terminates the Workers, rejects pending calls, starts again     |
+| `dispose()`                                                    | Cancels pending calls and releases the Workers                  |
 
-Both directions can use native `Transferable[]` values to move ownership instead of cloning large buffers.
+The same helper works inside the Worker file, where it returns the Worker-side controls:
 
 ```ts
-type Payload = {
-  buffer: ArrayBuffer;
-};
+import { defineWorker, unwrap } from 'easy-web-worker/defineWorker';
 
-const worker = createEasyWebWorker<Payload, ArrayBuffer>(({ onMessage }) => {
-  onMessage((message) => {
-    const { buffer } = message.payload;
+const worker = defineWorker(() => ({
+  shutdown: () => unwrap(worker).close(),
+}));
 
-    // Process the buffer...
+unwrap(worker).importScripts('https://example.com/library.js');
 
-    message.resolve(buffer, [buffer]);
-  });
+// handles messages sent without a method: send, override, overrideAfterCurrent
+unwrap(worker).onMessage((message) => {
+  message.resolve();
 });
-
-const buffer = new ArrayBuffer(1_000_000);
-
-const processedBuffer = await worker.send({ buffer }, [buffer]);
 ```
 
-This is especially useful for `ArrayBuffer`, media processing, binary parsing, and other data-heavy workloads.
+One name is not available for a method: `then`. The worker object is not a promise, so `await math` never sends a message.
 
----
+#### Entry points
 
-### 2️⃣ Static Workers with `StaticEasyWebWorker`
+Import each side from its own entry, so the Worker bundle carries no main-thread code:
 
-Sometimes a dedicated Worker file is the better architecture — especially when the Worker has its own modules, build pipeline, or large implementation.
+| Entry                          | Use it in       | Exports                         |
+| ------------------------------ | --------------- | ------------------------------- |
+| `easy-web-worker/defineWorker` | The Worker file | `defineWorker`, `unwrap`, types |
+| `easy-web-worker/createWorker` | The main thread | `createWorker`, `unwrap`, types |
 
-#### 🎪 The Basics
+Everything is also exported from the root `easy-web-worker` entry.
 
-**`worker.ts`**
+> **On the website:** [Typed workers](https://johnny-quesada-developer.github.io/easy-web-worker/docs/typed-workers/) · [Methods and the message](https://johnny-quesada-developer.github.io/easy-web-worker/docs/methods-and-the-message/) · [TypeScript](https://johnny-quesada-developer.github.io/easy-web-worker/docs/typescript/) · [API reference](https://johnny-quesada-developer.github.io/easy-web-worker/docs/api-reference/)
 
-```ts
-import { createStaticEasyWebWorker } from 'easy-web-worker/createStaticEasyWebWorker';
+---
 
-const { onMessage } = createStaticEasyWebWorker<number, number>();
+### Every way to create a worker
 
-onMessage((message) => {
-  message.resolve(message.payload * 2);
-});
+Pick the source that fits how your project builds and serves its Workers. `createWorker`, `createEasyWebWorker` and `new EasyWebWorker(...)` accept all of them. A function means methods for `createWorker` and messages for the other two.
 
-onMessage<string, string>('uppercase', (message) => {
-  message.resolve(message.payload.toUpperCase());
-});
-```
+| Source                 | Best for                                        | Pool with `maxWorkers` | `reboot` / `force` |
+| ---------------------- | ----------------------------------------------- | ---------------------- | ------------------ |
+| `URL` of a Worker file | Worker files in a bundled project               | ✅                     | ✅                 |
+| `string` path          | A Worker file you serve yourself                | ✅                     | ✅                 |
+| Existing `Worker`      | Bundlers that detect `new Worker(new URL(...))` | One Worker             | ❌                 |
+| Existing `Worker[]`    | Bringing your own pool                          | The array is the pool  | ❌                 |
+| Function               | Workers with no file at all                     | ✅                     | ✅                 |
+| Function array         | Workers composed from reusable pieces           | ✅                     | ✅                 |
 
-**Main thread**
+#### A Worker file in development
 
 ```ts
-import { createEasyWebWorker } from 'easy-web-worker';
-
-const worker = createEasyWebWorker<number, number>('./worker.js');
-
-const result = await worker.send(21);
+const math = createWorker<MathWorker>(
+  new URL('./math.worker.ts', import.meta.url),
+  {
+    workerOptions: { type: 'module' },
+  }
+);
 ```
 
-You keep the `send()`, cancellation, progress, and message lifecycle API while controlling the Worker file yourself.
+`type: 'module'` is required when the Worker file uses `import` or `export`, which every `defineWorker` file does.
 
-#### 🎁 Vite + TypeScript
+#### Vite: development and production
+
+In development, Vite serves the TypeScript file. A production build needs the Worker URL that Vite generates:
 
 ```ts
-import workerUrl from './worker?worker&url';
-import { createEasyWebWorker } from 'easy-web-worker';
+import { createWorker } from 'easy-web-worker/createWorker';
+import workerUrl from './math.worker?worker&url';
+import type { MathWorker } from './math.worker';
 
-const workerSource =
-  import.meta.env.MODE === 'production'
-    ? workerUrl
-    : new URL('./worker.ts', import.meta.url);
+// the Worker URL in production, the TypeScript file in development
+const isProduction = import.meta.env.MODE === 'production';
 
-const worker = createEasyWebWorker(workerSource, {
-  workerOptions: {
-    type: 'module',
-  },
-});
+const math = createWorker<MathWorker>(
+  isProduction ? workerUrl : new URL('./math.worker.ts', import.meta.url),
+  {
+    workerOptions: { type: 'module' },
+  }
+);
 ```
 
-#### 🔌 Existing Native Worker
-
-Already have a `Worker` instance? Wrap it directly.
+The same source works with the message API:
 
 ```ts
-const nativeWorker = new Worker(new URL('./worker.js', import.meta.url), {
-  type: 'module',
-});
+import { EasyWebWorker } from 'easy-web-worker';
 
-const worker = createEasyWebWorker(nativeWorker);
+const worker = new EasyWebWorker(
+  isProduction ? workerUrl : new URL('./TextDiff.worker.ts', import.meta.url),
+  {
+    workerOptions: { type: 'module' },
+  }
+);
 ```
 
-Or provide an existing pool:
+#### A native Worker you create
+
+webpack 5, Parcel and Vite all detect `new Worker(new URL(...))` and bundle the file for you. Create the Worker that way and hand it over:
 
 ```ts
-const worker = createEasyWebWorker([
-  new Worker('./worker-a.js'),
-  new Worker('./worker-b.js'),
-]);
+const math = createWorker<MathWorker>(
+  new Worker(new URL('./math.worker.ts', import.meta.url), { type: 'module' })
+);
 ```
 
-When an existing `Worker[]` is supplied, those Worker instances become the pool managed by `EasyWebWorker`.
-
----
-
-### 3️⃣ Concurrency & Worker Pool
+The library cannot create that Worker again, so `reboot` and `force` are not available. Leave `keepAlive` at its default so the Worker is not terminated when idle.
 
-A single `EasyWebWorker` can distribute simultaneous messages across multiple native Workers.
+#### Your own pool
 
-#### 🚦 Scale on Demand
+Pass an array of native Workers and calls are distributed across them:
 
 ```ts
-const worker = createEasyWebWorker<number, number>(
-  ({ onMessage }) => {
-    const fibonacci = (n: number): number => {
-      if (n <= 1) return n;
-      return fibonacci(n - 1) + fibonacci(n - 2);
-    };
-
-    onMessage((message) => {
-      message.resolve(fibonacci(message.payload));
-    });
-  },
-  {
-    maxWorkers: 4,
-  }
-);
+const createMathWorker = () =>
+  new Worker(new URL('./math.worker.ts', import.meta.url), { type: 'module' });
 
-const results = await Promise.all([
-  worker.send(40),
-  worker.send(41),
-  worker.send(42),
+const math = createWorker<MathWorker>([
+  createMathWorker(),
+  createMathWorker(),
+  createMathWorker(),
 ]);
 ```
 
-With `maxWorkers: 4`, the library can create additional Workers as concurrent requests arrive, up to the configured limit.
-
-#### 🔥 Warm Up the Pool
+#### A file you serve yourself
 
-Create the full pool immediately:
+A Worker script that is already built and public only needs its path:
 
 ```ts
-const worker = createEasyWebWorker(workerBody, {
-  maxWorkers: 4,
-  warmUpWorkers: true,
-});
+const math = createWorker<MathWorker>('/workers/math.worker.js');
 ```
 
-Useful when startup latency matters more than keeping the initial resource footprint small.
-
-#### 💤 Dispose Idle Workers Automatically
+#### A function, with no file at all
 
 ```ts
-const worker = createEasyWebWorker(workerBody, {
-  maxWorkers: 4,
-  keepAlive: false,
-  terminationDelay: 5_000,
-});
-```
+const math = createWorker(() => ({
+  double: (value: number) => value * 2,
+}));
 
-When there are no queued messages, idle Workers are terminated after the configured delay.
-
-#### ⚙️ Concurrency Defaults
+await math.double(21); // 42
+```
 
-| Option                     | Current behavior                                                            |
-| -------------------------- | --------------------------------------------------------------------------- |
-| `maxWorkers`               | Defaults to `1`                                                             |
-| `warmUpWorkers`            | Defaults to `true` for a single-worker configuration; otherwise `false`     |
-| `keepAlive`                | Defaults to the resolved `warmUpWorkers` value unless explicitly configured |
-| `terminationDelay`         | Defaults to `1000` ms                                                       |
-| Existing `Worker[]` source | Pool size comes from the supplied array and the workers are kept alive      |
+The function returns the methods, exactly like the builder of `defineWorker`. See [Runtime Workers](#runtime-workers-a-function-as-the-worker) for scope rules, parameters and external scripts.
 
-This lets the default experience behave like a persistent single Worker while making larger pools opt-in and demand-driven.
+> **On the website:** [Creating workers](https://johnny-quesada-developer.github.io/easy-web-worker/docs/creating-workers/) · [Troubleshooting](https://johnny-quesada-developer.github.io/easy-web-worker/docs/troubleshooting/)
 
 ---
 
-### 4️⃣ Reusable Worker Templates
+### Worker pools
 
-Runtime Worker bodies are templates, so common Worker functionality can be composed.
+One Worker runs one task at a time. A pool runs several at once, behind the same object.
 
-```ts
-import { createEasyWebWorker, type EasyWebWorkerBody } from 'easy-web-worker';
+#### Scale on demand
 
-const commonTools: EasyWebWorkerBody = ({ onMessage }, context) => {
-  context.doSomething = () => Promise.resolve('Reusable Worker code');
-};
-
-const worker = createEasyWebWorker([
-  commonTools,
-  ({ onMessage }, context) => {
-    onMessage(async (message) => {
-      const result = await context.doSomething();
+```ts
+const math = createWorker<MathWorker>(source, {
+  maxWorkers: 4,
+});
 
-      message.resolve(result);
-    });
-  },
+// three calls, three threads, at the same time
+const results = await Promise.all([
+  math.fibonacci(40),
+  math.fibonacci(41),
+  math.fibonacci(42),
 ]);
-
-await worker.send();
 ```
 
-This is useful when multiple runtime Workers share utilities, message handlers, or initialization logic.
+The calling code does not change. It does not know whether one Worker or four are behind it.
 
----
-
-### 5️⃣ Import Scripts into Runtime Workers
+Workers are created as concurrent calls arrive, so an idle application pays for none of them.
 
-External scripts can be included through the Worker configuration.
+#### Warm up or release the pool
 
 ```ts
-const worker = createEasyWebWorker(
-  ({ onMessage }, context) => {
-    onMessage((message) => {
-      context.doSomething();
-      message.resolve();
-    });
-  },
-  {
-    scripts: ['https://example.com/worker-library.js'],
-  }
-);
-```
-
-For example, if the imported script adds something to the Worker global scope:
+createWorker<MathWorker>(source, {
+  maxWorkers: 4,
+  warmUpWorkers: true, // create the whole pool up front, for the fastest first call
+});
 
-```js
-// worker-library.js
-self.message = 'Hello from imported script!';
-self.doSomething = () => console.log(self.message);
+createWorker<MathWorker>(source, {
+  maxWorkers: 4,
+  keepAlive: false, // terminate idle Workers...
+  terminationDelay: 5_000, // ...after five seconds without work
+});
 ```
 
-For modern module-heavy Workers, a static Worker file with normal ESM imports is often easier to organize.
-
----
-
-## 🔥 Advanced Patterns
-
-### 🏗️ Build a Worker API with Named Methods
-
-```ts
-type User = {
-  id: string;
-  name: string;
-};
-
-const worker = createEasyWebWorker(({ onMessage }) => {
-  const users = new Map<string, User>();
+#### Configuration
 
-  onMessage<User, void>('saveUser', (message) => {
-    users.set(message.payload.id, message.payload);
-    message.resolve();
-  });
+| Option                | Default                 | Purpose                                              |
+| --------------------- | ----------------------- | ---------------------------------------------------- |
+| `maxWorkers`          | `1`                     | Maximum number of native Workers                     |
+| `warmUpWorkers`       | `true` for one Worker   | Creates the pool during initialization               |
+| `keepAlive`           | Same as `warmUpWorkers` | Keeps idle Workers alive                             |
+| `terminationDelay`    | `1000` ms               | Wait before terminating idle Workers                 |
+| `workerOptions`       | `{}`                    | Native `WorkerOptions`, such as `{ type: 'module' }` |
+| `onWorkerError`       | Rethrows                | Receives the uncaught errors of the Worker           |
+| `scripts`             | `[]`                    | Scripts imported into a runtime Worker               |
+| `primitiveParameters` | `[]`                    | Static values for a runtime Worker, in `context`     |
 
-  onMessage<string, User | null>('getUser', (message) => {
-    message.resolve(users.get(message.payload) ?? null);
-  });
+The same options apply to `createWorker`, `createEasyWebWorker` and `new EasyWebWorker(...)`.
 
-  onMessage<string, boolean>('deleteUser', (message) => {
-    message.resolve(users.delete(message.payload));
-  });
-});
+> **On the website:** [Worker pools](https://johnny-quesada-developer.github.io/easy-web-worker/docs/worker-pools/) · [Live example: one worker or three](https://johnny-quesada-developer.github.io/easy-web-worker/examples/worker-pool/)
 
-await worker.sendToMethod<void, User>('saveUser', {
-  id: '42',
-  name: 'Johnny',
-});
-
-const user = await worker.sendToMethod<User | null, string>('getUser', '42');
-```
+---
 
-One Worker, multiple typed operations, one shared Worker-local state.
+### Runtime Workers: a function as the Worker
 
-### 🔎 Filter Large Collections with Progress
+Give `createWorker` a function instead of a file. No extra file, no bundler configuration.
 
-The Worker can retrieve, store, and filter a large collection without blocking the main thread.
+#### The Basics
 
 ```ts
-type Item = Record<string, unknown>;
+import { createWorker } from 'easy-web-worker/createWorker';
 
-const worker = createEasyWebWorker<string, Item[]>(({ onMessage }) => {
-  const collection = fetch('https://api.example.com/items').then(
-    (response) => response.json() as Promise<Item[]>
-  );
+const math = createWorker(({ onMessage }) => {
+  const fibonacci = (n: number): number =>
+    n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
 
-  const containsValue = (item: unknown, filter: string): boolean => {
-    if (item === null || item === undefined) return false;
+  return {
+    fibonacci,
 
-    if (typeof item !== 'object') {
-      return String(item).toLowerCase().includes(filter);
-    }
+    countTo: onMessage(async (limit: number, message) => {
+      for (let step = 1; step <= limit; step++) {
+        message.reportProgress((step * 100) / limit);
+      }
 
-    return Object.values(item).some((value) => containsValue(value, filter));
+      return limit;
+    }),
   };
+});
 
-  onMessage(async (message) => {
-    const items = await collection;
-    const filter = message.payload.trim().toLowerCase();
+const result = await math.fibonacci(40); // 102334155
+```
 
-    const result = items.filter((item, index) => {
-      message.reportProgress(((index + 1) / items.length) * 100);
+The function is the builder of [`defineWorker`](#three-ways-to-write-a-method): it receives `onMessage`, returns the methods, and their types are inferred. There is no type to export or import, because both sides are in the same file.
 
-      return containsValue(item, filter);
-    });
+Everything else works the same: cancellation, progress, transferable objects, `unwrap`, and pools with `maxWorkers`.
 
-    message.resolve(result);
-  });
-});
-```
+#### Worker scope
 
-Usage:
+The function becomes the source of a real Worker, so it **cannot use variables from outside**.
 
 ```ts
-const filtered = await worker
-  .send('johnny')
-  .onProgress((percentage) => console.log(percentage));
+const greeting = 'Hello';
 
-console.log(filtered);
+createWorker(() => ({
+  // `greeting` does not exist inside the Worker
+  greet: (name: string) => `${greeting} ${name}`,
+}));
 ```
 
-### 🥇 Latest Request Wins with `override()`
+Everything the Worker needs must be defined inside the function, imported as a script, sent as a payload, or passed through `primitiveParameters`.
 
-Useful for search, preview generation, parsing, or any workflow where an older queued result becomes irrelevant.
+#### Parameters and the scope of the Worker
+
+The second parameter is the global scope of the Worker. Static values arrive in `context.primitiveParameters`:
 
 ```ts
-const result = await worker.override(
-  latestPayload,
-  'Superseded by a newer request'
+const worker = createWorker(
+  (_helpers, context) => {
+    const [prefix] = context.primitiveParameters;
+
+    return {
+      label: (text: string) => `${prefix} ${text}`,
+    };
+  },
+  {
+    primitiveParameters: ['Result:'] as [string],
+  }
 );
+
+await worker.label('complete'); // 'Result: complete'
 ```
 
-`override()` cancels the current queued work and sends the new message after cancellation completes.
+#### The message API inside the function
 
-For immediate cancellation/reboot behavior:
+The function also receives `easyWorker`, the worker instance behind the methods. Everything the message API offers stays available, so existing runtime Workers can move over at their own pace.
 
 ```ts
-await worker.override(latestPayload, 'Superseded', { force: true });
-```
-
-> `force: true` reboots the Worker. A Worker created directly from an existing native `Worker` instance cannot be rebooted by the library.
+const worker = createWorker<{
+  double: (value: number) => number;
+  triple: (value: number) => number;
+}>(({ easyWorker }) => {
+  // named handler, message style
+  easyWorker.onMessage<number, number>('double', (message) => {
+    message.resolve(message.payload * 2);
+  });
 
-### 🥈 Keep the Current Task, Replace the Rest
+  // handler for messages sent without a method
+  easyWorker.onMessage((message) => {
+    message.resolve();
+  });
 
-`overrideAfterCurrent()` allows the currently executing message to finish, cancels the other queued messages, then sends the replacement.
+  return {
+    triple: (value: number) => value * 3,
+    shutdown: () => easyWorker.close(),
+  };
+});
 
-```ts
-const result = await worker.overrideAfterCurrent(
-  latestPayload,
-  'Queue replaced'
-);
+await worker.double(21); // 42
+await worker.triple(21); // 63
 ```
 
-This is useful when interrupting the current operation would be expensive or unsafe, but stale queued work should still be discarded.
+Only the returned methods are inferred. Handlers registered through `easyWorker` are described in the generic, as above, or called with `unwrap(worker).sendToMethod(...)`.
 
-### 🧹 Explicit Cleanup
+#### Import scripts
 
-Dispose the worker when the owning feature or application no longer needs it.
+External libraries load with the `scripts` option and appear in the scope of the Worker:
 
 ```ts
-await worker.dispose();
-```
-
-`dispose()` cancels outstanding work, revokes the generated Worker URL when applicable, terminates Worker instances, and clears the pool.
+const text = createWorker(
+  (_helpers, context) => {
+    // the script adds `Diff` to the scope of the Worker
+    const { diffWords } = context.Diff as {
+      diffWords: (before: string, after: string) => unknown[];
+    };
 
----
+    return {
+      compare: ({ before, after }: { before: string; after: string }) =>
+        diffWords(before, after),
+    };
+  },
+  {
+    scripts: ['https://cdn.jsdelivr.net/npm/diff@9.0.0/dist/diff.min.js'],
+  }
+);
 
-## 🧰 API Reference
+const changes = await text.compare({ before, after });
+```
 
-### `createEasyWebWorker(source, config?)`
+No Worker file is required, and the script does not become part of your application bundle.
 
-Convenience factory that creates an `EasyWebWorker`.
+#### Compose a Worker from several functions
 
-Supported sources:
+Pass an array and every function runs in the same Worker. They share its scope, and the methods they return are merged.
 
 ```ts
-EasyWebWorkerBody
-EasyWebWorkerBody[]
-string
-URL
-Worker
-Worker[]
-```
+const worker = createWorker([
+  // reusable piece: leaves a helper in the scope of the Worker
+  (_helpers, context) => {
+    context.round = (value: number) => Math.round(value * 100) / 100;
+  },
 
-Example:
+  () => ({
+    double: (value: number) => value * 2,
+    describe: () => 'first',
+  }),
 
-```ts
-const worker = createEasyWebWorker<Payload, Result>(workerBody, config);
-```
+  (_helpers, context) => {
+    const round = context.round as (value: number) => number;
 
-### `EasyWebWorker<TPayload, TResult>`
+    return {
+      average: (values: number[]) =>
+        round(values.reduce((total, value) => total + value, 0) / values.length),
 
-You can also instantiate the class directly:
-
-```ts
-import { EasyWebWorker } from 'easy-web-worker';
+      // repeated method: the last function wins
+      describe: () => 'last',
+    };
+  },
+]);
 
-const worker = new EasyWebWorker<Payload, Result>(workerBody, config);
+await worker.double(21); // 42
+await worker.average([1, 2, 2]); // 1.67
+await worker.describe(); // 'last'
 ```
 
-### ⚙️ Worker Configuration
-
-| Option                | Purpose                                                                                                                  |
-| --------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| `scripts`             | Scripts to include in a runtime Worker                                                                                   |
-| `workerOptions`       | Native [`WorkerOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker) passed when a Worker is created |
-| `onWorkerError`       | Handles native Worker errors                                                                                             |
-| `maxWorkers`          | Maximum number of native Workers in the pool                                                                             |
-| `keepAlive`           | Keep created Workers alive after work completes                                                                          |
-| `terminationDelay`    | Delay before idle Workers are terminated when `keepAlive` is `false`                                                     |
-| `warmUpWorkers`       | Create the configured Worker pool during initialization                                                                  |
-| `primitiveParameters` | Static primitive initialization values exposed through `context.primitiveParameters`                                     |
+Types are merged the same way: `worker.describe` takes the signature of the last function. Write the array inline so each function keeps its own type.
 
-### 📤 `send(payload?, transfer?)`
+#### Runtime Workers with the message API
 
-Send a message to the default Worker handler.
+`createEasyWebWorker` builds a Worker from a function too, with messages instead of methods:
 
 ```ts
-const result = await worker.send(payload);
-```
+import { createEasyWebWorker } from 'easy-web-worker';
 
-With transferables:
+const worker = createEasyWebWorker<number, number>(({ onMessage }) => {
+  onMessage((message) => {
+    message.resolve(message.payload * 2);
+  });
+});
 
-```ts
-const result = await worker.send(payload, [buffer]);
+await worker.send(21); // 42
 ```
 
-Returns a `CancelablePromise<TResult>`.
+The first generic is the payload of `send()`. The second is the value passed to `message.resolve()`. It also accepts an array of functions that share the scope of the Worker, to compose a Worker from reusable pieces.
 
-### 🎯 `sendToMethod(method, payload?, transfer?)`
+> **On the website:** [Runtime workers](https://johnny-quesada-developer.github.io/easy-web-worker/docs/runtime-workers/) · [Live example: a worker without a file](https://johnny-quesada-developer.github.io/easy-web-worker/examples/worker-without-a-file/)
 
-Send a message to a named `onMessage(method, callback)` handler.
+---
 
-```ts
-const result = await worker.sendToMethod<Result, Payload>('calculate', payload);
-```
+### The message API with `StaticEasyWebWorker`
 
-### 🛑 `cancelAll(reason?, config?)`
+`defineWorker` is built on a message API that you can use directly, in Worker files and in runtime Workers.
 
-Cancel all currently tracked messages.
+#### The Basics
 
 ```ts
-await worker.cancelAll('Canceled by user');
-```
+// worker.ts
+import { createStaticEasyWebWorker } from 'easy-web-worker/createStaticEasyWebWorker';
 
-Force an immediate Worker reboot:
+const { onMessage } = createStaticEasyWebWorker<number, number>((message) => {
+  message.resolve(message.payload * 2);
+});
 
-```ts
-await worker.cancelAll('Reset', {
-  force: true,
+onMessage<string, string>('uppercase', (message) => {
+  message.resolve(message.payload.toUpperCase());
 });
 ```
 
-### 🥇 `override(payload?, reason?, config?)`
+```ts
+// main.ts
+import { createEasyWebWorker } from 'easy-web-worker';
 
-Cancel current queued work and send a replacement message.
+const worker = createEasyWebWorker<number, number>(source);
 
-```ts
-const result = await worker.override(payload, 'Superseded');
+await worker.send(21); // default handler
+await worker.sendToMethod<string, string>('uppercase', 'hello'); // result type first
 ```
 
-### 🥈 `overrideAfterCurrent(payload?, reason?, config?)`
+#### Typed methods for an existing Worker
 
-Allow the current message to complete, cancel the remaining queue, then send a replacement.
+A Worker written with the message API can still be called with typed methods. Describe them:
 
 ```ts
-const result = await worker.overrideAfterCurrent(payload, 'Queue replaced');
-```
+const worker = createWorker<{ uppercase: (text: string) => string }>(source);
 
-### 🔄 `reboot(reason?)`
+await worker.uppercase('hello');
+```
 
-Terminate the current Worker pool, cancel tracked messages, and initialize the Worker again.
+> **On the website:** [Message API](https://johnny-quesada-developer.github.io/easy-web-worker/docs/message-api/) · [API reference](https://johnny-quesada-developer.github.io/easy-web-worker/docs/api-reference/)
 
-```ts
-worker.reboot('Worker configuration reset');
-```
+---
 
-A Worker created from an existing native `Worker` instance cannot be rebooted by the library.
+## Advanced Patterns
 
-### 🧹 `dispose()`
+### Latest request wins
 
-Cancel outstanding messages and release the Worker resources.
+For search, previews and autocomplete, an older request is worthless once a newer one exists.
 
 ```ts
-await worker.dispose();
-```
+const search = createEasyWebWorker<string, SearchResult[]>(searchBody);
 
----
+input.oninput = async () => {
+  // cancels what is pending, then sends the new message
+  const results = await search.override(input.value, 'Superseded');
 
-## 💬 `IEasyWebWorkerMessage<TPayload, TResult>`
+  render(results);
+};
+```
 
-Every `onMessage()` handler receives an `IEasyWebWorkerMessage`.
+`overrideAfterCurrent` lets the call in progress finish and replaces only what is waiting behind it.
 
-### 📥 `payload`
+### Stop work that never pauses
 
-The payload sent from the main thread.
+A Worker stuck in a synchronous loop cannot receive a cancellation. Restart it instead:
 
 ```ts
-onMessage((message) => {
-  console.log(message.payload);
-});
-```
-
-### ✅ `resolve(result?, transfer?)`
-
-Resolve the main-thread promise.
+import { unwrap } from 'easy-web-worker/createWorker';
 
-```ts
-message.resolve(result);
+// terminates the Workers, rejects the pending calls, starts fresh ones
+await unwrap(math).cancelAll('Taking too long', { force: true });
 ```
 
-### ❌ `reject(reason?, transfer?)`
-
-Reject the main-thread promise.
+### Clean up when the owner goes away
 
 ```ts
-message.reject(new Error('Something failed'));
+await unwrap(math).dispose(); // typed workers
+await worker.dispose(); // EasyWebWorker
 ```
 
-### 🛑 `cancel(reason?, transfer?)`
+`dispose` cancels the pending calls, revokes the generated Worker URL when there is one, and terminates the Workers.
 
-Cancel the request from inside the Worker.
+> **On the website:** [Cancellation and progress](https://johnny-quesada-developer.github.io/easy-web-worker/docs/cancellation-and-progress/) · [Testing](https://johnny-quesada-developer.github.io/easy-web-worker/docs/testing/) · [Troubleshooting](https://johnny-quesada-developer.github.io/easy-web-worker/docs/troubleshooting/)
 
-```ts
-message.cancel('No longer needed');
-```
-
-### 📊 `reportProgress(percentage, payload?, transfer?)`
+---
 
-Report progress while keeping the request pending.
+## Documentation and examples
 
-```ts
-message.reportProgress(50, {
-  processed: 500,
-  total: 1000,
-});
-```
+Everything in this README runs for real on the [easy-web-worker website](https://johnny-quesada-developer.github.io/easy-web-worker/): real Web Workers, in your browser, against the same files that are published to npm.
 
-### 🎬 Lifecycle Subscriptions
+### See it before you install it
 
-```ts
-message.onResolve(callback);
-message.onReject(callback);
-message.onCancel(callback);
-message.onProgress(callback);
-message.onFinalize(callback);
-```
+| Live example | What you will see |
+| --- | --- |
+| [Keep the page responsive](https://johnny-quesada-developer.github.io/easy-web-worker/examples/keep-the-page-responsive/) | The same computation on the main thread and in a Worker. One freezes the page, the other does not. |
+| [Progress and cancellation](https://johnny-quesada-developer.github.io/easy-web-worker/examples/progress-and-cancellation/) | A long search that reports how far it is, and stops inside the Worker when you cancel it. |
+| [Worker pool](https://johnny-quesada-developer.github.io/easy-web-worker/examples/worker-pool/) | Three searches with one Worker and then with three. Same answers, sooner. |
+| [Transferable buffers](https://johnny-quesada-developer.github.io/easy-web-worker/examples/transferable-buffers/) | A large buffer moved to the Worker instead of copied. |
+| [Worker without a file](https://johnny-quesada-developer.github.io/easy-web-worker/examples/worker-without-a-file/) | A Worker created from a function, with no extra file and no bundler setup. |
 
-Each subscription returns an unsubscribe function.
+Every example shows its full source next to the running result.
 
-### 🔍 Status
+### Then go deeper
 
-```ts
-message.getStatus();
-message.isPending();
-```
+| Guide | What you will find |
+| --- | --- |
+| [Getting started](https://johnny-quesada-developer.github.io/easy-web-worker/docs/getting-started/) | Define your first worker and call it from the main thread. |
+| [Guides](https://johnny-quesada-developer.github.io/easy-web-worker/docs/) | Typed workers, cancellation, progress, transferables, pools and bundler setup. |
+| [API reference](https://johnny-quesada-developer.github.io/easy-web-worker/docs/api-reference/) | `defineWorker`, `createWorker`, `unwrap`, the message and the configuration. |
+| [Testing](https://johnny-quesada-developer.github.io/easy-web-worker/docs/testing/) | Test worker logic as plain functions, and the calling code without a Worker. |
+| [Troubleshooting](https://johnny-quesada-developer.github.io/easy-web-worker/docs/troubleshooting/) | Symptoms, causes and fixes. |
+| [Platform and versions](https://johnny-quesada-developer.github.io/easy-web-worker/docs/platform-and-versions/) | Browser support and what changes when upgrading. |
 
 ---
 
-## 🎨 Worker Source Options
+## Built to grow with your application
+
+| Without `easy-web-worker`            | With `easy-web-worker`                   |
+| ------------------------------------ | ---------------------------------------- |
+| `postMessage()` protocols            | Functions                                |
+| Manual request IDs                   | Automatic routing                        |
+| Response matching                    | Promises                                 |
+| Custom error transport               | Throw / catch                            |
+| Custom cancellation protocol         | `task.cancel()`                          |
+| Custom progress messages             | `.onProgress()`                          |
+| Hand-maintained TypeScript contracts | Inferred types                           |
+| Manual Worker orchestration          | Built-in pools                           |
+| Manual lifecycle handling            | Warm-up, keep-alive and idle termination |
 
-| Source              | Best for                                     | Worker managed by `easy-web-worker`? |
-| ------------------- | -------------------------------------------- | ------------------------------------ |
-| Function template   | Small/medium Worker logic with minimal setup | ✅                                   |
-| Template array      | Composable runtime Worker logic              | ✅                                   |
-| `string` / `URL`    | Dedicated static Worker file                 | ✅                                   |
-| Existing `Worker`   | Integrating an existing native Worker        | ✅ Wrapped                           |
-| Existing `Worker[]` | Supplying your own pre-created pool          | ✅ Wrapped                           |
+The Worker is still a real Web Worker, and the browser still provides the isolation and the extra thread. `easy-web-worker` removes what you would otherwise build around it.
 
-All approaches use the same message-oriented API on the main thread.
+> **Write Worker code like an API, call it like normal asynchronous JavaScript, and scale it without rebuilding the communication layer.**
 
 ---
 
-## 🎓 Learning Resources
+## Get Started Now
 
-- 🌐 [Live example — text diff](https://johnny-quesada-developer.github.io/easy-web-workers-example/)
-- 🎥 [Introduction video](https://www.youtube.com/watch?v=CK-Uri9lDOE)
-- 🧩 [Example repository](https://github.com/johnny-quesada-developer/easy-web-workers-example)
-- 🧪 [CodePen example](https://codepen.io/johnnynabetes/full/wvOvygW)
-- 📘 [MDN — Using Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers)
-- 📦 [npm — easy-web-worker](https://www.npmjs.com/package/easy-web-worker)
+```bash
+npm install easy-web-worker
+```
 
----
+Then in your Worker file:
+
+```ts
+import { defineWorker } from 'easy-web-worker/defineWorker';
 
-## 🌐 Framework Compatibility
+const fibonacci = (n: number): number =>
+  n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
 
-`easy-web-worker` is built around the browser's native Worker API, so it is not tied to a UI framework.
+const worker = defineWorker(() => ({ fibonacci }));
 
-| Environment        | Usage                 |
-| ------------------ | --------------------- |
-| React              | ✅                    |
-| Angular            | ✅                    |
-| Vue                | ✅                    |
-| Svelte             | ✅                    |
-| Vanilla JavaScript | ✅                    |
-| TypeScript         | ✅ Strongly typed API |
+export type MathWorker = typeof worker;
+```
 
-The important requirement is a runtime with browser Web Worker support.
+And in your app:
 
----
+```ts
+import { createWorker } from 'easy-web-worker/createWorker';
+import type { MathWorker } from './math.worker';
 
-## 🎉 Why Developers Choose This
+const math = createWorker<MathWorker>(source);
 
-### The Bottom Line
+console.log(await math.fibonacci(40)); // 102334155
+```
 
-| What You Get                  | What You Avoid                         |
-| ----------------------------- | -------------------------------------- |
-| ✅ Real native Worker threads | ❌ Main-thread CPU bottlenecks         |
-| ✅ Promise-based messaging    | ❌ Manual message-ID plumbing          |
-| ✅ Cancellation               | ❌ Abandoned long-running work         |
-| ✅ Progress events            | ❌ Custom progress protocols           |
-| ✅ Named Worker methods       | ❌ Giant message-routing switches      |
-| ✅ Transferable support       | ❌ Unnecessary large-data cloning      |
-| ✅ Worker pools               | ❌ Hand-written concurrency management |
-| ✅ Runtime + static Workers   | ❌ One forced architecture             |
-| ✅ TypeScript generics        | ❌ Untyped request/response contracts  |
+Continue with the [guides and interactive examples](https://johnny-quesada-developer.github.io/easy-web-worker/) to build your next worker.
 
 ---
 
-## 🤝 Collaborators
+## Collaborators
 
 <div align="center">
 
@@ -1121,35 +1073,19 @@ The important requirement is a runtime with browser Web Worker support.
 
 ---
 
-## 🚀 Get Started Now
-
-```bash
-npm install easy-web-worker
-```
-
-Then:
-
-```ts
-import { createEasyWebWorker } from 'easy-web-worker';
+## Built by Johnny Quesada
 
-const worker = createEasyWebWorker<string, string>(({ onMessage }) => {
-  onMessage((message) => {
-    message.resolve(message.payload.toUpperCase());
-  });
-});
+`easy-web-worker` exists because using another thread should not require building a messaging framework first.
 
-console.log(await worker.send('hello worker'));
-// HELLO WORKER
-```
+If it makes your codebase simpler, consider starring the project. It helps other developers discover it.
 
-**That's it. You're running work in a real Web Worker.** 🎉
+[**Star on GitHub**](https://github.com/johnny-quesada-developer/easy-web-worker) · [**Read the docs**](https://johnny-quesada-developer.github.io/easy-web-worker/docs/) · [**Run the examples**](https://johnny-quesada-developer.github.io/easy-web-worker/examples/) · [**Report an issue**](https://github.com/johnny-quesada-developer/easy-web-worker/issues)
 
----
-
-<div align="center">
+## Earlier resources
 
-### Built with ❤️ for developers who want the main thread to stay responsive
+Demos and walkthroughs from previous versions, kept for reference. For the current API, start with the
+[documentation website](https://johnny-quesada-developer.github.io/easy-web-worker/).
 
-**[⭐ Star on GitHub](https://github.com/johnny-quesada-developer/easy-web-worker)** • **[📝 Report Issues](https://github.com/johnny-quesada-developer/easy-web-worker/issues)** • **[🧩 Examples](https://github.com/johnny-quesada-developer/easy-web-workers-example)**
-
-</div>
+- [Original text diff demo](https://johnny-quesada-developer.github.io/easy-web-workers-example/) and its [source](https://github.com/johnny-quesada-developer/easy-web-workers-example)
+- [Original video walkthrough](https://www.youtube.com/watch?v=CK-Uri9lDOE)
+- [Original CodePen example](https://codepen.io/johnnynabetes/full/wvOvygW)