@angular-helpers/worker-http 0.2.0 → 0.3.0

package/README.md

@@ -16,13 +16,13 @@ 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()`  | 🔧 In progress |
+| 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 |
 
 ---
 
@@ -313,13 +313,9 @@ const hash = await hasher.hash('SHA-256', data); // → hex string
 
 ---
 
-### `/backend` — Angular `HttpBackend` replacement (in progress)
+### `/backend` — Angular `HttpBackend` replacement
 
-> 🔧 **This entry point is currently in development.**
-
-The goal is a drop-in replacement for Angular's `HttpBackend` that transparently routes requests to the appropriate worker.
-
-**Planned API:**
+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.
 
 ```typescript
 // app.config.ts
@@ -328,34 +324,75 @@ import {
   withWorkerConfigs,
   withWorkerRoutes,
   withWorkerFallback,
+  withWorkerSerialization,
 } from '@angular-helpers/worker-http/backend';
+import { createSerovalSerializer } from '@angular-helpers/worker-http/serializer';
 
-bootstrapApplication(AppComponent, {
+export const appConfig: ApplicationConfig = {
   providers: [
     provideWorkerHttpClient(
       withWorkerConfigs([
+        {
+          id: 'api',
+          workerUrl: new URL('./workers/api.worker', import.meta.url),
+          maxInstances: 2, // round-robin pool
+        },
         {
           id: 'secure',
           workerUrl: new URL('./workers/secure.worker', import.meta.url),
-          maxInstances: 2,
         },
       ]),
-      withWorkerRoutes([{ pattern: /\/api\/secure\//, worker: 'secure', priority: 10 }]),
-      withWorkerFallback('main-thread'), // SSR-safe fallback
+      withWorkerRoutes([
+        { pattern: /\/api\/secure\//, worker: 'secure', priority: 10 },
+        { pattern: /\/api\//, worker: 'api', priority: 5 },
+      ]),
+      withWorkerFallback('main-thread'), // SSR-safe
+      withWorkerSerialization(createSerovalSerializer()), // optional: complex bodies
     ),
   ],
-});
+};
 
-// data.service.ts — identical to normal HttpClient usage
+// data.service.ts — WorkerHttpClient is a drop-in for HttpClient
 export class DataService {
-  private http = inject(HttpClient);
+  private http = inject(WorkerHttpClient);
 
-  getReports() {
-    return this.http.get<Report[]>('/api/secure/reports');
+  getUsers() {
+    return this.http.get<User[]>('/api/users'); // auto-routed to 'api' worker
+  }
+
+  getSecureData() {
+    // per-request override via { worker } option or WORKER_TARGET context token
+    return this.http.get('/api/secure/payments', { worker: 'secure' });
   }
 }
+
+// workers/api.worker.ts — runs on a separate OS thread
+import {
+  createWorkerPipeline,
+  loggingInterceptor,
+  retryInterceptor,
+  cacheInterceptor,
+} from '@angular-helpers/worker-http/interceptors';
+
+createWorkerPipeline([
+  loggingInterceptor(),
+  retryInterceptor({ maxRetries: 3 }),
+  cacheInterceptor({ ttl: 60000 }),
+]);
 ```
 
+**Features:**
+
+- `provideWorkerHttpClient(...features)` — replaces `provideHttpClient()`; do not use both
+- `withWorkerConfigs(configs)` — register named workers with optional pool size
+- `withWorkerRoutes(routes)` — URL-pattern routing with priority ordering
+- `withWorkerFallback(strategy)` — `'main-thread'` (SSR-safe) or `'error'`
+- `withWorkerSerialization(serializer)` — plug in `createSerovalSerializer()` for complex request bodies (`Date`, `Map`, `Set`)
+- `WORKER_TARGET` — `HttpContextToken<string | null>` for per-request worker routing via `HttpContext`
+- `WorkerHttpClient` — `HttpClient` wrapper with optional `{ worker: string }` routing field
+- `WorkerHttpBackend` — the `HttpBackend` implementation (injectable for advanced use)
+- `matchWorkerRoute(url, routes)` — pure utility to test routing rules
+
 ---
 
 ## Design principles

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

@@ -1,3 +1,372 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, inject, Injectable, makeEnvironmentProviders } from '@angular/core';
+import { HttpContextToken, HttpHeaders, HttpResponse, HttpBackend, FetchBackend, HttpErrorResponse, HttpClient, HttpContext, provideHttpClient, withFetch } from '@angular/common/http';
+import { throwError } from 'rxjs';
+import { map, catchError } from 'rxjs/operators';
+import { createWorkerTransport } from '@angular-helpers/worker-http/transport';
+
+/**
+ * Per-request HttpContextToken that carries the target worker ID.
+ *
+ * `null` → use URL-pattern auto-routing (or main-thread fallback if no route matches).
+ *
+ * @example
+ * ```typescript
+ * // With WorkerHttpClient (recommended)
+ * this.http.get('/api/data', { worker: 'secure' });
+ *
+ * // With standard HttpClient (power user)
+ * this.http.get('/api/data', {
+ *   context: new HttpContext().set(WORKER_TARGET, 'secure'),
+ * });
+ * ```
+ */
+const WORKER_TARGET = new HttpContextToken(() => null);
+/**
+ * Registered worker definitions provided via `withWorkerConfigs()`.
+ */
+const WORKER_HTTP_CONFIGS_TOKEN = new InjectionToken('WorkerHttpConfigs', {
+    factory: () => [],
+});
+/**
+ * URL-pattern routing rules provided via `withWorkerRoutes()`.
+ */
+const WORKER_HTTP_ROUTES_TOKEN = new InjectionToken('WorkerHttpRoutes', {
+    factory: () => [],
+});
+/**
+ * Fallback strategy provided via `withWorkerFallback()`.
+ * Defaults to `'main-thread'` (safe for SSR / unsupported environments).
+ */
+const WORKER_HTTP_FALLBACK_TOKEN = new InjectionToken('WorkerHttpFallback', { factory: () => 'main-thread' });
+/**
+ * Optional serializer for crossing the worker boundary.
+ * Provided via `withWorkerSerialization()`. Defaults to `null` (structured clone).
+ *
+ * When set, `WorkerHttpBackend` serializes the request body before `postMessage`
+ * using this serializer. The worker-side `createWorkerPipeline()` receives the
+ * serialized form — add a worker interceptor to deserialize it if needed.
+ */
+const WORKER_HTTP_SERIALIZER_TOKEN = new InjectionToken('WorkerHttpSerializer', { factory: () => null });
+
+/**
+ * Converts an Angular `HttpRequest` into a structured-clone-safe POJO
+ * that can be sent to a web worker via `postMessage`.
+ *
+ * Notes:
+ * - `urlWithParams` is used so query params embedded via `HttpParams` are included.
+ * - The `context` field is intentionally left empty: `HttpContext` uses class references
+ *   as keys which cannot cross the worker boundary.
+ */
+function toSerializableRequest(req) {
+    const headers = {};
+    for (const name of req.headers.keys()) {
+        headers[name.toLowerCase()] = req.headers.getAll(name) ?? [];
+    }
+    const params = {};
+    for (const name of req.params.keys()) {
+        params[name] = req.params.getAll(name) ?? [];
+    }
+    return {
+        method: req.method,
+        url: req.urlWithParams,
+        headers,
+        params,
+        body: req.body,
+        responseType: req.responseType,
+        withCredentials: req.withCredentials,
+        context: {},
+    };
+}
+/**
+ * Converts a worker `SerializableResponse` back into an Angular `HttpResponse`.
+ */
+function toHttpResponse(res, req) {
+    let headers = new HttpHeaders();
+    for (const [key, values] of Object.entries(res.headers)) {
+        for (const value of values) {
+            headers = headers.append(key, value);
+        }
+    }
+    return new HttpResponse({
+        body: res.body,
+        headers,
+        status: res.status,
+        statusText: res.statusText,
+        url: res.url || req.urlWithParams,
+    });
+}
+/**
+ * Matches a URL against a sorted list of `WorkerRoute` rules.
+ * Rules with higher `priority` are evaluated first.
+ * Returns the matched worker ID or `null` if no rule matches.
+ */
+function matchWorkerRoute(url, routes) {
+    const sorted = [...routes].sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    for (const route of sorted) {
+        const pattern = typeof route.pattern === 'string' ? new RegExp(route.pattern) : route.pattern;
+        if (pattern.test(url)) {
+            return route.worker;
+        }
+    }
+    return null;
+}
+
+/**
+ * Angular `HttpBackend` replacement that routes HTTP requests to web workers.
+ *
+ * Registered via `provideWorkerHttpClient()`. Not meant to be used directly.
+ *
+ * Flow per request:
+ * 1. Check SSR: if `Worker` is undefined → fallback strategy
+ * 2. Resolve target worker ID from `WORKER_TARGET` context or URL-pattern routing
+ * 3. Serialize `HttpRequest` → `SerializableRequest` (structured-clone safe)
+ * 4. Dispatch to the worker's `WorkerTransport`
+ * 5. Deserialize `SerializableResponse` → `HttpResponse`
+ */
+class WorkerHttpBackend extends HttpBackend {
+    configs = inject(WORKER_HTTP_CONFIGS_TOKEN);
+    routes = inject(WORKER_HTTP_ROUTES_TOKEN);
+    fallback = inject(WORKER_HTTP_FALLBACK_TOKEN);
+    serializer = inject(WORKER_HTTP_SERIALIZER_TOKEN);
+    fetchBackend = inject(FetchBackend, { optional: true });
+    transports = new Map();
+    handle(req) {
+        if (typeof Worker === 'undefined') {
+            return this.handleFallback(req, 'Web Workers are not available in this environment (SSR)');
+        }
+        const workerId = req.context.get(WORKER_TARGET) ?? matchWorkerRoute(req.url, this.routes);
+        if (!workerId) {
+            return this.handleFallback(req, `No worker route matched for URL: ${req.url}`);
+        }
+        const config = this.configs.find((c) => c.id === workerId);
+        if (!config) {
+            return throwError(() => new Error(`[WorkerHttpBackend] Unknown worker id: "${workerId}". ` +
+                `Register it via withWorkerConfigs([{ id: "${workerId}", workerUrl: ... }]).`));
+        }
+        const transport = this.getOrCreateTransport(config);
+        const serializable = toSerializableRequest(req);
+        const body = this.serializer !== null && serializable.body !== null && serializable.body !== undefined
+            ? this.serializer.serialize(serializable.body).data
+            : serializable.body;
+        const payload = body !== serializable.body ? { ...serializable, body } : serializable;
+        return transport.execute(payload).pipe(map((res) => toHttpResponse(res, req)), catchError((err) => throwError(() => new HttpErrorResponse({
+            error: err,
+            status: 0,
+            statusText: 'Worker Error',
+            url: req.urlWithParams,
+        }))));
+    }
+    ngOnDestroy() {
+        for (const transport of this.transports.values()) {
+            transport.terminate();
+        }
+        this.transports.clear();
+    }
+    getOrCreateTransport(config) {
+        const existing = this.transports.get(config.id);
+        if (existing)
+            return existing;
+        const transport = createWorkerTransport({
+            workerFactory: () => new Worker(config.workerUrl, { type: 'module' }),
+            maxInstances: config.maxInstances ?? 1,
+        });
+        this.transports.set(config.id, transport);
+        return transport;
+    }
+    handleFallback(req, reason) {
+        if (this.fallback === 'error' || !this.fetchBackend) {
+            return throwError(() => new Error(`[WorkerHttpBackend] ${reason}`));
+        }
+        return this.fetchBackend.handle(req);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WorkerHttpBackend, deps: null, target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WorkerHttpBackend });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WorkerHttpBackend, decorators: [{
+            type: Injectable
+        }] });
+
+/**
+ * Convenience wrapper over `HttpClient` that adds an optional `{ worker }` field
+ * to every method. Under the hood it sets `WORKER_TARGET` on the `HttpContext` —
+ * the caller never has to touch the context manually.
+ *
+ * Usage is identical to `HttpClient` — just inject `WorkerHttpClient` instead.
+ *
+ * @example
+ * ```typescript
+ * @Injectable({ providedIn: 'root' })
+ * export class DataService {
+ *   private readonly http = inject(WorkerHttpClient);
+ *
+ *   getUsers(): Observable<User[]> {
+ *     return this.http.get<User[]>('/api/users'); // auto-routed by URL pattern
+ *   }
+ *
+ *   getSensitiveReport(): Observable<Report> {
+ *     return this.http.get<Report>('/api/secure/reports', { worker: 'secure' });
+ *   }
+ * }
+ * ```
+ */
+class WorkerHttpClient {
+    http = inject(HttpClient);
+    get(url, options) {
+        return this.http.get(url, this.withWorker(options));
+    }
+    post(url, body, options) {
+        return this.http.post(url, body, this.withWorker(options));
+    }
+    put(url, body, options) {
+        return this.http.put(url, body, this.withWorker(options));
+    }
+    patch(url, body, options) {
+        return this.http.patch(url, body, this.withWorker(options));
+    }
+    delete(url, options) {
+        return this.http.delete(url, this.withWorker(options));
+    }
+    head(url, options) {
+        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),
+        };
+    }
+    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 });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.4", ngImport: i0, type: WorkerHttpClient, decorators: [{
+            type: Injectable
+        }] });
+
+/**
+ * Sets up the worker HTTP infrastructure and replaces Angular's `HttpBackend`
+ * with `WorkerHttpBackend`.
+ *
+ * Drop-in companion to `provideHttpClient()`. Can be used INSTEAD of it —
+ * `HttpClient` and the full interceptor chain are included automatically.
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideWorkerHttpClient(
+ *       withWorkerConfigs([
+ *         { id: 'public', workerUrl: new URL('./workers/public.worker', import.meta.url) },
+ *       ]),
+ *       withWorkerRoutes([
+ *         { pattern: /\/api\//, worker: 'public', priority: 1 },
+ *       ]),
+ *       withWorkerFallback('main-thread'),
+ *     ),
+ *   ],
+ * };
+ * ```
+ */
+function provideWorkerHttpClient(...features) {
+    const featureProviders = features.flatMap((f) => f.providers);
+    return makeEnvironmentProviders([
+        provideHttpClient(withFetch()),
+        FetchBackend,
+        { provide: HttpBackend, useClass: WorkerHttpBackend },
+        WorkerHttpClient,
+        ...featureProviders,
+    ]);
+}
+/**
+ * Registers worker definitions (id + workerUrl + optional pool size).
+ *
+ * At least one config is required for any request to reach a worker.
+ *
+ * @example
+ * ```typescript
+ * withWorkerConfigs([
+ *   { id: 'public', workerUrl: new URL('./workers/public.worker', import.meta.url) },
+ *   { id: 'secure', workerUrl: new URL('./workers/secure.worker', import.meta.url), maxInstances: 2 },
+ * ])
+ * ```
+ */
+function withWorkerConfigs(configs) {
+    return {
+        kind: 'WorkerConfigs',
+        providers: [{ provide: WORKER_HTTP_CONFIGS_TOKEN, useValue: configs }],
+    };
+}
+/**
+ * Declares URL-pattern → worker routing rules evaluated in priority order.
+ *
+ * When a request URL matches a pattern, the associated worker handles it.
+ * Explicit `WORKER_TARGET` context always takes precedence over routes.
+ *
+ * @example
+ * ```typescript
+ * withWorkerRoutes([
+ *   { pattern: /\/api\/secure\//, worker: 'secure', priority: 10 },
+ *   { pattern: /\/api\//, worker: 'public', priority: 1 },
+ * ])
+ * ```
+ */
+function withWorkerRoutes(routes) {
+    return {
+        kind: 'WorkerRoutes',
+        providers: [{ provide: WORKER_HTTP_ROUTES_TOKEN, useValue: routes }],
+    };
+}
+/**
+ * Sets the fallback strategy when workers are unavailable (SSR, old browsers,
+ * or when no route matches).
+ *
+ * - `'main-thread'` (default) — silently delegates to `FetchBackend`
+ * - `'error'` — throws, forcing explicit handling in the application
+ *
+ * @example
+ * ```typescript
+ * withWorkerFallback('main-thread') // SSR-safe
+ * ```
+ */
+function withWorkerFallback(strategy) {
+    return {
+        kind: 'WorkerFallback',
+        providers: [{ provide: WORKER_HTTP_FALLBACK_TOKEN, useValue: strategy }],
+    };
+}
+/**
+ * Configures a custom serializer for crossing the worker boundary.
+ *
+ * By default `WorkerHttpBackend` relies on the browser's structured clone algorithm
+ * (safe for plain objects, arrays, primitives, `Date`, `ArrayBuffer`).
+ * Use `withWorkerSerialization` when your request bodies contain types that
+ * structured clone cannot handle (e.g. class instances, circular references, `Map`, `Set`).
+ *
+ * **Worker-side note:** The serialized form is what the worker receives as `req.body`.
+ * If you use `createSerovalSerializer` or similar, add a worker-side interceptor
+ * to deserialize the body before calling `fetch()`.
+ *
+ * @example
+ * ```typescript
+ * import { createSerovalSerializer } from '@angular-helpers/worker-http/serializer';
+ *
+ * provideWorkerHttpClient(
+ *   withWorkerConfigs([...]),
+ *   withWorkerSerialization(createSerovalSerializer()),
+ * )
+ * ```
+ */
+function withWorkerSerialization(serializer) {
+    return {
+        kind: 'WorkerSerialization',
+        providers: [{ provide: WORKER_HTTP_SERIALIZER_TOKEN, useValue: serializer }],
+    };
+}
+
 /**
  * Generated bundle index. Do not edit.
  */
+
+export { WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withWorkerConfigs, withWorkerFallback, withWorkerRoutes, withWorkerSerialization };

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

@@ -228,7 +228,7 @@ function arrayBufferToHex$1(buffer) {
     return [...new Uint8Array(buffer)].map((b) => b.toString(16).padStart(2, '0')).join('');
 }
 function defaultPayloadBuilder(req) {
-    const body = req.body != null ? JSON.stringify(req.body) : '';
+    const body = req.body !== null && req.body !== undefined ? JSON.stringify(req.body) : '';
     return `${req.method}:${req.url}:${body}`;
 }
 /**
@@ -315,7 +315,7 @@ function loggingInterceptor(config) {
         catch (error) {
             const elapsedMs = Date.now() - startMs;
             const status = error.status;
-            const label = status != null ? String(status) : 'NETWORK_ERROR';
+            const label = status !== null && status !== undefined ? String(status) : 'NETWORK_ERROR';
             safeLog(`[worker] ✕ ${label} ${req.url} (${elapsedMs}ms)`, error);
             throw error;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@angular-helpers/worker-http",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Angular HTTP over Web Workers — off-main-thread HTTP pipelines with configurable interceptors, WebCrypto security, and pluggable serialization",
   "keywords": [
     "angular",

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

@@ -1,4 +1,8 @@
-import { Provider } from '@angular/core';
+import * as i0 from '@angular/core';
+import { Provider, InjectionToken, EnvironmentProviders, OnDestroy } from '@angular/core';
+import { HttpContextToken, HttpBackend, HttpRequest, HttpEvent, HttpContext, HttpResponse } from '@angular/common/http';
+import { WorkerSerializer } from '@angular-helpers/worker-http/serializer';
+import { Observable } from 'rxjs';
 
 /**
  * Discriminated union for worker HTTP feature kinds.
@@ -38,5 +42,255 @@ interface WorkerRoute {
  * Fallback strategy when workers are unavailable (SSR, old browsers).
  */
 type WorkerFallbackStrategy = 'main-thread' | 'error';
+/**
+ * Serializable HTTP request — POJO version of Angular's HttpRequest.
+ * Structured-clone safe: no classes, no functions, no prototype chains.
+ */
+interface SerializableRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string[]>;
+    params: Record<string, string[]>;
+    body: unknown;
+    responseType: 'json' | 'text' | 'blob' | 'arraybuffer';
+    withCredentials: boolean;
+    context: Record<string, unknown>;
+}
+/**
+ * Serializable HTTP response — POJO version of Angular's HttpResponse.
+ */
+interface SerializableResponse {
+    status: number;
+    statusText: string;
+    headers: Record<string, string[]>;
+    body: unknown;
+    url: string;
+}
+
+/**
+ * Per-request HttpContextToken that carries the target worker ID.
+ *
+ * `null` → use URL-pattern auto-routing (or main-thread fallback if no route matches).
+ *
+ * @example
+ * ```typescript
+ * // With WorkerHttpClient (recommended)
+ * this.http.get('/api/data', { worker: 'secure' });
+ *
+ * // With standard HttpClient (power user)
+ * this.http.get('/api/data', {
+ *   context: new HttpContext().set(WORKER_TARGET, 'secure'),
+ * });
+ * ```
+ */
+declare const WORKER_TARGET: HttpContextToken<string>;
+/**
+ * Optional serializer for crossing the worker boundary.
+ * Provided via `withWorkerSerialization()`. Defaults to `null` (structured clone).
+ *
+ * When set, `WorkerHttpBackend` serializes the request body before `postMessage`
+ * using this serializer. The worker-side `createWorkerPipeline()` receives the
+ * serialized form — add a worker interceptor to deserialize it if needed.
+ */
+declare const WORKER_HTTP_SERIALIZER_TOKEN: InjectionToken<WorkerSerializer>;
+
+/**
+ * Sets up the worker HTTP infrastructure and replaces Angular's `HttpBackend`
+ * with `WorkerHttpBackend`.
+ *
+ * Drop-in companion to `provideHttpClient()`. Can be used INSTEAD of it —
+ * `HttpClient` and the full interceptor chain are included automatically.
+ *
+ * @example
+ * ```typescript
+ * // app.config.ts
+ * export const appConfig: ApplicationConfig = {
+ *   providers: [
+ *     provideWorkerHttpClient(
+ *       withWorkerConfigs([
+ *         { id: 'public', workerUrl: new URL('./workers/public.worker', import.meta.url) },
+ *       ]),
+ *       withWorkerRoutes([
+ *         { pattern: /\/api\//, worker: 'public', priority: 1 },
+ *       ]),
+ *       withWorkerFallback('main-thread'),
+ *     ),
+ *   ],
+ * };
+ * ```
+ */
+declare function provideWorkerHttpClient(...features: WorkerHttpFeature<WorkerHttpFeatureKind>[]): EnvironmentProviders;
+/**
+ * Registers worker definitions (id + workerUrl + optional pool size).
+ *
+ * At least one config is required for any request to reach a worker.
+ *
+ * @example
+ * ```typescript
+ * withWorkerConfigs([
+ *   { id: 'public', workerUrl: new URL('./workers/public.worker', import.meta.url) },
+ *   { id: 'secure', workerUrl: new URL('./workers/secure.worker', import.meta.url), maxInstances: 2 },
+ * ])
+ * ```
+ */
+declare function withWorkerConfigs(configs: WorkerConfig[]): WorkerHttpFeature<'WorkerConfigs'>;
+/**
+ * Declares URL-pattern → worker routing rules evaluated in priority order.
+ *
+ * When a request URL matches a pattern, the associated worker handles it.
+ * Explicit `WORKER_TARGET` context always takes precedence over routes.
+ *
+ * @example
+ * ```typescript
+ * withWorkerRoutes([
+ *   { pattern: /\/api\/secure\//, worker: 'secure', priority: 10 },
+ *   { pattern: /\/api\//, worker: 'public', priority: 1 },
+ * ])
+ * ```
+ */
+declare function withWorkerRoutes(routes: WorkerRoute[]): WorkerHttpFeature<'WorkerRoutes'>;
+/**
+ * Sets the fallback strategy when workers are unavailable (SSR, old browsers,
+ * or when no route matches).
+ *
+ * - `'main-thread'` (default) — silently delegates to `FetchBackend`
+ * - `'error'` — throws, forcing explicit handling in the application
+ *
+ * @example
+ * ```typescript
+ * withWorkerFallback('main-thread') // SSR-safe
+ * ```
+ */
+declare function withWorkerFallback(strategy: WorkerFallbackStrategy): WorkerHttpFeature<'WorkerFallback'>;
+/**
+ * Configures a custom serializer for crossing the worker boundary.
+ *
+ * By default `WorkerHttpBackend` relies on the browser's structured clone algorithm
+ * (safe for plain objects, arrays, primitives, `Date`, `ArrayBuffer`).
+ * Use `withWorkerSerialization` when your request bodies contain types that
+ * structured clone cannot handle (e.g. class instances, circular references, `Map`, `Set`).
+ *
+ * **Worker-side note:** The serialized form is what the worker receives as `req.body`.
+ * If you use `createSerovalSerializer` or similar, add a worker-side interceptor
+ * to deserialize the body before calling `fetch()`.
+ *
+ * @example
+ * ```typescript
+ * import { createSerovalSerializer } from '@angular-helpers/worker-http/serializer';
+ *
+ * provideWorkerHttpClient(
+ *   withWorkerConfigs([...]),
+ *   withWorkerSerialization(createSerovalSerializer()),
+ * )
+ * ```
+ */
+declare function withWorkerSerialization(serializer: WorkerSerializer): WorkerHttpFeature<'WorkerSerialization'>;
+
+/**
+ * Angular `HttpBackend` replacement that routes HTTP requests to web workers.
+ *
+ * Registered via `provideWorkerHttpClient()`. Not meant to be used directly.
+ *
+ * Flow per request:
+ * 1. Check SSR: if `Worker` is undefined → fallback strategy
+ * 2. Resolve target worker ID from `WORKER_TARGET` context or URL-pattern routing
+ * 3. Serialize `HttpRequest` → `SerializableRequest` (structured-clone safe)
+ * 4. Dispatch to the worker's `WorkerTransport`
+ * 5. Deserialize `SerializableResponse` → `HttpResponse`
+ */
+declare class WorkerHttpBackend extends HttpBackend implements OnDestroy {
+    private readonly configs;
+    private readonly routes;
+    private readonly fallback;
+    private readonly serializer;
+    private readonly fetchBackend;
+    private readonly transports;
+    handle(req: HttpRequest<unknown>): Observable<HttpEvent<unknown>>;
+    ngOnDestroy(): void;
+    private getOrCreateTransport;
+    private handleFallback;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WorkerHttpBackend, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WorkerHttpBackend>;
+}
+
+/**
+ * Options accepted by `WorkerHttpClient` methods.
+ * Identical to `HttpClient` options with an optional `worker` field added.
+ */
+interface WorkerRequestOptions {
+    /** Target worker ID. Overrides URL-pattern routing for this specific request. */
+    worker?: string | null;
+    context?: HttpContext;
+    headers?: Record<string, string | string[]>;
+    params?: Record<string, string | number | boolean | ReadonlyArray<string | number | boolean>>;
+    responseType?: 'json';
+    withCredentials?: boolean;
+    observe?: 'body';
+    reportProgress?: boolean;
+    transferCache?: {
+        includeHeaders?: string[];
+    } | boolean;
+}
+/**
+ * Convenience wrapper over `HttpClient` that adds an optional `{ worker }` field
+ * to every method. Under the hood it sets `WORKER_TARGET` on the `HttpContext` —
+ * the caller never has to touch the context manually.
+ *
+ * Usage is identical to `HttpClient` — just inject `WorkerHttpClient` instead.
+ *
+ * @example
+ * ```typescript
+ * @Injectable({ providedIn: 'root' })
+ * export class DataService {
+ *   private readonly http = inject(WorkerHttpClient);
+ *
+ *   getUsers(): Observable<User[]> {
+ *     return this.http.get<User[]>('/api/users'); // auto-routed by URL pattern
+ *   }
+ *
+ *   getSensitiveReport(): Observable<Report> {
+ *     return this.http.get<Report>('/api/secure/reports', { worker: 'secure' });
+ *   }
+ * }
+ * ```
+ */
+declare class WorkerHttpClient {
+    private readonly http;
+    get<T>(url: string, options?: WorkerRequestOptions): Observable<T>;
+    post<T>(url: string, body: unknown, options?: WorkerRequestOptions): Observable<T>;
+    put<T>(url: string, body: unknown, options?: WorkerRequestOptions): Observable<T>;
+    patch<T>(url: string, body: unknown, options?: WorkerRequestOptions): Observable<T>;
+    delete<T>(url: string, options?: WorkerRequestOptions): Observable<T>;
+    head<T>(url: string, options?: WorkerRequestOptions): Observable<T>;
+    private withWorker;
+    static ɵfac: i0.ɵɵFactoryDeclaration<WorkerHttpClient, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<WorkerHttpClient>;
+}
+
+/**
+ * Converts an Angular `HttpRequest` into a structured-clone-safe POJO
+ * that can be sent to a web worker via `postMessage`.
+ *
+ * Notes:
+ * - `urlWithParams` is used so query params embedded via `HttpParams` are included.
+ * - The `context` field is intentionally left empty: `HttpContext` uses class references
+ *   as keys which cannot cross the worker boundary.
+ */
+declare function toSerializableRequest(req: HttpRequest<unknown>): SerializableRequest;
+/**
+ * Converts a worker `SerializableResponse` back into an Angular `HttpResponse`.
+ */
+declare function toHttpResponse(res: SerializableResponse, req: HttpRequest<unknown>): HttpResponse<unknown>;
+/**
+ * Matches a URL against a sorted list of `WorkerRoute` rules.
+ * Rules with higher `priority` are evaluated first.
+ * Returns the matched worker ID or `null` if no rule matches.
+ */
+declare function matchWorkerRoute(url: string, routes: Array<{
+    pattern: RegExp | string;
+    worker: string;
+    priority?: number;
+}>): string | null;
 
-export type { WorkerConfig, WorkerFallbackStrategy, WorkerHttpFeature, WorkerHttpFeatureKind, WorkerRoute };
+export { WORKER_HTTP_SERIALIZER_TOKEN, WORKER_TARGET, WorkerHttpBackend, WorkerHttpClient, matchWorkerRoute, provideWorkerHttpClient, toHttpResponse, toSerializableRequest, withWorkerConfigs, withWorkerFallback, withWorkerRoutes, withWorkerSerialization };
+export type { SerializableRequest, SerializableResponse, WorkerConfig, WorkerFallbackStrategy, WorkerHttpFeature, WorkerHttpFeatureKind, WorkerRequestOptions, WorkerRoute };