@effectionx/worker 0.4.1 → 0.5.0

package/test-assets/bidirectional-worker.ts

@@ -0,0 +1,19 @@
+import { spawn } from "effection";
+import { workerMain } from "../worker-main.ts";
+
+await workerMain<string, string, string, void, string, string>(function* ({
+  messages,
+  send,
+}) {
+  // Spawn messages handler in background (it runs until worker closes)
+  yield* spawn(function* () {
+    yield* messages.forEach(function* (msg) {
+      return `worker-response: ${msg}`;
+    });
+  });
+
+  // Send request to host and get response
+  const fromHost = yield* send("from-worker");
+
+  return `done: ${fromHost}`;
+});

package/test-assets/concurrent-requests-worker.ts

@@ -0,0 +1,9 @@
+import { all } from "effection";
+import { workerMain } from "../worker-main.ts";
+
+await workerMain<never, never, number[], void, number, number>(function* ({
+  send,
+}) {
+  const results = yield* all([send(3), send(2), send(1)]);
+  return results;
+});

package/test-assets/error-cause-worker.ts

@@ -0,0 +1,19 @@
+import { workerMain } from "../worker-main.ts";
+
+await workerMain<never, never, string, void, string, string>(function* ({
+  send,
+}) {
+  try {
+    yield* send("trigger-error");
+    return "no error";
+  } catch (e) {
+    const error = e as Error & { cause?: unknown };
+    const cause = error.cause as
+      | { name: string; message: string; stack?: string }
+      | undefined;
+    if (cause?.name && cause.message) {
+      return `caught error with cause: ${cause.name} - ${cause.message}`;
+    }
+    return `caught error without proper cause: ${error.message}`;
+  }
+});

package/test-assets/error-handling-worker.ts

@@ -0,0 +1,12 @@
+import { workerMain } from "../worker-main.ts";
+
+await workerMain<never, never, string, void, string, string>(function* ({
+  send,
+}) {
+  try {
+    yield* send("fail");
+    return "no error";
+  } catch (e) {
+    return `caught: ${(e as Error).message}`;
+  }
+});

package/test-assets/error-throw-worker.ts

@@ -0,0 +1,9 @@
+import { workerMain } from "../worker-main.ts";
+
+await workerMain<string, string, void, void, never, never>(function* ({
+  messages,
+}) {
+  yield* messages.forEach(function* (_msg) {
+    throw new RangeError("worker range error");
+  });
+});

package/test-assets/no-requests-worker.ts

@@ -0,0 +1,5 @@
+import { workerMain } from "../worker-main.ts";
+
+await workerMain<never, never, string, void, string, string>(function* () {
+  return "done without requests";
+});

package/test-assets/send-inside-foreach-worker.ts

@@ -0,0 +1,18 @@
+import { workerMain } from "../worker-main.ts";
+
+// Worker that calls send() from inside messages.forEach handler
+await workerMain<string, string, string, void, string, string>(function* ({
+  messages,
+  send,
+}) {
+  let lastResponse = "";
+
+  yield* messages.forEach(function* (msg) {
+    // Call send() to host while handling a message from host
+    const hostResponse = yield* send(`worker-request-for: ${msg}`);
+    lastResponse = hostResponse;
+    return `processed: ${msg} with ${hostResponse}`;
+  });
+
+  return `final: ${lastResponse}`;
+});

package/test-assets/sequential-requests-worker.ts

@@ -0,0 +1,10 @@
+import { workerMain } from "../worker-main.ts";
+
+await workerMain<never, never, number, void, string, number>(function* ({
+  send,
+}) {
+  const a = yield* send("first");
+  const b = yield* send("second");
+  const c = yield* send("third");
+  return c;
+});

package/test-assets/single-request-worker.ts

@@ -0,0 +1,8 @@
+import { workerMain } from "../worker-main.ts";
+
+await workerMain<never, never, string, void, string, string>(function* ({
+  send,
+}) {
+  const response = yield* send("hello");
+  return `received: ${response}`;
+});

package/test-assets/slow-request-worker.ts

@@ -0,0 +1,8 @@
+import { workerMain } from "../worker-main.ts";
+
+await workerMain<never, never, string, void, string, string>(function* ({
+  send,
+}) {
+  const response = yield* send("hello");
+  return `received: ${response}`;
+});

package/tsconfig.json

@@ -15,6 +15,9 @@
     },
     {
       "path": "../signals"
+    },
+    {
+      "path": "../timebox"
     }
   ]
 }

package/types.ts

