From 924a15216d87a167bcef734df55818b31f0f3a1a Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:34:25 +0000 Subject: [PATCH 01/10] docs(all): add search terms and use cases --- docs/async/all.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/async/all.mdx b/docs/async/all.mdx index a20c7168..25954153 100644 --- a/docs/async/all.mdx +++ b/docs/async/all.mdx @@ -34,3 +34,13 @@ const { user } = await _.all({ message: slack.customerSuccessChannel.sendMessage(...) }) ``` + +### Search terms + +- Often referred to as `all`, `promiseAll`, or `aggregatePromiseAll` + +### Popular use cases + +- Use this function to concurrently execute multiple asynchronous tasks, ensuring that all results are gathered, while handling any potential errors in a clean and organized manner. +- Utilize it in a scenario where you need to create multiple resources (e.g., users, buckets, channels) at the same time from different APIs, and want to manage both successful responses and potential errors effectively. +- Leverage it for parallel execution of API calls in a batch process, where each promise may fail independently, but you still want to collect all results or errors related to these calls. From 09e5ce752d70fe3f1a02c6bb9f559007973a3e3c Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:36:00 +0000 Subject: [PATCH 02/10] docs(defer): add search terms and use cases --- docs/async/defer.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/async/defer.mdx b/docs/async/defer.mdx index 7655ca4a..2ee98662 100644 --- a/docs/async/defer.mdx +++ b/docs/async/defer.mdx @@ -39,3 +39,13 @@ await _.defer(async register => { await executeTest(org, user) }) ``` + +### Search terms + +- Commonly referenced as `defer`, `cleanup`, or `ensure` in other libraries. + +### Popular use cases + +- Using `defer` for resource management, such as automatically closing file handles or database connections in a controlled manner after operations complete, ensuring that all cleanup code runs regardless of success or failure. +- Implementing deferred execution for asynchronous tasks, allowing multiple callbacks to be registered that handle cleanup logic, which is especially useful in error-prone operations like network requests or file manipulations. +- Facilitating error handling in complex code flows by automatically executing error handling callbacks, improving code maintainability and readability while simplifying structured cleanup of resources. From ede5dc73c32d952ff8116bf478dd6276a013af99 Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:36:24 +0000 Subject: [PATCH 03/10] docs(guard): add search terms and use cases --- docs/async/guard.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/async/guard.mdx b/docs/async/guard.mdx index 387607d4..c8074258 100644 --- a/docs/async/guard.mdx +++ b/docs/async/guard.mdx @@ -17,3 +17,13 @@ You can choose to guard only specific errors too const isInvalidUserError = (err: any) => err.code === 'INVALID_ID' const user = (await guard(fetchUser, isInvalidUserError)) ?? DEFAULT_USER ``` + +### Search terms + +- Often called `tryAsync`, `attemptAsync`, or `safeCall` in other libraries. + +### Popular use cases + +- Safely executing asynchronous functions in environments where exceptions are undesirable, replacing potential errors with `undefined`. +- Wrapping network requests or database calls to simplify error handling within complex applications. +- Utilizing a guard clause for fallback mechanisms when integrating third-party APIs that may be unreliable or sporadically fail. From 5632800e72152ad12d7e86b68c567b915591a988 Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:37:04 +0000 Subject: [PATCH 04/10] docs(map): add search terms and use cases --- docs/async/defer.mdx | 2 +- docs/async/map.mdx | 10 ++++++++++ 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/async/defer.mdx b/docs/async/defer.mdx index 2ee98662..b03ccab1 100644 --- a/docs/async/defer.mdx +++ b/docs/async/defer.mdx @@ -42,7 +42,7 @@ await _.defer(async register => { ### Search terms -- Commonly referenced as `defer`, `cleanup`, or `ensure` in other libraries. +- Commonly referenced as `defer`, `cleanup`, or `ensure` ### Popular use cases diff --git a/docs/async/map.mdx b/docs/async/map.mdx index c2e799cf..1d477f2e 100644 --- a/docs/async/map.mdx +++ b/docs/async/map.mdx @@ -16,3 +16,13 @@ const users = await _.map(userIds, async userId => { return await api.users.find(userId) }) ``` + +### Search terms + +- Often called `asyncMap`, `mapAsync`, or `promiseMap` in other libraries. + +### Popular use cases + +- Parallel data fetching: Use `map` to iterate over an array of URLs, fetching data from each asynchronously and collecting the results. +- Concurrent processing: Utilize `map` to apply a heavy computation asynchronously on an array of items, such as hashing passwords or processing images. +- Batch processing: Employ `map` to handle bulk updates or inserts in a database where each operation needs to be done asynchronously. From c002776d8c6c369a5197703307f0178226002de4 Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:38:08 +0000 Subject: [PATCH 05/10] docs(parallel): add search terms and use cases --- docs/async/parallel.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/async/parallel.mdx b/docs/async/parallel.mdx index 38f4bc19..291a7e8c 100644 --- a/docs/async/parallel.mdx +++ b/docs/async/parallel.mdx @@ -40,3 +40,13 @@ console.log(err) // => AggregateError console.log(err.errors) // => [Error, Error, Error] console.log(err.errors[1].message) // => No, I don't want to find user 2 ``` + +### Search terms + +- Often called `parallelize`, `concurrent`, or `asyncMap` in other libraries. + +### Popular use cases + +- Running multiple API calls concurrently and aggregating results while handling errors in bulk. +- Processing a large set of data items (e.g., files, database records) in parallel with controlled concurrency. +- Performing parallel execution of tasks where the order of execution results does not matter but managing error propagation is necessary. From 581157e04b3a8a65c535df05e5a65a9ca48bc60d Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:38:54 +0000 Subject: [PATCH 06/10] docs(reduce): add search terms and use cases --- docs/async/reduce.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/async/reduce.mdx b/docs/async/reduce.mdx index ca87a612..62a2e0c1 100644 --- a/docs/async/reduce.mdx +++ b/docs/async/reduce.mdx @@ -24,3 +24,13 @@ const users = await _.reduce( {}, ) ``` + +### Search terms + +- Often called `asyncReduce`, `asyncFold`, or `reduceAsync` in other libraries. + +### Popular use cases + +- Aggregating results from an array of promises where each promise's result is dependent on the previous result. +- Performing complex, sequential data transformations on large datasets within a controlled asynchronous context. +- Sequentially processing a list of tasks where each task needs the result of the previously resolved task, especially in data pipelines or batch processing scenarios. From d6302f40a1beccee97b67c3bb9da9495e9ef5959 Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:39:40 +0000 Subject: [PATCH 07/10] docs(retry): add search terms and use cases --- docs/async/retry.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/async/retry.mdx b/docs/async/retry.mdx index c0ca0188..09daebc9 100644 --- a/docs/async/retry.mdx +++ b/docs/async/retry.mdx @@ -21,3 +21,13 @@ await _.retry({ times: 2, delay: 1000 }, api.users.list) // exponential backoff await _.retry({ backoff: i => 10 ** i }, api.users.list) ``` + +### Search Terms + +- Often called `retry`, `retryAsync`, or `retryOperation` in other libraries. + +### Popular Use Cases + +- Retrying API calls or network requests that may intermittently fail. +- Implementing resilient calls to third-party services where temporary downtime or hiccups may occur. +- Handling operations that may fail due to race conditions or concurrency issues, like database queries or file system operations. From c32525ff86fc71306ef1ad540b9adf2435b6881d Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:40:22 +0000 Subject: [PATCH 08/10] docs(sleep): add search terms and use cases --- docs/async/sleep.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/async/sleep.mdx b/docs/async/sleep.mdx index 706df167..d24b40e5 100644 --- a/docs/async/sleep.mdx +++ b/docs/async/sleep.mdx @@ -12,3 +12,14 @@ import * as _ from 'radashi' await _.sleep(2000) // => waits 2 seconds ``` + +### Search terms + +- Often called `delay`, `timeout`, `wait`, `pause`, or `sleep` in other libraries. + +### Popular use cases + +- Delay the execution of a function or a block of code for a specified duration. +- Creating timed intervals between retry attempts in asynchronous operations or network requests. +- Simulating latency or downtime in testing environments to validate timeout handling in applications. +- Throttling or debouncing actions in user interfaces to enhance performance and usability. From fc8ada101d2a3e158bbaaf0a56586f5b5e955df9 Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:41:06 +0000 Subject: [PATCH 09/10] docs(tryit): add search terms and use cases --- docs/async/tryit.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/async/tryit.mdx b/docs/async/tryit.mdx index bca5c4bb..f3ea9dcf 100644 --- a/docs/async/tryit.mdx +++ b/docs/async/tryit.mdx @@ -26,3 +26,13 @@ const findUser = _.tryit(api.users.find) const [err, user] = await findUser(userId) ``` + +### Search terms + +- Often called `tryCatch`, `to`, or `attempt` in other libraries. + +### Popular use cases + +- Handling asynchronous operations without explicit try-catch blocks, ensuring promises are safely caught. +- Simplifying error handling in promise-based code by returning `[Error, result]` tuples, streamlining control flow. +- Wrapping synchronous and asynchronous functions to provide consistent error-first handling, useful in complex asynchronous functions and APIs. From 49453184d457eb01f82013b75cb4a6585a6c82fb Mon Sep 17 00:00:00 2001 From: marlonpassos Date: Thu, 22 Aug 2024 22:41:56 +0000 Subject: [PATCH 10/10] docs(withResolvers): add search terms and use cases --- docs/async/withResolvers.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/async/withResolvers.mdx b/docs/async/withResolvers.mdx index e5dcd099..3605088c 100644 --- a/docs/async/withResolvers.mdx +++ b/docs/async/withResolvers.mdx @@ -14,3 +14,13 @@ const { resolve, reject, promise } = withResolvers() resolve(42) ``` + +### Search terms + +- Often called `deferred`, `promiseWithDeferred`, or `promiseResolver` in other libraries. + +### Popular use cases + +- Handling asynchronous operations in a more controlled manner where you need manual resolution or rejection of a promise, often used for testing or mock implementation. +- Integrating with APIs or libraries that do not natively support promises by enabling conversion from callback-style to promise-style code. +- Coordinating multiple asynchronous operations where one promise's resolution should trigger others, enabling complex workflows or event handling.