resultar 3.3.0 → 3.4.0

package/dist/index.d.ts

@@ -6,6 +6,12 @@ interface ErrorConfig {
 //#region src/pipe.d.ts
 type PipeFn<Input, Output> = (input: Input) => Output;
 declare abstract class Pipeable {
+  /**
+  * Passes this value through one or more transformation functions.
+  *
+  * Use `pipe` to package reusable Result or ResultAsync combinators without hiding the underlying
+  * type.
+  */
   pipe<A>(ab: PipeFn<this, A>): A;
   pipe<A, B>(ab: PipeFn<this, A>, bc: PipeFn<A, B>): B;
   pipe<A, B, C>(ab: PipeFn<this, A>, bc: PipeFn<A, B>, cd: PipeFn<B, C>): C;
@@ -155,19 +161,19 @@ interface Resultable<T, E> {
   *
   * @returns `true` if the result is an `OK` variant of Result
   */
-  isOk(): boolean;
+  isOk: () => boolean;
   /**
   * Used to check if a `Result` is an `Err`
   *
   * @returns `true` if the result is an `Err` variant of Result
   */
-  isErr(): boolean;
+  isErr: () => boolean;
   /**
   * Unwrap the `Ok` value, or return the default if there is an `Err`
   *
   * @param v the default value to return if there is an `Err`
   */
-  unwrapOr<A>(defaultValue: A): T | A;
+  unwrapOr: <A>(defaultValue: A) => T | A;
   /**
   * **This method is unsafe, and should only be used in a test environments**
   *
@@ -175,7 +181,7 @@ interface Resultable<T, E> {
   *
   * @param config
   */
-  _unsafeUnwrap(config?: ErrorConfig): T;
+  _unsafeUnwrap: (config?: ErrorConfig) => T;
   /**
   * **This method is unsafe, and should only be used in a test environments**
   *
@@ -184,108 +190,339 @@ interface Resultable<T, E> {
   *
   * @param config
   */
-  _unsafeUnwrapErr(config?: ErrorConfig): E;
+  _unsafeUnwrapErr: (config?: ErrorConfig) => E;
 }
 interface ResultOperations<T, E> {
-  isOk(): this is OkResult<T, E>;
-  isErr(): this is ErrResult<T, E>;
-  unwrapOr<A>(defaultValue: A): T | A;
-  _unsafeUnwrap(config?: ErrorConfig): T;
-  _unsafeUnwrapErr(config?: ErrorConfig): E;
-  map<X>(f: (t: T) => X): Result<X, E>;
-  as<X>(value: X): Result<X, E>;
-  filterOrElse<U extends T, F>(predicate: (value: T) => value is U, onFalse: (value: T) => F): Result<U, E | F>;
-  filterOrElse<F>(predicate: (value: T) => boolean, onFalse: (value: T) => F): Result<T, E | F>;
-  mapErr<X>(fn: (t: E) => X): Result<T, X>;
-  andThen<X, Y>(f: (t: T) => Result<X, Y>): Result<X, E | Y>;
-  if(fCondition: (t: T) => boolean): {
+  /**
+  * Narrows this result to the Ok variant.
+  */
+  isOk: () => this is OkResult<T, E>;
+  /**
+  * Narrows this result to the Err variant.
+  */
+  isErr: () => this is ErrResult<T, E>;
+  /**
+  * Returns the Ok value, or `defaultValue` when this result is Err.
+  */
+  unwrapOr: <A>(defaultValue: A) => T | A;
+  /**
+  * Returns the Ok value or throws a Resultar diagnostic error when this result is Err.
+  *
+  * Prefer `match`, `unwrapOr`, or explicit error handling in application code. This helper is
+  * intended for tests and trusted final boundaries.
+  */
+  _unsafeUnwrap: (config?: ErrorConfig) => T;
+  /**
+  * Returns the Err value or throws a Resultar diagnostic error when this result is Ok.
+  *
+  * Prefer `match`, `isErr`, or explicit error handling in application code. This helper is intended
+  * for tests.
+  */
+  _unsafeUnwrapErr: (config?: ErrorConfig) => E;
+  /**
+  * Maps the Ok value while preserving the error channel.
+  */
+  map: <X>(f: (t: T) => X) => Result<X, E>;
+  /**
+  * Replaces the Ok value with a constant while preserving the error channel.
+  */
+  as: <X>(value: X) => Result<X, E>;
+  /**
+  * Keeps the Ok value only when the predicate passes; otherwise returns an Err from `onFalse`.
+  */
+  filterOrElse: {
+    <U extends T, F>(predicate: (value: T) => value is U, onFalse: (value: T) => F): Result<U, E | F>;
+    <F>(predicate: (value: T) => boolean, onFalse: (value: T) => F): Result<T, E | F>;
+  };
+  /**
+  * Maps the Err value while preserving the Ok value.
+  */
+  mapErr: <X>(fn: (t: E) => X) => Result<T, X>;
+  /**
+  * Chains another fallible operation from the Ok value.
+  *
+  * Use this instead of `map` when the callback returns another `Result`.
+  */
+  andThen: <X, Y>(f: (t: T) => Result<X, Y>) => Result<X, E | Y>;
+  /**
+  * Branches from the Ok value into one of two fallible Result branches.
+  */
+  if: (fCondition: (t: T) => boolean) => {
     true: <X1, Y1>(fTrue: (t: T) => Result<X1, Y1>) => {
       false: <X2, Y2>(fFalse: (t: T) => Result<X2, Y2>) => Result<X1 | X2, Y1 | Y2 | E>;
     };
   };
-  orElse<R extends Result<unknown, unknown>>(f: (e: E) => R): Result<InferOkTypes<R> | T, InferErrTypes<R>>;
-  catchTag<const Tag extends TagsOf<E>, R extends Result<unknown, unknown>>(tag: Tag, f: (error: ErrorForTag$1<E, Tag>) => R): Result<T | InferOkTypes<R>, ExcludeTag<E, Tag> | InferErrTypes<R>>;
-  catchTags<const Handlers extends object>(handlers: Handlers & ResultCatchTagHandlers<E, Handlers>): Result<T | InferOkTypes<CatchTagHandlerResult<Handlers>>, ExcludeTag<E, keyof Handlers & string> | InferErrTypes<CatchTagHandlerResult<Handlers>>>;
-  catchReason<const ErrorTag extends TagsWithReasonOf<E>, const ReasonTag extends ReasonTagsOf<E, ErrorTag>, R extends Result<unknown, unknown>>(errorTag: ErrorTag, reasonTag: ReasonTag, f: (reason: ReasonForTag<E, ErrorTag, ReasonTag>, error: ErrorForTag$1<E, ErrorTag>) => R): Result<T | InferOkTypes<R>, ExcludeReasonTag<E, ErrorTag, ReasonTag> | InferErrTypes<R>>;
-  catchReasons<const ErrorTag extends TagsWithReasonOf<E>, const Handlers extends object>(errorTag: ErrorTag, handlers: Handlers & ResultCatchReasonHandlers<E, ErrorTag, Handlers>): Result<T | InferOkTypes<CatchReasonHandlerResult<Handlers>>, ExcludeReasonTag<E, ErrorTag, keyof Handlers & string> | InferErrTypes<CatchReasonHandlerResult<Handlers>>>;
-  unwrapReason<const ErrorTag extends TagsWithReasonOf<E>>(errorTag: ErrorTag): Result<T, ExcludeTag<E, ErrorTag> | ReasonsOf<E, ErrorTag>>;
-  asyncAndThen<X, Y>(f: (t: T) => ResultAsync<X, Y>): ResultAsync<X, E | Y>;
-  asyncMap<X>(f: (t: T) => Promise<X>): ResultAsync<X, E>;
-  match<A, B = A>(handlers: MatchHandlers$1<T, E, A, B>): A | B;
-  match<A, B = A>(fnOk: MatchOkHandler<T, A>, fnErr: MatchErrorHandler<E, B>): A | B;
-  matchTags<A, const Handlers extends object>(fnOk: (t: T) => A, handlers: Handlers & MatchTagHandlers<E, Handlers>): A | MatchTagHandlerResult<Handlers>;
-  matchTagsPartial<A, B, const Handlers extends object>(fnOk: (t: T) => A, handlers: Handlers & PartialMatchTagHandlers<E, Handlers>, fallback: (error: E) => B): A | MatchTagHandlerResult<Handlers> | B;
-  pipe<A>(ab: PipeFn<Result<T, E>, A>): A;
-  pipe<A, B>(ab: PipeFn<Result<T, E>, A>, bc: PipeFn<A, B>): B;
-  pipe<A, B, C>(ab: PipeFn<Result<T, E>, A>, bc: PipeFn<A, B>, cd: PipeFn<B, C>): C;
-  log(fn: (t?: T, e?: E) => void): this;
-  tap(fn: (t: T) => void): this;
-  tapError(fn: (e: E) => void): this;
-  toDisposable(f: ResultFinalizer<T, E>): DisposableResult<T, E>;
-  unwrapOrThrow(): T;
-  [Symbol.iterator](): Generator<Result<never, E>, T>;
-  safeUnwrap(): Generator<Result<never, E>, T>;
+  /**
+  * Recovers from Err with another Result.
+  */
+  orElse: <R extends Result<unknown, unknown>>(f: (e: E) => R) => Result<InferOkTypes<R> | T, InferErrTypes<R>>;
+  /**
+  * Recovers from a specific tagged error by `_tag`.
+  */
+  catchTag: <const Tag extends TagsOf<E>, R extends Result<unknown, unknown>>(tag: Tag, f: (error: ErrorForTag$1<E, Tag>) => R) => Result<T | InferOkTypes<R>, ExcludeTag<E, Tag> | InferErrTypes<R>>;
+  /**
+  * Recovers from multiple tagged errors by `_tag`.
+  */
+  catchTags: <const Handlers extends object>(handlers: Handlers & ResultCatchTagHandlers<E, Handlers>) => Result<T | InferOkTypes<CatchTagHandlerResult<Handlers>>, ExcludeTag<E, keyof Handlers & string> | InferErrTypes<CatchTagHandlerResult<Handlers>>>;
+  /**
+  * Recovers from a nested tagged `reason` on a specific tagged error.
+  */
+  catchReason: <const ErrorTag extends TagsWithReasonOf<E>, const ReasonTag extends ReasonTagsOf<E, ErrorTag>, R extends Result<unknown, unknown>>(errorTag: ErrorTag, reasonTag: ReasonTag, f: (reason: ReasonForTag<E, ErrorTag, ReasonTag>, error: ErrorForTag$1<E, ErrorTag>) => R) => Result<T | InferOkTypes<R>, ExcludeReasonTag<E, ErrorTag, ReasonTag> | InferErrTypes<R>>;
+  /**
+  * Recovers from multiple nested tagged `reason` variants on a specific tagged error.
+  */
+  catchReasons: <const ErrorTag extends TagsWithReasonOf<E>, const Handlers extends object>(errorTag: ErrorTag, handlers: Handlers & ResultCatchReasonHandlers<E, ErrorTag, Handlers>) => Result<T | InferOkTypes<CatchReasonHandlerResult<Handlers>>, ExcludeReasonTag<E, ErrorTag, keyof Handlers & string> | InferErrTypes<CatchReasonHandlerResult<Handlers>>>;
+  /**
+  * Moves the nested `reason` of a tagged error into the Result error channel.
+  */
+  unwrapReason: <const ErrorTag extends TagsWithReasonOf<E>>(errorTag: ErrorTag) => Result<T, ExcludeTag<E, ErrorTag> | ReasonsOf<E, ErrorTag>>;
+  /**
+  * Chains an async fallible operation from the Ok value.
+  */
+  asyncAndThen: <X, Y>(f: (t: T) => ResultAsync<X, Y>) => ResultAsync<X, E | Y>;
+  /**
+  * Maps the Ok value with an async function and returns a `ResultAsync`.
+  */
+  asyncMap: <X>(f: (t: T) => Promise<X>) => ResultAsync<X, E>;
+  /**
+  * Converts this Result into a plain value by handling both Ok and Err.
+  */
+  match: {
+    <A, B = A>(handlers: MatchHandlers$1<T, E, A, B>): A | B;
+    <A, B = A>(fnOk: MatchOkHandler<T, A>, fnErr: MatchErrorHandler<E, B>): A | B;
+  };
+  /**
+  * Converts this Result into a plain value with exhaustive tagged-error handlers.
+  */
+  matchTags: <A, const Handlers extends object>(fnOk: (t: T) => A, handlers: Handlers & MatchTagHandlers<E, Handlers>) => A | MatchTagHandlerResult<Handlers>;
+  /**
+  * Converts this Result into a plain value with partial tagged-error handlers and a fallback.
+  */
+  matchTagsPartial: <A, B, const Handlers extends object>(fnOk: (t: T) => A, handlers: Handlers & PartialMatchTagHandlers<E, Handlers>, fallback: (error: E) => B) => A | MatchTagHandlerResult<Handlers> | B;
+  /**
+  * Pipes this Result through reusable transformation functions.
+  */
+  pipe: {
+    <A>(ab: PipeFn<Result<T, E>, A>): A;
+    <A, B>(ab: PipeFn<Result<T, E>, A>, bc: PipeFn<A, B>): B;
+    <A, B, C>(ab: PipeFn<Result<T, E>, A>, bc: PipeFn<A, B>, cd: PipeFn<B, C>): C;
+  };
+  /**
+  * Runs a side effect with the Ok or Err value and returns this same Result.
+  *
+  * Exceptions thrown by the side effect are swallowed.
+  */
+  log: (fn: (t?: T, e?: E) => void) => this;
+  /**
+  * Runs a side effect only when this result is Ok and returns this same Result.
+  *
+  * Exceptions thrown by the side effect are swallowed.
+  */
+  tap: (fn: (t: T) => void) => this;
+  /**
+  * Runs a side effect only when this result is Err and returns this same Result.
+  *
+  * Exceptions thrown by the side effect are swallowed.
+  */
+  tapError: (fn: (e: E) => void) => this;
+  /**
+  * Attaches a synchronous disposal finalizer to this Result.
+  */
+  toDisposable: (f: ResultFinalizer<T, E>) => DisposableResult<T, E>;
+  /**
+  * Returns the Ok value or throws the Err value.
+  *
+  * Use this at final application boundaries after the error channel has been modeled.
+  */
+  unwrapOrThrow: () => T;
+  /**
+  * Enables `yield* result` inside `safeTry` generators.
+  */
+  [Symbol.iterator]: () => Generator<Result<never, E>, T>;
+  /**
+  * Compatibility generator for `safeTry`. Prefer `yield* result` in new code.
+  */
+  safeUnwrap: () => Generator<Result<never, E>, T>;
 }
 interface OkResult<T, E> extends ResultOperations<T, E> {
+  /**
+  * Ok value carried by this result.
+  */
   readonly value: T;
 }
 interface ErrResult<T, E> extends ResultOperations<T, E> {
+  /**
+  * Err value carried by this result.
+  */
   readonly error: E;
 }
 type Result<T, E> = OkResult<T, E> | ErrResult<T, E>;
 type StrictResult<T, E extends Error = Error> = Result<T, E>;
+/**
+* Object form accepted by `tryResult`.
+*
+* Use this form when named `try` and `catch` fields make a synchronous boundary easier to read.
+*/
 interface TryResultOptions<T, E = unknown> {
+  /**
+  * Runs the synchronous work whose thrown value should become `Err<E>`.
+  */
   readonly try: () => Exclude<T, Promise<unknown>>;
+  /**
+  * Converts a thrown `unknown` cause into the typed Resultar error channel.
+  *
+  * If omitted, the error channel is `unknown`.
+  */
   readonly catch?: (e: unknown) => E;
 }
 interface SafeTryOptions<YieldErr extends Result<never, unknown>, GeneratorReturnResult extends Result<unknown, unknown>, CatchErr = never> {
+  /**
+  * Generator body evaluated by `safeTry`.
+  *
+  * Use `yield* result` to unwrap Resultar values and short-circuit on Err.
+  */
   readonly try: () => Generator<YieldErr, GeneratorReturnResult>;
+  /**
+  * Converts synchronous throws from the generator setup into the Result error channel.
+  */
   readonly catch?: (e: unknown) => CatchErr;
 }
 interface SafeTryAsyncOptions<YieldErr extends Result<never, unknown>, GeneratorReturnResult extends Result<unknown, unknown>, CatchErr = never> {
+  /**
+  * Async generator body evaluated by `safeTry`.
+  *
+  * Use `yield* result` or `yield* resultAsync` to unwrap Resultar values and short-circuit on Err.
+  */
   readonly try: () => AsyncGenerator<YieldErr, GeneratorReturnResult>;
+  /**
+  * Converts synchronous throws or async rejections from the generator setup into the ResultAsync
+  * error channel.
+  */
   readonly catch?: (e: unknown) => CatchErr;
 }
 interface ResultStatic {
-  [Symbol.hasInstance](value: unknown): boolean;
   /**
+  * Runtime `instanceof Result` support for Ok and Err values.
+  */
+  [Symbol.hasInstance]: (value: unknown) => boolean;
+  /**
+  * Runs synchronous work and captures thrown values into a Result.
+  *
   * Compatibility alias. Prefer the top-level `tryResult` helper in new code.
   */
-  tryCatch<T, E>(this: void, fn: () => Exclude<T, Promise<unknown>>, errorFn?: (e: unknown) => E): Result<T, E>;
-  fromThrowable<Fn extends (...args: readonly any[]) => unknown, E>(this: void, fn: Fn, errorFn?: (e: any) => E): (...args: Parameters<Fn>) => Result<ReturnType<Fn>, E>;
-  ok<T, E = never>(this: void, value: T): OkResult<T, E>;
-  ok<E = never>(this: void, value: void): OkResult<void, E>;
-  unit<E = never>(this: void): Result<undefined, E>;
-  err<T = never, E extends string = string>(this: void, err: E): ErrResult<T, E>;
-  err<T = never, E = unknown>(this: void, err: E): ErrResult<T, E>;
-  err<T = never>(this: void, err: void): ErrResult<T, void>;
-  combine<T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]>(this: void, resultList: T): CombineResults<T>;
-  combine<T extends readonly Result<unknown, unknown>[]>(this: void, resultList: T): CombineResults<T>;
-  combine<T extends ResultRecord>(this: void, resultRecord: T): CombineResultsRecord<T>;
-  combine<R extends Result<unknown, unknown>>(this: void, results: Iterable<R>): CombineResultsIterable<R>;
-  combineWithAllErrors<T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
-  combineWithAllErrors<T extends readonly Result<unknown, unknown>[]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
-  combineWithAllErrors<T extends ResultRecord>(this: void, resultRecord: T): CombineResultsRecordWithAllErrors<T>;
-  combineWithAllErrors<R extends Result<unknown, unknown>>(this: void, results: Iterable<R>): CombineResultsIterableWithAllErrors<R>;
-  validateAll<T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
-  validateAll<T extends readonly Result<unknown, unknown>[]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
-  validateAll<Item, R extends Result<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R): ResultValidatedAll<R>;
-  zip<Left extends Result<unknown, unknown>, Right extends Result<unknown, unknown>>(this: void, left: Left, right: Right): ResultZipped<Left, Right>;
-  firstSuccessOf<Candidates extends Iterable<ResultCandidate>>(this: void, candidates: Candidates): FirstSuccessOf<Candidates>;
-  if<OnTrue extends Result<unknown, unknown>, OnFalse extends Result<unknown, unknown>>(this: void, condition: ResultBooleanCondition, options: ResultIfOptions<OnTrue, OnFalse>): ResultIf<never, OnTrue, OnFalse>;
-  if<Condition extends Result<boolean, unknown>, OnTrue extends Result<unknown, unknown>, OnFalse extends Result<unknown, unknown>>(this: void, condition: Condition, options: ResultIfOptions<OnTrue, OnFalse>): ResultIf<InferErrTypes<Condition>, OnTrue, OnFalse>;
-  when<R extends Result<unknown, unknown>>(this: void, condition: ResultBooleanCondition, body: () => R): ResultWhen<R>;
-  whenResult<Condition extends Result<boolean, unknown>, R extends Result<unknown, unknown>>(this: void, condition: Condition, body: () => R): ResultWhenWithCondition<Condition, R>;
-  unless<R extends Result<unknown, unknown>>(this: void, condition: ResultBooleanCondition, body: () => R): ResultWhen<R>;
-  unlessResult<Condition extends Result<boolean, unknown>, R extends Result<unknown, unknown>>(this: void, condition: Condition, body: () => R): ResultWhenWithCondition<Condition, R>;
-  loop<State, BodyState extends State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopOptions<State, BodyState, R>): ResultLoopCollected<R>;
-  loop<State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopBooleanOptions<State, R>): ResultLoopCollected<R>;
-  loop<State, BodyState extends State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopDiscardOptions<State, BodyState, R>): ResultLoopDiscarded<R>;
-  loop<State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopBooleanDiscardOptions<State, R>): ResultLoopDiscarded<R>;
-  iterate<State, BodyState extends WidenLiteral$1<State>, R extends Result<WidenLiteral$1<State>, unknown>>(this: void, initial: State, options: ResultIterateOptions<WidenLiteral$1<State>, BodyState, R>): ResultIterated<WidenLiteral$1<State>, R>;
-  iterate<State, R extends Result<WidenLiteral$1<State>, unknown>>(this: void, initial: State, options: ResultIterateBooleanOptions<WidenLiteral$1<State>, R>): ResultIterated<WidenLiteral$1<State>, R>;
-  forEach<Item, R extends Result<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options?: ResultForEachOptions): ResultForEachCollected<R>;
-  forEach<Item, R extends Result<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options: ResultForEachDiscardOptions): ResultForEachDiscarded<R>;
+  tryCatch: <T, E>(this: void, fn: () => Exclude<T, Promise<unknown>>, errorFn?: (e: unknown) => E) => Result<T, E>;
+  /**
+  * Wraps a throwing synchronous function so every later call returns a Result.
+  */
+  fromThrowable: <Fn extends (...args: readonly any[]) => unknown, E>(this: void, fn: Fn, errorFn?: (e: any) => E) => (...args: Parameters<Fn>) => Result<ReturnType<Fn>, E>;
+  /**
+  * Creates an Ok result.
+  */
+  ok: {
+    <T, E = never>(this: void, value: T): OkResult<T, E>;
+    <E = never>(this: void, value: void): OkResult<void, E>;
+  };
+  /**
+  * Creates an Ok result with `undefined`.
+  */
+  unit: <E = never>(this: void) => Result<undefined, E>;
+  /**
+  * Creates an Err result.
+  */
+  err: {
+    <T = never, E extends string = string>(this: void, err: E): ErrResult<T, E>;
+    <T = never, E = unknown>(this: void, err: E): ErrResult<T, E>;
+    <T = never>(this: void, err: void): ErrResult<T, void>;
+  };
+  /**
+  * Combines many Result values and stops at the first Err.
+  *
+  * Arrays return an Ok array, records return an Ok record with the same keys, and iterables return
+  * an Ok readonly array.
+  */
+  combine: {
+    <T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]>(this: void, resultList: T): CombineResults<T>;
+    <T extends readonly Result<unknown, unknown>[]>(this: void, resultList: T): CombineResults<T>;
+    <T extends ResultRecord>(this: void, resultRecord: T): CombineResultsRecord<T>;
+    <R extends Result<unknown, unknown>>(this: void, results: Iterable<R>): CombineResultsIterable<R>;
+  };
+  /**
+  * Combines many Result values and collects every Err instead of stopping at the first one.
+  */
+  combineWithAllErrors: {
+    <T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
+    <T extends readonly Result<unknown, unknown>[]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
+    <T extends ResultRecord>(this: void, resultRecord: T): CombineResultsRecordWithAllErrors<T>;
+    <R extends Result<unknown, unknown>>(this: void, results: Iterable<R>): CombineResultsIterableWithAllErrors<R>;
+  };
+  /**
+  * Validates many Result values and collects every Err.
+  *
+  * When passed items plus a mapper, the mapper must return a Result for each item.
+  */
+  validateAll: {
+    <T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
+    <T extends readonly Result<unknown, unknown>[]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
+    <Item, R extends Result<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R): ResultValidatedAll<R>;
+  };
+  /**
+  * Combines exactly two Result values into an Ok tuple or the first Err.
+  */
+  zip: <Left extends Result<unknown, unknown>, Right extends Result<unknown, unknown>>(this: void, left: Left, right: Right) => ResultZipped<Left, Right>;
+  /**
+  * Runs candidates until the first Ok and returns the last Err if every candidate fails.
+  */
+  firstSuccessOf: <Candidates extends Iterable<ResultCandidate>>(this: void, candidates: Candidates) => FirstSuccessOf<Candidates>;
+  /**
+  * Chooses one of two Result branches from a boolean or Result boolean condition.
+  */
+  if: {
+    <OnTrue extends Result<unknown, unknown>, OnFalse extends Result<unknown, unknown>>(this: void, condition: ResultBooleanCondition, options: ResultIfOptions<OnTrue, OnFalse>): ResultIf<never, OnTrue, OnFalse>;
+    <Condition extends Result<boolean, unknown>, OnTrue extends Result<unknown, unknown>, OnFalse extends Result<unknown, unknown>>(this: void, condition: Condition, options: ResultIfOptions<OnTrue, OnFalse>): ResultIf<InferErrTypes<Condition>, OnTrue, OnFalse>;
+  };
+  /**
+  * Runs `body` only when the condition is true; otherwise returns Ok(undefined).
+  */
+  when: <R extends Result<unknown, unknown>>(this: void, condition: ResultBooleanCondition, body: () => R) => ResultWhen<R>;
+  /**
+  * Runs `body` only when a Result boolean condition is Ok(true).
+  */
+  whenResult: <Condition extends Result<boolean, unknown>, R extends Result<unknown, unknown>>(this: void, condition: Condition, body: () => R) => ResultWhenWithCondition<Condition, R>;
+  /**
+  * Runs `body` only when the condition is false; otherwise returns Ok(undefined).
+  */
+  unless: <R extends Result<unknown, unknown>>(this: void, condition: ResultBooleanCondition, body: () => R) => ResultWhen<R>;
+  /**
+  * Runs `body` only when a Result boolean condition is Ok(false).
+  */
+  unlessResult: <Condition extends Result<boolean, unknown>, R extends Result<unknown, unknown>>(this: void, condition: Condition, body: () => R) => ResultWhenWithCondition<Condition, R>;
+  /**
+  * Repeats a Result-producing body while a condition holds.
+  *
+  * Use `discard: true` when only failure matters and collected Ok values are not needed.
+  */
+  loop: {
+    <State, BodyState extends State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopOptions<State, BodyState, R>): ResultLoopCollected<R>;
+    <State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopBooleanOptions<State, R>): ResultLoopCollected<R>;
+    <State, BodyState extends State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopDiscardOptions<State, BodyState, R>): ResultLoopDiscarded<R>;
+    <State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopBooleanDiscardOptions<State, R>): ResultLoopDiscarded<R>;
+  };
+  /**
+  * Repeatedly transforms state with a Result-producing body until the condition fails.
+  */
+  iterate: {
+    <State, BodyState extends WidenLiteral$1<State>, R extends Result<WidenLiteral$1<State>, unknown>>(this: void, initial: State, options: ResultIterateOptions<WidenLiteral$1<State>, BodyState, R>): ResultIterated<WidenLiteral$1<State>, R>;
+    <State, R extends Result<WidenLiteral$1<State>, unknown>>(this: void, initial: State, options: ResultIterateBooleanOptions<WidenLiteral$1<State>, R>): ResultIterated<WidenLiteral$1<State>, R>;
+  };
+  /**
+  * Runs a Result-producing mapper for each item.
+  *
+  * Use `discard: true` when only failure matters and collected Ok values are not needed.
+  */
+  forEach: {
+    <Item, R extends Result<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options?: ResultForEachOptions): ResultForEachCollected<R>;
+    <Item, R extends Result<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options: ResultForEachDiscardOptions): ResultForEachDiscarded<R>;
+  };
 }
 declare const Result: ResultStatic;
 /**
@@ -295,28 +532,54 @@ declare const Result: ResultStatic;
 declare class DisposableResult<T, E> implements Resultable<T, E>, Disposable {
   private disposed;
   private readonly finalizer;
+  /**
+  * Wrapped Result value.
+  */
   readonly result: Result<T, E>;