@@ -1,5 +1,8 @@
-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";
@@ -14,15 +17,166 @@ 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 function serializeError(error: Error): SerializedError {
+  const serialized: SerializedError = {
+    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: string,
+  serialized: SerializedError,
+): Error {
+  return new Error(`${context}: ${serialized.message}`, {
+    cause: serialized,
+  });
+}
+
+/**
+ * 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>;
 }
 
 /**

package/worker-main.ts

@@ -6,6 +6,7 @@ import {
   Ok,
   type Operation,
   type Task,
+  createChannel,
   createSignal,
   each,
   main,
@@ -14,7 +15,14 @@ import {
   spawn,
 } from "effection";
 
-import type { WorkerControl, WorkerMainOptions } from "./types.ts";
+import type { Subscription } from "effection";
+import { useChannelRequest, useChannelResponse } from "./channel.ts";
+import type {
+  SerializedResult,
+  WorkerControl,
+  WorkerMainOptions,
+} from "./types.ts";
+import { errorFromSerialized } from "./types.ts";
 
 // Get the appropriate worker port for the current environment as a resource
 function useWorkerPort(): Operation<MessagePort> {
@@ -74,19 +82,42 @@ function useWorkerPort(): Operation<MessagePort> {
  * );
  * ```
  *
+ * @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<TSend, TRecv, TReturn, TData>(
-  body: (options: WorkerMainOptions<TSend, TRecv, TData>) => Operation<TReturn>,
+export async function workerMain<
+  TSend,
+  TRecv,
+  TReturn,
+  TData,
+  WRequest = never,
+  WResponse = never,
+>(
+  body: (
+    options: WorkerMainOptions<TSend, TRecv, TData, WRequest, WResponse>,
+  ) => Operation<TReturn>,
 ): Promise<void> {
   await main(function* () {
     const port = yield* useWorkerPort();
-    let sent = createSignal<{ value: TSend; response: MessagePort }>();
+    let sent = createChannel<{ value: TSend; response: MessagePort }>();
     let worker = yield* createWorkerStatesSignal();
 
     yield* spawn(function* () {
@@ -98,23 +129,103 @@ export async function workerMain<TSend, TRecv, TReturn, TData>(
             worker.start(
               yield* spawn(function* () {
                 try {
+                  // Helper to unwrap SerializedResult
+                  function unwrapResult<T>(result: SerializedResult<T>): T {
+                    if (result.ok) {
+                      return result.value;
+                    }
+                    throw errorFromSerialized(
+                      "Host handler failed",
+                      result.error,
+                    );
+                  }
+
+                  // Create send function for worker-initiated requests
+                  function send(requestValue: WRequest): Operation<WResponse> {
+                    return {
+                      *[Symbol.iterator]() {
+                        const response = yield* useChannelResponse<WResponse>();
+                        port.postMessage(
+                          {
+                            type: "request",
+                            value: requestValue,
+                            response: response.port,
+                          },
+                          // biome-ignore lint/suspicious/noExplicitAny: cross-env MessagePort compatibility
+                          [response.port] as any,
+                        );
+                        const result = yield* response;
+                        return unwrapResult(result);
+                      },
+                    };
+                  }
+
+                  // Add stream method for progress streaming
+                  send.stream = <WProgress>(
+                    requestValue: WRequest,
+                  ): Operation<Subscription<WProgress, WResponse>> => ({
+                    *[Symbol.iterator]() {
+                      const response = yield* useChannelResponse<
+                        WResponse,
+                        WProgress
+                      >();
+                      port.postMessage(
+                        {
+                          type: "request",
+                          value: requestValue,
+                          response: response.port,
+                        },
+                        // biome-ignore lint/suspicious/noExplicitAny: cross-env MessagePort compatibility
+                        [response.port] as any,
+                      );
+
+                      // Get the progress subscription
+                      const progressSubscription = yield* response.progress;
+
+                      // Wrap it to unwrap the SerializedResult at the end
+                      const wrappedSubscription: Subscription<
+                        WProgress,
+                        WResponse
+                      > = {
+                        *next() {
+                          const result = yield* progressSubscription.next();
+                          if (result.done) {
+                            // Unwrap the SerializedResult
+                            return {
+                              done: true as const,
+                              value: unwrapResult(result.value),
+                            };
+                          }
+                          return result;
+                        },
+                      };
+
+                      return wrappedSubscription;
+                    },
+                  });
+
                   let value = yield* body({
                     data: control.data,
                     messages: {
                       *forEach(fn: (value: TSend) => Operation<TRecv>) {
                         for (let { value, response } of yield* each(sent)) {
                           yield* spawn(function* () {
+                            const { resolve, reject } =
+                              yield* useChannelRequest<TRecv>(
+                                response as unknown as globalThis.MessagePort,
+                              );
                             try {
                               let result = yield* fn(value);
-                              response.postMessage(Ok(result));
+                              yield* resolve(result);
                             } catch (error) {
-                              response.postMessage(Err(error as Error));
+                              yield* reject(error as Error);
                             }
                           });
                           yield* each.next();
                         }
                       },
                     },
+                    send,
                   });
 
                   worker.complete(value);
@@ -132,7 +243,7 @@ export async function workerMain<TSend, TRecv, TReturn, TData>(
               response instanceof MessagePort,
               "Expect response to be an instance of MessagePort",
             );
-            sent.send({ value, response });
+            yield* sent.send({ value, response });
             break;
           }
           case "close": {