Skip to content

docs: update docs about safeTry #600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 24, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/tough-rice-eat.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"neverthrow": patch
---

docs: updated README.md about `safeTry` and added @deprecated tag to safeUnwrap
16 changes: 6 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -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}`))
)
})
}
9 changes: 9 additions & 0 deletions src/result-async.ts
Original file line number Diff line number Diff line change
@@ -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> {
25 changes: 16 additions & 9 deletions src/result.ts
Original file line number Diff line number Diff line change
@@ -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>