Merge pull request #600 from supermacro/update-docs-about-safeTry

docs: update docs about safeTry

.changeset/tough-rice-eat.md

@@ -0,0 +1,5 @@
+---
+"neverthrow": patch
+---
+
+docs: updated README.md about `safeTry` and added @deprecated tag to safeUnwrap

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<number, string> {
             // 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<Result<number, string>> {
         return ok(
             // You have to await if the expression is Promise<Result>
             (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}`))
         )
     })
 }

src/result-async.ts

@@ -192,6 +192,15 @@ export class ResultAsync<T, E> implements PromiseLike<Result<T, E>> {
   }
 
   /**
+   * @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<Err<never, E>, T> {

src/result.ts

@@ -73,13 +73,12 @@ export function err<T = never, E = unknown>(err: E): Err<T, E> {
  * 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<T, E>(body: () => Generator<Err<never, E>, Result<T, E>>): Result<T, E>
 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<T, E>(
   body: () => AsyncGenerator<Err<never, E>, Result<T, E>>,
@@ -261,6 +259,15 @@ interface IResult<T, E> {
   match<A, B = A>(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<Err<never, E>, T>