+  /**
+  * Creates a disposable wrapper around a Result.
+  */
   constructor(result: Result<T, E>, finalizer: ResultFinalizer<T, E>);
+  /**
+  * Ok value when present, otherwise undefined cast to `T` for compatibility.
+  */
   get value(): T;
+  /**
+  * Err value when present, otherwise undefined cast to `E` for compatibility.
+  */
   get error(): E;
+  /**
+  * Delegates to the wrapped Result `_unsafeUnwrap`.
+  */
   _unsafeUnwrap(config?: ErrorConfig): T;
+  /**
+  * Delegates to the wrapped Result `_unsafeUnwrapErr`.
+  */
   _unsafeUnwrapErr(config?: ErrorConfig): E;
+  /**
+  * Returns whether the wrapped Result is Ok.
+  */
   isOk(): boolean;
+  /**
+  * Returns whether the wrapped Result is Err.
+  */
   isErr(): boolean;
+  /**
+  * Returns the wrapped Ok value, or `defaultValue` when Err.
+  */
   unwrapOr<A>(defaultValue: A): T | A;
+  /**
+  * Runs the finalizer once.
+  *
+  * Finalizer exceptions are intentionally swallowed.
+  */
   [Symbol.dispose](): void;
 }
 /**
-* Evaluates the given generator to a Result returned or an Err yielded from it,
-* whichever comes first.
-*
-* This function, in combination with `Result.safeUnwrap()`, is intended to emulate
-* Rust's ? operator.
-* See `/tests/safeTry.test.ts` for examples.
+* Evaluates a synchronous generator and returns the first yielded Err or returned Result.
 *
-* @param body - What is evaluated. In body, `yield* result.safeUnwrap()` works as
-* Rust's `result?` expression.
-* @returns The first occurence of either an yielded Err or a returned Result.
+* Inside the generator, use `yield* result` to unwrap Ok values and short-circuit on Err. The object
+* form can map thrown setup errors into the Result error channel.
 */
 declare function safeTry<T, E, CatchErr = E>(input: SafeTryOptions<Result<never, E>, Result<T, E>, CatchErr> & {
   readonly catch: (e: unknown) => CatchErr;
@@ -327,16 +590,12 @@ declare function safeTry<YieldErr extends Result<never, unknown>, GeneratorRetur
 }): Result<InferOkTypes<GeneratorReturnResult>, InferErrTypes<YieldErr> | InferErrTypes<GeneratorReturnResult> | CatchErr>;
 declare function safeTry<YieldErr extends Result<never, unknown>, GeneratorReturnResult extends Result<unknown, unknown>>(input: (() => Generator<YieldErr, GeneratorReturnResult>) | SafeTryOptions<YieldErr, GeneratorReturnResult>): Result<InferOkTypes<GeneratorReturnResult>, InferErrTypes<YieldErr> | InferErrTypes<GeneratorReturnResult>>;
 /**
-* Evaluates the given generator to a Result returned or an Err yielded from it,
-* whichever comes first.
+* Evaluates an async generator and returns a ResultAsync for the first yielded Err or returned
+* Result.
 *
-* This function, in combination with `Result.safeUnwrap()`, is intended to emulate
-* Rust's ? operator.
-* See `/tests/safeTry.test.ts` for examples.
-*
-* @param body - What is evaluated. In body, `yield* result.safeUnwrap()`,
-* `yield* result`, and `yield* resultAsync` work as Rust's `result?` expression.
-* @returns The first occurence of either an yielded Err or a returned Result.
+* Inside the generator, use `yield* result` or `yield* resultAsync` to unwrap Ok values and
+* short-circuit on Err. The object form can map thrown or rejected setup errors into the ResultAsync
+* error channel.
 */
 declare function safeTry<T, E, CatchErr = E>(input: SafeTryAsyncOptions<Result<never, E>, Result<T, E>, CatchErr> & {
   readonly catch: (e: unknown) => CatchErr;
@@ -346,18 +605,66 @@ declare function safeTry<YieldErr extends Result<never, unknown>, GeneratorRetur
   readonly catch: (e: unknown) => CatchErr;
 }): ResultAsync<InferOkTypes<GeneratorReturnResult>, InferErrTypes<YieldErr> | InferErrTypes<GeneratorReturnResult> | CatchErr>;
 declare function safeTry<YieldErr extends Result<never, unknown>, GeneratorReturnResult extends Result<unknown, unknown>>(input: (() => AsyncGenerator<YieldErr, GeneratorReturnResult>) | SafeTryAsyncOptions<YieldErr, GeneratorReturnResult>): ResultAsync<InferOkTypes<GeneratorReturnResult>, InferErrTypes<YieldErr> | InferErrTypes<GeneratorReturnResult>>;
