import { type ArrayOrValue } from '../array/array';
import { type Milliseconds } from '../date/date';
import { type ReadAllKeysFunction, type PrimativeKey } from '../key';
import { type StringFactory } from '../string/factory';
import { type IndexNumber } from '../value';
import { type Maybe } from '../value/maybe.type';
import { type PromiseOrValue } from './promise.type';
/**
 * Configuration for {@link runAsyncTaskForValue}, which omits `throwError` since it always throws on failure.
 */
export type RunAsyncTaskForValueConfig<T = unknown> = Omit<PerformAsyncTaskConfig<T>, 'throwError'>;
/**
 * Configuration for {@link runAsyncTasksForValues}, which omits `throwError` since it always throws on failure.
 */
export type RunAsyncTasksForValuesConfig<T = unknown> = Omit<PerformAsyncTasksConfig<T>, 'throwError'>;
/**
 * Runs a single async task and returns the resulting value. Always configured to throw on failure.
 *
 * @param taskFn - The async task to execute.
 * @param config - Optional configuration for retries and retry behavior.
 * @returns The value produced by the task, or undefined if the task produced no value.
 * @throws Rethrows any error thrown by the task function.
 */
export declare function runAsyncTaskForValue<O>(taskFn: () => Promise<O>, config?: RunAsyncTaskForValueConfig<0>): Promise<Maybe<O>>;
/**
 * Runs an async task for each input value and returns an array of the resulting values.
 * Always configured to throw on failure.
 *
 * @param input - The array of input values to process.
 * @param taskFn - The async task function to run for each input value.
 * @param config - Optional configuration for parallelism and retries.
 * @returns An array of results produced by the task function for each input.
 * @throws Rethrows any error thrown by a task function.
 */
export declare function runAsyncTasksForValues<T, K = unknown>(input: T[], taskFn: PerformAsyncTaskFn<T, K>, config?: RunAsyncTasksForValuesConfig<T>): Promise<K[]>;
/**
 * An async function that processes a value and returns a result. Receives the current retry/try number.
 *
 * @param value - The input value to process.
 * @param tryNumber - The current attempt number (0-based).
 */
export type PerformAsyncTaskFn<T, K = unknown> = (value: T, tryNumber?: number) => Promise<K>;
/**
 * The result of executing a single async task via {@link performAsyncTask}.
 */
export interface PerformAsyncTaskResult<O> {
    /**
     * The resulting value if the task succeeded, or undefined on failure.
     */
    readonly value: Maybe<O>;
    /**
     * Whether the task completed successfully.
     */
    readonly success: boolean;
}
/**
 * The aggregated result of executing multiple async tasks via {@link performAsyncTasks}.
 */
export interface PerformAsyncTasksResult<I, O> {
    /**
     * Input values whose tasks succeeded.
     */
    readonly succeded: I[];
    /**
     * Input values whose tasks failed.
     */
    readonly failed: I[];
    /**
     * Tuples of [input, output] for each successful task.
     */
    readonly results: [I, O][];
    /**
     * Tuples of [input, error] for each failed task.
     */
    readonly errors: [I, unknown][];
}
/**
 * Configuration for retry behavior when performing async tasks.
 */
export interface PerformAsyncTaskConfig<I = unknown> {
    /**
     * Whether or not to throw an error if the task fails. Defaults to true.
     *
     * If retries are allowed, this will throw the final error from the final try.
     */
    readonly throwError?: boolean;
    /**
     * Whether or not retries are allowed. Defaults to false/0.
     */
    readonly retriesAllowed?: number | false;
    /**
     * The amount of time to wait between retries. Defaults to 100 ms.
     */
    readonly retryWait?: number;
    /**
     * Optional function to use before a retry.
     */
    readonly beforeRetry?: (value: I, tryNumber?: number) => void | Promise<void>;
}
/**
 * Configuration for {@link performAsyncTasks}, combining retry behavior with parallel execution options.
 */
export interface PerformAsyncTasksConfig<I = unknown, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey> extends PerformAsyncTaskConfig<I>, Omit<PerformTasksInParallelFunctionConfig<I, K>, 'taskFactory'> {
}
/**
 * Performs async tasks for each input value with configurable retry and parallelism behavior.
 * Useful for operations that may experience optimistic concurrency collisions.
 *
 * @param input - The array of input values to process.
 * @param taskFn - The async function to execute for each input.
 * @param config - Configuration for retries, parallelism, and error handling.
 * @returns An aggregated result with succeeded/failed items and their outputs/errors.
 * @throws Rethrows the last error from retries if `throwError` is true (default).
 */
export declare function performAsyncTasks<I, O = unknown, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(input: I[], taskFn: PerformAsyncTaskFn<I, O>, config?: PerformAsyncTasksConfig<I, K>): Promise<PerformAsyncTasksResult<I, O>>;
/**
 * Performs a single async task with configurable retry behavior and returns the result with success status.
 *
 * @param taskFn - The async task to execute.
 * @param config - Optional configuration for retries and error handling.
 * @returns A result object containing the value (if successful) and a success flag.
 * @throws Rethrows the last error from retries if `throwError` is true (default).
 */
