@effectionx/worker 0.3.1 → 0.4.0

package/worker-main.ts

@@ -0,0 +1,248 @@
+import assert from "node:assert";
+import { MessagePort, parentPort } from "node:worker_threads";
+import type { ValueSignal } from "@effectionx/signals";
+import {
+  Err,
+  Ok,
+  type Operation,
+  type Task,
+  createSignal,
+  each,
+  main,
+  on,
+  resource,
+  spawn,
+} from "effection";
+
+import type { WorkerControl, WorkerMainOptions } from "./types.ts";
+
+// Get the appropriate worker port for the current environment as a resource
+function useWorkerPort(): Operation<MessagePort> {
+  return resource(function* (provide) {
+    const port = parentPort
+      ? parentPort // Node.js worker_threads
+      : (self as unknown as MessagePort); // Browser/Deno Web Worker
+
+    try {
+      yield* provide(port);
+    } finally {
+      port.close();
+    }
+  });
+}
+
+/**
+ * Entrypoint used in the worker that estaliblishes communication
+ * with the main thread. It can be used to return a value,
+ * respond to messages or both.
+ *
+ * @example Returning a value
+ * ```ts
+ * import { workerMain } from "../worker.ts";
+ *
+ * await workerMain(function* ({ data }) {
+ *  return data;
+ * });
+ * ```
+ *
+ * @example Responding to messages
+ * ```ts
+ * import { workerMain } from "../worker.ts";
+ *
+ * await workerMain(function* ({ messages }) {
+ *  yield* messages.forEach(function* (message) {
+ *    return message;
+ *  });
+ * });
+ * ```
+ *
+ * @example Responding to messages and return a value
+ * ```ts
+ * import { workerMain } from "../worker.ts";
+ *
+ * await workerMain<number, number, number, number>(
+ *   function* ({ messages, data: initial }) {
+ *     let counter = initial;
+ *
+ *     yield* messages.forEach(function* (message) {
+ *       counter += message;
+ *       return counter; // returns a value after each message
+ *     });
+ *
+ *     return counter; // returns the final value
+ *   },
+ * );
+ * ```
+ *
+ * @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
+ * @returns {Promise<void>}
+ */
+export async function workerMain<TSend, TRecv, TReturn, TData>(
+  body: (options: WorkerMainOptions<TSend, TRecv, TData>) => Operation<TReturn>,
+): Promise<void> {
+  await main(function* () {
+    const port = yield* useWorkerPort();
+    let sent = createSignal<{ value: TSend; response: MessagePort }>();
+    let worker = yield* createWorkerStatesSignal();
+
+    yield* spawn(function* () {
+      for (const message of yield* each(on(port, "message"))) {
+        const control: WorkerControl<TSend, TData> = (message as MessageEvent)
+          .data;
+        switch (control.type) {
+          case "init": {
+            worker.start(
+              yield* spawn(function* () {
+                try {
+                  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* () {
+                            try {
+                              let result = yield* fn(value);
+                              response.postMessage(Ok(result));
+                            } catch (error) {
+                              response.postMessage(Err(error as Error));
+                            }
+                          });
+                          yield* each.next();
+                        }
+                      },
+                    },
+                  });
+
+                  worker.complete(value);
+                } catch (error) {
+                  worker.crash(error as Error);
+                }
+              }),
+            );
+            break;
+          }
+          case "send": {
+            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 });
+            break;
+          }
+          case "close": {
+            const current = worker.valueOf();
+            if (current.type === "running") {
+              yield* current.task.halt();
+              worker.interrupt();
+            }
+          }
+        }
+
+        yield* each.next();
+      }
+    });
+
+    for (const state of yield* each(worker)) {
+      if (state.type === "new") {
+        port.postMessage({ type: "open" });
+      } else if (state.type === "interrupted" || state.type === "error") {
+        port.postMessage({ type: "close", result: Err(state.error) });
+        break;
+      } else if (state.type === "complete") {
+        port.postMessage({ type: "close", result: Ok(state.value) });
+        break;
+      }
+      yield* each.next();
+    }
+  });
+}
+
+type New = { type: "new" };
+type Running = { type: "running"; task: Task<void> };
+type Complete = { type: "complete"; value: unknown };
+type Errored = { type: "error"; error: Error };
+type Interrupted = { type: "interrupted"; error: Error };
+
+type WorkerState = New | Running | Complete | Errored | Interrupted;
+
+interface WorkerStateSignal extends ValueSignal<WorkerState> {
+  state: WorkerState["type"];
+  start(task: Task<void>): Running | Complete;
+  complete(value: unknown): Complete;
+  crash(error: Error): Errored;
+  interrupt(): Interrupted;
+}
+
+export function createWorkerStatesSignal(): Operation<WorkerStateSignal> {
+  return resource(function* (provide) {
+    let ref: { current: WorkerState } = {
+      current: { type: "new" },
+    };
+    const signal = createSignal<WorkerState>();
+
+    const set: WorkerStateSignal["set"] = (value) => {
+      ref.current = value;
+      signal.send(value);
+      return value;
+    };
+
+    const update: WorkerStateSignal["update"] = (updater) =>
+      set(updater(ref.current));
+
+    const interrupt: WorkerStateSignal["interrupt"] = () => {
+      let next: Interrupted = {
+        type: "interrupted",
+        error: new Error("worker terminated"),
+      };
+      set(next);
+      return next;
+    };
+
+    try {
+      yield* provide({
+        *[Symbol.iterator]() {
+          let subscription = yield* signal;
+          signal.send(ref.current);
+          return subscription;
+        },
+        get state() {
+          return ref.current.type;
+        },
+        set,
+        update,
+        valueOf() {
+          return ref.current;
+        },
+        start(task) {
+          if (ref.current.type === "complete") {
+            return ref.current;
+          }
+          const next: Running = { type: "running", task };
+          set(next);
+          return next;
+        },
+        complete(value) {
+          let next: Complete = { type: "complete", value };
+          set(next);
+          return next;
+        },
+        crash(error) {
+          let next: Errored = { type: "error", error };
+          set(next);
+          return next;
+        },
+        interrupt: interrupt,
+      });
+    } finally {
+      if (ref.current.type === "running") {
+        interrupt();
+      }
+    }
+  });
+}

