@sapphire/result 2.8.0-next.f3515ea3 → 2.8.1-next.36867aa4

package/dist/cjs/index.d.cts

@@ -3,6 +3,7 @@ type If<Value extends boolean, TrueResult, FalseResult> = Value extends true ? T
 
 declare const ValueProperty$1: unique symbol;
 declare const SuccessProperty: unique symbol;
+declare const UnwrapSafeProperty: unique symbol;
 /**
  * A type used to express computations that can fail, it can be used for returning and propagating errors. This is a
  * type union with the variants `Ok(T)`, representing success and containing a value, and `Err(E)`, representing error
@@ -441,6 +442,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOrElse}
      * @seealso {@link unwrapErr}
      * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
      *
      * @example
      * ```typescript
@@ -468,6 +470,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOr}
      * @seealso {@link unwrapOrElse}
      * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
      *
      * @example
      * ```typescript
@@ -496,6 +499,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOrElse}
      * @seealso {@link unwrapErr}
      * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
      *
      * @param defaultValue The default value.
      *
@@ -519,6 +523,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOr}
      * @seealso {@link unwrapErr}
      * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
      *
      * @param op The predicate.
      *
@@ -541,6 +546,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOr}
      * @seealso {@link unwrapOrElse}
      * @seealso {@link unwrapErr}
+     * @seealso {@link unwrapSafe}
      *
      * @example
      * ```typescript
@@ -558,6 +564,20 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * ```
      */
     unwrapRaw(): If<Success, T, never>;
+    /**
+     * Returns the contained `Ok` value or yelds the contained `Err` value.
+     * Emulates Rust's `?` operator in `safeTry`'s body. See also {@link Result.safeTry}.
+     *
+     * If used outside of a `safeTry`'s' body, throws the contained error.
+     * @seealso {@link unwrap}
+     * @seealso {@link unwrapOr}
+     * @seealso {@link unwrapErr}
+     * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
+     *
+     * @see {@link https://doc.rust-lang.org/std/result/enum.Result.html#method.unwrap_safe}
+     */
+    unwrapSafe(): Generator<Err<E, T>, T>;
     /**
      * Returns `result` if the result is `Ok`, otherwise returns the `Err` value of itself.
      * @param result The result to check.
@@ -839,6 +859,14 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      */
     [Symbol.iterator](): Generator<T>;
     get [Symbol.toStringTag](): If<Success, 'Ok', 'Err'>;
+    /**
+     * This function, in combination with `[$]`, is intended to emulate
+     * Rust's ? operator.
+     *
+     * @see {@link Result.safeTry}
+     * @see {@link https://doc.rust-lang.org/std/result/enum.Result.html#method.safeTry}
+     */
+    get [UnwrapSafeProperty](): Generator<Err<E, T>, T>;
     static ok<T = undefined, E = any>(this: void, value?: T): Ok<T, E>;
     static err<E = undefined, T = any>(this: void, value?: E): Err<E, T>;
     /**
@@ -919,6 +947,88 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @returns A new {@link Result}.
      */
     static any<const Entries extends readonly AnyResult[]>(this: void, results: Entries): Result<UnwrapOk<Entries[number]>, UnwrapErrArray<Entries>>;
