@angular-helpers/worker-http 0.6.0 → 1.0.0

package/README.md

@@ -16,13 +16,15 @@ On top of that, workers provide a natural isolation boundary for security-sensit
 
 ## Package map
 
-| Entry point                                 | Description                                                      | Status       |
-| ------------------------------------------- | ---------------------------------------------------------------- | ------------ |
-| `@angular-helpers/worker-http/transport`    | Typed RPC bridge, round-robin pool, cancellation                 | ✅ Available |
-| `@angular-helpers/worker-http/serializer`   | Pluggable serialization (structured clone, seroval, auto-detect) | ✅ Available |
-| `@angular-helpers/worker-http/interceptors` | Pure-function interceptor pipeline for workers                   | ✅ Available |
-| `@angular-helpers/worker-http/crypto`       | WebCrypto primitives (HMAC, AES-GCM, SHA hashing)                | ✅ Available |
-| `@angular-helpers/worker-http/backend`      | Angular `HttpBackend` replacement — `provideWorkerHttpClient()`  | ✅ Available |
+| Entry point                                     | Description                                                      | Status       |
+| ----------------------------------------------- | ---------------------------------------------------------------- | ------------ |
+| `@angular-helpers/worker-http/transport`        | Typed RPC bridge, round-robin pool, cancellation                 | ✅ Available |
+| `@angular-helpers/worker-http/serializer`       | Pluggable serialization (structured clone, seroval, auto-detect) | ✅ Available |
+| `@angular-helpers/worker-http/interceptors`     | Pure-function interceptor pipeline for workers                   | ✅ Available |
+| `@angular-helpers/worker-http/crypto`           | WebCrypto primitives (HMAC, AES-GCM, SHA hashing)                | ✅ Available |
+| `@angular-helpers/worker-http/backend`          | Angular `HttpBackend` replacement — `provideWorkerHttpClient()`  | ✅ Available |
+| `@angular-helpers/worker-http/esbuild-plugin`   | esbuild plugin for auto-bundling interceptors into workers       | ✅ Available |
+| `@angular-helpers/worker-http/streams-polyfill` | Safari streams ponyfill for transferable stream support          | ✅ Available |
 
 ---
 
