@angular-helpers/worker-http 1.0.0 → 21.1.0

package/README.md

@@ -113,6 +113,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
@@ -470,9 +475,10 @@ 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.
 
 ---
 

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-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": "1.0.0",
+  "version": "21.1.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": {

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-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 };