From c7dfa1b44d3d37b784da9ad115ccace31f3f81a5 Mon Sep 17 00:00:00 2001 From: m-shaka Date: Thu, 24 Oct 2024 09:51:51 +0900 Subject: [PATCH 1/2] docs: update docs about safeTry --- README.md | 16 ++++++---------- src/result-async.ts | 9 +++++++++ src/result.ts | 25 ++++++++++++++++--------- 3 files changed, 31 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 889d96f1..5c9f113e 100644 --- a/README.md +++ b/README.md @@ -802,7 +802,7 @@ const result = Result.combineWithAllErrors(resultList) #### `Result.safeUnwrap()` -**⚠️ You must use `.safeUnwrap` in a generator context with `safeTry`**. Please see [safeTry](#safeTry). +**Deprecated**. You don't need to use this method anymore. Allows for unwrapping a `Result` or returning an `Err` implicitly, thereby reducing boilerplate. @@ -1412,7 +1412,7 @@ const result = ResultAsync.combineWithAllErrors(resultList) #### `ResultAsync.safeUnwrap()` -**⚠️ You must use `.safeUnwrap` in a generator context with `safeTry`**. Please see [safeTry](#safeTry). +**Deprecated**. You don't need to use this method anymore. Allows for unwrapping a `Result` or returning an `Err` implicitly, thereby reducing boilerplate. @@ -1492,13 +1492,11 @@ function myFunc(): Result { // aborted here and the enclosing `safeTry` block is evaluated to that `Err`. // Otherwise, this `(yield* ...)` is evaluated to its `.value`. (yield* mayFail1() - .mapErr(e => `aborted by an error from 1st function, ${e}`) - .safeUnwrap()) + .mapErr(e => `aborted by an error from 1st function, ${e}`)) + // The same as above. (yield* mayFail2() - .mapErr(e => `aborted by an error from 2nd function, ${e}`) - .safeUnwrap()) + .mapErr(e => `aborted by an error from 2nd function, ${e}`)) ) }) } @@ -1520,13 +1518,11 @@ function myFunc(): Promise> { return ok( // You have to await if the expression is Promise (yield* (await mayFail1()) - .mapErr(e => `aborted by an error from 1st function, ${e}`) - .safeUnwrap()) + .mapErr(e => `aborted by an error from 1st function, ${e}`)) + // You can call `safeUnwrap` directly if its ResultAsync (yield* mayFail2() - .mapErr(e => `aborted by an error from 2nd function, ${e}`) - .safeUnwrap()) + .mapErr(e => `aborted by an error from 2nd function, ${e}`)) ) }) } diff --git a/src/result-async.ts b/src/result-async.ts index 2bcb2d00..6afcb581 100644 --- a/src/result-async.ts +++ b/src/result-async.ts @@ -192,6 +192,15 @@ export class ResultAsync implements PromiseLike> { } /** + * @deprecated will be removed in 9.0.0. + * + * You can use `safeTry` without this method. + * @example + * ```typescript + * safeTry(async function* () { + * const okValue = yield* yourResult + * }) + * ``` * Emulates Rust's `?` operator in `safeTry`'s body. See also `safeTry`. */ async *safeUnwrap(): AsyncGenerator, T> { diff --git a/src/result.ts b/src/result.ts index 682e0550..3faa8886 100644 --- a/src/result.ts +++ b/src/result.ts @@ -73,13 +73,12 @@ export function err(err: E): Err { * Evaluates the given generator to a Result returned or an Err yielded from it, * whichever comes first. * - * This function, in combination with `Result.safeUnwrap()`, is intended to emulate - * Rust's ? operator. + * This function is intended to emulate Rust's ? operator. * See `/tests/safeTry.test.ts` for examples. * - * @param body - What is evaluated. In body, `yield* result.safeUnwrap()` works as + * @param body - What is evaluated. In body, `yield* result` works as * Rust's `result?` expression. - * @returns The first occurence of either an yielded Err or a returned Result. + * @returns The first occurrence of either an yielded Err or a returned Result. */ export function safeTry(body: () => Generator, Result>): Result export function safeTry< @@ -96,13 +95,12 @@ export function safeTry< * Evaluates the given generator to a Result returned or an Err yielded from it, * whichever comes first. * - * This function, in combination with `Result.safeUnwrap()`, is intended to emulate - * Rust's ? operator. + * This function is intended to emulate Rust's ? operator. * See `/tests/safeTry.test.ts` for examples. * - * @param body - What is evaluated. In body, `yield* result.safeUnwrap()` and - * `yield* resultAsync.safeUnwrap()` work as Rust's `result?` expression. - * @returns The first occurence of either an yielded Err or a returned Result. + * @param body - What is evaluated. In body, `yield* result` and + * `yield* resultAsync` work as Rust's `result?` expression. + * @returns The first occurrence of either an yielded Err or a returned Result. */ export function safeTry( body: () => AsyncGenerator, Result>, @@ -261,6 +259,15 @@ interface IResult { match(ok: (t: T) => A, err: (e: E) => B): A | B /** + * @deprecated will be removed in 9.0.0. + * + * You can use `safeTry` without this method. + * @example + * ```typescript + * safeTry(function* () { + * const okValue = yield* yourResult + * }) + * ``` * Emulates Rust's `?` operator in `safeTry`'s body. See also `safeTry`. */ safeUnwrap(): Generator, T> From 3aee20a1c429062d26f440fde32a3f26ef05533a Mon Sep 17 00:00:00 2001 From: m-shaka Date: Thu, 24 Oct 2024 09:53:35 +0900 Subject: [PATCH 2/2] Create tough-rice-eat.md --- .changeset/tough-rice-eat.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/tough-rice-eat.md diff --git a/.changeset/tough-rice-eat.md b/.changeset/tough-rice-eat.md new file mode 100644 index 00000000..02b4fd66 --- /dev/null +++ b/.changeset/tough-rice-eat.md @@ -0,0 +1,5 @@ +--- +"neverthrow": patch +--- + +docs: updated README.md about `safeTry` and added @deprecated tag to safeUnwrap