+/**
+* Creates an Ok result.
+*/
 declare function ok<T, E = never>(value: T): OkResult<T, E>;
 declare function ok<E = never>(value: void): OkResult<void, E>;
+/**
+* Creates an Err result.
+*/
 declare function err<T = never, E extends string = string>(err: E): ErrResult<T, E>;
 declare function err<T = never, E = unknown>(err: E): ErrResult<T, E>;
 declare function err<T = never>(err: void): ErrResult<T, void>;
+/**
+* Wraps a throwing synchronous function so every later call returns a Result.
+*
+* Prefer `tryResult` when you want to run the operation immediately.
+*/
 declare const fromThrowable: typeof Result.fromThrowable;
+/**
+* Runs synchronous work and captures thrown values into `Result<T, E>`.
+*
+* Use `tryResult` at the edge of uncontrolled synchronous code: JSON parsing, environment parsing,
+* platform APIs, or third-party functions that may throw. The mapper receives the thrown `unknown`
+* cause and returns the typed error for the Resultar channel.
+*
+* @example
+* ```ts
+* const config = tryResult(
+*   () => JSON.parse(input) as Config,
+*   (cause) => new ParseConfigError({ cause }),
+* )
+* ```
+*/
 declare function tryResult<T, E>(fn: () => Exclude<T, Promise<unknown>>, errorFn: (e: unknown) => E): Result<T, E>;