@@ -43,6 +45,43 @@ Angular HttpClient                   createWorkerPipeline([
 
 ---
 
+## Installation
+
+### Quick setup with ng-add
+
+The easiest way to get started is using the Angular CLI schematic:
+
+```bash
+ng add @angular-helpers/worker-http
+```
+
+This will:
+
+1. Install the package
+2. Create a worker file at `src/app/workers/http-api.worker.ts`
+3. Update `tsconfig.json` with webworker lib
+4. Add `provideWorkerHttpClient()` to your `app.config.ts`
+
+**Options:**
+
+```bash
+# Custom worker path
+ng add @angular-helpers/worker-http --workerPath=src/workers/api.worker.ts
+
+# Configure esbuild plugin (for custom build setups)
+ng add @angular-helpers/worker-http --installEsbuildPlugin=true
+```
+
+### Manual installation
+
+```bash
+npm install @angular-helpers/worker-http
+```
+
+Then follow the setup in the `/backend` section below.
+
+---
+
 ## Entry points
 
 ### `/transport` — Typed RPC bridge
@@ -67,9 +106,40 @@ transport.terminate();
 **Features:**
 
 - Round-robin pool (`maxInstances`) for parallel request handling
-- Request cancellation via `AbortController` in the worker
-- Automatic `Transferable` detection for zero-copy `ArrayBuffer` transfer
 - Lazy worker instantiation — no worker created until first request
+- **Cancellation that actually aborts `fetch()`** — unsubscribing posts a
+  cancel message; the worker-side message loop threads an `AbortSignal` all
+  the way into `fetch()` so the in-flight HTTP request is truly aborted
+- **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.
+- **Opt-in transferable detection** via `transferDetection: 'auto'` — passes
+  detected `ArrayBuffer` / `MessagePort` / `ImageBitmap` /
+  `OffscreenCanvas` / streams as the transfer list of `postMessage`, enabling
+  zero-copy transfer of large buffers. Default is `'none'` to preserve the
+  caller's access to the original data after post.
+
+```typescript
+import {
+  createWorkerTransport,
+  WorkerHttpTimeoutError,
+} from '@angular-helpers/worker-http/transport';
+
+const transport = createWorkerTransport({
+  workerUrl: new URL('./workers/api.worker', import.meta.url),
+  maxInstances: 2,
+  requestTimeout: 10_000, // override default 30 s
+  transferDetection: 'auto', // zero-copy ArrayBuffer at postMessage
+});
+
+transport.execute(request).subscribe({
+  error: (err) => {
+    if (err instanceof WorkerHttpTimeoutError) {
+      // dedicated timeout handling
+    }
+  },
+});
+```
 
 ---
 
@@ -479,6 +549,61 @@ interface WorkerHttpTelemetryEventBase {
 
 ---
 
+### `/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.
+
+```typescript
+// esbuild.config.ts
+import { workerHttpPlugin } from '@angular-helpers/worker-http/esbuild-plugin';
+
+export default {
+  plugins: [
+    workerHttpPlugin({
+      // Explicit interceptors (relative to project root)
+      interceptors: ['./src/interceptors/auth.ts', './src/interceptors/logging.ts'],
+
+      // Or auto-discover all files matching interceptor naming pattern
+      autoDiscover: true,
+    }),
+  ],
+};
+```
+
+**Options:**
+
+| Option         | Type       | Default | Description                                            |
+| -------------- | ---------- | ------- | ------------------------------------------------------ |
+| `interceptors` | `string[]` | `[]`    | Explicit list of interceptor paths to bundle           |
+| `autoDiscover` | `boolean`  | `false` | Scan `src/` for files matching `*interceptor*` pattern |
+
+Discovered interceptors are merged with explicit ones. Test files (`.spec.ts`, `.test.ts`) are automatically excluded.
+
+---
+
+### `/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.
+
+```typescript
+// Enable in your app config (main thread)
+import { withWorkerStreamsPolyfill } from '@angular-helpers/worker-http/backend';
+
+provideWorkerHttpClient(
+  withWorkerConfigs([...]),
+  withWorkerStreamsPolyfill(), // Enable Safari 16-17 compatibility
+);
+```
+
+**When to use:**
+
+- Your app uses `responseType: 'stream'` and targets Safari 16-17
+- You see `DataCloneError` when transferring streams to/from workers
+
+**Bundle impact:** Zero for modern browsers. The polyfill is lazy-loaded only on affected Safari versions when streams are actually used.
+
+---
+
 ## SSR + hydration
 
 Worker HTTP integrates transparently with Angular SSR. The two problems SSR

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

@@ -62,6 +62,15 @@ const WORKER_HTTP_INTERCEPTORS_TOKEN = new InjectionToken('WorkerHttpInterceptor
  * affects the HTTP request).
  */
 const WORKER_HTTP_TELEMETRY_TOKEN = new InjectionToken('WorkerHttpTelemetry', { factory: () => [] });
+/**
+ * Enable Safari streams polyfill for transferable ReadableStream/TransformStream
+ * support in workers. Provided via `withWorkerStreamsPolyfill()`.
+ * Defaults to `false` (native streams only).
+ *
+ * When enabled, the transport dynamically imports `@angular-helpers/worker-http/streams-polyfill`
+ * on Safari 16-17 to enable stream transfer via postMessage.
+ */
+const WORKER_HTTP_STREAMS_POLYFILL_TOKEN = new InjectionToken('WorkerHttpStreamsPolyfill', { factory: () => false });
 
 /**
  * Converts an Angular `HttpRequest` into a structured-clone-safe POJO
@@ -156,6 +165,7 @@ class WorkerHttpBackend extends HttpBackend {
     interceptorSpecs = inject(WORKER_HTTP_INTERCEPTORS_TOKEN);
     fetchBackend = inject(FetchBackend, { optional: true });
     telemetry = inject(WORKER_HTTP_TELEMETRY_TOKEN);
+    streamsPolyfill = inject(WORKER_HTTP_STREAMS_POLYFILL_TOKEN);
     transports = new Map();
     handle(req) {
         if (typeof Worker === 'undefined') {
@@ -208,6 +218,7 @@ class WorkerHttpBackend extends HttpBackend {
             workerFactory: () => new Worker(config.workerUrl, { type: 'module' }),
             maxInstances: config.maxInstances ?? 1,
             initMessage: specs.length > 0 ? { type: 'init-interceptors', specs } : undefined,
+            streamsPolyfill: this.streamsPolyfill,
         });
         this.transports.set(config.id, transport);
         return transport;
@@ -285,6 +296,7 @@ class WorkerHttpBackend extends HttpBackend {
             }
             catch (telemetryError) {
                 // A throwing telemetry subscriber must never affect the HTTP request.
+                // oxlint-disable-next-line no-console -- defensive log when user-provided telemetry throws
                 console.error('[WorkerHttpBackend] telemetry subscriber threw:', telemetryError);
             }
         }
@@ -557,9 +569,38 @@ function withTelemetry(telemetry) {
         providers: [{ provide: WORKER_HTTP_TELEMETRY_TOKEN, useValue: telemetry, multi: true }],
     };
 }
+/**
+ * Enables the Safari streams polyfill for transferable ReadableStream/TransformStream
+ * support in Web Workers.
+ *
+ * Safari 16-17 lacks native transferable streams. When this feature is enabled,
+ * the transport layer dynamically loads a ponyfill that enables stream transfer
+ * via postMessage on affected browsers.
+ *
+ * **When to use:**
+ * - Your application uses `responseType: 'stream'` and targets Safari 16-17
+ * - You see "DataCloneError" when transferring streams to/from workers
+ *
+ * **Bundle impact:** The polyfill is lazy-loaded only on Safari 16-17 when
+ * streams are actually used. Non-Safari browsers and modern Safari pay 0 bytes.
+ *
+ * @example
+ * ```typescript
+ * provideWorkerHttpClient(
+ *   withWorkerConfigs([...]),
+ *   withWorkerStreamsPolyfill(), // Enable for Safari compatibility
+ * )
+ * ```
+ */
+function withWorkerStreamsPolyfill() {
+    return {
+        kind: 'StreamsPolyfill',
+        providers: [{ provide: WORKER_HTTP_STREAMS_POLYFILL_TOKEN, useValue: true }],
+    };
+}
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withTelemetry, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization };
+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 };

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

@@ -80,9 +80,13 @@ async function createAesEncryptor(config) {
         ? new Uint8Array(config.keyMaterial.buffer.slice(0))
         : new Uint8Array(config.keyMaterial);
     const cryptoKey = await crypto.subtle.importKey('raw', keyMaterial, { name: algorithm, length: keyLength }, false, ['encrypt', 'decrypt']);
+    // AES-GCM uses a 96-bit (12-byte) IV per NIST SP 800-38D recommendation.
+    // AES-CBC and AES-CTR require exactly one block (16 bytes) for their IV /
+    // counter respectively; passing 12 bytes causes `OperationError`.
+    const ivLength = algorithm === 'AES-GCM' ? 12 : 16;
     return {
         async encrypt(data) {
-            const iv = crypto.getRandomValues(new Uint8Array(12));
+            const iv = crypto.getRandomValues(new Uint8Array(ivLength));
             const params = algorithm === 'AES-GCM'
                 ? { name: algorithm, iv }
                 : algorithm === 'AES-CBC'

package/fesm2022/angular-helpers-worker-http-esbuild-plugin.mjs

@@ -0,0 +1,170 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+/**
+ * esbuild plugin for worker-http that bundles interceptors into worker files.
+ *
+ * This plugin:
+ * 1. Intercepts worker file builds
+ * 2. Discovers interceptor files if autoDiscover is true
+ * 3. Injects interceptor imports into the worker bootstrap
+ * 4. Ensures interceptors are available in the worker's interceptor pipeline
+ *
+ * @param options - Plugin configuration
+ * @returns esbuild Plugin
+ *
+ * @example
+ * ```typescript
+ * import { workerHttpPlugin } from '@angular-helpers/worker-http/esbuild-plugin';
+ *
+ * const config = {
+ *   plugins: [
+ *     workerHttpPlugin({
+ *       autoDiscover: true,
+ *     })
+ *   ]
+ * };
+ * ```
+ */
+function workerHttpPlugin(options = {}) {
+    const { interceptors = [], autoDiscover = false } = options;
+    return {
+        name: 'worker-http',
+        setup(build) {
+            const filter = /\.worker\.(ts|js|mjs)$/;
+            const discoveredInterceptors = [];
+            // Auto-discover interceptors from src directory
+            if (autoDiscover) {
+                const rootDir = build.initialOptions.absWorkingDir ?? process.cwd();
+                discoveredInterceptors.push(...discoverInterceptors(rootDir));
+            }
+            const allInterceptors = [...new Set([...interceptors, ...discoveredInterceptors])];
+            // Intercept worker file loads to inject interceptor imports
+            build.onLoad({ filter }, async (args) => {
+                let contents = await fs.promises.readFile(args.path, 'utf-8');
+                if (allInterceptors.length > 0) {
+                    const importStatements = generateInterceptorImports(allInterceptors, args.path);
+                    contents = injectImports(contents, importStatements);
+                }
+                return {
+                    contents,
+                    loader: 'ts',
+                };
+            });
+        },
+    };
+}
+/**
+ * Discovers interceptor files by scanning src directories.
+ * Looks for files matching interceptor naming patterns
+ * in TypeScript or JavaScript files.
+ */
+function discoverInterceptors(rootDir) {
+    const interceptors = [];
+    const srcDir = path.join(rootDir, 'src');
+    if (!fs.existsSync(srcDir)) {
+        return interceptors;
+    }
+    scanDirectory(srcDir, interceptors, rootDir);
+    return interceptors;
+}
+/**
+ * Recursively scans a directory for interceptor files.
+ */
+function scanDirectory(dir, interceptors, rootDir) {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            // Skip node_modules and dist
+            if (entry.name === 'node_modules' || entry.name === 'dist') {
+                continue;
+            }
+            scanDirectory(fullPath, interceptors, rootDir);
+        }
+        else if (entry.isFile()) {
+            const isInterceptorFile = /interceptor/i.test(entry.name) &&
+                (entry.name.endsWith('.ts') || entry.name.endsWith('.js') || entry.name.endsWith('.mjs')) &&
+                !entry.name.endsWith('.spec.ts') &&
+                !entry.name.endsWith('.test.ts') &&
+                !entry.name.endsWith('.d.ts');
+            if (isInterceptorFile) {
+                // Get relative path from project root
+                const relativePath = path.relative(rootDir, fullPath);
+                interceptors.push('./' + relativePath.replace(/\\/g, '/'));
+            }
+        }
+    }
+}
+/**
+ * Generates import statements for discovered interceptors.
+ * Converts relative paths to valid import specifiers.
+ */
+function generateInterceptorImports(interceptorPaths, workerFilePath) {
+    return interceptorPaths.map((interceptorPath, index) => {
+        // Create a valid identifier from the path
+        const identifier = `interceptor_${index}_${interceptorPath.replace(/[^a-zA-Z0-9]/g, '_')}`;
+        return `import ${identifier} from '${interceptorPath}';`;
+    });
+}
+/**
+ * Injects import statements at the top of the worker file.
+ * Preserves any existing imports.
+ */
+function injectImports(contents, importStatements) {
+    if (importStatements.length === 0) {
+        return contents;
+    }
+    const imports = importStatements.join('\n');
+    const marker = '// Auto-injected by worker-http esbuild plugin';
+    // Check if already injected
+    if (contents.includes(marker)) {
+        return contents;
+    }
+    const injection = `${marker}\n${imports}\n`;
+    // Find the first non-comment, non-whitespace line to insert before
+    const lines = contents.split('\n');
+    let insertIndex = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        // Skip shebang, comments, and empty lines
+        if (line.startsWith('#!') ||
+            line.startsWith('//') ||
+            line.startsWith('/*') ||
+            line.startsWith('*') ||
+            line === '') {
+            insertIndex = i + 1;
+            continue;
+        }
+        break;
+    }
+    lines.splice(insertIndex, 0, injection);
+    return lines.join('\n');
+}
+
+/**
+ * esbuild plugin for @angular-helpers/worker-http
+ *
+ * Automatically bundles worker interceptors and injects them into the worker bootstrap.
+ *
+ * @example
+ * ```typescript
+ * // angular.json custom webpack config
+ * import { workerHttpPlugin } from '@angular-helpers/worker-http/esbuild-plugin';
+ *
+ * export default {
+ *   plugins: [
+ *     workerHttpPlugin({
+ *       interceptors: ['./src/interceptors/auth.ts'],
+ *       autoDiscover: true
+ *     })
+ *   ]
+ * };
+ * ```
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { workerHttpPlugin };

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

@@ -1,9 +1,14 @@
 /**
  * Composes interceptor functions around a final handler, producing a single
- * `(req) => Promise<resp>` chain. Pure — no side effects.
+ * `(req, signal?) => Promise<resp>` chain. Pure — no side effects.
+ *
+ * The optional `signal` is threaded through interceptor boundaries automatically
+ * via a wrapper around `next`, so legacy `WorkerInterceptorFn` implementations
+ * (which take only `req, next`) keep working and still propagate cancellation
+ * when they invoke `next(req)`.
  */
 function buildChain(fns, finalHandler) {
-    return fns.reduceRight((next, interceptor) => (req) => interceptor(req, next), finalHandler);
+    return fns.reduceRight((next, interceptor) => (req, signal) => interceptor(req, (r) => next(r, signal)), finalHandler);
 }
 /**
  * Performs the actual `fetch()` call inside the worker, translating the
@@ -98,7 +103,7 @@ function attachRequestLoop(chain) {
         const controller = new AbortController();
         controllers.set(requestId, controller);
         try {
-            const response = await chain(payload);
+            const response = await chain(payload, controller.signal);
             self.postMessage({ type: 'response', requestId, result: response });
         }
         catch (error) {
@@ -145,7 +150,7 @@ function attachRequestLoop(chain) {
  * ```
  */
 function createWorkerPipeline(interceptors) {
-    const chain = buildChain(interceptors, (req) => executeFetch(req));
+    const chain = buildChain(interceptors, (req, signal) => executeFetch(req, signal));
     attachRequestLoop(chain);
 }
 
@@ -325,7 +330,9 @@ function hmacSigningInterceptor(config) {
  * ```
  */
 function loggingInterceptor(config) {
-    const logger = config?.logger ?? ((msg, data) => console.log(msg, data));
+    const logger = config?.logger ??
+        // oxlint-disable-next-line no-console -- default logger of a logging interceptor; consumers inject their own via config.logger
+        ((msg, data) => console.log(msg, data));
     const includeHeaders = config?.includeHeaders ?? false;
     function safeLog(message, data) {
         try {
@@ -538,7 +545,7 @@ function createConfigurableWorkerPipeline() {
         if (data.type === INIT_MESSAGE_TYPE) {
             const specs = data.specs ?? [];
             const fns = specs.map((spec) => resolveSpec(spec));
-            const chain = buildChain(fns, (req) => executeFetch(req));
+            const chain = buildChain(fns, (req, signal) => executeFetch(req, signal));
             // Swap to the regular request loop and replay any buffered messages.
             attachRequestLoop(chain);
             const handler = self.onmessage;

package/fesm2022/angular-helpers-worker-http-streams-polyfill.mjs

@@ -0,0 +1,125 @@
+/**
+ * Detects if the current browser needs the streams ponyfill.
+ *
+ * Safari 16-17 fails to transfer `ReadableStream`/`TransformStream`
+ * to/from Web Workers via `structuredClone` because they lack
+ * the transferable streams implementation.
+ *
+ * @param userAgent - Optional user agent string for testing (defaults to feature detection)
+ * @returns `true` if ponyfill is needed, `false` if native works
+ */
+function needsPolyfill(userAgent) {
+    // If userAgent provided (testing mode), use UA-based detection
+    if (userAgent !== undefined) {
+        return isLegacySafari(userAgent);
+    }
+    // Quick check: if we're not in a browser context, assume no polyfill needed
+    if (typeof ReadableStream === 'undefined') {
+        return false;
+    }
+    try {
+        const rs = new ReadableStream({
+            start(controller) {
+                controller.close();
+            },
+        });
+        // Safari < 18 lacks the transferable streams spec extension
+        // The presence of 'getReader' alone isn't enough — we need to verify
+        // that the stream can be transferred via postMessage
+        const channel = new MessageChannel();
+        let transferable = true;
+        // Try to transfer — this throws on Safari 16-17
+        try {
+            channel.port1.postMessage(rs, [rs]);
+        }
+        catch {
+            transferable = false;
+        }
+        channel.port1.close();
+        channel.port2.close();
+        return !transferable;
+    }
+    catch {
+        // Any error means we should try polyfill
+        return true;
+    }
+}
+/**
+ * User-agent based detection for Safari.
+ * Used as a fast-path before the more expensive transfer test.
+ *
+ * @param userAgent - Optional user agent string (defaults to navigator.userAgent)
+ */
+function isSafari(userAgent) {
+    const ua = userAgent ?? (typeof navigator !== 'undefined' ? navigator.userAgent : '');
+    return /Safari/.test(ua) && !/Chrome/.test(ua) && !/Chromium/.test(ua);
+}
+/**
+ * Check if Safari version is known to need polyfill (< 18).
+ *
+ * @param userAgent - Optional user agent string (defaults to navigator.userAgent)
+ */
+function isLegacySafari(userAgent) {
+    if (!isSafari(userAgent)) {
+        return false;
+    }
+    const ua = userAgent ?? (typeof navigator !== 'undefined' ? navigator.userAgent : '');
+    const match = /Version\/(\d+)/.exec(ua);
+    if (!match) {
+        return false;
+    }
+    const version = Number.parseInt(match[1], 10);
+    return version < 18;
+}
+
+/**
+ * Ponyfill for Web Streams API that supports transfer to/from workers.
+ *
+ * Uses `web-streams-polyfill` internally but only loads it when needed.
+ * This keeps bundle size small for non-Safari browsers.
+ *
+ * @see {@link needsPolyfill} for detection
+ */
+let cachedPonyfill = null;
+/**
+ * Lazily loads the web-streams-polyfill ponyfill.
+ *
+ * @returns Ponyfilled streams or native if not needed
+ */
+async function ponyfillStreams() {
+    if (cachedPonyfill) {
+        return cachedPonyfill;
+    }
+    // Dynamic import to avoid bundling polyfill for non-Safari users
+    const { ReadableStream, TransformStream, WritableStream } = await import('web-streams-polyfill');
+    cachedPonyfill = {
+        ReadableStream,
+        TransformStream,
+        WritableStream,
+    };
+    return cachedPonyfill;
+}
+
+/**
+ * Safari Transferable Streams Ponyfill
+ *
+ * Provides `ReadableStream` and `TransformStream` implementations that support
+ * `structuredClone` transfer to/from Web Workers on Safari 16-17.
+ *
+ * This is a **ponyfill** (not a polyfill) — it does not modify global scope.
+ * Native implementations are re-exported when available.
+ *
+ * Usage:
+ * ```typescript
+ * import '@angular-helpers/worker-http/streams-polyfill';
+ * ```
+ * Or let the transport auto-inject when `safariPolyfill: true` is configured.
+ *
+ * @see {@link detect} for feature detection
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { needsPolyfill, ponyfillStreams };

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

@@ -1,14 +1,118 @@
 import { Observable } from 'rxjs';
 
+/**
+ * Scans a payload one level deep and collects every `Transferable` instance
+ * (ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas, ReadableStream,
+ * WritableStream, TransformStream) found in its own enumerable properties.
+ *
+ * Used by `createWorkerTransport` when `transferDetection === 'auto'` to build
+ * the second argument of `worker.postMessage(data, transfer)` so large buffers
+ * move zero-copy instead of being structured-cloned.
+ *
+ * Design notes:
+ * - Only one level deep by design: deep traversal has quadratic cost on heavy
+ *   graphs and makes the transfer list surprising. Real payloads that care
+ *   about zero-copy put the buffer at the top level.
+ * - Duplicates are filtered — the same buffer referenced twice is transferred
+ *   only once (required by the structured-clone algorithm).
+ * - Returns an empty array for primitives, plain serializable values, or when
+ *   no transferable is found; `postMessage` accepts `[]` safely.
+ */
+function detectTransferables(payload) {
+    if (payload === null || payload === undefined)
+        return [];
+    if (typeof payload !== 'object')
+        return [];
+    const found = [];
+    const seen = new Set();
+    const collect = (value) => {
+        if (value === null || value === undefined)
+            return;
+        if (isTransferable(value)) {
+            if (!seen.has(value)) {
+                seen.add(value);
+                found.push(value);
+            }
+        }
+    };
+    if (isTransferable(payload)) {
+        collect(payload);
+        return found;
+    }
+    if (Array.isArray(payload)) {
+        for (const item of payload)
+            collect(item);
+        return found;
+    }
+    for (const key of Object.keys(payload)) {
+        collect(payload[key]);
+    }
+    return found;
+}
+function isTransferable(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (typeof value !== 'object')
+        return false;
+    // ArrayBuffer is the common case; check first.
+    if (typeof ArrayBuffer !== 'undefined' && value instanceof ArrayBuffer)
+        return true;
+    // Typed-array views carry an underlying buffer but are NOT Transferable —
+    // only the buffer is. Caller must pass `.buffer` explicitly if they want it.
+    if (typeof MessagePort !== 'undefined' && value instanceof MessagePort)
+        return true;
+    if (typeof ImageBitmap !== 'undefined' && value instanceof ImageBitmap)
+        return true;
+    if (typeof OffscreenCanvas !== 'undefined' && value instanceof OffscreenCanvas)
+        return true;
+    if (typeof ReadableStream !== 'undefined' && value instanceof ReadableStream)
+        return true;
+    if (typeof WritableStream !== 'undefined' && value instanceof WritableStream)
+        return true;
+    if (typeof TransformStream !== 'undefined' && value instanceof TransformStream)
+        return true;
+    return false;
+}
+
+/**
+ * Thrown by `createWorkerTransport` when a request exceeds its configured
+ * `requestTimeout`. Consumers can `instanceof`-check this error to distinguish
+ * timeout rejections from transport/worker errors.
+ *
+ * @example
+ * ```typescript
+ * transport.execute(req).subscribe({
+ *   error: (err) => {
+ *     if (err instanceof WorkerHttpTimeoutError) {
+ *       // dedicated timeout handling
+ *     }
+ *   },
+ * });
+ * ```
+ */
+class WorkerHttpTimeoutError extends Error {
+    name = 'WorkerHttpTimeoutError';
+    timeoutMs;
+    constructor(timeoutMs) {
+        super(`Worker request timed out after ${timeoutMs} ms`);
+        this.timeoutMs = timeoutMs;
+        // Maintain a proper prototype chain across TS transpile targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
 /**
  * Creates a typed, Observable-based transport for communicating with a web worker.
  *
  * Features:
  * - Request/response correlation via `requestId`
- * - Automatic cancellation on Observable unsubscribe
+ * - Cancellation on Observable unsubscribe (also aborts `fetch()` in the worker)
+ * - Per-request timeout (default 30 s) rejecting with `WorkerHttpTimeoutError`
  * - Optional worker pool with round-robin dispatch
  * - Lazy worker creation (default)
- * - Transferable auto-detection for ArrayBuffer payloads
+ * - Opt-in transferable detection (`transferDetection: 'auto'`) for zero-copy
+ *   `ArrayBuffer` / stream payloads
  *
  * @example
  * ```typescript
@@ -28,6 +132,10 @@ function createWorkerTransport(config) {
     let roundRobinIndex = 0;
     let terminated = false;
     const maxInstances = Math.min(config.maxInstances ?? 1, typeof navigator !== 'undefined' ? (navigator.hardwareConcurrency ?? 4) : 1);
+    const requestTimeout = config.requestTimeout ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const transferDetection = config.transferDetection ?? 'none';
+    const streamsPolyfill = config.streamsPolyfill ?? false;
+    let polyfillLoaded = false;
     function createWorker() {
         if (config.workerFactory) {
             return config.workerFactory();
@@ -61,13 +169,31 @@ function createWorkerTransport(config) {
         }
         const requestId = crypto.randomUUID();
         return new Observable((subscriber) => {
+            // Lazy-load polyfill on first request if enabled
+            if (streamsPolyfill && !polyfillLoaded) {
+                loadStreamsPolyfill().catch((err) => {
+                    console.warn('[worker-http] Streams polyfill failed to load:', err);
+                });
+            }
             const worker = getOrCreateWorker();
+            let settled = false;
+            let timeoutHandle;
+            const cleanup = () => {
+                worker.removeEventListener('message', messageHandler);
+                worker.removeEventListener('error', errorHandler);
+                if (timeoutHandle !== undefined) {
+                    clearTimeout(timeoutHandle);
+                    timeoutHandle = undefined;
+                }
+            };
             const messageHandler = (event) => {
                 const data = event.data;
                 if (data.requestId !== requestId)
                     return;
-                worker.removeEventListener('message', messageHandler);
-                worker.removeEventListener('error', errorHandler);
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
                 if (data.type === 'error') {
                     const err = data.error;
                     subscriber.error(new Error(err.message));
@@ -78,21 +204,63 @@ function createWorkerTransport(config) {
                 }
             };
             const errorHandler = (event) => {
-                worker.removeEventListener('message', messageHandler);
-                worker.removeEventListener('error', errorHandler);
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
                 subscriber.error(new Error(event.message ?? 'Worker error'));
             };
             worker.addEventListener('message', messageHandler);
             worker.addEventListener('error', errorHandler);
-            worker.postMessage({ type: 'request', requestId, payload: request });
+            if (transferDetection === 'auto') {
+                const transferables = detectTransferables(request);
+                worker.postMessage({ type: 'request', requestId, payload: request }, transferables);
+            }
+            else {
+                worker.postMessage({ type: 'request', requestId, payload: request });
+            }
+            if (requestTimeout > 0 && Number.isFinite(requestTimeout)) {
+                timeoutHandle = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    cleanup();
+                    // 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);
+            }
             // Teardown: send cancel message on unsubscribe
             return () => {
-                worker.removeEventListener('message', messageHandler);
-                worker.removeEventListener('error', errorHandler);
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
                 worker.postMessage({ type: 'cancel', requestId });
             };
         });
     }
+    /**
+     * Lazy-loads the streams polyfill if enabled and not already loaded.
+     * Called before operations that might involve stream transfer.
+     */
+    async function loadStreamsPolyfill() {
+        if (!streamsPolyfill || polyfillLoaded) {
+            return;
+        }
+        try {
+            const { needsPolyfill, ponyfillStreams } = await import('@angular-helpers/worker-http/streams-polyfill');
+            if (needsPolyfill()) {
+                await ponyfillStreams();
+            }
+            polyfillLoaded = true;
+        }
+        catch (err) {
+            // Log warning but don't block request — streams will fail naturally
+            console.warn('[worker-http] Failed to load streams polyfill:', err);
+        }
+    }
     function terminate() {
         terminated = true;
         for (const worker of workers) {
@@ -116,4 +284,4 @@ function createWorkerTransport(config) {
  * Generated bundle index. Do not edit.
  */
 
-export { createWorkerTransport };
+export { WorkerHttpTimeoutError, createWorkerTransport, detectTransferables };

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

@@ -1,20 +1,3 @@
-/**
- * @angular-helpers/worker-http
- *
- * Angular HTTP over Web Workers — off-main-thread HTTP pipelines
- * with configurable interceptors, WebCrypto security, and pluggable serialization.
- *
- * Sub-entry points:
- *   - @angular-helpers/worker-http/transport     (P1: typed RPC bridge)
- *   - @angular-helpers/worker-http/serializer    (P2: TOON, seroval, auto-detect)
- *   - @angular-helpers/worker-http/backend       (P3: Angular HttpBackend replacement)
- *   - @angular-helpers/worker-http/interceptors  (P4: pure-fn interceptors for workers)
- *   - @angular-helpers/worker-http/crypto        (P5: WebCrypto primitives)
- */
-const WORKER_HTTP_VERSION = '0.0.1';
-
 /**
  * Generated bundle index. Do not edit.
  */
-
-export { WORKER_HTTP_VERSION };

package/package.json

@@ -1,7 +1,53 @@
 {
   "name": "@angular-helpers/worker-http",
-  "version": "0.6.0",
+  "version": "1.0.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": {
+    ".": {
+      "types": "./types/angular-helpers-worker-http.d.ts",
+      "esm": "./esm/src/index.js",
+      "default": "./fesm2022/angular-helpers-worker-http.mjs"
+    },
+    "./backend": {
+      "types": "./types/angular-helpers-worker-http-backend.d.ts",
+      "esm": "./esm/backend/src/index.js",
+      "default": "./fesm2022/angular-helpers-worker-http-backend.mjs"
+    },
+    "./transport": {
+      "types": "./types/angular-helpers-worker-http-transport.d.ts",
+      "esm": "./esm/transport/src/index.js",
+      "default": "./fesm2022/angular-helpers-worker-http-transport.mjs"
+    },
+    "./interceptors": {
+      "types": "./types/angular-helpers-worker-http-interceptors.d.ts",
+      "esm": "./esm/interceptors/src/index.js",
+      "default": "./fesm2022/angular-helpers-worker-http-interceptors.mjs"
+    },
+    "./crypto": {
+      "types": "./types/angular-helpers-worker-http-crypto.d.ts",
+      "esm": "./esm/crypto/src/index.js",
+      "default": "./fesm2022/angular-helpers-worker-http-crypto.mjs"
+    },
+    "./serializer": {
+      "types": "./types/angular-helpers-worker-http-serializer.d.ts",
+      "esm": "./esm/serializer/src/index.js",
+      "default": "./fesm2022/angular-helpers-worker-http-serializer.mjs"
+    },
+    "./esbuild-plugin": {
+      "types": "./types/angular-helpers-worker-http-esbuild-plugin.d.ts",
+      "esm": "./esm/esbuild-plugin/src/index.js",
+      "default": "./fesm2022/angular-helpers-worker-http-esbuild-plugin.mjs"
+    },
+    "./streams-polyfill": {
+      "types": "./types/angular-helpers-worker-http-streams-polyfill.d.ts",
+      "esm": "./esm/streams-polyfill/src/index.js",
+      "default": "./fesm2022/angular-helpers-worker-http-streams-polyfill.mjs"
+    },
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
   "keywords": [
     "angular",
     "web-worker",
@@ -41,39 +87,16 @@
     },
     "seroval": {
       "optional": true
-    }
-  },
-  "module": "fesm2022/angular-helpers-worker-http.mjs",
-  "typings": "types/angular-helpers-worker-http.d.ts",
-  "exports": {
-    "./package.json": {
-      "default": "./package.json"
-    },
-    ".": {
-      "types": "./types/angular-helpers-worker-http.d.ts",
-      "default": "./fesm2022/angular-helpers-worker-http.mjs"
-    },
-    "./backend": {
-      "types": "./types/angular-helpers-worker-http-backend.d.ts",
-      "default": "./fesm2022/angular-helpers-worker-http-backend.mjs"
-    },
-    "./crypto": {
-      "types": "./types/angular-helpers-worker-http-crypto.d.ts",
-      "default": "./fesm2022/angular-helpers-worker-http-crypto.mjs"
-    },
-    "./interceptors": {
-      "types": "./types/angular-helpers-worker-http-interceptors.d.ts",
-      "default": "./fesm2022/angular-helpers-worker-http-interceptors.mjs"
     },
-    "./serializer": {
-      "types": "./types/angular-helpers-worker-http-serializer.d.ts",
-      "default": "./fesm2022/angular-helpers-worker-http-serializer.mjs"
+    "esbuild": {
+      "optional": true
     },
-    "./transport": {
-      "types": "./types/angular-helpers-worker-http-transport.d.ts",
-      "default": "./fesm2022/angular-helpers-worker-http-transport.mjs"
+    "web-streams-polyfill": {
+      "optional": true
     }
   },
+  "module": "fesm2022/angular-helpers-worker-http.mjs",
+  "typings": "types/angular-helpers-worker-http.d.ts",
   "sideEffects": false,
   "dependencies": {
     "tslib": "^2.3.0"

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

@@ -9,7 +9,7 @@ import { Observable } from 'rxjs';
  * Discriminated union for worker HTTP feature kinds.
  * Mirrors Angular's HttpFeatureKind pattern.
  */
-type WorkerHttpFeatureKind = 'WorkerConfigs' | 'WorkerRoutes' | 'WorkerFallback' | 'WorkerSerialization' | 'WorkerInterceptors' | 'Telemetry';
+type WorkerHttpFeatureKind = 'WorkerConfigs' | 'WorkerRoutes' | 'WorkerFallback' | 'WorkerSerialization' | 'WorkerInterceptors' | 'Telemetry' | 'StreamsPolyfill';
 /**
  * Feature object — mirrors Angular's HttpFeature<K> shape.
  */
@@ -182,6 +182,15 @@ declare const WORKER_HTTP_SERIALIZER_TOKEN: InjectionToken<WorkerSerializer>;
  * Defaults to an empty map (no interceptors).
  */
 declare const WORKER_HTTP_INTERCEPTORS_TOKEN: InjectionToken<Readonly<Record<string, readonly WorkerInterceptorSpec[]>>>;
+/**
+ * Enable Safari streams polyfill for transferable ReadableStream/TransformStream
+ * support in workers. Provided via `withWorkerStreamsPolyfill()`.
+ * Defaults to `false` (native streams only).
+ *
+ * When enabled, the transport dynamically imports `@angular-helpers/worker-http/streams-polyfill`
+ * on Safari 16-17 to enable stream transfer via postMessage.
+ */
+declare const WORKER_HTTP_STREAMS_POLYFILL_TOKEN: InjectionToken<boolean>;
 
 /**
  * Sets up the worker HTTP infrastructure and replaces Angular's `HttpBackend`
@@ -345,6 +354,30 @@ declare function withWorkerInterceptors(specs: readonly WorkerInterceptorSpec[]
  * ```
  */
 declare function withTelemetry(telemetry: WorkerHttpTelemetry): WorkerHttpFeature<'Telemetry'>;
+/**
+ * Enables the Safari streams polyfill for transferable ReadableStream/TransformStream
+ * support in Web Workers.
+ *
+ * Safari 16-17 lacks native transferable streams. When this feature is enabled,
+ * the transport layer dynamically loads a ponyfill that enables stream transfer
+ * via postMessage on affected browsers.
+ *
+ * **When to use:**
+ * - Your application uses `responseType: 'stream'` and targets Safari 16-17
+ * - You see "DataCloneError" when transferring streams to/from workers
+ *
+ * **Bundle impact:** The polyfill is lazy-loaded only on Safari 16-17 when
+ * streams are actually used. Non-Safari browsers and modern Safari pay 0 bytes.
+ *
+ * @example
+ * ```typescript
+ * provideWorkerHttpClient(
+ *   withWorkerConfigs([...]),
+ *   withWorkerStreamsPolyfill(), // Enable for Safari compatibility
+ * )
+ * ```
+ */
+declare function withWorkerStreamsPolyfill(): WorkerHttpFeature<'StreamsPolyfill'>;
 
 /**
  * Angular `HttpBackend` replacement that routes HTTP requests to web workers.
@@ -366,6 +399,7 @@ declare class WorkerHttpBackend extends HttpBackend implements OnDestroy {
     private readonly interceptorSpecs;
     private readonly fetchBackend;
     private readonly telemetry;
+    private readonly streamsPolyfill;
     private readonly transports;
     handle(req: HttpRequest<unknown>): Observable<HttpEvent<unknown>>;
     ngOnDestroy(): void;
@@ -460,5 +494,5 @@ declare function matchWorkerRoute(url: string, routes: Array<{
     priority?: number;
 }>): string | null;
 
-export { WORKER_HTTP_INTERCEPTORS_TOKEN, WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withTelemetry, withWorkerConfigs, withWorkerFallback, withWorkerInterceptors, withWorkerRoutes, withWorkerSerialization };
+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 type { SerializableRequest, SerializableResponse, WorkerConfig, WorkerFallbackStrategy, WorkerHttpErrorEvent, WorkerHttpFeature, WorkerHttpFeatureKind, WorkerHttpRequestEvent, WorkerHttpResponseEvent, WorkerHttpTelemetry, WorkerHttpTelemetryEventBase, WorkerHttpTransportKind, WorkerInterceptorSpecsMap, WorkerRequestOptions, WorkerRoute };

package/types/angular-helpers-worker-http-esbuild-plugin.d.ts

@@ -0,0 +1,46 @@
+import { Plugin } from 'esbuild';
+
+interface WorkerHttpPluginOptions {
+    /**
+     * Explicit list of interceptor file paths to bundle into the worker.
+     * Paths are relative to project root.
+     * @example ['./src/interceptors/auth.ts', './src/interceptors/logging.ts']
+     */
+    interceptors?: string[];
+    /**
+     * Auto-discover interceptors by scanning src folders for files
+     * matching the interceptor naming pattern.
+     * Discovered interceptors are merged with explicit interceptors list.
+     * @default false
+     */
+    autoDiscover?: boolean;
+}
+/**
+ * esbuild plugin for worker-http that bundles interceptors into worker files.
+ *
+ * This plugin:
+ * 1. Intercepts worker file builds
+ * 2. Discovers interceptor files if autoDiscover is true
+ * 3. Injects interceptor imports into the worker bootstrap
+ * 4. Ensures interceptors are available in the worker's interceptor pipeline
+ *
+ * @param options - Plugin configuration
+ * @returns esbuild Plugin
+ *
+ * @example
+ * ```typescript
+ * import { workerHttpPlugin } from '@angular-helpers/worker-http/esbuild-plugin';
+ *
+ * const config = {
+ *   plugins: [
+ *     workerHttpPlugin({
+ *       autoDiscover: true,
+ *     })
+ *   ]
+ * };
+ * ```
+ */
+declare function workerHttpPlugin(options?: WorkerHttpPluginOptions): Plugin;
+
+export { workerHttpPlugin };
+export type { WorkerHttpPluginOptions };

package/types/angular-helpers-worker-http-streams-polyfill.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Detects if the current browser needs the streams ponyfill.
+ *
+ * Safari 16-17 fails to transfer `ReadableStream`/`TransformStream`
+ * to/from Web Workers via `structuredClone` because they lack
+ * the transferable streams implementation.
+ *
+ * @param userAgent - Optional user agent string for testing (defaults to feature detection)
+ * @returns `true` if ponyfill is needed, `false` if native works
+ */
+declare function needsPolyfill(userAgent?: string): boolean;
+
+/**
+ * Ponyfill for Web Streams API that supports transfer to/from workers.
+ *
+ * Uses `web-streams-polyfill` internally but only loads it when needed.
+ * This keeps bundle size small for non-Safari browsers.
+ *
+ * @see {@link needsPolyfill} for detection
+ */
+interface StreamPonyfillExports {
+    ReadableStream: typeof ReadableStream;
+    TransformStream: typeof TransformStream;
+    WritableStream: typeof WritableStream;
+}
+/**
+ * Lazily loads the web-streams-polyfill ponyfill.
+ *
+ * @returns Ponyfilled streams or native if not needed
+ */
+declare function ponyfillStreams(): Promise<StreamPonyfillExports>;
+
+export { needsPolyfill, ponyfillStreams };
+export type { StreamPonyfillExports };

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

@@ -34,9 +34,27 @@ interface WorkerTransportConfig {
     workerUrl?: string | URL;
     /** Maximum number of worker instances in the pool (default: 1) */
     maxInstances?: number;
-    /** Transfer strategy for large payloads */
+    /**
+     * Transfer strategy for `postMessage` payloads.
+     *
+     * - `'none'` (default) — payloads are always structured-cloned, preserving
+     *   the caller's access to the original data after post.
+     * - `'auto'` — shallowly walks the payload and passes every detected
+     *   `Transferable` (ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas,
+     *   ReadableStream, WritableStream, TransformStream) in the transfer list
+     *   of `postMessage`. Large buffers move zero-copy; their `byteLength`
+     *   becomes `0` in the main thread after post.
+     *
+     * The `'manual'` value is reserved for a future API where callers supply
+     * their own transfer list per request. It currently behaves like `'none'`.
+     */
     transferDetection?: 'auto' | 'manual' | 'none';
-    /** Timeout in ms for a single request (default: 30000) */
+    /**
+     * Per-request timeout in milliseconds. If the worker does not respond
+     * within this window, `execute()` errors with `WorkerHttpTimeoutError`
+     * and a cancel message is posted to the worker. Set to `0` or
+     * non-finite to disable the timeout entirely. Default: `30000` (30 s).
+     */
     requestTimeout?: number;
     /**
      * Optional handshake message posted to every worker as soon as it is
@@ -50,6 +68,14 @@ interface WorkerTransportConfig {
         type: string;
         [key: string]: unknown;
     };
+    /**
+     * Enable Safari streams polyfill for transferable ReadableStream/TransformStream
+     * support. When `true`, the transport lazy-loads the ponyfill on Safari 16-17
+     * to enable stream transfer via postMessage.
+     *
+     * @default false
+     */
+    streamsPolyfill?: boolean;
 }
 /**
  * Message sent from main thread to worker.
@@ -103,10 +129,12 @@ interface WorkerTransport<TRequest = unknown, TResponse = unknown> {
  *
  * Features:
  * - Request/response correlation via `requestId`
- * - Automatic cancellation on Observable unsubscribe
+ * - Cancellation on Observable unsubscribe (also aborts `fetch()` in the worker)
+ * - Per-request timeout (default 30 s) rejecting with `WorkerHttpTimeoutError`
  * - Optional worker pool with round-robin dispatch
  * - Lazy worker creation (default)
- * - Transferable auto-detection for ArrayBuffer payloads
+ * - Opt-in transferable detection (`transferDetection: 'auto'`) for zero-copy
+ *   `ArrayBuffer` / stream payloads
  *
  * @example
  * ```typescript
@@ -123,5 +151,47 @@ interface WorkerTransport<TRequest = unknown, TResponse = unknown> {
  */
 declare function createWorkerTransport<TRequest = unknown, TResponse = unknown>(config: WorkerTransportConfig): WorkerTransport<TRequest, TResponse>;
 
-export { createWorkerTransport };
+/**
+ * Thrown by `createWorkerTransport` when a request exceeds its configured
+ * `requestTimeout`. Consumers can `instanceof`-check this error to distinguish
+ * timeout rejections from transport/worker errors.
+ *
+ * @example
+ * ```typescript
+ * transport.execute(req).subscribe({
+ *   error: (err) => {
+ *     if (err instanceof WorkerHttpTimeoutError) {
+ *       // dedicated timeout handling
+ *     }
+ *   },
+ * });
+ * ```
+ */
+declare class WorkerHttpTimeoutError extends Error {
+    readonly name = "WorkerHttpTimeoutError";
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+
+/**
+ * Scans a payload one level deep and collects every `Transferable` instance
+ * (ArrayBuffer, MessagePort, ImageBitmap, OffscreenCanvas, ReadableStream,
+ * WritableStream, TransformStream) found in its own enumerable properties.
+ *
+ * Used by `createWorkerTransport` when `transferDetection === 'auto'` to build
+ * the second argument of `worker.postMessage(data, transfer)` so large buffers
+ * move zero-copy instead of being structured-cloned.
+ *
+ * Design notes:
+ * - Only one level deep by design: deep traversal has quadratic cost on heavy
+ *   graphs and makes the transfer list surprising. Real payloads that care
+ *   about zero-copy put the buffer at the top level.
+ * - Duplicates are filtered — the same buffer referenced twice is transferred
+ *   only once (required by the structured-clone algorithm).
+ * - Returns an empty array for primitives, plain serializable values, or when
+ *   no transferable is found; `postMessage` accepts `[]` safely.
+ */
+declare function detectTransferables(payload: unknown): Transferable[];
+
+export { WorkerHttpTimeoutError, createWorkerTransport, detectTransferables };
 export type { WorkerErrorResponse, WorkerMessage, WorkerResponse, WorkerTransport, WorkerTransportConfig };

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

@@ -1,16 +1,2 @@
-/**
- * @angular-helpers/worker-http
- *
- * Angular HTTP over Web Workers — off-main-thread HTTP pipelines
- * with configurable interceptors, WebCrypto security, and pluggable serialization.
- *
- * Sub-entry points:
- *   - @angular-helpers/worker-http/transport     (P1: typed RPC bridge)
- *   - @angular-helpers/worker-http/serializer    (P2: TOON, seroval, auto-detect)
- *   - @angular-helpers/worker-http/backend       (P3: Angular HttpBackend replacement)
- *   - @angular-helpers/worker-http/interceptors  (P4: pure-fn interceptors for workers)
- *   - @angular-helpers/worker-http/crypto        (P5: WebCrypto primitives)
- */
-declare const WORKER_HTTP_VERSION = "0.0.1";
 
-export { WORKER_HTTP_VERSION };
+export { };