resultar 3.5.1 → 3.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +149 -18
  2. package/dist/index.d.ts +900 -760
  3. package/dist/index.js +286 -7
  4. package/package.json +10 -10
package/dist/index.d.ts CHANGED
@@ -7,21 +7,21 @@ interface ErrorConfig {
7
7
  type PipeFn<Input, Output> = (input: Input) => Output;
8
8
  declare abstract class Pipeable {
9
9
  /**
10
- * Passes this value through one or more transformation functions.
11
- *
12
- * Use `pipe` to package reusable Result or ResultAsync combinators without hiding the underlying
13
- * type.
14
- */
10
+ * Passes this value through one or more transformation functions.
11
+ *
12
+ * Use `pipe` to package reusable Result or ResultAsync combinators without hiding the underlying
13
+ * type.
14
+ */
15
15
  pipe<A>(ab: PipeFn<this, A>): A;
16
16
  pipe<A, B>(ab: PipeFn<this, A>, bc: PipeFn<A, B>): B;
17
17
  pipe<A, B, C>(ab: PipeFn<this, A>, bc: PipeFn<A, B>, cd: PipeFn<B, C>): C;
18
18
  }
19
19
  //#endregion
20
20
  //#region src/utils.d.ts
21
- type ExtractOkTypes<T extends readonly Result<unknown, unknown>[]> = { [idx in keyof T]: T[idx] extends Result<infer U, unknown> ? U : never };
22
- type ExtractOkAsyncTypes<T extends readonly ResultAsync<unknown, unknown>[]> = { [idx in keyof T]: T[idx] extends ResultAsync<infer U, unknown> ? U : never };
23
- type ExtractErrTypes<T extends readonly Result<unknown, unknown>[]> = { [idx in keyof T]: T[idx] extends Result<unknown, infer E> ? E : never };
24
- type ExtractErrAsyncTypes<T extends readonly ResultAsync<unknown, unknown>[]> = { [idx in keyof T]: T[idx] extends ResultAsync<unknown, infer E> ? E : never };
21
+ type ExtractOkTypes<T extends readonly Result<unknown, unknown>[]> = { [idx in keyof T]: T[idx] extends Result<infer U, unknown> ? U : never; };
22
+ type ExtractOkAsyncTypes<T extends readonly ResultAsync<unknown, unknown>[]> = { [idx in keyof T]: T[idx] extends ResultAsync<infer U, unknown> ? U : never; };
23
+ type ExtractErrTypes<T extends readonly Result<unknown, unknown>[]> = { [idx in keyof T]: T[idx] extends Result<unknown, infer E> ? E : never; };
24
+ type ExtractErrAsyncTypes<T extends readonly ResultAsync<unknown, unknown>[]> = { [idx in keyof T]: T[idx] extends ResultAsync<unknown, infer E> ? E : never; };
25
25
  type InferOkTypes<R> = R extends Result<infer T, unknown> ? T : never;
26
26
  type InferErrTypes<R> = R extends Result<unknown, infer E> ? E : never;
27
27
  type InferAsyncOkTypes<R> = R extends ResultAsync<infer T, unknown> ? T : never;
@@ -61,21 +61,21 @@ type ExcludeReasonTag<E, ErrorTag extends string, ReasonTag extends string> = Ex
61
61
  }> | ErrorWithRemainingReason<ErrorForTag$1<E, ErrorTag>, Exclude<ReasonsOf<E, ErrorTag>, {
62
62
  readonly _tag: ReasonTag;
63
63
  }>>;
64
- type CatchTagHandlerResult<Handlers> = { readonly [Key in keyof Handlers]: Handlers[Key] extends ((...args: infer _Args) => infer R) ? R : never }[keyof Handlers];
65
- type CatchReasonHandlerResult<Handlers> = { readonly [Key in keyof Handlers]: Handlers[Key] extends ((...args: infer _Args) => infer R) ? R : never }[keyof Handlers];
66
- type MatchTagHandlerResult<Handlers> = { readonly [Key in keyof Handlers]: Handlers[Key] extends ((...args: infer _Args) => infer R) ? R : never }[keyof Handlers];
67
- type CatchTagHandlers<E, Handlers, R> = { readonly [Tag in keyof Handlers]: Tag extends TagsOf<E> ? (error: ErrorForTag$1<E, Tag & string>) => R : never };
64
+ type CatchTagHandlerResult<Handlers> = { readonly [Key in keyof Handlers]: Handlers[Key] extends ((...args: infer _Args) => infer R) ? R : never; }[keyof Handlers];
65
+ type CatchReasonHandlerResult<Handlers> = { readonly [Key in keyof Handlers]: Handlers[Key] extends ((...args: infer _Args) => infer R) ? R : never; }[keyof Handlers];
66
+ type MatchTagHandlerResult<Handlers> = { readonly [Key in keyof Handlers]: Handlers[Key] extends ((...args: infer _Args) => infer R) ? R : never; }[keyof Handlers];
67
+ type CatchTagHandlers<E, Handlers, R> = { readonly [Tag in keyof Handlers]: Tag extends TagsOf<E> ? (error: ErrorForTag$1<E, Tag & string>) => R : never; };
68
68
  type ResultCatchTagHandlers<E, Handlers> = CatchTagHandlers<E, Handlers, Result<unknown, unknown>>;
69
69
  type ResultAsyncCatchTagHandlers<E, Handlers> = CatchTagHandlers<E, Handlers, Result<unknown, unknown> | ResultAsync<unknown, unknown>>;
70
- type CatchReasonHandlers<E, ErrorTag extends string, Handlers, R> = { readonly [ReasonTag in keyof Handlers]: ReasonTag extends ReasonTagsOf<E, ErrorTag> ? (reason: ReasonForTag<E, ErrorTag, ReasonTag & string>, error: ErrorForTag$1<E, ErrorTag>) => R : never };
70
+ type CatchReasonHandlers<E, ErrorTag extends string, Handlers, R> = { readonly [ReasonTag in keyof Handlers]: ReasonTag extends ReasonTagsOf<E, ErrorTag> ? (reason: ReasonForTag<E, ErrorTag, ReasonTag & string>, error: ErrorForTag$1<E, ErrorTag>) => R : never; };
71
71
  type ResultCatchReasonHandlers<E, ErrorTag extends string, Handlers> = CatchReasonHandlers<E, ErrorTag, Handlers, Result<unknown, unknown>>;
72
72
  type ResultAsyncCatchReasonHandlers<E, ErrorTag extends string, Handlers> = CatchReasonHandlers<E, ErrorTag, Handlers, Result<unknown, unknown> | ResultAsync<unknown, unknown>>;
73
- type MatchTagHandlers<E, Handlers> = { readonly [Tag in ErrorTagsOf<E>]: (error: ErrorForTag$1<E, Tag>) => unknown } & ([UntaggedError$1<E>] extends [never] ? {
73
+ type MatchTagHandlers<E, Handlers> = { readonly [Tag in ErrorTagsOf<E>]: (error: ErrorForTag$1<E, Tag>) => unknown; } & ([UntaggedError$1<E>] extends [never] ? {
74
74
  readonly Error?: (error: Error) => unknown;
75
75
  } : {
76
76
  readonly Error: (error: UntaggedError$1<E>) => unknown;
77
- }) & { readonly [Tag in keyof Handlers]: Tag extends ErrorTagsOf<E> | "Error" ? Handlers[Tag] : never };
78
- type PartialMatchTagHandlers<E, Handlers> = { readonly [Tag in keyof Handlers]: Tag extends ErrorTagsOf<E> ? (error: ErrorForTag$1<E, Tag & string>) => unknown : Tag extends "Error" ? (error: Extract<E, Error>) => unknown : never };
77
+ }) & { readonly [Tag in keyof Handlers]: Tag extends ErrorTagsOf<E> | "Error" ? Handlers[Tag] : never; };
78
+ type PartialMatchTagHandlers<E, Handlers> = { readonly [Tag in keyof Handlers]: Tag extends ErrorTagsOf<E> ? (error: ErrorForTag$1<E, Tag & string>) => unknown : Tag extends "Error" ? (error: Extract<E, Error>) => unknown : never; };
79
79
  //#endregion
80
80
  //#region src/result.d.ts
81
81
  type ResultFinalizer<T, E> = (value: T | undefined, error: E | undefined) => void;
@@ -83,8 +83,8 @@ type MatchOkHandler<T, A> = (value: T) => A;
83
83
  type MatchErrorHandler<E, B> = (error: E) => B;
84
84
  type ResultCandidate = () => Result<unknown, unknown>;
85
85
  type ResultRecord = Readonly<Record<string, Result<unknown, unknown>>>;
86
- type CombineResultsRecord<T extends ResultRecord> = Result<{ readonly [Key in keyof T]: InferOkTypes<T[Key]> }, InferErrTypes<T[keyof T]>>;
87
- type CombineResultsRecordWithAllErrors<T extends ResultRecord> = Result<{ readonly [Key in keyof T]: InferOkTypes<T[Key]> }, InferErrTypes<T[keyof T]>[]>;
86
+ type CombineResultsRecord<T extends ResultRecord> = Result<{ readonly [Key in keyof T]: InferOkTypes<T[Key]>; }, InferErrTypes<T[keyof T]>>;
87
+ type CombineResultsRecordWithAllErrors<T extends ResultRecord> = Result<{ readonly [Key in keyof T]: InferOkTypes<T[Key]>; }, InferErrTypes<T[keyof T]>[]>;
88
88
  type CombineResultsIterable<R extends Result<unknown, unknown>> = Result<readonly InferOkTypes<R>[], InferErrTypes<R>>;
89
89
  type CombineResultsIterableWithAllErrors<R extends Result<unknown, unknown>> = Result<readonly InferOkTypes<R>[], InferErrTypes<R>[]>;
90
90
  type ResultLoopCollected<R extends Result<unknown, unknown>> = Result<readonly InferOkTypes<R>[], InferErrTypes<R>>;
@@ -148,298 +148,309 @@ interface ResultIfOptions<OnTrue extends Result<unknown, unknown>, OnFalse exten
148
148
  readonly onTrue: () => OnTrue;
149
149
  }
150
150
  /**
151
- * A Result interface that is used to define the methods that are available on a
152
- * `Result` object.
153
- *
154
- * The immutability of the `Result` object is maintained by the interface.
155
- */
151
+ * A Result interface that is used to define the methods that are available on a
152
+ * `Result` object.
153
+ *
154
+ * The immutability of the `Result` object is maintained by the interface.
155
+ */
156
156
  interface Resultable<T, E> {
157
157
  get value(): T;
158
158
  get error(): E;
159
159
  /**
160
- * Used to check if a `Result` is an `OK`
161
- *
162
- * @returns `true` if the result is an `OK` variant of Result
163
- */
160
+ * Used to check if a `Result` is an `OK`
161
+ *
162
+ * @returns `true` if the result is an `OK` variant of Result
163
+ */
164
164
  isOk: () => boolean;
165
165
  /**
166
- * Used to check if a `Result` is an `Err`
167
- *
168
- * @returns `true` if the result is an `Err` variant of Result
169
- */
166
+ * Used to check if a `Result` is an `Err`
167
+ *
168
+ * @returns `true` if the result is an `Err` variant of Result
169
+ */
170
170
  isErr: () => boolean;
171
171
  /**
172
- * Unwrap the `Ok` value, or return the default if there is an `Err`
173
- *
174
- * @param v the default value to return if there is an `Err`
175
- */
172
+ * Unwrap the `Ok` value, or return the default if there is an `Err`
173
+ *
174
+ * @param v the default value to return if there is an `Err`
175
+ */
176
176
  unwrapOr: <A>(defaultValue: A) => T | A;
177
177
  /**
178
- * **This method is unsafe, and should only be used in a test environments**
179
- *
180
- * Takes a `Result<T, E>` and returns a `T` when the result is an `Ok`, otherwise it throws a custom object.
181
- *
182
- * @param config
183
- */
178
+ * **This method is unsafe, and should only be used in a test environments**
179
+ *
180
+ * Takes a `Result<T, E>` and returns a `T` when the result is an `Ok`, otherwise it throws a custom object.
181
+ *
182
+ * @param config
183
+ */
184
184
  _unsafeUnwrap: (config?: ErrorConfig) => T;
185
185
  /**
186
- * **This method is unsafe, and should only be used in a test environments**
187
- *
188
- * takes a `Result<T, E>` and returns a `E` when the result is an `Err`,
189
- * otherwise it throws a custom object.
190
- *
191
- * @param config
192
- */
186
+ * **This method is unsafe, and should only be used in a test environments**
187
+ *
188
+ * takes a `Result<T, E>` and returns a `E` when the result is an `Err`,
189
+ * otherwise it throws a custom object.
190
+ *
191
+ * @param config
192
+ */
193
193
  _unsafeUnwrapErr: (config?: ErrorConfig) => E;
194
194
  }