+/**
+* Captures a synchronous boundary with named `try` and `catch` fields.
+*
+* This is equivalent to `tryResult(() => ..., toError)`, but it reads better when the boundary has
+* a clear domain name or label.
+*/
 declare function tryResult<T, E>(options: TryResultOptions<T, E> & {
   readonly catch: (e: unknown) => E;
 }): Result<T, E>;
+/**
+* Runs synchronous work and captures thrown values into `Result<T, unknown>`.
+*
+* Prefer the overload with a catch mapper in application code so the error channel stays documented.
+* This overload is useful while adapting unknown external failures or during migration.
+*/
 declare function tryResult<T>(input: (() => Exclude<T, Promise<unknown>>) | TryResultOptions<T>): Result<T, unknown>;
+/**
+* Creates an Ok result with `undefined`.
+*/
 declare function unit<E = never>(): OkResult<undefined, E>;
+/**
+* Runs a `Result` at an application boundary and returns the success value.
+*
+* If the result is `Err`, this throws the error. Use it at final framework, CLI, test, or bootstrap
+* boundaries after the error channel has already been modeled with Resultar.
+*/
+declare const runSync: <T, E>(result: Result<T, E>) => T;
 /** Compatibility alias. Prefer `tryResult` in new code. */
 declare const tryCatch: typeof tryResult;
 type Prev = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, ...0[]];
@@ -378,81 +685,226 @@ type CombineResults<T extends readonly Result<unknown, unknown>[]> = IsLiteralAr
 type CombineResultsWithAllErrorsArray<T extends readonly Result<unknown, unknown>[]> = IsLiteralArray<T> extends 1 ? TraverseWithAllErrors<T> : Result<ExtractOkTypes<T>, ExtractErrTypes<T>[number][]>;
 //#endregion
 //#region src/abort-error.d.ts
+/**
+* Standard cancellation error used by ResultAsync retry, race, timeout, and resource helpers.
+*/
 declare class AbortError extends Error {
+  /**
+  * Creates an AbortError.
+  */
   constructor(message?: string, options?: ErrorOptions);
 }
+/**
+* Checks whether a value is an AbortError or abort-shaped platform error.
+*/
 declare const isAbortError: (value: unknown) => value is AbortError;
 //#endregion
 //#region src/result-async.d.ts
 type ResultAsyncFinalizer<T, E> = (value: T | undefined, error: E | undefined) => void | Promise<void>;
+/**
+* Object form accepted by `tryResultAsync`.
+*
+* Use this form when named `try` and `catch` fields make an async boundary easier to read, or when
+* you want the mapper next to the promise factory.
+*/
 interface TryResultAsyncOptions<T, E = unknown> {
+  /**
+  * Creates the promise whose rejection should become `Err<E>`.
+  *
+  * Synchronous throws from this function are also captured.
+  */
   readonly try: () => Promise<T>;
+  /**
+  * Converts a rejected or thrown `unknown` cause into the typed Resultar error channel.
+  *
+  * If omitted, the error channel is `unknown`.
+  */
   readonly catch?: (e: unknown) => E;
 }
 interface ResultAsyncAbortSignal {
+  /**
+  * Whether the cooperative async operation has been aborted.
+  */
   readonly aborted: boolean;
+  /**
+  * Optional abort cause provided by the losing race, timeout, or caller.
+  */
   readonly reason?: unknown;
-  addEventListener(type: "abort", listener: () => void, options?: {
+  /**
+  * Registers an abort listener.
+  */
+  addEventListener: (type: "abort", listener: () => void, options?: {
     readonly once?: boolean;
-  }): void;
-  removeEventListener(type: "abort", listener: () => void): void;
+  }) => void;
+  /**
+  * Removes an abort listener.
+  */
+  removeEventListener: (type: "abort", listener: () => void) => void;
 }
+/**
+* Concurrency setting for async collection helpers.
+*
+* Use a number for bounded parallelism or `'unbounded'` when every task may start immediately.
+*/
 type ResultAsyncConcurrency = number | "unbounded";
 type HandlerOk<R> = InferOkTypes<R> | InferAsyncOkTypes<R>;
 type HandlerErr<R> = InferErrTypes<R> | InferAsyncErrTypes<R>;
 type IterableElement<T> = T extends Iterable<infer Element> ? Element : never;
+/**
+* Candidate used by `ResultAsync.firstSuccessOf`.
+*/
 type ResultAsyncCandidate = () => ResultAsync<unknown, unknown>;
 type ResultAsyncRecord = Readonly<Record<string, ResultAsync<unknown, unknown>>>;
 type CombineResultAsyncsRecord<T extends ResultAsyncRecord> = ResultAsync<{ readonly [Key in keyof T]: InferAsyncOkTypes<T[Key]> }, InferAsyncErrTypes<T[keyof T]>>;
 type CombineResultAsyncsRecordWithAllErrors<T extends ResultAsyncRecord> = ResultAsync<{ readonly [Key in keyof T]: InferAsyncOkTypes<T[Key]> }, InferAsyncErrTypes<T[keyof T]>[]>;
 type CombineResultAsyncsIterable<R extends ResultAsync<unknown, unknown>> = ResultAsync<readonly InferAsyncOkTypes<R>[], InferAsyncErrTypes<R>>;
 type CombineResultAsyncsIterableWithAllErrors<R extends ResultAsync<unknown, unknown>> = ResultAsync<readonly InferAsyncOkTypes<R>[], InferAsyncErrTypes<R>[]>;
+/**
+* Task used by race, timeout, and retry helpers.
+*
+* The signal lets the task cooperate with cancellation when another task wins or a timeout fires.
+*/
 type ResultAsyncRaceTask<T, E> = (signal: ResultAsyncAbortSignal) => ResultAsync<T, E>;
 type ResultAsyncRaceTaskOk<Task> = Task extends ResultAsyncRaceTask<infer T, unknown> ? T : never;
 type ResultAsyncRaceTaskErr<Task> = Task extends ResultAsyncRaceTask<unknown, infer E> ? E : never;
 type ResultAsyncRaceTasksOk<Tasks extends readonly ResultAsyncRaceTask<unknown, unknown>[]> = ResultAsyncRaceTaskOk<Tasks[number]>;
 type ResultAsyncRaceTasksErr<Tasks extends readonly ResultAsyncRaceTask<unknown, unknown>[]> = ResultAsyncRaceTaskErr<Tasks[number]>;
 interface ResultAsyncRaceHandle<T, E> {
+  /**
+  * Abort signal associated with the running task.
+  */
   readonly signal: ResultAsyncAbortSignal;
-  abort(reason?: unknown): void;
-  wait(): ResultAsync<T, E>;
+  /**
+  * Aborts the running task with an optional reason.
+  */
+  abort: (reason?: unknown) => void;
+  /**
+  * Waits for the task to settle as a ResultAsync.
+  */
+  wait: () => ResultAsync<T, E>;
 }
+/**
+* Options for `ResultAsync.timeout`.
+*/
 interface ResultAsyncTimeoutOptions<E> {
+  /**
+  * Creates the typed timeout error when the timeout wins.
+  */
   readonly onTimeout: () => E;
+  /**
+  * Timeout duration in milliseconds.
+  */
   readonly timeoutMs: number;
 }
+/**
+* Metadata passed to retry predicates, delays, callbacks, and fallback handlers.
+*/
 interface ResultAsyncRetryContext {
+  /**
+  * Current attempt number, starting at 1.
+  */
   readonly attempt: number;
+  /**
+  * Next attempt number if another retry is scheduled.
+  */
   readonly nextAttempt: number;
+  /**
+  * Number of retries still available after the current failure.
+  */
   readonly retriesRemaining: number;
 }
