@fgv/ts-utils 5.1.0-11 → 5.1.0-12

package/README.md

@@ -56,6 +56,27 @@ function processData(input: string): Result<ProcessedData> {
 }
 ```
 
+### Async Chaining
+
+Use `thenOnSuccess()` to chain async operations without breaking the fluent style:
+
+```typescript
+import { Result, succeed, captureAsyncResult } from '@fgv/ts-utils';
+
+async function processData(input: string): Promise<Result<SavedData>> {
+  return parseInput(input)
+    .onSuccess((parsed) => validate(parsed))
+    .thenOnSuccess(async (valid) => fetchRelatedData(valid.id))
+    .onSuccess((data) => transform(data))
+    .thenOnSuccess(async (transformed) => saveData(transformed))
+    .withErrorFormat((msg) => `pipeline failed: ${msg}`);
+}
+```
+
+`AsyncResult<T>` implements `PromiseLike`, so the entire chain can be directly `await`ed. Rejected promises are caught and converted to `Failure`.
+
+[Full async chaining documentation &rarr;](./src/packlets/base/README.md#async-result-chaining)
+
 ### Error Context
 
 ```typescript

package/dist/packlets/base/result.js

@@ -101,6 +101,26 @@ export class Success {
     onFailure(__) {
         return this;
     }
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess(cb) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return new AsyncResult(cb(this._value));
+        }
+        catch (err) {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return AsyncResult.from(fail(_errorMessage(err)));
+        }
+    }
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(__) {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        return AsyncResult.from(this);
+    }
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -226,6 +246,26 @@ export class Failure {
     onFailure(cb) {
         return cb(this._message);
     }
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess(__) {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        return AsyncResult.from(fail(this._message));
+    }
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(cb) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return new AsyncResult(cb(this._message));
+        }
+        catch (err) {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return AsyncResult.from(fail(_errorMessage(err)));
+        }
+    }
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -591,13 +631,25 @@ export function propagateWithDetail(result, detail, successDetail) {
         ? succeedWithDetail(result.value, successDetail !== null && successDetail !== void 0 ? successDetail : detail)
         : failWithDetail(result.message, detail);
 }
