@angular-helpers/worker-http 21.0.0 → 21.2.0

package/README.md

@@ -88,6 +88,9 @@ Then follow the setup in the `/backend` section below.
 
 A framework-agnostic, type-safe bridge between the main thread and a Web Worker. Wraps `postMessage` with request/response correlation, Observable API, and automatic cancellation on unsubscribe.
 
+<details>
+<summary><strong>API and examples</strong></summary>
+
 ```typescript
 import { createWorkerTransport } from '@angular-helpers/worker-http/transport';
 
@@ -113,6 +116,11 @@ transport.terminate();
 - **Per-request timeout** (default `30_000` ms) via `requestTimeout`; errors
   with `WorkerHttpTimeoutError` and sends a cancel message to the worker.
   Set to `0` to disable.
+- **Per-call `AbortSignal` and `timeout` overrides** via the second argument
+  to `execute(request, { signal, timeout })`. The signal triggers a typed
+  `WorkerHttpAbortError`; an aborted-at-call-time signal fails fast with no
+  postMessage round-trip. Distinct error class from `WorkerHttpTimeoutError`
+  so consumers can branch on `instanceof`.
 - **Opt-in transferable detection** via `transferDetection: 'auto'` — passes
   detected `ArrayBuffer` / `MessagePort` / `ImageBitmap` /
   `OffscreenCanvas` / streams as the transfer list of `postMessage`, enabling
@@ -141,12 +149,17 @@ transport.execute(request).subscribe({
 });
 ```
 
+</details>
+
 ---
 
 ### `/interceptors` — Worker-side pipeline
 
 Pure-function interceptors that run inside the worker. No Angular DI, no DOM access — just `(req, next) => Promise<response>`.
 
+<details>
+<summary><strong>Setup, built-in interceptors, and custom interceptors</strong></summary>
+
 #### Setup in your worker file
 
 ```typescript
@@ -278,11 +291,22 @@ export const authTokenInterceptor: WorkerInterceptorFn = (req, next) => {
 };
 ```
 
+</details>
+
 ---
 
 ### `/serializer` — Pluggable serialization
 
-Handles the `postMessage` serialization boundary. Structured clone is zero-overhead but loses `Date`, `Map`, `Set` fidelity. `seroval` preserves full type fidelity. The auto-serializer picks the best strategy per payload.
+Handles the `postMessage` serialization boundary. Three strategies, each with a clear sweet spot:
+
+- `structuredCloneSerializer` — zero overhead, default
+- `createToonSerializer()` — 30–60% smaller for uniform arrays of objects
+- `createSerovalSerializer()` — full type fidelity (`Date`, `Map`, `Set`, circular refs)
+
+The auto-serializer picks the best strategy per payload.
+
+<details>
+<summary><strong>Per-strategy API and examples</strong></summary>
 
 #### `structuredCloneSerializer` (default)
 
@@ -311,14 +335,49 @@ const original = serializer.deserialize(payload);
 // original.tags instanceof Set → true
 ```
 
+#### `createToonSerializer()` — Token-Oriented Object Notation
+
+Requires `@toon-format/toon` as an optional peer dependency (`npm install @toon-format/toon`).
+
+[TOON](https://toonformat.dev) declares object keys once and emits values as CSV-like rows. For uniform arrays of objects (the most common API response shape — `User[]`, `Product[]`, paginated lists), it cuts payload size by **30–60%** compared to JSON, with negligible parsing overhead.
+
+```typescript
+import { createToonSerializer } from '@angular-helpers/worker-http/serializer';
+
+const serializer = await createToonSerializer();
+
+const payload = serializer.serialize([
+  { id: 1, name: 'Alice', role: 'admin' },
+  { id: 2, name: 'Bob', role: 'member' },
+  { id: 3, name: 'Carol', role: 'member' },
+  { id: 4, name: 'Dave', role: 'guest' },
+  { id: 5, name: 'Eve', role: 'admin' },
+]);
+
+// payload.data is a TOON string:
+//   [5]{id,name,role}:
+//     1,Alice,admin
+//     2,Bob,member
+//     3,Carol,member
+//     4,Dave,guest
+//     5,Eve,admin
+```
+
+**When TOON shines**: uniform arrays of objects with primitive values (numbers, strings, booleans, nulls) at depth-1.
+
+**When TOON does NOT help**: payloads with `Date`, `Map`, `Set`, nested objects, or single objects — use `seroval` or structured clone instead.
+
 #### `createAutoSerializer()` — Smart auto-detection
 
-Automatically picks the best strategy per payload. The factory is async (pre-loads `seroval` during initialization), but the returned serializer is fully synchronous.
+Automatically picks the best strategy per payload. The factory is async (pre-loads `seroval` and `@toon-format/toon` during initialization, both optional), but the returned serializer is fully synchronous.
 
-**Detection logic (depth-1):**
+**Detection logic (depth-1, top-down, first match wins):**
 
-- Contains `Date`, `Map`, `Set`, or `RegExp` at the top level or as direct array/object values → `seroval`
-- Otherwise → structured clone (zero overhead)
+1. Contains `Date`, `Map`, `Set`, or `RegExp` at the top level or as direct array/object values → `seroval`
+2. Uniform array of plain objects with primitive values, length ≥ 5 → `toon`
+3. Otherwise → structured clone (zero overhead)
+
+The TOON threshold is conservative (length ≥ 5). Smaller arrays don't justify the encoding overhead.
 
 Payloads larger than `transferThreshold` (default: 100 KiB) are encoded to `ArrayBuffer` and transferred zero-copy.
 
@@ -341,12 +400,17 @@ auto.serialize(hugeDataset); // transferables: [ArrayBuffer]
 
 > **Depth-1 limitation**: `[{ createdAt: new Date() }]` — the `Date` is inside a nested object; not detected at depth-1. For deeply nested complex types, use `createSerovalSerializer()` directly.
 
+</details>
+
 ---
 
 ### `/crypto` — WebCrypto primitives
 
 Standalone WebCrypto utilities. Useful in both workers and the main thread, but workers provide memory isolation for key material.
 
+<details>
+<summary><strong>HMAC, AES, hashing examples</strong></summary>
+
 #### `createHmacSigner(config)`
 
 ```typescript