export declare function performAsyncTask<O>(taskFn: () => Promise<O>, config?: PerformAsyncTaskConfig<0>): Promise<PerformAsyncTaskResult<O>>;
/**
 * Used as a key to identify the "group" that a task belongs to to prevent other concurrent tasks from that group from running in parallel when parallel execution is desired.
 */
export type PerformTasksInParallelTaskUniqueKey = string;
/**
 * Configuration for {@link performTasksInParallelFunction}, excluding `waitBetweenTaskInputRequests`.
 */
export type PerformTasksInParallelFunctionConfig<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey> = Omit<PerformTasksFromFactoryInParallelFunctionConfig<I, K>, 'waitBetweenTaskInputRequests'>;
/**
 * Function that awaits a promise generated from each of the input values.
 *
 * Will throw an error if any error is encountered as soon as it is encountered. No further tasks will be dispatched, but tasks that have already been dispatched will continue to run.
 */
export type PerformTasksInParallelFunction<I> = (input: I[]) => Promise<void>;
/**
 * Convenience function that creates a parallel task executor and immediately runs it with the given input.
 *
 * @param input - The array of items to process.
 * @param config - Configuration for task execution, parallelism, and concurrency constraints.
 * @returns A Promise that resolves when all tasks complete.
 * @throws Rethrows the first error encountered during task execution.
 */
export declare function performTasksInParallel<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(input: I[], config: PerformTasksInParallelFunctionConfig<I, K>): Promise<void>;
/**
 * Creates a reusable function that performs tasks in parallel with optional concurrency limits
 * and non-concurrent task key constraints.
 *
 * @param config - Configuration for task factory, parallelism limits, and concurrency keys.
 * @returns A function that accepts an array of inputs and returns a Promise resolving when all tasks complete.
 */
export declare function performTasksInParallelFunction<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(config: PerformTasksInParallelFunctionConfig<I, K>): PerformTasksInParallelFunction<I>;
/**
 * Configuration for {@link performTasksFromFactoryInParallelFunction}, controlling task execution,
 * parallelism limits, and non-concurrent key constraints.
 */
export interface PerformTasksFromFactoryInParallelFunctionConfig<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey> {
    /**
     * Creates a promise from the input.
     */
    readonly taskFactory: (input: I, value: IndexNumber, taskKeys: K[]) => Promise<void>;
    /**
     * This function is used to uniquely identify tasks that may use the same resources to prevent such tasks from running concurrently.
     *
     * When in use the order is not guranteed.
     */
    readonly nonConcurrentTaskKeyFactory?: Maybe<ReadAllKeysFunction<I, K>>;
    /**
     * Whether or not tasks are performed sequentially or if tasks are all done in "parellel".
     *
     * Is ignored if maxParallelTasks is set.
     */
    readonly sequential?: boolean;
    /**
     * The maximum number of items to process in parallel. If there is no max, then all items will be processed in parallel.
     */
    readonly maxParallelTasks?: number;
    /**
     * Optional amount of time to wait between each task.
     */
    readonly waitBetweenTasks?: Milliseconds;
    /**
     * Optional amount of time to wait between each task input request.
     */
    readonly waitBetweenTaskInputRequests?: Milliseconds;
}
/**
 * A factory function that produces the next batch of task inputs. Returns `null` to signal
 * that no more inputs are available.
 */
export type PerformTaskFactoryTasksInParallelFunctionTaskInputFactory<I> = () => PromiseOrValue<ArrayOrValue<I> | null>;
/**
 * Function that awaits all promises generated from the task factory until the factory returns null.
 *
 * If an array is pushed then the task factory will begin (but not necessarily complete) all those tasks before pulling the next set of tasks.
 *
 * Will throw an error if any error is encountered as soon as it is encountered. No further tasks will be dispatched, but tasks that have already been dispatched will continue to run.
 */
export type PerformTaskFactoryTasksInParallelFunction<I> = (taskInputFactory: PerformTaskFactoryTasksInParallelFunctionTaskInputFactory<I>) => Promise<void>;
/**
 * Creates a function that pulls task inputs from a factory and executes them in parallel
 * with configurable concurrency limits and non-concurrent key constraints.
 *
 * @param config - Configuration for the task factory, parallelism, and concurrency behavior.
 * @returns a function that accepts a task input factory and returns a Promise that resolves when all tasks complete
 */
export declare function performTasksFromFactoryInParallelFunction<I, K extends PrimativeKey = PerformTasksInParallelTaskUniqueKey>(config: PerformTasksFromFactoryInParallelFunctionConfig<I, K>): PerformTaskFactoryTasksInParallelFunction<I>;
/**
 * Creates a default non-concurrent task key factory that generates unique incrementing number strings.
 *
 * @returns A {@link StringFactory} that produces unique keys for identifying non-concurrent tasks.
 */
export declare function makeDefaultNonConcurrentTaskKeyFactory(): StringFactory<any>;