+/**
+ * Extracts a message string from an unknown thrown/rejected value.
+ * @param err - The caught error value.
+ * @returns The error message string.
+ * @internal
+ */
+export function _errorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
 /**
  * Wraps a function which might throw to convert exception results
  * to {@link Failure}.
  * @param func - The function to be captured.
  * @returns Returns {@link Success} with a value of type `<T>` on
  * success , or {@link Failure} with the thrown error message if
- * `func` throws an `Error`.
+ * `func` throws an `Error` or string.
  * @public
  */
 export function captureResult(func) {
@@ -605,7 +657,180 @@ export function captureResult(func) {
         return succeed(func());
     }
     catch (err) {
-        return fail(err.message);
+        return fail(_errorMessage(err));
+    }
+}
+/**
+ * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both
+ * synchronous and asynchronous operations.
+ *
+ * @remarks
+ * `AsyncResult<T>` implements `PromiseLike` so it can be directly `await`ed.
+ * Use the `thenOnSuccess` and `thenOnFailure` methods on {@link Result} to bridge
+ * from synchronous to asynchronous result chains.
+ *
+ * @example
+ * ```typescript
+ * const result: Result<Final> = await parseInput(input)
+ *   .thenOnSuccess(async (parsed) => fetchData(parsed))
+ *   .onSuccess((data) => transform(data))
+ *   .thenOnSuccess(async (transformed) => saveData(transformed))
+ *   .withErrorFormat((msg) => `pipeline failed: ${msg}`);
+ * ```
+ *
+ * @public
+ */
+export class AsyncResult {
+    /**
+     * Constructs an {@link AsyncResult} wrapping the supplied promise.
+     * @remarks
+     * If the supplied promise rejects, the rejection is caught and converted
+     * to a {@link Failure}, ensuring that awaiting an {@link AsyncResult} always
+     * yields a {@link Result}.
+     * @param promise - A `Promise` that resolves to a {@link Result}.
+     */
+    constructor(promise) {
+        this._promise = promise.catch((err) => fail(_errorMessage(err)));
+    }
+    /**
+     * Calls a supplied {@link SuccessContinuation | success continuation} if
+     * the wrapped result is successful.
+     * @param cb - The synchronous {@link SuccessContinuation | success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onSuccess(cb) {
+        return new AsyncResult(this._promise.then((r) => r.onSuccess(cb)));
+    }
+    /**
+     * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+     * the wrapped result is successful.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncSuccessContinuation | async success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnSuccess(cb) {
+        return new AsyncResult(this._promise.then(async (r) => {
+            if (r.isFailure()) {
+                return fail(r.message);
+            }
+            try {
+                return await cb(r.value);
+            }
+            catch (err) {
+                return fail(_errorMessage(err));
+            }
+        }));
+    }
+    /**
+     * Calls a supplied {@link FailureContinuation | failure continuation} if
+     * the wrapped result is a failure.
+     * @param cb - The synchronous {@link FailureContinuation | failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onFailure(cb) {
+        return new AsyncResult(this._promise.then((r) => r.onFailure(cb)));
+    }
+    /**
+     * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+     * the wrapped result is a failure.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncFailureContinuation | async failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnFailure(cb) {
+        return new AsyncResult(this._promise.then(async (r) => {
+            if (r.isSuccess()) {
+                return r;
+            }
+            try {
+                return await cb(r.message);
+            }
+            catch (err) {
+                return fail(_errorMessage(err));
+            }
+        }));
+    }
+    /**
+     * Calls a supplied {@link ErrorFormatter | error formatter} if
+     * the wrapped result is a failure.
+     * @param cb - The {@link ErrorFormatter | error formatter} to
+     * be called in the event of failure.
+     * @returns A new {@link AsyncResult} with the formatted error message,
+     * or the original success result.
+     */
+    withErrorFormat(cb) {
+        return new AsyncResult(this._promise.then((r) => r.withErrorFormat(cb)));
+    }
+    /**
+     * Propagates the wrapped result, appending any error message to the
+     * supplied errors aggregator.
+     * @param errors - {@link IMessageAggregator | Error aggregator} in which
+     * errors will be aggregated.
+     * @param formatter - An optional {@link ErrorFormatter | error formatter}
+     * to be used to format the error message.
+     * @returns A new {@link AsyncResult} wrapping the result after aggregation.
+     */
+    aggregateError(errors, formatter) {
+        return new AsyncResult(this._promise.then((r) => {
+            r.aggregateError(errors, formatter);
+            return r;
+        }));
+    }
+    /**
+     * Reports the wrapped result to the supplied reporter.
+     * @param reporter - The {@link IResultReporter | reporter} to which the result
+     * will be reported.
+     * @param options - The {@link IResultReportOptions | options} for reporting the result.
+     * @returns A new {@link AsyncResult} wrapping the result after reporting.
+     */
+    report(reporter, options) {
+        return new AsyncResult(this._promise.then((r) => {
+            r.report(reporter, options);
+            return r;
+        }));
+    }
+    /**
+     * Implementation of `PromiseLike.then` enabling `await` on {@link AsyncResult}.
+     * @param onfulfilled - Callback invoked when the promise resolves.
+     * @param onrejected - Callback invoked when the promise rejects.
+     * @returns A `Promise` resolving to the callback result.
+     */
+    /* eslint-disable @rushstack/no-new-null */
+    then(onfulfilled, onrejected) {
+        /* eslint-enable @rushstack/no-new-null */
+        return this._promise.then(onfulfilled, onrejected);
+    }
+    /**
+     * Creates an {@link AsyncResult} from a {@link Result}.
+     * @param result - The {@link Result} to wrap.
+     * @returns A new {@link AsyncResult} wrapping the supplied result.
+     */
+    static from(result) {
+        return new AsyncResult(Promise.resolve(result));
+    }
+}
+/**
+ * Wraps an async function which might throw to convert exception results
+ * to {@link Failure}.
+ * @param func - The async function to be captured.
+ * @returns Returns a `Promise` of {@link Success} with a value of type `<T>` on
+ * success, or {@link Failure} with the thrown error message if `func` throws or rejects.
+ * @public
+ */
+export async function captureAsyncResult(func) {
+    try {
+        return succeed(await func());
+    }
+    catch (err) {
+        return fail(_errorMessage(err));
     }
 }
 //# sourceMappingURL=result.js.map

package/dist/ts-utils.d.ts

@@ -420,6 +420,131 @@ declare interface ArrayValidatorConstructorParams<T, TC = unknown> extends Valid
  */
 declare function asValidator<T, TC = unknown>(converterOrValidator: Converter<T, TC> | Validator<T, TC>): Validator<T, TC>;
 