@@ -381,12 +445,17 @@ const hasher = createContentHasher();
 const hash = await hasher.hash('SHA-256', data); // → hex string
 ```
 
+</details>
+
 ---
 
 ### `/backend` — Angular `HttpBackend` replacement
 
 Drop-in replacement for Angular's `HttpBackend` that transparently routes `HttpClient` requests to Web Workers. Use `WorkerHttpClient` exactly like `HttpClient` — the routing is invisible to application code.
 
+<details>
+<summary><strong>Configuration, providers, and consumer code</strong></summary>
+
 ```typescript
 // app.config.ts
 import {
@@ -470,17 +539,23 @@ manual control.
 - `withWorkerSerialization(serializer)` — plug in `createSerovalSerializer()` for complex request bodies (`Date`, `Map`, `Set`)
 - `withWorkerInterceptors(specs | specsByWorker)` — configure the worker-side pipeline from Angular DI; pairs with `createConfigurableWorkerPipeline()` in the worker file
 - `WORKER_TARGET` — `HttpContextToken<string | null>` for per-request worker routing via `HttpContext`
-- `WorkerHttpClient` — `HttpClient` wrapper with optional `{ worker: string }` routing field
+- `WorkerHttpClient` — `HttpClient` wrapper with optional `{ worker: string }` routing field, plus per-request `signal?: AbortSignal` and `timeout?: number` for cancellation. Aborted requests error with `WorkerHttpAbortError`; expired timeouts with `WorkerHttpTimeoutError`.
 - `WorkerHttpBackend` — the `HttpBackend` implementation (injectable for advanced use)
 - `matchWorkerRoute(url, routes)` — pure utility to test routing rules
+- `WORKER_HTTP_SIGNAL`, `WORKER_HTTP_TIMEOUT` — `HttpContextToken`s used internally by `WorkerHttpClient`; set them directly on the `HttpContext` if you're using `HttpClient` rather than the wrapper.
+
+</details>
 
 ---
 
 ## Telemetry
 
-Main-thread extension point for APM / metrics. `withTelemetry(...)` registers
-a subscriber that fires synchronously at three lifecycle points of every
-request handled by `WorkerHttpBackend`:
+Main-thread extension point for APM / metrics. `withTelemetry(...)` registers a subscriber that fires synchronously at three lifecycle points of every request handled by `WorkerHttpBackend` (`onRequest`, `onResponse`, `onError`).
+
+<details>
+<summary><strong>Subscriber semantics, examples, and event interface</strong></summary>
+
+Lifecycle points:
 
 - **`onRequest`** — after worker resolution, before dispatch
 - **`onResponse`** — when a successful response is emitted
@@ -547,12 +622,17 @@ interface WorkerHttpTelemetryEventBase {
 // onError    adds: kind: 'error',    error,  durationMs
 ```
 
+</details>
+
 ---
 
 ### `/esbuild-plugin` — Interceptor auto-bundling
 
 An esbuild plugin that automatically discovers and bundles interceptor files into your worker builds. When using Angular with a custom webpack/esbuild configuration, this ensures your interceptors are included in the worker bundle without manual imports.
 
+<details>
+<summary><strong>Plugin options and example</strong></summary>
+
 ```typescript
 // esbuild.config.ts
 import { workerHttpPlugin } from '@angular-helpers/worker-http/esbuild-plugin';
@@ -579,12 +659,17 @@ export default {
 
 Discovered interceptors are merged with explicit ones. Test files (`.spec.ts`, `.test.ts`) are automatically excluded.
 
+</details>
+
 ---
 
 ### `/streams-polyfill` — Safari transferable streams
 
 Safari 16-17 lack native transferable `ReadableStream`/`TransformStream` support. This ponyfill enables stream transfer in workers for those browsers, loaded lazily only when needed.
 
+<details>
+<summary><strong>Setup and bundle impact</strong></summary>
+
 ```typescript
 // Enable in your app config (main thread)
 import { withWorkerStreamsPolyfill } from '@angular-helpers/worker-http/backend';
@@ -602,12 +687,16 @@ provideWorkerHttpClient(
 
 **Bundle impact:** Zero for modern browsers. The polyfill is lazy-loaded only on affected Safari versions when streams are actually used.
 
+</details>
+
 ---
 
 ## SSR + hydration
 
-Worker HTTP integrates transparently with Angular SSR. The two problems SSR
-creates for worker-based HTTP are handled out of the box:
+Worker HTTP integrates transparently with Angular SSR. SSR's two problems for worker-based HTTP — missing `Worker` global on the server and the post-hydration re-fetch — are both handled out of the box.
+
+<details>
+<summary><strong>How SSR fallback and the transfer cache work</strong></summary>
 
 **1. Workers do not exist on the server.**
 During SSR, `typeof Worker === 'undefined'`. `WorkerHttpBackend` detects this
@@ -657,6 +746,8 @@ To customise which headers are captured or to cache `POST` requests, pass
 `withHttpTransferCacheOptions(...)` to `provideClientHydration()` — both are
 re-exported from `@angular/platform-browser`.
 
+</details>
+
 ---
 
 ## Design principles
@@ -671,13 +762,14 @@ re-exported from `@angular/platform-browser`.
 
 ## Serialization strategy decision guide
 
-| Payload type                         | Recommended serializer                 | Reason                      |
-| ------------------------------------ | -------------------------------------- | --------------------------- |
-| Simple objects, arrays of primitives | `structuredCloneSerializer` (default)  | Zero overhead               |
-| Objects with `Date`, `Map`, `Set`    | `createSerovalSerializer()`            | Full type fidelity          |
-| Unknown payload shape                | `createAutoSerializer()`               | Depth-1 auto-detect         |
-| Large arrays (> 100 KiB)             | `createAutoSerializer()`               | Auto ArrayBuffer transfer   |
-| Deeply nested complex types          | `createSerovalSerializer()` explicitly | Auto-detect is depth-1 only |
+| Payload type                               | Recommended serializer                 | Reason                      |
+| ------------------------------------------ | -------------------------------------- | --------------------------- |
+| Simple objects, arrays of primitives       | `structuredCloneSerializer` (default)  | Zero overhead               |
+| Uniform array of plain objects (≥ 5 items) | `createToonSerializer()`               | 30–60% size reduction       |
+| Objects with `Date`, `Map`, `Set`          | `createSerovalSerializer()`            | Full type fidelity          |
+| Unknown payload shape                      | `createAutoSerializer()`               | Depth-1 auto-detect         |
+| Large arrays (> 100 KiB)                   | `createAutoSerializer()`               | Auto ArrayBuffer transfer   |
+| Deeply nested complex types                | `createSerovalSerializer()` explicitly | Auto-detect is depth-1 only |
 
 ---
 
@@ -695,9 +787,12 @@ Server-Side Rendering (SSR) is supported via automatic fallback to the main thre
 
 ## Benchmarks
 
-A reproducible benchmark suite ships with the demo app at
-[`/demo/worker-http-benchmark`](../../src/app/demo/worker-http-benchmark) and compares three
-transport modes across four workloads:
+A reproducible benchmark suite ships with the demo app at [`/demo/worker-http-benchmark`](../../src/app/demo/worker-http-benchmark).
+
+<details>
+<summary><strong>Modes, workloads, metrics, and how to run</strong></summary>
+
+It compares three transport modes across four workloads:
 
 | Mode            | What it measures                                           |
 | --------------- | ---------------------------------------------------------- |
@@ -733,6 +828,8 @@ npm start
 Numbers vary by hardware, browser, and current system load — always run a scenario several times
 and watch the trend, not a single value.
 
+</details>
+
 ---
 
 ## Related documentation

package/fesm2022/angular-helpers-worker-http-backend.mjs

@@ -22,6 +22,31 @@ import { createWorkerTransport } from '@angular-helpers/worker-http/transport';
  * ```
  */
 const WORKER_TARGET = new HttpContextToken(() => null);
+/**
+ * Per-request HttpContextToken carrying an external `AbortSignal`.
+ *
+ * When the signal fires, the backend posts a `cancel` message to the worker
+ * and the request errors with `WorkerHttpAbortError` (wrapped by Angular into
+ * `HttpErrorResponse`).
+ *
+ * @example
+ * ```typescript
+ * const ac = new AbortController();
+ * this.http.get('/api/users', { signal: ac.signal });
+ * // later
+ * ac.abort();
+ * ```
+ */
+const WORKER_HTTP_SIGNAL = new HttpContextToken(() => null);
+/**
+ * Per-request HttpContextToken carrying a timeout in milliseconds.
+ *
+ * When set, overrides the transport-level `requestTimeout` for this single
+ * call. `0` or non-finite disables the timeout for this request only.
+ *
+ * On expiry the request errors with `WorkerHttpTimeoutError`.
+ */
+const WORKER_HTTP_TIMEOUT = new HttpContextToken(() => null);
 /**
  * Registered worker definitions provided via `withWorkerConfigs()`.
  */
@@ -188,7 +213,12 @@ class WorkerHttpBackend extends HttpBackend {
         const payload = body !== serializable.body ? { ...serializable, body } : serializable;
         const base = this.buildEventBase(req, workerId, 'worker');
         this.emitRequest(base);
-        return transport.execute(payload).pipe(map((res) => toHttpResponse(res, req)), tap((event) => {
+        const signal = req.context.get(WORKER_HTTP_SIGNAL) ?? undefined;
+        const timeout = req.context.get(WORKER_HTTP_TIMEOUT);
+        const executeOptions = signal !== undefined || timeout !== null
+            ? { signal, timeout: timeout ?? undefined }
+            : undefined;
+        return transport.execute(payload, executeOptions).pipe(map((res) => toHttpResponse(res, req)), tap((event) => {
             if (event instanceof HttpResponse) {
                 this.emitResponse(base, event.status);
             }
@@ -352,11 +382,15 @@ class WorkerHttpClient {
         return this.http.head(url, this.withWorker(options));
     }
     withWorker(options) {
-        const { worker = null, context, ...rest } = options ?? {};
-        return {
-            ...rest,
-            context: (context ?? new HttpContext()).set(WORKER_TARGET, worker),
-        };
+        const { worker = null, signal, timeout, context, ...rest } = options ?? {};
+        let ctx = (context ?? new HttpContext()).set(WORKER_TARGET, worker);
+        if (signal !== undefined) {
+            ctx = ctx.set(WORKER_HTTP_SIGNAL, signal);
+        }
+        if (timeout !== undefined) {
+            ctx = ctx.set(WORKER_HTTP_TIMEOUT, timeout);
+        }
+        return { ...rest, context: ctx };
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WorkerHttpClient, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WorkerHttpClient });
@@ -603,4 +637,4 @@ function withWorkerStreamsPolyfill() {
  * Generated bundle index. Do not edit.
  */
 
-export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_HTTP_STREAMS_POLYFILL_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withTelemetry, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization, withWorkerStreamsPolyfill };
+export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_HTTP_SIGNAL, WORKER_HTTP_STREAMS_POLYFILL_TOKEN, WORKER_HTTP_TIMEOUT, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withTelemetry, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization, withWorkerStreamsPolyfill };

package/fesm2022/angular-helpers-worker-http-serializer.mjs

@@ -71,6 +71,138 @@ async function createSerovalSerializer() {
     };
 }
 
+let cachedToon = null;
+async function loadToon() {
+    if (!cachedToon) {
+        try {
+            // Dynamic import via variable — keeps @toon-format/toon as optional peer dep (no static reference)
+            const id = '@toon-format/toon';
+            cachedToon = (await import(/* @vite-ignore */ id));
+        }
+        catch {
+            throw new Error('@toon-format/toon is required as a peer dependency. ' +
+                'Install it with: npm install @toon-format/toon');
+        }
+    }
+    return cachedToon;
+}
+/**
+ * Creates a `WorkerSerializer` backed by `@toon-format/toon` (Token-Oriented Object Notation).
+ *
+ * TOON is a compact, schema-aware encoding of the JSON data model that declares object
+ * keys once and emits values as CSV-like rows. It typically reduces size by **30–60%**
+ * for uniform arrays of objects (e.g. `User[]`, `Product[]`, paginated lists), with
+ * negligible parsing overhead.
+ *
+ * **When to use it**:
+ * - Worker↔main `postMessage` payloads dominated by uniform arrays of objects
+ * - Cases where `structuredClone` cost is dominated by repeated key strings
+ *
+ * **When NOT to use it**:
+ * - Payloads containing `Date`, `Map`, `Set`, `RegExp` (use `seroval` instead)
+ * - Small / single-object payloads (overhead not justified)
+ *
+ * The factory is async because it dynamically imports the optional `@toon-format/toon` peer.
+ *
+ * `@toon-format/toon` must be installed separately:
+ * ```
+ * npm install @toon-format/toon
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const serializer = await createToonSerializer();
+ * const payload = serializer.serialize([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ *   { id: 3, name: 'Carol' },
+ *   { id: 4, name: 'Dave' },
+ *   { id: 5, name: 'Eve' },
+ * ]);
+ * worker.postMessage({ payload }, payload.transferables);
+ * ```
+ *
+ * @see https://toonformat.dev
+ */
+async function createToonSerializer() {
+    const { encode, decode } = await loadToon();
+    return {
+        serialize(data) {
+            return {
+                data: encode(data),
+                transferables: [],
+                format: 'toon',
+            };
+        },
+        deserialize(payload) {
+            if (payload.format !== 'toon') {
+                throw new Error(`Expected format 'toon', got '${payload.format}'`);
+            }
+            return decode(payload.data);
+        },
+    };
+}
+/**
+ * Conservative threshold below which TOON's overhead outweighs its size benefit.
+ * Auto-serializer keeps shorter arrays on `structured-clone`.
+ *
+ * Exported for testing and for consumers building custom routing logic.
+ */
+const MIN_UNIFORM_ARRAY_LENGTH = 5;
+/**
+ * Detects whether a value is a depth-1 uniform array of plain objects with primitive values.
+ *
+ * Pure function — no side effects. Used by `createAutoSerializer()` to decide
+ * whether to route a payload through TOON.
+ *
+ * Conditions checked (all must pass):
+ * 1. Value is an array with `length >= MIN_UNIFORM_ARRAY_LENGTH`
+ * 2. Every item is a non-null, non-array plain object
+ * 3. Every item has the same set of keys as the first item
+ * 4. Every value across all items is a primitive (string, number, boolean, null)
+ *
+ * @example
+ * ```typescript
+ * isUniformObjectArray([{a:1},{a:2},{a:3},{a:4},{a:5}]); // true
+ * isUniformObjectArray([{a:1},{b:2}]);                    // false (heterogeneous keys)
+ * isUniformObjectArray([{a:[1,2]},{a:[3,4]}]);            // false (nested array value)
+ * isUniformObjectArray([{a:1}]);                          // false (length < 5)
+ * ```
+ */
+function isUniformObjectArray(value) {
+    if (!Array.isArray(value) || value.length < MIN_UNIFORM_ARRAY_LENGTH) {
+        return false;
+    }
+    const first = value[0];
+    if (first === null || typeof first !== 'object' || Array.isArray(first)) {
+        return false;
+    }
+    const expectedKeys = Object.keys(first)
+        .sort()
+        .join('\u0000');
+    if (expectedKeys === '') {
+        return false;
+    }
+    for (const item of value) {
+        if (item === null || typeof item !== 'object' || Array.isArray(item)) {
+            return false;
+        }
+        const record = item;
+        if (Object.keys(record).sort().join('\u0000') !== expectedKeys) {
+            return false;
+        }
+        for (const v of Object.values(record)) {
+            if (v === null)
+                continue;
+            const t = typeof v;
+            if (t !== 'string' && t !== 'number' && t !== 'boolean') {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+
 /**
  * Shallow check for complex types at depth-1 that structured-clone cannot preserve.
  * Depth-1 is intentional: fast and predictable. For deeply nested complex types,
@@ -107,9 +239,11 @@ function encodeToTransferable(str) {
  * The factory is async because it pre-loads `seroval` during initialization
  * so the returned serializer methods are fully synchronous (no await in hot path).
  *
- * Strategy selection per `serialize()` call:
- * - Contains `Date`, `Map`, `Set`, or `RegExp` at depth-1 → `seroval` (full fidelity)
- * - Otherwise → structured clone (native, zero overhead)
+ * Strategy selection per `serialize()` call (top-down, first match wins):
+ * 1. Contains `Date`, `Map`, `Set`, or `RegExp` at depth-1 → `seroval` (full fidelity)
+ * 2. Uniform array of plain objects (length ≥ 5, primitive values, identical key set)
+ *    → `toon` (30–60% size reduction)
+ * 3. Otherwise → structured clone (native, zero overhead)
  *
  * Large payloads (> `transferThreshold`, default 100 KiB) are encoded to
  * `ArrayBuffer` and added to `transferables` for zero-copy `postMessage` transfer.
@@ -130,6 +264,13 @@ async function createAutoSerializer(config) {
     catch {
         // seroval not installed — complex types will throw at serialize time with a clear message
     }
+    let toon = null;
+    try {
+        toon = await createToonSerializer();
+    }
+    catch {
+        // @toon-format/toon not installed — uniform arrays will fall back to structured-clone
+    }
     return {
         serialize(data) {
             let payload;
@@ -140,6 +281,9 @@ async function createAutoSerializer(config) {
                 }
                 payload = sv.serialize(data);
             }
+            else if (toon && isUniformObjectArray(data)) {
+                payload = toon.serialize(data);
+            }
             else {
                 payload = structuredCloneSerializer.serialize(data);
             }
@@ -168,6 +312,13 @@ async function createAutoSerializer(config) {
                 }
                 return sv.deserialize(resolved);
             }
+            if (resolved.format === 'toon') {
+                if (!toon) {
+                    throw new Error('@toon-format/toon is required to deserialize this payload. ' +
+                        'Install it with: npm install @toon-format/toon');
+                }
+                return toon.deserialize(resolved);
+            }
             throw new Error(`Unknown serialization format: '${resolved.format}'`);
         },
     };
@@ -177,4 +328,4 @@ async function createAutoSerializer(config) {
  * Generated bundle index. Do not edit.
  */
 
-export { createAutoSerializer, createSerovalSerializer, structuredCloneSerializer };
+export { MIN_UNIFORM_ARRAY_LENGTH, createAutoSerializer, createSerovalSerializer, createToonSerializer, isUniformObjectArray, structuredCloneSerializer };

package/fesm2022/angular-helpers-worker-http-transport.mjs

@@ -74,6 +74,41 @@ function isTransferable(value) {
     return false;
 }
 
+/**
+ * Thrown by `createWorkerTransport` when a request is aborted via an external
+ * `AbortSignal` passed to `execute(request, { signal })`.
+ *
+ * Distinct from `WorkerHttpTimeoutError` (which fires when the per-request
+ * `timeout` elapses) and from a silent unsubscribe (which sends a `cancel`
+ * message but does not surface an error to the subscriber, since RxJS already
+ * tore down the stream).
+ *
+ * @example
+ * ```typescript
+ * const ac = new AbortController();
+ * transport.execute(req, { signal: ac.signal }).subscribe({
+ *   error: (err) => {
+ *     if (err instanceof WorkerHttpAbortError) {
+ *       // user-driven cancellation; usually safe to ignore in UI
+ *     }
+ *   },
+ * });
+ * ac.abort('user navigated away');
+ * ```
+ */
+class WorkerHttpAbortError extends Error {
+    name = 'WorkerHttpAbortError';
+    /** The reason passed to `AbortController.abort(reason)`, if any. */
+    reason;
+    constructor(reason) {
+        super(reason === undefined
+            ? 'Worker request aborted'
+            : `Worker request aborted: ${reason instanceof Error ? reason.message : String(reason)}`);
+        this.reason = reason;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
 /**
  * Thrown by `createWorkerTransport` when a request exceeds its configured
  * `requestTimeout`. Consumers can `instanceof`-check this error to distinguish
@@ -161,14 +196,22 @@ function createWorkerTransport(config) {
         roundRobinIndex++;
         return worker;
     }
-    function execute(request) {
+    function execute(request, options) {
         if (terminated) {
             return new Observable((subscriber) => {
                 subscriber.error(new Error('WorkerTransport has been terminated'));
             });
         }
         const requestId = crypto.randomUUID();
+        const externalSignal = options?.signal;
+        const effectiveTimeout = options?.timeout ?? requestTimeout;
         return new Observable((subscriber) => {
+            // Fail-fast: if the caller's signal was already aborted before we even
+            // touched a worker, surface it immediately with no postMessage roundtrip.
+            if (externalSignal?.aborted) {
+                subscriber.error(new WorkerHttpAbortError(externalSignal.reason));
+                return () => undefined;
+            }
             // Lazy-load polyfill on first request if enabled
             if (streamsPolyfill && !polyfillLoaded) {
                 loadStreamsPolyfill().catch((err) => {
@@ -178,6 +221,7 @@ function createWorkerTransport(config) {
             const worker = getOrCreateWorker();
             let settled = false;
             let timeoutHandle;
+            let abortListener;
             const cleanup = () => {
                 worker.removeEventListener('message', messageHandler);
                 worker.removeEventListener('error', errorHandler);
@@ -185,6 +229,10 @@ function createWorkerTransport(config) {
                     clearTimeout(timeoutHandle);
                     timeoutHandle = undefined;
                 }
+                if (abortListener && externalSignal) {
+                    externalSignal.removeEventListener('abort', abortListener);
+                    abortListener = undefined;
+                }
             };
             const messageHandler = (event) => {
                 const data = event.data;
@@ -219,7 +267,7 @@ function createWorkerTransport(config) {
             else {
                 worker.postMessage({ type: 'request', requestId, payload: request });
             }
-            if (requestTimeout > 0 && Number.isFinite(requestTimeout)) {
+            if (effectiveTimeout > 0 && Number.isFinite(effectiveTimeout)) {
                 timeoutHandle = setTimeout(() => {
                     if (settled)
                         return;
@@ -228,8 +276,23 @@ function createWorkerTransport(config) {
                     // Ask the worker to abort any in-flight work for this id. The
                     // cancellation fix wires this through to `fetch()`.
                     worker.postMessage({ type: 'cancel', requestId });
-                    subscriber.error(new WorkerHttpTimeoutError(requestTimeout));
-                }, requestTimeout);
+                    subscriber.error(new WorkerHttpTimeoutError(effectiveTimeout));
+                }, effectiveTimeout);
+            }
+            // External AbortSignal: surface a typed abort error and cancel the
+            // worker-side fetch. Distinct from a silent unsubscribe (no error) and
+            // from a timeout (different error type).
+            if (externalSignal) {
+                abortListener = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    const reason = externalSignal.reason;
+                    cleanup();
+                    worker.postMessage({ type: 'cancel', requestId });
+                    subscriber.error(new WorkerHttpAbortError(reason));
+                };
+                externalSignal.addEventListener('abort', abortListener, { once: true });
             }
             // Teardown: send cancel message on unsubscribe
             return () => {
@@ -284,4 +347,4 @@ function createWorkerTransport(config) {
  * Generated bundle index. Do not edit.
  */
 
-export { WorkerHttpTimeoutError, createWorkerTransport, detectTransferables };
+export { WorkerHttpAbortError, WorkerHttpTimeoutError, createWorkerTransport, detectTransferables };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-helpers/worker-http",
-  "version": "21.0.0",
+  "version": "21.2.0",
   "description": "Angular HTTP over Web Workers — off-main-thread HTTP pipelines with configurable interceptors, WebCrypto security, and pluggable serialization",
   "schematics": "./schematics/collection.json",
   "exports": {
@@ -76,7 +76,8 @@
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
     "rxjs": "^7.0.0",
-    "seroval": "^1.0.0"
+    "seroval": "^1.0.0",
+    "@toon-format/toon": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "@angular/common": {
@@ -88,6 +89,9 @@
     "seroval": {
       "optional": true
     },
+    "@toon-format/toon": {
+      "optional": true
+    },
     "esbuild": {
       "optional": true
     },

package/types/angular-helpers-worker-http-backend.d.ts

@@ -168,6 +168,31 @@ type WorkerInterceptorSpecsMap = Readonly<Record<string, readonly WorkerIntercep
  * ```
  */
 declare const WORKER_TARGET: HttpContextToken<string>;
+/**
+ * Per-request HttpContextToken carrying an external `AbortSignal`.
+ *
+ * When the signal fires, the backend posts a `cancel` message to the worker
+ * and the request errors with `WorkerHttpAbortError` (wrapped by Angular into
+ * `HttpErrorResponse`).
+ *
+ * @example
+ * ```typescript
+ * const ac = new AbortController();
+ * this.http.get('/api/users', { signal: ac.signal });
+ * // later
+ * ac.abort();
+ * ```
+ */
+declare const WORKER_HTTP_SIGNAL: HttpContextToken<AbortSignal>;
+/**
+ * Per-request HttpContextToken carrying a timeout in milliseconds.
+ *
+ * When set, overrides the transport-level `requestTimeout` for this single
+ * call. `0` or non-finite disables the timeout for this request only.
+ *
+ * On expiry the request errors with `WorkerHttpTimeoutError`.
+ */
+declare const WORKER_HTTP_TIMEOUT: HttpContextToken<number>;
 /**
  * Optional serializer for crossing the worker boundary.
  * Provided via `withWorkerSerialization()`. Defaults to `null` (structured clone).
@@ -422,6 +447,20 @@ declare class WorkerHttpBackend extends HttpBackend implements OnDestroy {
 interface WorkerRequestOptions {
     /** Target worker ID. Overrides URL-pattern routing for this specific request. */
     worker?: string | null;
+    /**
+     * External `AbortSignal`. When it fires, the backend posts a `cancel` to
+     * the worker and the request errors with `WorkerHttpAbortError` (wrapped in
+     * `HttpErrorResponse`). Useful with `AbortController` or
+     * `takeUntilDestroyed()`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Per-request timeout in milliseconds. Overrides the transport-level
+     * `requestTimeout` for this single call. On expiry the request errors with
+     * `WorkerHttpTimeoutError`. `0` or non-finite disables the timeout for this
+     * request only.
+     */
+    timeout?: number;
     context?: HttpContext;
     headers?: Record<string, string | string[]>;
     params?: Record<string, string | number | boolean | ReadonlyArray<string | number | boolean>>;
@@ -494,5 +533,5 @@ declare function matchWorkerRoute(url: string, routes: Array<{
     priority?: number;
 }>): string | null;
 
-export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_HTTP_STREAMS_POLYFILL_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withTelemetry, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization, withWorkerStreamsPolyfill };
+export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_HTTP_SIGNAL, WORKER_HTTP_STREAMS_POLYFILL_TOKEN, WORKER_HTTP_TIMEOUT, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withTelemetry, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization, withWorkerStreamsPolyfill };
 export type { SerializableRequest, SerializableResponse, WorkerConfig, WorkerFallbackStrategy, WorkerHttpErrorEvent, WorkerHttpFeature, WorkerHttpFeatureKind, WorkerHttpRequestEvent, WorkerHttpResponseEvent, WorkerHttpTelemetry, WorkerHttpTelemetryEventBase, WorkerHttpTransportKind, WorkerInterceptorSpecsMap, WorkerRequestOptions, WorkerRoute };

package/types/angular-helpers-worker-http-serializer.d.ts

@@ -63,15 +63,85 @@ declare const structuredCloneSerializer: WorkerSerializer;
  */
 declare function createSerovalSerializer(): Promise<WorkerSerializer>;
 
+/**
+ * Creates a `WorkerSerializer` backed by `@toon-format/toon` (Token-Oriented Object Notation).
+ *
+ * TOON is a compact, schema-aware encoding of the JSON data model that declares object
+ * keys once and emits values as CSV-like rows. It typically reduces size by **30–60%**
+ * for uniform arrays of objects (e.g. `User[]`, `Product[]`, paginated lists), with
+ * negligible parsing overhead.
+ *
+ * **When to use it**:
+ * - Worker↔main `postMessage` payloads dominated by uniform arrays of objects
+ * - Cases where `structuredClone` cost is dominated by repeated key strings
+ *
+ * **When NOT to use it**:
+ * - Payloads containing `Date`, `Map`, `Set`, `RegExp` (use `seroval` instead)
+ * - Small / single-object payloads (overhead not justified)
+ *
+ * The factory is async because it dynamically imports the optional `@toon-format/toon` peer.
+ *
+ * `@toon-format/toon` must be installed separately:
+ * ```
+ * npm install @toon-format/toon
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const serializer = await createToonSerializer();
+ * const payload = serializer.serialize([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' },
+ *   { id: 3, name: 'Carol' },
+ *   { id: 4, name: 'Dave' },
+ *   { id: 5, name: 'Eve' },
+ * ]);
+ * worker.postMessage({ payload }, payload.transferables);
+ * ```
+ *
+ * @see https://toonformat.dev
+ */
+declare function createToonSerializer(): Promise<WorkerSerializer>;
+/**
+ * Conservative threshold below which TOON's overhead outweighs its size benefit.
+ * Auto-serializer keeps shorter arrays on `structured-clone`.
+ *
+ * Exported for testing and for consumers building custom routing logic.
+ */
+declare const MIN_UNIFORM_ARRAY_LENGTH = 5;
+/**
+ * Detects whether a value is a depth-1 uniform array of plain objects with primitive values.
+ *
+ * Pure function — no side effects. Used by `createAutoSerializer()` to decide
+ * whether to route a payload through TOON.
+ *
+ * Conditions checked (all must pass):
+ * 1. Value is an array with `length >= MIN_UNIFORM_ARRAY_LENGTH`
+ * 2. Every item is a non-null, non-array plain object
+ * 3. Every item has the same set of keys as the first item
+ * 4. Every value across all items is a primitive (string, number, boolean, null)
+ *
+ * @example
+ * ```typescript
+ * isUniformObjectArray([{a:1},{a:2},{a:3},{a:4},{a:5}]); // true
+ * isUniformObjectArray([{a:1},{b:2}]);                    // false (heterogeneous keys)
+ * isUniformObjectArray([{a:[1,2]},{a:[3,4]}]);            // false (nested array value)
+ * isUniformObjectArray([{a:1}]);                          // false (length < 5)
+ * ```
+ */
+declare function isUniformObjectArray(value: unknown): boolean;
+
 /**
  * Creates an auto-detecting `WorkerSerializer` that picks the best strategy per payload.
  *
  * The factory is async because it pre-loads `seroval` during initialization
  * so the returned serializer methods are fully synchronous (no await in hot path).
  *
- * Strategy selection per `serialize()` call:
- * - Contains `Date`, `Map`, `Set`, or `RegExp` at depth-1 → `seroval` (full fidelity)
- * - Otherwise → structured clone (native, zero overhead)
+ * Strategy selection per `serialize()` call (top-down, first match wins):
+ * 1. Contains `Date`, `Map`, `Set`, or `RegExp` at depth-1 → `seroval` (full fidelity)
+ * 2. Uniform array of plain objects (length ≥ 5, primitive values, identical key set)
+ *    → `toon` (30–60% size reduction)
+ * 3. Otherwise → structured clone (native, zero overhead)
  *
  * Large payloads (> `transferThreshold`, default 100 KiB) are encoded to
  * `ArrayBuffer` and added to `transferables` for zero-copy `postMessage` transfer.
@@ -85,5 +155,5 @@ declare function createSerovalSerializer(): Promise<WorkerSerializer>;
  */
 declare function createAutoSerializer(config?: AutoSerializerConfig): Promise<WorkerSerializer>;
 
-export { createAutoSerializer, createSerovalSerializer, structuredCloneSerializer };
+export { MIN_UNIFORM_ARRAY_LENGTH, createAutoSerializer, createSerovalSerializer, createToonSerializer, isUniformObjectArray, structuredCloneSerializer };
 export type { AutoSerializerConfig, SerializedPayload, SerializerStrategy, WorkerSerializer };

package/types/angular-helpers-worker-http-transport.d.ts

@@ -109,13 +109,26 @@ interface WorkerErrorResponse {
         statusText?: string;
     };
 }
+/**
+ * Per-request options accepted by `WorkerTransport.execute()`.
+ *
+ * - `signal` — external `AbortSignal`. When it fires, the transport posts a
+ *   `cancel` message to the worker and rejects the Observable with
+ *   `WorkerHttpAbortError`.
+ * - `timeout` — overrides the transport-level `requestTimeout` for this single
+ *   call. `0` or non-finite disables the timeout for this request.
+ */
+interface WorkerExecuteOptions {
+    signal?: AbortSignal;
+    timeout?: number;
+}
 /**
  * Typed transport interface for communicating with a web worker.
  * Observable-based: unsubscribing sends a cancel message to the worker.
  */
 interface WorkerTransport<TRequest = unknown, TResponse = unknown> {
     /** Send a request to the worker and get an Observable response */
-    execute(request: TRequest): Observable<TResponse>;
+    execute(request: TRequest, options?: WorkerExecuteOptions): Observable<TResponse>;
     /** Terminate all workers and release resources */
     terminate(): void;
     /** Whether the transport has active workers */
@@ -173,6 +186,35 @@ declare class WorkerHttpTimeoutError extends Error {
     constructor(timeoutMs: number);
 }
 
+/**
+ * Thrown by `createWorkerTransport` when a request is aborted via an external
+ * `AbortSignal` passed to `execute(request, { signal })`.
+ *
+ * Distinct from `WorkerHttpTimeoutError` (which fires when the per-request
+ * `timeout` elapses) and from a silent unsubscribe (which sends a `cancel`
+ * message but does not surface an error to the subscriber, since RxJS already
+ * tore down the stream).
+ *
+ * @example
+ * ```typescript
+ * const ac = new AbortController();
+ * transport.execute(req, { signal: ac.signal }).subscribe({
+ *   error: (err) => {
+ *     if (err instanceof WorkerHttpAbortError) {
+ *       // user-driven cancellation; usually safe to ignore in UI
+ *     }
+ *   },
+ * });
+ * ac.abort('user navigated away');
+ * ```
+ */
+declare class WorkerHttpAbortError extends Error {
+    readonly name = "WorkerHttpAbortError";
+    /** The reason passed to `AbortController.abort(reason)`, if any. */
+    readonly reason: unknown;
+    constructor(reason?: unknown);
+}
+
 /**
  * Scans a payload one level deep and collects every `Transferable` instance
  * (ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas, ReadableStream,
@@ -193,5 +235,5 @@ declare class WorkerHttpTimeoutError extends Error {
  */
 declare function detectTransferables(payload: unknown): Transferable[];
 
-export { WorkerHttpTimeoutError, createWorkerTransport, detectTransferables };
-export type { WorkerErrorResponse, WorkerMessage, WorkerResponse, WorkerTransport, WorkerTransportConfig };
+export { WorkerHttpAbortError, WorkerHttpTimeoutError, createWorkerTransport, detectTransferables };
+export type { WorkerErrorResponse, WorkerExecuteOptions, WorkerMessage, WorkerResponse, WorkerTransport, WorkerTransportConfig };