tryharder 0.0.0

package/dist/index.d.ts

@@ -0,0 +1,269 @@
+/** @internal */
+declare class ControlError extends Error {}
+declare class CancellationError extends ControlError {
+	constructor(message?: string, options?: ErrorOptions);
+}
+declare class TimeoutError extends ControlError {
+	constructor(message?: string, options?: ErrorOptions);
+}
+declare class RetryExhaustedError extends Error {
+	constructor(message?: string, options?: ErrorOptions);
+}
+declare class UnhandledException extends Error {
+	constructor(message?: string, options?: ErrorOptions);
+}
+type TaskRecord = Record<string, any>;
+type TaskValidation<T extends TaskRecord> = { [K in keyof T] : T[K] extends (...args: any[]) => any ? T[K] : never };
+type TaskResult<T> = T extends (...args: any[]) => infer R ? Awaited<R> : never;
+type InferredTaskContext<T extends TaskRecord> = {
+	$result: { readonly [K in keyof T] : ReturnType<T[K]> extends Promise<infer R> ? Promise<R> : Promise<ReturnType<T[K]>> };
+	$signal: AbortSignal;
+	$disposer: AsyncDisposableStack;
+};
+type AllValue<T extends TaskRecord> = { [K in keyof T] : TaskResult<T[K]> };
+interface AllCatchContext<T extends TaskRecord> {
+	failedTask: (keyof T & string) | undefined;
+	partial: Partial<AllValue<T>>;
+	signal: AbortSignal;
+}
+type AllCatchFn<
+	T extends TaskRecord,
+	C
+> = (error: unknown, ctx: AllCatchContext<T>) => C | Promise<C>;
+interface AllOptions<
+	T extends TaskRecord,
+	C
+> {
+	catch: AllCatchFn<T, C>;
+}
+interface SettledFulfilled<T> {
+	status: "fulfilled";
+	value: T;
+}
+interface SettledRejected {
+	status: "rejected";
+	reason: unknown;
+}
+type SettledResult<T> = SettledFulfilled<T> | SettledRejected;
+type AllSettledResult<T extends TaskRecord> = { [K in keyof T] : SettledResult<TaskResult<T[K]>> };
+interface RetryInfo {
+	attempt: number;
+	limit: number;
+}
+interface BaseTryCtx {
+	signal?: AbortSignal;
+}
+type TryCtxFor<HasRetry extends boolean> = BaseTryCtx & (HasRetry extends true ? {
+	retry: RetryInfo;
+} : Record<never, never>);
+type TryCtx = TryCtxFor<true>;
+type NonPromise<T> = T extends PromiseLike<unknown> ? never : T;
+interface BaseRetryPolicy {
+	/**
+	* Maximum number of attempts, including the first run.
+	*/
+	limit: number;
+	/**
+	* Delay in milliseconds between attempts. Defaults to 0.
+	*/
+	delayMs?: number;
+	/**
+	* Adds random jitter to delays when enabled.
+	*/
+	jitter?: boolean;
+	/**
+	* Return true to retry after an error, false to stop.
+	*/
+	shouldRetry?: (error: unknown, ctx: TryCtx) => boolean;
+}
+interface LinearBackoffRetryPolicy extends BaseRetryPolicy {
+	/**
+	* Use linearly increasing delay between attempts.
+	*/
+	backoff: "linear";
+	/**
+	* Not supported for linear backoff.
+	*/
+	maxDelayMs?: never;
+}
+interface ExponentialBackoffRetryPolicy extends BaseRetryPolicy {
+	/**
+	* Use exponential delay growth between attempts.
+	*/
+	backoff: "exponential";
+	/**
+	* Optional cap for exponential delay in milliseconds.
+	*/
+	maxDelayMs?: number;
+}
+/**
+* Retry policy using a constant delay strategy.
+*/
+interface ConstantBackoffRetryPolicy extends BaseRetryPolicy {
+	/**
+	* Required discriminant: use a fixed delay between attempts.
+	*/
+	backoff: "constant";
+	/**
+	* Not supported for constant backoff.
+	*/
+	maxDelayMs?: never;
+}
+/**
+* Retry configuration object.
+*/
+type RetryPolicy = LinearBackoffRetryPolicy | ExponentialBackoffRetryPolicy | ConstantBackoffRetryPolicy;
+/**
+* Retry shorthand or full retry configuration.
+*
+* - `number`: attempt limit
+* - `RetryPolicy`: detailed retry settings
+*/
+type RetryOptions = number | RetryPolicy;
+declare function retryOptions(policy: RetryOptions): RetryPolicy;
+declare const FLOW_EXIT_BRAND: unique symbol;
+type FlowExit<T> = {
+	readonly [FLOW_EXIT_BRAND]: T;
+};
+type ExitValue<T> = T extends FlowExit<infer V> ? V : never;
+type FlowExitValue<T extends TaskRecord> = { [K in keyof T] : ExitValue<TaskResult<T[K]>> }[keyof T];
+type InferredFlowTaskContext<T extends TaskRecord> = InferredTaskContext<T> & {
+	$exit<V>(value: V): FlowExit<V>;
+};
+type FlowResult<T extends TaskRecord> = FlowExitValue<T>;
+type RunTryFn<
+	T,
+	Ctx extends BaseTryCtx = BaseTryCtx
+> = (ctx: Ctx) => NonPromise<T> | Promise<T>;
+type RunCatchFn<E> = (error: unknown) => NonPromise<E> | Promise<E>;
+interface RunAsyncOptions<
+	T,
+	E,
+	Ctx extends BaseTryCtx = BaseTryCtx
+> {
+	try: RunTryFn<T, Ctx>;
+	catch: RunCatchFn<E>;
+}
+type AsyncRunInput<
+	T,
+	E,
+	Ctx extends BaseTryCtx = BaseTryCtx
+> = RunTryFn<T, Ctx> | RunAsyncOptions<T, E, Ctx>;
+type SyncRunTryFn<
+	T,
+	Ctx extends BaseTryCtx = BaseTryCtx
+> = (ctx: Ctx) => NonPromise<T>;
+type SyncRunCatchFn<E> = (error: unknown) => NonPromise<E>;
+interface SyncRunOptions<
+	T,
+	E,
+	Ctx extends BaseTryCtx = BaseTryCtx
+> {
+	try: SyncRunTryFn<T, Ctx>;
+	catch: SyncRunCatchFn<E>;
+}
+type SyncRunInput<
+	T,
+	E,
+	Ctx extends BaseTryCtx = BaseTryCtx
+> = SyncRunTryFn<T, Ctx> | SyncRunOptions<T, E, Ctx>;
+/**
+* Wraps are observational hooks: they can inspect execution context and
+* surround execution, but they must not mutate context or replace it.
+*/
+type WrapCtx = Readonly<Omit<TryCtx, "retry">> & {
+	readonly retry: Readonly<TryCtx["retry"]>;
+};
+type WrapFn = (ctx: WrapCtx, next: () => unknown) => unknown;
+interface BuilderConfig {
+	/**
+	* Retry configuration applied to the run.
+	*/
+	retry?: RetryPolicy;
+	/**
+	* Timeout configuration applied to the run.
+	*/
+	timeout?: number;
+	/**
+	* Abort signals used to cancel execution.
+	*/
+	signals?: AbortSignal[];
+	/**
+	* Wrapper middleware chain around execution.
+	*/
+	wraps?: WrapFn[];
+}
+type ConfigRunErrors = RetryExhaustedError | TimeoutError | CancellationError;
+type OrchestrationMethods = "all" | "allSettled" | "flow";
+type SignalBuilderHiddenMethods<SupportsOrchestration extends boolean> = "runSync" | "wrap" | (SupportsOrchestration extends true ? never : OrchestrationMethods);
+type ExecutionBuilderSurface<
+	E extends ConfigRunErrors,
+	HasRetry extends boolean
+> = Omit<RunBuilder<E, HasRetry, false>, OrchestrationMethods | "wrap">;
+type AsyncExecutionBuilderSurface<
+	E extends ConfigRunErrors,
+	HasRetry extends boolean
+> = Omit<RunBuilder<E, HasRetry, false>, OrchestrationMethods | "runSync" | "wrap">;
+type SignalBuilderSurface<
+	E extends ConfigRunErrors,
+	HasRetry extends boolean,
+	SupportsOrchestration extends boolean
+> = Omit<RunBuilder<E, HasRetry, SupportsOrchestration>, SignalBuilderHiddenMethods<SupportsOrchestration>>;
+declare class RunBuilder<
+	E extends ConfigRunErrors = never,
+	HasRetry extends boolean = false,
+	SupportsOrchestration extends boolean = true
+> {
+	protected readonly config: BuilderConfig;
+	constructor(config?: BuilderConfig);
+	protected buildRetryConfig(policy: RetryOptions): BuilderConfig;
+	protected buildTimeoutConfig(ms: number): BuilderConfig;
+	protected buildSignalConfig(signal: AbortSignal): BuilderConfig;
+	retry(policy: number): ExecutionBuilderSurface<E | RetryExhaustedError, true>;
+	retry(policy: RetryOptions): AsyncExecutionBuilderSurface<E | RetryExhaustedError, true>;
+	timeout(ms: number): AsyncExecutionBuilderSurface<E | TimeoutError, HasRetry>;
+	signal(signal: AbortSignal): SignalBuilderSurface<E | CancellationError, HasRetry, SupportsOrchestration>;
+	wrap(fn: WrapFn): RunBuilder<E, HasRetry, SupportsOrchestration>;
+	run<T>(tryFn: RunTryFn<T, TryCtxFor<HasRetry>>): Promise<T | UnhandledException | E>;
+	run<
+		T,
+		C
+	>(options: AsyncRunInput<T, C, TryCtxFor<HasRetry>>): Promise<T | C | E>;
+	runSync<T>(tryFn: SyncRunTryFn<T, TryCtxFor<HasRetry>>): T | UnhandledException | E;
+	runSync<
+		T,
+		C
+	>(input: SyncRunInput<T, C, TryCtxFor<HasRetry>>): T | C | E;
+	all<
+		T extends TaskRecord,
+		C = never
+	>(tasks: T & TaskValidation<NoInfer<T>> & ThisType<InferredTaskContext<T>>, options?: AllOptions<T, C>): Promise<{ [K in keyof T] : TaskResult<T[K]> } | C>;
+	allSettled<T extends TaskRecord>(tasks: T & TaskValidation<NoInfer<T>> & ThisType<InferredTaskContext<T>>): Promise<AllSettledResult<T>>;
+	flow<T extends TaskRecord>(tasks: T & ThisType<InferredFlowTaskContext<T>>): Promise<FlowResult<T>>;
+}
+declare function dispose(): AsyncDisposableStack;
+type GenUnwrap<T> = Exclude<Awaited<T>, Error>;
+type GenUse = <T>(value: T) => Generator<T, GenUnwrap<T>, GenUnwrap<T>>;
+type GenErrors<TYield> = Extract<Awaited<TYield>, Error>;
+type CheckIsAsync<
+	TYield,
+	TReturn
+> = Extract<TYield | TReturn, PromiseLike<unknown>> extends never ? false : true;
+type GenResult<
+	TYield,
+	TReturn
+> = CheckIsAsync<TYield, TReturn> extends true ? Promise<Awaited<TReturn> | GenErrors<TYield>> : Awaited<TReturn> | GenErrors<TYield>;
+declare function driveGen<
+	TYield,
+	TReturn
+>(factory: (useFn: GenUse) => Generator<TYield, TReturn, unknown>): GenResult<TYield, TReturn>;
+declare const all: RunBuilder["all"];
+declare const allSettled2: RunBuilder["allSettled"];
+declare const flow: RunBuilder["flow"];
+declare const retry: RunBuilder["retry"];
+declare const run: RunBuilder["run"];
+declare const runSync2: RunBuilder["runSync"];
+declare const signal: RunBuilder["signal"];
+declare const timeout: RunBuilder["timeout"];
+declare const wrap: RunBuilder["wrap"];
+export { wrap, timeout, signal, runSync2 as runSync, run, retryOptions, retry, driveGen as gen, flow, dispose, allSettled2 as allSettled, all };