195
+ /** Operations shared by the Ok and Err variants of `Result<T, E>`. */
195
196
  interface ResultOperations<T, E> {
196
197
  /**
197
- * Narrows this result to the Ok variant.
198
- */
198
+ * Narrows this result to the Ok variant.
199
+ */
199
200
  isOk: () => this is OkResult<T, E>;
200
201
  /**
201
- * Narrows this result to the Err variant.
202
- */
202
+ * Narrows this result to the Err variant.
203
+ */
203
204
  isErr: () => this is ErrResult<T, E>;
204
205
  /**
205
- * Returns the Ok value, or `defaultValue` when this result is Err.
206
- */
206
+ * Returns the Ok value, or `defaultValue` when this result is Err.
207
+ */
207
208
  unwrapOr: <A>(defaultValue: A) => T | A;
208
209
  /**
209
- * Returns the Ok value or throws a Resultar diagnostic error when this result is Err.
210
- *
211
- * Prefer `match`, `unwrapOr`, or explicit error handling in application code. This helper is
212
- * intended for tests and trusted final boundaries.
213
- */
210
+ * Returns the Ok value or throws a Resultar diagnostic error when this result is Err.
211
+ *
212
+ * Prefer `match`, `unwrapOr`, or explicit error handling in application code. This helper is
213
+ * intended for tests and trusted final boundaries.
214
+ */
214
215
  _unsafeUnwrap: (config?: ErrorConfig) => T;
215
216
  /**
216
- * Returns the Err value or throws a Resultar diagnostic error when this result is Ok.
217
- *
218
- * Prefer `match`, `isErr`, or explicit error handling in application code. This helper is intended
219
- * for tests.
220
- */
217
+ * Returns the Err value or throws a Resultar diagnostic error when this result is Ok.
218
+ *
219
+ * Prefer `match`, `isErr`, or explicit error handling in application code. This helper is intended
220
+ * for tests.
221
+ */
221
222
  _unsafeUnwrapErr: (config?: ErrorConfig) => E;
222
223
  /**
223
- * Maps the Ok value while preserving the error channel.
224
- */
224
+ * Maps the Ok value while preserving the error channel.
225
+ */
225
226
  map: <X>(f: (t: T) => X) => Result<X, E>;
226
227
  /**
227
- * Replaces the Ok value with a constant while preserving the error channel.
228
- */
228
+ * Replaces the Ok value with a constant while preserving the error channel.
229
+ */
229
230
  as: <X>(value: X) => Result<X, E>;
230
231
  /**
231
- * Keeps the Ok value only when the predicate passes; otherwise returns an Err from `onFalse`.
232
- */
232
+ * Keeps the Ok value only when the predicate passes; otherwise returns an Err from `onFalse`.
233
+ */
233
234
  filterOrElse: {
234
235
  <U extends T, F>(predicate: (value: T) => value is U, onFalse: (value: T) => F): Result<U, E | F>;
235
236
  <F>(predicate: (value: T) => boolean, onFalse: (value: T) => F): Result<T, E | F>;
236
237
  };
237
238
  /**
238
- * Maps the Err value while preserving the Ok value.
239
- */
239
+ * Maps the Err value while preserving the Ok value.
240
+ */
240
241
  mapErr: <X>(fn: (t: E) => X) => Result<T, X>;
241
242
  /**
242
- * Chains another fallible operation from the Ok value.
243
- *
244
- * Use this instead of `map` when the callback returns another `Result`.
245
- */
243
+ * Chains another fallible operation from the Ok value.
244
+ *
245
+ * Use this instead of `map` when the callback returns another `Result`.
246
+ */
246
247
  andThen: <X, Y>(f: (t: T) => Result<X, Y>) => Result<X, E | Y>;
247
248
  /**
248
- * Branches from the Ok value into one of two fallible Result branches.
249
- */
249
+ * Branches from the Ok value into one of two fallible Result branches.
250
+ */
250
251
  if: (fCondition: (t: T) => boolean) => {
251
252
  true: <X1, Y1>(fTrue: (t: T) => Result<X1, Y1>) => {
252
253
  false: <X2, Y2>(fFalse: (t: T) => Result<X2, Y2>) => Result<X1 | X2, Y1 | Y2 | E>;
253
254
  };
254
255
  };
255
256
  /**
256
- * Recovers from Err with another Result.
257
- */
257
+ * Recovers from Err with another Result.
258
+ */
258
259
  orElse: <R extends Result<unknown, unknown>>(f: (e: E) => R) => Result<InferOkTypes<R> | T, InferErrTypes<R>>;
259
260
  /**
260
- * Recovers from a specific tagged error by `_tag`.
261
- */
261
+ * Recovers from a specific tagged error by `_tag`.
262
+ */
262
263
  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>>;
263
264
  /**
264
- * Recovers from multiple tagged errors by `_tag`.
265
- */
265
+ * Recovers from multiple tagged errors by `_tag`.
266
+ */
266
267
  catchTags: <const Handlers extends object>(handlers: Handlers & ResultCatchTagHandlers<E, Handlers>) => Result<T | InferOkTypes<CatchTagHandlerResult<Handlers>>, ExcludeTag<E, keyof Handlers & string> | InferErrTypes<CatchTagHandlerResult<Handlers>>>;
267
268
  /**
268
- * Recovers from a nested tagged `reason` on a specific tagged error.
269
- */
269
+ * Recovers from a nested tagged `reason` on a specific tagged error.
270
+ */
270
271
  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>>;
271
272
  /**
272
- * Recovers from multiple nested tagged `reason` variants on a specific tagged error.
273
- */
273
+ * Recovers from multiple nested tagged `reason` variants on a specific tagged error.
274
+ */
274
275
  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>>>;
275
276
  /**
276
- * Moves the nested `reason` of a tagged error into the Result error channel.
277
- */
277
+ * Moves the nested `reason` of a tagged error into the Result error channel.
278
+ */
278
279
  unwrapReason: <const ErrorTag extends TagsWithReasonOf<E>>(errorTag: ErrorTag) => Result<T, ExcludeTag<E, ErrorTag> | ReasonsOf<E, ErrorTag>>;
279
280
  /**
280
- * Chains an async fallible operation from the Ok value.
281
- */
281
+ * Chains an async fallible operation from the Ok value.
282
+ */
282
283
  asyncAndThen: <X, Y>(f: (t: T) => ResultAsync<X, Y>) => ResultAsync<X, E | Y>;
283
284
  /**
284
- * Maps the Ok value with an async function and returns a `ResultAsync`.
285
- */
285
+ * Maps the Ok value with an async function and returns a `ResultAsync`.
286
+ */
286
287
  asyncMap: <X>(f: (t: T) => Promise<X>) => ResultAsync<X, E>;
287
288
  /**
288
- * Converts this Result into a plain value by handling both Ok and Err.
289
- */
289
+ * Converts this Result into a plain value by handling both Ok and Err.
290
+ */
290
291
  match: {
291
292
  <A, B = A>(handlers: MatchHandlers$1<T, E, A, B>): A | B;
292
293
  <A, B = A>(fnOk: MatchOkHandler<T, A>, fnErr: MatchErrorHandler<E, B>): A | B;
293
294
  };
294
295
  /**
295
- * Converts this Result into a plain value with exhaustive tagged-error handlers.
296
- */
296
+ * Converts this Result into a plain value with exhaustive tagged-error handlers.
297
+ */
297
298
  matchTags: <A, const Handlers extends object>(fnOk: (t: T) => A, handlers: Handlers & MatchTagHandlers<E, Handlers>) => A | MatchTagHandlerResult<Handlers>;
298
299
  /**
299
- * Converts this Result into a plain value with partial tagged-error handlers and a fallback.
300
- */
300
+ * Converts this Result into a plain value with partial tagged-error handlers and a fallback.
301
+ */
301
302
  matchTagsPartial: <A, B, const Handlers extends object>(fnOk: (t: T) => A, handlers: Handlers & PartialMatchTagHandlers<E, Handlers>, fallback: (error: E) => B) => A | MatchTagHandlerResult<Handlers> | B;
302
303
  /**
303
- * Pipes this Result through reusable transformation functions.
304
- */
304
+ * Pipes this Result through reusable transformation functions.
305
+ */
305
306
  pipe: {
306
307
  <A>(ab: PipeFn<Result<T, E>, A>): A;
307
308
  <A, B>(ab: PipeFn<Result<T, E>, A>, bc: PipeFn<A, B>): B;
308
309
  <A, B, C>(ab: PipeFn<Result<T, E>, A>, bc: PipeFn<A, B>, cd: PipeFn<B, C>): C;
309
310
  };
310
311
  /**
311
- * Runs a side effect with the Ok or Err value and returns this same Result.
312
- *
313
- * Exceptions thrown by the side effect are swallowed.
314
- */
312
+ * Runs a side effect with the Ok or Err value and returns this same Result.
313
+ *
314
+ * Exceptions thrown by the side effect are swallowed.
315
+ */
315
316
  log: (fn: (t?: T, e?: E) => void) => this;
316
317
  /**
317
- * Runs a side effect only when this result is Ok and returns this same Result.
318
- *
319
- * Exceptions thrown by the side effect are swallowed.
320
- */
318
+ * Runs a side effect only when this result is Ok and returns this same Result.
319
+ *
320
+ * Exceptions thrown by the side effect are swallowed.
321
+ */
321
322
  tap: (fn: (t: T) => void) => this;
322
323
  /**
323
- * Runs a side effect only when this result is Err and returns this same Result.
324
- *
325
- * Exceptions thrown by the side effect are swallowed.
326
- */
324
+ * Runs a side effect only when this result is Err and returns this same Result.
325
+ *
326
+ * Exceptions thrown by the side effect are swallowed.
327
+ */
327
328
  tapError: (fn: (e: E) => void) => this;
328
329
  /**
329
- * Attaches a synchronous disposal finalizer to this Result.
330
- */
330
+ * Attaches a synchronous disposal finalizer to this Result.
331
+ */
331
332
  toDisposable: (f: ResultFinalizer<T, E>) => DisposableResult<T, E>;
332
333
  /**
333
- * Returns the Ok value or throws the Err value.
334
- *
335
- * Use this at final application boundaries after the error channel has been modeled.
336
- */
334
+ * Returns the Ok value or throws the Err value.
335
+ *
336
+ * Use this at final application boundaries after the error channel has been modeled.
337
+ */
337
338
  unwrapOrThrow: () => T;
338
339
  /**
339
- * Enables `yield* result` inside `safeTry` generators.
340
- */
340
+ * Enables `yield* result` inside `safeTry` generators.
341
+ */
341
342
  [Symbol.iterator]: () => Generator<Result<never, E>, T>;
342
343
  /**
343
- * Compatibility generator for `safeTry`. Prefer `yield* result` in new code.
344
- */
344
+ * Compatibility generator for `safeTry`. Prefer `yield* result` in new code.
345
+ */
345
346
  safeUnwrap: () => Generator<Result<never, E>, T>;
346
347
  }
348
+ /** Successful `Result` variant carrying a value of type `T`. */
347
349
  interface OkResult<T, E> extends ResultOperations<T, E> {
348
350
  /**
349
- * Ok value carried by this result.
350
- */
351
+ * Ok value carried by this result.
352
+ */
351
353
  readonly value: T;
352
354
  }
355
+ /** Failed `Result` variant carrying an error of type `E`. */
353
356
  interface ErrResult<T, E> extends ResultOperations<T, E> {
354
357
  /**
355
- * Err value carried by this result.
356
- */
358
+ * Err value carried by this result.
359
+ */
357
360
  readonly error: E;
358
361
  }
362
+ /** Success-or-failure value with explicit Ok and Err channels. */
359
363
  type Result<T, E> = OkResult<T, E> | ErrResult<T, E>;
364
+ /** `Result` convention that restricts the error channel to real `Error` instances. */
360
365
  type StrictResult<T, E extends Error = Error> = Result<T, E>;
361
366
  /**
362
- * Object form accepted by `tryResult`.
363
- *
364
- * Use this form when named `try` and `catch` fields make a synchronous boundary easier to read.
365
- */
367
+ * Object form accepted by `tryResult`.
368
+ *
369
+ * Use this form when named `try` and `catch` fields make a synchronous boundary easier to read.
370
+ */
366
371
  interface TryResultOptions<T, E = unknown> {
367
372
  /**
368
- * Runs the synchronous work whose thrown value should become `Err<E>`.
369
- */
373
+ * Runs the synchronous work whose thrown value should become `Err<E>`.
374
+ */
370
375
  readonly try: () => Exclude<T, Promise<unknown>>;
371
376
  /**
372
- * Converts a thrown `unknown` cause into the typed Resultar error channel.
373
- *
374
- * If omitted, the error channel is `unknown`.
375
- */
377
+ * Converts a thrown `unknown` cause into the typed Resultar error channel.
378
+ *
379
+ * If omitted, the error channel is `unknown`.
380
+ */
376
381
  readonly catch?: (e: unknown) => E;
377
382
  }
383
+ /** Object-form synchronous generator workflow accepted by `safeTry`. */
378
384
  interface SafeTryOptions<YieldErr extends Result<never, unknown>, GeneratorReturnResult extends Result<unknown, unknown>, CatchErr = never> {
379
385
  /**
380
- * Generator body evaluated by `safeTry`.
381
- *
382
- * Use `yield* result` to unwrap Resultar values and short-circuit on Err.
383
- */
386
+ * Generator body evaluated by `safeTry`.
387
+ *
388
+ * Use `yield* result` to unwrap Resultar values and short-circuit on Err.
389
+ */
384
390
  readonly try: () => Generator<YieldErr, GeneratorReturnResult>;
385
391
  /**
386
- * Converts synchronous throws from the generator setup into the Result error channel.
387
- */
392
+ * Converts synchronous throws from the generator setup into the Result error channel.
393
+ */
388
394
  readonly catch?: (e: unknown) => CatchErr;
389
395
  }
396
+ /** Object-form asynchronous generator workflow accepted by `safeTry`. */
390
397
  interface SafeTryAsyncOptions<YieldErr extends Result<never, unknown>, GeneratorReturnResult extends Result<unknown, unknown>, CatchErr = never> {
391
398
  /**
392
- * Async generator body evaluated by `safeTry`.
393
- *
394
- * Use `yield* result` or `yield* resultAsync` to unwrap Resultar values and short-circuit on Err.
395
- */
399
+ * Async generator body evaluated by `safeTry`.
400
+ *
401
+ * Use `yield* result` or `yield* resultAsync` to unwrap Resultar values and short-circuit on Err.
402
+ */
396
403
  readonly try: () => AsyncGenerator<YieldErr, GeneratorReturnResult>;
397
404
  /**
398
- * Converts synchronous throws or async rejections from the generator setup into the ResultAsync
399
- * error channel.
400
- */
405
+ * Converts synchronous throws or async rejections from the generator setup into the ResultAsync
406
+ * error channel.
407
+ */
401
408
  readonly catch?: (e: unknown) => CatchErr;
402
409
  }
403
410
  interface ResultStatic {
404
411
  /**
405
- * Runtime `instanceof Result` support for Ok and Err values.
406
- */
412
+ * Runtime `instanceof Result` support for Ok and Err values.
413
+ */
407
414
  [Symbol.hasInstance]: (value: unknown) => boolean;
408
415
  /**
409
- * Runs synchronous work and captures thrown values into a Result.
410
- *
411
- * Compatibility alias. Prefer the top-level `tryResult` helper in new code.
412
- */
416
+ * Alias for `safeTry`, providing the same generator vocabulary as `ResultTask.gen`.
417
+ */
418
+ gen: typeof safeTry;
419
+ /**
420
+ * Runs synchronous work and captures thrown values into a Result.
421
+ *
422
+ * Compatibility alias. Prefer the top-level `tryResult` helper in new code.
423
+ */
413
424
  tryCatch: <T, E>(this: void, fn: () => Exclude<T, Promise<unknown>>, errorFn?: (e: unknown) => E) => Result<T, E>;
414
425
  /**
415
- * Wraps a throwing synchronous function so every later call returns a Result.
416
- */
426
+ * Wraps a throwing synchronous function so every later call returns a Result.
427
+ */
417
428
  fromThrowable: <Fn extends (...args: readonly any[]) => unknown, E>(this: void, fn: Fn, errorFn?: (e: any) => E) => (...args: Parameters<Fn>) => Result<ReturnType<Fn>, E>;
418
429
  /**
419
- * Creates an Ok result.
420
- */
430
+ * Creates an Ok result.
431
+ */
421
432
  ok: {
422
433
  <T, E = never>(this: void, value: T): OkResult<T, E>;
423
434
  <E = never>(this: void, value: void): OkResult<void, E>;
424
435
  };
425
436
  /**
426
- * Creates an Ok result with `undefined`.
427
- */
437
+ * Creates an Ok result with `undefined`.
438
+ */
428
439
  unit: <E = never>(this: void) => Result<undefined, E>;
429
440
  /**
430
- * Creates an Err result.
431
- */
441
+ * Creates an Err result.
442
+ */
432
443
  err: {
433
444
  <T = never, E extends string = string>(this: void, err: E): ErrResult<T, E>;
434
445
  <T = never, E = unknown>(this: void, err: E): ErrResult<T, E>;
435
446
  <T = never>(this: void, err: void): ErrResult<T, void>;
436
447
  };
437
448
  /**
438
- * Combines many Result values and stops at the first Err.
439
- *
440
- * Arrays return an Ok array, records return an Ok record with the same keys, and iterables return
441
- * an Ok readonly array.
442
- */
449
+ * Combines many Result values and stops at the first Err.
450
+ *
451
+ * Arrays return an Ok array, records return an Ok record with the same keys, and iterables return
452
+ * an Ok readonly array.
453
+ */
443
454
  combine: {
444
455
  <T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]>(this: void, resultList: T): CombineResults<T>;
445
456
  <T extends readonly Result<unknown, unknown>[]>(this: void, resultList: T): CombineResults<T>;
@@ -447,8 +458,8 @@ interface ResultStatic {
447
458
  <R extends Result<unknown, unknown>>(this: void, results: Iterable<R>): CombineResultsIterable<R>;
448
459
  };
449
460
  /**
450
- * Combines many Result values and collects every Err instead of stopping at the first one.
451
- */
461
+ * Combines many Result values and collects every Err instead of stopping at the first one.
462
+ */
452
463
  combineWithAllErrors: {
453
464
  <T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
454
465
  <T extends readonly Result<unknown, unknown>[]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
@@ -456,51 +467,51 @@ interface ResultStatic {
456
467
  <R extends Result<unknown, unknown>>(this: void, results: Iterable<R>): CombineResultsIterableWithAllErrors<R>;
457
468
  };
458
469
  /**
459
- * Validates many Result values and collects every Err.
460
- *
461
- * When passed items plus a mapper, the mapper must return a Result for each item.
462
- */
470
+ * Validates many Result values and collects every Err.
471
+ *
472
+ * When passed items plus a mapper, the mapper must return a Result for each item.
473
+ */
463
474
  validateAll: {
464
475
  <T extends readonly [Result<unknown, unknown>, ...Result<unknown, unknown>[]]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
465
476
  <T extends readonly Result<unknown, unknown>[]>(this: void, resultList: T): CombineResultsWithAllErrorsArray<T>;
466
477
  <Item, R extends Result<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R): ResultValidatedAll<R>;
467
478
  };
468
479
  /**
469
- * Combines exactly two Result values into an Ok tuple or the first Err.
470
- */
480
+ * Combines exactly two Result values into an Ok tuple or the first Err.
481
+ */
471
482
  zip: <Left extends Result<unknown, unknown>, Right extends Result<unknown, unknown>>(this: void, left: Left, right: Right) => ResultZipped<Left, Right>;
472
483
  /**
473
- * Runs candidates until the first Ok and returns the last Err if every candidate fails.
474
- */
484
+ * Runs candidates until the first Ok and returns the last Err if every candidate fails.
485
+ */
475
486
  firstSuccessOf: <Candidates extends Iterable<ResultCandidate>>(this: void, candidates: Candidates) => FirstSuccessOf<Candidates>;
476
487
  /**
477
- * Chooses one of two Result branches from a boolean or Result boolean condition.
478
- */
488
+ * Chooses one of two Result branches from a boolean or Result boolean condition.
489
+ */
479
490
  if: {
480
491
  <OnTrue extends Result<unknown, unknown>, OnFalse extends Result<unknown, unknown>>(this: void, condition: ResultBooleanCondition, options: ResultIfOptions<OnTrue, OnFalse>): ResultIf<never, OnTrue, OnFalse>;
481
492
  <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>;
482
493
  };
483
494
  /**
484
- * Runs `body` only when the condition is true; otherwise returns Ok(undefined).
485
- */
495
+ * Runs `body` only when the condition is true; otherwise returns Ok(undefined).
496
+ */
486
497
  when: <R extends Result<unknown, unknown>>(this: void, condition: ResultBooleanCondition, body: () => R) => ResultWhen<R>;
487
498
  /**
488
- * Runs `body` only when a Result boolean condition is Ok(true).
489
- */
499
+ * Runs `body` only when a Result boolean condition is Ok(true).
500
+ */
490
501
  whenResult: <Condition extends Result<boolean, unknown>, R extends Result<unknown, unknown>>(this: void, condition: Condition, body: () => R) => ResultWhenWithCondition<Condition, R>;
491
502
  /**
492
- * Runs `body` only when the condition is false; otherwise returns Ok(undefined).
493
- */
503
+ * Runs `body` only when the condition is false; otherwise returns Ok(undefined).
504
+ */
494
505
  unless: <R extends Result<unknown, unknown>>(this: void, condition: ResultBooleanCondition, body: () => R) => ResultWhen<R>;
495
506
  /**
496
- * Runs `body` only when a Result boolean condition is Ok(false).
497
- */
507
+ * Runs `body` only when a Result boolean condition is Ok(false).
508
+ */
498
509
  unlessResult: <Condition extends Result<boolean, unknown>, R extends Result<unknown, unknown>>(this: void, condition: Condition, body: () => R) => ResultWhenWithCondition<Condition, R>;
499
510
  /**
500
- * Repeats a Result-producing body while a condition holds.
501
- *
502
- * Use `discard: true` when only failure matters and collected Ok values are not needed.
503
- */
511
+ * Repeats a Result-producing body while a condition holds.
512
+ *
513
+ * Use `discard: true` when only failure matters and collected Ok values are not needed.
514
+ */
504
515
  loop: {
505
516
  <State, BodyState extends State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopOptions<State, BodyState, R>): ResultLoopCollected<R>;
506
517
  <State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopBooleanOptions<State, R>): ResultLoopCollected<R>;
