@fgv/ts-utils 5.1.0-2 → 5.1.0-20

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,
@@ -454,63 +579,146 @@ declare class BaseConverter<T, TC = unknown> implements Converter<T, TC> {
      */
     constructor(converter: ConverterFunc<T, TC>, defaultContext?: TC, traits?: ConverterTraits);
     /**
-     * {@inheritDoc Converter.isOptional}
+     * Indicates whether this element is explicitly optional.
      */
     get isOptional(): boolean;
     /**
-     * {@inheritDoc Converter.brand}
+     * Returns the brand for a branded type.
      */
     get brand(): string | undefined;
     /**
-     * {@inheritDoc Converter.convert}
+     * Converts from `unknown` to `<T>`. For objects and arrays, is guaranteed
+     * to return a new entity, with any unrecognized properties removed.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
     convert(from: unknown, context?: TC): Result<T>;
     /**
-     * {@inheritDoc Converter.convertOptional}
+     * Converts from `unknown` to `<T>` or `undefined`, as appropriate.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the converter succeeds for
+     * `undefined` or any convertible value, but reports an error
+     * if it encounters a value that cannot be converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that
+     * cannot be converted result in a successful return of `undefined`.
+     * @param from - The `unknown` to be converted
+     * @param context - An optional conversion context of type `<TC>` to be used in
+     * the conversion.
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A {@link Result} with a {@link Success} and a value on success or an
+     * {@link Failure} with a a message on failure.
      */
     convertOptional(from: unknown, context?: TC, onError?: OnError): Result<T | undefined>;
     /**
-     * {@inheritDoc Converter.optional}
+     * Creates a {@link Converter} for an optional value.
+     *
+     * @remarks
+     * If `onError` is `failOnError`, the resulting converter will accept `undefined`
+     * or a convertible value, but report an error if it encounters a value that cannot be
+     * converted.
+     *
+     * If `onError` is `ignoreErrors` (default) then values that cannot be converted will
+     * result in a successful return of `undefined`.
+     *
+     * @param onError - Specifies handling of values that cannot be converted (default `ignoreErrors`).
+     * @returns A new {@link Converter} returning `<T|undefined>`.
      */
     optional(onError?: OnError): Converter<T | undefined, TC>;
     /**
-     * {@inheritDoc Converter.map}
+     * Creates a {@link Converter} which applies a (possibly) mapping conversion to
+     * the converted value of this {@link Converter}.
+     * @param mapper - A function which maps from the the result type `<T>` of this
+     * converter to a new result type `<T2>`.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     map<T2>(mapper: (from: T, context?: TC) => Result<T2>): Converter<T2, TC>;
     /**
-     * {@inheritDoc Converter.mapConvert}
+     * Creates a {@link Converter} which applies an additional supplied
+     * converter to the result of this converter.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to the
+     * converted result from this {@link Converter}.
+     * @returns A new {@link Converter} returning `<T2>`.
      */
     mapConvert<T2>(mapConverter: Converter<T2>): Converter<T2, TC>;
     /**
-     * {@inheritDoc Converter.mapItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied map function.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapper - The map function to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapItems<TI>(mapper: (from: unknown, context?: TC) => Result<TI>): Converter<TI[], TC>;
     /**
-     * {@inheritDoc Converter.mapConvertItems}
+     * Creates a {@link Converter} which maps the individual items of a collection
+     * resulting from this {@link Converter} using the supplied {@link Converter}.
+     *
+     * @remarks
+     * Fails if `from` is not an array.
+     *
+     * @param mapConverter - The {@link Converter} to be applied to each element of the
+     * result of this {@link Converter}.
+     * @returns A new {@link Converter} returning `<TI[]>`.
      */
     mapConvertItems<TI>(mapConverter: Converter<TI, unknown>): Converter<TI[], TC>;
     /**
-     * {@inheritDoc Converter.withAction}
+     * Creates a {@link Converter | Converter} which applies a supplied action after
+     * conversion. The supplied action is always called regardless of success or failure
+     * of the base conversion and is allowed to mutate the return type.
+     * @param action - The action to be applied.
      */
     withAction<TI>(action: (result: Result<T>, context?: TC) => Result<TI>): Converter<TI, TC>;
     /**
-     * {@inheritDoc Converter.withTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to the conversion
+     * result.
+     * @param guard - The type guard function to apply.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI, TC>;
     /**
-     * {@inheritDoc Converter.withItemTypeGuard}
+     * Creates a {@link Converter} which applies a supplied type guard to each member of
+     * the conversion result from this converter.
+     *
+     * @remarks
+     * Fails if the conversion result is not an array or if any member fails the
+     * type guard.
+     * @param guard - The type guard function to apply to each element.
+     * @param message - Optional message to be reported if the type guard fails.
+     * @returns A new {@link Converter} returning `<TI>`.
      */
     withItemTypeGuard<TI>(guard: (from: unknown, context?: TC) => from is TI, message?: string): Converter<TI[], TC>;
     /**
-     * {@inheritDoc Converter.withConstraint}
+     * Creates a {@link Converter} which applies an optional constraint to the result
+     * of this conversion. If this {@link Converter} (the base converter) succeeds, the new
+     * converter calls a supplied constraint evaluation function with the conversion, which
+     * fails the entire conversion if the constraint function returns either `false` or
+     * {@link Failure | Failure<T>}.
+     *
+     * @param constraint - Constraint evaluation function.
+     * @param options - {@link Conversion.ConstraintOptions | Options} for constraint evaluation.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withConstraint(constraint: (val: T, context?: TC) => boolean | Result<T>, options?: ConstraintOptions): Converter<T, TC>;
     /**
-     * {@inheritDoc Converter.withBrand}
+     * Returns a converter which adds a brand to the type to prevent mismatched usage
+     * of simple types.
+     * @param brand - The brand to be applied to the result value.
+     * @returns A {@link Converter} returning `Brand<T, B>`.
      */
     withBrand<B extends string>(brand: B): Converter<Brand<T, B>, TC>;
     /**
-     * {@inheritDoc Converter.withDefault}
+     * Returns a Converter which always succeeds with a default value rather than failing.
+     * @param defaultValue - The default value to use if conversion fails.
      */
     withDefault<TD = T>(defaultValue: TD): DefaultingConverter<T, TD, TC>;
     or(other: Converter<T, TC>): Converter<T, TC>;
@@ -519,7 +727,10 @@ declare class BaseConverter<T, TC = unknown> implements Converter<T, TC> {
      */
     protected _context(supplied?: TC): TC | undefined;
     /**
-     * {@inheritDoc Converter.withFormattedError}
+     * Creates a new {@link Converter} which is derived from this one but which returns an
+     * error message formatted by the supplied formatter if the conversion fails.
+     * @param formatter - The formatter to be applied.
+     * @returns A new {@link Converter} returning `<T>`.
      */
     withFormattedError(formatter: ConversionErrorFormatter<TC>): Converter<T, TC>;
     /**
@@ -778,13 +989,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>;
@@ -987,7 +1208,7 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
           private readonly _byKey;
           private readonly _byIndex;
           /**
-           * {@inheritDoc Collections.ResultMap.size}
+           * Returns the number of entries in the map.
            */
           get size(): number;
           /**
@@ -1014,19 +1235,28 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritDoc Collections.ResultMap.entries}
+           * Returns an iterator over the map entries.
+           * @returns An iterator over the map entries.
            */
           entries(): IterableIterator<KeyValueEntry<CollectibleKey<TITEM>, TITEM>>;
           /**
-           * {@inheritDoc Collections.ResultMap.forEach}
+           * Calls a function for each entry in the map.
+           * @param callback - The function to call for each entry.
+           * @param arg - An optional argument to pass to the callback.
            */
           forEach(callback: ResultMapForEachCb<CollectibleKey<TITEM>, TITEM>, arg?: unknown): void;
           /**
-           * {@inheritDoc Collections.ResultMap.get}
+           * Gets a value by key.
+           * @param key - The key to look up.
+           * @returns Returns {@link DetailedSuccess | Success} with the value and detail `exists` if found,
+           * or {@link DetailedFailure | Failure} with detail `not-found` if the key does not exist.
            */
           get(key: CollectibleKey<TITEM>): DetailedResult<TITEM, ResultMapResultDetail>;
           /**
-           * {@inheritDoc Collections.IReadOnlyCollector.getAt}
+           * Gets the item at a specified index.
+           * @param index - The index of the item to retrieve.
+           * @returns Returns {@link Success | Success} with the item if it exists, or {@link Failure | Failure}
+           * with an error if the index is out of range.
            */
           getAt(index: number): Result<TITEM>;
           /**
@@ -1051,19 +1281,24 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           getOrAdd(key: CollectibleKey<TITEM>, factory: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritDoc Collections.ResultMap.has}
+           * Returns true if the map contains an entry with the given key.
+           * @param key - The key to check for.
+           * @returns `true` if the key exists, `false` otherwise.
            */
           has(key: CollectibleKey<TITEM>): boolean;
           /**
-           * {@inheritDoc Collections.ResultMap.keys}
+           * Returns an iterator over the map keys.
+           * @returns An iterator over the map keys.
            */
           keys(): IterableIterator<CollectibleKey<TITEM>>;
           /**
-           * {@inheritDoc Collections.ResultMap.values}
+           * Returns an iterator over the map values.
+           * @returns An iterator over the map values.
            */
           values(): IterableIterator<TITEM>;
           /**
-           * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
+           * Gets all items in the collection, ordered by index.
+           * @returns An array of items in the collection, ordered by index.
            */
           valuesByIndex(): ReadonlyArray<TITEM>;
           /**
@@ -1099,7 +1334,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           constructor(params: ICollectorValidatorCreateParams<TITEM>);
           /**
-           * {@inheritDoc Collections.Collector.add}
+           * Adds an item to the collection, failing if a different item with the same key already exists. Note
+           * that adding an object that is already in the collection again will succeed without updating the collection.
+           * @param item - The item to add.
+           * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+           * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+           * an error message and appropriate detail if the item could not be added.
            */
           add(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
           /**
@@ -1107,12 +1347,24 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
           /**
-           * {@inheritDoc Collections.Collector.getOrAdd}
+           * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+           * using a factory callback if no item with that key exists.
+           * @param key - The weakly-typed key of the item to get or add.
+           * @param factory - The factory callback to create the item.
+           * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+           * detail `exists` indicates that an existing item was returned and detail `added` indicates
+           * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+           * appropriate detail if the item could not be added.
            */
           getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
           /**
-           * {@inheritDoc Collections.Collector.getOrAdd}
-           * @param item - The item to add to the collector.
+           * Gets an existing item with a key matching that of the supplied item, or adds the supplied
+           * item to the collector if no item with that key exists.
+           * @param item - The weakly-typed item to get or add.
+           * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+           * detail `exists` indicates that an existing item was returned and detail `added` indicates
+           * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+           * appropriate detail if the item could not be added.
            */
           getOrAdd(item: unknown): DetailedResult<TITEM, CollectorResultDetail>;
           /**
@@ -1577,7 +1829,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               static createConvertingCollector<TITEM extends ICollectible<any, any>, TSRC = TITEM>(params: IConvertingCollectorConstructorParams<TITEM, TSRC>): Result<ConvertingCollector<TITEM, TSRC>>;
               /**
-               * {@inheritDoc Collections.Collector.add}
+               * Adds an item to the collection, failing if a different item with the same key already exists. Note
+               * that adding an object that is already in the collection again will succeed without updating the collection.
+               * @param item - The item to add.
+               * @returns Returns {@link DetailedSuccess | Success} with the item and detail `added` if it was added
+               * or detail `exists` if the item was already in the map.  Returns {@link DetailedFailure | Failure} with
+               * an error message and appropriate detail if the item could not be added.
                */
               add(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -1600,11 +1857,24 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               add(key: CollectibleKey<TITEM>, cb: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritDoc Collections.Collector.getOrAdd}
+               * Gets an existing item with a key matching that of the supplied item, or adds the supplied
+               * item to the collector if no item with that key exists.
+               * @param item - The item to get or add.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(item: TITEM): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritDoc Collections.Collector.getOrAdd}
+               * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+               * using a factory callback if no item with that key exists.
+               * @param key - The key of the item to get or add.
+               * @param callback - The factory callback to create the item.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(key: CollectibleKey<TITEM>, callback: CollectibleFactoryCallback<TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -1662,7 +1932,12 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               constructor(params: IConvertingCollectorValidatorCreateParams<TITEM, TSRC>);
               /**
-               * {@inheritDoc Collections.ConvertingCollector.add}
+               * Adds an item to the collector using the default factory at a specified key,
+               * failing if an item with that key already exists.
+               * @param key - The weakly-typed key of the item to add.
+               * @param value - The source representation of the item to be added.
+               * @returns Returns {@link Success | Success} with the item if it is added, or {@link Failure | Failure} with
+               * an error if the item cannot be created and indexed.
                */
               add(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -1675,11 +1950,25 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               get(key: string): DetailedResult<TITEM, ResultMapResultDetail>;
               /**
-               * {@inheritDoc Collections.ConvertingCollector.getOrAdd}
+               * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+               * by converting the supplied weakly-typed value if no item with that key exists.
+               * @param key - The weakly-typed key of the item to get or add.
+               * @param value - The weakly-typed source value to convert and add if the key does not exist.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(key: string, value: unknown): DetailedResult<TITEM, CollectorResultDetail>;
               /**
-               * {@inheritDoc Collections.Collector.getOrAdd}
+               * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+               * using a factory callback if no item with that key exists.
+               * @param key - The weakly-typed key of the item to get or add.
+               * @param factory - The factory callback to create the item.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
               /**
@@ -2070,6 +2359,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 +2458,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}
                */
@@ -3016,7 +3321,14 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
                */
               has(key: string): boolean;
               /**
-               * {@inheritDoc Collections.Collector.getOrAdd}
+               * Gets an existing item with a key matching the supplied key, or adds a new item to the collector
+               * using a factory callback if no item with that key exists.
+               * @param key - The weakly-typed key of the item to get or add.
+               * @param factory - The factory callback to create the item.
+               * @returns Returns {@link DetailedSuccess | Success} with the item stored in the collector -
+               * detail `exists` indicates that an existing item was returned and detail `added` indicates
+               * that the item was added. Returns {@link DetailedFailure | Failure} with an error and
+               * appropriate detail if the item could not be added.
                */
               getOrAdd(key: string, factory: ResultMapValueFactory<CollectibleKey<TITEM>, TITEM>): DetailedResult<TITEM, CollectorResultDetail>;
           }
@@ -3053,31 +3365,42 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           export declare interface IReadOnlyResultMap<TK extends string = string, TV = unknown> {
               /**
-               * {@inheritDoc Collections.ResultMap.size}
+               * Returns the number of entries in the map.
                */
               readonly size: number;
               /**
-               * {@inheritDoc Collections.ResultMap.entries}
+               * Returns an iterator over the map entries.
+               * @returns An iterator over the map entries.
                */
               entries(): IterableIterator<KeyValueEntry<TK, TV>>;
               /**
-               * {@inheritDoc Collections.ResultMap.forEach}
+               * Calls a function for each entry in the map.
+               * @param cb - The function to call for each entry.
+               * @param arg - An optional argument to pass to the callback.
                */
               forEach(cb: ResultMapForEachCb, arg?: unknown): void;
               /**
-               * {@inheritDoc Collections.ResultMap.get}
+               * Gets a value from the map.
+               * @param key - The key to retrieve.
+               * @returns `Success` with the value and detail `exists` if the key was found,
+               * `Failure` with detail `not-found` if the key was not found or with detail
+               * `invalid-key` if the key is invalid.
                */
               get(key: TK): DetailedResult<TV, ResultMapResultDetail>;
               /**
-               * {@inheritDoc Collections.ResultMap.has}
+               * Returns `true` if the map contains a key.
+               * @param key - The key to check.
+               * @returns `true` if the key exists, `false` otherwise.
                */
               has(key: TK): boolean;
               /**
-               * {@inheritDoc Collections.ResultMap.keys}
+               * Returns an iterator over the map keys.
+               * @returns An iterator over the map keys.
                */
               keys(): IterableIterator<TK>;
               /**
-               * {@inheritDoc Collections.ResultMap.values}
+               * Returns an iterator over the map values.
+               * @returns An iterator over the map values.
                */
               values(): IterableIterator<TV>;
               /**
@@ -3113,15 +3436,19 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare interface IReadOnlyValidatingCollector<TITEM extends ICollectible<any, any>> extends IReadOnlyValidatingResultMap<CollectibleKey<TITEM>, TITEM> {
               /**
-               * {@inheritDoc Collections.ValidatingCollector.validating}
+               * A {@link Collections.CollectorValidator | CollectorValidator} which validates keys and values
+               * before inserting them into this collector.
                */
               readonly validating: IReadOnlyCollectorValidator<TITEM>;
               /**
-               * {@inheritDoc Collections.IReadOnlyCollector.getAt}
+               * Gets the item at a specified index.
+               * @param index - The index of the item to retrieve.
+               * @returns `Success` with the item if it exists, or `Failure` with an error if the index is out of range.
                */
               getAt(index: number): Result<TITEM>;
               /**
-               * {@inheritDoc Collections.IReadOnlyCollector.valuesByIndex}
+               * Gets all items in the collection, ordered by index.
+               * @returns An array of items in the collection, ordered by index.
                */
               valuesByIndex(): ReadonlyArray<TITEM>;
           }
@@ -3132,7 +3459,8 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare interface IReadOnlyValidatingResultMap<TK extends string = string, TV = unknown> extends IReadOnlyResultMap<TK, TV> {
               /**
-               * {@inheritDoc Collections.ValidatingResultMap.validating}
+               * A {@link Collections.ResultMapValidator | ResultMapValidator} which validates keys and values
+               * before inserting them into this collection.
                */
               readonly validating: IReadOnlyResultMapValidator<TK, TV>;
           }
@@ -3276,6 +3604,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.
@@ -3750,36 +4102,61 @@ declare class Collectible<TKEY extends string = string, TINDEX extends number =
            */
           declare abstract class LoggerBase implements IDetailLogger {
               /**
-               * {@inheritDoc Logging.ILogger.logLevel}
+               * The level of logging to be used.
                */
               logLevel: ReporterLogLevel;
               protected constructor(logLevel?: ReporterLogLevel);
               /**
-               * {@inheritDoc Logging.ILogger.detail}
+               * Logs a detail message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               detail(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.ILogger.info}
+               * Logs an info message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               info(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.ILogger.warn}
+               * Logs a warning message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               warn(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.ILogger.error}
+               * Logs an error message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               error(message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.IDetailLogger.errorWithDetail}
+               * Logs a short error summary at `error` level, then emits `detail` at `detail` level.
+               * @param message - Short human-readable summary.
+               * @param detail - Full detail (e.g. raw converter error) logged at `detail` level.
                */
               errorWithDetail(message: string, detail: unknown): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.IDetailLogger.warnWithDetail}
+               * Logs a short warning summary at `warning` level, then emits `detail` at `detail` level.
+               * @param message - Short human-readable summary.
+               * @param detail - Full detail logged at `detail` level.
                */
               warnWithDetail(message: string, detail: unknown): Success<string | undefined>;
               /**
-               * {@inheritDoc Logging.ILogger.log}
+               * Logs a message at the given level.
+               * @param level - The level of the message.
+               * @param message - The message to log.
+               * @param parameters - The parameters to log.
+               * @returns `Success` with the logged message if the level is enabled, or
+               * `Success` with `undefined` if the message is suppressed.
                */
               log(level: MessageLogLevel, message?: unknown, ...parameters: unknown[]): Success<string | undefined>;
               /**
@@ -5557,6 +5934,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}
                                   */