@effectionx/worker 0.4.2 → 0.5.0

package/worker.test.ts

@@ -3,7 +3,15 @@ import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { beforeEach, describe, it } from "@effectionx/bdd";
 import { when } from "@effectionx/converge";
-import { scoped, spawn, suspend, until } from "effection";
+import {
+  all,
+  scoped,
+  sleep,
+  spawn,
+  suspend,
+  until,
+  withResolvers,
+} from "effection";
 import { expect } from "expect";
 
 import type { ShutdownWorkerParams } from "./test-assets/shutdown-worker.ts";
@@ -31,7 +39,7 @@ describe("worker", () => {
       yield* worker.send();
     } catch (e) {
       expect(e).toBeInstanceOf(Error);
-      expect(e).toMatchObject({ message: "boom!" });
+      expect((e as Error).message).toContain("boom!");
     }
   });
   it("produces its return value", function* () {
@@ -55,7 +63,7 @@ describe("worker", () => {
       yield* worker;
     } catch (e) {
       expect(e).toBeInstanceOf(Error);
-      expect(e).toMatchObject({ message: "boom!" });
+      expect((e as Error).message).toContain("boom!");
     }
   });
   describe("shutdown", () => {
@@ -130,7 +138,7 @@ describe("worker", () => {
       yield* worker;
     } catch (e) {
       expect(e).toBeInstanceOf(Error);
-      expect(e).toMatchObject({ message: "worker terminated" });
+      expect((e as Error).message).toContain("worker terminated");
     }
   });
 
@@ -176,4 +184,294 @@ describe("worker", () => {
   it.skip("crashes if there is a message error from the worker thread", function* () {
     // don't know how to trigger
   });
+
+  describe("worker-initiated requests", () => {
+    it("handles a single request from worker", function* () {
+      const worker = yield* useWorker<never, never, string, void>(
+        import.meta.resolve("./test-assets/single-request-worker.ts"),
+        { type: "module" },
+      );
+
+      const result = yield* worker.forEach<string, string>(function* (request) {
+        return `echo: ${request}`;
+      });
+
+      expect(result).toEqual("received: echo: hello");
+    });
+
+    it("handles multiple sequential requests from worker", function* () {
+      const worker = yield* useWorker<never, never, number, void>(
+        import.meta.resolve("./test-assets/sequential-requests-worker.ts"),
+        { type: "module" },
+      );
+
+      let counter = 0;
+      const result = yield* worker.forEach<string, number>(
+        function* (_request) {
+          counter += 1;
+          return counter;
+        },
+      );
+
+      expect(result).toEqual(3);
+    });
+
+    it("propagates errors from host handler to worker and crashes host", function* () {
+      const worker = yield* useWorker<never, never, string, void>(
+        import.meta.resolve("./test-assets/error-handling-worker.ts"),
+        { type: "module" },
+      );
+
+      // Host should crash after forwarding error to worker
+      let hostError: Error | undefined;
+      try {
+        yield* worker.forEach<string, string>(function* (request) {
+          if (request === "fail") {
+            throw new Error("host error");
+          }
+          return "ok";
+        });
+      } catch (e) {
+        hostError = e as Error;
+      }
+
+      // Verify host crashed with the original error
+      expect(hostError).toBeDefined();
+      expect(hostError?.message).toEqual("host error");
+    });
+
+    it("handles concurrent requests from worker", function* () {
+      const worker = yield* useWorker<never, never, number[], void>(
+        import.meta.resolve("./test-assets/concurrent-requests-worker.ts"),
+        { type: "module" },
+      );
+
+      const result = yield* worker.forEach<number, number>(function* (request) {
+        yield* sleep(request * 10);
+        return request * 2;
+      });
+
+      expect(result).toEqual([6, 4, 2]);
+    });
+
+    it("supports bidirectional communication", function* () {
+      const worker = yield* useWorker<string, string, string, void>(
+        import.meta.resolve("./test-assets/bidirectional-worker.ts"),
+        { type: "module" },
+      );
+
+      yield* spawn(function* () {
+        yield* worker.forEach<string, string>(function* (request) {
+          return `host-response: ${request}`;
+        });
+      });
+
+      const hostResult = yield* worker.send("from-host");
+      expect(hostResult).toEqual("worker-response: from-host");
+
+      const finalResult = yield* worker;
+      expect(finalResult).toEqual("done: host-response: from-worker");
+    });
+
+    it("existing workers without send still work", function* () {
+      const worker = yield* useWorker(
+        import.meta.resolve("./test-assets/echo-worker.ts"),
+        { type: "module" },
+      );
+
+      const result = yield* worker.send("hello world");
+      expect(result).toEqual("hello world");
+    });
+
+    it("forEach completes with result when worker sends no requests", function* () {
+      const worker = yield* useWorker<never, never, string, void>(
+        import.meta.resolve("./test-assets/no-requests-worker.ts"),
+        { type: "module" },
+      );
+
+      let handlerCalled = false;
+      const result = yield* worker.forEach<string, string>(
+        function* (_request) {
+          handlerCalled = true;
+          return "response";
+        },
+      );
+
+      expect(result).toEqual("done without requests");
+      expect(handlerCalled).toBe(false);
+    });
+
+    it("yield worker after forEach returns same result", function* () {
+      const worker = yield* useWorker<never, never, string, void>(
+        import.meta.resolve("./test-assets/single-request-worker.ts"),
+        { type: "module" },
+      );
+
+      const result1 = yield* worker.forEach<string, string>(
+        function* (request) {
+          return `echo: ${request}`;
+        },
+      );
+
+      const result2 = yield* worker;
+
+      expect(result1).toEqual("received: echo: hello");
+      expect(result2).toEqual("received: echo: hello");
+    });
+
+    it("yield forEach after worker returns cached result", function* () {
+      const worker = yield* useWorker<never, never, string, void>(
+        import.meta.resolve("./test-assets/no-requests-worker.ts"),
+        { type: "module" },
+      );
+
+      const result1 = yield* worker;
+
+      let handlerCalled = false;
+      const result2 = yield* worker.forEach<string, string>(
+        function* (_request) {
+          handlerCalled = true;
+          return "response";
+        },
+      );
+
+      expect(result1).toEqual("done without requests");
+      expect(result2).toEqual("done without requests");
+      expect(handlerCalled).toBe(false);
+    });
+
+    it("yield worker multiple times returns same result", function* () {
+      const worker = yield* useWorker<never, never, string, void>(
+        import.meta.resolve("./test-assets/no-requests-worker.ts"),
+        { type: "module" },
+      );
+
+      const result1 = yield* worker;
+      const result2 = yield* worker;
+      const result3 = yield* worker;
+
+      expect(result1).toEqual("done without requests");
+      expect(result2).toEqual("done without requests");
+      expect(result3).toEqual("done without requests");
+    });
+
+    it("queues requests sent before forEach is called", function* () {
+      const worker = yield* useWorker<never, never, string, void>(
+        import.meta.resolve("./test-assets/single-request-worker.ts"),
+        { type: "module" },
+      );
+
+      // Yield control to allow worker to send request before forEach is set up
+      // The channel implementation buffers requests, so sleep(0) is sufficient
+      yield* sleep(0);
+
+      const result = yield* worker.forEach<string, string>(function* (request) {
+        return `echo: ${request}`;
+      });
+
+      expect(result).toEqual("received: echo: hello");
+    });
+
+    it("throws error when forEach is called concurrently", function* () {
+      expect.assertions(1);
+      const worker = yield* useWorker<never, never, string, void>(
+        import.meta.resolve("./test-assets/slow-request-worker.ts"),
+        { type: "module" },
+      );
+
+      const forEachStarted = withResolvers<void>();
+      const allowHandlerToComplete = withResolvers<void>();
+
+      // Start first forEach in background
+      yield* spawn(function* () {
+        yield* worker.forEach<string, string>(function* (_request) {
+          forEachStarted.resolve();
+          // Block until test signals completion (deterministic latch instead of sleep)
+          yield* allowHandlerToComplete.operation;
+          return "slow response";
+        });
+      });
+
+      // Wait for first forEach to start handling a request
+      yield* forEachStarted.operation;
+
+      // Second forEach should throw
+      try {
+        yield* worker.forEach<string, string>(function* (_request) {
+          return "should not be called";
+        });
+      } catch (e) {
+        expect((e as Error).message).toEqual("forEach is already in progress");
+      }
+
+      // Allow first handler to complete so test can clean up
+      allowHandlerToComplete.resolve();
+    });
+
+    it("error cause contains name, message, and stack from host", function* () {
+      const worker = yield* useWorker<never, never, string, void>(
+        import.meta.resolve("./test-assets/error-cause-worker.ts"),
+        { type: "module" },
+      );
+
+      // Host should crash after forwarding error to worker
+      let hostError: Error | undefined;
+      try {
+        yield* worker.forEach<string, string>(function* (_request) {
+          const error = new TypeError("custom type error");
+          throw error;
+        });
+      } catch (e) {
+        hostError = e as Error;
+      }
+
+      // Verify host crashed with the original error
+      expect(hostError).toBeDefined();
+      expect(hostError?.name).toEqual("TypeError");
+      expect(hostError?.message).toEqual("custom type error");
+    });
+
+    it("error cause contains name, message, and stack from worker", function* () {
+      expect.assertions(4);
+      const worker = yield* useWorker<string, string, void, void>(
+        import.meta.resolve("./test-assets/error-throw-worker.ts"),
+        { type: "module" },
+      );
+
+      try {
+        yield* worker.send("trigger-error");
+      } catch (e) {
+        const error = e as Error & { cause?: unknown };
+        expect(error.message).toContain("Worker handler failed");
+        expect(error.cause).toBeDefined();
+        const cause = error.cause as {
+          name: string;
+          message: string;
+          stack?: string;
+        };
+        expect(cause.name).toEqual("RangeError");
+        expect(cause.message).toEqual("worker range error");
+      }
+    });
+
+    it("worker can call send inside messages.forEach handler", function* () {
+      const worker = yield* useWorker<string, string, string, void>(
+        import.meta.resolve("./test-assets/send-inside-foreach-worker.ts"),
+        { type: "module" },
+      );
+
+      // Handle worker-initiated requests
+      yield* spawn(function* () {
+        yield* worker.forEach<string, string>(function* (request) {
+          return `host-handled: ${request}`;
+        });
+      });
+
+      // Send message to worker, which triggers it to call send() back to host
+      const result = yield* worker.send("trigger");
+      expect(result).toEqual(
+        "processed: trigger with host-handled: worker-request-for: trigger",
+      );
+    });
+  });
 });

package/worker.ts

@@ -1,29 +1,71 @@
-import assert from "node:assert";
 import {
   Err,
   Ok,
+  type Operation,
+  type Result,
+  createChannel,
   on,
   once,
-  type Operation,
   resource,
-  type Result,
   spawn,
   withResolvers,
 } from "effection";
 import Worker from "web-worker";
 
-import { useMessageChannel } from "./message-channel.ts";
+import { useChannelRequest, useChannelResponse } from "./channel.ts";
+import {
+  type ForEachContext,
+  type SerializedError,
+  errorFromSerialized,
+} from "./types.ts";
+// Note: Ok/Err still used for outcome handling; serializeError no longer needed here
 
 /**
- * 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>;
 }
 
 /**
@@ -80,30 +122,93 @@ export function useWorker<TSend, TRecv, TReturn, TData>(
 ): Operation<WorkerResource<TSend, TRecv, TReturn>> {
   return resource(function* (provide) {
     let outcome = withResolvers<TReturn>();
+    let outcomeSettled = false;
+
+    const resolveOutcome = (value: TReturn) => {
+      if (outcomeSettled) {
+        return;
+      }
+      outcomeSettled = true;
+      outcome.resolve(value);
+    };
+
+    const rejectOutcome = (error: Error) => {
+      if (outcomeSettled) {
+        return;
+      }
+      outcomeSettled = true;
+      outcome.reject(error);
+    };
 
     let worker = new Worker(url, options);
     let subscription = yield* on(worker, "message");
 
-    let onclose = (event: MessageEvent) => {
-      if (event.data.type === "close") {
-        let { result } = event.data as { result: Result<TReturn> };
-        if (result.ok) {
-          outcome.resolve(result.value);
-        } else {
-          outcome.reject(result.error);
+    // Channel for worker-initiated requests (buffered via eager subscription)
+    const requests = createChannel<
+      { value: unknown; response: MessagePort },
+      void
+    >();
+    // 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<void>();
+
+    // 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;
         }
-      }
-    };
 
-    worker.addEventListener("message", onclose);
+        if (msg.type === "open") {
+          opened = true;
+          ready.resolve();
+        } else if (msg.type === "close") {
+          const { result } = msg as { result: Result<TReturn> };
+          if (result.ok) {
+            resolveOutcome(result.value);
+          } else {
+            const serializedError = result.error as unknown as SerializedError;
+            rejectOutcome(
+              errorFromSerialized("Worker failed", serializedError),
+            );
+          }
+          // Close channel so forEach terminates naturally
+          yield* requests.close(undefined);
+        } else if (msg.type === "request") {
+          yield* requests.send({ value: msg.value, response: msg.response });
+        }
+      }
 
-    let first = yield* subscription.next();
+      if (!opened) {
+        const error = new Error(
+          "worker terminated before sending open message",
+        );
+        ready.reject(error);
+        throw error;
+      }
+    });
 
-    assert(
-      first.value.data.type === "open",
-      `expected first message to arrive from worker to be of type "open", but was: ${first.value.data.type}`,
-    );
+    // Wait for "open" message before proceeding
+    yield* ready.operation;
 
+    // Handle worker errors
     yield* spawn(function* () {
       let event = yield* once(worker, "error");
       event.preventDefault();
@@ -118,29 +223,108 @@ export function useWorker<TSend, TRecv, TReturn, TData>(
 
       yield* provide({
         *send(value) {
-          let channel = yield* useMessageChannel();
+          const response = yield* useChannelResponse<TRecv>();
           worker.postMessage(
             {
               type: "send",
               value,
-              response: channel.port2,
+              response: response.port,
             },
-            [channel.port2],
+            [response.port],
           );
-          channel.port1.start();
-          let event = yield* once(channel.port1, "message");
-          let result = (event as MessageEvent).data;
+          const result = yield* response;
           if (result.ok) {
             return result.value;
           }
-          throw result.error;
+          throw errorFromSerialized("Worker handler failed", result.error);
         },
+
+        *forEach<WRequest, WResponse, WProgress = never>(
+          fn: (
+            request: WRequest,
+            ctx: ForEachContext<WProgress>,
+          ) => Operation<WResponse>,
+        ): Operation<TReturn> {
+          // 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: Error | undefined;
+
+              // Create a task for this request and wait for it to complete
+              const task = yield* spawn(function* () {
+                const channelRequest = yield* useChannelRequest<
+                  WResponse,
+                  WProgress
+                >(request.response);
+                try {
+                  // Create context with progress method
+                  const ctx: ForEachContext<WProgress> = {
+                    progress: (data: WProgress) =>
+                      channelRequest.progress(data),
+                  };
+                  const result = yield* fn(request.value as WRequest, ctx);
+                  yield* channelRequest.resolve(result);
+                } catch (error) {
+                  // Forward error to worker so it knows the request failed
+                  yield* channelRequest.reject(error as Error);
+                  // Store error to re-throw after forwarding (don't swallow host errors)
+                  handlerError = error as 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 as { result: Result<TReturn> };
+            if (result.ok) {
+              resolveOutcome(result.value);
+            } else {
+              const serializedError =
+                result.error as unknown as SerializedError;
+              rejectOutcome(
+                errorFromSerialized("Worker failed", serializedError),
+              );
+            }
+          }
+        }
+      }
       yield* settled(outcome.operation);
-      worker.removeEventListener("message", onclose);
     }
   });
 }

package/dist/message-channel.d.ts

@@ -1,3 +0,0 @@
-import { type Operation } from "effection";
-export declare function useMessageChannel(): Operation<MessageChannel>;
-//# sourceMappingURL=message-channel.d.ts.map

package/dist/message-channel.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"message-channel.d.ts","sourceRoot":"","sources":["../message-channel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,SAAS,EAAY,MAAM,WAAW,CAAC;AAErD,wBAAgB,iBAAiB,IAAI,SAAS,CAAC,cAAc,CAAC,CAU7D"}

package/dist/message-channel.js

@@ -1,13 +0,0 @@
-import { resource } from "effection";
-export function useMessageChannel() {
-    return resource(function* (provide) {
-        let channel = new MessageChannel();
-        try {
-            yield* provide(channel);
-        }
-        finally {
-            channel.port1.close();
-            channel.port2.close();
-        }
-    });
-}

package/message-channel.ts

@@ -1,13 +0,0 @@
-import { type Operation, resource } from "effection";
-
-export function useMessageChannel(): Operation<MessageChannel> {
-  return resource(function* (provide) {
-    let channel = new MessageChannel();
-    try {
-      yield* provide(channel);
-    } finally {
-      channel.port1.close();
-      channel.port2.close();
-    }
-  });
-}