@@ -508,79 +519,80 @@ interface ResultStatic {
508
519
  <State, R extends Result<unknown, unknown>>(this: void, initial: State, options: ResultLoopBooleanDiscardOptions<State, R>): ResultLoopDiscarded<R>;
509
520
  };
510
521
  /**
511
- * Repeatedly transforms state with a Result-producing body until the condition fails.
512
- */
522
+ * Repeatedly transforms state with a Result-producing body until the condition fails.
523
+ */
513
524
  iterate: {
514
525
  <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>;
515
526
  <State, R extends Result<WidenLiteral$1<State>, unknown>>(this: void, initial: State, options: ResultIterateBooleanOptions<WidenLiteral$1<State>, R>): ResultIterated<WidenLiteral$1<State>, R>;
516
527
  };
517
528
  /**
518
- * Runs a Result-producing mapper for each item.
519
- *
520
- * Use `discard: true` when only failure matters and collected Ok values are not needed.
521
- */
529
+ * Runs a Result-producing mapper for each item.
530
+ *
531
+ * Use `discard: true` when only failure matters and collected Ok values are not needed.
532
+ */
522
533
  forEach: {
523
534
  <Item, R extends Result<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options?: ResultForEachOptions): ResultForEachCollected<R>;
524
535
  <Item, R extends Result<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options: ResultForEachDiscardOptions): ResultForEachDiscarded<R>;
525
536
  };
526
537
  }
538
+ /** Static helpers for creating, combining, and iterating over Result values. */
527
539
  declare const Result: ResultStatic;
528
540
  /**
529
- * A `Disposable` is an object that has a `dispose` method that can be used to
530
- * clean up resources.
531
- */
541
+ * A `Disposable` is an object that has a `dispose` method that can be used to
542
+ * clean up resources.
543
+ */
532
544
  declare class DisposableResult<T, E> implements Resultable<T, E>, Disposable {
533
545
  private disposed;
534
546
  private readonly finalizer;
535
547
  /**
536
- * Wrapped Result value.
537
- */
548
+ * Wrapped Result value.
549
+ */
538
550
  readonly result: Result<T, E>;
539
551
  /**
540
- * Creates a disposable wrapper around a Result.
541
- */
552
+ * Creates a disposable wrapper around a Result.
553
+ */
542
554
  constructor(result: Result<T, E>, finalizer: ResultFinalizer<T, E>);
543
555
  /**
544
- * Ok value when present, otherwise undefined cast to `T` for compatibility.
545
- */
556
+ * Ok value when present, otherwise undefined cast to `T` for compatibility.
557
+ */
546
558
  get value(): T;
547
559
  /**
548
- * Err value when present, otherwise undefined cast to `E` for compatibility.
549
- */
560
+ * Err value when present, otherwise undefined cast to `E` for compatibility.
561
+ */
550
562
  get error(): E;
551
563
  /**
552
- * Delegates to the wrapped Result `_unsafeUnwrap`.
553
- */
564
+ * Delegates to the wrapped Result `_unsafeUnwrap`.
565
+ */
554
566
  _unsafeUnwrap(config?: ErrorConfig): T;
555
567
  /**
556
- * Delegates to the wrapped Result `_unsafeUnwrapErr`.
557
- */
568
+ * Delegates to the wrapped Result `_unsafeUnwrapErr`.
569
+ */
558
570
  _unsafeUnwrapErr(config?: ErrorConfig): E;
559
571
  /**
560
- * Returns whether the wrapped Result is Ok.
561
- */
572
+ * Returns whether the wrapped Result is Ok.
573
+ */
562
574
  isOk(): boolean;
563
575
  /**
564
- * Returns whether the wrapped Result is Err.
565
- */
576
+ * Returns whether the wrapped Result is Err.
577
+ */
566
578
  isErr(): boolean;
567
579
  /**
568
- * Returns the wrapped Ok value, or `defaultValue` when Err.
569
- */
580
+ * Returns the wrapped Ok value, or `defaultValue` when Err.
581
+ */
570
582
  unwrapOr<A>(defaultValue: A): T | A;
571
583
  /**
572
- * Runs the finalizer once.
573
- *
574
- * Finalizer exceptions are intentionally swallowed.
575
- */
584
+ * Runs the finalizer once.
585
+ *
586
+ * Finalizer exceptions are intentionally swallowed.
587
+ */
576
588
  [Symbol.dispose](): void;
577
589
  }
578
590
  /**
579
- * Evaluates a synchronous generator and returns the first yielded Err or returned Result.
580
- *
581
- * Inside the generator, use `yield* result` to unwrap Ok values and short-circuit on Err. The object
582
- * form can map thrown setup errors into the Result error channel.
583
- */
591
+ * Evaluates a synchronous generator and returns the first yielded Err or returned Result.
592
+ *
593
+ * Inside the generator, use `yield* result` to unwrap Ok values and short-circuit on Err. The object
594
+ * form can map thrown setup errors into the Result error channel.
595
+ */
584
596
  declare function safeTry<T, E, CatchErr = E>(input: SafeTryOptions<Result<never, E>, Result<T, E>, CatchErr> & {
585
597
  readonly catch: (e: unknown) => CatchErr;
586
598
  }): Result<T, E | CatchErr>;
@@ -590,13 +602,13 @@ declare function safeTry<YieldErr extends Result<never, unknown>, GeneratorRetur
590
602
  }): Result<InferOkTypes<GeneratorReturnResult>, InferErrTypes<YieldErr> | InferErrTypes<GeneratorReturnResult> | CatchErr>;
591
603
  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>>;
592
604
  /**
593
- * Evaluates an async generator and returns a ResultAsync for the first yielded Err or returned
594
- * Result.
595
- *
596
- * Inside the generator, use `yield* result` or `yield* resultAsync` to unwrap Ok values and
597
- * short-circuit on Err. The object form can map thrown or rejected setup errors into the ResultAsync
598
- * error channel.
599
- */
605
+ * Evaluates an async generator and returns a ResultAsync for the first yielded Err or returned
606
+ * Result.
607
+ *
608
+ * Inside the generator, use `yield* result` or `yield* resultAsync` to unwrap Ok values and
609
+ * short-circuit on Err. The object form can map thrown or rejected setup errors into the ResultAsync
610
+ * error channel.
611
+ */
600
612
  declare function safeTry<T, E, CatchErr = E>(input: SafeTryAsyncOptions<Result<never, E>, Result<T, E>, CatchErr> & {
601
613
  readonly catch: (e: unknown) => CatchErr;
602
614
  }): ResultAsync<T, E | CatchErr>;
@@ -606,64 +618,64 @@ declare function safeTry<YieldErr extends Result<never, unknown>, GeneratorRetur
606
618
  }): ResultAsync<InferOkTypes<GeneratorReturnResult>, InferErrTypes<YieldErr> | InferErrTypes<GeneratorReturnResult> | CatchErr>;
607
619
  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>>;
608
620
  /**
609
- * Creates an Ok result.
610
- */
621
+ * Creates an Ok result.
622
+ */
611
623
  declare function ok<T, E = never>(value: T): OkResult<T, E>;
612
624
  declare function ok<E = never>(value: void): OkResult<void, E>;
613
625
  /**
614
- * Creates an Err result.
615
- */
626
+ * Creates an Err result.
627
+ */
616
628
  declare function err<T = never, E extends string = string>(err: E): ErrResult<T, E>;
617
629
  declare function err<T = never, E = unknown>(err: E): ErrResult<T, E>;
618
630
  declare function err<T = never>(err: void): ErrResult<T, void>;
619
631
  /**
620
- * Wraps a throwing synchronous function so every later call returns a Result.
621
- *
622
- * Prefer `tryResult` when you want to run the operation immediately.
623
- */
632
+ * Wraps a throwing synchronous function so every later call returns a Result.
633
+ *
634
+ * Prefer `tryResult` when you want to run the operation immediately.
635
+ */
624
636
  declare const fromThrowable: typeof Result.fromThrowable;
625
637
  /**
626
- * Runs synchronous work and captures thrown values into `Result<T, E>`.
627
- *
628
- * Use `tryResult` at the edge of uncontrolled synchronous code: JSON parsing, environment parsing,
629
- * platform APIs, or third-party functions that may throw. The mapper receives the thrown `unknown`
630
- * cause and returns the typed error for the Resultar channel.
631
- *
632
- * @example
633
- * ```ts
634
- * const config = tryResult(
635
- * () => JSON.parse(input) as Config,
636
- * (cause) => new ParseConfigError({ cause }),
637
- * )
638
- * ```
639
- */
638
+ * Runs synchronous work and captures thrown values into `Result<T, E>`.
639
+ *
640
+ * Use `tryResult` at the edge of uncontrolled synchronous code: JSON parsing, environment parsing,
641
+ * platform APIs, or third-party functions that may throw. The mapper receives the thrown `unknown`
642
+ * cause and returns the typed error for the Resultar channel.
643
+ *
644
+ * @example
645
+ * ```ts
646
+ * const config = tryResult(
647
+ * () => JSON.parse(input) as Config,
648
+ * (cause) => new ParseConfigError({ cause }),
649
+ * )
650
+ * ```
651
+ */
640
652
  declare function tryResult<T, E>(fn: () => Exclude<T, Promise<unknown>>, errorFn: (e: unknown) => E): Result<T, E>;
641
653
  /**
642
- * Captures a synchronous boundary with named `try` and `catch` fields.
643
- *
644
- * This is equivalent to `tryResult(() => ..., toError)`, but it reads better when the boundary has
645
- * a clear domain name or label.
646
- */
654
+ * Captures a synchronous boundary with named `try` and `catch` fields.
655
+ *
656
+ * This is equivalent to `tryResult(() => ..., toError)`, but it reads better when the boundary has
657
+ * a clear domain name or label.
658
+ */
647
659
  declare function tryResult<T, E>(options: TryResultOptions<T, E> & {
648
660
  readonly catch: (e: unknown) => E;
649
661
  }): Result<T, E>;
650
662
  /**
651
- * Runs synchronous work and captures thrown values into `Result<T, unknown>`.
652
- *
653
- * Prefer the overload with a catch mapper in application code so the error channel stays documented.
654
- * This overload is useful while adapting unknown external failures or during migration.
655
- */
663
+ * Runs synchronous work and captures thrown values into `Result<T, unknown>`.
664
+ *
665
+ * Prefer the overload with a catch mapper in application code so the error channel stays documented.
666
+ * This overload is useful while adapting unknown external failures or during migration.
667
+ */
656
668
  declare function tryResult<T>(input: (() => Exclude<T, Promise<unknown>>) | TryResultOptions<T>): Result<T, unknown>;
657
669
  /**
658
- * Creates an Ok result with `undefined`.
659
- */
670
+ * Creates an Ok result with `undefined`.
671
+ */
660
672
  declare function unit<E = never>(): OkResult<undefined, E>;
661
673
  /**
662
- * Runs a `Result` at an application boundary and returns the success value.
663
- *
664
- * If the result is `Err`, this throws the error. Use it at final framework, CLI, test, or bootstrap
665
- * boundaries after the error channel has already been modeled with Resultar.
666
- */
674
+ * Runs a `Result` at an application boundary and returns the success value.
675
+ *
676
+ * If the result is `Err`, this throws the error. Use it at final framework, CLI, test, or bootstrap
677
+ * boundaries after the error channel has already been modeled with Resultar.
678
+ */
667
679
  declare const runSync: <T, E>(result: Result<T, E>) => T;
668
680
  /** Compatibility alias. Prefer `tryResult` in new code. */
669
681
  declare const tryCatch: typeof tryResult;
@@ -672,7 +684,7 @@ type CollectResults<T, Collected extends unknown[] = [], Depth extends number =
672
684
  type Transpose<A, Transposed extends unknown[][] = [], Depth extends number = 10> = A extends [infer T, ...infer Rest] ? T extends [infer L, infer R] ? Transposed extends [infer PL, infer PR] ? PL extends unknown[] ? PR extends unknown[] ? Transpose<Rest, [[...PL, L], [...PR, R]], Prev[Depth]> : never : never : Transpose<Rest, [[L], [R]], Prev[Depth]> : Transposed : Transposed;
673
685
  type Combine<T, Depth extends number = 5> = Transpose<CollectResults<T>, [], Depth> extends [infer L, infer R] ? [UnknownMembersToNever<L>, UnknownMembersToNever<R>] : Transpose<CollectResults<T>, [], Depth> extends [] ? [[], []] : never;
674
686
  type Dedup<T> = T extends Result<infer RL, infer RR> ? Result<RL, RR> : T;
675
- type MemberListOf<T> = ((T extends unknown ? (t: T) => T : never) extends infer U ? (U extends unknown ? (u: U) => unknown : never) extends ((v: infer V) => unknown) ? V : never : never) extends ((_: unknown) => infer W) ? [...MemberListOf<Exclude<T, W>>, W] : [];
687
+ type MemberListOf<T> = ((T extends unknown ? (t: T) => T : never) extends (infer U) ? (U extends unknown ? (u: U) => unknown : never) extends ((v: infer V) => unknown) ? V : never : never) extends ((_: unknown) => infer W) ? [...MemberListOf<Exclude<T, W>>, W] : [];
676
688
  type EmptyArrayToNever<T, NeverArrayToNever extends number = 0> = T extends [] ? never : NeverArrayToNever extends 1 ? T extends [never, ...infer Rest] ? [EmptyArrayToNever<Rest>] extends [never] ? never : T : T : T;
677
689
  type UnknownMembersToNever<T> = T extends [infer H, ...infer R] ? [[unknown] extends [H] ? never : H, ...UnknownMembersToNever<R>] : T;
678
690
  type MembersToUnion<T> = T extends unknown[] ? T[number] : never;
@@ -686,263 +698,266 @@ type CombineResultsWithAllErrorsArray<T extends readonly Result<unknown, unknown
686
698
  //#endregion
687
699
  //#region src/abort-error.d.ts
688
700
  /**
689
- * Standard cancellation error used by ResultAsync retry, race, timeout, and resource helpers.
690
- */
701
+ * Standard cancellation error used by ResultAsync retry, race, timeout, and resource helpers.
702
+ */
691
703
  declare class AbortError extends Error {
692
704
  /**
693
- * Creates an AbortError.
694
- */
705
+ * Creates an AbortError.
706
+ */
695
707
  constructor(message?: string, options?: ErrorOptions);
696
708
  }
697
709
  /**
698
- * Checks whether a value is an AbortError or abort-shaped platform error.
699
- */
710
+ * Checks whether a value is an AbortError or abort-shaped platform error.
711
+ */
700
712
  declare const isAbortError: (value: unknown) => value is AbortError;
701
713
  //#endregion
702
714
  //#region src/result-async.d.ts
703
715
  type ResultAsyncFinalizer<T, E> = (value: T | undefined, error: E | undefined) => void | Promise<void>;