+    /**
+     * Evaluates the given generator to a Result returned or an Err yielded from it,
+     * whichever comes first.
+     *
+     * This function, in combination with `[$]`, is intended to emulate
+     * Rust's ? operator.
+     *
+     * @example
+     * ```typescript
+     *	const result = Result.safeTry(function* ({ $ }) {
+     *	  const first = yield* ok(1)[$];
+     *	  const second = yield* ok(1)[$];
+     *
+     *	  return ok(first + second);
+     *  });
+     *
+     *	result.match({
+     *	  ok: (value) => value, // 2
+     *	  err: (error) => {}
+     *	});
+     *```
+     *
+     * @example
+     * ```typescript
+     *	const resultAsync = Result.safeTry(async function* ({ $async }) {
+     *	  const first = yield* $async(Result.fromAsync(() => Promise.resolve(1)));
+     *	  const second = yield* ok(1)[$];
+     *
+     *	  return ok(first + second);
+     *  });
+     *
+     *	resultAsync.match({
+     *	  ok: (value) => value, // 2
+     *	  err: (error) => {}
+     *	});
+     * ```
+     * @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.
+     */
+    static safeTry<T, E>(body: (options: SafeTryOptions) => Generator<Err<E>, Result<T, E>>): Result<T, E>;
+    /**
+     * Evaluates the given generator to a Result returned or an Err yielded from it,
+     * whichever comes first.
+     *
+     * This function, in combination with `[$]`, is intended to emulate
+     * Rust's ? operator.
+     *
+     * @example
+     * ```typescript
+     *	const result = Result.safeTry(function* ({ $ }) {
+     *	  const first = yield* ok(1)[$];
+     *	  const second = yield* ok(1)[$];
+     *
+     *	  return ok(first + second);
+     *  });
+     *
+     *	result.match({
+     *	  ok: (value) => value, // 2
+     *	  err: (error) => {}
+     *	});
+     *```
+     *
+     * @example
+     * ```typescript
+     *	const resultAsync = Result.safeTry(async function* ({ $async }) {
+     *	  const first = yield* $async(Result.fromAsync(() => Promise.resolve(1)));
+     *	  const second = yield* ok(1)[$];
+     *
+     *	  return ok(first + second);
+     *  });
+     *
+     *	resultAsync.match({
+     *	  ok: (value) => value, // 2
+     *	  err: (error) => {}
+     *	});
+     * ```
+     * @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.
+     */
+    static safeTry<T, E>(body: (options: SafeTryOptions) => AsyncGenerator<Err<E>, Result<T, E>>): Promise<Result<T, E>>;
 }
 declare namespace Result {
     type Ok<T, E = any> = Result<T, E, true>;
@@ -944,6 +1054,10 @@ type UnwrapOk<T extends AnyResult> = Result.UnwrapOk<T>;
 type UnwrapErr<T extends AnyResult> = Result.UnwrapErr<T>;
 type UnwrapOkArray<T extends readonly AnyResult[] | []> = Result.UnwrapOkArray<T>;
 type UnwrapErrArray<T extends readonly AnyResult[] | []> = Result.UnwrapErrArray<T>;
+interface SafeTryOptions {
+    $: typeof UnwrapSafeProperty;
+    $async: <T, E>(result: Promise<Result<T, E>>) => AsyncGenerator<Err<E>, T>;
+}
 
 declare const ValueProperty: unique symbol;
 declare const ExistsProperty: unique symbol;
@@ -1793,4 +1907,4 @@ declare class ResultError<E> extends Error {
     get name(): string;
 }
 
-export { type AnyOption, type AnyResult, type Err, type None, type Ok, Option, OptionError, type OptionResolvable, Result, ResultError, type ResultResolvable, type Some, type UnwrapErr, type UnwrapErrArray, type UnwrapOk, type UnwrapOkArray, type UnwrapSome, type UnwrapSomeArray, err, none, ok, some };
+export { type AnyOption, type AnyResult, type Err, type None, type Ok, Option, OptionError, type OptionResolvable, Result, ResultError, type ResultResolvable, type SafeTryOptions, type Some, type UnwrapErr, type UnwrapErrArray, type UnwrapOk, type UnwrapOkArray, type UnwrapSome, type UnwrapSomeArray, err, none, ok, some };

package/dist/esm/index.d.mts

@@ -3,6 +3,7 @@ type If<Value extends boolean, TrueResult, FalseResult> = Value extends true ? T
 
 declare const ValueProperty$1: unique symbol;
 declare const SuccessProperty: unique symbol;
+declare const UnwrapSafeProperty: unique symbol;
 /**
  * A type used to express computations that can fail, it can be used for returning and propagating errors. This is a
  * type union with the variants `Ok(T)`, representing success and containing a value, and `Err(E)`, representing error
@@ -441,6 +442,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOrElse}
      * @seealso {@link unwrapErr}
      * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
      *
      * @example
      * ```typescript
@@ -468,6 +470,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOr}
      * @seealso {@link unwrapOrElse}
      * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
      *
      * @example
      * ```typescript
@@ -496,6 +499,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOrElse}
      * @seealso {@link unwrapErr}
      * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
      *
      * @param defaultValue The default value.
      *
@@ -519,6 +523,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOr}
      * @seealso {@link unwrapErr}
      * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
      *
      * @param op The predicate.
      *
@@ -541,6 +546,7 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @seealso {@link unwrapOr}
      * @seealso {@link unwrapOrElse}
      * @seealso {@link unwrapErr}
+     * @seealso {@link unwrapSafe}
      *
      * @example
      * ```typescript
@@ -558,6 +564,20 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * ```
      */
     unwrapRaw(): If<Success, T, never>;
+    /**
+     * Returns the contained `Ok` value or yelds the contained `Err` value.
+     * Emulates Rust's `?` operator in `safeTry`'s body. See also {@link Result.safeTry}.
+     *
+     * If used outside of a `safeTry`'s' body, throws the contained error.
+     * @seealso {@link unwrap}
+     * @seealso {@link unwrapOr}
+     * @seealso {@link unwrapErr}
+     * @seealso {@link unwrapRaw}
+     * @seealso {@link unwrapSafe}
+     *
+     * @see {@link https://doc.rust-lang.org/std/result/enum.Result.html#method.unwrap_safe}
+     */
+    unwrapSafe(): Generator<Err<E, T>, T>;
     /**
      * Returns `result` if the result is `Ok`, otherwise returns the `Err` value of itself.
      * @param result The result to check.
@@ -839,6 +859,14 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      */
     [Symbol.iterator](): Generator<T>;
     get [Symbol.toStringTag](): If<Success, 'Ok', 'Err'>;
+    /**
+     * This function, in combination with `[$]`, is intended to emulate
+     * Rust's ? operator.
+     *
+     * @see {@link Result.safeTry}
+     * @see {@link https://doc.rust-lang.org/std/result/enum.Result.html#method.safeTry}
+     */
+    get [UnwrapSafeProperty](): Generator<Err<E, T>, T>;
     static ok<T = undefined, E = any>(this: void, value?: T): Ok<T, E>;
     static err<E = undefined, T = any>(this: void, value?: E): Err<E, T>;
     /**
@@ -919,6 +947,88 @@ declare class Result<T, E, const Success extends boolean = boolean> {
      * @returns A new {@link Result}.
      */
     static any<const Entries extends readonly AnyResult[]>(this: void, results: Entries): Result<UnwrapOk<Entries[number]>, UnwrapErrArray<Entries>>;
+    /**
+     * Evaluates the given generator to a Result returned or an Err yielded from it,
+     * whichever comes first.
+     *
+     * This function, in combination with `[$]`, is intended to emulate
+     * Rust's ? operator.
+     *
+     * @example
+     * ```typescript
+     *	const result = Result.safeTry(function* ({ $ }) {
+     *	  const first = yield* ok(1)[$];
+     *	  const second = yield* ok(1)[$];
+     *
+     *	  return ok(first + second);
+     *  });
+     *
+     *	result.match({
+     *	  ok: (value) => value, // 2
+     *	  err: (error) => {}
+     *	});
+     *```
+     *
+     * @example
+     * ```typescript
+     *	const resultAsync = Result.safeTry(async function* ({ $async }) {
+     *	  const first = yield* $async(Result.fromAsync(() => Promise.resolve(1)));
+     *	  const second = yield* ok(1)[$];
+     *
+     *	  return ok(first + second);
+     *  });
+     *
+     *	resultAsync.match({
+     *	  ok: (value) => value, // 2
+     *	  err: (error) => {}
+     *	});
+     * ```
+     * @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.
+     */
+    static safeTry<T, E>(body: (options: SafeTryOptions) => Generator<Err<E>, Result<T, E>>): Result<T, E>;
+    /**
+     * Evaluates the given generator to a Result returned or an Err yielded from it,
+     * whichever comes first.
+     *
+     * This function, in combination with `[$]`, is intended to emulate
+     * Rust's ? operator.
+     *
+     * @example
+     * ```typescript
+     *	const result = Result.safeTry(function* ({ $ }) {
+     *	  const first = yield* ok(1)[$];
+     *	  const second = yield* ok(1)[$];
+     *
+     *	  return ok(first + second);
+     *  });
+     *
+     *	result.match({
+     *	  ok: (value) => value, // 2
+     *	  err: (error) => {}
+     *	});
+     *```
+     *
+     * @example
+     * ```typescript
+     *	const resultAsync = Result.safeTry(async function* ({ $async }) {
+     *	  const first = yield* $async(Result.fromAsync(() => Promise.resolve(1)));
+     *	  const second = yield* ok(1)[$];
+     *
+     *	  return ok(first + second);
+     *  });
+     *
+     *	resultAsync.match({
+     *	  ok: (value) => value, // 2
+     *	  err: (error) => {}
+     *	});
+     * ```
+     * @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.
+     */
+    static safeTry<T, E>(body: (options: SafeTryOptions) => AsyncGenerator<Err<E>, Result<T, E>>): Promise<Result<T, E>>;
 }
 declare namespace Result {
     type Ok<T, E = any> = Result<T, E, true>;
@@ -944,6 +1054,10 @@ type UnwrapOk<T extends AnyResult> = Result.UnwrapOk<T>;
 type UnwrapErr<T extends AnyResult> = Result.UnwrapErr<T>;
 type UnwrapOkArray<T extends readonly AnyResult[] | []> = Result.UnwrapOkArray<T>;
 type UnwrapErrArray<T extends readonly AnyResult[] | []> = Result.UnwrapErrArray<T>;
+interface SafeTryOptions {
+    $: typeof UnwrapSafeProperty;
+    $async: <T, E>(result: Promise<Result<T, E>>) => AsyncGenerator<Err<E>, T>;
+}
 
 declare const ValueProperty: unique symbol;
 declare const ExistsProperty: unique symbol;
@@ -1793,4 +1907,4 @@ declare class ResultError<E> extends Error {
     get name(): string;
 }
 
-export { type AnyOption, type AnyResult, type Err, type None, type Ok, Option, OptionError, type OptionResolvable, Result, ResultError, type ResultResolvable, type Some, type UnwrapErr, type UnwrapErrArray, type UnwrapOk, type UnwrapOkArray, type UnwrapSome, type UnwrapSomeArray, err, none, ok, some };
+export { type AnyOption, type AnyResult, type Err, type None, type Ok, Option, OptionError, type OptionResolvable, Result, ResultError, type ResultResolvable, type SafeTryOptions, type Some, type UnwrapErr, type UnwrapErrArray, type UnwrapOk, type UnwrapOkArray, type UnwrapSome, type UnwrapSomeArray, err, none, ok, some };

package/dist/esm/index.mjs

@@ -39,6 +39,7 @@ var ResultError = _ResultError;
 // src/lib/Result.ts
 var ValueProperty = Symbol.for("@sapphire/result:Result.value");
 var SuccessProperty = Symbol.for("@sapphire/result:Result.success");
+var UnwrapSafeProperty = Symbol.for("@sapphire/result:Result.safeUnwrap");
 var _a, _b;
 var _Result = class _Result {
   constructor(value, success) {
@@ -465,6 +466,7 @@ var _Result = class _Result {
    * @seealso {@link unwrapOrElse}
    * @seealso {@link unwrapErr}
    * @seealso {@link unwrapRaw}
+   * @seealso {@link unwrapSafe}
    *
    * @example
    * ```typescript
@@ -495,6 +497,7 @@ var _Result = class _Result {
    * @seealso {@link unwrapOr}
    * @seealso {@link unwrapOrElse}
    * @seealso {@link unwrapRaw}
+   * @seealso {@link unwrapSafe}
    *
    * @example
    * ```typescript
@@ -526,6 +529,7 @@ var _Result = class _Result {
    * @seealso {@link unwrapOrElse}
    * @seealso {@link unwrapErr}
    * @seealso {@link unwrapRaw}
+   * @seealso {@link unwrapSafe}
    *
    * @param defaultValue The default value.
    *
@@ -551,6 +555,7 @@ var _Result = class _Result {
    * @seealso {@link unwrapOr}
    * @seealso {@link unwrapErr}
    * @seealso {@link unwrapRaw}
+   * @seealso {@link unwrapSafe}
    *
    * @param op The predicate.
    *
@@ -575,6 +580,7 @@ var _Result = class _Result {
    * @seealso {@link unwrapOr}
    * @seealso {@link unwrapOrElse}
    * @seealso {@link unwrapErr}
+   * @seealso {@link unwrapSafe}
    *
    * @example
    * ```typescript
@@ -595,6 +601,26 @@ var _Result = class _Result {
     if (this.isErr()) throw this[ValueProperty];
     return this[ValueProperty];
   }
+  /**
+   * Returns the contained `Ok` value or yelds the contained `Err` value.
+   * Emulates Rust's `?` operator in `safeTry`'s body. See also {@link Result.safeTry}.
+   *
+   * If used outside of a `safeTry`'s' body, throws the contained error.
+   * @seealso {@link unwrap}
+   * @seealso {@link unwrapOr}
+   * @seealso {@link unwrapErr}
+   * @seealso {@link unwrapRaw}
+   * @seealso {@link unwrapSafe}
+   *
+   * @see {@link https://doc.rust-lang.org/std/result/enum.Result.html#method.unwrap_safe}
+   */
+  *unwrapSafe() {
+    if (this.isOk()) {
+      return this[ValueProperty];
+    }
+    yield this;
+    throw new ResultError("Should not be used outside of a safe try generator", this[ValueProperty]);
+  }
   /**
    * Returns `result` if the result is `Ok`, otherwise returns the `Err` value of itself.
    * @param result The result to check.
@@ -869,6 +895,16 @@ var _Result = class _Result {
   get [Symbol.toStringTag]() {
     return this.match({ ok: /* @__PURE__ */ __name(() => "Ok", "ok"), err: /* @__PURE__ */ __name(() => "Err", "err") });
   }
+  /**
+   * This function, in combination with `[$]`, is intended to emulate
+   * Rust's ? operator.
+   *
+   * @see {@link Result.safeTry}
+   * @see {@link https://doc.rust-lang.org/std/result/enum.Result.html#method.safeTry}
+   */
+  get [UnwrapSafeProperty]() {
+    return this.unwrapSafe();
+  }
   // eslint-disable-next-line @typescript-eslint/no-invalid-void-type
   static ok(value) {
     return new _Result(value, true);
@@ -988,6 +1024,13 @@ var _Result = class _Result {
     }
     return err(errors);
   }
+  static safeTry(body) {
+    const n = body({ $: UnwrapSafeProperty, $async: unwrapSafeAsync }).next();
+    if (n instanceof Promise) {
+      return n.then((r) => r.value);
+    }
+    return n.value;
+  }
 };
 __name(_Result, "Result");
 var Result = _Result;
@@ -996,6 +1039,11 @@ function resolve(value) {
   return Result.isResult(value) ? value : ok(value);
 }
 __name(resolve, "resolve");
+async function* unwrapSafeAsync(result) {
+  const _result = await result;
+  return yield* _result.unwrapSafe();
+}
+__name(unwrapSafeAsync, "unwrapSafeAsync");
 
 // src/lib/Option.ts
 var ValueProperty2 = Symbol.for("@sapphire/result:Option.value");