+/**
+ * Async continuation callback to be called in the event that a
+ * {@link Result} fails, returning a `Promise` of a new {@link Result}.
+ * @public
+ */
+export declare type AsyncFailureContinuation<T> = (message: string) => Promise<Result<T>>;
+
+/**
+ * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both
+ * synchronous and asynchronous operations.
+ *
+ * @remarks
+ * `AsyncResult<T>` implements `PromiseLike` so it can be directly `await`ed.
+ * Use the `thenOnSuccess` and `thenOnFailure` methods on {@link Result} to bridge
+ * from synchronous to asynchronous result chains.
+ *
+ * @example
+ * ```typescript
+ * const result: Result<Final> = await parseInput(input)
+ *   .thenOnSuccess(async (parsed) => fetchData(parsed))
+ *   .onSuccess((data) => transform(data))
+ *   .thenOnSuccess(async (transformed) => saveData(transformed))
+ *   .withErrorFormat((msg) => `pipeline failed: ${msg}`);
+ * ```
+ *
+ * @public
+ */
+export declare class AsyncResult<T> implements PromiseLike<Result<T>> {
+    private readonly _promise;
+    /**
+     * Constructs an {@link AsyncResult} wrapping the supplied promise.
+     * @remarks
+     * If the supplied promise rejects, the rejection is caught and converted
+     * to a {@link Failure}, ensuring that awaiting an {@link AsyncResult} always
+     * yields a {@link Result}.
+     * @param promise - A `Promise` that resolves to a {@link Result}.
+     */
+    constructor(promise: Promise<Result<T>>);
+    /**
+     * Calls a supplied {@link SuccessContinuation | success continuation} if
+     * the wrapped result is successful.
+     * @param cb - The synchronous {@link SuccessContinuation | success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onSuccess<TN>(cb: SuccessContinuation<T, TN>): AsyncResult<TN>;
+    /**
+     * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+     * the wrapped result is successful.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncSuccessContinuation | async success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+    /**
+     * Calls a supplied {@link FailureContinuation | failure continuation} if
+     * the wrapped result is a failure.
+     * @param cb - The synchronous {@link FailureContinuation | failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onFailure(cb: FailureContinuation<T>): AsyncResult<T>;
+    /**
+     * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+     * the wrapped result is a failure.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncFailureContinuation | async failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;
+    /**
+     * Calls a supplied {@link ErrorFormatter | error formatter} if
+     * the wrapped result is a failure.
+     * @param cb - The {@link ErrorFormatter | error formatter} to
+     * be called in the event of failure.
+     * @returns A new {@link AsyncResult} with the formatted error message,
+     * or the original success result.
+     */
+    withErrorFormat(cb: ErrorFormatter): AsyncResult<T>;
+    /**
+     * Propagates the wrapped result, appending any error message to the
+     * supplied errors aggregator.
+     * @param errors - {@link IMessageAggregator | Error aggregator} in which
+     * errors will be aggregated.
+     * @param formatter - An optional {@link ErrorFormatter | error formatter}
+     * to be used to format the error message.
+     * @returns A new {@link AsyncResult} wrapping the result after aggregation.
+     */
+    aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter): AsyncResult<T>;
+    /**
+     * Reports the wrapped result to the supplied reporter.
+     * @param reporter - The {@link IResultReporter | reporter} to which the result
+     * will be reported.
+     * @param options - The {@link IResultReportOptions | options} for reporting the result.
+     * @returns A new {@link AsyncResult} wrapping the result after reporting.
+     */
+    report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): AsyncResult<T>;
+    /**
+     * Implementation of `PromiseLike.then` enabling `await` on {@link AsyncResult}.
+     * @param onfulfilled - Callback invoked when the promise resolves.
+     * @param onrejected - Callback invoked when the promise rejects.
+     * @returns A `Promise` resolving to the callback result.
+     */
+    then<TResult1 = Result<T>, TResult2 = never>(onfulfilled?: ((value: Result<T>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /**
+     * Creates an {@link AsyncResult} from a {@link Result}.
+     * @param result - The {@link Result} to wrap.
+     * @returns A new {@link AsyncResult} wrapping the supplied result.
+     */
+    static from<T>(result: Result<T>): AsyncResult<T>;
+}
+
+/**
+ * Async continuation callback to be called in the event that a
+ * {@link Result} is successful, returning a `Promise` of a new {@link Result}.
+ * @public
+ */
+export declare type AsyncSuccessContinuation<T, TN> = (value: T) => Promise<Result<TN>>;
+
 declare namespace Base {
     export {
         GenericValidatorConstructorParams,
@@ -778,13 +903,23 @@ declare class CacheInvalidatingResultMapWrapper<TK extends string, TSRC, TTARGET
     toReadOnly(): IReadOnlyResultMap<TK, TSRC>;
 }
 
+/**
+ * Wraps an async function which might throw to convert exception results
+ * to {@link Failure}.
+ * @param func - The async function to be captured.
+ * @returns Returns a `Promise` of {@link Success} with a value of type `<T>` on
+ * success, or {@link Failure} with the thrown error message if `func` throws or rejects.
+ * @public
+ */
+export declare function captureAsyncResult<T>(func: () => Promise<T>): Promise<Result<T>>;
+
 /**
  * Wraps a function which might throw to convert exception results
  * to {@link Failure}.
  * @param func - The function to be captured.
  * @returns Returns {@link Success} with a value of type `<T>` on
  * success , or {@link Failure} with the thrown error message if
- * `func` throws an `Error`.
+ * `func` throws an `Error` or string.
  * @public
  */
 export declare function captureResult<T>(func: () => T): Result<T>;
@@ -2070,6 +2205,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare type ErrorFormatter<TD = unknown> = (message: string, detail?: TD) => string;
 
+          /**
+           * Extracts a message string from an unknown thrown/rejected value.
+           * @param err - The caught error value.
+           * @returns The error message string.
+           * @internal
+           */
+          export declare function _errorMessage(err: unknown): string;
+
           /**
            * Returns {@link Failure | Failure<T>} with the supplied error message.
            * @param message - Error message to be returned.
@@ -2161,6 +2304,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * {@inheritDoc IResult.onFailure}
                */
               onFailure(cb: FailureContinuation<T>): Result<T>;
+              /**
+               * {@inheritDoc IResult.thenOnSuccess}
+               */
+              thenOnSuccess<TN>(__: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+              /**
+               * {@inheritDoc IResult.thenOnFailure}
+               */
+              thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;
               /**
                * {@inheritDoc IResult.withErrorFormat}
                */
@@ -3276,6 +3427,30 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                * was successful, propagates the result value from the successful event.
                */
               onFailure(cb: FailureContinuation<T>): Result<T>;
+              /**
+               * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+               * the operation was a success, bridging into an {@link AsyncResult} chain.
+               * @remarks
+               * If the async callback rejects, the rejection is caught and converted
+               * to a {@link Failure}.
+               * @param cb - The {@link AsyncSuccessContinuation | async success continuation} to
+               * be called in the event of success.
+               * @returns An {@link AsyncResult} wrapping the async continuation result, or
+               * propagating the error message from this failure.
+               */
+              thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+              /**
+               * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+               * the operation failed, bridging into an {@link AsyncResult} chain.
+               * @remarks
+               * If the async callback rejects, the rejection is caught and converted
+               * to a {@link Failure}.
+               * @param cb - The {@link AsyncFailureContinuation | async failure continuation} to
+               * be called in the event of failure.
+               * @returns An {@link AsyncResult} wrapping the async continuation result, or
+               * propagating the success value from this result.
+               */
+              thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;
               /**
                * Calls a supplied {@link ErrorFormatter | error formatter} if
                * the operation failed.
@@ -5557,6 +5732,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                                   * {@inheritDoc IResult.onFailure}
                                   */
                                  onFailure(__: FailureContinuation<T>): Result<T>;
+                                 /**
+                                  * {@inheritDoc IResult.thenOnSuccess}
+                                  */
+                                 thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+                                 /**
+                                  * {@inheritDoc IResult.thenOnFailure}
+                                  */
+                                 thenOnFailure(__: AsyncFailureContinuation<T>): AsyncResult<T>;
                                  /**
                                   * {@inheritDoc IResult.withErrorFormat}
                                   */

package/lib/packlets/base/result.d.ts

@@ -266,6 +266,30 @@ export interface IResult<T> {
      * was successful, propagates the result value from the successful event.
      */
     onFailure(cb: FailureContinuation<T>): Result<T>;
+    /**
+     * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+     * the operation was a success, bridging into an {@link AsyncResult} chain.
+     * @remarks
+     * If the async callback rejects, the rejection is caught and converted
+     * to a {@link Failure}.
+     * @param cb - The {@link AsyncSuccessContinuation | async success continuation} to
+     * be called in the event of success.
+     * @returns An {@link AsyncResult} wrapping the async continuation result, or
+     * propagating the error message from this failure.
+     */
+    thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+    /**
+     * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+     * the operation failed, bridging into an {@link AsyncResult} chain.
+     * @remarks
+     * If the async callback rejects, the rejection is caught and converted
+     * to a {@link Failure}.
+     * @param cb - The {@link AsyncFailureContinuation | async failure continuation} to
+     * be called in the event of failure.
+     * @returns An {@link AsyncResult} wrapping the async continuation result, or
+     * propagating the success value from this result.
+     */
+    thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;
     /**
      * Calls a supplied {@link ErrorFormatter | error formatter} if
      * the operation failed.
@@ -380,6 +404,14 @@ export declare class Success<out T> implements IResult<T> {
      * {@inheritDoc IResult.onFailure}
      */
     onFailure(__: FailureContinuation<T>): Result<T>;
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(__: AsyncFailureContinuation<T>): AsyncResult<T>;
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -476,6 +508,14 @@ export declare class Failure<out T> implements IResult<T> {
      * {@inheritDoc IResult.onFailure}
      */
     onFailure(cb: FailureContinuation<T>): Result<T>;
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess<TN>(__: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -772,14 +812,152 @@ export declare function failsWithDetail<T, TD>(message: string, detail?: TD): De
  * @public
  */
 export declare function propagateWithDetail<T, TD>(result: Result<T>, detail: TD, successDetail?: TD): DetailedResult<T, TD>;
+/**
+ * Extracts a message string from an unknown thrown/rejected value.
+ * @param err - The caught error value.
+ * @returns The error message string.
+ * @internal
+ */
+export declare function _errorMessage(err: unknown): string;
 /**
  * Wraps a function which might throw to convert exception results
  * to {@link Failure}.
  * @param func - The function to be captured.
  * @returns Returns {@link Success} with a value of type `<T>` on
  * success , or {@link Failure} with the thrown error message if
- * `func` throws an `Error`.
+ * `func` throws an `Error` or string.
  * @public
  */
 export declare function captureResult<T>(func: () => T): Result<T>;
+/**
+ * Async continuation callback to be called in the event that a
+ * {@link Result} is successful, returning a `Promise` of a new {@link Result}.
+ * @public
+ */
+export type AsyncSuccessContinuation<T, TN> = (value: T) => Promise<Result<TN>>;
+/**
+ * Async continuation callback to be called in the event that a
+ * {@link Result} fails, returning a `Promise` of a new {@link Result}.
+ * @public
+ */
+export type AsyncFailureContinuation<T> = (message: string) => Promise<Result<T>>;
+/**
+ * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both
+ * synchronous and asynchronous operations.
+ *
+ * @remarks
+ * `AsyncResult<T>` implements `PromiseLike` so it can be directly `await`ed.
+ * Use the `thenOnSuccess` and `thenOnFailure` methods on {@link Result} to bridge
+ * from synchronous to asynchronous result chains.
+ *
+ * @example
+ * ```typescript
+ * const result: Result<Final> = await parseInput(input)
+ *   .thenOnSuccess(async (parsed) => fetchData(parsed))
+ *   .onSuccess((data) => transform(data))
+ *   .thenOnSuccess(async (transformed) => saveData(transformed))
+ *   .withErrorFormat((msg) => `pipeline failed: ${msg}`);
+ * ```
+ *
+ * @public
+ */
+export declare class AsyncResult<T> implements PromiseLike<Result<T>> {
+    private readonly _promise;
+    /**
+     * Constructs an {@link AsyncResult} wrapping the supplied promise.
+     * @remarks
+     * If the supplied promise rejects, the rejection is caught and converted
+     * to a {@link Failure}, ensuring that awaiting an {@link AsyncResult} always
+     * yields a {@link Result}.
+     * @param promise - A `Promise` that resolves to a {@link Result}.
+     */
+    constructor(promise: Promise<Result<T>>);
+    /**
+     * Calls a supplied {@link SuccessContinuation | success continuation} if
+     * the wrapped result is successful.
+     * @param cb - The synchronous {@link SuccessContinuation | success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onSuccess<TN>(cb: SuccessContinuation<T, TN>): AsyncResult<TN>;
+    /**
+     * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+     * the wrapped result is successful.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncSuccessContinuation | async success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnSuccess<TN>(cb: AsyncSuccessContinuation<T, TN>): AsyncResult<TN>;
+    /**
+     * Calls a supplied {@link FailureContinuation | failure continuation} if
+     * the wrapped result is a failure.
+     * @param cb - The synchronous {@link FailureContinuation | failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onFailure(cb: FailureContinuation<T>): AsyncResult<T>;
+    /**
+     * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+     * the wrapped result is a failure.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncFailureContinuation | async failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnFailure(cb: AsyncFailureContinuation<T>): AsyncResult<T>;
+    /**
+     * Calls a supplied {@link ErrorFormatter | error formatter} if
+     * the wrapped result is a failure.
+     * @param cb - The {@link ErrorFormatter | error formatter} to
+     * be called in the event of failure.
+     * @returns A new {@link AsyncResult} with the formatted error message,
+     * or the original success result.
+     */
+    withErrorFormat(cb: ErrorFormatter): AsyncResult<T>;
+    /**
+     * Propagates the wrapped result, appending any error message to the
+     * supplied errors aggregator.
+     * @param errors - {@link IMessageAggregator | Error aggregator} in which
+     * errors will be aggregated.
+     * @param formatter - An optional {@link ErrorFormatter | error formatter}
+     * to be used to format the error message.
+     * @returns A new {@link AsyncResult} wrapping the result after aggregation.
+     */
+    aggregateError(errors: IMessageAggregator, formatter?: ErrorFormatter): AsyncResult<T>;
+    /**
+     * Reports the wrapped result to the supplied reporter.
+     * @param reporter - The {@link IResultReporter | reporter} to which the result
+     * will be reported.
+     * @param options - The {@link IResultReportOptions | options} for reporting the result.
+     * @returns A new {@link AsyncResult} wrapping the result after reporting.
+     */
+    report(reporter?: IResultReporter<T>, options?: IResultReportOptions<unknown>): AsyncResult<T>;
+    /**
+     * Implementation of `PromiseLike.then` enabling `await` on {@link AsyncResult}.
+     * @param onfulfilled - Callback invoked when the promise resolves.
+     * @param onrejected - Callback invoked when the promise rejects.
+     * @returns A `Promise` resolving to the callback result.
+     */
+    then<TResult1 = Result<T>, TResult2 = never>(onfulfilled?: ((value: Result<T>) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    /**
+     * Creates an {@link AsyncResult} from a {@link Result}.
+     * @param result - The {@link Result} to wrap.
+     * @returns A new {@link AsyncResult} wrapping the supplied result.
+     */
+    static from<T>(result: Result<T>): AsyncResult<T>;
+}
+/**
+ * Wraps an async function which might throw to convert exception results
+ * to {@link Failure}.
+ * @param func - The async function to be captured.
+ * @returns Returns a `Promise` of {@link Success} with a value of type `<T>` on
+ * success, or {@link Failure} with the thrown error message if `func` throws or rejects.
+ * @public
+ */
+export declare function captureAsyncResult<T>(func: () => Promise<T>): Promise<Result<T>>;
 //# sourceMappingURL=result.d.ts.map

package/lib/packlets/base/result.js

@@ -21,7 +21,7 @@
  * SOFTWARE.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DetailedFailure = exports.DetailedSuccess = exports.Failure = exports.Success = void 0;
+exports.AsyncResult = exports.DetailedFailure = exports.DetailedSuccess = exports.Failure = exports.Success = void 0;
 exports.isDeferredResult = isDeferredResult;
 exports.succeed = succeed;
 exports.succeeds = succeeds;
@@ -33,7 +33,9 @@ exports.succeedsWithDetail = succeedsWithDetail;
 exports.failWithDetail = failWithDetail;
 exports.failsWithDetail = failsWithDetail;
 exports.propagateWithDetail = propagateWithDetail;
+exports._errorMessage = _errorMessage;
 exports.captureResult = captureResult;
+exports.captureAsyncResult = captureAsyncResult;
 /**
  * Checks if a result is a deferred result.
  * @param result - The result to check.
@@ -116,6 +118,26 @@ class Success {
     onFailure(__) {
         return this;
     }
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess(cb) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return new AsyncResult(cb(this._value));
+        }
+        catch (err) {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return AsyncResult.from(fail(_errorMessage(err)));
+        }
+    }
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(__) {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        return AsyncResult.from(this);
+    }
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -242,6 +264,26 @@ class Failure {
     onFailure(cb) {
         return cb(this._message);
     }
+    /**
+     * {@inheritDoc IResult.thenOnSuccess}
+     */
+    thenOnSuccess(__) {
+        // eslint-disable-next-line @typescript-eslint/no-use-before-define
+        return AsyncResult.from(fail(this._message));
+    }
+    /**
+     * {@inheritDoc IResult.thenOnFailure}
+     */
+    thenOnFailure(cb) {
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return new AsyncResult(cb(this._message));
+        }
+        catch (err) {
+            // eslint-disable-next-line @typescript-eslint/no-use-before-define
+            return AsyncResult.from(fail(_errorMessage(err)));
+        }
+    }
     /**
      * {@inheritDoc IResult.withErrorFormat}
      */
@@ -610,13 +652,25 @@ function propagateWithDetail(result, detail, successDetail) {
         ? succeedWithDetail(result.value, successDetail !== null && successDetail !== void 0 ? successDetail : detail)
         : failWithDetail(result.message, detail);
 }
+/**
+ * Extracts a message string from an unknown thrown/rejected value.
+ * @param err - The caught error value.
+ * @returns The error message string.
+ * @internal
+ */
+function _errorMessage(err) {
+    if (err instanceof Error) {
+        return err.message;
+    }
+    return String(err);
+}
 /**
  * Wraps a function which might throw to convert exception results
  * to {@link Failure}.
  * @param func - The function to be captured.
  * @returns Returns {@link Success} with a value of type `<T>` on
  * success , or {@link Failure} with the thrown error message if
- * `func` throws an `Error`.
+ * `func` throws an `Error` or string.
  * @public
  */
 function captureResult(func) {
@@ -624,7 +678,181 @@ function captureResult(func) {
         return succeed(func());
     }
     catch (err) {
-        return fail(err.message);
+        return fail(_errorMessage(err));
+    }
+}
+/**
+ * Wraps a `Promise` of a {@link Result} to enable fluent chaining of both
+ * synchronous and asynchronous operations.
+ *
+ * @remarks
+ * `AsyncResult<T>` implements `PromiseLike` so it can be directly `await`ed.
+ * Use the `thenOnSuccess` and `thenOnFailure` methods on {@link Result} to bridge
+ * from synchronous to asynchronous result chains.
+ *
+ * @example
+ * ```typescript
+ * const result: Result<Final> = await parseInput(input)
+ *   .thenOnSuccess(async (parsed) => fetchData(parsed))
+ *   .onSuccess((data) => transform(data))
+ *   .thenOnSuccess(async (transformed) => saveData(transformed))
+ *   .withErrorFormat((msg) => `pipeline failed: ${msg}`);
+ * ```
+ *
+ * @public
+ */
+class AsyncResult {
+    /**
+     * Constructs an {@link AsyncResult} wrapping the supplied promise.
+     * @remarks
+     * If the supplied promise rejects, the rejection is caught and converted
+     * to a {@link Failure}, ensuring that awaiting an {@link AsyncResult} always
+     * yields a {@link Result}.
+     * @param promise - A `Promise` that resolves to a {@link Result}.
+     */
+    constructor(promise) {
+        this._promise = promise.catch((err) => fail(_errorMessage(err)));
+    }
+    /**
+     * Calls a supplied {@link SuccessContinuation | success continuation} if
+     * the wrapped result is successful.
+     * @param cb - The synchronous {@link SuccessContinuation | success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onSuccess(cb) {
+        return new AsyncResult(this._promise.then((r) => r.onSuccess(cb)));
+    }
+    /**
+     * Calls a supplied {@link AsyncSuccessContinuation | async success continuation} if
+     * the wrapped result is successful.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncSuccessContinuation | async success continuation}
+     * to be called in the event of success.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnSuccess(cb) {
+        return new AsyncResult(this._promise.then(async (r) => {
+            if (r.isFailure()) {
+                return fail(r.message);
+            }
+            try {
+                return await cb(r.value);
+            }
+            catch (err) {
+                return fail(_errorMessage(err));
+            }
+        }));
+    }
+    /**
+     * Calls a supplied {@link FailureContinuation | failure continuation} if
+     * the wrapped result is a failure.
+     * @param cb - The synchronous {@link FailureContinuation | failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the continuation result.
+     */
+    onFailure(cb) {
+        return new AsyncResult(this._promise.then((r) => r.onFailure(cb)));
+    }
+    /**
+     * Calls a supplied {@link AsyncFailureContinuation | async failure continuation} if
+     * the wrapped result is a failure.
+     * @remarks
+     * Both synchronous throws and async rejections from the callback are caught
+     * and converted to a {@link Failure}.
+     * @param cb - The {@link AsyncFailureContinuation | async failure continuation}
+     * to be called in the event of failure.
+     * @returns A new {@link AsyncResult} wrapping the async continuation result.
+     */
+    thenOnFailure(cb) {
+        return new AsyncResult(this._promise.then(async (r) => {
+            if (r.isSuccess()) {
+                return r;
+            }
+            try {
+                return await cb(r.message);
+            }
+            catch (err) {
+                return fail(_errorMessage(err));
+            }
+        }));
+    }
+    /**
+     * Calls a supplied {@link ErrorFormatter | error formatter} if
+     * the wrapped result is a failure.
+     * @param cb - The {@link ErrorFormatter | error formatter} to
+     * be called in the event of failure.
+     * @returns A new {@link AsyncResult} with the formatted error message,
+     * or the original success result.
+     */
+    withErrorFormat(cb) {
+        return new AsyncResult(this._promise.then((r) => r.withErrorFormat(cb)));
+    }
+    /**
+     * Propagates the wrapped result, appending any error message to the
+     * supplied errors aggregator.
+     * @param errors - {@link IMessageAggregator | Error aggregator} in which
+     * errors will be aggregated.
+     * @param formatter - An optional {@link ErrorFormatter | error formatter}
+     * to be used to format the error message.
+     * @returns A new {@link AsyncResult} wrapping the result after aggregation.
+     */
+    aggregateError(errors, formatter) {
+        return new AsyncResult(this._promise.then((r) => {
+            r.aggregateError(errors, formatter);
+            return r;
+        }));
+    }
+    /**
+     * Reports the wrapped result to the supplied reporter.
+     * @param reporter - The {@link IResultReporter | reporter} to which the result
+     * will be reported.
+     * @param options - The {@link IResultReportOptions | options} for reporting the result.
+     * @returns A new {@link AsyncResult} wrapping the result after reporting.
+     */
+    report(reporter, options) {
+        return new AsyncResult(this._promise.then((r) => {
+            r.report(reporter, options);
+            return r;
+        }));
+    }
+    /**
+     * Implementation of `PromiseLike.then` enabling `await` on {@link AsyncResult}.
+     * @param onfulfilled - Callback invoked when the promise resolves.
+     * @param onrejected - Callback invoked when the promise rejects.
+     * @returns A `Promise` resolving to the callback result.
+     */
+    /* eslint-disable @rushstack/no-new-null */
+    then(onfulfilled, onrejected) {
+        /* eslint-enable @rushstack/no-new-null */
+        return this._promise.then(onfulfilled, onrejected);
+    }
+    /**
+     * Creates an {@link AsyncResult} from a {@link Result}.
+     * @param result - The {@link Result} to wrap.
+     * @returns A new {@link AsyncResult} wrapping the supplied result.
+     */
+    static from(result) {
+        return new AsyncResult(Promise.resolve(result));
+    }
+}
+exports.AsyncResult = AsyncResult;
+/**
+ * Wraps an async function which might throw to convert exception results
+ * to {@link Failure}.
+ * @param func - The async function to be captured.
+ * @returns Returns a `Promise` of {@link Success} with a value of type `<T>` on
+ * success, or {@link Failure} with the thrown error message if `func` throws or rejects.
+ * @public
+ */
+async function captureAsyncResult(func) {
+    try {
+        return succeed(await func());
+    }
+    catch (err) {
+        return fail(_errorMessage(err));
     }
 }
 //# sourceMappingURL=result.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fgv/ts-utils",
-  "version": "5.1.0-11",
+  "version": "5.1.0-12",
   "description": "Assorted Typescript Utilities",
   "main": "lib/index.js",
   "module": "dist/index.js",
@@ -54,8 +54,8 @@
     "@rushstack/heft-jest-plugin": "1.2.6",
     "eslint-plugin-tsdoc": "~0.5.2",
     "typedoc": "~0.28.16",
-    "@fgv/heft-dual-rig": "5.1.0-11",
-    "@fgv/typedoc-compact-theme": "5.1.0-11"
+    "@fgv/heft-dual-rig": "5.1.0-12",
+    "@fgv/typedoc-compact-theme": "5.1.0-12"
   },
   "repository": {
     "type": "git",