diff --git a/packages/resulto/src/result.ts b/packages/resulto/src/result.ts index f9945a2..67dedc9 100644 --- a/packages/resulto/src/result.ts +++ b/packages/resulto/src/result.ts @@ -39,9 +39,13 @@ export interface ResultDeclarations { map(f: Fn): Result /** - * Works similar to the {@link ResultDeclarations.map|map} method, except - * that this method returns `AsyncResult` instead of `Result`, and the - * function `f` has to return `Promise`. + * Maps an `AsyncResult` to `AsyncResult` by applying a function + * `f` to a contained `Ok` value, leaving an `Err` value untouched. + * + * This function can be used to compose the results of two functions. + * + * Use this method instead of {@link ResultDeclarations.map} when the provided + * `f` returns promise. */ asyncMap(f: Fn>): AsyncResult @@ -52,9 +56,11 @@ export interface ResultDeclarations { mapOr(value: U, f: Fn): U /** - * Works similar to the {@link ResultDeclarations.mapOr|mapOr} method, except - * that this method returns `Promise`, and the function `f` has to return - * `Promise`. + * Returns the provided `value` (if `Err`), or applies a function to the + * contained value (if `Ok`). + * + * Use this method instead of {@link ResultDeclarations.mapOr} when the + * provided `f` returns promise. */ asyncMapOr(value: U, f: Fn>): Promise @@ -68,9 +74,15 @@ export interface ResultDeclarations { mapOrElse(fallbackFn: ErrFn, f: Fn): U /** - * Works similar to the {@link ResultDeclarations.mapOrElse|mapOrElse} method, - * except that this method returns `Promise`, and functions `fallbackFn` and - * `f` can return `Promise`. + * Maps an `AsyncResult` to `Promise` by applying function + * `fallbackFn` to a contained `Err` value, or function `f` to a contained + * `Ok` value. + * + * This function can be used to unpack a successful result while handling an + * error. + * + * Use this method instead of {@link ResultDeclarations.mapOrElse} when the + * provided `fallbackFn` or `f` return promise. */ asyncMapOrElse( fallbackFn: ErrFn>, @@ -87,9 +99,14 @@ export interface ResultDeclarations { mapErr(f: ErrFn): Result /** - * Works similar to the {@link ResultDeclarations.mapErr|mapErr} method, - * except that this method returns `AsyncResult` instead of `Result`, and the - * function `f` has to return `Promise`. + * Maps an `AsyncResult` to `AsyncResult` by applying a function + * to a contained `Err` value, leaving an `Ok` value untouched. + * + * This function can be used to pass through a successful result while + * handling an error. + * + * Use this method instead of {@link ResultDeclarations.mapErr} when the + * provided `f` returns promise. */ asyncMapErr(f: ErrFn>): AsyncResult @@ -151,9 +168,12 @@ export interface ResultDeclarations { andThen(f: Fn>): Result /** - * Works similar to the {@link ResultDeclarations.andThen|andThen} method, - * except that this method returns `AsyncResult` instead of `Result`, and the - * function `f` has to return `Promise`. + * Calls `f` if the result is `Ok`, otherwise returns the `Err` value. + * + * This function can be used for control flow based on `AsyncResult` values. + * + * Use this method instead of {@link ResultDeclarations.andThen} when the + * provided `f` returns promise. */ asyncAndThen(f: Fn>>): AsyncResult @@ -165,14 +185,17 @@ export interface ResultDeclarations { /** * Calls `f` if the result is `Err`, otherwise returns the `Ok` value. * - * This function can be used for control flow based on result values. + * This function can be used for control flow based on `Result` values. */ orElse(f: ErrFn>): Result /** - * Works similar to the {@link ResultDeclarations.orElse|orElse} method, - * except that this method returns `AsyncResult` instead of `Result`, and the - * function `f` has to return `Promise`. + * Calls `f` if the result is `Err`, otherwise returns the `Ok` value. + * + * This function can be used for control flow based on `AsyncResult` values. + * + * Use this method instead of {@link ResultDeclarations.orElse} when the + * provided `f` returns promise. */ asyncOrElse(f: ErrFn>>): AsyncResult @@ -187,9 +210,10 @@ export interface ResultDeclarations { unwrapOrElse(f: ErrFn): U | T /** - * Works similar to the {@link ResultDeclarations.unwrapOrElse|unwrapOrElse} - * method, except that this method returns `Promise`, and the function `f` - * has to return `Promise`. + * Returns the contained `Ok `value or computes it from a `f`. + * + * Use this method instead of {@link ResultDeclarations.unwrapOrElse} when the + * provided `f` returns promise. */ asyncUnwrapOrElse(f: ErrFn>): Promise @@ -201,9 +225,12 @@ export interface ResultDeclarations { match(okFn: Fn, errFn: ErrFn): U /** - * Works similar to the {@link ResultDeclarations.match|match} method, except - * that this method returns `Promise`, and functions `okFn` and `errFn` can - * return `Promise`. + * Calls `okFn` if the result is `Ok`, otherwise calls `errFn`. + * + * Both `okFn` and `errFn` must have the same return type. + * + * Use this method instead of {@link ResultDeclarations.match} when the + * provided `okFn` or `errFn` return promise. */ asyncMatch( okFn: Fn>, @@ -225,6 +252,8 @@ export type Result = Ok | Err * * In fact this is just a regular `Result` wrapped in a proxy to allow chaining * promises without using `await` on every call. + * + * @augments ResultDeclarations */ export type AsyncResult = { // We have to duplicate declarations due to the TypeScript limitations. @@ -234,42 +263,80 @@ export type AsyncResult = { // Reference: https://github.com/sindresorhus/type-fest/issues/178 /** - * @see {@link ResultDeclarations.map} for details. + * Maps an `AsyncResult` to `AsyncResult` by applying a function + * `f` to a contained `Ok` value, leaving an `Err` value untouched. + * + * This function can be used to compose the results of two functions. */ map(f: Fn): AsyncResult /** - * @see {@link ResultDeclarations.asyncMap} for details. + * Maps an `AsyncResult` to `AsyncResult` by applying a function + * `f` to a contained `Ok` value, leaving an `Err` value untouched. + * + * This function can be used to compose the results of two functions. + * + * Use this method instead of {@link AsyncResult.map} when the provided `f` + * returns promise. */ asyncMap(f: Fn>): AsyncResult /** - * @see {@link ResultDeclarations.mapErr} for details. + * Maps an `AsyncResult` to `AsyncResult` by applying a function + * to a contained `Err` value, leaving an `Ok` value untouched. + * + * This function can be used to pass through a successful result while + * handling an error. */ mapErr(f: ErrFn): AsyncResult /** - * @see {@link ResultDeclarations.asyncMapErr} for details. + * Maps an `AsyncResult` to `AsyncResult` by applying a function + * to a contained `Err` value, leaving an `Ok` value untouched. + * + * This function can be used to pass through a successful result while + * handling an error. + * + * Use this method instead of {@link AsyncResult.mapErr} when the provided `f` + * returns promise. */ asyncMapErr(f: ErrFn>): AsyncResult /** - * @see {@link ResultDeclarations.mapOr} for details. + * Returns the provided `value` (if `Err`), or applies a function to the + * contained value (if `Ok`). */ mapOr(value: U, f: Fn): Promise /** - * @see {@link ResultDeclarations.asyncMapOr} for details. + * Returns the provided `value` (if `Err`), or applies a function to the + * contained value (if `Ok`). + * + * Use this method instead of {@link AsyncResult.mapOr} when the provided `f` + * returns promise. */ asyncMapOr(value: U, f: Fn>): Promise /** - * @see {@link ResultDeclarations.mapOrElse} for details. + * Maps an `AsyncResult` to `Promise` by applying function + * `fallbackFn` to a contained `Err` value, or function `f` to a contained + * `Ok` value. + * + * This function can be used to unpack a successful result while handling an + * error. */ mapOrElse(fallbackFn: ErrFn, f: Fn): Promise /** - * @see {@link ResultDeclarations.asyncMapOrElse} for details. + * Maps an `AsyncResult` to `Promise` by applying function + * `fallbackFn` to a contained `Err` value, or function `f` to a contained + * `Ok` value. + * + * This function can be used to unpack a successful result while handling an + * error. + * + * Use this method instead of {@link AsyncResult.mapOrElse} when the provided + * `fallbackFn` or `f` return promise. */ asyncMapOrElse( fallbackFn: ErrFn>, @@ -277,92 +344,131 @@ export type AsyncResult = { ): Promise /** - * @see {@link ResultDeclarations.inspect} for details. + * Calls the provided function `f` with the contained value (if `Ok`). */ inspect(f: Fn): AsyncResult /** - * @see {@link ResultDeclarations.inspectErr} for details. + * Calls the provided function `f` with the contained error (if `Err`). */ inspectErr(f: ErrFn): AsyncResult /** - * @see {@link ResultDeclarations.tap} for details. + * Performs a side effect on the contained value (if `Ok`). + * + * NOTE: `f` is awaited. */ tap(f: Fn>): AsyncResult /** - * @see {@link ResultDeclarations.expect} for details. + * Returns the contained `Ok` value. + * + * This function may throw `UnwrapError` (if `Err`). */ expect(msg: string): Promise /** - * @see {@link ResultDeclarations.unwrap} for details. + * Returns the contained `Ok` value. + * + * This function may throw `UnwrapError` (if `Err`). */ unwrap(): Promise /** - * @see {@link ResultDeclarations.expectErr} for details. + * Returns the contained `Err` value. + * + * This function may throw `UnwrapError` (if `Ok`). */ expectErr(msg: string): Promise /** - * @see {@link ResultDeclarations.unwrapErr} for details. + * Returns the contained `Err` value. + * + * This function may throw `UnwrapError` (if `Ok`). */ unwrapErr(): Promise /** - * @see {@link ResultDeclarations.and} for details. + * Returns `res` if the result is `Ok`, otherwise returns the `Err` value. */ and(res: Result): AsyncResult /** - * @see {@link ResultDeclarations.andThen} for details. + * Calls `f` if the result is `Ok`, otherwise returns the `Err` value. + * + * This function can be used for control flow based on `AsyncResult` values. */ andThen(f: Fn>): AsyncResult /** - * @see {@link ResultDeclarations.asyncAndThen} for details. + * Calls `f` if the result is `Ok`, otherwise returns the `Err` value. + * + * This function can be used for control flow based on `AsyncResult` values. + * + * Use this method instead of {@link AsyncResult.andThen} when the provided + * `f` returns promise. */ asyncAndThen(f: Fn>>): AsyncResult /** - * @see {@link ResultDeclarations.or} for details. + * Returns `res` if the result is `Err`, otherwise returns the `Ok` value. */ or(res: Result): AsyncResult /** - * @see {@link ResultDeclarations.orElse} for details. + * Calls `f` if the result is `Err`, otherwise returns the `Ok` value. + * + * This function can be used for control flow based on `AsyncResult` values. */ orElse(f: ErrFn>): AsyncResult /** - * @see {@link ResultDeclarations.asyncOrElse} for details. + * Calls `f` if the result is `Err`, otherwise returns the `Ok` value. + * + * This function can be used for control flow based on `AsyncResult` values. + * + * Use this method instead of {@link AsyncResult.orElse} when the provided `f` + * returns promise. */ asyncOrElse(f: ErrFn>>): AsyncResult /** - * @see {@link ResultDeclarations.unwrapOr} for details. + * Returns the contained `Ok` value or a provided `value`. */ unwrapOr(value: U): Promise /** - * @see {@link ResultDeclarations.unwrapOrElse} for details. + * Calls `f` if the result is `Err`, otherwise returns the `Ok` value. + * + * This function can be used for control flow based on `AsyncResult` values. + * + * Use this method instead of {@link AsyncResult.orElse} when the provided `f` + * returns promise. */ unwrapOrElse(f: ErrFn): Promise /** - * @see {@link ResultDeclarations.asyncUnwrapOrElse} for details. + * Returns the contained `Ok `value or computes it from a `f`. + * + * Use this method instead of {@link AsyncResult.unwrapOrElse} when the + * provided `f` returns promise. */ asyncUnwrapOrElse(f: ErrFn>): Promise /** - * @see {@link ResultDeclarations.match} for details. + * Calls `okFn` if the result is `Ok`, otherwise calls `errFn`. + * + * Both `okFn` and `errFn` must have the same return type. */ match(okFn: Fn, errFn: ErrFn): Promise /** - * @see {@link ResultDeclarations.asyncMatch} for details. + * Calls `okFn` if the result is `Ok`, otherwise calls `errFn`. + * + * Both `okFn` and `errFn` must have the same return type. + * + * Use this method instead of {@link AsyncResult.match} when the provided + * `okFn` or `errFn` return promise. */ asyncMatch( okFn: Fn>,