704
716
  /**
705
- * Object form accepted by `tryResultAsync`.
706
- *
707
- * Use this form when named `try` and `catch` fields make an async boundary easier to read, or when
708
- * you want the mapper next to the promise factory.
709
- */
717
+ * Object form accepted by `tryResultAsync`.
718
+ *
719
+ * Use this form when named `try` and `catch` fields make an async boundary easier to read, or when
720
+ * you want the mapper next to the promise factory.
721
+ */
710
722
  interface TryResultAsyncOptions<T, E = unknown> {
711
723
  /**
712
- * Creates the promise whose rejection should become `Err<E>`.
713
- *
714
- * Synchronous throws from this function are also captured.
715
- */
724
+ * Creates the promise whose rejection should become `Err<E>`.
725
+ *
726
+ * Synchronous throws from this function are also captured.
727
+ */
716
728
  readonly try: () => Promise<T>;
717
729
  /**
718
- * Converts a rejected or thrown `unknown` cause into the typed Resultar error channel.
719
- *
720
- * If omitted, the error channel is `unknown`.
721
- */
730
+ * Converts a rejected or thrown `unknown` cause into the typed Resultar error channel.
731
+ *
732
+ * If omitted, the error channel is `unknown`.
733
+ */
722
734
  readonly catch?: (e: unknown) => E;
723
735
  }
736
+ /** Minimal abort-signal contract used by cancellable Resultar operations. */
724
737
  interface ResultAsyncAbortSignal {
725
738
  /**
726
- * Whether the cooperative async operation has been aborted.
727
- */
739
+ * Whether the cooperative async operation has been aborted.
740
+ */
728
741
  readonly aborted: boolean;
729
742
  /**
730
- * Optional abort cause provided by the losing race, timeout, or caller.
731
- */
743
+ * Optional abort cause provided by the losing race, timeout, or caller.
744
+ */
732
745
  readonly reason?: unknown;
733
746
  /**
734
- * Registers an abort listener.
735
- */
747
+ * Registers an abort listener.
748
+ */
736
749
  addEventListener: (type: "abort", listener: () => void, options?: {
737
750
  readonly once?: boolean;
738
751
  }) => void;
739
752
  /**
740
- * Removes an abort listener.
741
- */
753
+ * Removes an abort listener.
754
+ */
742
755
  removeEventListener: (type: "abort", listener: () => void) => void;
743
756
  }
744
757
  /**
745
- * Context passed to `ResultAsync.fromCallback` subscriptions.
746
- */
758
+ * Context passed to `ResultAsync.fromCallback` subscriptions.
759
+ */
747
760
  interface ResultAsyncCallbackContext<T> {
748
761
  /**
749
- * Completes the operation with `Ok(value)`.
750
- */
762
+ * Completes the operation with `Ok(value)`.
763
+ */
751
764
  readonly resolve: (value: T) => void;
752
765
  /**
753
- * Completes the operation with a cause mapped by the subscription's `catch` function.
754
- */
766
+ * Completes the operation with a cause mapped by the subscription's `catch` function.
767
+ */
755
768
  readonly reject: (cause: unknown) => void;
756
769
  /**
757
- * Cooperative cancellation signal for the subscription.
758
- */
770
+ * Cooperative cancellation signal for the subscription.
771
+ */
759
772
  readonly signal: ResultAsyncAbortSignal;
760
773
  }
761
774
  /**
762
- * Synchronous cleanup returned by a `ResultAsync.fromCallback` subscription.
763
- */
775
+ * Synchronous cleanup returned by a `ResultAsync.fromCallback` subscription.
776
+ */
764
777
  type ResultAsyncCallbackCleanup = () => void;
765
778
  /**
766
- * Options for adapting a callback or subscription API into `ResultAsync`.
767
- */
779
+ * Options for adapting a callback or subscription API into `ResultAsync`.
780
+ */
768
781
  interface ResultAsyncFromCallbackOptions<T, E> {
769
782
  /**
770
- * Maps callback failures and synchronous subscription throws into the typed error channel.
771
- */
783
+ * Maps callback failures and synchronous subscription throws into the typed error channel.
784
+ */
772
785
  readonly catch: (cause: unknown) => E;
773
786
  /**
774
- * Optional external signal that cancels the subscription with `AbortError`.
775
- */
787
+ * Optional external signal that cancels the subscription with `AbortError`.
788
+ */
776
789
  readonly signal?: ResultAsyncAbortSignal;
777
790
  /**
778
- * Registers the callback source and optionally returns a synchronous unsubscribe function.
779
- */
791
+ * Registers the callback source and optionally returns a synchronous unsubscribe function.
792
+ */
780
793
  readonly subscribe: (context: ResultAsyncCallbackContext<T>) => ResultAsyncCallbackCleanup | void;
781
794
  }
782
795
  /**
783
- * Concurrency setting for async collection helpers.
784
- *
785
- * Use a number for bounded parallelism or `'unbounded'` when every task may start immediately.
786
- */
796
+ * Concurrency setting for async collection helpers.
797
+ *
798
+ * Use a number for bounded parallelism or `'unbounded'` when every task may start immediately.
799
+ */
787
800
  type ResultAsyncConcurrency = number | "unbounded";
788
801
  type HandlerOk<R> = InferOkTypes<R> | InferAsyncOkTypes<R>;
789
802
  type HandlerErr<R> = InferErrTypes<R> | InferAsyncErrTypes<R>;
790
803
  type IterableElement<T> = T extends Iterable<infer Element> ? Element : never;
791
804
  /**
792
- * Candidate used by `ResultAsync.firstSuccessOf`.
793
- */
805
+ * Candidate used by `ResultAsync.firstSuccessOf`.
806
+ */
794
807
  type ResultAsyncCandidate = () => ResultAsync<unknown, unknown>;
795
808
  type ResultAsyncRecord = Readonly<Record<string, ResultAsync<unknown, unknown>>>;
796
- type CombineResultAsyncsRecord<T extends ResultAsyncRecord> = ResultAsync<{ readonly [Key in keyof T]: InferAsyncOkTypes<T[Key]> }, InferAsyncErrTypes<T[keyof T]>>;
797
- type CombineResultAsyncsRecordWithAllErrors<T extends ResultAsyncRecord> = ResultAsync<{ readonly [Key in keyof T]: InferAsyncOkTypes<T[Key]> }, InferAsyncErrTypes<T[keyof T]>[]>;
809
+ type CombineResultAsyncsRecord<T extends ResultAsyncRecord> = ResultAsync<{ readonly [Key in keyof T]: InferAsyncOkTypes<T[Key]>; }, InferAsyncErrTypes<T[keyof T]>>;
810
+ type CombineResultAsyncsRecordWithAllErrors<T extends ResultAsyncRecord> = ResultAsync<{ readonly [Key in keyof T]: InferAsyncOkTypes<T[Key]>; }, InferAsyncErrTypes<T[keyof T]>[]>;
798
811
  type CombineResultAsyncsIterable<R extends ResultAsync<unknown, unknown>> = ResultAsync<readonly InferAsyncOkTypes<R>[], InferAsyncErrTypes<R>>;
799
812
  type CombineResultAsyncsIterableWithAllErrors<R extends ResultAsync<unknown, unknown>> = ResultAsync<readonly InferAsyncOkTypes<R>[], InferAsyncErrTypes<R>[]>;
800
813
  /**
801
- * Task used by race, timeout, and retry helpers.
802
- *
803
- * The signal lets the task cooperate with cancellation when another task wins or a timeout fires.
804
- */
814
+ * Task used by race, timeout, and retry helpers.
815
+ *
816
+ * The signal lets the task cooperate with cancellation when another task wins or a timeout fires.
817
+ */
805
818
  type ResultAsyncRaceTask<T, E> = (signal: ResultAsyncAbortSignal) => ResultAsync<T, E>;
806
819
  type ResultAsyncRaceTaskOk<Task> = Task extends ResultAsyncRaceTask<infer T, unknown> ? T : never;
807
820
  type ResultAsyncRaceTaskErr<Task> = Task extends ResultAsyncRaceTask<unknown, infer E> ? E : never;
808
821
  type ResultAsyncRaceTasksOk<Tasks extends readonly ResultAsyncRaceTask<unknown, unknown>[]> = ResultAsyncRaceTaskOk<Tasks[number]>;
809
822
  type ResultAsyncRaceTasksErr<Tasks extends readonly ResultAsyncRaceTask<unknown, unknown>[]> = ResultAsyncRaceTaskErr<Tasks[number]>;
823
+ /** Running cancellable task returned by Resultar race helpers. */
810
824
  interface ResultAsyncRaceHandle<T, E> {
811
825
  /**
812
- * Abort signal associated with the running task.
813
- */
826
+ * Abort signal associated with the running task.
827
+ */
814
828
  readonly signal: ResultAsyncAbortSignal;
815
829
  /**
816
- * Aborts the running task with an optional reason.
817
- */
830
+ * Aborts the running task with an optional reason.
831
+ */
818
832
  abort: (reason?: unknown) => void;
819
833
  /**
820
- * Waits for the task to settle as a ResultAsync.
821
- */
834
+ * Waits for the task to settle as a ResultAsync.
835
+ */
822
836
  wait: () => ResultAsync<T, E>;
823
837
  }
824
838
  /**
825
- * Options for `ResultAsync.timeout`.
826
- */
839
+ * Options for `ResultAsync.timeout`.
840
+ */
827
841
  interface ResultAsyncTimeoutOptions<E> {
828
842
  /**
829
- * Creates the typed timeout error when the timeout wins.
830
- */
843
+ * Creates the typed timeout error when the timeout wins.
844
+ */
831
845
  readonly onTimeout: () => E;
832
846
  /**
833
- * Timeout duration in milliseconds.
834
- */
847
+ * Timeout duration in milliseconds.
848
+ */
835
849
  readonly timeoutMs: number;
836
850
  }
837
851
  /**
838
- * Metadata passed to retry predicates, delays, callbacks, and fallback handlers.
839
- */
852
+ * Metadata passed to retry predicates, delays, callbacks, and fallback handlers.
853
+ */
840
854
  interface ResultAsyncRetryContext {
841
855
  /**
842
- * Current attempt number, starting at 1.
843
- */
856
+ * Current attempt number, starting at 0.
857
+ */
844
858
  readonly attempt: number;
845
859
  /**
846
- * Next attempt number if another retry is scheduled.
847
- */
860
+ * Next attempt number if another retry is scheduled.
861
+ */
848
862
  readonly nextAttempt: number;
849
863
  /**
850
- * Number of retries still available after the current failure.
851
- */
864
+ * Number of retries still available after the current failure.
865
+ */
852
866
  readonly retriesRemaining: number;
853
867
  }
854
868
  /**
855
- * Task used by `ResultAsync.retry` and `ResultAsync.retryOrElse`.
856
- */
869
+ * Task used by `ResultAsync.retry` and `ResultAsync.retryOrElse`.
870
+ */
857
871
  type ResultAsyncRetryTask<T, E> = (attempt: number, signal: ResultAsyncAbortSignal) => ResultAsync<T, E>;
858
872
  type ResultAsyncRetryTaskOk<Task> = Task extends ResultAsyncRetryTask<infer T, unknown> ? T : never;
859
873
  type ResultAsyncRetryTaskErr<Task> = Task extends ResultAsyncRetryTask<unknown, infer E> ? E : never;
860
874
  type ResultAsyncRetryDelay = number | ((context: ResultAsyncRetryContext) => number);
875
+ /** Retry policy for `ResultAsync.retry` and related helpers. */
861
876
  interface ResultAsyncRetryOptions<E> {
862
877
  /**
863
- * Delay in milliseconds before retrying. Functions receive retry context.
864
- */
878
+ * Delay in milliseconds before retrying. Functions receive retry context.
879
+ */
865
880
  readonly delayMs?: ResultAsyncRetryDelay;
866
881
  /**
867
- * Randomizes the computed delay by this percentage factor.
868
- *
869
- * For example, `0.5` means 50% below to 50% above the computed delay.
870
- */
882
+ * Randomizes the computed delay by this percentage factor.
883
+ *
884
+ * For example, `0.5` means 50% below to 50% above the computed delay.
885
+ */
871
886
  readonly jittered?: number;
872
887
  /**
873
- * Side effect called after a failed attempt that will be retried.
874
- */
888
+ * Side effect called after a failed attempt that will be retried.
889
+ */
875
890
  readonly onRetry?: (error: E, context: ResultAsyncRetryContext) => void | Promise<void>;
876
891
  /**
877
- * Optional external abort signal for the retry loop.
878
- */
892
+ * Optional external abort signal for the retry loop.
893
+ */
879
894
  readonly signal?: ResultAsyncAbortSignal;
880
895
  /**
881
- * Maximum number of retries after the initial attempt.
882
- */
896
+ * Maximum number of retries after the initial attempt.
897
+ */
883
898
  readonly times: number;
884
899
  /**
885
- * Predicate deciding whether a failure is retryable.
886
- */
900
+ * Predicate deciding whether a failure is retryable.
901
+ */
887
902
  readonly while?: (error: E, context: ResultAsyncRetryContext) => boolean | Promise<boolean>;
888
903
  }
889
904
  /**
890
- * Options for `ResultAsync.retryOrElse`.
891
- */
905
+ * Options for `ResultAsync.retryOrElse`.
906
+ */
892
907
  interface ResultAsyncRetryOrElseOptions<E, F, U> extends ResultAsyncRetryOptions<E> {
893
908
  /**
894
- * Fallback Resultar operation used after retry exhaustion.
895
- */
909
+ * Fallback Resultar operation used after retry exhaustion.
910
+ */
896
911
  readonly orElse: (error: E, context: ResultAsyncRetryContext) => Result<U, F> | ResultAsync<U, F>;
897
912
  }
898
913
  /**
899
- * Acquires a resource for `ResultAsync.withResource`.
900
- */
914
+ * Acquires a resource for `ResultAsync.withResource`.
915
+ */
901
916
  type ResultAsyncResourceAcquire<Resource, E> = (signal: ResultAsyncAbortSignal) => ResultAsync<Resource, E>;
902
917
  /**
903
- * Operation accepted by `ResultAsync.withResource` use/release callbacks.
904
- */
918
+ * Operation accepted by `ResultAsync.withResource` use/release callbacks.
919
+ */
905
920
  type ResultAsyncResourceEffect<T, E> = Result<T, E> | ResultAsync<T, E>;
906
921
  /**
907
- * Uses an acquired resource inside `ResultAsync.withResource`.
908
- */
922
+ * Uses an acquired resource inside `ResultAsync.withResource`.
923
+ */
909
924
  type ResultAsyncResourceUse<Resource, T, E> = (resource: Resource, signal: ResultAsyncAbortSignal) => ResultAsyncResourceEffect<T, E>;
910
925
  /**
911
- * Context passed to resource release callbacks.
912
- */
926
+ * Context passed to resource release callbacks.
927
+ */
913
928
  interface ResultAsyncResourceReleaseContext {
914
929
  /**
915
- * Result produced by the use phase, or undefined when acquisition failed.
916
- */
930
+ * Result produced by the use phase, or undefined when acquisition failed.
931
+ */
917
932
  readonly result: Result<unknown, unknown> | undefined;
918
933
  /**
919
- * Abort signal shared by the resource lifecycle.
920
- */
934
+ * Abort signal shared by the resource lifecycle.
935
+ */
921
936
  readonly signal: ResultAsyncAbortSignal;
922
937
  }
923
938
  /**
924
- * Releases a resource after use, regardless of success or failure.
925
- */
939
+ * Releases a resource after use, regardless of success or failure.
940
+ */
926
941
  type ResultAsyncResourceRelease<Resource> = (resource: Resource, context: ResultAsyncResourceReleaseContext) => ResultAsyncResourceEffect<unknown, unknown> | Promise<void> | void;
927
942
  /**
928
- * Options for `ResultAsync.withResource`.
929
- */
943
+ * Options for `ResultAsync.withResource`.
944
+ */
930
945
  interface ResultAsyncWithResourceOptions<Resource, AcquireError, T, UseError> {
931
946
  /**
932
- * Acquires the resource.
933
- */
947
+ * Acquires the resource.
948
+ */
934
949
  readonly acquire: ResultAsyncResourceAcquire<Resource, AcquireError>;
935
950
  /**
936
- * Releases the resource after use.
937
- */
951
+ * Releases the resource after use.
952
+ */
938
953
  readonly release: ResultAsyncResourceRelease<Resource>;
939
954
  /**
940
- * Optional external abort signal for the full lifecycle.
941
- */
955
+ * Optional external abort signal for the full lifecycle.
956
+ */
942
957
  readonly signal?: ResultAsyncAbortSignal;
943
958
  /**
944
- * Uses the acquired resource.
945
- */
959
+ * Uses the acquired resource.
960
+ */
946
961
  readonly use: ResultAsyncResourceUse<Resource, T, UseError>;
947
962
  }
948
963
  type FirstSuccessOfAsync<Candidates extends Iterable<ResultAsyncCandidate>> = ResultAsync<InferAsyncOkTypes<ReturnType<IterableElement<Candidates>>>, InferAsyncErrTypes<ReturnType<IterableElement<Candidates>>>>;
@@ -1007,467 +1022,469 @@ interface ResultAsyncIfOptions<OnTrue extends ResultAsyncConditional, OnFalse ex
1007
1022
  readonly onFalse: () => OnFalse;
1008
1023
  readonly onTrue: () => OnTrue;
1009
1024
  }
