easy-web-worker 7.0.5 → 8.0.0

package/README.md

@@ -1,539 +1,1091 @@
 # easy-web-worker 🌟
 
-![Image John Avatar](https://raw.githubusercontent.com/johnny-quesada-developer/global-hooks-example/main/public/avatar2.jpeg)
+<div align="center">
 
-Hello and welcome to **easy-web-worker** with [easy-cancelable-promise](https://www.npmjs.com/package/easy-cancelable-promise) – your go-to solution for seamless **Web Workers** integration, now enhanced with cancelable promises! 🚀
+![Johnny Quesada](https://raw.githubusercontent.com/johnny-quesada-developer/global-hooks-example/main/public/avatar2.jpeg)
 
-[Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers) are a native tool provided by **JavaScript**, allowing you to use them within your favorite framework like **React**, **Angular**, **Vue**, and others, or with pure **JavaScript** and **TypeScript**.
+</div>
 
-Check out the running example with **React** and **TypeScript** at [CODEPEN](https://codepen.io/johnnynabetes/full/wvOvygW); let's explore the capabilities of JavaScript's concurrent processing with Web Workers!"
+<div align="center">
 
-[Important!] Starting from version 4.0.0, EasyWebWorker supports concurrency mode. This means you can now configure whether a single **EasyWebWorker** should use multiple Web Worker instances. This feature is extremely powerful for code that requires not only heavy computations occasionally but also robust concurrent processing. For more detailed information, please see the section below. [concurrency mode](#concurrency-mode)
+## **Web Workers are powerful. Now they're also easy.**
 
-#### IMPORTANT!
+Let `easy-web-worker` handle everything between the threads.
 
-If you were previously using **easy-web-worker** with **cancelable-promise-jq**, please note that the **cancelable-promise-jq** package has been renamed/deprecated. To continue using the latest version of **easy-web-worker**, simply uninstall **cancelable-promise-jq** and replace all imports with **easy-cancelable-promise**.
+You keep the power of native Web Workers without dealing with all the complexity that usually comes with them.
 
-I sincerely apologize for any inconvenience this may cause.
+`easy-web-worker` handles the plumbing between both sides: message routing, request matching, promises, errors, cancellation, progress, transferable objects, lifecycle management, and worker pools.
 
-### Creating a web worker never was easier!
+[![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)
 
-```ts
-import createEasyWebWorker from 'easy-web-worker/createEasyWebWorker';
+[**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)
 
-/**
- * The callback parameter will be the body of the worker
- */
-const worker = createEasyWebWorker(({ onMessage }) => {
-  const fibonacci = (n) => {
-    if (n <= 1) return n;
-    return fibonacci(n - 1) + fibonacci(n - 2);
-  };
+Created by [Johnny Quesada](https://github.com/johnny-quesada-developer).
 
-  /**
-   * Inside the worker we have to define an action when onMessage
-   */
-  onMessage((message) => {
-    /**
-     * The payload includes whatever parameters are sent from the main thread
-     */
-    const { payload } = message;
-    const result = fibonacci(payload.base);
-
-    message.resolve(result);
-    //message.reject(); // or reject
-  });
-});
+</div>
+
+---
+
+## Start with a single worker
+
+**Imagine defining your worker like this:**
+
+```ts
+export const worker = defineWorker(() => ({
+  fibonacci,
+}));
+
+function fibonacci(n: number): number {
+  return n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
+}
 ```
 
-Then, for sending a message to the worker:
+**And calling it like this:**
 
 ```ts
+import type { worker as MathWorker } from './math.worker';
+import mathWorkerUrl from './math.worker?worker&url';
+
 /**
- * This returns a CancelablePromise
+ * The type of the worker is inferred from it's declaration,
+ * so everything is typed on the main thread.
  */
-await worker.send(40);
+const mathWorker = createWorker<typeof MathWorker>(mathWorkerUrl);
+
+const result = await mathWorker.fibonacci(40); // 102334155
 ```
 
-And that's it! You now have a worker running heavy computation in a real separate thread, with real asynchronous programming in JavaScript.
+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.
+
+---
 
-You can also create an easy web worker from a static file, or from a native worker instance, here various examples:
+## Built for work that should not block the page
+
+### **Functions, not messages**
+
+Every key you return from `defineWorker` becomes a typed method on the main thread.
 
 ```ts
-// on vite and typescript
-import workerUrl from './worker?worker&url';
+// The worker does the heavy lifting
+const worker = defineWorker(() => ({
+  countWords: (text: string) => text.trim().split(/\s+/).length,
+}));
+```
 
-const isProduction = import.meta.env.MODE === 'production';
+```ts
+// The main thread remains 100% responsive
+await text.countWords(article); // CancelablePromise<number>
+```
 
-const workerSource = isProduction
-  ? workerUrl
-  : new URL('./worker.ts', import.meta.url);
+[**How typed workers work →**](https://johnny-quesada-developer.github.io/easy-web-worker/docs/typed-workers/)
 
-const worker = new EasyWebWorker(workerSource, {
-  workerOptions: {
-    type: 'module',
-  },
-});
+### **Return a value, get a promise**
+
+A method resolves with what it returns and rejects with what it throws. `async` works the same way.
+
+```ts
+const worker = defineWorker(() => ({
+  parseReport: async (url: string) => {
+    const response = await fetch(url);
+
+    if (!response.ok) throw new Error('Report not available');
 
-// or
-const worker = createEasyWebWorker(workerSource, {
-  workerOptions: {
-    type: 'module',
+    return buildReport(await response.text());
   },
-});
+}));
+```
 
-// if you are using ESM - ECMAScript Modules
-const worker = createEasyWebWorker([
-  new Worker(new URL('./worker.js', import.meta.url)),
-]);
+[**Return values and errors →**](https://johnny-quesada-developer.github.io/easy-web-worker/docs/typed-workers/#return-values-and-errors)
 
-// other ways with vanilla js
-const worker = createEasyWebWorker('./worker.js');
-const worker = createEasyWebWorker(new Worker('./worker.js')); // ƒ Worker() { [native code] }
+### **Cancellation that reaches the Worker**
 
-const worker = new EasyWebWorker('./worker.js');
-const worker = new EasyWebWorker(new Worker('./worker.js')); // ƒ Worker() { [native code] }
+Every call returns a `CancelablePromise`. Canceling it tells the Worker to stop.
+
+```ts
+const task = math.findPrimes(50_000_000);
+
+task.cancel('Canceled by user');
 ```
 
-When working with **static files**, which can offer substantial benefits with web workers, you simply need to create an instance of **StaticEasyWebWorker**.
+[**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)
 
-The **StaticEasyWebWorker** provides an interface to continue working with [easy-cancelable-promise](https://www.npmjs.com/package/easy-cancelable-promise) and build more complex APIs within your worker.
+### **Progress on the same call**
 
-From inside your worker, the message callbacks receive a message that includes multiple methods and functions. You can use these to communicate back with the main thread, or to subscribe to and react to the lifecycle of a worker.
+Long-running methods report progress through the promise they already returned.
 
 ```ts
-const { onMessage } = new StaticEasyWebWorker();
+await math.findPrimes(50_000_000).onProgress((percentage) => {
+  progressBar.value = percentage;
+});
+```
 
-/**
- *  For adding a default onMessage
- */
-onMessage((message) => {
-  /** Your message receives a payload,
-   * which is any information sent from the main thread.*/
-  const { payload } = message;
+[**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)
 
-  const bigArrayBuffer = new new ArrayBuffer(1000000)();
+### **Every core, one option**
 
-  /** You can resolve the message and respond to the main thread's promise that is listening.
-   * This promise could also send data back to the main thread and transfer data if needed */
-  message.resolve({ bigArrayBuffer }, [bigArrayBuffer]);
+Set `maxWorkers` and the same object spreads calls across several native Workers.
 
-  /** You can reject the message and send back a reason,
-   * if no transfer is necessary just avoid the second parameter */
-  message.reject(new Error('something happened'));
+```ts
+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)]);
+```
 
-  const metadata = { message: 'progress from inside the worker' };
+[**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/)
 
-  /** You can report progress */
-  message.reportProgress(10, metadata, []); // all the methods allows you to send Transferable[]
+### **Move large buffers instead of copying them**
 
-  /** You can cancel an operation from within the worker */
-  message.cancel('the operating was canceled from the worker');
+Pass transferable objects as the second argument. Ownership moves and nothing is cloned.
 
-  /** You can subscribe to the cancellation event of the message,
-   * regardless of whether this cancellation is internal or external to the worker.*/
-  const unsubscribeCancel = message.onCancel((reason) => {});
+```ts
+const blurred = await images.blur(buffer, [buffer]);
+```
 
-  // you can unsubscribe from the cancel event as well
-  unsubscribeCancel();
+[**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/)
 
-  /**
-   * And there is extra listeners for the other events
-   * This events represent the lifecycle of the message
-   */
-  const unsubscribeResolve = message.onResolve((data) => {});
-  const unsubscribeReject = message.onReject((data) => {});
-  const unsubscribeProgress = message.onProgress((data) => {});
-  const unsubscribeFinalize = message.onFinalize((data) => {});
+### **Any way you create a Worker**
 
-  /** You can also review the status of the message at any time*/
-  const status = message.getStatus(); // pending | resolved | rejected | canceled
-});
+A Worker file, a native `Worker`, your own pool, or just a function. The API on top stays the same.
 
-/**
- * For adding specific actions
- */
-onMessage('readCSV', (message) => {
-  // do something
+```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
+```
+
+[**Every source, with the setup for each bundler →**](https://johnny-quesada-developer.github.io/easy-web-worker/docs/creating-workers/)
+
+### **No Worker file required**
+
+Pass a function instead of a file. Same methods, same inferred types, nothing to configure.
+
+```ts
+const math = createWorker(() => {
+  const fibonacci = (n: number): number =>
+    n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
+
+  return { fibonacci };
 });
+
+await math.fibonacci(40); // 102334155, typed as number
 ```
 
-It's important to mention that the **cancel** method is the only one that provides two-way binding. It can travel all the way from the main thread to the worker, cancel something inside the worker, and notify the main thread upon completion.
+[**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/)
 
-**easy-web-worker** is designed to enhance the capabilities of the **Worker** class by integrating a pattern of cancelable promises from the [easy-cancelable-promise](https://www.npmjs.com/package/easy-cancelable-promise) library. For straightforward tasks, it simplifies the process by eliminating the need to configure webpack or other bundlers. And for more complex requirements, the **StaticEasyWebWorker** class allows the integration of easy worker and cancelable promises capabilities into your static workers.
+---
 
-Start enhancing your applications with robust, cancelable promises and easy web worker integration today! 🌐
+## Installation
 
-Experience it in action with a [Live Example featuring text-diff](https://johnny-quesada-developer.github.io/easy-web-workers-example/) 📘.
+```bash
+npm install easy-web-worker
+```
 
-For a comprehensive understanding, watch our informative [introduction video](https://www.youtube.com/watch?v=CK-Uri9lDOE) 🎥. You can also dive deeper into the code and explore on [easy-web-workers-examples](https://github.com/johnny-quesada-developer/easy-web-workers-example) 🧩.
+- **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.
 
-## Creating a simple Web Worker
+---
 
-Creating a new worker is as simple as
+## Quick Start
 
-```TS
-const backgroundWorker = createEasyWebWorker<string, string>(({ onMessage }) => {
-  onMessage((message) => {
-    const { payload } = message;
+### Your first typed worker
 
-    message.resolve(`this is  a message from the worker: ${payload}`);
-  });
+```ts
+// math.worker.ts
+import { defineWorker } from 'easy-web-worker/defineWorker';
 
-  // you could also define and send specific methods which allow you to create a better structured API
-  onMessage<number, number>('doSomething', (message) => {
-    const { payload } = message;
+const fibonacci = (n: number): number =>
+  n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
 
-    message.resolve(payload + 2);
-  });
+// 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),
+  {
+    workerOptions: { type: 'module' },
+  }
+);
+
+// 3. Call it
+const result = await math.fibonacci(40); // 102334155
+```
+
+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.
+
+> 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.
+
+### Progress and cancellation
+
+Wrap a method with `onMessage` to receive the message of the call.
+
+```ts
+// math.worker.ts
+const worker = defineWorker(({ onMessage }) => ({
+  findPrimes: onMessage(async (limit: number, message) => {
+    const primes: number[] = [];
+
+    for (let candidate = 2; candidate <= limit; candidate++) {
+      if (isPrime(candidate)) primes.push(candidate);
+
+      if (candidate % 100_000 !== 0) continue;
+
+      // give the Worker a moment to receive a cancellation
+      await new Promise((resolve) => setTimeout(resolve));
+
+      if (!message.isPending()) break;
+
+      message.reportProgress((candidate / limit) * 100);
+    }
+
+    return primes;
+  }),
+}));
+```
+
+```ts
+// main.ts
+const task = math.findPrimes(50_000_000).onProgress((percentage) => {
+  progressBar.value = percentage;
 });
 
-// outside your worker
-const messageResult = await backgroundWorker.send('hello!');
+cancelButton.onclick = () => task.cancel('Canceled by user');
 
-// for specific methods us the sendToMethod function
-const messageResult2 = await backgroundWorker.sendToMethod('doSomething', 2);
+const primes = await task;
 ```
 
-### Important notes:
+Progress and cancellation belong to the call itself, not to a second channel.
 
-EasyWebWorker<IPayload, IResult> has two generic parameters... They will affect the typing of the send() and response() methods.
+> 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.
 
-- If IResult is null, the _resolve_ method will not require parameters
-- If IPayload is null, the _send_ method will not require parameters
+---
 
-Take into consideration that the _workerBody_ is a template to create a worker in run time, so you'll not be able to use anything outside of the Worker-Scope.
+## Core Features Deep Dive
 
-```TS
-const message = 'Hello';
+### Typed workers with `defineWorker` and `createWorker`
 
-await createEasyWebWorker<null, string>(({ onMessage }) => {
-  onMessage((message) => {
+Write the Worker as a set of methods and call them from the main thread like local async functions.
+
+#### The Basics
+
+```ts
+// text.worker.ts
+const worker = defineWorker(() => ({
+  countWords: (text: string) => text.trim().split(/\s+/).length,
+
+  findDuplicates: (lines: string[]) =>
+    lines.filter((line, index) => lines.indexOf(line) !== index),
+}));
+
+export type TextWorker = typeof worker;
+```
+
+```ts
+// main.ts
+const text = createWorker<TextWorker>(source);
+
+await text.countWords(article); // number
+await text.findDuplicates(lines); // string[]
+```
+
+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.
+
+How the types cross the threads:
+
+| 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>`  |
+
+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`.
+
+#### What it replaces
+
+`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:
+
+```ts
+// fibonacci.worker.js
+self.onmessage = ({ data: { id, n } }) => {
+  self.postMessage({ id, result: fibonacci(n) });
+};
+```
+
+```ts
+// 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);
+};
+
+const fibonacci = (n) =>
+  new Promise((resolve) => {
+    const id = nextId++;
 
-    message.resolve(message); // THIS WILL PRODUCE AND ERROR!! the variable *message* will not exist in Worker-Scope.
+    pending.set(id, resolve);
+    worker.postMessage({ id, n });
   });
-}).send('hello!');
 ```
 
-If you need to pass a primitive parameter to the body of the worker, you can use the **primitiveParameters** configuration. This is an array of values that will be serialized and embedded into the worker's body.
+And that is before errors, cancellation, progress, types, or a second method.
+
+#### Return values and errors
 
 ```ts
-const message = 'Hello';
+// report.worker.ts
+const worker = defineWorker(() => ({
+  parseReport: async (url: string) => {
+    const response = await fetch(url);
 
-await createEasyWebWorker<null, string>(
-  ({ onMessage }, context) => {
-    const [message] = context.primitiveParameters;
+    if (!response.ok) {
+      throw new Error(`Report not available: ${response.status}`);
+    }
 
-    console.log(message); // "hello!" // 👍 it works!
+    return buildReport(await response.text());
   },
-  {
-    primitiveParameters: [message],
-  }
-).send('hello!');
+}));
 ```
 
-Take a look at Workers API if you don't know yet how they work: https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API,
-If you need t to send data to the worker, please define IPayload while creating a worker. _new EasyWebWorker<IPayload>(_
-You are just allowed to send information to Workers by messages, and vice versa
+```ts
+// main.ts
+try {
+  const report = await reports.parseReport('/reports/2026.csv');
+} catch (error) {
+  console.log((error as Error).message); // 'Report not available: 404'
+}
+```
 
-## IEasyWebWorkerMessage<IPayload = null, IResult = void>
+An error rejects that one call. The Worker keeps serving the next one.
 
-When you defined an onMessage callback in your **Worker**, this will receive all messages from the **send** method:
+#### Three ways to write a method
 
-```TS
-easyWorker.onMessage((message) => {
-  // the *message* will be strongly typed with TS
+```ts
+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));
+  }),
+}));
+```
 
- // the message could resolve the *send* promise.
-  message.resolve();
+| 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 |
+
+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.
+
+If a method completes the message itself with `resolve`, `reject` or `cancel`, its return value is ignored.
+
+#### The message
+
+Available in `onMessage`, in `.handle(...)`, and in the message API.
+
+| 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                     |
 
- // the message could be rejected from the worker
-  message.reject(new Error());
+#### Cancellation
 
-  // this message could be cancelled from inside the worker
-  message.cancel();
+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()`.
 
