@effectionx/worker 0.4.2 → 0.5.1

package/dist/types.d.ts

@@ -1,4 +1,7 @@
-import type { Operation } from "effection";
+import type { Operation, Result, Subscription } from "effection";
+/**
+ * Messages sent from host to worker (control messages).
+ */
 export type WorkerControl<TSend, TData> = {
     type: "init";
     data: TData;
@@ -9,15 +12,146 @@ export type WorkerControl<TSend, TData> = {
 } | {
     type: "close";
 };
-export interface WorkerMainOptions<TSend, TRecv, TData> {
+/**
+ * Messages sent from worker to host.
+ *
+ * @template WRequest - value worker sends to host in requests
+ * @template TReturn - return value when worker completes
+ */
+export type WorkerToHost<WRequest, TReturn> = {
+    type: "open";
+} | {
+    type: "request";
+    value: WRequest;
+    response: MessagePort;
+} | {
+    type: "close";
+    result: Result<TReturn>;
+};
+/**
+ * Serialized error format for cross-boundary communication.
+ * Error objects cannot be cloned via postMessage, so we serialize them.
+ */
+export interface SerializedError {
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: SerializedError;
+}
+/**
+ * A Result type for cross-boundary communication where errors are serialized.
+ * Unlike effection's Result<T> which uses Error, this uses SerializedError.
+ *
+ * Used by channel primitives to send success/error responses over MessageChannel.
+ */
+export type SerializedResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: SerializedError;
+};
+/**
+ * Messages sent over a channel that supports progress streaming.
+ * Used by useChannelRequest to send progress updates and final response.
+ */
+export type ChannelMessage<TResponse, TProgress> = {
+    type: "progress";
+    data: TProgress;
+} | {
+    type: "response";
+    result: SerializedResult<TResponse>;
+};
+/**
+ * Acknowledgement messages sent back over a channel.
+ * Used by useChannelResponse to acknowledge receipt of messages.
+ */
+export type ChannelAck = {
+    type: "ack";
+} | {
+    type: "progress_ack";
+};
+/**
+ * Context passed to forEach handler for progress streaming.
+ * Allows the handler to send progress updates back to the requester.
+ *
+ * @template TProgress - The progress data type
+ */
+export interface ForEachContext<TProgress> {
     /**
-     * Namespace that provides APIs for working with incoming messages
+     * Send a progress update to the requester.
+     * This operation blocks until the requester acknowledges receipt (backpressure).
+     *
+     * @param data - The progress data to send
+     */
+    progress(data: TProgress): Operation<void>;
+}
+/**
+ * Serialize an Error for transmission via postMessage.
+ * Recursively serializes error.cause if present.
+ */
+export declare function serializeError(error: Error): SerializedError;
+/**
+ * Create an Error from a serialized error, with original data in `cause`.
+ *
+ * @param context - Description of where the error occurred (e.g., "Host handler failed")
+ * @param serialized - The serialized error data
+ */
+export declare function errorFromSerialized(context: string, serialized: SerializedError): Error;
+/**
+ * A send function that supports both simple request/response and progress streaming.
+ *
+ * @template WRequest - value worker sends to host
+ * @template WResponse - value worker receives from host
+ */
+export interface WorkerSend<WRequest, WResponse> {
+    /**
+     * Send a request to the host and wait for a response.
+     * Ignores any progress updates from the host.
+     */
+    (value: WRequest): Operation<WResponse>;
+    /**
+     * Send a request to the host and receive a subscription that yields
+     * progress updates and returns the final response.
+     *
+     * @template WProgress - progress type from host
+     *
+     * @example
+     * ```ts
+     * const subscription = yield* send.stream<number>(request);
+     * let next = yield* subscription.next();
+     * while (!next.done) {
+     *   console.log("Progress:", next.value);
+     *   next = yield* subscription.next();
+     * }
+     * const response = next.value;
+     * ```
+     */
+    stream<WProgress>(value: WRequest): Operation<Subscription<WProgress, WResponse>>;
+}
+/**
+ * Options passed to the worker's main function.
+ *
+ * @template TSend - value host sends to worker
+ * @template TRecv - value host receives from worker (response to host's send)
+ * @template TData - initial data passed to worker
+ * @template WRequest - value worker sends to host in requests
+ * @template WResponse - value worker receives from host (response to worker's send)
+ */
+export interface WorkerMainOptions<TSend, TRecv, TData, WRequest = never, WResponse = never> {
+    /**
+     * Namespace that provides APIs for working with incoming messages from host.
      */
     messages: WorkerMessages<TSend, TRecv>;
     /**
      * Initial data received by the worker from the main thread used for initialization.
      */
     data: TData;
+    /**
+     * Send a request to the host and wait for a response.
+     * Also supports progress streaming via `send.stream()`.
+     */
+    send: WorkerSend<WRequest, WResponse>;
 }
 /**
  * Object that represents messages the main thread

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,MAAM,MAAM,aAAa,CAAC,KAAK,EAAE,KAAK,IAClC;IACE,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,KAAK,CAAC;CACb,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,QAAQ,EAAE,WAAW,CAAC;CACvB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;CACf,CAAC;AAEN,MAAM,WAAW,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK;IACpD;;OAEG;IACH,QAAQ,EAAE,cAAc,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IACvC;;OAEG;IACH,IAAI,EAAE,KAAK,CAAC;CACb;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,EAAE,KAAK;IAC1C,OAAO,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,IAAI,CAAC,CAAC;CACpE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -1 +1,27 @@
-export {};
+/**
+ * Serialize an Error for transmission via postMessage.
+ * Recursively serializes error.cause if present.
+ */
+export function serializeError(error) {
+    const serialized = {
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+    };
+    // Recursively serialize cause if it's an Error
+    if (error.cause instanceof Error) {
+        serialized.cause = serializeError(error.cause);
+    }
+    return serialized;
+}
+/**
+ * Create an Error from a serialized error, with original data in `cause`.
+ *
+ * @param context - Description of where the error occurred (e.g., "Host handler failed")
+ * @param serialized - The serialized error data
+ */
+export function errorFromSerialized(context, serialized) {
+    return new Error(`${context}: ${serialized.message}`, {
+        cause: serialized,
+    });
+}

package/dist/worker-main.d.ts

@@ -44,14 +44,28 @@ import type { WorkerMainOptions } from "./types.ts";
  * );
  * ```
  *
+ * @example Sending requests to the host
+ * ```ts
+ * import { workerMain } from "../worker.ts";
+ *
+ * await workerMain<never, never, string, void, string, string>(
+ *   function* ({ send }) {
+ *     const response = yield* send("hello");
+ *     return `received: ${response}`;
+ *   },
+ * );
+ * ```
+ *
  * @template TSend - value main thread will send to the worker
  * @template TRecv - value main thread will receive from the worker
  * @template TReturn - worker operation return value
  * @template TData - data passed from the main thread to the worker during initialization
- * @param {(options: WorkerMainOptions<TSend, TRecv, TData>) => Operation<TReturn>} body
+ * @template WRequest - value worker sends to the host in requests
+ * @template WResponse - value worker receives from the host (response to worker's send)
+ * @param {(options: WorkerMainOptions<TSend, TRecv, TData, WRequest, WResponse>) => Operation<TReturn>} body
  * @returns {Promise<void>}
  */
-export declare function workerMain<TSend, TRecv, TReturn, TData>(body: (options: WorkerMainOptions<TSend, TRecv, TData>) => Operation<TReturn>): Promise<void>;
+export declare function workerMain<TSend, TRecv, TReturn, TData, WRequest = never, WResponse = never>(body: (options: WorkerMainOptions<TSend, TRecv, TData, WRequest, WResponse>) => Operation<TReturn>): Promise<void>;
 type New = {
     type: "new";
 };

package/dist/worker-main.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker-main.d.ts","sourceRoot":"","sources":["../worker-main.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,IAAI,EAOV,MAAM,WAAW,CAAC;AAEnB,OAAO,KAAK,EAAiB,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAiBnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAC3D,IAAI,EAAE,CAAC,OAAO,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,SAAS,CAAC,OAAO,CAAC,GAC5E,OAAO,CAAC,IAAI,CAAC,CA8Ef;AAED,KAAK,GAAG,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAC3B,KAAK,OAAO,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AACrD,KAAK,QAAQ,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AACrD,KAAK,OAAO,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAC/C,KAAK,WAAW,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEzD,KAAK,WAAW,GAAG,GAAG,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;AAEpE,UAAU,iBAAkB,SAAQ,WAAW,CAAC,WAAW,CAAC;IAC1D,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IAC7B,SAAS,IAAI,WAAW,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,IAAI,SAAS,CAAC,iBAAiB,CAAC,CAkEvE"}
+{"version":3,"file":"worker-main.d.ts","sourceRoot":"","sources":["../worker-main.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,IAAI,EAQV,MAAM,WAAW,CAAC;AAInB,OAAO,KAAK,EAGV,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAkBpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EACL,KAAK,EACL,OAAO,EACP,KAAK,EACL,QAAQ,GAAG,KAAK,EAChB,SAAS,GAAG,KAAK,EAEjB,IAAI,EAAE,CACJ,OAAO,EAAE,iBAAiB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,CAAC,KACjE,SAAS,CAAC,OAAO,CAAC,GACtB,OAAO,CAAC,IAAI,CAAC,CA8Jf;AAED,KAAK,GAAG,GAAG;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,CAAC;AAC3B,KAAK,OAAO,GAAG;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AACrD,KAAK,QAAQ,GAAG;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,EAAE,OAAO,CAAA;CAAE,CAAC;AACrD,KAAK,OAAO,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAC/C,KAAK,WAAW,GAAG;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAC;AAEzD,KAAK,WAAW,GAAG,GAAG,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,WAAW,CAAC;AAEpE,UAAU,iBAAkB,SAAQ,WAAW,CAAC,WAAW,CAAC;IAC1D,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IAC7B,SAAS,IAAI,WAAW,CAAC;CAC1B;AAED,wBAAgB,wBAAwB,IAAI,SAAS,CAAC,iBAAiB,CAAC,CAkEvE"}

package/dist/worker-main.js

@@ -1,6 +1,8 @@
 import assert from "node:assert";
 import { MessagePort, parentPort } from "node:worker_threads";
-import { Err, Ok, createSignal, each, main, on, resource, spawn, } from "effection";
+import { Err, Ok, createChannel, createSignal, each, main, on, resource, spawn, } from "effection";
+import { useChannelRequest, useChannelResponse } from "./channel.js";
+import { errorFromSerialized } from "./types.js";
 // Get the appropriate worker port for the current environment as a resource
 function useWorkerPort() {
     return resource(function* (provide) {
@@ -58,17 +60,31 @@ function useWorkerPort() {
  * );
  * ```
  *