package/worker.test.ts

@@ -0,0 +1,179 @@
+import { access, mkdir, readFile, rm } from "node:fs/promises";
+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 { expect } from "expect";
+
+import type { ShutdownWorkerParams } from "./test-assets/shutdown-worker.ts";
+import { useWorker } from "./worker.ts";
+
+describe("worker", () => {
+  it("sends and receive messages in synchrony", function* () {
+    expect.assertions(1);
+    let worker = yield* useWorker(
+      import.meta.resolve("./test-assets/echo-worker.ts"),
+      { type: "module" },
+    );
+
+    let result = yield* worker.send("hello world");
+    expect(result).toEqual("hello world");
+  });
+  it("will raise an exception if an exception happens on the remote side", function* () {
+    expect.assertions(2);
+    let worker = yield* useWorker<void, unknown, unknown, unknown>(
+      import.meta.resolve("./test-assets/boom-worker.ts"),
+      { type: "module" },
+    );
+
+    try {
+      yield* worker.send();
+    } catch (e) {
+      expect(e).toBeInstanceOf(Error);
+      expect(e).toMatchObject({ message: "boom!" });
+    }
+  });
+  it("produces its return value", function* () {
+    expect.assertions(2);
+    let worker = yield* useWorker(
+      import.meta.resolve("./test-assets/result-worker.ts"),
+      { type: "module", data: "this is the worker result" },
+    );
+
+    expect(yield* worker).toEqual("this is the worker result");
+    expect(yield* worker).toEqual("this is the worker result");
+  });
+  it("raises an exception if the worker raises one", function* () {
+    expect.assertions(2);
+    let worker = yield* useWorker(
+      import.meta.resolve("./test-assets/boom-result-worker.ts"),
+      { type: "module", data: "boom!" },
+    );
+
+    try {
+      yield* worker;
+    } catch (e) {
+      expect(e).toBeInstanceOf(Error);
+      expect(e).toMatchObject({ message: "boom!" });
+    }
+  });
+  describe("shutdown", () => {
+    let startFile: string;
+    let endFile: string;
+    let url: string;
+
+    beforeEach(function* () {
+      let dir = fileURLToPath(import.meta.resolve("./test-tmp"));
+      yield* until(
+        rm(dir, { recursive: true, force: true }).then(() =>
+          mkdir(dir, { recursive: true }),
+        ),
+      );
+      startFile = join(dir, "started.txt");
+      endFile = join(dir, "ended.txt");
+      url = import.meta.resolve("./test-assets/shutdown-worker.ts");
+    });
+
+    it("shuts down gracefully", function* () {
+      let task = yield* spawn(function* () {
+        yield* useWorker(url, {
+          type: "module",
+          data: {
+            startFile,
+            endFile,
+            endText: "goodbye cruel world!",
+          } satisfies ShutdownWorkerParams,
+        });
+        yield* suspend();
+      });
+
+      // Wait for worker to start
+      yield* when(
+        function* () {
+          let exists = yield* until(
+            access(startFile).then(
+              () => true,
+              () => false,
+            ),
+          );
+          if (!exists) throw new Error("start file not found");
+          return true;
+        },
+        { timeout: 10_000 },
+      );
+
+      yield* task.halt();
+
+      // Wait for the end file to be written with expected content
+      let { value: content } = yield* when(
+        function* () {
+          let text = yield* until(readFile(endFile, "utf-8").catch(() => ""));
+          if (text !== "goodbye cruel world!") {
+            throw new Error(`expected "goodbye cruel world!", got "${text}"`);
+          }
+          return text;
+        },
+        { timeout: 500 },
+      );
+
+      expect(content).toEqual("goodbye cruel world!");
+    });
+  });
+
+  it("becomes halted if you try and await its value out of scope", function* () {
+    let url = import.meta.resolve("./test-assets/suspend-worker.ts");
+    let worker = yield* scoped(function* () {
+      return yield* useWorker(url, { type: "module" });
+    });
+    try {
+      yield* worker;
+    } catch (e) {
+      expect(e).toBeInstanceOf(Error);
+      expect(e).toMatchObject({ message: "worker terminated" });
+    }
+  });
+
+  it("supports stateful operations", function* () {
+    expect.assertions(3);
+
+    let url = import.meta.resolve("./test-assets/counter-worker.ts");
+
+    let worker = yield* useWorker(url, { type: "module", data: 2 });
+
+    expect(yield* worker.send(10)).toEqual(12);
+
+    expect(yield* worker.send(-5)).toEqual(7);
+
+    expect(yield* worker.send(35)).toEqual(42);
+  });
+
+  it.skip("crashes if there is an uncaught error in the worker", function* () {
+    let crash = import.meta.resolve("./test-assets/crash-worker.ts");
+    let worker = yield* useWorker(crash, { name: "crash", type: "module" });
+    try {
+      yield* worker;
+    } catch (e) {
+      expect(e).toBeInstanceOf(Error);
+      expect(e).toMatchObject({ message: "boom!" });
+    }
+  });
+
+  it.skip("crashes if the worker module cannot be found", function* () {
+    let crash = import.meta.resolve("./test-assets/non-existent-worker.ts");
+    let worker = yield* useWorker(crash, { name: "crash", type: "module" });
+    try {
+      yield* worker;
+    } catch (e) {
+      expect(e).toBeInstanceOf(Error);
+      expect(e).toMatchObject({ message: "boom!" });
+    }
+  });
+  it.skip("crashes if there is a message error from the main thread", function* () {
+    // don't know how to reproduce this
+  });
+
+  it.skip("crashes if there is a message error from the worker thread", function* () {
+    // don't know how to trigger
+  });
+});