-  // the message is also able to listen to cancelation evens
-  message.onCancel(() => {
-    // release resources
-  })
+Canceling twice, or after the call finished, does nothing.
+
+A Worker that never pauses cannot receive a cancellation. See [Stop work that never pauses](#stop-work-that-never-pauses).
+
+#### Transferable objects
+
+```ts
+// main.ts
+const buffer = await file.arrayBuffer();
+
+const blurred = await images.blur(buffer, [buffer]);
+```
+
+Returned values are cloned. To transfer a result back, complete the call yourself:
+
+```ts
+// images.worker.ts
+const worker = defineWorker(({ onMessage }) => ({
+  blur: onMessage<ArrayBuffer, ArrayBuffer>().handle((message) => {
+    const result = applyBlur(message.payload);
+
+    message.resolve(result, [result]);
+  }),
+}));
+```
 
-  // you could also report progress to the principal thread if you configured a onProgress callback
-  message.reportProgress(25);
+#### `unwrap`: the controls behind the methods
+
+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
+import { createWorker, unwrap } from 'easy-web-worker/createWorker';
+
+const math = createWorker<MathWorker>(source);
+
+await unwrap(math).cancelAll('Leaving the page');
+await unwrap(math).reboot();
+await unwrap(math).dispose();
+```
+
+| `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                  |
+
+The same helper works inside the Worker file, where it returns the Worker-side controls:
+
+```ts
+import { defineWorker, unwrap } from 'easy-web-worker/defineWorker';
+
+const worker = defineWorker(() => ({
+  shutdown: () => unwrap(worker).close(),
+}));
+
+unwrap(worker).importScripts('https://example.com/library.js');
+
+// handles messages sent without a method: send, override, overrideAfterCurrent
+unwrap(worker).onMessage((message) => {
+  message.resolve();
 });
 ```
 
-## onProgress
+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
+
+Import each side from its own entry, so the Worker bundle carries no main-thread code:
+
+| 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 |
+
+Everything is also exported from the root `easy-web-worker` entry.
+
+> **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/)
 
