@noego/trust 0.5.1 → 0.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 +155 -0
- package/dist/{baseline-D0Ok-NGU.d.ts → baseline-DsqHPLAg.d.ts} +27 -2
- package/dist/{chunk-RVTPDLEW.js → chunk-4XGOH7JE.js} +3491 -3456
- package/dist/chunk-4XGOH7JE.js.map +1 -0
- package/dist/{chunk-V4FYZG5Q.js → chunk-6K5I3ZRI.js} +2 -2
- package/dist/{chunk-P4VFMA2A.js → chunk-QTS55J43.js} +2174 -71
- package/dist/chunk-QTS55J43.js.map +1 -0
- package/dist/cli/index.js +208 -88
- package/dist/cli/index.js.map +1 -1
- package/dist/core/index.d.ts +2 -2
- package/dist/core/index.js +2 -2
- package/dist/eslint/index.d.ts +6 -2
- package/dist/eslint/index.js +84 -12
- package/dist/eslint/index.js.map +1 -1
- package/dist/index.cjs +1223 -10
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +236 -6
- package/dist/index.d.ts +236 -6
- package/dist/index.js +1212 -6
- package/dist/index.js.map +1 -1
- package/dist/native/trust_native_wasm.wasm +0 -0
- package/package.json +4 -4
- package/dist/chunk-P4VFMA2A.js.map +0 -1
- package/dist/chunk-RVTPDLEW.js.map +0 -1
- /package/dist/{chunk-V4FYZG5Q.js.map → chunk-6K5I3ZRI.js.map} +0 -0
package/dist/index.d.ts
CHANGED
|
@@ -9,6 +9,8 @@
|
|
|
9
9
|
* Result.ok / Result.err — make a result
|
|
10
10
|
* Trust.try / Trust.tryAsync — the only boundary that may catch a throw
|
|
11
11
|
* Trust.decide / Trust.translate — the only places a failure may stop or change
|
|
12
|
+
* Trust.retry — kind-selective retry preserving failure context
|
|
13
|
+
* Trust.using / Trust.usingAsync — acquire, use and always release a Result resource
|
|
12
14
|
*
|
|
13
15
|
* The underlying functions are exported as well because the `@noego/trust/eslint`
|
|
14
16
|
* rules recognise calls by their declaration (not by name): `Trust.try(...)` resolves
|
|
@@ -22,6 +24,24 @@ type Err<E> = {
|
|
|
22
24
|
readonly ok: false;
|
|
23
25
|
readonly error: E;
|
|
24
26
|
};
|
|
27
|
+
type StatedOk<T, S extends string> = {
|
|
28
|
+
[K in S]: {
|
|
29
|
+
readonly ok: true;
|
|
30
|
+
readonly state: K;
|
|
31
|
+
readonly value: T;
|
|
32
|
+
};
|
|
33
|
+
}[S];
|
|
34
|
+
type StatedResult<T, E, S extends string> = StatedOk<T, S> | Err<E>;
|
|
35
|
+
type LiteralState<S extends string> = string extends S ? never : S;
|
|
36
|
+
type Stateless<R> = Extract<R, {
|
|
37
|
+
readonly state: unknown;
|
|
38
|
+
}> extends never ? R : never;
|
|
39
|
+
type NotResult<T> = unknown extends T ? never : Extract<T, Ok<unknown> | Err<unknown>> extends never ? T : never;
|
|
40
|
+
declare function state<const S extends string>(state: LiteralState<S>): StatedOk<void, S>;
|
|
41
|
+
declare function state<const S extends string, R extends Result<unknown, unknown>>(state: LiteralState<S>, result: R & Stateless<R> & (0 extends (1 & R) ? never : unknown)): StatedOk<OkOf<R>, S> | Extract<R, {
|
|
42
|
+
readonly ok: false;
|
|
43
|
+
}>;
|
|
44
|
+
declare function state<const S extends string, T>(state: LiteralState<S>, value: T, ...check: [T] extends [NotResult<T>] ? unknown extends T ? [problem: never] : [] : [problem: never]): StatedOk<T, S>;
|
|
25
45
|
/** A failure is an object with a literal `kind` plus any fields. */
|
|
26
46
|
type Failure<K extends string = string, Fields extends object = {}> = {
|
|
27
47
|
readonly kind: K;
|
|
@@ -116,32 +136,242 @@ type KindCheck<M> = [
|
|
|
116
136
|
type Remaining<E, H> = Exclude<E, {
|
|
117
137
|
readonly kind: keyof H & string;
|
|
118
138
|
}>;
|
|
119
|
-
type
|
|
120
|
-
|
|
139
|
+
type StatedMembersOf<R> = Extract<R, {
|
|
140
|
+
readonly ok: true;
|
|
141
|
+
readonly state: string;
|
|
142
|
+
}>;
|
|
143
|
+
type HasStates<R> = [StatedMembersOf<R>] extends [never] ? false : true;
|
|
144
|
+
type StateGuard<R> = HasStates<R> extends true ? Exclude<Extract<R, Ok<unknown>>, StatedMembersOf<R>> extends never ? unknown : {
|
|
145
|
+
readonly __trust: 'mixed stated and stateless successes are not supported';
|
|
146
|
+
} : unknown;
|
|
147
|
+
type SuccessOf<R, H> = HasStates<R> extends true ? StatedMembersOf<R> | H[keyof H] : Ok<OkOf<R> | H[keyof H]>;
|
|
148
|
+
type RecoveryCheck<R, H> = {
|
|
149
|
+
[K in keyof H]: HasStates<R> extends true ? H[K] extends StatedOk<unknown, infer S extends string> ? string extends S ? 1 : never : 1 : Extract<H[K], {
|
|
150
|
+
readonly state: unknown;
|
|
151
|
+
}> extends never ? never : 1;
|
|
152
|
+
}[keyof H] extends never ? [] : [problem: {
|
|
153
|
+
readonly __trust: 'recovery must preserve the success state discipline';
|
|
154
|
+
}];
|
|
155
|
+
type Decided<R, H> = [Remaining<ErrorOf<R>, H>] extends [never] ? SuccessOf<R, H> : SuccessOf<R, H> | Err<Remaining<ErrorOf<R>, H>>;
|
|
156
|
+
type Translated<R, M> = (HasStates<R> extends true ? StatedMembersOf<R> : Ok<OkOf<R>>) | Err<M[keyof M] | Remaining<ErrorOf<R>, M>>;
|
|
121
157
|
/**
|
|
122
158
|
* The only place a failure may stop: a failure whose kind has a handler becomes
|
|
123
159
|
* `ok(handler(failure))`; anything else is returned untouched. Handlers are synchronous
|
|
124
160
|
* and must return a value (never `undefined`/`void`).
|
|
125
161
|
*/
|
|
126
|
-
declare function decide<R extends Result<unknown, unknown>, H extends HandlerBase<ErrorOf<R>, H>>(result: R & FailureGuard<R>, handlers: HandlerFns<ErrorOf<R>, H>): Decided<R, H>;
|
|
162
|
+
declare function decide<R extends Result<unknown, unknown>, H extends HandlerBase<ErrorOf<R>, H>>(result: R & FailureGuard<R> & StateGuard<R>, handlers: HandlerFns<ErrorOf<R>, H>, ...check: RecoveryCheck<R, H>): Decided<R, H>;
|
|
127
163
|
/** Turns failures into different failures; unmapped failures and successes pass through untouched. */
|
|
128
|
-
declare function translate<R extends Result<unknown, unknown>, M extends MapperBase<ErrorOf<R>, M>>(result: R & FailureGuard<R>, mappers: MapperFns<ErrorOf<R>, M>, ...check: KindCheck<M>): Translated<R, M>;
|
|
164
|
+
declare function translate<R extends Result<unknown, unknown>, M extends MapperBase<ErrorOf<R>, M>>(result: R & FailureGuard<R> & StateGuard<R>, mappers: MapperFns<ErrorOf<R>, M>, ...check: KindCheck<M>): Translated<R, M>;
|
|
165
|
+
type MatchGuard<R> = [RawErrorOf<R>] extends [never] ? HasStates<R> extends true ? StateGuard<R> : {
|
|
166
|
+
readonly __trust: 'match needs stated successes';
|
|
167
|
+
} : {
|
|
168
|
+
readonly __trust: 'match requires all failures to be handled first';
|
|
169
|
+
};
|
|
170
|
+
type StatesOf<R> = StatedMembersOf<R>['state'];
|
|
171
|
+
type MatchFns<R, H> = {
|
|
172
|
+
[K in keyof H]-?: (value: OkOf<Extract<R, {
|
|
173
|
+
readonly state: K;
|
|
174
|
+
}>>) => H[K];
|
|
175
|
+
};
|
|
176
|
+
type MatchBase<R, H> = {
|
|
177
|
+
[K in StatesOf<R>]: {} | null;
|
|
178
|
+
} & {
|
|
179
|
+
[K in keyof H]: K extends StatesOf<R> ? {} | null : never;
|
|
180
|
+
};
|
|
181
|
+
type Matched<H> = [H[keyof H]] extends [StatedOk<unknown, string>] ? H[keyof H] : Ok<H[keyof H]>;
|
|
182
|
+
type MatchCheck<H> = [Extract<H[keyof H], {
|
|
183
|
+
readonly state: unknown;
|
|
184
|
+
}>] extends [never] ? [] : [H[keyof H]] extends [StatedOk<unknown, infer S extends string>] ? string extends S ? [problem: {
|
|
185
|
+
readonly __trust: 'match needs literal output states';
|
|
186
|
+
}] : [] : [problem: {
|
|
187
|
+
readonly __trust: 'match cannot mix stated and bare returns';
|
|
188
|
+
}];
|
|
189
|
+
declare function match<R extends Result<unknown, unknown>, H extends MatchBase<R, H>>(result: R & MatchGuard<R>, handlers: MatchFns<R, H>, ...check: MatchCheck<H>): Matched<H>;
|
|
190
|
+
type RetryDelay = number | false | null | undefined;
|
|
191
|
+
type HasWideKind<E> = E extends {
|
|
192
|
+
readonly kind: infer K extends string;
|
|
193
|
+
} ? string extends K ? true : never : never;
|
|
194
|
+
type MatchingFailure<E, K> = E extends {
|
|
195
|
+
readonly kind: infer EK extends string;
|
|
196
|
+
} ? EK extends K ? E : K extends EK ? E & {
|
|
197
|
+
readonly kind: K;
|
|
198
|
+
} : [EK & K] extends [never] ? never : E & {
|
|
199
|
+
readonly kind: EK & K;
|
|
200
|
+
} : never;
|
|
201
|
+
type RetryGuard<R> = [RawErrorOf<R>] extends [never] ? {
|
|
202
|
+
readonly __trust: 'retry needs a result that can fail (it has no Err member)';
|
|
203
|
+
} : [RawErrorOf<R>] extends [{
|
|
204
|
+
readonly kind: string;
|
|
205
|
+
}] ? [HasWideKind<RawErrorOf<R>>] extends [never] ? StateGuard<R> : {
|
|
206
|
+
readonly __trust: 'every failure needs a literal string `kind` (`kind: string` is too wide)';
|
|
207
|
+
} : {
|
|
208
|
+
readonly __trust: 'every failure needs a string `kind` (string and Error are not failures)';
|
|
209
|
+
};
|
|
210
|
+
type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
|
|
211
|
+
type ToDigits<S extends string, Acc extends Digit[] = []> = S extends `${infer C}${infer Rest}` ? C extends Digit ? ToDigits<Rest, [...Acc, C]> : never : Acc;
|
|
212
|
+
type MaxSafeDigits = ['9', '0', '0', '7', '1', '9', '9', '2', '5', '4', '7', '4', '0', '9', '9', '1'];
|
|
213
|
+
type DigitsLeq<A extends Digit[], B extends Digit[]> = A extends [infer AH extends Digit, ...infer AT extends Digit[]] ? B extends [infer BH extends Digit, ...infer BT extends Digit[]] ? AH extends BH ? DigitsLeq<AT, BT> : '0123456789' extends `${string}${AH}${string}${BH}${string}` ? true : false : false : true;
|
|
214
|
+
type IsValidRetryTimesMember<N extends number> = 0 extends N ? false : [ToDigits<`${N}`>] extends [never] ? false : ToDigits<`${N}`> extends infer DS extends Digit[] ? DS['length'] extends 0 ? false : '0123456789abcdef' extends `${string}${DS['length'] extends 10 ? 'a' : DS['length'] extends 11 ? 'b' : DS['length'] extends 12 ? 'c' : DS['length'] extends 13 ? 'd' : DS['length'] extends 14 ? 'e' : DS['length'] extends 15 ? 'f' : DS['length']}${string}` ? true : DS['length'] extends 16 ? DigitsLeq<DS, MaxSafeDigits> : false : false;
|
|
215
|
+
type CheckRetryTimesMember<N extends number> = N extends unknown ? IsValidRetryTimesMember<N> : never;
|
|
216
|
+
type RetryTimes<N extends number> = number extends N ? number : [Extract<CheckRetryTimesMember<N>, false>] extends [never] ? number : {
|
|
217
|
+
readonly __trust: 'retry `times` must be a safe integer >= 1';
|
|
218
|
+
};
|
|
219
|
+
declare const hostAbortSignalBrand: unique symbol;
|
|
220
|
+
type AmbientAbortSignal = typeof globalThis extends {
|
|
221
|
+
readonly AbortSignal: {
|
|
222
|
+
readonly prototype: infer S;
|
|
223
|
+
};
|
|
224
|
+
} ? S : {
|
|
225
|
+
readonly [hostAbortSignalBrand]: true;
|
|
226
|
+
readonly aborted: boolean;
|
|
227
|
+
readonly reason: unknown;
|
|
228
|
+
throwIfAborted(): void;
|
|
229
|
+
addEventListener(type: 'abort', listener: () => void, options?: boolean | {
|
|
230
|
+
readonly once?: boolean;
|
|
231
|
+
}): void;
|
|
232
|
+
removeEventListener(type: 'abort', listener: () => void, options?: boolean | {
|
|
233
|
+
readonly capture?: boolean;
|
|
234
|
+
}): void;
|
|
235
|
+
};
|
|
236
|
+
type RetryShape<H, N extends number> = {
|
|
237
|
+
readonly times: N & RetryTimes<N>;
|
|
238
|
+
readonly on: {
|
|
239
|
+
readonly [K in keyof H]-?: (...args: never[]) => H[K];
|
|
240
|
+
};
|
|
241
|
+
readonly signal?: AmbientAbortSignal;
|
|
242
|
+
readonly timeoutMs?: number;
|
|
243
|
+
};
|
|
244
|
+
type HandlerKeyToKind<K> = K extends string ? K : K extends number ? `${K}` : never;
|
|
245
|
+
type RetryContext<E, H> = {
|
|
246
|
+
readonly on: ([HasWideKind<E>] extends [never] ? {
|
|
247
|
+
readonly [K in Exclude<KindsOf<E>, keyof Object>]?: (failure: MatchingFailure<E, K>, attempt: number) => RetryDelay;
|
|
248
|
+
} : unknown) & {
|
|
249
|
+
readonly [K in keyof H]-?: [E] extends [never] ? (failure: never, attempt: number) => RetryDelay : [HasWideKind<E>] extends [never] ? [HandlerKeyToKind<K>] extends [never] ? ((failure: never, attempt: number) => RetryDelay) & {
|
|
250
|
+
readonly __trust: 'retry `on` handler names an unknown failure `kind`';
|
|
251
|
+
} : HandlerKeyToKind<K> extends KindsOf<E> ? (failure: MatchingFailure<E, HandlerKeyToKind<K>>, attempt: number) => RetryDelay : ((failure: never, attempt: number) => RetryDelay) & {
|
|
252
|
+
readonly __trust: 'retry `on` handler names an unknown failure `kind`';
|
|
253
|
+
} : (failure: never, attempt: number) => RetryDelay;
|
|
254
|
+
};
|
|
255
|
+
};
|
|
256
|
+
declare const retryPending: unique symbol;
|
|
257
|
+
type RetryPending = {
|
|
258
|
+
readonly [retryPending]: true;
|
|
259
|
+
};
|
|
260
|
+
type RetryResultOf<T> = Awaited<Exclude<T, RetryPending>>;
|
|
261
|
+
type RetryDeferred<T, H> = [Extract<T, RetryPending>] extends [never] ? RetryContext<ErrorOf<RetryResultOf<T>>, H> & RetryGuard<RetryResultOf<T>> : unknown;
|
|
262
|
+
/**
|
|
263
|
+
* Retries a `Result`-returning operation up to `options.times` total attempts,
|
|
264
|
+
* sleeping only for failure `kind`s explicitly listed in `options.on` and returning
|
|
265
|
+
* the exact `Result` of the last attempt untouched when stopping.
|
|
266
|
+
*
|
|
267
|
+
* Cancellation (`options.signal`) and per-attempt `options.timeoutMs` are cooperative:
|
|
268
|
+
* they abort the `signal` passed to `fn`, and `retry` still awaits `fn`'s returned
|
|
269
|
+
* `Result` (or rejection) before inspecting the outcome or starting another attempt.
|
|
270
|
+
* If `fn` ignores an aborted `signal` and never settles, `retry` will remain pending.
|
|
271
|
+
*/
|
|
272
|
+
declare function retry<T extends Result<unknown, unknown> | PromiseLike<Result<unknown, unknown>> | RetryPending, H extends Record<keyof H, RetryDelay>, N extends number = number>(fn: (attempt: number, signal: AmbientAbortSignal) => T, options: RetryShape<H, N> & RetryDeferred<T, H>): Promise<RetryResultOf<T>>;
|
|
273
|
+
interface AllOptions {
|
|
274
|
+
readonly signal?: AmbientAbortSignal | undefined;
|
|
275
|
+
}
|
|
276
|
+
interface MapOptions {
|
|
277
|
+
readonly concurrency: number;
|
|
278
|
+
readonly signal?: AmbientAbortSignal | undefined;
|
|
279
|
+
}
|
|
280
|
+
type MaybePromise<T> = T | PromiseLike<T>;
|
|
281
|
+
type ResultTask = MaybePromise<Result<unknown, unknown>>;
|
|
282
|
+
type AllList = readonly ResultTask[] | [];
|
|
283
|
+
type PositionalValues<T extends readonly unknown[]> = {
|
|
284
|
+
-readonly [K in keyof T]: OkOf<Awaited<T[K]>>;
|
|
285
|
+
};
|
|
286
|
+
type AllValues<T extends readonly unknown[]> = number extends T['length'] ? Exclude<keyof T, keyof any[] | `${number}`> extends never ? PositionalValues<T> : OkOf<Awaited<T[number]>>[] : PositionalValues<[...T]>;
|
|
287
|
+
type AllErrors<T extends readonly unknown[]> = RawErrorOf<Awaited<T[number]>>;
|
|
288
|
+
type AllResult<T extends readonly unknown[]> = [AllErrors<T>] extends [never] ? Ok<AllValues<T>> : Result<AllValues<T>, AllErrors<T>>;
|
|
289
|
+
type HasStatedMember<R> = 0 extends (1 & R) ? false : [StatedMembersOf<R>] extends [never] ? false : true;
|
|
290
|
+
type AllCheck<T extends readonly unknown[]> = HasStatedMember<Awaited<T[number]>> extends true ? [problem: {
|
|
291
|
+
readonly __trust: 'Trust.all cannot unwrap stated results; match states first';
|
|
292
|
+
}] : [];
|
|
293
|
+
type MappedResult<R> = [RawErrorOf<R>] extends [never] ? Ok<OkOf<R>[]> : Result<OkOf<R>[], RawErrorOf<R>>;
|
|
294
|
+
type MapCheck<R> = HasStatedMember<R> extends true ? [problem: {
|
|
295
|
+
readonly __trust: 'Trust.map cannot unwrap stated results; match states first';
|
|
296
|
+
}] : [];
|
|
297
|
+
/**
|
|
298
|
+
* Runs a tuple or array of `Result` tasks in parallel and short-circuits on the first `Err`,
|
|
299
|
+
* aborting the internal `AbortSignal` (and chaining an optional parent `options.signal`).
|
|
300
|
+
*/
|
|
301
|
+
declare function all<T extends AllList>(tasks: (signal: AmbientAbortSignal) => T, ...check: AllCheck<T>): Promise<AllResult<T>>;
|
|
302
|
+
declare function all<T extends AllList>(tasks: (signal: AmbientAbortSignal) => T, options: AllOptions | undefined, ...check: AllCheck<T>): Promise<AllResult<T>>;
|
|
303
|
+
declare function all<T extends AllList>(tasks: T, ...check: AllCheck<T>): Promise<AllResult<T>>;
|
|
304
|
+
declare function all<T extends AllList>(tasks: T, options: AllOptions | undefined, ...check: AllCheck<T>): Promise<AllResult<T>>;
|
|
305
|
+
/**
|
|
306
|
+
* Maps `items` with at most `options.concurrency` active callbacks at once (`concurrency` must be a finite integer >= 1).
|
|
307
|
+
* On the first `Err`, stops scheduling remaining items, aborts `signal`, and resolves to that `Err`.
|
|
308
|
+
*/
|
|
309
|
+
declare function map<T, Out extends ResultTask>(items: Iterable<T>, options: MapOptions, fn: (item: T, signal: AmbientAbortSignal, index: number) => Out, ...check: MapCheck<Awaited<Out>>): Promise<MappedResult<Awaited<Out>>>;
|
|
310
|
+
type ResourceOf<A> = OkOf<Awaited<A>>;
|
|
311
|
+
type SyncOf<T> = Exclude<T, PromiseLike<unknown>>;
|
|
312
|
+
type AsyncOf<T> = Extract<T, PromiseLike<unknown>>;
|
|
313
|
+
type HasType<T> = [T] extends [never] ? false : true;
|
|
314
|
+
type HasOk<R> = [Extract<R, Ok<unknown>>] extends [never] ? false : true;
|
|
315
|
+
type ErrUnion<E> = [E] extends [never] ? never : Err<E>;
|
|
316
|
+
type UsingSuccess<U> = HasOk<U> extends false ? never : HasStates<U> extends true ? StatedMembersOf<U> : Ok<OkOf<U>>;
|
|
317
|
+
type UsingResult<A, U, C> = HasOk<A> extends false ? ErrUnion<RawErrorOf<A>> : HasOk<U> extends false ? ErrUnion<RawErrorOf<A> | RawErrorOf<U>> : HasOk<C> extends false ? ErrUnion<RawErrorOf<A> | RawErrorOf<U> | RawErrorOf<C>> : UsingSuccess<U> | ErrUnion<RawErrorOf<A> | RawErrorOf<U> | RawErrorOf<C>>;
|
|
318
|
+
type SyncAcquireOk<A> = Extract<SyncOf<A>, Ok<unknown>>;
|
|
319
|
+
type SyncAcquireErr<A> = ErrUnion<RawErrorOf<SyncOf<A>>>;
|
|
320
|
+
type UsingSyncOut<A, U, C> = HasType<SyncAcquireOk<A>> extends true ? HasType<SyncOf<U>> extends true ? HasType<SyncOf<C>> extends true ? UsingResult<SyncOf<A>, SyncOf<U>, SyncOf<C>> : SyncAcquireErr<A> : SyncAcquireErr<A> : SyncAcquireErr<A>;
|
|
321
|
+
type UsingAsyncOut<A, U, C> = HasType<AsyncOf<A>> extends true ? Promise<UsingResult<Awaited<A>, Awaited<U>, Awaited<C>>> : HasType<SyncAcquireOk<A>> extends true ? HasType<AsyncOf<U> | AsyncOf<C>> extends true ? Promise<UsingResult<Awaited<A>, Awaited<U>, Awaited<C>>> : never : never;
|
|
322
|
+
type UsingOut<A, U, C> = HasType<AsyncOf<A | U | C>> extends false ? UsingResult<A, U, C> : UsingSyncOut<A, U, C> | UsingAsyncOut<A, U, C>;
|
|
323
|
+
type UsingCheck<A, U, C> = HasStates<A> extends true ? [problem: {
|
|
324
|
+
readonly __trust: 'acquire must return a stateless Result';
|
|
325
|
+
}] : HasStates<C> extends true ? [problem: {
|
|
326
|
+
readonly __trust: 'release must return a stateless Result';
|
|
327
|
+
}] : HasStates<U> extends true ? Exclude<Extract<U, Ok<unknown>>, StatedMembersOf<U>> extends never ? [] : [problem: {
|
|
328
|
+
readonly __trust: 'mixed stated and stateless successes are not supported';
|
|
329
|
+
}] : [];
|
|
330
|
+
type UsingNoInfer<T> = [T][T extends unknown ? 0 : never];
|
|
331
|
+
/**
|
|
332
|
+
* Acquires a resource, runs `use(resource)`, and always runs `release(resource)` once acquired.
|
|
333
|
+
* Preserves `use`'s `Err` when both `use` and `release` return `Err`, returns `release`'s `Err` when
|
|
334
|
+
* `use` succeeded and `release` returned `Err`, and preserves `StatedOk` states from `use`.
|
|
335
|
+
*
|
|
336
|
+
* Unexpected throws or rejections are never converted into `Result`s (only `Trust.try` / `Trust.tryAsync`
|
|
337
|
+
* catch throws): if both `use` and `release` throw/reject, `use`'s exception propagates with `release`'s
|
|
338
|
+
* exception retained on `suppressed`; if `use` returned `Err` and `release` throws/rejects unexpectedly,
|
|
339
|
+
* `release`'s exception propagates with `use`'s `Err` retained on `primaryResult` / `primaryError`.
|
|
340
|
+
*
|
|
341
|
+
* When `acquire` can fail synchronously while `use` or `release` returns a `Promise`, an early
|
|
342
|
+
* `acquire` failure is returned synchronously (reflected in the return type); use `Trust.usingAsync`
|
|
343
|
+
* when you always want a `Promise`.
|
|
344
|
+
*/
|
|
345
|
+
declare function using<A extends MaybePromise<Result<unknown, unknown>>, U extends MaybePromise<Result<unknown, unknown>>, C extends MaybePromise<Result<unknown, unknown>>>(acquire: () => A, use: (resource: ResourceOf<A>) => U, release: (resource: ResourceOf<A>) => C, ...check: UsingCheck<Awaited<A>, Awaited<U>, Awaited<C>>): UsingOut<A, U, C>;
|
|
346
|
+
declare function using<A extends MaybePromise<Result<unknown, unknown>>, U extends MaybePromise<Result<unknown, unknown>>, C extends MaybePromise<Result<unknown, unknown>>>(acquire: () => A, use: (resource: ResourceOf<A>) => U, release: (resource: ResourceOf<A>) => C, onReleaseError: ((releaseError: UsingNoInfer<RawErrorOf<Awaited<C>>>, useError: UsingNoInfer<RawErrorOf<Awaited<U>>>) => void) | undefined, ...check: UsingCheck<Awaited<A>, Awaited<U>, Awaited<C>>): UsingOut<A, U, C>;
|
|
347
|
+
/** Async form of `Trust.using`: always returns a `Promise`. */
|
|
348
|
+
declare function usingAsync<A extends MaybePromise<Result<unknown, unknown>>, U extends MaybePromise<Result<unknown, unknown>>, C extends MaybePromise<Result<unknown, unknown>>>(acquire: () => A, use: (resource: ResourceOf<A>) => U, release: (resource: ResourceOf<A>) => C, ...check: UsingCheck<Awaited<A>, Awaited<U>, Awaited<C>>): Promise<UsingResult<Awaited<A>, Awaited<U>, Awaited<C>>>;
|
|
349
|
+
declare function usingAsync<A extends MaybePromise<Result<unknown, unknown>>, U extends MaybePromise<Result<unknown, unknown>>, C extends MaybePromise<Result<unknown, unknown>>>(acquire: () => A, use: (resource: ResourceOf<A>) => U, release: (resource: ResourceOf<A>) => C, onReleaseError: ((releaseError: UsingNoInfer<RawErrorOf<Awaited<C>>>, useError: UsingNoInfer<RawErrorOf<Awaited<U>>>) => void) | undefined, ...check: UsingCheck<Awaited<A>, Awaited<U>, Awaited<C>>): Promise<UsingResult<Awaited<A>, Awaited<U>, Awaited<C>>>;
|
|
129
350
|
type Result<T, E> = Ok<T> | Err<E>;
|
|
130
351
|
/** Make a result: `Result.ok(value)`, `Result.err({ kind: 'x', ... })`. */
|
|
131
352
|
declare const Result: {
|
|
132
353
|
readonly ok: typeof ok;
|
|
133
354
|
readonly err: typeof err;
|
|
355
|
+
readonly state: typeof state;
|
|
134
356
|
};
|
|
135
357
|
/**
|
|
136
358
|
* Apply the discipline:
|
|
137
359
|
* `Trust.try` / `Trust.tryAsync` are the only boundary that may catch a throw;
|
|
138
|
-
* `Trust.decide` is the only place a failure may stop; `Trust.translate` the only place it may change kind
|
|
360
|
+
* `Trust.decide` is the only place a failure may stop; `Trust.translate` the only place it may change kind;
|
|
361
|
+
* `Trust.retry` retries only named failure kinds and preserves the final failure intact.
|
|
362
|
+
* `Trust.using` / `Trust.usingAsync` acquire, use and always release a Result resource.
|
|
139
363
|
*/
|
|
140
364
|
declare const Trust: {
|
|
141
365
|
readonly try: typeof tryResult;
|
|
142
366
|
readonly tryAsync: typeof tryResultAsync;
|
|
143
367
|
readonly decide: typeof decide;
|
|
144
368
|
readonly translate: typeof translate;
|
|
369
|
+
readonly match: typeof match;
|
|
370
|
+
readonly retry: typeof retry;
|
|
371
|
+
readonly all: typeof all;
|
|
372
|
+
readonly map: typeof map;
|
|
373
|
+
readonly using: typeof using;
|
|
374
|
+
readonly usingAsync: typeof usingAsync;
|
|
145
375
|
};
|
|
146
376
|
|
|
147
|
-
export { type Err, type Failure, type Ok, Result, Trust, decide, err, ok, translate, tryResult, tryResultAsync };
|
|
377
|
+
export { type AllOptions, type Err, type Failure, type MapOptions, type Ok, Result, type StatedOk, type StatedResult, Trust, all, decide, err, map, match, ok, retry, state, translate, tryResult, tryResultAsync, using, usingAsync };
|