package/worker.ts

@@ -0,0 +1,159 @@
+import assert from "node:assert";
+import {
+  Err,
+  Ok,
+  on,
+  once,
+  type Operation,
+  resource,
+  type Result,
+  spawn,
+  withResolvers,
+} from "effection";
+import Worker from "web-worker";
+
+import { useMessageChannel } from "./message-channel.ts";
+
+/**
+ * Argument received by workerMain function
+ *
+ * @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
+ */
+export interface WorkerResource<TSend, TRecv, TReturn>
+  extends Operation<TReturn> {
+  send(data: TSend): Operation<TRecv>;
+}
+
+/**
+ * Use on the main thread to create and exeecute a well behaved web worker.
+ *
+ * @example Compute a single value
+ * ```ts
+ * import { run } from "effection";
+ * import { useWorker } from "@effectionx/worker"
+ *
+ * await run(function*() {
+ *    const worker = yield* useWorker("script.ts", { type: "module" });
+ *
+ *    try {
+ *      const result = yield* worker;
+ *    } catch (e) {
+ *      console.error(e);
+ *    }
+ * });
+ * ```
+ *
+ * @example Compute multipe values
+ * ```ts
+ * import { run } from "effection";
+ * import { useWorker } from "@effectionx/worker"
+ *
+ * await run(function*() {
+ *    const worker = yield* useWorker("script.ts", { type: "module" });
+ *
+ *    try {
+ *      const result1 = yield* worker.send("Tom");
+ *      const result2 = yield* worker.send("Dick");
+ *      const result2 = yield* worker.send("Harry");
+ *
+ *      // get the last result
+ *      const finalResult = yield* worker;
+ *    } catch (e) {
+ *      console.error(e);
+ *    }
+ * });
+ * ```
+ *
+ * @param url URL or string of script
+ * @param options WorkerOptions
+ * @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
+ * @returns {Operation<WorkerResource<TSend, TRecv>>}
+ */
+export function useWorker<TSend, TRecv, TReturn, TData>(
+  url: string | URL,
+  options?: WorkerOptions & { data?: TData },
+): Operation<WorkerResource<TSend, TRecv, TReturn>> {
+  return resource(function* (provide) {
+    let outcome = withResolvers<TReturn>();
+
+    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);
+        }
+      }
+    };
+
+    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}`,
+    );
+
+    yield* spawn(function* () {
+      let event = yield* once(worker, "error");
+      event.preventDefault();
+      throw event.error;
+    });
+
+    try {
+      worker.postMessage({
+        type: "init",
+        data: options?.data,
+      });
+
+      yield* provide({
+        *send(value) {
+          let channel = yield* useMessageChannel();
+          worker.postMessage(
+            {
+              type: "send",
+              value,
+              response: channel.port2,
+            },
+            [channel.port2],
+          );
+          channel.port1.start();
+          let event = yield* once(channel.port1, "message");
+          let result = (event as MessageEvent).data;
+          if (result.ok) {
+            return result.value;
+          }
+          throw result.error;
+        },
+        [Symbol.iterator]: outcome.operation[Symbol.iterator],
+      });
+    } finally {
+      worker.postMessage({ type: "close" });
+      yield* settled(outcome.operation);
+      worker.removeEventListener("message", onclose);
+    }
+  });
+}
+
+function settled<T>(operation: Operation<T>): Operation<Result<void>> {
+  return {
+    *[Symbol.iterator]() {
+      try {
+        yield* operation;
+        return Ok(void 0);
+      } catch (error) {
+        return Err(error as Error);
+      }
+    },
+  };
+}

package/esm/_dnt.shims.d.ts

@@ -1,2 +0,0 @@
-export declare const dntGlobalThis: Omit<typeof globalThis, never>;
-//# sourceMappingURL=_dnt.shims.d.ts.map

package/esm/_dnt.shims.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"_dnt.shims.d.ts","sourceRoot":"","sources":["../src/_dnt.shims.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,gCAA2C,CAAC"}

package/esm/_dnt.shims.js

@@ -1,57 +0,0 @@
-const dntGlobals = {};
-export const dntGlobalThis = createMergeProxy(globalThis, dntGlobals);
-function createMergeProxy(baseObj, extObj) {
-    return new Proxy(baseObj, {
-        get(_target, prop, _receiver) {
-            if (prop in extObj) {
-                return extObj[prop];
-            }
-            else {
-                return baseObj[prop];
-            }
-        },
-        set(_target, prop, value) {
-            if (prop in extObj) {
-                delete extObj[prop];
-            }
-            baseObj[prop] = value;
-            return true;
-        },
-        deleteProperty(_target, prop) {
-            let success = false;
-            if (prop in extObj) {
-                delete extObj[prop];
-                success = true;
-            }
-            if (prop in baseObj) {
-                delete baseObj[prop];
-                success = true;
-            }
-            return success;
-        },
-        ownKeys(_target) {
-            const baseKeys = Reflect.ownKeys(baseObj);
-            const extKeys = Reflect.ownKeys(extObj);
-            const extKeysSet = new Set(extKeys);
-            return [...baseKeys.filter((k) => !extKeysSet.has(k)), ...extKeys];
-        },
-        defineProperty(_target, prop, desc) {
-            if (prop in extObj) {
-                delete extObj[prop];
-            }
-            Reflect.defineProperty(baseObj, prop, desc);
-            return true;
-        },
-        getOwnPropertyDescriptor(_target, prop) {
-            if (prop in extObj) {
-                return Reflect.getOwnPropertyDescriptor(extObj, prop);
-            }
-            else {
-                return Reflect.getOwnPropertyDescriptor(baseObj, prop);
-            }
-        },
-        has(_target, prop) {
-            return prop in extObj || prop in baseObj;
-        },
-    });
-}

package/esm/deps/jsr.io/@std/assert/1.0.16/almost_equals.d.ts

@@ -1,29 +0,0 @@
-/**
- * Make an assertion that `actual` and `expected` are almost equal numbers
- * through a given tolerance. It can be used to take into account IEEE-754
- * double-precision floating-point representation limitations. If the values
- * are not almost equal then throw.
- *
- * The default tolerance is one hundred thousandth of a percent of the
- * expected value.
- *
- * @example Usage
- * ```ts ignore
- * import { assertAlmostEquals } from "@std/assert";
- *
- * assertAlmostEquals(0.01, 0.02); // Throws
- * assertAlmostEquals(1e-8, 1e-9); // Throws
- * assertAlmostEquals(1.000000001e-8, 1.000000002e-8); // Doesn't throw
- * assertAlmostEquals(0.01, 0.02, 0.1); // Doesn't throw
- * assertAlmostEquals(0.1 + 0.2, 0.3, 1e-16); // Doesn't throw
- * assertAlmostEquals(0.1 + 0.2, 0.3, 1e-17); // Throws
- * ```
- *
- * @param actual The actual value to compare.
- * @param expected The expected value to compare.
- * @param tolerance The tolerance to consider the values almost equal. The
- * default is one hundred thousandth of a percent of the expected value.
- * @param msg The optional message to include in the error.
- */
-export declare function assertAlmostEquals(actual: number, expected: number, tolerance?: number, msg?: string): void;
-//# sourceMappingURL=almost_equals.d.ts.map

package/esm/deps/jsr.io/@std/assert/1.0.16/almost_equals.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"almost_equals.d.ts","sourceRoot":"","sources":["../../../../../../src/deps/jsr.io/@std/assert/1.0.16/almost_equals.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,GAAG,CAAC,EAAE,MAAM,QAmBb"}