+/**
+* Task used by `ResultAsync.retry` and `ResultAsync.retryOrElse`.
+*/
 type ResultAsyncRetryTask<T, E> = (attempt: number, signal: ResultAsyncAbortSignal) => ResultAsync<T, E>;
 type ResultAsyncRetryTaskOk<Task> = Task extends ResultAsyncRetryTask<infer T, unknown> ? T : never;
 type ResultAsyncRetryTaskErr<Task> = Task extends ResultAsyncRetryTask<unknown, infer E> ? E : never;
 type ResultAsyncRetryDelay = number | ((context: ResultAsyncRetryContext) => number);
 interface ResultAsyncRetryOptions<E> {
+  /**
+  * Delay in milliseconds before retrying. Functions receive retry context.
+  */
   readonly delayMs?: ResultAsyncRetryDelay;
+  /**
+  * Randomizes the computed delay by this percentage factor.
+  *
+  * For example, `0.5` means 50% below to 50% above the computed delay.
+  */
   readonly jittered?: number;
+  /**
+  * Side effect called after a failed attempt that will be retried.
+  */
   readonly onRetry?: (error: E, context: ResultAsyncRetryContext) => void | Promise<void>;
+  /**
+  * Optional external abort signal for the retry loop.
+  */
   readonly signal?: ResultAsyncAbortSignal;
+  /**
+  * Maximum number of retries after the initial attempt.
+  */
   readonly times: number;
+  /**
+  * Predicate deciding whether a failure is retryable.
+  */
   readonly while?: (error: E, context: ResultAsyncRetryContext) => boolean | Promise<boolean>;
 }
+/**
+* Options for `ResultAsync.retryOrElse`.
+*/
 interface ResultAsyncRetryOrElseOptions<E, F, U> extends ResultAsyncRetryOptions<E> {
+  /**
+  * Fallback Resultar operation used after retry exhaustion.
+  */
   readonly orElse: (error: E, context: ResultAsyncRetryContext) => Result<U, F> | ResultAsync<U, F>;
 }
+/**
+* Acquires a resource for `ResultAsync.withResource`.
+*/
 type ResultAsyncResourceAcquire<Resource, E> = (signal: ResultAsyncAbortSignal) => ResultAsync<Resource, E>;
+/**
+* Operation accepted by `ResultAsync.withResource` use/release callbacks.
+*/
 type ResultAsyncResourceEffect<T, E> = Result<T, E> | ResultAsync<T, E>;
+/**
+* Uses an acquired resource inside `ResultAsync.withResource`.
+*/
 type ResultAsyncResourceUse<Resource, T, E> = (resource: Resource, signal: ResultAsyncAbortSignal) => ResultAsyncResourceEffect<T, E>;
+/**
+* Context passed to resource release callbacks.
+*/
 interface ResultAsyncResourceReleaseContext {
+  /**
+  * Result produced by the use phase, or undefined when acquisition failed.
+  */
   readonly result: Result<unknown, unknown> | undefined;
+  /**
+  * Abort signal shared by the resource lifecycle.
+  */
   readonly signal: ResultAsyncAbortSignal;
 }
+/**
+* Releases a resource after use, regardless of success or failure.
+*/
 type ResultAsyncResourceRelease<Resource> = (resource: Resource, context: ResultAsyncResourceReleaseContext) => ResultAsyncResourceEffect<unknown, unknown> | Promise<void> | void;
+/**
+* Options for `ResultAsync.withResource`.
+*/
 interface ResultAsyncWithResourceOptions<Resource, AcquireError, T, UseError> {
+  /**
+  * Acquires the resource.
+  */
   readonly acquire: ResultAsyncResourceAcquire<Resource, AcquireError>;
+  /**
+  * Releases the resource after use.
+  */
   readonly release: ResultAsyncResourceRelease<Resource>;
+  /**
+  * Optional external abort signal for the full lifecycle.
+  */
   readonly signal?: ResultAsyncAbortSignal;
+  /**
+  * Uses the acquired resource.
+  */
   readonly use: ResultAsyncResourceUse<Resource, T, UseError>;
 }
 type FirstSuccessOfAsync<Candidates extends Iterable<ResultAsyncCandidate>> = ResultAsync<InferAsyncOkTypes<ReturnType<IterableElement<Candidates>>>, InferAsyncErrTypes<ReturnType<IterableElement<Candidates>>>>;
@@ -521,8 +973,19 @@ declare class DisposableResultAsync<T, E> implements PromiseLike<Result<T, E>>,
   private readonly innerPromise;
   private readonly finalizer;
   private disposed;
+  /**
+  * Creates an async disposable wrapper around a ResultAsync promise.
+  */
   constructor(res: Promise<Result<T, E>>, finalizer: ResultAsyncFinalizer<T, E>);
+  /**
+  * PromiseLike integration. Resolves to the wrapped Result.
+  */
   then<A, B>(successCallback?: (res: Result<T, E>) => A | PromiseLike<A>, failureCallback?: (reason: unknown) => B | PromiseLike<B>): PromiseLike<A | B>;
+  /**
+  * Runs the finalizer once after the wrapped Result resolves.
+  *
+  * Finalizer exceptions and rejections are intentionally swallowed.
+  */
   [Symbol.asyncDispose](): Promise<void>;
 }
 /**
@@ -618,86 +1081,234 @@ declare class ResultAsync<T, E> extends Pipeable implements PromiseLike<Result<T
   * @return {ResultAsync<T, E>} A ResultAsync instance with the given promise and error type E.
   */
   static fromPromise<T, E>(this: void, promise: PromiseLike<T>, errorFn: (e: unknown) => E): ResultAsync<T, E>;
+  /**
+  * Combines many ResultAsync values and stops at the first Err.
+  *
+  * Arrays return an Ok array, records return an Ok record with the same keys, and iterables return
+  * an Ok readonly array.
+  */
   static combine<T extends readonly [ResultAsync<unknown, unknown>, ...ResultAsync<unknown, unknown>[]]>(this: void, asyncResultList: T): CombineResultAsyncs<T>;
   static combine<T extends readonly ResultAsync<unknown, unknown>[]>(this: void, asyncResultList: T): CombineResultAsyncs<T>;
   static combine<T extends ResultAsyncRecord>(this: void, asyncResultRecord: T): CombineResultAsyncsRecord<T>;
   static combine<R extends ResultAsync<unknown, unknown>>(this: void, asyncResults: Iterable<R>): CombineResultAsyncsIterable<R>;