-Let say you are performing some heavy process in your worker, but you still wanted to implement some kind of progress bar in the main thread... you could add an onProgress callback.
+---
 
-```TS
-await worker.send().onProgress((progress: number) => {
-  // change some progress bar percentage
-}).then(doSomething);
+### Every way to create a worker
+
+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.
+
+| 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           | ✅                     | ✅                 |
+
+#### A Worker file in development
+
+```ts
+const math = createWorker<MathWorker>(
+  new URL('./math.worker.ts', import.meta.url),
+  {
+    workerOptions: { type: 'module' },
+  }
+);
 ```
 
-onProgress Is gonna be executed every time you call _message.reportProgress_ inside the worker... the cool part here is that the _reportProgress_ is not gonna finish the main promise returned by the _send_ method.
+`type: 'module'` is required when the Worker file uses `import` or `export`, which every `defineWorker` file does.
 
-## Having multiple Worker-Templates
+#### Vite: development and production
 
-As _WorkerBody_ are just templates, you could reuse them on other _Workers_, or use them as plugins for your _Workers_. Let's see:
+In development, Vite serves the TypeScript file. A production build needs the Worker URL that Vite generates:
 
-```TS
-const reusableWorkerSegment: EasyWebWorkerBody = ({ onMessage, close, importScripts }, context) => {
-  context.doSomething = () => Promise.resolve('This is a plugin example');
-};
+```ts
+import { createWorker } from 'easy-web-worker/createWorker';
+import workerUrl from './math.worker?worker&url';
+import type { MathWorker } from './math.worker';
+
+// the Worker URL in production, the TypeScript file in development
+const isProduction = import.meta.env.MODE === 'production';
+
+const math = createWorker<MathWorker>(
+  isProduction ? workerUrl : new URL('./math.worker.ts', import.meta.url),
+  {
+    workerOptions: { type: 'module' },
+  }
+);
+```
+
+The same source works with the message API:
+
+```ts
+import { EasyWebWorker } from 'easy-web-worker';
+
+const worker = new EasyWebWorker(
+  isProduction ? workerUrl : new URL('./TextDiff.worker.ts', import.meta.url),
+  {
+    workerOptions: { type: 'module' },
+  }
+);
+```
 
