repos / starfx

commit

96e49d4

parent

c1d8bf0

author

Eric Bower

date

2024-08-26 03:40:24 +0000 UTC

docs: fx

 1@@ -100,6 +100,11 @@ func main() {
 2 				Href: "/loaders",
 3 				Page: pager("loaders.md"),
 4 			},
 5+			{
 6+				Text: "fx",
 7+				Href: "/fx",
 8+				Page: pager("fx.md"),
 9+			},
10 			{
11 				Text: "Error Handling",
12 				Href: "/error-handling",

 1@@ -0,0 +1,55 @@
 2+---
 3+title: fx
 4+description: Our powerful async flow control
 5+---
 6+
 7+`fx` (Effects) are helper functions to make async flow control easier.
 8+
 9+# parallel
10+
11+The goal of `parallel` is to make it easier to cooridnate multiple async
12+operations in parallel, with different ways to receive completed tasks.
13+
14+All tasks are called with `fx.safe` which means they will never throw an
15+exception. Instead all tasks will return a Result object that the end
16+development must evaluate in order to grab the value.
17+
18+```ts
19+import { parallel } from "starfx";
20+
21+function* run() {
22+  const task = yield* parallel([job1, job2]);
23+  // wait for all tasks to complete before moving to next yield point
24+  const results = yield* task;
25+  // job1 = results[0];
26+  // job2 = results[1];
27+}
28+```
29+
30+Instead of waiting for all tasks to complete, we can instead loop over tasks as
31+they arrive:
32+
33+```ts
34+function* run() {
35+  const task = yield* parallel([job1, job2]);
36+  for (const job of yield* each(task.immediate)) {
37+    // job2 completes first then it will be first in list
38+    console.log(job);
39+    yield* each.next();
40+  }
41+}
42+```
43+
44+Or we can instead loop over tasks in order of the array provided to parallel:
45+
46+```ts
47+function* run() {
48+  const task = yield* parallel([job1, job2]);
49+  for (const job of yield* each(task.sequence)) {
50+    // job1 then job2 will be returned regardless of when the jobs
51+    // complete
52+    console.log(job);
53+    yield* each.next();
54+  }
55+}
56+```