+  /**
+  * Combines many ResultAsync values and collects every Err instead of stopping at the first one.
+  */
   static combineWithAllErrors<T extends readonly [ResultAsync<unknown, unknown>, ...ResultAsync<unknown, unknown>[]]>(this: void, asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
   static combineWithAllErrors<T extends readonly ResultAsync<unknown, unknown>[]>(this: void, asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
   static combineWithAllErrors<T extends ResultAsyncRecord>(this: void, asyncResultRecord: T): CombineResultAsyncsRecordWithAllErrors<T>;
   static combineWithAllErrors<R extends ResultAsync<unknown, unknown>>(this: void, asyncResults: Iterable<R>): CombineResultAsyncsIterableWithAllErrors<R>;
+  /**
+  * Validates many ResultAsync values and collects every Err.
+  *
+  * When passed items plus a mapper, the mapper must return a ResultAsync for each item. Use the
+  * optional concurrency setting to bound parallel work.
+  */
   static validateAll<T extends readonly [ResultAsync<unknown, unknown>, ...ResultAsync<unknown, unknown>[]]>(this: void, asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
   static validateAll<T extends readonly ResultAsync<unknown, unknown>[]>(this: void, asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
   static validateAll<Item, R extends ResultAsync<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options?: ResultAsyncValidateAllOptions): ResultAsyncValidatedAll<R>;
+  /**
+  * Combines exactly two ResultAsync values into an Ok tuple or the first Err.
+  */
   static zip<Left extends ResultAsync<unknown, unknown>, Right extends ResultAsync<unknown, unknown>>(this: void, left: Left, right: Right): ResultAsyncZipped<Left, Right>;
+  /**
+  * Retries a ResultAsync task according to a typed retry policy.
+  *
+  * The returned error channel includes the task error and `AbortError`.
+  */
   static retry<Task extends ResultAsyncRetryTask<unknown, unknown>>(this: void, task: Task, options: ResultAsyncRetryOptions<ResultAsyncRetryTaskErr<Task>>): ResultAsync<ResultAsyncRetryTaskOk<Task>, ResultAsyncRetryTaskErr<Task> | AbortError>;
+  /**
+  * Retries a ResultAsync task and falls back to another Resultar operation after retry exhaustion.
+  */
   static retryOrElse<Task extends ResultAsyncRetryTask<unknown, unknown>, U, F>(this: void, task: Task, options: ResultAsyncRetryOrElseOptions<ResultAsyncRetryTaskErr<Task>, F, U>): ResultAsync<ResultAsyncRetryTaskOk<Task> | U, F | AbortError>;
+  /**
+  * Acquires, uses, and releases a resource with cleanup on every path.
+  *
+  * Release errors are intentionally not part of the success/error channel; model cleanup failures
+  * in `use` when they should affect control flow.
+  */
   static withResource<Resource, AcquireError, T, UseError>(this: void, options: ResultAsyncWithResourceOptions<Resource, AcquireError, T, UseError>): ResultAsync<T, AcquireError | UseError | AbortError>;
+  /**
+  * Races two cooperative ResultAsync tasks and returns the first settled Result.
+  */
   static race<Left extends ResultAsyncRaceTask<unknown, unknown>, Right extends ResultAsyncRaceTask<unknown, unknown>>(this: void, left: Left, right: Right): ResultAsync<ResultAsyncRaceTaskOk<Left> | ResultAsyncRaceTaskOk<Right>, ResultAsyncRaceTaskErr<Left> | ResultAsyncRaceTaskErr<Right>>;
+  /**
+  * Races multiple cooperative ResultAsync tasks and returns the first settled Result.
+  */
   static raceAll<Tasks extends readonly [ResultAsyncRaceTask<unknown, unknown>, ...ResultAsyncRaceTask<unknown, unknown>[]]>(this: void, tasks: Tasks): ResultAsync<ResultAsyncRaceTasksOk<Tasks>, ResultAsyncRaceTasksErr<Tasks>>;
+  /**
+  * Races two cooperative ResultAsync tasks and returns the first successful Ok.
+  *
+  * If both fail, the returned error is the final observed Err.
+  */
   static raceFirst<Left extends ResultAsyncRaceTask<unknown, unknown>, Right extends ResultAsyncRaceTask<unknown, unknown>>(this: void, left: Left, right: Right): ResultAsync<ResultAsyncRaceTaskOk<Left> | ResultAsyncRaceTaskOk<Right>, ResultAsyncRaceTaskErr<Left> | ResultAsyncRaceTaskErr<Right>>;
+  /**
+  * Races two cooperative ResultAsync tasks and lets handlers decide what to do when either side
+  * settles first.
+  *
+  * Handlers receive the settled Result and a handle to the still-running opposite task.
+  */
   static raceWith<Left extends ResultAsyncRaceTask<unknown, unknown>, Right extends ResultAsyncRaceTask<unknown, unknown>, OnLeftDone extends ResultAsyncConditional, OnRightDone extends ResultAsyncConditional>(this: void, left: Left, right: Right, handlers: {
     readonly onLeftDone: (result: Result<ResultAsyncRaceTaskOk<Left>, ResultAsyncRaceTaskErr<Left>>, right: ResultAsyncRaceHandle<ResultAsyncRaceTaskOk<Right>, ResultAsyncRaceTaskErr<Right>>) => OnLeftDone;
     readonly onRightDone: (result: Result<ResultAsyncRaceTaskOk<Right>, ResultAsyncRaceTaskErr<Right>>, left: ResultAsyncRaceHandle<ResultAsyncRaceTaskOk<Left>, ResultAsyncRaceTaskErr<Left>>) => OnRightDone;
   }): ResultAsync<HandlerOk<OnLeftDone> | HandlerOk<OnRightDone>, HandlerErr<OnLeftDone> | HandlerErr<OnRightDone>>;
+  /**
+  * Runs a cooperative ResultAsync task with a typed timeout error.
+  */
   static timeout<Task extends ResultAsyncRaceTask<unknown, unknown>, TimeoutError>(this: void, task: Task, options: ResultAsyncTimeoutOptions<TimeoutError>): ResultAsync<ResultAsyncRaceTaskOk<Task>, ResultAsyncRaceTaskErr<Task> | TimeoutError>;
+  /**
+  * Runs async candidates until the first Ok and returns the last Err if every candidate fails.
+  */
   static firstSuccessOf<Candidates extends Iterable<ResultAsyncCandidate>>(this: void, candidates: Candidates): FirstSuccessOfAsync<Candidates>;
+  /**
+  * Chooses one of two Resultar async branches from a boolean or Resultar boolean condition.
+  */
   static if<OnTrue extends ResultAsyncConditional, OnFalse extends ResultAsyncConditional>(this: void, condition: ResultAsyncBooleanCondition, options: ResultAsyncIfOptions<OnTrue, OnFalse>): ResultAsyncIf<never, OnTrue, OnFalse>;
   static if<Condition extends ResultAsyncConditionResult, OnTrue extends ResultAsyncConditional, OnFalse extends ResultAsyncConditional>(this: void, condition: Condition, options: ResultAsyncIfOptions<OnTrue, OnFalse>): ResultAsyncIf<HandlerErr<Condition>, OnTrue, OnFalse>;
+  /**
+  * Runs `body` only when the condition is true; otherwise returns Ok(undefined).
+  */
   static when<R extends ResultAsyncConditional>(this: void, condition: ResultAsyncBooleanCondition, body: () => R): ResultAsyncWhen<R>;
+  /**
+  * Runs `body` only when a Resultar boolean condition is Ok(true).
+  */
   static whenResult<Condition extends ResultAsyncConditionResult, R extends ResultAsyncConditional>(this: void, condition: Condition, body: () => R): ResultAsyncWhenWithCondition<Condition, R>;
+  /**
+  * Runs `body` only when the condition is false; otherwise returns Ok(undefined).
+  */
   static unless<R extends ResultAsyncConditional>(this: void, condition: ResultAsyncBooleanCondition, body: () => R): ResultAsyncWhen<R>;
+  /**
+  * Runs `body` only when a Resultar boolean condition is Ok(false).
+  */
   static unlessResult<Condition extends ResultAsyncConditionResult, R extends ResultAsyncConditional>(this: void, condition: Condition, body: () => R): ResultAsyncWhenWithCondition<Condition, R>;
+  /**
+  * Repeats a ResultAsync-producing body while a condition holds.
+  *
+  * Use `discard: true` when only failure matters and collected Ok values are not needed.
+  */
   static loop<State, BodyState extends State, R extends ResultAsync<unknown, unknown>>(this: void, initial: State, options: ResultAsyncLoopOptions<State, BodyState, R>): ResultAsyncLoopCollected<R>;
   static loop<State, R extends ResultAsync<unknown, unknown>>(this: void, initial: State, options: ResultAsyncLoopBooleanOptions<State, R>): ResultAsyncLoopCollected<R>;
   static loop<State, BodyState extends State, R extends ResultAsync<unknown, unknown>>(this: void, initial: State, options: ResultAsyncLoopDiscardOptions<State, BodyState, R>): ResultAsyncLoopDiscarded<R>;
   static loop<State, R extends ResultAsync<unknown, unknown>>(this: void, initial: State, options: ResultAsyncLoopBooleanDiscardOptions<State, R>): ResultAsyncLoopDiscarded<R>;
+  /**
+  * Repeatedly transforms state with a ResultAsync-producing body until the condition fails.
+  */
   static iterate<State, BodyState extends WidenLiteral<State>, R extends ResultAsync<WidenLiteral<State>, unknown>>(this: void, initial: State, options: ResultAsyncIterateOptions<WidenLiteral<State>, BodyState, R>): ResultAsyncIterated<WidenLiteral<State>, R>;
   static iterate<State, R extends ResultAsync<WidenLiteral<State>, unknown>>(this: void, initial: State, options: ResultAsyncIterateBooleanOptions<WidenLiteral<State>, R>): ResultAsyncIterated<WidenLiteral<State>, R>;
+  /**
+  * Runs a ResultAsync-producing mapper for each item.
+  *
+  * Use `discard: true` when only failure matters and collected Ok values are not needed. Use
+  * `concurrency` to bound parallel work.
+  */
   static forEach<Item, R extends ResultAsync<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options?: ResultAsyncForEachOptions): ResultAsyncForEachCollected<R>;
   static forEach<Item, R extends ResultAsync<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options: ResultAsyncForEachDiscardOptions): ResultAsyncForEachDiscarded<R>;
   /**
-  * Wraps a async function with a try catch, creating a new function with the same
-  * arguments but returning `Ok` if successful, `Err` if the function throws
+  * Wraps an async function so every later call returns a ResultAsync.
   *
-  * @param fn function to wrap with ok on success or err on failure
-  * @param errorFn when an error is thrown, this will wrap the error result if provided
-  * @returns a new function that returns a `ResultAsync`
+  * Prefer `tryResultAsync` when you want to run the operation immediately.
   */
   static fromThrowable<A extends readonly unknown[], T, E>(this: void, fn: (...args: A) => Promise<T>, errorFn?: (err: unknown) => E): (...args: A) => ResultAsync<T, E>;
   private readonly innerPromise;
+  /**
+  * Creates a ResultAsync from a Promise that resolves to a Result.
+  *
+  * Most application code should prefer `tryResultAsync`, `fromPromise`, `okAsync`, or `errAsync`.
+  */
   constructor(res: Promise<Result<T, E>>);
+  /**
+  * PromiseLike integration. Resolves to the underlying `Result<T, E>`.
+  *
+  * Prefer ResultAsync combinators for application flow; this exists so ResultAsync can be awaited
+  * and used by Promise APIs.
+  */
   then<A, B>(successCallback?: (res: Result<T, E>) => A | PromiseLike<A>, failureCallback?: (reason: unknown) => B | PromiseLike<B>): PromiseLike<A | B>;
+  /**
+  * Maps the Err value while preserving the Ok value.
+  */
   mapErr<U>(f: (t: E) => U | Promise<U>): ResultAsync<T, U>;
+  /**
+  * Maps the Ok value while preserving the error channel.
+  */
   map<X>(f: (t: T) => X | Promise<X>): ResultAsync<X, E>;
+  /**
+  * Replaces the Ok value with a constant while preserving the error channel.
+  */
   as<X>(value: X): ResultAsync<X, E>;
+  /**
+  * Keeps the Ok value only when the predicate passes; otherwise returns an Err from `onFalse`.
+  */
   filterOrElse<U extends T, F>(predicate: (value: T) => value is U, onFalse: (value: T) => F | Promise<F>): ResultAsync<U, E | F>;
   filterOrElse<F>(predicate: (value: T) => boolean | Promise<boolean>, onFalse: (value: T) => F | Promise<F>): ResultAsync<T, E | F>;
+  /**
+  * Chains another fallible sync or async operation from the Ok value.
+  *
+  * Use this instead of `map` when the callback returns `Result` or `ResultAsync`.
+  */
   andThen<R extends Result<unknown, unknown>>(f: (t: T) => R): ResultAsync<InferOkTypes<R>, InferErrTypes<R> | E>;
   andThen<R extends ResultAsync<unknown, unknown>>(f: (t: T) => R): ResultAsync<InferAsyncOkTypes<R>, InferAsyncErrTypes<R> | E>;
   andThen<U, F>(f: (t: T) => Result<U, F> | ResultAsync<U, F>): ResultAsync<U, E | F>;
+  /**
+  * Branches from the Ok value into one of two async fallible Result branches.
+  */
   if(fCondition: (t: T) => boolean): {
     true: <X1, Y1>(fTrue: (t: T) => ResultAsync<X1, Y1>) => {
       false: <X2, Y2>(fFalse: (t: T) => ResultAsync<X2, Y2>) => ResultAsync<X1 | X2, Y1 | Y2 | E>;
     };
   };
+  /**
+  * Recovers from Err with another Result or ResultAsync.
+  */
   orElse<R extends Result<unknown, unknown>>(f: (e: E) => R): ResultAsync<InferOkTypes<R> | T, InferErrTypes<R>>;
   orElse<R extends ResultAsync<unknown, unknown>>(f: (e: E) => R): ResultAsync<InferAsyncOkTypes<R> | T, InferAsyncErrTypes<R>>;
   orElse<U, A>(f: (e: E) => Result<U, A> | ResultAsync<U, A>): ResultAsync<U | T, A>;
+  /**
+  * Recovers from a specific tagged error by `_tag`.
+  */
   catchTag<const Tag extends TagsOf<E>, R extends Result<unknown, unknown>>(tag: Tag, f: (error: ErrorForTag$1<E, Tag>) => R): ResultAsync<T | InferOkTypes<R>, ExcludeTag<E, Tag> | InferErrTypes<R>>;
   catchTag<const Tag extends TagsOf<E>, R extends ResultAsync<unknown, unknown>>(tag: Tag, f: (error: ErrorForTag$1<E, Tag>) => R): ResultAsync<T | InferAsyncOkTypes<R>, ExcludeTag<E, Tag> | InferAsyncErrTypes<R>>;
   catchTag<U, F, const Tag extends TagsOf<E>>(tag: Tag, f: (error: ErrorForTag$1<E, Tag>) => Result<U, F> | ResultAsync<U, F>): ResultAsync<T | U, ExcludeTag<E, Tag> | F>;
+  /**
+  * Recovers from multiple tagged errors by `_tag`.
+  */
   catchTags<const Handlers extends object>(handlers: Handlers & ResultAsyncCatchTagHandlers<E, Handlers>): ResultAsync<T | HandlerOk<CatchTagHandlerResult<Handlers>>, ExcludeTag<E, keyof Handlers & string> | HandlerErr<CatchTagHandlerResult<Handlers>>>;
+  /**
+  * Recovers from a nested tagged `reason` on a specific tagged error.
+  */
   catchReason<const ErrorTag extends TagsWithReasonOf<E>, const ReasonTag extends ReasonTagsOf<E, ErrorTag>, R extends Result<unknown, unknown>>(errorTag: ErrorTag, reasonTag: ReasonTag, f: (reason: ReasonForTag<E, ErrorTag, ReasonTag>, error: ErrorForTag$1<E, ErrorTag>) => R): ResultAsync<T | InferOkTypes<R>, ExcludeReasonTag<E, ErrorTag, ReasonTag> | InferErrTypes<R>>;
   catchReason<const ErrorTag extends TagsWithReasonOf<E>, const ReasonTag extends ReasonTagsOf<E, ErrorTag>, R extends ResultAsync<unknown, unknown>>(errorTag: ErrorTag, reasonTag: ReasonTag, f: (reason: ReasonForTag<E, ErrorTag, ReasonTag>, error: ErrorForTag$1<E, ErrorTag>) => R): ResultAsync<T | InferAsyncOkTypes<R>, ExcludeReasonTag<E, ErrorTag, ReasonTag> | InferAsyncErrTypes<R>>;
   catchReason<U, F, const ErrorTag extends TagsWithReasonOf<E>, const ReasonTag extends ReasonTagsOf<E, ErrorTag>>(errorTag: ErrorTag, reasonTag: ReasonTag, f: (reason: ReasonForTag<E, ErrorTag, ReasonTag>, error: ErrorForTag$1<E, ErrorTag>) => Result<U, F> | ResultAsync<U, F>): ResultAsync<T | U, ExcludeReasonTag<E, ErrorTag, ReasonTag> | F>;
+  /**
+  * Recovers from multiple nested tagged `reason` variants on a specific tagged error.
+  */
   catchReasons<const ErrorTag extends TagsWithReasonOf<E>, const Handlers extends object>(errorTag: ErrorTag, handlers: Handlers & ResultAsyncCatchReasonHandlers<E, ErrorTag, Handlers>): ResultAsync<T | HandlerOk<CatchReasonHandlerResult<Handlers>>, ExcludeReasonTag<E, ErrorTag, keyof Handlers & string> | HandlerErr<CatchReasonHandlerResult<Handlers>>>;
+  /**
+  * Moves the nested `reason` of a tagged error into the ResultAsync error channel.
+  */
   unwrapReason<const ErrorTag extends TagsWithReasonOf<E>>(errorTag: ErrorTag): ResultAsync<T, ExcludeTag<E, ErrorTag> | ReasonsOf<E, ErrorTag>>;
+  /**
+  * Converts this ResultAsync into a Promise of a plain value by handling both Ok and Err.
+  */
   match<A, B = A>(handlers: MatchHandlers$1<T, E, A, B>): Promise<A | B>;
   match<A, B = A>(ok: (t: T) => A, fnErr: (e: E) => B): Promise<A | B>;
+  /**
+  * Converts this ResultAsync into a Promise of a plain value with exhaustive tagged-error handlers.
+  */
   matchTags<A, const Handlers extends object>(ok: (t: T) => A, handlers: Handlers & MatchTagHandlers<E, Handlers>): Promise<A | MatchTagHandlerResult<Handlers>>;
+  /**
+  * Converts this ResultAsync into a Promise of a plain value with partial tagged-error handlers and
+  * a fallback.
+  */
   matchTagsPartial<A, B, const Handlers extends object>(ok: (t: T) => A, handlers: Handlers & PartialMatchTagHandlers<E, Handlers>, fallback: (error: E) => B): Promise<A | MatchTagHandlerResult<Handlers> | B>;
+  /**
+  * Resolves to the Ok value, or `t` when this ResultAsync is Err.
+  */
   unwrapOr<A>(t: A): Promise<T | A>;
+  /**
+  * Resolves to the Ok value or rejects with the Err value.
+  *
+  * Use this at final application boundaries after the error channel has been modeled.
+  */
   unwrapOrThrow(): Promise<T>;
   /**
   * Runs a side effect for either variant and preserves the original async result.
@@ -724,21 +1335,91 @@ declare class ResultAsync<T, E> extends Pipeable implements PromiseLike<Result<T
   * Use `mapErr` or `orElse` when the callback should transform the error.
   */
   tapError(f: (e: E) => void | Promise<void>): ResultAsync<T, E>;
+  /**
+  * Attaches an async disposal finalizer to this ResultAsync.
+  */
   toAsyncDisposable(f: ResultAsyncFinalizer<T, E>): DisposableResultAsync<T, E>;
+  /**
+  * Enables `yield* resultAsync` inside async `safeTry` generators.
+  */
   [Symbol.asyncIterator](): AsyncGenerator<Result<never, E>, T>;
 }
 type StrictResultAsync<T, E extends Error = Error> = ResultAsync<T, E>;