-const reusableWorkerSegment = await createEasyWebWorker([
-  reusableWorkerSegment,
-  ({ onMessage }, context) => onMessage(async (message) => {
-  // context will have all stuff we added on other plugins
-  const result = await context.doSomething();
+#### A native Worker you create
 
-  message.resolve(result);
-})]).send();
+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 math = createWorker<MathWorker>(
+  new Worker(new URL('./math.worker.ts', import.meta.url), { type: 'module' })
+);
 ```
 
-In this way, you could avoid having to create more than once the same template for your worker.
+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.
 
-## Importing scripts into your _Workers_
+#### Your own pool
 
-Web Workers has this amazing method called importScripts, are you passed an array of strings in the EasyWorker extra configuration, all those files are gonna be imported into your worker.
+Pass an array of native Workers and calls are distributed across them:
 
-// test.js
+```ts
+const createMathWorker = () =>
+  new Worker(new URL('./math.worker.ts', import.meta.url), { type: 'module' });
 
-```TS
-self.message = 'Hello coders!';
-self.doSomething = () => console.log(self.message);
+const math = createWorker<MathWorker>([
+  createMathWorker(),
+  createMathWorker(),
+  createMathWorker(),
+]);
 ```
 
-```TS
-await createEasyWebWorker(({ onMessage }, context) => {
-  onMessage((message) => context.doSomething());
-}, {
-  scripts: ['http://localhost:3000/test.js'],
-}).send();
+#### A file you serve yourself
 
+A Worker script that is already built and public only needs its path:
+
+```ts
+const math = createWorker<MathWorker>('/workers/math.worker.js');
 ```
 
-This is a very simple example, but you could import a whole library into your worker, as _JQUERY_, _Bluebird_ for example
+#### A function, with no file at all
+
+```ts
+const math = createWorker(() => ({
+  double: (value: number) => value * 2,
+}));
+
+await math.double(21); // 42
+```
 
-## StaticEasyWebWorker
+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.
 
-If you want to create a _Worker_ with a static .js file and don't want to lose the structure of messages and promises and the onProgress callback from the library... you could use StaticEasyWebWorker<IPayload = null, IResult = void>\_ directly in your Worker.
+> **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/)
 
-let's see how to use it:
+---
 
-// worker.js
-// This is gonna be the content of your worker
-// onMessage Callback is gonna receive all _send_ method calls.
+### Worker pools
 
-```TS
-// imports only the static web worker
-import createStaticEasyWebWorker from 'easy-web-worker/createStaticEasyWebWorker';
+One Worker runs one task at a time. A pool runs several at once, behind the same object.
 