1025
+ /** Async-disposable wrapper that finalizes a `ResultAsync` exactly once. */
1010
1026
  declare class DisposableResultAsync<T, E> implements PromiseLike<Result<T, E>>, AsyncDisposable {
1011
1027
  private readonly innerPromise;
1012
1028
  private readonly finalizer;
1013
1029
  private disposed;
1014
1030
  /**
1015
- * Creates an async disposable wrapper around a ResultAsync promise.
1016
- */
1031
+ * Creates an async disposable wrapper around a ResultAsync promise.
1032
+ */
1017
1033
  constructor(res: Promise<Result<T, E>>, finalizer: ResultAsyncFinalizer<T, E>);
1018
1034
  /**
1019
- * PromiseLike integration. Resolves to the wrapped Result.
1020
- */
1035
+ * PromiseLike integration. Resolves to the wrapped Result.
1036
+ */
1021
1037
  then<A, B>(successCallback?: (res: Result<T, E>) => A | PromiseLike<A>, failureCallback?: (reason: unknown) => B | PromiseLike<B>): PromiseLike<A | B>;
1022
1038
  /**
1023
- * Runs the finalizer once after the wrapped Result resolves.
1024
- *
1025
- * Finalizer exceptions and rejections are intentionally swallowed.
1026
- */
1039
+ * Runs the finalizer once after the wrapped Result resolves.
1040
+ *
1041
+ * Finalizer exceptions and rejections are intentionally swallowed.
1042
+ */
1027
1043
  [Symbol.asyncDispose](): Promise<void>;
1028
1044
  }
