From d0915ed785e7ccff243562c04fff2c3948449fcc Mon Sep 17 00:00:00 2001
From: hw <xodltus@naver.com>
Date: Sun, 10 Mar 2024 12:31:33 +0900
Subject: [PATCH] docs: add `fx`

---
 website/docs_md/method-chaining.md | 81 ++++++++++++++++++++++++++++++
 website/function.json              |  1 +
 website/sidebars.js                |  5 ++
 website/tsdoc-metadata.json        |  2 +-
 4 files changed, 88 insertions(+), 1 deletion(-)
 create mode 100644 website/docs_md/method-chaining.md

diff --git a/website/docs_md/method-chaining.md b/website/docs_md/method-chaining.md
new file mode 100644
index 00000000..2aac072a
--- /dev/null
+++ b/website/docs_md/method-chaining.md
@@ -0,0 +1,81 @@
+---
+id: method-chaining
+---
+
+# Method Chaining
+
+You can handle Iterable/AsyncIterable through a [pipe](https://fxts.dev/docs/pipe), but `fxts` also provides data change in the form of method chaining.
+
+```ts
+fx([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+  .filter((a) => a % 2 === 0) // [0, 2]
+  .map((a) => a * a) // [0, 4]
+  .take(2) // [0, 4]
+  .reduce(sum); // 4
+
+fx("abc")
+  .map((a) => a.toUpperCase()) // ["a", "b"]
+  .take(2)
+  .toArray(); // ["a", "b"]
+```
+
+### Note
+
+Since `fx` defaults to lazy evaluation, it is not actually evaluated until strict evaluation methods such as `toArray`, `groupBy`, `indexBy`, and `some` are executed.
+
+For details on lazy evaluation, please refer to https://fxts.dev/docs/lazy-evaluation.
+
+### Support for handling AsyncIterable
+
+`fx` can also handle [AsyncIterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncIterator) values. `toAsync` is used in the example below to create an `AsyncIterator` value.
+
+```ts
+await fx(toAsync([1, 2, 3, 4]))
+  .filter(async (a) => a % 2 === 0)
+  .map(async (a) => a * a)
+  .reduce(sum);
+
+await fx([1, 2, 3, 4])
+  .filter((a) => a % 2 === 0)
+  .toAsync() // if async function returns
+  .map(async (a) => a * a)
+  .reduce(sum);
+```
+
+### Handle Concurrency
+
+`fx` supports concurrent operation. As we saw in concurrent, concurrent can only be used in asyncIterable.
+
+For details on handling concurrent with `fxts`, please refer to https://fxts.dev/docs/handle-concurrency
+
+```ts
+/**
+ *
+ *  evaluation
+ *               ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐  ┌─────┐
+ *               │  1  │──│  2  │──│  3  │──│  4  │──│  5  │──│  6  │
+ *               └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘  └──┬──┘
+ *       map        │        │        │        │        │        │
+ *  concurrent(3)  (1)      (1)      (2)      (2)      (3)      (3)
+ *                  │        │        │        │        │        │
+ *                  ▼        ▼        ▼        ▼        ▼        ▼
+ */
+await fx(toAsync(range(1, 7)))
+  // async function returns
+  .map(async (a) => delay(100, a))
+  .concurrent(2)
+  .consume(); // It takes approximately 300ms.
+```
+
+### Etc
+
+`fx` does not provide all the functions of `fxts` as methods.
+
+If you want to use the `fxts` function which is not provided or additional functions, you can use the `chain` method.
+
+```ts
+fx([1, 2, 3, 4])
+  .chain(append(5))
+  .map((a) => a + 10)
+  .toArray(); // [11, 12, 13, 14, 15]
+```
diff --git a/website/function.json b/website/function.json
index d6d33600..902836aa 100644
--- a/website/function.json
+++ b/website/function.json
@@ -17,6 +17,7 @@
     "filter",
     "flat",
     "flatMap",
+    "fx",
     "intersection",
     "intersectionBy",
     "keys",
diff --git a/website/sidebars.js b/website/sidebars.js
index 257f7044..39615f04 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -71,6 +71,11 @@ const sidebars = {
           id: "error-handling",
           label: "Error handling",
         },
+        {
+          type: "doc",
+          id: "method-chaining",
+          label: "Method Chaining",
+        },
       ],
     },
     {
diff --git a/website/tsdoc-metadata.json b/website/tsdoc-metadata.json
index 5e804b3b..22735db1 100644
--- a/website/tsdoc-metadata.json
+++ b/website/tsdoc-metadata.json
@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.18.19"
+      "packageVersion": "7.42.3"
     }
   ]
 }