-//  this is gonna create the same message structure the runtime Workers
-const { onMessage } = createStaticEasyWebWorker();
+#### Scale on demand
 
-onMessage((message) => {
-  setTimeout(() => {
-    message.resolve(200);
-  }, 5000);
+```ts
+const math = createWorker<MathWorker>(source, {
+  maxWorkers: 4,
 });
 
-onMessage('action', (message) => {
-  setTimeout(() => {
-    message.resolve(200);
-  }, 5000);
+// three calls, three threads, at the same time
+const results = await Promise.all([
+  math.fibonacci(40),
+  math.fibonacci(41),
+  math.fibonacci(42),
+]);
+```
+
+The calling code does not change. It does not know whether one Worker or four are behind it.
+
+Workers are created as concurrent calls arrive, so an idle application pays for none of them.
+
+#### Warm up or release the pool
+
+```ts
+createWorker<MathWorker>(source, {
+  maxWorkers: 4,
+  warmUpWorkers: true, // create the whole pool up front, for the fastest first call
+});
+
+createWorker<MathWorker>(source, {
+  maxWorkers: 4,
+  keepAlive: false, // terminate idle Workers...
+  terminationDelay: 5_000, // ...after five seconds without work
 });
 ```
 
-By the way, if you're in need of a super simple static worker, just know that the first parameter of createStaticEasyWebWorker is a function which will be used as the default onmessage callback.
+#### Configuration
+
+| 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`     |
+
+The same options apply to `createWorker`, `createEasyWebWorker` and `new EasyWebWorker(...)`.
+
+> **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/)
+
+---
+
+### Runtime Workers: a function as the Worker
+
+Give `createWorker` a function instead of a file. No extra file, no bundler configuration.
+
+#### The Basics
 
 ```ts
-createStaticEasyWebWorker((message) => {
-  // this is the default onMessage
+import { createWorker } from 'easy-web-worker/createWorker';
+
+const math = createWorker(({ onMessage }) => {
+  const fibonacci = (n: number): number =>
+    n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
+
+  return {
+    fibonacci,
+
+    countTo: onMessage(async (limit: number, message) => {
+      for (let step = 1; step <= limit; step++) {
+        message.reportProgress((step * 100) / limit);
+      }
+
+      return limit;
+    }),
+  };
 });
+
+const result = await math.fibonacci(40); // 102334155
 ```
 
-and in your main thread:
+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.
+
+Everything else works the same: cancellation, progress, transferable objects, `unwrap`, and pools with `maxWorkers`.
+
+#### Worker scope
 
-```TS
-const worker = createEasyWebWorker<null,number>('./worker.js');
+The function becomes the source of a real Worker, so it **cannot use variables from outside**.
+
+```ts
+const greeting = 'Hello';
 
-await worker.send();
+createWorker(() => ({
+  // `greeting` does not exist inside the Worker
+  greet: (name: string) => `${greeting} ${name}`,
+}));
 ```
 
-Super easy right?
+Everything the Worker needs must be defined inside the function, imported as a script, sent as a payload, or passed through `primitiveParameters`.
 
-## Concurrency mode
+#### Parameters and the scope of the Worker
 
-With EasyWebWorker, you can create operations that require heavy concurrency and delegate them to a web workers queue, or create workers on demand depending on the traffic and specific tasks. Let's take a look:
+The second parameter is the global scope of the Worker. Static values arrive in `context.primitiveParameters`:
 
-```TS
-/**
- * Notice that the structure of the worker remains the same;
- * the only changes are in the configuration parameters of the worker.
- * Take a look below.*/
-const worker = createEasyWebWorker(({ onMessage }) => {
-  onMessage((message) => {
-    const { payload } = message;
+```ts
+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'
+```
+
+#### The message API inside the function
 
-    // heavy computation like fibonacci
+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.
 
-    message.resolve(result);
+```ts
+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);
+  });
+
+  // handler for messages sent without a method
+  easyWorker.onMessage((message) => {
+    message.resolve();
   });
-}, {
-  // We will now scale up to four workers if necessary.
-  maxWorkers: 4
+
+  return {
+    triple: (value: number) => value * 3,
+    shutdown: () => easyWorker.close(),
+  };
 });