1029
1045
  /**
1030
- * Represents an asynchronous Result type that wraps a Promise of a Result<T, E>.
1031
- * This class provides a way to handle asynchronous operations that may succeed with a value of type T
1032
- * or fail with an error of type E.
1033
- *
1034
- * @template T - The type of the success value
1035
- * @template E - The type of the error value
1036
- *
1037
- * @implements {PromiseLike<Result<T, E>>}
1038
- *
1039
- * @example
1040
- * ```typescript
1041
- * // Create a successful async result
1042
- * const okAsync = ResultAsync.okAsync(42);
1043
- *
1044
- * // Create a failed async result
1045
- * const errAsync = ResultAsync.errAsync(new Error("Something went wrong"));
1046
- *
1047
- * // Transform a Promise into a ResultAsync
1048
- * const resultFromPromise = ResultAsync.fromPromise(
1049
- * fetch("https://api.example.com/data"),
1050
- * (error) => new Error(`API call failed: ${error}`)
1051
- * );
1052
- * ```
1053
- *
1054
- * @remarks
1055
- * ResultAsync implements the PromiseLike interface, allowing it to be used with async/await syntax.
1056
- * It provides various utility methods for transforming and combining results, similar to the Result type,
1057
- * but operating in an asynchronous context.
1058
- *
1059
- * The class includes methods for:
1060
- * - Creating ResultAsync instances (okAsync, errAsync, fromPromise, fromCallback)
1061
- * - Transforming values (map, mapErr)
1062
- * - Chaining operations (andThen, orElse)
1063
- * - Error handling (tapError)
1064
- * - Conditional branching (if)
1065
- * - Combining multiple ResultAsync instances (combine, combineWithAllErrors)
1066
- */
1046
+ * Represents an asynchronous Result type that wraps a Promise of a Result<T, E>.
1047
+ * This class provides a way to handle asynchronous operations that may succeed with a value of type T
1048
+ * or fail with an error of type E.
1049
+ *
1050
+ * @template T - The type of the success value
1051
+ * @template E - The type of the error value
1052
+ *
1053
+ * @implements {PromiseLike<Result<T, E>>}
1054
+ *
1055
+ * @example
1056
+ * ```typescript
1057
+ * // Create a successful async result
1058
+ * const okAsync = ResultAsync.okAsync(42);
1059
+ *
1060
+ * // Create a failed async result
1061
+ * const errAsync = ResultAsync.errAsync(new Error("Something went wrong"));
1062
+ *
1063
+ * // Transform a Promise into a ResultAsync
1064
+ * const resultFromPromise = ResultAsync.fromPromise(
1065
+ * fetch("https://api.example.com/data"),
1066
+ * (error) => new Error(`API call failed: ${error}`)
1067
+ * );
1068
+ * ```
1069
+ *
1070
+ * @remarks
1071
+ * ResultAsync implements the PromiseLike interface, allowing it to be used with async/await syntax.
1072
+ * It provides various utility methods for transforming and combining results, similar to the Result type,
1073
+ * but operating in an asynchronous context.
1074
+ *
1075
+ * The class includes methods for:
1076
+ * - Creating ResultAsync instances (okAsync, errAsync, fromPromise, fromCallback)
1077
+ * - Transforming values (map, mapErr)
1078
+ * - Chaining operations (andThen, orElse)
1079
+ * - Error handling (tapError)
1080
+ * - Conditional branching (if)
1081
+ * - Combining multiple ResultAsync instances (combine, combineWithAllErrors)
1082
+ */
1067
1083
  declare class ResultAsync<T, E> extends Pipeable implements PromiseLike<Result<T, E>> {
1068
1084
  /**
1069
- * Returns a ResultAsync instance that is immediately resolved with a Result.ok(value).
1070
- *
1071
- * @param {T} value - The value to be wrapped in a Result.ok.
1072
- * @return {ResultAsync<T, E>} A ResultAsync instance with the given value and error type E.
1073
- */
1085
+ * Returns a ResultAsync instance that is immediately resolved with a Result.ok(value).
1086
+ *
1087
+ * @param {T} value - The value to be wrapped in a Result.ok.
1088
+ * @return {ResultAsync<T, E>} A ResultAsync instance with the given value and error type E.
1089
+ */
1074
1090
  static okAsync<T, E = never>(this: void, value: T): ResultAsync<T, E>;
1075
1091
  static okAsync<E = never>(this: void, value: void): ResultAsync<void, E>;
1076
1092
  /**
1077
- * Returns a ResultAsync that is immediately resolved with a Result.ok(undefined) value.
1078
- *
1079
- * @return {ResultAsync<undefined, E>} A ResultAsync instance with undefined as the value type and E as the error type.
1080
- */
1093
+ * Returns a ResultAsync that is immediately resolved with a Result.ok(undefined) value.
1094
+ *
1095
+ * @return {ResultAsync<undefined, E>} A ResultAsync instance with undefined as the value type and E as the error type.
1096
+ */
1081
1097
  static unitAsync<E = never>(this: void): ResultAsync<undefined, E>;
1082
1098
  /**
1083
- * Returns a ResultAsync instance that is immediately resolved with a Result.err(error).
1084
- *
1085
- * @param {E} error - The error to be wrapped in a Result.err.
1086
- * @return {ResultAsync<T, E>} A ResultAsync instance with the given error and value type T.
1087
- */
1099
+ * Returns a ResultAsync instance that is immediately resolved with a Result.err(error).
1100
+ *
1101
+ * @param {E} error - The error to be wrapped in a Result.err.
1102
+ * @return {ResultAsync<T, E>} A ResultAsync instance with the given error and value type T.
1103
+ */
1088
1104
  static errAsync<T = never, E = unknown>(this: void, err: E): ResultAsync<T, E>;
1089
1105
  static errAsync<T = never>(this: void, err: void): ResultAsync<T, void>;
1090
1106
  /**
1091
- * Creates a ResultAsync from a Promise, catching any errors that occur during its execution.
1092
- *
1093
- * Compatibility alias. Prefer the top-level `tryResultAsync` helper in new code.
1094
- *
1095
- * @param fn - The Promise or a function returning a Promise to be wrapped in a ResultAsync.
1096
- * @param errorFn - Optional function to transform the caught error into a specific error type.
1097
- * If not provided, the original error will be used.
1098
- * @returns A ResultAsync that will resolve to Ok with the promise's value if successful,
1099
- * or Err with either the transformed error (if errorFn is provided) or the original error.
1100
- *
1101
- * New code should use the top-level `tryResultAsync` helper instead.
1102
- */
1107
+ * Creates a ResultAsync from a Promise, catching any errors that occur during its execution.
1108
+ *
1109
+ * Compatibility alias. Prefer the top-level `tryResultAsync` helper in new code.
1110
+ *
1111
+ * @param fn - The Promise or a function returning a Promise to be wrapped in a ResultAsync.
1112
+ * @param errorFn - Optional function to transform the caught error into a specific error type.
1113
+ * If not provided, the original error will be used.
1114
+ * @returns A ResultAsync that will resolve to Ok with the promise's value if successful,
1115
+ * or Err with either the transformed error (if errorFn is provided) or the original error.
1116
+ *
1117
+ * New code should use the top-level `tryResultAsync` helper instead.
1118
+ */
1103
1119
  static tryCatch<T>(this: void, fn: Promise<T> | (() => Promise<T>)): ResultAsync<T, unknown>;
1104
1120
  static tryCatch<T, E>(this: void, fn: Promise<T> | (() => Promise<T>), errorFn: (e: unknown) => E): ResultAsync<T, E>;
1105
1121
  /**
1106
- * Returns a ResultAsync instance that is resolved with a Result.ok(value) or Result.err(error)
1107
- * based on the provided promise.
1108
- *
1109
- * @param {Promise<T>} promise - The promise to be wrapped in a ResultAsync.
1110
- * @return {ResultAsync<T, E>} A ResultAsync instance with the given promise and error type E.
1111
- */
1122
+ * Returns a ResultAsync instance that is resolved with a Result.ok(value) or Result.err(error)
1123
+ * based on the provided promise.
1124
+ *
1125
+ * @param {Promise<T>} promise - The promise to be wrapped in a ResultAsync.
1126
+ * @return {ResultAsync<T, E>} A ResultAsync instance with the given promise and error type E.
1127
+ */
1112
1128
  static fromSafePromise<T, E = never>(this: void, promise: PromiseLike<T>): ResultAsync<T, E>;
1113
1129
  /**
1114
- * Returns a ResultAsync instance that is resolved with a Result.ok(value) or Result.err(error)
1115
- * based on the provided promise.
1116
- *
1117
- * @param {Promise<T>} promise - The promise to be wrapped in a ResultAsync.
1118
- * @param {(e: unknown) => E} errorFn - A function that transforms the error from the promise into the error type E.
1119
- * @return {ResultAsync<T, E>} A ResultAsync instance with the given promise and error type E.
1120
- */
1130
+ * Returns a ResultAsync instance that is resolved with a Result.ok(value) or Result.err(error)
1131
+ * based on the provided promise.
1132
+ *
1133
+ * @param {Promise<T>} promise - The promise to be wrapped in a ResultAsync.
1134
+ * @param {(e: unknown) => E} errorFn - A function that transforms the error from the promise into the error type E.
1135
+ * @return {ResultAsync<T, E>} A ResultAsync instance with the given promise and error type E.
1136
+ */
1121
1137
  static fromPromise<T, E>(this: void, promise: PromiseLike<T>, errorFn: (e: unknown) => E): ResultAsync<T, E>;
1122
1138
  /**
1123
- * Adapts a callback or subscription API into a cancellable ResultAsync.
1124
- *
1125
- * The returned cleanup function runs once after resolve, reject, cancellation, or synchronous
1126
- * subscription failure. Cleanup errors are ignored.
1127
- */
1139
+ * Adapts a callback or subscription API into a cancellable ResultAsync.
1140
+ *
1141
+ * The returned cleanup function runs once after resolve, reject, cancellation, or synchronous
1142
+ * subscription failure. Cleanup errors are ignored.
1143
+ */
1128
1144
  static fromCallback<T, E>(this: void, options: ResultAsyncFromCallbackOptions<T, E>): ResultAsync<T, E | AbortError>;
1129
1145
  /**
1130
- * Combines many ResultAsync values and stops at the first Err.
1131
- *
1132
- * Arrays return an Ok array, records return an Ok record with the same keys, and iterables return
1133
- * an Ok readonly array.
1134
- */
1146
+ * Combines many ResultAsync values and stops at the first Err.
1147
+ *
1148
+ * Arrays return an Ok array, records return an Ok record with the same keys, and iterables return
1149
+ * an Ok readonly array.
1150
+ */
1135
1151
  static combine<T extends readonly [ResultAsync<unknown, unknown>, ...ResultAsync<unknown, unknown>[]]>(this: void, asyncResultList: T): CombineResultAsyncs<T>;
1136
1152
  static combine<T extends readonly ResultAsync<unknown, unknown>[]>(this: void, asyncResultList: T): CombineResultAsyncs<T>;
1137
1153
  static combine<T extends ResultAsyncRecord>(this: void, asyncResultRecord: T): CombineResultAsyncsRecord<T>;
1138
1154
  static combine<R extends ResultAsync<unknown, unknown>>(this: void, asyncResults: Iterable<R>): CombineResultAsyncsIterable<R>;
1139
1155
  /**
1140
- * Combines many ResultAsync values and collects every Err instead of stopping at the first one.
1141
- */
1156
+ * Combines many ResultAsync values and collects every Err instead of stopping at the first one.
1157
+ */
1142
1158
  static combineWithAllErrors<T extends readonly [ResultAsync<unknown, unknown>, ...ResultAsync<unknown, unknown>[]]>(this: void, asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
1143
1159
  static combineWithAllErrors<T extends readonly ResultAsync<unknown, unknown>[]>(this: void, asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
1144
1160
  static combineWithAllErrors<T extends ResultAsyncRecord>(this: void, asyncResultRecord: T): CombineResultAsyncsRecordWithAllErrors<T>;
1145
1161
  static combineWithAllErrors<R extends ResultAsync<unknown, unknown>>(this: void, asyncResults: Iterable<R>): CombineResultAsyncsIterableWithAllErrors<R>;
1146
1162
  /**
1147
- * Validates many ResultAsync values and collects every Err.
1148
- *
1149
- * When passed items plus a mapper, the mapper must return a ResultAsync for each item. Use the
1150
- * optional concurrency setting to bound parallel work.
1151
- */
1163
+ * Validates many ResultAsync values and collects every Err.
1164
+ *
1165
+ * When passed items plus a mapper, the mapper must return a ResultAsync for each item. Use the
1166
+ * optional concurrency setting to bound parallel work.
1167
+ */
1152
1168
  static validateAll<T extends readonly [ResultAsync<unknown, unknown>, ...ResultAsync<unknown, unknown>[]]>(this: void, asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
1153
1169
  static validateAll<T extends readonly ResultAsync<unknown, unknown>[]>(this: void, asyncResultList: T): CombineResultsWithAllErrorsArrayAsync<T>;
1154
1170
  static validateAll<Item, R extends ResultAsync<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options?: ResultAsyncValidateAllOptions): ResultAsyncValidatedAll<R>;
1155
1171
  /**
1156
- * Combines exactly two ResultAsync values into an Ok tuple or the first Err.
1157
- */
1172
+ * Combines exactly two ResultAsync values into an Ok tuple or the first Err.
1173
+ */
1158
1174
  static zip<Left extends ResultAsync<unknown, unknown>, Right extends ResultAsync<unknown, unknown>>(this: void, left: Left, right: Right): ResultAsyncZipped<Left, Right>;
1159
1175
  /**
1160
- * Retries a ResultAsync task according to a typed retry policy.
1161
- *
1162
- * The returned error channel includes the task error and `AbortError`.
1163
- */
1176
+ * Retries a ResultAsync task according to a typed retry policy.
1177
+ *
1178
+ * The returned error channel includes the task error and `AbortError`.
1179
+ */
1164
1180
  static retry<Task extends ResultAsyncRetryTask<unknown, unknown>>(this: void, task: Task, options: ResultAsyncRetryOptions<ResultAsyncRetryTaskErr<Task>>): ResultAsync<ResultAsyncRetryTaskOk<Task>, ResultAsyncRetryTaskErr<Task> | AbortError>;
1165
1181
  /**
1166
- * Retries a ResultAsync task and falls back to another Resultar operation after retry exhaustion.
1167
- */
1182
+ * Retries a ResultAsync task and falls back to another Resultar operation after retry exhaustion.
1183
+ */
1168
1184
  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>;
1169
1185
  /**
1170
- * Acquires, uses, and releases a resource with cleanup on every path.
1171
- *
1172
- * Release errors are intentionally not part of the success/error channel; model cleanup failures
1173
- * in `use` when they should affect control flow.
1174
- */
1186
+ * Acquires, uses, and releases a resource with cleanup on every path.
1187
+ *
1188
+ * Release errors are intentionally not part of the success/error channel; model cleanup failures
1189
+ * in `use` when they should affect control flow.
1190
+ */
1175
1191
  static withResource<Resource, AcquireError, T, UseError>(this: void, options: ResultAsyncWithResourceOptions<Resource, AcquireError, T, UseError>): ResultAsync<T, AcquireError | UseError | AbortError>;
1176
1192
  /**
1177
- * Races two cooperative ResultAsync tasks and returns the first settled Result.
1178
- */
1193
+ * Races two cooperative ResultAsync tasks and returns the first settled Result.
1194
+ */
1179
1195
  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>>;
1180
1196
  /**
1181
- * Races multiple cooperative ResultAsync tasks and returns the first settled Result.
1182
- */
1197
+ * Races multiple cooperative ResultAsync tasks and returns the first settled Result.
1198
+ */
1183
1199
  static raceAll<Tasks extends readonly [ResultAsyncRaceTask<unknown, unknown>, ...ResultAsyncRaceTask<unknown, unknown>[]]>(this: void, tasks: Tasks): ResultAsync<ResultAsyncRaceTasksOk<Tasks>, ResultAsyncRaceTasksErr<Tasks>>;
1184
1200
  /**
1185
- * Races two cooperative ResultAsync tasks and returns the first successful Ok.
1186
- *
1187
- * If both fail, the returned error is the final observed Err.
1188
- */
1201
+ * Races two cooperative ResultAsync tasks and returns the first successful Ok.
1202
+ *
1203
+ * If both fail, the returned error is the final observed Err.
1204
+ */
1189
1205
  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>>;
1190
1206
  /**
1191
- * Races two cooperative ResultAsync tasks and lets handlers decide what to do when either side
1192
- * settles first.
1193
- *
1194
- * Handlers receive the settled Result and a handle to the still-running opposite task.
1195
- */
1207
+ * Races two cooperative ResultAsync tasks and lets handlers decide what to do when either side
1208
+ * settles first.
1209
+ *
1210
+ * Handlers receive the settled Result and a handle to the still-running opposite task.
1211
+ */
1196
1212
  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: {
1197
1213
  readonly onLeftDone: (result: Result<ResultAsyncRaceTaskOk<Left>, ResultAsyncRaceTaskErr<Left>>, right: ResultAsyncRaceHandle<ResultAsyncRaceTaskOk<Right>, ResultAsyncRaceTaskErr<Right>>) => OnLeftDone;
1198
1214
  readonly onRightDone: (result: Result<ResultAsyncRaceTaskOk<Right>, ResultAsyncRaceTaskErr<Right>>, left: ResultAsyncRaceHandle<ResultAsyncRaceTaskOk<Left>, ResultAsyncRaceTaskErr<Left>>) => OnRightDone;
1199
1215
  }): ResultAsync<HandlerOk<OnLeftDone> | HandlerOk<OnRightDone>, HandlerErr<OnLeftDone> | HandlerErr<OnRightDone>>;
1200
1216
  /**
1201
- * Runs a cooperative ResultAsync task with a typed timeout error.
1202
- */
1217
+ * Runs a cooperative ResultAsync task with a typed timeout error.
1218
+ */
1203
1219
  static timeout<Task extends ResultAsyncRaceTask<unknown, unknown>, TimeoutError>(this: void, task: Task, options: ResultAsyncTimeoutOptions<TimeoutError>): ResultAsync<ResultAsyncRaceTaskOk<Task>, ResultAsyncRaceTaskErr<Task> | TimeoutError>;
1204
1220
  /**
1205
- * Runs async candidates until the first Ok and returns the last Err if every candidate fails.
1206
- */
1221
+ * Runs async candidates until the first Ok and returns the last Err if every candidate fails.
1222
+ */
1207
1223
  static firstSuccessOf<Candidates extends Iterable<ResultAsyncCandidate>>(this: void, candidates: Candidates): FirstSuccessOfAsync<Candidates>;
1208
1224
  /**
1209
- * Chooses one of two Resultar async branches from a boolean or Resultar boolean condition.
1210
- */
1225
+ * Chooses one of two Resultar async branches from a boolean or Resultar boolean condition.
1226
+ */
1211
1227
  static if<OnTrue extends ResultAsyncConditional, OnFalse extends ResultAsyncConditional>(this: void, condition: ResultAsyncBooleanCondition, options: ResultAsyncIfOptions<OnTrue, OnFalse>): ResultAsyncIf<never, OnTrue, OnFalse>;
1212
1228
  static if<Condition extends ResultAsyncConditionResult, OnTrue extends ResultAsyncConditional, OnFalse extends ResultAsyncConditional>(this: void, condition: Condition, options: ResultAsyncIfOptions<OnTrue, OnFalse>): ResultAsyncIf<HandlerErr<Condition>, OnTrue, OnFalse>;
1213
1229
  /**
1214
- * Runs `body` only when the condition is true; otherwise returns Ok(undefined).
1215
- */
1230
+ * Runs `body` only when the condition is true; otherwise returns Ok(undefined).
1231
+ */
1216
1232
  static when<R extends ResultAsyncConditional>(this: void, condition: ResultAsyncBooleanCondition, body: () => R): ResultAsyncWhen<R>;
1217
1233
  /**
1218
- * Runs `body` only when a Resultar boolean condition is Ok(true).
1219
- */
1234
+ * Runs `body` only when a Resultar boolean condition is Ok(true).
1235
+ */
1220
1236
  static whenResult<Condition extends ResultAsyncConditionResult, R extends ResultAsyncConditional>(this: void, condition: Condition, body: () => R): ResultAsyncWhenWithCondition<Condition, R>;
1221
1237
  /**
1222
- * Runs `body` only when the condition is false; otherwise returns Ok(undefined).
1223
- */
1238
+ * Runs `body` only when the condition is false; otherwise returns Ok(undefined).
1239
+ */
1224
1240
  static unless<R extends ResultAsyncConditional>(this: void, condition: ResultAsyncBooleanCondition, body: () => R): ResultAsyncWhen<R>;
1225
1241
  /**
1226
- * Runs `body` only when a Resultar boolean condition is Ok(false).
1227
- */
1242
+ * Runs `body` only when a Resultar boolean condition is Ok(false).
1243
+ */
1228
1244
  static unlessResult<Condition extends ResultAsyncConditionResult, R extends ResultAsyncConditional>(this: void, condition: Condition, body: () => R): ResultAsyncWhenWithCondition<Condition, R>;
1229
1245
  /**
1230
- * Repeats a ResultAsync-producing body while a condition holds.
1231
- *
1232
- * Use `discard: true` when only failure matters and collected Ok values are not needed.
1233
- */
1246
+ * Repeats a ResultAsync-producing body while a condition holds.
1247
+ *
1248
+ * Use `discard: true` when only failure matters and collected Ok values are not needed.
1249
+ */
1234
1250
  static loop<State, BodyState extends State, R extends ResultAsync<unknown, unknown>>(this: void, initial: State, options: ResultAsyncLoopOptions<State, BodyState, R>): ResultAsyncLoopCollected<R>;
1235
1251
  static loop<State, R extends ResultAsync<unknown, unknown>>(this: void, initial: State, options: ResultAsyncLoopBooleanOptions<State, R>): ResultAsyncLoopCollected<R>;
1236
1252
  static loop<State, BodyState extends State, R extends ResultAsync<unknown, unknown>>(this: void, initial: State, options: ResultAsyncLoopDiscardOptions<State, BodyState, R>): ResultAsyncLoopDiscarded<R>;
1237
1253
  static loop<State, R extends ResultAsync<unknown, unknown>>(this: void, initial: State, options: ResultAsyncLoopBooleanDiscardOptions<State, R>): ResultAsyncLoopDiscarded<R>;
1238
1254
  /**
1239
- * Repeatedly transforms state with a ResultAsync-producing body until the condition fails.
1240
- */
1255
+ * Repeatedly transforms state with a ResultAsync-producing body until the condition fails.
1256
+ */
1241
1257
  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>;
1242
1258
  static iterate<State, R extends ResultAsync<WidenLiteral<State>, unknown>>(this: void, initial: State, options: ResultAsyncIterateBooleanOptions<WidenLiteral<State>, R>): ResultAsyncIterated<WidenLiteral<State>, R>;
1243
1259
  /**
1244
- * Runs a ResultAsync-producing mapper for each item.
1245
- *
1246
- * Use `discard: true` when only failure matters and collected Ok values are not needed. Use
1247
- * `concurrency` to bound parallel work.
1248
- */
1260
+ * Runs a ResultAsync-producing mapper for each item.
1261
+ *
1262
+ * Use `discard: true` when only failure matters and collected Ok values are not needed. Use
1263
+ * `concurrency` to bound parallel work.
1264
+ */
1249
1265
  static forEach<Item, R extends ResultAsync<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options?: ResultAsyncForEachOptions): ResultAsyncForEachCollected<R>;
1250
1266
  static forEach<Item, R extends ResultAsync<unknown, unknown>>(this: void, items: Iterable<Item>, f: (value: Item, index: number) => R, options: ResultAsyncForEachDiscardOptions): ResultAsyncForEachDiscarded<R>;
1251
1267
  /**
1252
- * Wraps an async function so every later call returns a ResultAsync.
1253
- *
1254
- * Prefer `tryResultAsync` when you want to run the operation immediately.
1255
- */
1268
+ * Wraps an async function so every later call returns a ResultAsync.
1269
+ *
1270
+ * Prefer `tryResultAsync` when you want to run the operation immediately.
1271
+ */
1256
1272
  static fromThrowable<A extends readonly unknown[], T, E>(this: void, fn: (...args: A) => Promise<T>, errorFn?: (err: unknown) => E): (...args: A) => ResultAsync<T, E>;
1257
1273
  private readonly innerPromise;
1258
1274
  /**
1259
- * Creates a ResultAsync from a Promise that resolves to a Result.
1260
- *
1261
- * Most application code should prefer `tryResultAsync`, `fromPromise`, `okAsync`, or `errAsync`.
1262
- */
1275
+ * Creates a ResultAsync from a Promise that resolves to a Result.
1276
+ *
1277
+ * Most application code should prefer `tryResultAsync`, `fromPromise`, `okAsync`, or `errAsync`.
1278
+ */
1263
1279
  constructor(res: Promise<Result<T, E>>);
1264
1280
  /**
1265
- * PromiseLike integration. Resolves to the underlying `Result<T, E>`.
1266
- *
1267
- * Prefer ResultAsync combinators for application flow; this exists so ResultAsync can be awaited
1268
- * and used by Promise APIs.
1269
- */
1281
+ * PromiseLike integration. Resolves to the underlying `Result<T, E>`.
1282
+ *
1283
+ * Prefer ResultAsync combinators for application flow; this exists so ResultAsync can be awaited
1284
+ * and used by Promise APIs.
1285
+ */
1270
1286
  then<A, B>(successCallback?: (res: Result<T, E>) => A | PromiseLike<A>, failureCallback?: (reason: unknown) => B | PromiseLike<B>): PromiseLike<A | B>;
1271
1287
  /**
1272
- * Maps the Err value while preserving the Ok value.
1273
- */
1288
+ * Maps the Err value while preserving the Ok value.
1289
+ */
1274
1290
  mapErr<U>(f: (t: E) => U | Promise<U>): ResultAsync<T, U>;
1275
1291
  /**
1276
- * Maps the Ok value while preserving the error channel.
1277
- */
1292
+ * Maps the Ok value while preserving the error channel.
1293
+ */
1278
1294
  map<X>(f: (t: T) => X | Promise<X>): ResultAsync<X, E>;
1279
1295
  /**
1280
- * Replaces the Ok value with a constant while preserving the error channel.
1281
- */
1296
+ * Replaces the Ok value with a constant while preserving the error channel.
1297
+ */
1282
1298
  as<X>(value: X): ResultAsync<X, E>;
1283
1299
  /**
1284
- * Keeps the Ok value only when the predicate passes; otherwise returns an Err from `onFalse`.
1285
- */
1300
+ * Keeps the Ok value only when the predicate passes; otherwise returns an Err from `onFalse`.
1301
+ */
1286
1302
  filterOrElse<U extends T, F>(predicate: (value: T) => value is U, onFalse: (value: T) => F | Promise<F>): ResultAsync<U, E | F>;
1287
1303
  filterOrElse<F>(predicate: (value: T) => boolean | Promise<boolean>, onFalse: (value: T) => F | Promise<F>): ResultAsync<T, E | F>;
1288
1304
  /**
1289
- * Chains another fallible sync or async operation from the Ok value.
1290
- *
1291
- * Use this instead of `map` when the callback returns `Result` or `ResultAsync`.
1292
- */
1305
+ * Chains another fallible sync or async operation from the Ok value.
1306
+ *
1307
+ * Use this instead of `map` when the callback returns `Result` or `ResultAsync`.
1308
+ */
1293
1309
  andThen<R extends Result<unknown, unknown>>(f: (t: T) => R): ResultAsync<InferOkTypes<R>, InferErrTypes<R> | E>;
1294
1310
  andThen<R extends ResultAsync<unknown, unknown>>(f: (t: T) => R): ResultAsync<InferAsyncOkTypes<R>, InferAsyncErrTypes<R> | E>;
1295
1311
  andThen<U, F>(f: (t: T) => Result<U, F> | ResultAsync<U, F>): ResultAsync<U, E | F>;
1296
1312
  /**
1297
- * Branches from the Ok value into one of two async fallible Result branches.
1298
- */
1313
+ * Branches from the Ok value into one of two async fallible Result branches.
1314
+ */
1299
1315
  if(fCondition: (t: T) => boolean): {
1300
1316
  true: <X1, Y1>(fTrue: (t: T) => ResultAsync<X1, Y1>) => {
1301
1317
  false: <X2, Y2>(fFalse: (t: T) => ResultAsync<X2, Y2>) => ResultAsync<X1 | X2, Y1 | Y2 | E>;
1302
1318
  };
1303
1319
  };
1304
1320
  /**
1305
- * Recovers from Err with another Result or ResultAsync.
1306
- */
1321
+ * Recovers from Err with another Result or ResultAsync.
1322
+ */
1307
1323
  orElse<R extends Result<unknown, unknown>>(f: (e: E) => R): ResultAsync<InferOkTypes<R> | T, InferErrTypes<R>>;
1308
1324
  orElse<R extends ResultAsync<unknown, unknown>>(f: (e: E) => R): ResultAsync<InferAsyncOkTypes<R> | T, InferAsyncErrTypes<R>>;
1309
1325
  orElse<U, A>(f: (e: E) => Result<U, A> | ResultAsync<U, A>): ResultAsync<U | T, A>;
1310
1326
  /**
1311
- * Recovers from a specific tagged error by `_tag`.
1312
- */
1327
+ * Recovers from a specific tagged error by `_tag`.
1328
+ */
1313
1329
  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>>;
1314
1330
  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>>;
1315
1331
  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>;
1316
1332
  /**
1317
- * Recovers from multiple tagged errors by `_tag`.
1318
- */
1333
+ * Recovers from multiple tagged errors by `_tag`.
1334
+ */
1319
1335
  catchTags<const Handlers extends object>(handlers: Handlers & ResultAsyncCatchTagHandlers<E, Handlers>): ResultAsync<T | HandlerOk<CatchTagHandlerResult<Handlers>>, ExcludeTag<E, keyof Handlers & string> | HandlerErr<CatchTagHandlerResult<Handlers>>>;
1320
1336
  /**
1321
- * Recovers from a nested tagged `reason` on a specific tagged error.
1322
- */
1337
+ * Recovers from a nested tagged `reason` on a specific tagged error.
1338
+ */
1323
1339
  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>>;
1324
1340
  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>>;
1325
1341
  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>;
1326
1342
  /**
1327
- * Recovers from multiple nested tagged `reason` variants on a specific tagged error.
1328
- */
1343
+ * Recovers from multiple nested tagged `reason` variants on a specific tagged error.
1344
+ */
1329
1345
  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>>>;
1330
1346
  /**
1331
- * Moves the nested `reason` of a tagged error into the ResultAsync error channel.
1332
- */
1347
+ * Moves the nested `reason` of a tagged error into the ResultAsync error channel.
1348
+ */
1333
1349
  unwrapReason<const ErrorTag extends TagsWithReasonOf<E>>(errorTag: ErrorTag): ResultAsync<T, ExcludeTag<E, ErrorTag> | ReasonsOf<E, ErrorTag>>;
1334
1350
  /**
1335
- * Converts this ResultAsync into a Promise of a plain value by handling both Ok and Err.
1336
- */
1351
+ * Converts this ResultAsync into a Promise of a plain value by handling both Ok and Err.
1352
+ */
1337
1353
  match<A, B = A>(handlers: MatchHandlers$1<T, E, A, B>): Promise<A | B>;
1338
1354
  match<A, B = A>(ok: (t: T) => A, fnErr: (e: E) => B): Promise<A | B>;
1339
1355
  /**
1340
- * Converts this ResultAsync into a Promise of a plain value with exhaustive tagged-error handlers.
1341
- */
1356
+ * Converts this ResultAsync into a Promise of a plain value with exhaustive tagged-error handlers.
1357
+ */
1342
1358
  matchTags<A, const Handlers extends object>(ok: (t: T) => A, handlers: Handlers & MatchTagHandlers<E, Handlers>): Promise<A | MatchTagHandlerResult<Handlers>>;
1343
1359
  /**
1344
- * Converts this ResultAsync into a Promise of a plain value with partial tagged-error handlers and
1345
- * a fallback.
1346
- */
1360
+ * Converts this ResultAsync into a Promise of a plain value with partial tagged-error handlers and
1361
+ * a fallback.
1362
+ */
1347
1363
  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>;
1348
1364
  /**
1349
- * Resolves to the Ok value, or `t` when this ResultAsync is Err.
1350
- */
1365
+ * Resolves to the Ok value, or `t` when this ResultAsync is Err.
1366
+ */
1351
1367
  unwrapOr<A>(t: A): Promise<T | A>;
1352
1368
  /**
1353
- * Resolves to the Ok value or rejects with the Err value.
1354
- *
1355
- * Use this at final application boundaries after the error channel has been modeled.
1356
- */
1369
+ * Resolves to the Ok value or rejects with the Err value.
1370
+ *
1371
+ * Use this at final application boundaries after the error channel has been modeled.
1372
+ */
1357
1373
  unwrapOrThrow(): Promise<T>;
1358
1374
  /**
1359
- * Runs a side effect for either variant and preserves the original async result.
1360
- *
1361
- * For `Ok`, the callback receives `(value, undefined)`.
1362
- * For `Err`, the callback receives `(undefined, error)`.
1363
- * Callback errors and rejected callback promises are intentionally ignored.
1364
- *
1365
- * Use `map`, `mapErr`, `andThen`, or `orElse` when the callback should
1366
- * transform the result.
1367
- */
1375
+ * Runs a side effect for either variant and preserves the original async result.
1376
+ *
1377
+ * For `Ok`, the callback receives `(value, undefined)`.
1378
+ * For `Err`, the callback receives `(undefined, error)`.
1379
+ * Callback errors and rejected callback promises are intentionally ignored.
1380
+ *
1381
+ * Use `map`, `mapErr`, `andThen`, or `orElse` when the callback should
1382
+ * transform the result.
1383
+ */
1368
1384
  log(f: (t?: T, e?: E) => void | Promise<void>): ResultAsync<T, E>;
1369
1385
  /**
1370
- * Runs a side effect only for the `Ok` variant and preserves the original async result.
1371
- *
1372
- * Callback errors and rejected callback promises are intentionally ignored.
1373
- * Use `map` or `andThen` when the callback should transform the value.
1374
- */
1386
+ * Runs a side effect only for the `Ok` variant and preserves the original async result.
1387
+ *
1388
+ * Callback errors and rejected callback promises are intentionally ignored.
1389
+ * Use `map` or `andThen` when the callback should transform the value.
1390
+ */
1375
1391
  tap(f: (t: T) => void | Promise<void>): ResultAsync<T, E>;
1376
1392
  /**
1377
- * Runs a side effect only for the `Err` variant and preserves the original async result.
1378
- *
1379
- * Callback errors and rejected callback promises are intentionally ignored.
1380
- * Use `mapErr` or `orElse` when the callback should transform the error.
1381
- */
1393
+ * Runs a side effect only for the `Err` variant and preserves the original async result.
1394
+ *
1395
+ * Callback errors and rejected callback promises are intentionally ignored.
1396
+ * Use `mapErr` or `orElse` when the callback should transform the error.
1397
+ */
1382
1398
  tapError(f: (e: E) => void | Promise<void>): ResultAsync<T, E>;
1383
1399
  /**
1384
- * Attaches an async disposal finalizer to this ResultAsync.
1385
- */
1400
+ * Attaches an async disposal finalizer to this ResultAsync.
1401
+ */
1386
1402
  toAsyncDisposable(f: ResultAsyncFinalizer<T, E>): DisposableResultAsync<T, E>;
1387
1403
  /**
1388
- * Enables `yield* resultAsync` inside async `safeTry` generators.
1389
- */
1404
+ * Enables `yield* resultAsync` inside async `safeTry` generators.
1405
+ */
1390
1406
  [Symbol.asyncIterator](): AsyncGenerator<Result<never, E>, T>;
1391
1407
  }