+/**
+* Creates an Ok ResultAsync.
+*/
 declare const okAsync: typeof ResultAsync.okAsync;
+/**
+* Creates an Err ResultAsync.
+*/
 declare const errAsync: typeof ResultAsync.errAsync;
+/**
+* Converts an existing promise into a ResultAsync and maps rejection into a typed Err.
+*/
 declare const fromPromise: typeof ResultAsync.fromPromise;
+/**
+* Converts an existing promise that is expected not to reject into a ResultAsync.
+*
+* Use `fromPromise` or `tryResultAsync` when rejection should become a typed Err.
+*/
 declare const fromSafePromise: typeof ResultAsync.fromSafePromise;
+/**
+* Creates an Ok ResultAsync with `undefined`.
+*/
 declare const unitAsync: typeof ResultAsync.unitAsync;
+/**
+* Wraps an async function so every later call returns a ResultAsync.
+*/
 declare const fromThrowableAsync: typeof ResultAsync.fromThrowable;
+/**
+* Captures a promise or async factory into `ResultAsync<T, E>`.
+*
+* Use `tryResultAsync` at the edge of uncontrolled async code: network calls, file I/O,
+* third-party SDKs, JSON parsing promises, and framework APIs that can reject. The mapper receives
+* the rejected or thrown `unknown` cause and returns the typed error for the Resultar channel.
+*
+* Passing a factory is preferred when creating the promise can throw synchronously.
+*
+* @example
+* ```ts
+* const user = tryResultAsync(
+*   () => fetchUser(id),
+*   (cause) => new FetchUserError({ cause, id }),
+* )
+* ```
+*/
 declare function tryResultAsync<T, E>(fn: Promise<T> | (() => Promise<T>), errorFn: (e: unknown) => E): ResultAsync<T, E>;
+/**
+* Captures an async boundary with named `try` and `catch` fields.
+*
+* This is equivalent to `tryResultAsync(() => ..., toError)`, but it reads better for reusable
+* infrastructure helpers where the label, task, and mapper live together.
+*
+* @example
+* ```ts
+* const startup = tryResultAsync({
+*   try: () => fastify.register(plugin),
+*   catch: (cause) => new StartupTaskError({ cause, label: "register plugin" }),
+* })
+* ```
+*/
 declare function tryResultAsync<T, E>(options: TryResultAsyncOptions<T, E> & {
   readonly catch: (e: unknown) => E;
 }): ResultAsync<T, E>;
+/**
+* Captures a promise or async factory into `ResultAsync<T, unknown>`.
+*
+* Prefer the overload with a catch mapper in application code so the error channel stays documented.
+* This overload is useful while adapting unknown external failures or during migration.
+*/
 declare function tryResultAsync<T>(input: Promise<T> | (() => Promise<T>) | TryResultAsyncOptions<T>): ResultAsync<T, unknown>;
+/**
+* Runs a `ResultAsync` at an application boundary and returns the success value.
+*
+* If the result is `Err`, this rejects with the error. Use it at final framework, CLI, test, or
+* bootstrap boundaries after the error channel has already been modeled with Resultar.
+*/
+declare const runPromise: <T, E>(result: ResultAsync<T, E>) => Promise<T>;
 /** Compatibility alias. Prefer `tryResultAsync` in new code. */
 declare const tryCatchAsync: typeof tryResultAsync;
 type CombineResultAsyncs<T extends readonly ResultAsync<unknown, unknown>[]> = IsLiteralArray<T> extends 1 ? TraverseAsync<UnwrapAsync<T>> : ResultAsync<ExtractOkAsyncTypes<T>, ExtractErrAsyncTypes<T>[number]>;
@@ -749,15 +1430,39 @@ type TraverseWithAllErrorsAsync<T, Depth extends number = 5> = TraverseAsync<T,
 type Writable<T> = T extends readonly unknown[] ? [...T] : T;
 //#endregion
 //#region src/redacted.d.ts
+/**
+* String-like wrapper that hides a sensitive value in messages and JSON output.
+*/
 type Redacted<T> = string & {
+  /**
+  * Internal marker used by `isRedacted`.
+  */
   readonly __resultarRedacted: true;
   readonly __resultarRedactedType?: T;
+  /**
+  * Optional label shown as `<redacted:label>`.
+  */
   readonly label: string | undefined;
-  toJSON(): string;
-  toString(): string;
+  /**
+  * Serializes to the redacted placeholder.
+  */
+  toJSON: () => string;
+  /**
+  * Converts to the redacted placeholder.
+  */
+  toString: () => string;
 };