+ * @example Sending requests to the host
+ * ```ts
+ * import { workerMain } from "../worker.ts";
+ *
+ * await workerMain<never, never, string, void, string, string>(
+ *   function* ({ send }) {
+ *     const response = yield* send("hello");
+ *     return `received: ${response}`;
+ *   },
+ * );
+ * ```
+ *
  * @template TSend - value main thread will send to the worker
  * @template TRecv - value main thread will receive from the worker
  * @template TReturn - worker operation return value
  * @template TData - data passed from the main thread to the worker during initialization
- * @param {(options: WorkerMainOptions<TSend, TRecv, TData>) => Operation<TReturn>} body
+ * @template WRequest - value worker sends to the host in requests
+ * @template WResponse - value worker receives from the host (response to worker's send)
+ * @param {(options: WorkerMainOptions<TSend, TRecv, TData, WRequest, WResponse>) => Operation<TReturn>} body
  * @returns {Promise<void>}
  */
 export async function workerMain(body) {
     await main(function* () {
         const port = yield* useWorkerPort();
-        let sent = createSignal();
+        let sent = createChannel();
         let worker = yield* createWorkerStatesSignal();
         yield* spawn(function* () {
             for (const message of yield* each(on(port, "message"))) {
@@ -78,24 +94,80 @@ export async function workerMain(body) {
                     case "init": {
                         worker.start(yield* spawn(function* () {
                             try {
+                                // Helper to unwrap SerializedResult
+                                function unwrapResult(result) {
+                                    if (result.ok) {
+                                        return result.value;
+                                    }
+                                    throw errorFromSerialized("Host handler failed", result.error);
+                                }
+                                // Create send function for worker-initiated requests
+                                function send(requestValue) {
+                                    return {
+                                        *[Symbol.iterator]() {
+                                            const response = yield* useChannelResponse();
+                                            port.postMessage({
+                                                type: "request",
+                                                value: requestValue,
+                                                response: response.port,
+                                            }, 
+                                            // biome-ignore lint/suspicious/noExplicitAny: cross-env MessagePort compatibility
+                                            [response.port]);
+                                            const result = yield* response;
+                                            return unwrapResult(result);
+                                        },
+                                    };
+                                }
+                                // Add stream method for progress streaming
+                                send.stream = (requestValue) => ({
+                                    *[Symbol.iterator]() {
+                                        const response = yield* useChannelResponse();
+                                        port.postMessage({
+                                            type: "request",
+                                            value: requestValue,
+                                            response: response.port,
+                                        }, 
+                                        // biome-ignore lint/suspicious/noExplicitAny: cross-env MessagePort compatibility
+                                        [response.port]);
+                                        // Get the progress subscription
+                                        const progressSubscription = yield* response.progress;
+                                        // Wrap it to unwrap the SerializedResult at the end
+                                        const wrappedSubscription = {
+                                            *next() {
+                                                const result = yield* progressSubscription.next();
+                                                if (result.done) {
+                                                    // Unwrap the SerializedResult
+                                                    return {
+                                                        done: true,
+                                                        value: unwrapResult(result.value),
+                                                    };
+                                                }
+                                                return result;
+                                            },
+                                        };
+                                        return wrappedSubscription;
+                                    },
+                                });
                                 let value = yield* body({
                                     data: control.data,
                                     messages: {
                                         *forEach(fn) {
                                             for (let { value, response } of yield* each(sent)) {
                                                 yield* spawn(function* () {
+                                                    const { resolve, reject } = yield* useChannelRequest(response);
                                                     try {
                                                         let result = yield* fn(value);
-                                                        response.postMessage(Ok(result));
+                                                        yield* resolve(result);
                                                     }
                                                     catch (error) {
-                                                        response.postMessage(Err(error));
+                                                        yield* reject(error);
                                                     }
                                                 });
                                                 yield* each.next();
                                             }
                                         },
                                     },
+                                    send,
                                 });
                                 worker.complete(value);
                             }
@@ -109,7 +181,7 @@ export async function workerMain(body) {
                         let { value, response } = control;
                         // Ensure that response is a proper MessagePort (DOM)
                         assert(response instanceof MessagePort, "Expect response to be an instance of MessagePort");
-                        sent.send({ value, response });
+                        yield* sent.send({ value, response });
                         break;
                     }
                     case "close": {

package/dist/worker.d.ts

@@ -1,13 +1,45 @@
 import { type Operation } from "effection";
+import { type ForEachContext } from "./types.ts";
 /**
- * Argument received by workerMain function
+ * Resource returned by useWorker, providing APIs for worker communication.
  *
  * @template TSend - value main thread will send to the worker
  * @template TRecv - value main thread will receive from the worker
- * @template TData - data passed from the main thread to the worker during initialization
+ * @template TReturn - worker operation return value
  */
 export interface WorkerResource<TSend, TRecv, TReturn> extends Operation<TReturn> {
+    /**
+     * Send a message to the worker and wait for a response.
+     */
     send(data: TSend): Operation<TRecv>;
+    /**
+     * Handle requests initiated by the worker.
+     * Only one forEach can be active at a time.
+     *
+     * The handler receives a context object with a `progress` method for
+     * sending progress updates back to the worker.
+     *
+     * @template WRequest - value worker sends to host
+     * @template WResponse - value host sends back to worker
+     * @template WProgress - progress type sent back to worker (optional)
+     *
+     * @example Basic usage (no progress)
+     * ```ts
+     * yield* worker.forEach(function* (request) {
+     *   return computeResponse(request);
+     * });
+     * ```
+     *
+     * @example With progress streaming
+     * ```ts
+     * yield* worker.forEach(function* (request, ctx) {
+     *   yield* ctx.progress({ step: 1, message: "Starting..." });
+     *   yield* ctx.progress({ step: 2, message: "Processing..." });
+     *   return { result: "done" };
+     * });
+     * ```
+     */
+    forEach<WRequest, WResponse, WProgress = never>(fn: (request: WRequest, ctx: ForEachContext<WProgress>) => Operation<WResponse>): Operation<TReturn>;
 }
 /**
  * Use on the main thread to create and exeecute a well behaved web worker.

package/dist/worker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../worker.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,SAAS,EAKf,MAAM,WAAW,CAAC;AAKnB;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CACnD,SAAQ,SAAS,CAAC,OAAO,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EACpD,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,CAAC,EAAE,aAAa,GAAG;IAAE,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,GACzC,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAkElD"}
+{"version":3,"file":"worker.d.ts","sourceRoot":"","sources":["../worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,SAAS,EAQf,MAAM,WAAW,CAAC;AAInB,OAAO,EACL,KAAK,cAAc,EAGpB,MAAM,YAAY,CAAC;AAGpB;;;;;;GAMG;AACH,MAAM,WAAW,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CACnD,SAAQ,SAAS,CAAC,OAAO,CAAC;IAC1B;;OAEG;IACH,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IACpC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,OAAO,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,GAAG,KAAK,EAC5C,EAAE,EAAE,CACF,OAAO,EAAE,QAAQ,EACjB,GAAG,EAAE,cAAc,CAAC,SAAS,CAAC,KAC3B,SAAS,CAAC,SAAS,CAAC,GACxB,SAAS,CAAC,OAAO,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EACpD,GAAG,EAAE,MAAM,GAAG,GAAG,EACjB,OAAO,CAAC,EAAE,aAAa,GAAG;IAAE,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,GACzC,SAAS,CAAC,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAgNlD"}

package/dist/worker.js

@@ -1,7 +1,7 @@
-import assert from "node:assert";
-import { Err, Ok, on, once, resource, spawn, withResolvers, } from "effection";
+import { Err, Ok, createChannel, on, once, resource, spawn, withResolvers, } from "effection";
 import Worker from "web-worker";
-import { useMessageChannel } from "./message-channel.js";
+import { useChannelRequest, useChannelResponse } from "./channel.js";
+import { errorFromSerialized, } from "./types.js";
 /**
  * Use on the main thread to create and exeecute a well behaved web worker.
  *
@@ -53,22 +53,75 @@ import { useMessageChannel } from "./message-channel.js";
 export function useWorker(url, options) {
     return resource(function* (provide) {
         let outcome = withResolvers();
+        let outcomeSettled = false;
+        const resolveOutcome = (value) => {
+            if (outcomeSettled) {
+                return;
+            }
+            outcomeSettled = true;
+            outcome.resolve(value);
+        };
+        const rejectOutcome = (error) => {
+            if (outcomeSettled) {
+                return;
+            }
+            outcomeSettled = true;
+            outcome.reject(error);
+        };
         let worker = new Worker(url, options);
         let subscription = yield* on(worker, "message");
-        let onclose = (event) => {
-            if (event.data.type === "close") {
-                let { result } = event.data;
-                if (result.ok) {
-                    outcome.resolve(result.value);
+        // Channel for worker-initiated requests (buffered via eager subscription)
+        const requests = createChannel();
+        // Subscribe immediately so messages buffer before forEach is called
+        const requestSubscription = yield* requests;
+        // Flags for forEach state
+        let forEachInProgress = false;
+        let forEachCompleted = false;
+        let opened = false;
+        // Signal for when worker is ready (received "open" message)
+        const ready = withResolvers();
+        // Spawned message loop - handles incoming messages using each pattern
+        yield* spawn(function* () {
+            while (true) {
+                const next = yield* subscription.next();
+                if (next.done) {
+                    break;
+                }
+                const msg = next.value.data;
+                if (!opened && msg.type !== "open") {
+                    const error = new Error(`expected first message to arrive from worker to be of type "open", but was: ${msg.type}`);
+                    ready.reject(error);
+                    throw error;
+                }
+                if (msg.type === "open") {
+                    opened = true;
+                    ready.resolve();
+                }
+                else if (msg.type === "close") {
+                    const { result } = msg;
+                    if (result.ok) {
+                        resolveOutcome(result.value);
+                    }
+                    else {
+                        const serializedError = result.error;
+                        rejectOutcome(errorFromSerialized("Worker failed", serializedError));
+                    }
+                    // Close channel so forEach terminates naturally
+                    yield* requests.close(undefined);
                 }
-                else {
-                    outcome.reject(result.error);
+                else if (msg.type === "request") {
+                    yield* requests.send({ value: msg.value, response: msg.response });
                 }
             }
-        };
-        worker.addEventListener("message", onclose);
-        let first = yield* subscription.next();
-        assert(first.value.data.type === "open", `expected first message to arrive from worker to be of type "open", but was: ${first.value.data.type}`);
+            if (!opened) {
+                const error = new Error("worker terminated before sending open message");
+                ready.reject(error);
+                throw error;
+            }
+        });
+        // Wait for "open" message before proceeding
+        yield* ready.operation;
+        // Handle worker errors
         yield* spawn(function* () {
             let event = yield* once(worker, "error");
             event.preventDefault();
@@ -81,27 +134,90 @@ export function useWorker(url, options) {
             });
             yield* provide({
                 *send(value) {
-                    let channel = yield* useMessageChannel();
+                    const response = yield* useChannelResponse();
                     worker.postMessage({
                         type: "send",
                         value,
-                        response: channel.port2,
-                    }, [channel.port2]);
-                    channel.port1.start();
-                    let event = yield* once(channel.port1, "message");
-                    let result = event.data;
+                        response: response.port,
+                    }, [response.port]);
+                    const result = yield* response;
                     if (result.ok) {
                         return result.value;
                     }
-                    throw result.error;
+                    throw errorFromSerialized("Worker handler failed", result.error);
+                },
+                *forEach(fn) {
+                    // Prevent calling forEach more than once
+                    if (forEachCompleted) {
+                        throw new Error("forEach has already completed");
+                    }
+                    // Prevent concurrent forEach
+                    if (forEachInProgress) {
+                        throw new Error("forEach is already in progress");
+                    }
+                    forEachInProgress = true;
+                    try {
+                        // Iterate until channel closes (when worker sends "close")
+                        let next = yield* requestSubscription.next();
+                        while (!next.done) {
+                            const request = next.value;
+                            // Track handler errors - we forward to worker but also re-throw to host
+                            let handlerError;
+                            // Create a task for this request and wait for it to complete
+                            const task = yield* spawn(function* () {
+                                const channelRequest = yield* useChannelRequest(request.response);
+                                try {
+                                    // Create context with progress method
+                                    const ctx = {
+                                        progress: (data) => channelRequest.progress(data),
+                                    };
+                                    const result = yield* fn(request.value, ctx);
+                                    yield* channelRequest.resolve(result);
+                                }
+                                catch (error) {
+                                    // Forward error to worker so it knows the request failed
+                                    yield* channelRequest.reject(error);
+                                    // Store error to re-throw after forwarding (don't swallow host errors)
+                                    handlerError = error;
+                                }
+                            });
+                            // Wait for the handler to complete
+                            yield* task;
+                            // If the handler failed, stop processing and re-throw
+                            if (handlerError) {
+                                throw handlerError;
+                            }
+                            next = yield* requestSubscription.next();
+                        }
+                        return yield* outcome.operation;
+                    }
+                    finally {
+                        forEachInProgress = false;
+                        forEachCompleted = true;
+                    }
                 },
                 [Symbol.iterator]: outcome.operation[Symbol.iterator],
             });
         }
         finally {
             worker.postMessage({ type: "close" });
+            if (!outcomeSettled) {
+                while (!outcomeSettled) {
+                    const event = yield* once(worker, "message");
+                    const msg = event.data;
+                    if (msg.type === "close") {
+                        const { result } = msg;
+                        if (result.ok) {
+                            resolveOutcome(result.value);
+                        }
+                        else {
+                            const serializedError = result.error;
+                            rejectOutcome(errorFromSerialized("Worker failed", serializedError));
+                        }
+                    }
+                }
+            }
             yield* settled(outcome.operation);
-            worker.removeEventListener("message", onclose);
         }
     });
 }

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "@effectionx/worker",
   "description": "Web Worker integration with two-way messaging and graceful shutdown",
-  "version": "0.4.2",
+  "version": "0.5.1",
   "type": "module",
   "main": "./dist/mod.js",
   "types": "./dist/mod.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/mod.d.ts",
       "development": "./mod.ts",
+      "import": "./dist/mod.js",
       "default": "./dist/mod.js"
     }
   },
@@ -29,10 +31,12 @@
   "sideEffects": false,
   "dependencies": {
     "web-worker": "^1",
-    "@effectionx/signals": "0.5.1"
+    "@effectionx/signals": "0.5.2",
+    "@effectionx/timebox": "0.4.2"
   },
   "devDependencies": {
-    "@effectionx/bdd": "0.4.2",
-    "@effectionx/converge": "0.1.2"
+    "effection": "^4",
+    "@effectionx/bdd": "0.4.3",
+    "@effectionx/converge": "0.1.3"
   }
 }