1408
+ /** `ResultAsync` convention that restricts the error channel to real `Error` instances. */
1392
1409
  type StrictResultAsync<T, E extends Error = Error> = ResultAsync<T, E>;
1393
1410
  /**
1394
- * Creates an Ok ResultAsync.
1395
- */
1411
+ * Creates an Ok ResultAsync.
1412
+ */
1396
1413
  declare const okAsync: typeof ResultAsync.okAsync;
1397
1414
  /**
1398
- * Creates an Err ResultAsync.
1399
- */
1415
+ * Creates an Err ResultAsync.
1416
+ */
1400
1417
  declare const errAsync: typeof ResultAsync.errAsync;
1401
1418
  /**
1402
- * Adapts a callback or subscription API into a cancellable ResultAsync.
1403
- */
1419
+ * Adapts a callback or subscription API into a cancellable ResultAsync.
1420
+ */
1404
1421
  declare const fromCallback: typeof ResultAsync.fromCallback;
1405
1422
  /**
1406
- * Converts an existing promise into a ResultAsync and maps rejection into a typed Err.
1407
- */
1423
+ * Converts an existing promise into a ResultAsync and maps rejection into a typed Err.
1424
+ */
1408
1425
  declare const fromPromise: typeof ResultAsync.fromPromise;
1409
1426
  /**
1410
- * Converts an existing promise that is expected not to reject into a ResultAsync.
1411
- *
1412
- * Use `fromPromise` or `tryResultAsync` when rejection should become a typed Err.
1413
- */
1427
+ * Converts an existing promise that is expected not to reject into a ResultAsync.
1428
+ *
1429
+ * Use `fromPromise` or `tryResultAsync` when rejection should become a typed Err.
1430
+ */
1414
1431
  declare const fromSafePromise: typeof ResultAsync.fromSafePromise;
1415
1432
  /**
1416
- * Creates an Ok ResultAsync with `undefined`.
1417
- */
1433
+ * Creates an Ok ResultAsync with `undefined`.
1434
+ */
1418
1435
  declare const unitAsync: typeof ResultAsync.unitAsync;
1419
1436
  /**
1420
- * Wraps an async function so every later call returns a ResultAsync.
1421
- */
1437
+ * Wraps an async function so every later call returns a ResultAsync.
1438
+ */
1422
1439
  declare const fromThrowableAsync: typeof ResultAsync.fromThrowable;
1423
1440
  /**
1424
- * Captures a promise or async factory into `ResultAsync<T, E>`.
1425
- *
1426
- * Use `tryResultAsync` at the edge of uncontrolled async code: network calls, file I/O,
1427
- * third-party SDKs, JSON parsing promises, and framework APIs that can reject. The mapper receives
1428
- * the rejected or thrown `unknown` cause and returns the typed error for the Resultar channel.
1429
- *
1430
- * Passing a factory is preferred when creating the promise can throw synchronously.
1431
- *
1432
- * @example
1433
- * ```ts
1434
- * const user = tryResultAsync(
1435
- * () => fetchUser(id),
1436
- * (cause) => new FetchUserError({ cause, id }),
1437
- * )
1438
- * ```
1439
- */
1441
+ * Captures a promise or async factory into `ResultAsync<T, E>`.
1442
+ *
1443
+ * Use `tryResultAsync` at the edge of uncontrolled async code: network calls, file I/O,
1444
+ * third-party SDKs, JSON parsing promises, and framework APIs that can reject. The mapper receives
1445
+ * the rejected or thrown `unknown` cause and returns the typed error for the Resultar channel.
1446
+ *
1447
+ * Passing a factory is preferred when creating the promise can throw synchronously.
1448
+ *
1449
+ * @example
1450
+ * ```ts
1451
+ * const user = tryResultAsync(
1452
+ * () => fetchUser(id),
1453
+ * (cause) => new FetchUserError({ cause, id }),
1454
+ * )
1455
+ * ```
1456
+ */
1440
1457
  declare function tryResultAsync<T, E>(fn: Promise<T> | (() => Promise<T>), errorFn: (e: unknown) => E): ResultAsync<T, E>;
1441
1458
  /**
1442
- * Captures an async boundary with named `try` and `catch` fields.
1443
- *
1444
- * This is equivalent to `tryResultAsync(() => ..., toError)`, but it reads better for reusable
1445
- * infrastructure helpers where the label, task, and mapper live together.
1446
- *
1447
- * @example
1448
- * ```ts
1449
- * const startup = tryResultAsync({
1450
- * try: () => fastify.register(plugin),
1451
- * catch: (cause) => new StartupTaskError({ cause, label: "register plugin" }),
1452
- * })
1453
- * ```
1454
- */
1459
+ * Captures an async boundary with named `try` and `catch` fields.
1460
+ *
1461
+ * This is equivalent to `tryResultAsync(() => ..., toError)`, but it reads better for reusable
1462
+ * infrastructure helpers where the label, task, and mapper live together.
1463
+ *
1464
+ * @example
1465
+ * ```ts
1466
+ * const startup = tryResultAsync({
1467
+ * try: () => fastify.register(plugin),
1468
+ * catch: (cause) => new StartupTaskError({ cause, label: "register plugin" }),
1469
+ * })
1470
+ * ```
1471
+ */
1455
1472
  declare function tryResultAsync<T, E>(options: TryResultAsyncOptions<T, E> & {
1456
1473
  readonly catch: (e: unknown) => E;
1457
1474
  }): ResultAsync<T, E>;
1458
1475
  /**
1459
- * Captures a promise or async factory into `ResultAsync<T, unknown>`.
1460
- *
1461
- * Prefer the overload with a catch mapper in application code so the error channel stays documented.
1462
- * This overload is useful while adapting unknown external failures or during migration.
1463
- */
1476
+ * Captures a promise or async factory into `ResultAsync<T, unknown>`.
1477
+ *
1478
+ * Prefer the overload with a catch mapper in application code so the error channel stays documented.
1479
+ * This overload is useful while adapting unknown external failures or during migration.
1480
+ */
1464
1481
  declare function tryResultAsync<T>(input: Promise<T> | (() => Promise<T>) | TryResultAsyncOptions<T>): ResultAsync<T, unknown>;
1465
1482
  /**
1466
- * Runs a `ResultAsync` at an application boundary and returns the success value.
1467
- *
1468
- * If the result is `Err`, this rejects with the error. Use it at final framework, CLI, test, or
1469
- * bootstrap boundaries after the error channel has already been modeled with Resultar.
1470
- */
1483
+ * Runs a `ResultAsync` at an application boundary and returns the success value.
1484
+ *
1485
+ * If the result is `Err`, this rejects with the error. Use it at final framework, CLI, test, or
1486
+ * bootstrap boundaries after the error channel has already been modeled with Resultar.
1487
+ */
1471
1488
  declare const runPromise: <T, E>(result: ResultAsync<T, E>) => Promise<T>;
1472
1489
  /** Compatibility alias. Prefer `tryResultAsync` in new code. */
1473
1490
  declare const tryCatchAsync: typeof tryResultAsync;
@@ -1480,40 +1497,162 @@ type Writable<T> = T extends readonly unknown[] ? [...T] : T;
1480
1497
  //#endregion
1481
1498
  //#region src/redacted.d.ts
1482
1499
  /**
1483
- * String-like wrapper that hides a sensitive value in messages and JSON output.
1484
- */
1500
+ * String-like wrapper that hides a sensitive value in messages and JSON output.
1501
+ */
1485
1502
  type Redacted<T> = string & {
1486
1503
  /**
1487
- * Internal marker used by `isRedacted`.
1488
- */
1504
+ * Internal marker used by `isRedacted`.
1505
+ */
1489
1506
  readonly __resultarRedacted: true;
1490
1507
  readonly __resultarRedactedType?: T;
1491
1508
  /**
1492
- * Optional label shown as `<redacted:label>`.
1493
- */
1509
+ * Optional label shown as `<redacted:label>`.
1510
+ */
1494
1511
  readonly label: string | undefined;
1495
1512
  /**
1496
- * Serializes to the redacted placeholder.
1497
- */
1513
+ * Serializes to the redacted placeholder.
1514
+ */
1498
1515
  toJSON: () => string;
1499
1516
  /**
1500
- * Converts to the redacted placeholder.
1501
- */
1517
+ * Converts to the redacted placeholder.
1518
+ */
1502
1519
  toString: () => string;
1503
1520
  };
1504
1521
  /**
1505
- * Wraps a sensitive value so tagged-error messages and JSON output show only a placeholder.
1506
- */
1522
+ * Wraps a sensitive value so tagged-error messages and JSON output show only a placeholder.
1523
+ */
1507
1524
  declare const redact: <T>(value: T, label?: string) => Redacted<T>;
1508
1525
  /**
1509
- * Checks whether a value was created by `redact`.
1510
- */
1526
+ * Checks whether a value was created by `redact`.
1527
+ */
1511
1528
  declare const isRedacted: (value: unknown) => value is Redacted<unknown>;
1512
1529
  /**
1513
- * Returns the original sensitive value from a Redacted wrapper.
1514
- */
1530
+ * Returns the original sensitive value from a Redacted wrapper.
1531
+ */
1515
1532
  declare const revealRedacted: <T>(value: Redacted<T>) => T;
1516
1533
  //#endregion
