From a5ab74e5b13a75ed472495462cb34e1e4ad9bf4f Mon Sep 17 00:00:00 2001
From: bloodyowl <bloodyowl@icloud.com>
Date: Sun, 27 Oct 2024 11:52:10 +0100
Subject: [PATCH] Add docs on retry & concurrency

---
 docs/docs/concurrency.md | 18 ++++++++++++++++++
 docs/docs/retry.md       | 31 +++++++++++++++++++++++++++++++
 docs/sidebars.js         |  2 ++
 3 files changed, 51 insertions(+)
 create mode 100644 docs/docs/concurrency.md
 create mode 100644 docs/docs/retry.md

diff --git a/docs/docs/concurrency.md b/docs/docs/concurrency.md
new file mode 100644
index 0000000..931a657
--- /dev/null
+++ b/docs/docs/concurrency.md
@@ -0,0 +1,18 @@
+---
+title: Concurrency
+sidebar_label: Concurrency
+---
+
+While you have a simple `Future.all` to run all futures in parallel (like `Promise.all` does), you might want to limit the concurrency at which you execute operations.
+
+Using `Future.concurrent`, you can specify the maximum concurrency for your array of operations.
+
+```ts
+Future.concurrent(
+  userIds.map((userId) => {
+    // notice we return a function
+    return () => getUserById(userId);
+  }),
+  { concurrency: 10 },
+);
+```
diff --git a/docs/docs/retry.md b/docs/docs/retry.md
new file mode 100644
index 0000000..f3330e6
--- /dev/null
+++ b/docs/docs/retry.md
@@ -0,0 +1,31 @@
+---
+title: Retry
+sidebar_label: Retry
+---
+
+When some operations can fail, you might want to implement a retry logic.
+
+## Retry with maximum attempts
+
+If `getUserById` outputs a `Result.Ok` value, the future resolves, if it outputs a `Result.Error`, it re-executes `getUserById`.
+
+```ts
+// retry immediately after failure
+Future.retry(() => getUserById(userId), { max: 3 });
+// Future<Result<...>>
+```
+
+## Rety with delay
+
+The function you pass `Future.retry` takes an `attempt` parameter, which is the current number of attempts. The count starts at `0`.
+
+```ts
+// adding delay
+Future.retry(
+  (attempt) => {
+    return Future.wait(attempt * 100).flatMap(() => getUserById(userId));
+  },
+  { max: 10 },
+);
+// Future<Result<...>>
+```
diff --git a/docs/sidebars.js b/docs/sidebars.js
index dedb0aa..f682f2a 100644
--- a/docs/sidebars.js
+++ b/docs/sidebars.js
@@ -72,6 +72,8 @@ module.exports = {
         "form-validation",
         "nested-optional-values",
         "cancellable-request",
+        "retry",
+        "concurrency",
       ],
     },
     {