+
+await worker.double(21); // 42
+await worker.triple(21); // 63
 ```
 
-By default, creating an **EasyWebWorker** also creates a single native JavaScript worker. Without any added configuration, this Worker instance will remain active unless it is programmatically disposed. However, by modifying the **maxWorkers** parameter, you can control the number of native workers used, allowing the **EasyWebWorker** to execute multiple messages across multiple threads.
+Only the returned methods are inferred. Handlers registered through `easyWorker` are described in the generic, as above, or called with `unwrap(worker).sendToMethod(...)`.
 
-You can also control whether these additional workers should be created on demand when messages are sent to the **EasyWebWorker**. This can be done along with setting the **terminationDelay**, which indicates how long to wait before disposing of a **Worker** to avoid unnecessary resource consumption. Alternatively, you can choose to **warmUp** and keep the Workers alive from the moment the **EasyWebWorker** is created.
+#### Import scripts
 
-From the main thread, the consumption of the worker remains the same. Depending on the configuration, the workers will be created either statically or on-demand as needed. The EasyWebWorker will be responsible for selecting them from a pool. Additionally, the EasyWebWorker will manage the distribution of messages among the available workers.
+External libraries load with the `scripts` option and appear in the scope of the Worker:
 
 ```ts
-// Since maxWorkers is configured to 4, a total of 3 native workers, will be created.
-const results = await Promise.all([
-  worker.send(payload),
-  worker.send(payload1),
-  worker.send(payload2),
-]);
+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'],
+  }
+);
+
+const changes = await text.compare({ before, after });
 ```
 
-In the previous example, since the **warmUp** parameter wasn’t included, only 3 Native workers will be created to handle the 3 messages, even though the maximum available is 4. Additionally, since the **keepAlive** parameter was not included, if a total of 1 second passes without new messages, the Native workers will be disposed of to save resources.
+No Worker file is required, and the script does not become part of your application bundle.
 
-## Want to see more?
+#### Compose a Worker from several functions
 
-Here is an example of how you could easily create data filter into a Worker, to avoid performing loops process into the main thread that could end affecting user experience.
+Pass an array and every function runs in the same Worker. They share its scope, and the methods they return are merged.
 
-```TS
-interface FilterSource {
-  filter: string,
-  collection: any[],
-  reportProgress: boolean,
-}
+```ts
+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;
+  },
 
-const worker = createEasyWebWorker<FilterSource, any[]>(({ onMessage }) => {
-  const containsValue = (item: any, filter: string): boolean => {
-    const itemKeys = Object.keys(item);
+  () => ({
+    double: (value: number) => value * 2,
+    describe: () => 'first',
+  }),
 
-    return itemKeys.some((key) => {
-      const prop = item[key] || null;
+  (_helpers, context) => {
+    const round = context.round as (value: number) => number;
 
-      if (typeof prop !== 'string' && Object.keys(prop).length) return containsValue(prop, filter);
-      if (prop.toString().replace(/(\r\n|\n|\r)/gm, '').trim().toLowerCase()
-        .indexOf(filter) !== -1) return true;
+    return {
+      average: (values: number[]) =>
+        round(values.reduce((total, value) => total + value, 0) / values.length),
 
-      return false;
-    });
-  };
+      // repeated method: the last function wins
+      describe: () => 'last',
+    };
+  },
+]);
 
-  onMessage((message: IEasyWebWorkerMessage<FilterSource, any[]>) => {
-    const { payload } = message;
-    const { collection, filter = '', reportProgress: countProgress } = payload;
-    const { length: collectionLength } = collection;
-    const result = filter === '' ? collection : [];
-    const progressPerItem = collectionLength ? 100 / collectionLength : 0;
+await worker.double(21); // 42
+await worker.average([1, 2, 2]); // 1.67
+await worker.describe(); // 'last'
+```
 
