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.
- package/README.md +149 -18
- package/dist/index.d.ts +900 -760
- package/dist/index.js +286 -7
- 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
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
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]
|
|
87
|
-
type CombineResultsRecordWithAllErrors<T extends ResultRecord> = Result<{ readonly [Key in keyof T]: InferOkTypes<T[Key]
|
|
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
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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
|
-
|
|
167
|
-
|
|
168
|
-
|
|
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
|
-
|
|
173
|
-
|
|
174
|
-
|
|
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
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
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
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
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
|
-
|
|
198
|
-
|
|
198
|
+
* Narrows this result to the Ok variant.
|
|
199
|
+
*/
|
|
199
200
|
isOk: () => this is OkResult<T, E>;
|
|
200
201
|
/**
|
|
201
|
-
|
|
202
|
-
|
|
202
|
+
* Narrows this result to the Err variant.
|
|
203
|
+
*/
|
|
203
204
|
isErr: () => this is ErrResult<T, E>;
|
|
204
205
|
/**
|
|
205
|
-
|
|
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
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
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
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
243
|
-
|
|
244
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
312
|
-
|
|
313
|
-
|
|
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
|
-
|
|
318
|
-
|
|
319
|
-
|
|
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
|
-
|
|
324
|
-
|
|
325
|
-
|
|
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
|
-
|
|
330
|
-
|
|
330
|
+
* Attaches a synchronous disposal finalizer to this Result.
|
|
331
|
+
*/
|
|
331
332
|
toDisposable: (f: ResultFinalizer<T, E>) => DisposableResult<T, E>;
|
|
332
333
|
/**
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
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
|
-
|
|
340
|
-
|
|
340
|
+
* Enables `yield* result` inside `safeTry` generators.
|
|
341
|
+
*/
|
|
341
342
|
[Symbol.iterator]: () => Generator<Result<never, E>, T>;
|
|
342
343
|
/**
|
|
343
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
373
|
-
|
|
374
|
-
|
|
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
|
-
|
|
381
|
-
|
|
382
|
-
|
|
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
|
-
|
|
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
|
-
|
|
393
|
-
|
|
394
|
-
|
|
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
|
-
|
|
399
|
-
|
|
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
|
-
|
|
406
|
-
|
|
412
|
+
* Runtime `instanceof Result` support for Ok and Err values.
|
|
413
|
+
*/
|
|
407
414
|
[Symbol.hasInstance]: (value: unknown) => boolean;
|
|
408
415
|
/**
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
427
|
-
|
|
437
|
+
* Creates an Ok result with `undefined`.
|
|
438
|
+
*/
|
|
428
439
|
unit: <E = never>(this: void) => Result<undefined, E>;
|
|
429
440
|
/**
|
|
430
|
-
|
|
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
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
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
|
-
|
|
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
|
-
|
|
460
|
-
|
|
461
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
501
|
-
|
|
502
|
-
|
|
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
|
-
|
|
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
|
-
|
|
519
|
-
|
|
520
|
-
|
|
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
|
-
|
|
537
|
-
|
|
548
|
+
* Wrapped Result value.
|
|
549
|
+
*/
|
|
538
550
|
readonly result: Result<T, E>;
|
|
539
551
|
/**
|
|
540
|
-
|
|
541
|
-
|
|
552
|
+
* Creates a disposable wrapper around a Result.
|
|
553
|
+
*/
|
|
542
554
|
constructor(result: Result<T, E>, finalizer: ResultFinalizer<T, E>);
|
|
543
555
|
/**
|
|
544
|
-
|
|
545
|
-
|
|
556
|
+
* Ok value when present, otherwise undefined cast to `T` for compatibility.
|
|
557
|
+
*/
|
|
546
558
|
get value(): T;
|
|
547
559
|
/**
|
|
548
|
-
|
|
549
|
-
|
|
560
|
+
* Err value when present, otherwise undefined cast to `E` for compatibility.
|
|
561
|
+
*/
|
|
550
562
|
get error(): E;
|
|
551
563
|
/**
|
|
552
|
-
|
|
553
|
-
|
|
564
|
+
* Delegates to the wrapped Result `_unsafeUnwrap`.
|
|
565
|
+
*/
|
|
554
566
|
_unsafeUnwrap(config?: ErrorConfig): T;
|
|
555
567
|
/**
|
|
556
|
-
|
|
557
|
-
|
|
568
|
+
* Delegates to the wrapped Result `_unsafeUnwrapErr`.
|
|
569
|
+
*/
|
|
558
570
|
_unsafeUnwrapErr(config?: ErrorConfig): E;
|
|
559
571
|
/**
|
|
560
|
-
|
|
561
|
-
|
|
572
|
+
* Returns whether the wrapped Result is Ok.
|
|
573
|
+
*/
|
|
562
574
|
isOk(): boolean;
|
|
563
575
|
/**
|
|
564
|
-
|
|
565
|
-
|
|
576
|
+
* Returns whether the wrapped Result is Err.
|
|
577
|
+
*/
|
|
566
578
|
isErr(): boolean;
|
|
567
579
|
/**
|
|
568
|
-
|
|
569
|
-
|
|
580
|
+
* Returns the wrapped Ok value, or `defaultValue` when Err.
|
|
581
|
+
*/
|
|
570
582
|
unwrapOr<A>(defaultValue: A): T | A;
|
|
571
583
|
/**
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
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
|
-
|
|
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
|
-
|
|
713
|
-
|
|
714
|
-
|
|
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
|
-
|
|
719
|
-
|
|
720
|
-
|
|
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
|
-
|
|
727
|
-
|
|
739
|
+
* Whether the cooperative async operation has been aborted.
|
|
740
|
+
*/
|
|
728
741
|
readonly aborted: boolean;
|
|
729
742
|
/**
|
|
730
|
-
|
|
731
|
-
|
|
743
|
+
* Optional abort cause provided by the losing race, timeout, or caller.
|
|
744
|
+
*/
|
|
732
745
|
readonly reason?: unknown;
|
|
733
746
|
/**
|
|
734
|
-
|
|
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
|
-
|
|
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
|
-
|
|
750
|
-
|
|
762
|
+
* Completes the operation with `Ok(value)`.
|
|
763
|
+
*/
|
|
751
764
|
readonly resolve: (value: T) => void;
|
|
752
765
|
/**
|
|
753
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
775
|
-
|
|
787
|
+
* Optional external signal that cancels the subscription with `AbortError`.
|
|
788
|
+
*/
|
|
776
789
|
readonly signal?: ResultAsyncAbortSignal;
|
|
777
790
|
/**
|
|
778
|
-
|
|
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]
|
|
797
|
-
type CombineResultAsyncsRecordWithAllErrors<T extends ResultAsyncRecord> = ResultAsync<{ readonly [Key in keyof T]: InferAsyncOkTypes<T[Key]
|
|
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
|
-
|
|
813
|
-
|
|
826
|
+
* Abort signal associated with the running task.
|
|
827
|
+
*/
|
|
814
828
|
readonly signal: ResultAsyncAbortSignal;
|
|
815
829
|
/**
|
|
816
|
-
|
|
817
|
-
|
|
830
|
+
* Aborts the running task with an optional reason.
|
|
831
|
+
*/
|
|
818
832
|
abort: (reason?: unknown) => void;
|
|
819
833
|
/**
|
|
820
|
-
|
|
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
|
-
|
|
830
|
-
|
|
843
|
+
* Creates the typed timeout error when the timeout wins.
|
|
844
|
+
*/
|
|
831
845
|
readonly onTimeout: () => E;
|
|
832
846
|
/**
|
|
833
|
-
|
|
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
|
-
|
|
843
|
-
|
|
856
|
+
* Current attempt number, starting at 0.
|
|
857
|
+
*/
|
|
844
858
|
readonly attempt: number;
|
|
845
859
|
/**
|
|
846
|
-
|
|
847
|
-
|
|
860
|
+
* Next attempt number if another retry is scheduled.
|
|
861
|
+
*/
|
|
848
862
|
readonly nextAttempt: number;
|
|
849
863
|
/**
|
|
850
|
-
|
|
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
|
-
|
|
864
|
-
|
|
878
|
+
* Delay in milliseconds before retrying. Functions receive retry context.
|
|
879
|
+
*/
|
|
865
880
|
readonly delayMs?: ResultAsyncRetryDelay;
|
|
866
881
|
/**
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
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
|
-
|
|
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
|
-
|
|
878
|
-
|
|
892
|
+
* Optional external abort signal for the retry loop.
|
|
893
|
+
*/
|
|
879
894
|
readonly signal?: ResultAsyncAbortSignal;
|
|
880
895
|
/**
|
|
881
|
-
|
|
882
|
-
|
|
896
|
+
* Maximum number of retries after the initial attempt.
|
|
897
|
+
*/
|
|
883
898
|
readonly times: number;
|
|
884
899
|
/**
|
|
885
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
933
|
-
|
|
947
|
+
* Acquires the resource.
|
|
948
|
+
*/
|
|
934
949
|
readonly acquire: ResultAsyncResourceAcquire<Resource, AcquireError>;
|
|
935
950
|
/**
|
|
936
|
-
|
|
937
|
-
|
|
951
|
+
* Releases the resource after use.
|
|
952
|
+
*/
|
|
938
953
|
readonly release: ResultAsyncResourceRelease<Resource>;
|
|
939
954
|
/**
|
|
940
|
-
|
|
941
|
-
|
|
955
|
+
* Optional external abort signal for the full lifecycle.
|
|
956
|
+
*/
|
|
942
957
|
readonly signal?: ResultAsyncAbortSignal;
|
|
943
958
|
/**
|
|
944
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1024
|
-
|
|
1025
|
-
|
|
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
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1072
|
-
|
|
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
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
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
|
-
|
|
1084
|
-
|
|
1085
|
-
|
|
1086
|
-
|
|
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
|
-
|
|
1092
|
-
|
|
1093
|
-
|
|
1094
|
-
|
|
1095
|
-
|
|
1096
|
-
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
|
|
1101
|
-
|
|
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
|
-
|
|
1107
|
-
|
|
1108
|
-
|
|
1109
|
-
|
|
1110
|
-
|
|
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
|
-
|
|
1115
|
-
|
|
1116
|
-
|
|
1117
|
-
|
|
1118
|
-
|
|
1119
|
-
|
|
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
|
-
|
|
1124
|
-
|
|
1125
|
-
|
|
1126
|
-
|
|
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
|
-
|
|
1131
|
-
|
|
1132
|
-
|
|
1133
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1148
|
-
|
|
1149
|
-
|
|
1150
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1161
|
-
|
|
1162
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1171
|
-
|
|
1172
|
-
|
|
1173
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1186
|
-
|
|
1187
|
-
|
|
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
|
-
|
|
1192
|
-
|
|
1193
|
-
|
|
1194
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1231
|
-
|
|
1232
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
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
|
-
|
|
1253
|
-
|
|
1254
|
-
|
|
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
|
-
|
|
1260
|
-
|
|
1261
|
-
|
|
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
|
-
|
|
1266
|
-
|
|
1267
|
-
|
|
1268
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1290
|
-
|
|
1291
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1345
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1354
|
-
|
|
1355
|
-
|
|
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
|
-
|
|
1360
|
-
|
|
1361
|
-
|
|
1362
|
-
|
|
1363
|
-
|
|
1364
|
-
|
|
1365
|
-
|
|
1366
|
-
|
|
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
|
-
|
|
1371
|
-
|
|
1372
|
-
|
|
1373
|
-
|
|
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
|
-
|
|
1378
|
-
|
|
1379
|
-
|
|
1380
|
-
|
|
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
|
-
|
|
1385
|
-
|
|
1400
|
+
* Attaches an async disposal finalizer to this ResultAsync.
|
|
1401
|
+
*/
|
|
1386
1402
|
toAsyncDisposable(f: ResultAsyncFinalizer<T, E>): DisposableResultAsync<T, E>;
|
|
1387
1403
|
/**
|
|
1388
|
-
|
|
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
|
-
|
|
1488
|
-
|
|
1504
|
+
* Internal marker used by `isRedacted`.
|
|
1505
|
+
*/
|
|
1489
1506
|
readonly __resultarRedacted: true;
|
|
1490
1507
|
readonly __resultarRedactedType?: T;
|
|
1491
1508
|
/**
|
|
1492
|
-
|
|
1493
|
-
|
|
1509
|
+
* Optional label shown as `<redacted:label>`.
|
|
1510
|
+
*/
|
|
1494
1511
|
readonly label: string | undefined;
|
|
1495
1512
|
/**
|
|
1496
|
-
|
|
1497
|
-
|
|
1513
|
+
* Serializes to the redacted placeholder.
|
|
1514
|
+
*/
|
|
1498
1515
|
toJSON: () => string;
|
|
1499
1516
|
/**
|
|
1500
|
-
|
|
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
|
-
|
|
1548
|
-
|
|
1687
|
+
* Optional base Error class to extend instead of native Error.
|
|
1688
|
+
*/
|
|
1549
1689
|
readonly extends?: ErrorBaseConstructor<Base>;
|
|
1550
1690
|
/**
|
|
1551
|
-
|
|
1552
|
-
|
|
1691
|
+
* Message template. `$prop` placeholders are filled from constructor props.
|
|
1692
|
+
*/
|
|
1553
1693
|
readonly message?: MessageTemplate;
|
|
1554
1694
|
/**
|
|
1555
|
-
|
|
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
|
-
|
|
1565
|
-
|
|
1704
|
+
* Stable runtime tag.
|
|
1705
|
+
*/
|
|
1566
1706
|
readonly _tag: Tag;
|
|
1567
1707
|
/**
|
|
1568
|
-
|
|
1569
|
-
|
|
1708
|
+
* Stable identity for grouping errors by tag and message template.
|
|
1709
|
+
*/
|
|
1570
1710
|
readonly fingerprint: readonly [Tag, MessageTemplate];
|
|
1571
1711
|
/**
|
|
1572
|
-
|
|
1573
|
-
|
|
1712
|
+
* Original message template before interpolation.
|
|
1713
|
+
*/
|
|
1574
1714
|
readonly messageTemplate: MessageTemplate;
|
|
1575
1715
|
/**
|
|
1576
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1591
|
-
|
|
1730
|
+
* Stable runtime tag.
|
|
1731
|
+
*/
|
|
1592
1732
|
readonly tag: Tag;
|
|
1593
1733
|
/**
|
|
1594
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 };
|