@thi.ng/fibers 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-09-06T13:36:28Z
+- **Last updated**: 2023-09-17T15:40:02Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/fibers@0.5.0) (2023-09-17)
+
+#### 🚀 Features
+
+- add asPromise() fiber-to-promise conversion ([29fc86f](https://github.com/thi-ng/umbrella/commit/29fc86f))
+
 ## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/fibers@0.4.0) (2023-09-06)
 
 #### 🚀 Features

package/README.md

@@ -114,6 +114,7 @@ app.fork(function* () {
 The following operators act as basic composition helpers to construct more elaborate fiber setups:
 
 - [`all`](https://docs.thi.ng/umbrella/fibers/functions/all.html): wait for all given fibers to complete
+- [`asPromise`](https://docs.thi.ng/umbrella/fibers/functions/asPromise.html): wrap fiber as promise for use in `async` contexts
 - [`first`](https://docs.thi.ng/umbrella/fibers/functions/first.html): wait for one of the given fibers to complete
 - [`fork`](https://docs.thi.ng/umbrella/fibers/classes/Fiber.html#fork): create & attach a new child process
 - [`forkAll`](https://docs.thi.ng/umbrella/fibers/classes/Fiber.html#forkAll): create & attach multiple child processes
@@ -121,6 +122,7 @@ The following operators act as basic composition helpers to construct more elabo
 - [`sequence`](https://docs.thi.ng/umbrella/fibers/functions/sequence.html): execute fibers in sequence
 - [`shuffle`](https://docs.thi.ng/umbrella/fibers/functions/shuffle-1.html): execute fibers in constantly randomized order
 - [`timeSlice`](https://docs.thi.ng/umbrella/fibers/functions/timeSlice.html): execute fiber in batches of N milliseconds
+- [`timeSliceIterable`](https://docs.thi.ng/umbrella/fibers/functions/timeSliceIterable.html): consume iterable in batches of N milliseconds
 - [`until`](https://docs.thi.ng/umbrella/fibers/functions/until.html): wait until predicate is truthy
 - [`untilEvent`](https://docs.thi.ng/umbrella/fibers/functions/untilEvent.html): wait until event occurs
 - [`untilPromise`](https://docs.thi.ng/umbrella/fibers/functions/untilPromise.html): wait until promise resolves/rejects
@@ -376,7 +378,7 @@ For Node.js REPL:
 const fibers = await import("@thi.ng/fibers");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.33 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.41 KB
 
 ## Dependencies
 
@@ -397,12 +399,13 @@ directory are using this package.
 
 A selection:
 
-| Screenshot                                                                                                            | Description                                                       | Live demo                                            | Source                                                                            |
-|:----------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------------|:-----------------------------------------------------|:----------------------------------------------------------------------------------|
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ascii-raymarch.jpg" width="240"/> | ASCII art raymarching with thi.ng/shader-ast & thi.ng/text-canvas | [Demo](https://demo.thi.ng/umbrella/ascii-raymarch/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ascii-raymarch) |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/fiber-basics.png" width="240"/>   | Fiber-based cooperative multitasking basics                       | [Demo](https://demo.thi.ng/umbrella/fiber-basics/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/fiber-basics)   |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ifs-fractal.jpg" width="240"/>    | Barnsley fern IFS fractal renderer                                | [Demo](https://demo.thi.ng/umbrella/ifs-fractal/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ifs-fractal)    |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/render-audio.png" width="240"/>   | Generative audio synth offline renderer and WAV file export       | [Demo](https://demo.thi.ng/umbrella/render-audio/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/render-audio)   |
+| Screenshot                                                                                                            | Description                                                                                             | Live demo                                            | Source                                                                            |
+|:----------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------|:-----------------------------------------------------|:----------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ascii-raymarch.jpg" width="240"/> | ASCII art raymarching with thi.ng/shader-ast & thi.ng/text-canvas                                       | [Demo](https://demo.thi.ng/umbrella/ascii-raymarch/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ascii-raymarch) |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/fiber-basics.png" width="240"/>   | Fiber-based cooperative multitasking basics                                                             | [Demo](https://demo.thi.ng/umbrella/fiber-basics/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/fiber-basics)   |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/ifs-fractal.jpg" width="240"/>    | Barnsley fern IFS fractal renderer                                                                      | [Demo](https://demo.thi.ng/umbrella/ifs-fractal/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/ifs-fractal)    |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/mastodon-feed.jpg" width="240"/>  | Mastodon API feed reader with support for different media types, fullscreen media modal, HTML rewriting | [Demo](https://demo.thi.ng/umbrella/mastodon-feed/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/mastodon-feed)  |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/render-audio.png" width="240"/>   | Generative audio synth offline renderer and WAV file export                                             | [Demo](https://demo.thi.ng/umbrella/render-audio/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/render-audio)   |
 
 ## API
 

package/ops.d.ts

@@ -31,7 +31,7 @@ export declare const sequence: (fibers: Iterable<MaybeFiber>, opts?: Partial<Fib
  * Also see {@link withTimeout}, {@link all}.
  *
  * @example
- * ```ta
+ * ```ts
  * // wait until mouse click for max 5 seconds
  * const res = yield* first([
  *   untilEvent(window, "click", { id: "click" }),
@@ -202,4 +202,38 @@ export declare class Shuffle extends Fiber {
 export declare const shuffle: (fibers: Iterable<MaybeFiber>, opts?: Partial<FiberOpts & {
     rnd: IRandom;
 }>) => Shuffle;
+/**
+ * Helper function to await fiber-based task completion from within an `async`
+ * context. Wraps given `task` in a fiber with custom {@link FiberOpts.deinit}
+ * and {@link FiberOpts.catch} handlers and executes it. Returns a promise which
+ * resolves with that fiber's final value once its complete. If there is an
+ * error during fiber execution the promise will be rejected with that original
+ * error.
+ *
+ * @remarks
+ * If `opts` are given, their {@link FiberOpts.deinit} and
+ * {@link FiberOpts.catch} handlers will be augmented with resolving/rejecting
+ * the promise. I.e. The promise will NOT be rejected if there's a user-provided
+ * `catch` handler indicating the error has been dealt with.
+ *
+ * @example
+ * ```ts
+ * (async () => {
+ *   // create & spawn task/fiber
+ *   const task = asPromise(function*() {
+ *     for(let i = 0; i< 3; i++) {
+ *       console.log("working...", i);
+ *       yield* wait(1000);
+ *     }
+ *     return 42;
+ *   });
+ *   // now wait for task to complete
+ *   const result = await task;
+ *   console.log("final result", result);
+ * })()
+ * ```
+ *
+ * @param task
+ */
+export declare const asPromise: <T>(task: MaybeFiber<T>, opts?: Partial<FiberOpts>) => Promise<T>;
 //# sourceMappingURL=ops.d.ts.map

package/ops.js

@@ -52,7 +52,7 @@ export const sequence = (fibers, opts) => fiber(function* (ctx) {
  * Also see {@link withTimeout}, {@link all}.
  *
  * @example
- * ```ta
+ * ```ts
  * // wait until mouse click for max 5 seconds
  * const res = yield* first([
  *   untilEvent(window, "click", { id: "click" }),
@@ -291,3 +291,51 @@ export class Shuffle extends Fiber {
  * @param opts
  */
 export const shuffle = (fibers, opts) => new Shuffle(fibers, opts);
+/**
+ * Helper function to await fiber-based task completion from within an `async`
+ * context. Wraps given `task` in a fiber with custom {@link FiberOpts.deinit}
+ * and {@link FiberOpts.catch} handlers and executes it. Returns a promise which
+ * resolves with that fiber's final value once its complete. If there is an
+ * error during fiber execution the promise will be rejected with that original
+ * error.
+ *
+ * @remarks
+ * If `opts` are given, their {@link FiberOpts.deinit} and
+ * {@link FiberOpts.catch} handlers will be augmented with resolving/rejecting
+ * the promise. I.e. The promise will NOT be rejected if there's a user-provided
+ * `catch` handler indicating the error has been dealt with.
+ *
+ * @example
+ * ```ts
+ * (async () => {
+ *   // create & spawn task/fiber
+ *   const task = asPromise(function*() {
+ *     for(let i = 0; i< 3; i++) {
+ *       console.log("working...", i);
+ *       yield* wait(1000);
+ *     }
+ *     return 42;
+ *   });
+ *   // now wait for task to complete
+ *   const result = await task;
+ *   console.log("final result", result);
+ * })()
+ * ```
+ *
+ * @param task
+ */
+export const asPromise = (task, opts) => new Promise((resolve, reject) => {
+    fiber(task, {
+        ...opts,
+        deinit: (ctx) => {
+            opts?.deinit && opts.deinit(ctx);
+            ctx.state < STATE_ERROR && resolve(ctx.deref());
+        },
+        catch: (ctx, e) => {
+            if (opts?.catch && opts.catch(ctx, e))
+                return true;
+            reject(e);
+            return false;
+        },
+    }).run();
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/fibers",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Process hierarchies & operators for cooperative multitasking",
   "type": "module",
   "module": "./index.js",
@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.9.5",
-    "@thi.ng/arrays": "^2.5.22",
+    "@thi.ng/arrays": "^2.5.23",
     "@thi.ng/bench": "^3.4.6",
     "@thi.ng/checks": "^3.4.5",
     "@thi.ng/errors": "^2.3.5",
@@ -108,5 +108,5 @@
     "status": "alpha",
     "year": 2023
   },
-  "gitHead": "1bbef970bab7f7def0700e587cf0471e1e1ef9f3\n"
+  "gitHead": "3be3edbcb76c6855ee8b0c667fe4e152615652c9\n"
 }