-    let currentProgress = 0;
+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.
 
-    if (filter) {
-      for (let index = 0; index < collectionLength; index += 1) {
-        if (countProgress) {
-          currentProgress += progressPerItem;
-          message.reportProgress(currentProgress);
-        }
+#### Runtime Workers with the message API
 
-        const item = collection[index];
+`createEasyWebWorker` builds a Worker from a function too, with messages instead of methods:
 
-        if (containsValue(item, filter)) result.push(item);
-      }
-    }
+```ts
+import { createEasyWebWorker } from 'easy-web-worker';
 
-    message.resolve(result);
+const worker = createEasyWebWorker<number, number>(({ onMessage }) => {
+  onMessage((message) => {
+    message.resolve(message.payload * 2);
   });
 });
+
+await worker.send(21); // 42
+```
+
+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.
+
+> **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/)
+
+---
+
+### The message API with `StaticEasyWebWorker`
+
+`defineWorker` is built on a message API that you can use directly, in Worker files and in runtime Workers.
+
+#### The Basics
+
+```ts
+// worker.ts
+import { createStaticEasyWebWorker } from 'easy-web-worker/createStaticEasyWebWorker';
+
+const { onMessage } = createStaticEasyWebWorker<number, number>((message) => {
+  message.resolve(message.payload * 2);
+});
+
+onMessage<string, string>('uppercase', (message) => {
+  message.resolve(message.payload.toUpperCase());
+});
 ```
 
-And how to use this?
+```ts
+// main.ts
+import { createEasyWebWorker } from 'easy-web-worker';
+
+const worker = createEasyWebWorker<number, number>(source);
 
-```TS
-worker.send({
-  collection: [{ name: 'julio perez' }, { name: 'carol starling' }, { name: 'goku' }, { name: { firstname: 'johnny' } }],
-  filter: 'johnny',
-  reportProgress: true,
-}).onProgress((progressPercentage) => console.log(progressPercentage))
-  .then((filtered: any[]) => console.log(filtered));
+await worker.send(21); // default handler
+await worker.sendToMethod<string, string>('uppercase', 'hello'); // result type first
 ```
 
-the output should be:
-=> 25
-=> 50
-=> 75
-=> 100
-=> [{ name: { firstname: 'johnny' } }]
+#### Typed methods for an existing Worker
 
-Of course this is a very tiny array, but is just to give you and idea, actually you also could make fetch requests into workers... give it a try.
+A Worker written with the message API can still be called with typed methods. Describe them:
 
-# Methods
+```ts
+const worker = createWorker<{ uppercase: (text: string) => string }>(source);
 
-### `EasyWebWorker.reboot(reason?: unknown): CancelableCancelablePromise<void>[]`
+await worker.uppercase('hello');
+```
 
-This method will reboot the worker and cancel all the messages in the queue.
+> **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/)
 
-- `reason` - (optional) reason why the worker will be restarted.
+---
 
-Returns an array of promises that are resolved with the rejection reason provided when the messages are canceled.
+## Advanced Patterns
 
-Example usage:
+### Latest request wins
 
-```typescript
-const worker = createEasyWebWorker<string, string>(({ onMessage }) => {
-  onMessage((message) => {
-    message.resolve(`Received message: ${message.payload}`);
-  });
-});
+For search, previews and autocomplete, an older request is worthless once a newer one exists.
 
