Skip to content

Commit 321ab39

Browse files
authored
Merge pull request #89 from duplojs/fix/87
fix(87): matchInformation + pipe
2 parents 1630e80 + 99b1ecc commit 321ab39

99 files changed

Lines changed: 1816 additions & 1803 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/en/v1/api/either/future.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,11 @@ An instance of `Future`, subclass of `Promise`, whose `await` automatically retu
3939

4040
## Best practices
4141

42-
- `Future` automatically propagates the first `Left` encountered: combine it with `E.rightAsyncPipe` for your async pipelines.
4342
- Use `Future.all([...])` to wait for multiple typed operations.
4443
- Prefer `futureSuccess` / `futureError` to create base cases.
4544

4645
## See also
4746

4847
- [`futureSuccess`](/en/v1/api/either/futureSuccess).
4948
- [`futureError`](/en/v1/api/either/futureError).
50-
- [`rightAsyncPipe`](/en/v1/api/either/rightAsyncPipe) – To chain async operations.
49+
- [`asyncGroup`](/en/v1/api/either/asyncGroup) – To aggregate asynchronous `Either` values.

‎docs/en/v1/api/either/index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,7 @@ Unwraps a `Left` payload immediately and throws if the input is not `Left`.
179179
Chains synchronous transformations as long as results are `Right`, and stops at the first `Left`.
180180

181181
### [rightAsyncPipe](/en/v1/api/either/rightAsyncPipe)
182-
Async version that accepts promises, `Future`, or `Either` and automatically stops on a `Left`.
182+
Async version that accepts promises or `Either` and automatically stops on a `Left`.
183183

184184
### [group](/en/v1/api/either/group)
185185
Aggregates multiple synchronous `Either` and returns the first `Left` or an object of `Right` values.
@@ -217,7 +217,7 @@ Unwraps selected `Either` payloads from an exhaustive information selector, othe
217217
Type-level helper that returns the same Either while preserving strict Left/Right typing.
218218

219219
### [safeCallback](/en/v1/api/either/safeCallback)
220-
Runs a callback and captures exceptions into a `Left<"callback">`.
220+
Runs a callback and captures thrown errors or promise rejections into, or resolves to, a `Left<"safe-callback-error">`.
221221

222222
## Boolean helpers
223223

Lines changed: 16 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
outline: [2, 3]
3-
description: "Asynchronous version of rightPipe. Automatically handles promises, Future, and Either, and short-circuits on the first Left."
3+
description: "Asynchronous version of rightPipe. Automatically handles promises and Either, and short-circuits on the first Left."
44
prev:
55
text: "rightPipe"
66
link: "/en/v1/api/either/rightPipe"
@@ -11,47 +11,52 @@ next:
1111

1212
# rightAsyncPipe
1313

14-
Asynchronous version of `rightPipe`. Automatically handles promises, `Future`, and `Either`, and short-circuits on the first `Left`.
14+
Asynchronous version of `rightPipe`. Automatically handles promises and `Either`, and short-circuits on the first `Left`.
1515

1616
## Interactive example
1717

1818
<MonacoTSEditor
1919
src="/examples/v1/api/either/rightAsyncPipe/tryout.doc.ts"
2020
majorVersion="v1"
21-
height="565px"
21+
height="523px"
2222
/>
2323

2424
## Syntax
2525

2626
```typescript
2727
function rightAsyncPipe<
28-
GenericInput extends MaybeFutureEither<AnyValue>,
29-
GenericOutputPipe1 extends MaybeFutureEither<AnyValue>
28+
const GenericInput extends unknown,
29+
const GenericOutputPipe1 extends unknown
3030
>(
3131
input: GenericInput,
3232
pipe1: RightAsyncPipeFunction<GenericInput, GenericOutputPipe1>
33-
): Future<RightAsyncPipeResult<GenericInput | GenericOutputPipe1, GenericOutputPipe1>>;
33+
): Promise<
34+
Extract<
35+
RightAsyncPipeResult<GenericInput | GenericOutputPipe1, GenericOutputPipe1>,
36+
any
37+
>
38+
>;
3439
// ... overloads up to 15 steps
3540
```
3641