1534
+ //#region src/result-task.d.ts
1535
+ /** A failure cause produced by a `ResultTask` execution. */
1536
+ type Cause<E> = {
1537
+ readonly _tag: "Fail";
1538
+ readonly error: E;
1539
+ } | {
1540
+ readonly _tag: "Die";
1541
+ readonly defect: unknown;
1542
+ };
1543
+ /** The complete outcome of a `ResultTask` execution. */
1544
+ type Exit<A, E> = {
1545
+ readonly _tag: "Success";
1546
+ readonly value: A;
1547
+ } | {
1548
+ readonly _tag: "Failure";
1549
+ readonly cause: Cause<E>;
1550
+ };
1551
+ /** A service that can be requested from a `ResultTask.gen` workflow. */
1552
+ interface ServiceTag<Identifier extends string, Service> {
1553
+ readonly _tag: "ServiceTag";
1554
+ readonly identifier: Identifier;
1555
+ readonly key: symbol;
1556
+ readonly [Symbol.iterator]: () => Generator<ResultTaskServiceYield<ServiceTag<Identifier, Service>>, Service, Service>;
1557
+ }
1558
+ /** Options for running a `ResultTask` with an optional signal and its required services. */
1559
+ type ResultTaskRunOptions<R = never> = {
1560
+ readonly signal?: AbortSignal;
1561
+ } & ([R] extends [never] ? {
1562
+ readonly services?: never;
1563
+ } : {
1564
+ readonly services: ResultTaskServices<R>;
1565
+ });
1566
+ /** The object-shaped service environment required by a task. */
1567
+ type ResultTaskServices<R> = { readonly [Tag in Extract<R, AnyServiceTag> as Tag["identifier"]]: ServiceForTag<Tag>; };
1568
+ /** Options for creating a synchronous task with an explicit error boundary. */
1569
+ interface ResultTaskTryOptions<A, E> {
1570
+ readonly try: () => A;
1571
+ readonly catch: (cause: unknown) => E;
1572
+ }
1573
+ /** Options for creating a lazy promise-producing task with an explicit error boundary. */
1574
+ interface ResultTaskTryPromiseOptions<A, E> {
1575
+ readonly try: (signal: AbortSignal) => PromiseLike<A>;
1576
+ readonly catch: (cause: unknown) => E;
1577
+ }
1578
+ type AnyServiceTag = Pick<ServiceTag<string, unknown>, "_tag" | "identifier" | "key">;
1579
+ type ServiceForTag<Tag> = Tag extends ServiceTag<string, infer Service> ? Service : never;
1580
+ interface ResultTaskYield<A, E, R> {
1581
+ readonly _tag: "ResultTask";
1582
+ readonly task: ResultTask<A, E, R>;
1583
+ }
1584
+ interface ResultTaskServiceYield<Tag extends AnyServiceTag> {
1585
+ readonly _tag: "Service";
1586
+ readonly tag: Tag;
1587
+ }
1588
+ type GeneratorError<Yield> = Yield extends {
1589
+ readonly _tag: "ResultTask";
1590
+ readonly task: infer Task;
1591
+ } ? Task extends ResultTask<infer _A, infer E, infer _R> ? E : never : never;
1592
+ type GeneratorRequirements<Yield> = Yield extends {
1593
+ readonly _tag: "ResultTask";
1594
+ readonly task: infer Task;
1595
+ } ? Task extends ResultTask<infer _A, infer _E, infer R> ? R : never : Yield extends {
1596
+ readonly _tag: "Service";
1597
+ readonly tag: infer Tag;
1598
+ } ? Tag : never;
1599
+ type ResultTaskRunArguments<R> = [R] extends [never] ? [options?: ResultTaskRunOptions<R>] : [options: ResultTaskRunOptions<R>];
1600
+ /**
1601
+ * A lazy, composable workflow that can succeed with `A` or fail with `E`.
1602
+ *
1603
+ * Constructing a `ResultTask` never runs its work. Use `runResult`, `runExit`, or `runPromise` at an
1604
+ * explicit application boundary to execute it.
1605
+ */
1606
+ declare class ResultTask<A, E = never, R = never> extends Pipeable {
1607
+ private readonly execute;
1608
+ private constructor();
1609
+ private readonly typeWitness;
1610
+ /** Creates a task that succeeds with `value` when it is executed. */
1611
+ static succeed<A, E = never>(value: A): ResultTask<A, E>;
1612
+ /** Creates a task that fails with `error` when it is executed. */
1613
+ static fail<const E>(error: E): ResultTask<never, E>;
1614
+ /** Lifts an already computed Result into a lazy task. */
1615
+ static fromResult<A, E>(result: Result<A, E>): ResultTask<A, E>;
1616
+ /** Creates a task for synchronous work. Thrown values are defects, not typed failures. */
1617
+ static sync<A>(evaluate: () => A): ResultTask<A>;
1618
+ /** Creates a task that maps synchronous throws into the typed error channel. */
1619
+ static try<A, E>(options: ResultTaskTryOptions<A, E>): ResultTask<A, E>;
1620
+ /** Creates a lazy task that maps synchronous throws and promise rejections into `E`. */
1621
+ static tryPromise<A, E>(options: ResultTaskTryPromiseOptions<A, E>): ResultTask<A, E>;
1622
+ /** Creates a service tag that can be requested with `yield*` inside `ResultTask.gen`. */
1623
+ static service<Service, const Identifier extends string>(identifier: Identifier): ServiceTag<Identifier, Service>;
1624
+ /** Builds a task from a generator and short-circuits on the first failed task. */
1625
+ static gen<Yield, Return, Next>(body: () => Generator<Yield, Return, Next>): ResultTask<Return, GeneratorError<Yield>, GeneratorRequirements<Yield>>;
1626
+ /** Maps the success value without executing the task. */
1627
+ map<B>(f: (value: A) => B): ResultTask<B, E, R>;
1628
+ /** Chains another task from the success value without executing either task immediately. */
1629
+ flatMap<B, E2, R2>(f: (value: A) => ResultTask<B, E2, R2>): ResultTask<B, E | E2, R | R2>;
1630
+ /** Alias for `flatMap`, matching the existing Resultar vocabulary. */
1631
+ andThen<B, E2, R2>(f: (value: A) => ResultTask<B, E2, R2>): ResultTask<B, E | E2, R | R2>;
1632
+ /** Recovers from a typed failure without recovering from a runtime defect. */
1633
+ catchAll<B, E2, R2>(f: (error: E) => ResultTask<B, E2, R2>): ResultTask<A | B, E2, R | R2>;
1634
+ /** Enables `yield* task` inside `ResultTask.gen` workflows. */
1635
+ [Symbol.iterator](): Generator<ResultTaskYield<A, E, R>, A, Exit<A, E>>;
1636
+ /** Provides one required service and removes it from the task's requirements. */
1637
+ static provideService<A, E, R, Tag extends Extract<R, AnyServiceTag>>(task: ResultTask<A, E, R>, tag: Tag, service: ServiceForTag<Tag>): ResultTask<A, E, Exclude<R, Tag>>;
1638
+ /** Provides all requirements using an object keyed by service identifier. */
1639
+ static provideServices<A, E, R>(task: ResultTask<A, E, R>, services: ResultTaskServices<R>): ResultTask<A, E>;
1640
+ /** Maps the success value using the canonical functional form. */
1641
+ static map<A, E, R, B>(task: ResultTask<A, E, R>, f: (value: A) => B): ResultTask<B, E, R>;
1642
+ /** Chains a task using the canonical functional form. */
1643
+ static flatMap<A, E, R, B, E2, R2>(task: ResultTask<A, E, R>, f: (value: A) => ResultTask<B, E2, R2>): ResultTask<B, E | E2, R | R2>;
1644
+ /** Recovers from a typed failure using the canonical functional form. */
1645
+ static catchAll<A, E, R, B, E2, R2>(task: ResultTask<A, E, R>, f: (error: E) => ResultTask<B, E2, R2>): ResultTask<A | B, E2, R | R2>;
1646
+ private static runExitInternal;
1647
+ private static runResultInternal;
1648
+ /** Runs a task and preserves success, typed failure, and runtime defects in an `Exit`. */
1649
+ static runExit<A, E, R>(task: ResultTask<A, E, R>, ...args: ResultTaskRunArguments<R>): Promise<Exit<A, E>>;
1650
+ /** Runs a task and returns a Result, rejecting only when a runtime defect occurs. */
1651
+ static runResult<A, E, R>(task: ResultTask<A, E, R>, ...args: ResultTaskRunArguments<R>): Promise<Result<A, E>>;
1652
+ /** Runs a task and returns the success value, rejecting on typed failures or defects. */
1653
+ static runPromise<A, E, R>(task: ResultTask<A, E, R>, ...args: ResultTaskRunArguments<R>): Promise<A>;
1654
+ }
1655
+ //#endregion
1517
1656
  //#region src/tagged-error.d.ts
1518
1657
  type Alpha = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" | "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I" | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R" | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" | "_";
1519
1658
  type Digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
@@ -1542,85 +1681,86 @@ type ConstructorProps<Template extends string> = TemplateProps<Template> & {
1542
1681
  type TaggedErrorConstructorArgs<Template extends string> = [ExtractTemplateVariables<Template>] extends [never] ? [props?: {
1543
1682
  readonly cause?: unknown;
1544
1683
  }] : [props: ConstructorProps<Template>];
1684
+ /** Configuration used to create a tagged `Error` class. */
1545
1685
  interface TaggedErrorOptions<Tag extends string, MessageTemplate extends string, Base extends Error = Error> {
1546
1686
  /**
1547
- * Optional base Error class to extend instead of native Error.
1548
- */
1687
+ * Optional base Error class to extend instead of native Error.
1688
+ */
1549
1689
  readonly extends?: ErrorBaseConstructor<Base>;
1550
1690
  /**
1551
- * Message template. `$prop` placeholders are filled from constructor props.
1552
- */
1691
+ * Message template. `$prop` placeholders are filled from constructor props.
1692
+ */
1553
1693
  readonly message?: MessageTemplate;
1554
1694
  /**
1555
- * Stable runtime tag and Error name.
1556
- */
1695
+ * Stable runtime tag and Error name.
1696
+ */
1557
1697
  readonly name: Tag;
1558
1698
  }
1559
1699
  /**
1560
- * Instance type produced by `createTaggedError`.
1561
- */
1700
+ * Instance type produced by `createTaggedError`.
1701
+ */
1562
1702
  type TaggedErrorInstance<Tag extends string, MessageTemplate extends string, Base extends Error = Error> = Base & Readonly<TemplateProps<MessageTemplate>> & {
1563
1703
  /**
1564
- * Stable runtime tag.
1565
- */
1704
+ * Stable runtime tag.
1705
+ */
1566
1706
  readonly _tag: Tag;
1567
1707
  /**
1568
- * Stable identity for grouping errors by tag and message template.
1569
- */
1708
+ * Stable identity for grouping errors by tag and message template.
1709
+ */
1570
1710
  readonly fingerprint: readonly [Tag, MessageTemplate];
1571
1711
  /**
1572
- * Original message template before interpolation.
1573
- */
1712
+ * Original message template before interpolation.
1713
+ */
1574
1714
  readonly messageTemplate: MessageTemplate;
1575
1715
  /**
1576
- * Finds a matching cause in the error cause chain.
1577
- */
1716
+ * Finds a matching cause in the error cause chain.
1717
+ */
1578
1718
  findCause: <T extends Error>(ErrorClass: ErrorClass<T>) => T | undefined;
1579
1719
  /**
1580
- * Serializes the tagged error, metadata, and cause chain.
1581
- */
1720
+ * Serializes the tagged error, metadata, and cause chain.
1721
+ */
1582
1722
  toJSON: () => object;
1583
1723
  };
1584
1724
  /**
1585
- * Class type returned by `createTaggedError`.
1586
- */
1725
+ * Class type returned by `createTaggedError`.
1726
+ */
1587
1727
  type TaggedErrorClass<Tag extends string, MessageTemplate extends string, Base extends Error = Error> = {
1588
1728
  new (...args: TaggedErrorConstructorArgs<MessageTemplate>): TaggedErrorInstance<Tag, MessageTemplate, Base>;
1589
1729
  /**
1590
- * Stable runtime tag.
1591
- */
1730
+ * Stable runtime tag.
1731
+ */
1592
1732
  readonly tag: Tag;
1593
1733
  /**
1594
- * Creates an Err containing this tagged error.
1595
- */
1734
+ * Creates an Err containing this tagged error.
1735
+ */
1596
1736
  err: <This extends new (...args: TaggedErrorConstructorArgs<MessageTemplate>) => Error>(this: This, ...args: TaggedErrorConstructorArgs<MessageTemplate>) => ErrResult<never, ErrorClassInstance<This>>;
1597
1737
  /**
1598
- * Narrows a value to this tagged error class.
1599
- */
1738
+ * Narrows a value to this tagged error class.
1739
+ */
1600
1740
  is: (value: unknown) => value is TaggedErrorInstance<Tag, MessageTemplate, Base>;
1601
1741
  };
1602
1742
  /**
1603
- * Union of members produced by `taggedEnum`.
1604
- */
1743
+ * Union of members produced by `taggedEnum`.
1744
+ */
1605
1745
  type TaggedEnum<Members extends Record<string, object>> = { readonly [Tag in keyof Members]: Readonly<Members[Tag]> & {
1606
1746
  readonly _tag: Tag;
1607
- } }[keyof Members];
1747
+ }; }[keyof Members];
1608
1748
  type TaggedEnumMember<Members extends Record<string, object>, Tag extends keyof Members> = Readonly<Members[Tag]> & {
1609
1749
  readonly _tag: Tag;
1610
1750
  };
1611
1751
  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>;
1612
1752
  /**
1613
- * Factory returned by `taggedEnum`.
1614
- */
1615
- type TaggedEnumFactory<Members extends Record<string, object>> = { readonly [Tag in keyof Members]: TaggedEnumConstructor<Members, Tag> } & {
1753
+ * Factory returned by `taggedEnum`.
1754
+ */
1755
+ type TaggedEnumFactory<Members extends Record<string, object>> = { readonly [Tag in keyof Members]: TaggedEnumConstructor<Members, Tag>; } & {
1616
1756
  /**
1617
- * Narrows a value to a tagged enum member.
1618
- */
1757
+ * Narrows a value to a tagged enum member.
1758
+ */
1619
1759
  $is: <Tag extends keyof Members>(tag: Tag, value: unknown) => value is TaggedEnumMember<Members, Tag>;
1620
1760
  /**
1621
- * Exhaustively matches a tagged enum value.
1622
- */
1623
- $match: <ReturnType>(value: TaggedEnum<Members>, handlers: { readonly [Tag in keyof Members]: (value: TaggedEnumMember<Members, Tag>) => ReturnType }) => ReturnType;
1761
+ * Exhaustively matches a tagged enum value.
1762
+ */
1763
+ $match: <ReturnType>(value: TaggedEnum<Members>, handlers: { readonly [Tag in keyof Members]: (value: TaggedEnumMember<Members, Tag>) => ReturnType; }) => ReturnType;
1624
1764
  };
1625
1765
  type TaggedErrorLike = Error & {
1626
1766
  readonly _tag: string;
@@ -1630,7 +1770,7 @@ type ErrorForTag<ErrorType extends Error, Tag extends string> = Extract<ErrorTyp
1630
1770
  readonly _tag: Tag;
1631
1771
  }>;
1632
1772
  type UntaggedError<ErrorType extends Error> = Exclude<ErrorType, TaggedErrorLike>;
1633
- type MatchHandlers<ErrorType extends Error, ReturnType> = { readonly [Tag in TaggedErrorTags<ErrorType>]: (error: ErrorForTag<ErrorType, Tag>) => ReturnType } & ([UntaggedError<ErrorType>] extends [never] ? {
1773
+ type MatchHandlers<ErrorType extends Error, ReturnType> = { readonly [Tag in TaggedErrorTags<ErrorType>]: (error: ErrorForTag<ErrorType, Tag>) => ReturnType; } & ([UntaggedError<ErrorType>] extends [never] ? {
1634
1774
  readonly Error?: (error: Error) => ReturnType;
1635
1775
  } : {
1636
1776
  readonly Error: (error: UntaggedError<ErrorType>) => ReturnType;
@@ -1638,43 +1778,43 @@ type MatchHandlers<ErrorType extends Error, ReturnType> = { readonly [Tag in Tag
1638
1778
  type PartialMatchHandlers<ErrorType extends Error, ReturnType> = Partial<MatchHandlers<ErrorType, ReturnType>>;
1639
1779
  declare const defaultMessageTemplate = "$message";
1640
1780
  /**
1641
- * Narrows a value to native or platform-recognized Error.
1642
- */
1781
+ * Narrows a value to native or platform-recognized Error.
1782
+ */
1643
1783
  declare function isError(value: unknown): value is Error;
1644
1784
  declare function isError<Value>(value: Value): value is Extract<Value, Error>;
1645
1785
  /**
1646
- * Finds the first cause in an Error cause chain that is an instance of `ErrorClass`.
1647
- */
1786
+ * Finds the first cause in an Error cause chain that is an instance of `ErrorClass`.
1787
+ */
1648
1788
  declare const findCause: <T extends Error>(error: Error, ErrorClass: ErrorClass<T>) => T | undefined;
1649
1789
  /**
1650
- * Creates an Error class with a stable `_tag`, typed template props, cause support, and JSON output.
1651
- *
1652
- * Prefer tagged errors for domain failures that travel through Resultar error channels.
1653
- *
1654
- * @example
1655
- * ```ts
1656
- * class UserNotFoundError extends createTaggedError({
1657
- * name: "UserNotFoundError",
1658
- * message: "User $id was not found",
1659
- * }) {}
1660
- * ```
1661
- */
1790
+ * Creates an Error class with a stable `_tag`, typed template props, cause support, and JSON output.
1791
+ *
1792
+ * Prefer tagged errors for domain failures that travel through Resultar error channels.
1793
+ *
1794
+ * @example
1795
+ * ```ts
1796
+ * class UserNotFoundError extends createTaggedError({
1797
+ * name: "UserNotFoundError",
1798
+ * message: "User $id was not found",
1799
+ * }) {}
1800
+ * ```
1801
+ */
1662
1802
  declare function createTaggedError<const Tag extends string, const MessageTemplate extends string = typeof defaultMessageTemplate, Base extends Error = Error>(options: Omit<TaggedErrorOptions<Tag, MessageTemplate, Base>, "message"> & {
1663
1803
  readonly message?: RejectReservedTemplateVariables<MessageTemplate>;
1664
1804
  }): TaggedErrorClass<Tag, MessageTemplate, Base>;
1665
1805
  /**
1666
- * Creates a small tagged-union factory with member constructors, `$is`, and `$match`.
1667
- */
1806
+ * Creates a small tagged-union factory with member constructors, `$is`, and `$match`.
1807
+ */
1668
1808
  declare const taggedEnum: <Members extends Record<string, object>>() => TaggedEnumFactory<Members>;
1669
1809
  /**
1670
- * Matches an Error by tagged `_tag`, with optional native `Error` fallback.
1671
- *
1672
- * Throws the original error when no handler matches.
1673
- */
1810
+ * Matches an Error by tagged `_tag`, with optional native `Error` fallback.
1811
+ *
1812
+ * Throws the original error when no handler matches.
1813
+ */
1674
1814
  declare const matchError: <ErrorType extends Error, ReturnType>(error: ErrorType, handlers: MatchHandlers<ErrorType, ReturnType>) => ReturnType;
1675
1815
  /**
1676
- * Matches an Error by tagged `_tag`, then native `Error`, then the provided fallback.
1677
- */
1816
+ * Matches an Error by tagged `_tag`, then native `Error`, then the provided fallback.
1817
+ */
1678
1818
  declare const matchErrorPartial: <ErrorType extends Error, ReturnType>(error: ErrorType, handlers: PartialMatchHandlers<ErrorType, ReturnType>, fallback: (error: ErrorType) => ReturnType) => ReturnType;
1679
1819
  //#endregion
1680
- export { AbortError, DisposableResult, DisposableResultAsync, type ErrResult, type OkResult, type Redacted, Result, ResultAsync, type ResultAsyncAbortSignal, type ResultAsyncCallbackCleanup, type ResultAsyncCallbackContext, type ResultAsyncConcurrency, type ResultAsyncFromCallbackOptions, 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, fromCallback, 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 };
1820
+ export { AbortError, type Cause, DisposableResult, DisposableResultAsync, type ErrResult, type Exit, type OkResult, type Redacted, Result, ResultAsync, type ResultAsyncAbortSignal, type ResultAsyncCallbackCleanup, type ResultAsyncCallbackContext, type ResultAsyncConcurrency, type ResultAsyncFromCallbackOptions, 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, ResultTask, type ResultTaskRunOptions, type ResultTaskServices, type ResultTaskTryOptions, type ResultTaskTryPromiseOptions, type SafeTryAsyncOptions, type SafeTryOptions, type ServiceTag, 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, fromCallback, 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 };