-const messagePromise = worker.send('Hello!');
+```ts
+const search = createEasyWebWorker<string, SearchResult[]>(searchBody);
 
-worker.reboot('Worker was restarted');
+input.oninput = async () => {
+  // cancels what is pending, then sends the new message
+  const results = await search.override(input.value, 'Superseded');
 
-// The message promise will be rejected with the reason 'Worker was restarted'
+  render(results);
+};
 ```
 
-### override(payload?, reason?, config?): CancelablePromise
+`overrideAfterCurrent` lets the call in progress finish and replaces only what is waiting behind it.
 
-Cancel all current messages and send a new one.
+### Stop work that never pauses
 
-### cancelAll(reason?: unknown): CancelablePromise<void>[]
+A Worker stuck in a synchronous loop cannot receive a cancellation. Restart it instead:
 
-Cancels all messages that are currently waiting to be processed by the worker.
+```ts
+import { unwrap } from 'easy-web-worker/createWorker';
 
-- `reason` - (optional) The reason for the cancellation.
+// terminates the Workers, rejects the pending calls, starts fresh ones
+await unwrap(math).cancelAll('Taking too long', { force: true });
+```
 
-Returns an array of promises that are resolved with the rejection reason provided when the messages are canceled.
+### Clean up when the owner goes away
 
-### overrideAfterCurrent(payload?, reason?, config?): CancelablePromise
+```ts
+await unwrap(math).dispose(); // typed workers
+await worker.dispose(); // EasyWebWorker
+```
+
+`dispose` cancels the pending calls, revokes the generated Worker URL when there is one, and terminates the Workers.
+
+> **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/)
+
+---
+
+## Documentation and examples
+
+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.
+
+### See it before you install it
+
+| 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. |
+
+Every example shows its full source next to the running result.
+
+### Then go deeper
 
-Cancel all the messages but the current execution and add a new message
+| 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. |
 
-### send(payload?, reason?, config?): CancelablePromise
+---
 
-Sends a message to the worker
+## 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 |
+
+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.
+
+> **Write Worker code like an API, call it like normal asynchronous JavaScript, and scale it without rebuilding the communication layer.**
+
+---
+
+## Get Started Now
+
+```bash
+npm install easy-web-worker
+```
+
+Then in your Worker file:
+
+```ts
+import { defineWorker } from 'easy-web-worker/defineWorker';
 
-- `payload` - (optional) The message payload.
-- `options` - (optional) Additional send options.
+const fibonacci = (n: number): number =>
+  n <= 1 ? n : fibonacci(n - 1) + fibonacci(n - 2);
 
-**_Thanks for reading, hope this help someone_**
+const worker = defineWorker(() => ({ fibonacci }));
+
+export type MathWorker = typeof worker;
+```
+
+And in your app:
+
+```ts
+import { createWorker } from 'easy-web-worker/createWorker';
+import type { MathWorker } from './math.worker';
+
+const math = createWorker<MathWorker>(source);
+
+console.log(await math.fibonacci(40)); // 102334155
+```
+
+Continue with the [guides and interactive examples](https://johnny-quesada-developer.github.io/easy-web-worker/) to build your next worker.
+
+---
 
 ## Collaborators
 
-[![Image Johnny Quesada](https://avatars.githubusercontent.com/u/62082152?v=4&s=150)](https://github.com/johnny-quesada-developer)
-&nbsp;&nbsp;&nbsp;&nbsp;[![Image Gabriele Cirulli](https://avatars.githubusercontent.com/u/886011?v=4&s=150)](https://github.com/gabrielecirulli)
+<div align="center">
+
+<table>
+  <tr>
+    <td align="center">
+      <a href="https://github.com/johnny-quesada-developer">
+        <img src="https://avatars.githubusercontent.com/u/62082152?v=4&s=150" width="100" alt="Johnny Quesada" />
+        <br />
+        <sub><b>Johnny Quesada</b></sub>
+      </a>
+    </td>
+    <td align="center">
+      <a href="https://github.com/gabrielecirulli">
+        <img src="https://avatars.githubusercontent.com/u/886011?v=4&s=150" width="100" alt="Gabriele Cirulli" />
+        <br />
+        <sub><b>Gabriele Cirulli</b></sub>
+      </a>
+    </td>
+  </tr>
+</table>
+
+</div>
+
+---
+
+## Built by Johnny Quesada
+
+`easy-web-worker` exists because using another thread should not require building a messaging framework first.
+
+If it makes your codebase simpler, consider starring the project. It helps other developers discover it.
+
+[**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)
+
+## Earlier resources
+
+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/).
 
-[Johnny Quesada](https://github.com/johnny-quesada-developer) &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[Gabriele Cirulli](https://github.com/gabrielecirulli)
+- [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)