37-
`RightAsyncPipeFunction` receives the unwrapped value of a `Right` (after `await`) and can return a raw value, an `Either`, or a promise/Future of these values.
42+
`RightAsyncPipeFunction` receives the unwrapped value of a `Right` (after `await`) and can return a raw value, an `Either`, or a promise of these values.
3843

3944
## Parameters
4045

41-
- `input`: Starting `Either`, promise, or `Future`.
46+
- `input`: Starting value, `Either`, or promise.
4247
- `pipeX`: Async or sync functions executed sequentially. The pipeline stops on the first `Left`.
4348

4449
## Return value
4550

46-
A `Future` resolved with the last `Right` if everything succeeds, or the `Left` that interrupted the pipeline.
51+
A `Promise` resolved with the last `Right` if everything succeeds, or the `Left` that interrupted the pipeline.
4752

4853
## Best practices
4954

5055
- Prefix your information with a clear namespace (`"user.fetch"`, `"user.validate"`) to track progress.
5156
- Combine `rightAsyncPipe` and `rightPipe` depending on whether your steps are sync/async.
52-
- In a `Promise`/`Future` mix, let `rightAsyncPipe` handle the normalization.
57+
- Let `rightAsyncPipe` await each step instead of manually unwrapping intermediate promises.
5358

5459
## See also
5560

5661
- [`rightPipe`](/en/v1/api/either/rightPipe).
57-
- [`future`](/en/v1/api/either/future) – To create `Future` values to chain.
62+
- [`safeCallback`](/en/v1/api/either/safeCallback) – To convert thrown errors into `Either` values.
Lines changed: 11 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
outline: [2, 3]
3-
description: "Runs a callback in a safe block. If the callback throws, the function returns a \"callback\" typed Left instead of propagating the exception."
3+
description: "Runs a callback in a safe block. If the callback throws or returns a rejected promise, the function returns or resolves to a safe-callback-error Left instead of propagating the error."
44
prev:
55
text: "expect"
66
link: "/en/v1/api/either/expect"
@@ -11,37 +11,38 @@ next:
1111

1212
# safeCallback
1313

14-
Runs a callback in a safe block. If the callback throws, the function returns a `"callback"` typed `Left` instead of propagating the exception. If the callback returns an `Either`, it is kept as-is.
14+
Runs a callback in a safe block. If the callback throws or returns a rejected promise, the function returns or resolves to a `"safe-callback-error"` typed `Left` instead of propagating the error. If the callback returns an `Either`, it is kept as-is. Promise results are handled after resolution.
1515

1616
## Interactive example
1717

1818
<MonacoTSEditor
1919
src="/examples/v1/api/either/safeCallback/tryout.doc.ts"
2020
majorVersion="v1"
21-
height="376px"
21+
height="565px"
2222
/>
2323

2424
## Syntax
2525

2626
```typescript
2727
function safeCallback<
28-
GenericOutput extends unknown
28+
const GenericOutput extends unknown
2929
>(
3030
theFunction: () => GenericOutput
31-
): ComputeSafeCallbackResult<GenericOutput> | CallbackError;
31+
): Extract<ComputeSafeCallbackResult<GenericOutput>, any>;
3232
```
3333

3434
## Parameters
3535

36-
- `theFunction` : Callback to execute in a safe block.
36+
- `theFunction`: Callback to execute in a safe block. It can return a direct value, an `Either`, or a promise of either.
3737

3838
## Return value
3939

40-
- If the callback returns an `Left` or `Right`: the `Either` is returned as-is.
41-
- If the callback succeeds with a non-`Either` value: the value is wrapped in `CallbackSuccess`.
42-
- If the callback throws: `CallbackError` (alias of `left("callback", error)`).
40+
- If the callback returns a `Left` or `Right`: the `Either` is returned as-is.
41+
- If the callback succeeds with a non-`Either` value: the value is wrapped in `SafeCallbackSuccess`.
42+
- If the callback returns a promise: the resolved value follows the same rules.
43+
- If the callback throws or the promise rejects: `SafeCallbackError` (`left("safe-callback-error", error)`) is returned or resolved.
4344

4445
## See also
4546

4647
- [`left`](/en/v1/api/either/left) – Build a typed `Left`.
47-
- [`whenHasInformation`](/en/v1/api/either/whenHasInformation) – Pattern match on `"callback"`.
48+
- [`whenHasInformation`](/en/v1/api/either/whenHasInformation) – Pattern match on `"safe-callback-error"`.