+/**
+* Wraps a sensitive value so tagged-error messages and JSON output show only a placeholder.
+*/
 declare const redact: <T>(value: T, label?: string) => Redacted<T>;
+/**
+* Checks whether a value was created by `redact`.
+*/
 declare const isRedacted: (value: unknown) => value is Redacted<unknown>;
+/**
+* Returns the original sensitive value from a Redacted wrapper.
+*/
 declare const revealRedacted: <T>(value: Redacted<T>) => T;
 //#endregion
 //#region src/tagged-error.d.ts
@@ -789,23 +1494,65 @@ type TaggedErrorConstructorArgs<Template extends string> = [ExtractTemplateVaria
   readonly cause?: unknown;
 }] : [props: ConstructorProps<Template>];
 interface TaggedErrorOptions<Tag extends string, MessageTemplate extends string, Base extends Error = Error> {
+  /**
+  * Optional base Error class to extend instead of native Error.
+  */
   readonly extends?: ErrorBaseConstructor<Base>;
+  /**
+  * Message template. `$prop` placeholders are filled from constructor props.
+  */
   readonly message?: MessageTemplate;
+  /**
+  * Stable runtime tag and Error name.
+  */
   readonly name: Tag;
 }
+/**
+* Instance type produced by `createTaggedError`.
+*/
 type TaggedErrorInstance<Tag extends string, MessageTemplate extends string, Base extends Error = Error> = Base & Readonly<TemplateProps<MessageTemplate>> & {
+  /**
+  * Stable runtime tag.
+  */
   readonly _tag: Tag;
+  /**
+  * Stable identity for grouping errors by tag and message template.
+  */
   readonly fingerprint: readonly [Tag, MessageTemplate];
+  /**
+  * Original message template before interpolation.
+  */
   readonly messageTemplate: MessageTemplate;
-  findCause<T extends Error>(ErrorClass: ErrorClass<T>): T | undefined;
-  toJSON(): object;
+  /**
+  * Finds a matching cause in the error cause chain.
+  */
+  findCause: <T extends Error>(ErrorClass: ErrorClass<T>) => T | undefined;
+  /**
+  * Serializes the tagged error, metadata, and cause chain.
+  */
+  toJSON: () => object;
 };
+/**
+* Class type returned by `createTaggedError`.
+*/
 type TaggedErrorClass<Tag extends string, MessageTemplate extends string, Base extends Error = Error> = {
   new (...args: TaggedErrorConstructorArgs<MessageTemplate>): TaggedErrorInstance<Tag, MessageTemplate, Base>;
+  /**
+  * Stable runtime tag.
+  */
   readonly tag: Tag;
-  err<This extends new (...args: TaggedErrorConstructorArgs<MessageTemplate>) => Error>(this: This, ...args: TaggedErrorConstructorArgs<MessageTemplate>): ErrResult<never, ErrorClassInstance<This>>;
-  is(value: unknown): value is TaggedErrorInstance<Tag, MessageTemplate, Base>;
+  /**
+  * Creates an Err containing this tagged error.
+  */
+  err: <This extends new (...args: TaggedErrorConstructorArgs<MessageTemplate>) => Error>(this: This, ...args: TaggedErrorConstructorArgs<MessageTemplate>) => ErrResult<never, ErrorClassInstance<This>>;
+  /**
+  * Narrows a value to this tagged error class.
+  */
+  is: (value: unknown) => value is TaggedErrorInstance<Tag, MessageTemplate, Base>;
 };
+/**
+* Union of members produced by `taggedEnum`.
+*/
 type TaggedEnum<Members extends Record<string, object>> = { readonly [Tag in keyof Members]: Readonly<Members[Tag]> & {
   readonly _tag: Tag;
 } }[keyof Members];
@@ -813,9 +1560,18 @@ type TaggedEnumMember<Members extends Record<string, object>, Tag extends keyof
   readonly _tag: Tag;
 };
 type TaggedEnumConstructor<Members extends Record<string, object>, Tag extends keyof Members> = keyof Members[Tag] extends never ? (props?: Readonly<Members[Tag]>) => TaggedEnumMember<Members, Tag> : (props: Readonly<Members[Tag]>) => TaggedEnumMember<Members, Tag>;
+/**
+* Factory returned by `taggedEnum`.
+*/
 type TaggedEnumFactory<Members extends Record<string, object>> = { readonly [Tag in keyof Members]: TaggedEnumConstructor<Members, Tag> } & {
-  $is<Tag extends keyof Members>(tag: Tag, value: unknown): value is TaggedEnumMember<Members, Tag>;
-  $match<ReturnType>(value: TaggedEnum<Members>, handlers: { readonly [Tag in keyof Members]: (value: TaggedEnumMember<Members, Tag>) => ReturnType }): ReturnType;
+  /**
+  * Narrows a value to a tagged enum member.
+  */
+  $is: <Tag extends keyof Members>(tag: Tag, value: unknown) => value is TaggedEnumMember<Members, Tag>;
+  /**
+  * Exhaustively matches a tagged enum value.
+  */
+  $match: <ReturnType>(value: TaggedEnum<Members>, handlers: { readonly [Tag in keyof Members]: (value: TaggedEnumMember<Members, Tag>) => ReturnType }) => ReturnType;
 };
 type TaggedErrorLike = Error & {
   readonly _tag: string;
@@ -832,15 +1588,45 @@ type MatchHandlers<ErrorType extends Error, ReturnType> = { readonly [Tag in Tag
 });
 type PartialMatchHandlers<ErrorType extends Error, ReturnType> = Partial<MatchHandlers<ErrorType, ReturnType>>;
 declare const defaultMessageTemplate = "$message";
+/**
+* Narrows a value to native or platform-recognized Error.
+*/
 declare function isError(value: unknown): value is Error;
 declare function isError<Value>(value: Value): value is Extract<Value, Error>;
+/**
+* Finds the first cause in an Error cause chain that is an instance of `ErrorClass`.
+*/
 declare const findCause: <T extends Error>(error: Error, ErrorClass: ErrorClass<T>) => T | undefined;
+/**
+* Creates an Error class with a stable `_tag`, typed template props, cause support, and JSON output.
+*
+* Prefer tagged errors for domain failures that travel through Resultar error channels.
+*
+* @example
+* ```ts
+* class UserNotFoundError extends createTaggedError({
+*   name: "UserNotFoundError",
+*   message: "User $id was not found",
+* }) {}
+* ```
+*/
 declare function createTaggedError<const Tag extends string, const MessageTemplate extends string = typeof defaultMessageTemplate, Base extends Error = Error>(options: Omit<TaggedErrorOptions<Tag, MessageTemplate, Base>, "message"> & {
   readonly message?: RejectReservedTemplateVariables<MessageTemplate>;
 }): TaggedErrorClass<Tag, MessageTemplate, Base>;
+/**
+* Creates a small tagged-union factory with member constructors, `$is`, and `$match`.
+*/
 declare const taggedEnum: <Members extends Record<string, object>>() => TaggedEnumFactory<Members>;
+/**
+* Matches an Error by tagged `_tag`, with optional native `Error` fallback.
+*
+* Throws the original error when no handler matches.
+*/
 declare const matchError: <ErrorType extends Error, ReturnType>(error: ErrorType, handlers: MatchHandlers<ErrorType, ReturnType>) => ReturnType;
+/**
+* Matches an Error by tagged `_tag`, then native `Error`, then the provided fallback.
+*/
 declare const matchErrorPartial: <ErrorType extends Error, ReturnType>(error: ErrorType, handlers: PartialMatchHandlers<ErrorType, ReturnType>, fallback: (error: ErrorType) => ReturnType) => ReturnType;
 //#endregion
-export { AbortError, DisposableResult, DisposableResultAsync, type ErrResult, type OkResult, type Redacted, Result, ResultAsync, type ResultAsyncAbortSignal, type ResultAsyncConcurrency, type ResultAsyncRaceHandle, type ResultAsyncRaceTask, type ResultAsyncResourceAcquire, type ResultAsyncResourceEffect, type ResultAsyncResourceRelease, type ResultAsyncResourceReleaseContext, type ResultAsyncResourceUse, type ResultAsyncRetryContext, type ResultAsyncRetryOptions, type ResultAsyncRetryOrElseOptions, type ResultAsyncRetryTask, type ResultAsyncTimeoutOptions, type ResultAsyncWithResourceOptions, type ResultOperations, type SafeTryAsyncOptions, type SafeTryOptions, type StrictResult, type StrictResultAsync, type TaggedEnum, type TaggedEnumFactory, type TaggedErrorClass, type TaggedErrorInstance, type TaggedErrorOptions, type TryResultAsyncOptions, type TryResultOptions, createTaggedError, tryResult as default, tryResult as try, tryResult, err, errAsync, findCause, fromPromise, fromSafePromise, fromThrowable, fromThrowableAsync, isAbortError, isError, isRedacted, matchError, matchErrorPartial, ok, okAsync, redact, revealRedacted, safeTry, taggedEnum, tryResultAsync as tryAsync, tryResultAsync, tryCatch, tryCatchAsync, unit, unitAsync };
+export { AbortError, DisposableResult, DisposableResultAsync, type ErrResult, type OkResult, type Redacted, Result, ResultAsync, type ResultAsyncAbortSignal, type ResultAsyncConcurrency, type ResultAsyncRaceHandle, type ResultAsyncRaceTask, type ResultAsyncResourceAcquire, type ResultAsyncResourceEffect, type ResultAsyncResourceRelease, type ResultAsyncResourceReleaseContext, type ResultAsyncResourceUse, type ResultAsyncRetryContext, type ResultAsyncRetryOptions, type ResultAsyncRetryOrElseOptions, type ResultAsyncRetryTask, type ResultAsyncTimeoutOptions, type ResultAsyncWithResourceOptions, type ResultOperations, type SafeTryAsyncOptions, type SafeTryOptions, type StrictResult, type StrictResultAsync, type TaggedEnum, type TaggedEnumFactory, type TaggedErrorClass, type TaggedErrorInstance, type TaggedErrorOptions, type TryResultAsyncOptions, type TryResultOptions, createTaggedError, tryResult as default, tryResult as try, tryResult, err, errAsync, findCause, fromPromise, fromSafePromise, fromThrowable, fromThrowableAsync, isAbortError, isError, isRedacted, matchError, matchErrorPartial, ok, okAsync, redact, revealRedacted, runPromise, runSync, safeTry, taggedEnum, tryResultAsync as tryAsync, tryResultAsync, tryCatch, tryCatchAsync, unit, unitAsync };
 //# sourceMappingURL=index.d.ts.map