@angular-helpers/worker-http 0.2.0

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

@@ -0,0 +1,89 @@
+/**
+ * Serialized payload ready for postMessage transfer.
+ */
+interface SerializedPayload {
+    /** Serialized data (may be string, ArrayBuffer, or structured-clone-safe object) */
+    data: unknown;
+    /** Transferable objects to pass to postMessage (zero-copy) */
+    transferables: Transferable[];
+    /** Format identifier for deserialization */
+    format: 'structured-clone' | 'toon' | 'seroval' | 'custom';
+}
+/**
+ * Pluggable serializer interface for crossing the worker boundary.
+ */
+interface WorkerSerializer {
+    /** Serialize data for transfer to/from worker */
+    serialize(data: unknown): SerializedPayload;
+    /** Deserialize data received from worker/main thread */
+    deserialize(payload: SerializedPayload): unknown;
+}
+/**
+ * Strategy for automatic serializer selection based on payload shape.
+ */
+type SerializerStrategy = 'auto' | 'structured-clone' | 'toon' | 'seroval' | 'custom';
+/**
+ * Configuration for the auto-detect serializer.
+ */
+interface AutoSerializerConfig {
+    /** Size threshold (bytes) above which to use ArrayBuffer transfer (default: 102400 = 100 KiB) */
+    transferThreshold?: number;
+    /** Custom serializer to use when strategy is 'custom' */
+    custom?: WorkerSerializer;
+}
+
+/**
+ * Default serializer that relies on the browser's native structured clone algorithm.
+ * Zero overhead — data is passed directly to postMessage without transformation.
+ *
+ * Best for: small payloads (< 100 KiB), simple types.
+ * Limitations: cannot handle functions, DOM nodes, or class instances with prototype chains.
+ */
+declare const structuredCloneSerializer: WorkerSerializer;
+
+/**
+ * Creates a `WorkerSerializer` backed by `seroval` for full type fidelity.
+ *
+ * Supports `Date`, `Map`, `Set`, `BigInt`, `RegExp`, circular references, and more.
+ * The factory is async because it dynamically imports the optional `seroval` peer.
+ *
+ * `seroval` must be installed separately:
+ * ```
+ * npm install seroval
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const serializer = await createSerovalSerializer();
+ * const payload = serializer.serialize({ date: new Date(), map: new Map() });
+ * const original = serializer.deserialize(payload);
+ * ```
+ *
+ * @see https://github.com/lxsmnsyc/seroval
+ */
+declare function createSerovalSerializer(): Promise<WorkerSerializer>;
+
+/**
+ * Creates an auto-detecting `WorkerSerializer` that picks the best strategy per payload.
+ *
+ * The factory is async because it pre-loads `seroval` during initialization
+ * so the returned serializer methods are fully synchronous (no await in hot path).
+ *
+ * Strategy selection per `serialize()` call:
+ * - Contains `Date`, `Map`, `Set`, or `RegExp` at depth-1 → `seroval` (full fidelity)
+ * - Otherwise → structured clone (native, zero overhead)
+ *
+ * Large payloads (> `transferThreshold`, default 100 KiB) are encoded to
+ * `ArrayBuffer` and added to `transferables` for zero-copy `postMessage` transfer.
+ *
+ * @example
+ * ```typescript
+ * const auto = await createAutoSerializer();
+ * const payload = auto.serialize({ users, fetchedAt: new Date() });
+ * worker.postMessage({ payload }, payload.transferables);
+ * ```
+ */
+declare function createAutoSerializer(config?: AutoSerializerConfig): Promise<WorkerSerializer>;
+
+export { createAutoSerializer, createSerovalSerializer, structuredCloneSerializer };
+export type { AutoSerializerConfig, SerializedPayload, SerializerStrategy, WorkerSerializer };

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

@@ -0,0 +1,115 @@
+import { Observable } from 'rxjs';
+
+/**
+ * Configuration for creating a worker transport.
+ *
+ * IMPORTANT: Angular CLI's esbuild bundler only detects web workers when
+ * `new Worker(new URL(...))` appears directly in application source code.
+ * For pre-transpiled workers, use `workerUrl` instead.
+ */
+interface WorkerTransportConfig {
+    /**
+     * Factory function that creates a new Worker instance.
+     * The `new Worker(new URL(...))` call MUST be in your app code (not a library)
+     * for Angular CLI to bundle the worker correctly.
+     *
+     * @example
+     * ```typescript
+     * workerFactory: () => new Worker(new URL('./echo.worker.ts', import.meta.url), { type: 'module' })
+     * ```
+     */
+    workerFactory?: () => Worker;
+    /**
+     * URL to a pre-transpiled worker file.
+     * Use this when workers are built separately (e.g., with Vite) and distributed
+     * as static assets. Resolves against the document's base URI.
+     *
+     * @example
+     * ```typescript
+     * workerUrl: 'assets/workers/echo.worker.js'
+     * // or with full URL
+     * workerUrl: new URL('workers/echo.worker.js', import.meta.url).href
+     * ```
+     */
+    workerUrl?: string | URL;
+    /** Maximum number of worker instances in the pool (default: 1) */
+    maxInstances?: number;
+    /** Transfer strategy for large payloads */
+    transferDetection?: 'auto' | 'manual' | 'none';
+    /** Timeout in ms for a single request (default: 30000) */
+    requestTimeout?: number;
+}
+/**
+ * Message sent from main thread to worker.
+ */
+interface WorkerMessage<TPayload = unknown> {
+    type: 'request' | 'cancel';
+    requestId: string;
+    payload?: TPayload;
+    transferables?: Transferable[];
+}
+/**
+ * Successful response from worker to main thread.
+ */
+interface WorkerResponse<TResult = unknown> {
+    type: 'response';
+    requestId: string;
+    result: TResult;
+    transferables?: Transferable[];
+}
+/**
+ * Error response from worker to main thread.
+ */
+interface WorkerErrorResponse {
+    type: 'error';
+    requestId: string;
+    error: {
+        message: string;
+        name: string;
+        stack?: string;
+        status?: number;
+        statusText?: string;
+    };
+}
+/**
+ * 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>;
+    /** Terminate all workers and release resources */
+    terminate(): void;
+    /** Whether the transport has active workers */
+    readonly isActive: boolean;
+    /** Number of currently active worker instances */
+    readonly activeInstances: number;
+}
+
+/**
+ * Creates a typed, Observable-based transport for communicating with a web worker.
+ *
+ * Features:
+ * - Request/response correlation via `requestId`
+ * - Automatic cancellation on Observable unsubscribe
+ * - Optional worker pool with round-robin dispatch
+ * - Lazy worker creation (default)
+ * - Transferable auto-detection for ArrayBuffer payloads
+ *
+ * @example
+ * ```typescript
+ * const transport = createWorkerTransport<MyRequest, MyResponse>({
+ *   workerFactory: () => new Worker(new URL('./my.worker.ts', import.meta.url), { type: 'module' }),
+ *   maxInstances: 2,
+ * });
+ *
+ * transport.execute(request).subscribe({
+ *   next: (response) => console.log(response),
+ *   error: (err) => console.error(err),
+ * });
+ * ```
+ */
+declare function createWorkerTransport<TRequest = unknown, TResponse = unknown>(config: WorkerTransportConfig): WorkerTransport<TRequest, TResponse>;
+
+export { createWorkerTransport };
+export type { WorkerErrorResponse, WorkerMessage, WorkerResponse, WorkerTransport, WorkerTransportConfig };

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

@@ -0,0 +1,16 @@
+/**
+ * @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 };