‎docs/en/v1/guide/either.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ if (E.isLeft(result) && E.hasInformation(result, "emailAlreadyExists")) {
8989

9090
When you want to chain transformations **as long as it stays a `Right`**:
9191
- `E.rightPipe` for sync
92-
- `E.rightAsyncPipe` for async (promises and `Future`)
92+
- `E.rightAsyncPipe` for async pipelines based on promises
9393

9494
To aggregate multiple `Either`:
9595
- `E.group` returns the first `Left`, otherwise a `Right` with all values

‎docs/examples/v1/api/array/withMaxElements/tryout.doc.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,6 @@ const pipeRoles = pipe(
2525

2626
type checkPipeRoles = ExpectType<
2727
typeof pipeRoles,
28-
["guest"] & A.MaxElements<1>,
28+
readonly ["guest"] & A.MaxElements<1>,
2929
"strict"
3030
>;

‎docs/examples/v1/api/either/bool/tryout.doc.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@ import { A, E, pipe, type ExpectType, equal } from "@duplojs/utils";
22

33
const result = pipe(
44
["duplo"],
5-
A.find(equal("nest")),
5+
A.find(equal("duplo")),
66
E.bool,
77
);
88

99
type check = ExpectType<
1010
typeof result,
11-
E.BoolFalsy<undefined> | E.BoolTruthy<"nest">,
11+
E.BoolFalsy<undefined> | E.BoolTruthy<"duplo">,
1212
"strict"
1313
>;

‎docs/examples/v1/api/either/rightAsyncPipe/tryout.doc.ts‎

Lines changed: 8 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,13 @@
11
import { E, type ExpectType } from "@duplojs/utils";
22

3-
const input = E.future(
4-
Promise.resolve(
5-
true
6-
? false
7-
? true
8-
? E.right("right-1", 1)
9-
: E.left("left-1", null)
10-
: E.right("right-2", 2)
11-
: E.left("left-2", 2),
12-
),
3+
const input = Promise.resolve(
4+
true
5+
? false
6+
? true
7+
? E.right("right-1", 1)
8+
: E.left("left-1", null)
9+
: E.right("right-2", 2)
10+
: E.left("left-2", 2),
1311
);
1412

1513
const result = E.rightAsyncPipe(

‎docs/examples/v1/api/either/safeCallback/tryout.doc.ts‎

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
import { E } from "@duplojs/utils";
22

33
const success = E.safeCallback(() => 42);
4-
// E.CallbackError | E.CallbackSuccess<number>
4+
// E.SafeCallbackSuccess<number> | E.SafeCallbackError
55

66
const failure = E.safeCallback(() => {
77
throw new Error("boom");
@@ -14,3 +14,12 @@ const eitherResult = E.safeCallback(
1414
);
1515

1616
const isLeft = E.isLeft(eitherResult);
17+
18+
const asyncSuccess = E.safeCallback(
19+
() => Promise.resolve("done"),
20+
);
21+
// Promise<E.SafeCallbackSuccess<string> | E.SafeCallbackError> | E.SafeCallbackError
22+
23+
const asyncFailure = E.safeCallback(
24+
() => Promise.reject(new Error("boom")),
25+
);

‎docs/fr/v1/api/either/future.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,12 +39,11 @@ Une instance de `Future`, sous-classe de `Promise`, dont `await` retourne automa
3939

4040
## Bonnes pratiques
4141

42-
- `Future` propage automatiquement le premier `Left` rencontré : combinez-le avec `E.rightAsyncPipe` pour vos pipelines async.
4342
- Utilisez `Future.all([...])` pour attendre plusieurs opérations typées.
4443
- Préférez `futureSuccess` / `futureError` pour créer des cas de base.
4544

4645
## Voir aussi
4746

4847
- [`futureSuccess`](/fr/v1/api/either/futureSuccess).
4948
- [`futureError`](/fr/v1/api/either/futureError).
50-
- [`rightAsyncPipe`](/fr/v1/api/either/rightAsyncPipe) – Pour chaîner des opérations async.
49+
- [`asyncGroup`](/fr/v1/api/either/asyncGroup) – Pour agréger des valeurs `Either` asynchrones.

0 commit comments

Comments
 (0)