@thi.ng/fibers 0.1.0

package/ops.js

@@ -0,0 +1,198 @@
+import { now, timeDiff } from "@thi.ng/bench/now";
+import { STATE_ACTIVE, STATE_DONE, STATE_ERROR, } from "./api.js";
+import { Fiber, fiber } from "./fiber.js";
+/**
+ * Returns co-routine which "blocks" for given number of milliseconds or
+ * indefinitely.
+ *
+ * @param delay
+ */
+export const wait = (delay) => delay !== undefined
+    ? untilPromise(new Promise((resolve) => setTimeout(resolve, delay)))
+    : fiber(function* () {
+        while (true)
+            yield;
+    });
+/**
+ * Returns ES6 generator which "blocks" for given number of frames.
+ *
+ * @param delay
+ */
+export function* waitFrames(delay) {
+    while (delay-- > 0)
+        yield;
+}
+/**
+ * Returns a fiber which executes given fibers in sequence until all are
+ * complete or one of them errored or got canceled.
+ *
+ * @param fibers
+ * @param opts
+ */
+export const sequence = (fibers, opts) => fiber(function* (ctx) {
+    for (let fiber of fibers) {
+        const $fiber = ctx.fork(fiber);
+        while ($fiber.isActive())
+            yield;
+        if ($fiber.state === STATE_ERROR)
+            throw $fiber.error;
+        ctx.value = $fiber.value;
+        if ($fiber.state > STATE_DONE || ctx.state > STATE_ACTIVE)
+            break;
+    }
+    return ctx.value;
+}, opts);
+/**
+ * Returns a fiber which executes given fibers as child processes until **one**
+ * of them is finished/terminated. That child fiber itself will be the result.
+ *
+ * @remarks
+ * Also see {@link withTimeout}, {@link all}.
+ *
+ * @example
+ * ```ta
+ * // wait until mouse click for max 5 seconds
+ * const res = yield* first([
+ *   untilEvent(window, "click", { id: "click" }),
+ *   wait(5000)
+ * ]);
+ *
+ * // one way to check result
+ * if (res.id === "click") { ... }
+ * ```
+ *
+ * @param fibers
+ * @param opts
+ */
+export const first = (fibers, opts) => fiber(function* (ctx) {
+    const $fibers = fibers.map((f) => ctx.fork(f));
+    while (true) {
+        for (let f of $fibers) {
+            if (!f.isActive())
+                return f;
+        }
+        yield;
+    }
+}, opts);
+/**
+ * Returns a fiber which executes given fibers as child processes until **all**
+ * of them are finished/terminated.
+ *
+ * @remarks
+ * Also see {@link first}.
+ *
+ * @param fibers
+ * @param opts
+ */
+export const all = (fibers, opts) => fiber((ctx) => {
+    for (let f of fibers)
+        ctx.fork(f);
+    return ctx.join();
+}, opts);
+/**
+ * Syntax sugar common use cases of {@link first} where a child fiber should be
+ * limited to a max. time period before giving up.
+ *
+ * @example
+ * ```ts
+ * // wait for fetch response max. 5 seconds
+ * const res = yield* withTimeout(untilPromise(fetch("example.json")), 5000);
+ *
+ * if (res.deref() != null) { ... }
+ * ```
+ *
+ * @param fiber
+ * @param timeout
+ * @param opts
+ */
+export const withTimeout = (fiber, timeout, opts) => first([fiber, wait(timeout)], opts);
+/**
+ * Higher-order fiber which repeatedly executes given `fiber` until its
+ * completion, but does so in a time-sliced manner, such that the fiber never
+ * consumes more than `maxTime` milliseconds per update cycle.
+ *
+ * @param fiber
+ * @param maxTime
+ * @param opts
+ */
+export const timeSlice = (body, maxTime, opts) => fiber(function* () {
+    const $fiber = fiber(body);
+    while (true) {
+        let t0 = now();
+        do {
+            if ($fiber.state > STATE_ACTIVE || $fiber.next() > STATE_ACTIVE)
+                return;
+        } while (timeDiff(t0, now()) < maxTime);
+        yield;
+    }
+}, opts);
+/**
+ * Returns a fiber which "blocks" until given predicate function returns true.
+ *
+ * @remarks
+ * See {@link untilState} for stateful version.
+ *
+ * @param pred
+ */
+export function* until(pred) {
+    while (!pred())
+        yield;
+}
+/**
+ * Stateful version of {@link until}. Takes an arbitrary `state`
+ * value/container and returns a fiber which "blocks" until given predicate
+ * function returns true. The `state` is passed to the predicate in each
+ * iteration.
+ *
+ * @param state
+ * @param pred
+ */
+export function* untilState(state, pred) {
+    while (!pred(state))
+        yield;
+}
+/**
+ * Returns a fiber which "blocks" until the given `promise` resolves or rejects.
+ * In the latter case, the fiber will throw the received error.
+ *
+ * @remove
+ * If the erroring fiber was added directly to a {@link FiberPool}, the error
+ * will be logged and the fiber removed. See {@link FiberPool.update} for
+ * details.
+ *
+ * @param promise
+ */
+export const untilPromise = (promise) => fiber(function* (ctx) {
+    let error;
+    promise.then((x) => ctx.done(x), (e) => (error = e));
+    while (true) {
+        if (error)
+            throw error;
+        yield;
+    }
+});
+/**
+ * Returns fiber which attaches a one-off event handler for event `type` to
+ * `target` and then "blocks" until the event occurred.
+ *
+ * @remarks
+ * The event handler will be removed when the fiber terminates. Upon completion,
+ * the event will be the fiber's {@link Fiber.value}.
+ *
+ * @param target
+ * @param type
+ * @param opts
+ */
+export const untilEvent = (target, type, opts) => {
+    let listener;
+    return fiber(null, {
+        ...opts,
+        init(ctx) {
+            listener = (e) => ctx.done(e);
+            target.addEventListener(type, listener);
+        },
+        deinit() {
+            target.removeEventListener(type, listener);
+        },
+    });
+};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@thi.ng/fibers",
+  "version": "0.1.0",
+  "description": "Process hierarchies & operators for cooperative multitasking",
+  "type": "module",
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thi-ng/umbrella.git"
+  },
+  "homepage": "https://github.com/thi-ng/umbrella/tree/develop/packages/fibers#readme",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/postspectacular"
+    },
+    {
+      "type": "patreon",
+      "url": "https://patreon.com/thing_umbrella"
+    }
+  ],
+  "author": "Karsten Schmidt (https://thi.ng)",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "yarn clean && tsc --declaration",
+    "clean": "rimraf --glob '*.js' '*.d.ts' '*.map' doc",
+    "doc": "typedoc --excludePrivate --excludeInternal --out doc src/index.ts",
+    "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
+    "doc:readme": "yarn doc:stats && tools:readme",
+    "doc:stats": "tools:module-stats",
+    "pub": "yarn npm publish --access public",
+    "test": "testament test"
+  },
+  "dependencies": {
+    "@thi.ng/api": "^8.9.0",
+    "@thi.ng/bench": "^3.4.1",
+    "@thi.ng/checks": "^3.4.0",
+    "@thi.ng/logger": "^1.4.16"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.36.3",
+    "@thi.ng/testament": "^0.3.18",
+    "rimraf": "^5.0.1",
+    "tools": "^0.0.1",
+    "typedoc": "^0.24.8",
+    "typescript": "^5.1.6"
+  },
+  "keywords": [
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "browser": {
+    "process": false,
+    "setTimeout": false
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "./*.js",
+    "./*.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    },
+    "./fiber": {
+      "default": "./fiber.js"
+    },
+    "./ops": {
+      "default": "./ops.js"
+    }
+  },
+  "thi.ng": {
+    "status": "alpha",
+    "year": 2023
+  },
+  "gitHead": "9fa3f7f8169efa30e3c71b43c82f77393581c3b5\n"
+}