import { DurationObj } from "./time.mjs";
import * as evtmitter0 from "evtmitter";
import { Result, ResultValidErrors } from "t-result";

//#region src/asyncQueue.d.ts

/** Configuration for rate limiting task execution */
type RateLimit = {
  /** Maximum number of tasks to execute within the interval */
  maxTasks: number;
  /** Time interval in milliseconds or as a duration object */
  interval: DurationObj | number;
};
/** Configuration options for AsyncQueue initialization */
type AsyncQueueOptions = {
  /** Maximum number of tasks to run concurrently (default: 1) */
  concurrency?: number;
  /** AbortSignal to cancel the entire queue */
  signal?: AbortSignal;
  /** Default timeout for all tasks in milliseconds */
  timeout?: number;
  /** Stop processing new tasks when any task fails (default: false) */
  stopOnError?: boolean;
  /** Reject all pending tasks when stopping on error (default: false) */
  rejectPendingOnError?: boolean;
  /** Start processing tasks immediately when added (default: true) */
  autoStart?: boolean;
  /** Rate limit configuration to limit tasks per time interval */
  rateLimit?: RateLimit;
};
/** Options for adding individual tasks to the queue */
type AddOptions<I, T, E extends ResultValidErrors> = {
  /** AbortSignal to cancel this specific task */
  signal?: AbortSignal;
  /** Timeout for this specific task in milliseconds */
  timeout?: number;
  /** Metadata to associate with this task */
  meta?: I;
  /** Callback invoked when task completes successfully */
  onComplete?: (value: T) => void;
  /** Callback invoked when task fails */
  onError?: (error: E | Error) => void;
};
/** Runtime context passed to task functions */
type RunCtx<I> = {
  /** Combined AbortSignal from task, queue, and timeout signals */
  signal?: AbortSignal;
  /** Metadata associated with this task */
  meta?: I;
};
/**
 * A powerful async task queue with advanced error handling and flow control
 *
 * @example
 *   Basic Usage
 *   ```typescript
 *   const queue = createAsyncQueue<string>({ concurrency: 2 });
 *
 *   const processedItems: string[] = [];
 *
 *   queue.resultifyAdd(async () => {
 *   await delay(100);
 *   return 'task completed';
 *   }).then(result => {
 *   if (result.ok) processedItems.push(result.value);
 *   });
 *
 *   await queue.onIdle();
 *   console.log('Processed:', processedItems);
 *   ```
 *
 * @example
 *   Error Recovery
 *   ```typescript
 *   const queue = createAsyncQueue<string>({
 *   stopOnError: true,
 *   rejectPendingOnError: false
 *   });
 *
 *   // Add batch of tasks
 *   const items = ['item1', 'item2', 'bad-item', 'item3'];
 *   items.forEach(item => {
 *   queue.resultifyAdd(async () => {
 *   if (item === 'bad-item') throw new Error('Processing failed');
 *   return item.toUpperCase();
 *   });
 *   });
 *
 *   await queue.onIdle();
 *
 *   if (queue.isStopped) {
 *   console.log(`Stopped at ${queue.failed} failures, ${queue.size} remaining`);
 *   // Reset and continue with remaining tasks
 *   queue.reset();
 *   await queue.onIdle();
 *   }
 *   ```
 *
 * @example
 *   Lazy Start
 *   ```typescript
 *   const queue = createAsyncQueue<string>({ autoStart: false });
 *
 *   // Prepare all tasks without starting
 *   queue.resultifyAdd(() => processTask1());
 *   queue.resultifyAdd(() => processTask2());
 *   queue.resultifyAdd(() => processTask3());
 *
 *   // Start processing when ready
 *   queue.start();
 *   await queue.onIdle();
 *   ```
 *
 * @template T - The type of value returned by successful tasks
 * @template E - The type of errors that tasks can produce (defaults to Error)
 * @template I - The type of metadata associated with tasks (defaults to
 *   unknown)
 */
declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = unknown> {
  #private;
  /**
   * Event emitter for tracking task lifecycle
   *
   * @example
   *   Listening to Events
   *   ```typescript
   *   const queue = createAsyncQueue<string>();
   *
   *   queue.events.on('start', (event) => {
   *   console.log('Task started:', event.payload.meta);
   *   });
   *
   *   queue.events.on('complete', (event) => {
   *   console.log('Task completed:', event.payload.value);
   *   });
   *
   *   queue.events.on('error', (event) => {
   *   console.error('Task failed:', event.payload.error);
   *   });
   *   ```
   */
  events: evtmitter0.Emitter<{
    /** Emitted when a task starts executing */
    start: {
      meta: I;
    };
    /** Emitted when a task completes successfully */
    complete: {
      meta: I;
      value: T;
    };
    /** Emitted when a task fails */
    error: {
      meta: I;
      error: E | Error;
    };
  }>;
  /** Array of all task failures with metadata for debugging and analysis */
  failures: Array<{
    meta: I;
    error: E | Error;
  }>;
  /** Array of all task completions with metadata for debugging and analysis */
  completions: Array<{
    meta: I;
    value: T;
  }>;
  constructor({
    concurrency,
    signal,
    timeout: taskTimeout,
    stopOnError,
    rejectPendingOnError,
    autoStart,
    rateLimit
  }?: AsyncQueueOptions);
  /**
   * Add a task that returns a Result to the queue
   *
   * Use this method when your task function already returns a Result type. For
   * functions that throw errors or return plain values, use `resultifyAdd`
   * instead.
   *
   * @example
   *   ```typescript
   *   const queue = createAsyncQueue<string>();
   *
   *   const result = await queue.add(async () => {
   *     try {
   *       const data = await fetchData();
   *       return Result.ok(data);
   *     } catch (error) {
   *       return Result.err(error);
   *     }
   *   });
   *
   *   if (result.ok) {
   *     console.log('Success:', result.value);
   *   } else {
   *     console.log('Error:', result.error);
   *   }
   *   ```;
   *
   * @param fn - Task function that returns a Result
   * @param options - Optional configuration for this task
   * @returns Promise that resolves with the task result
   */
  add(fn: (ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>, options?: AddOptions<I, T, E>): Promise<Result<T, E | Error>>;
  /**
   * Add a task that returns a plain value or throws errors to the queue
   *
   * This is the most commonly used method. It automatically wraps your function
   * to handle errors and convert them to Result types.
   *
   * @example
   *   Basic Usage
   *   ```typescript
   *   const queue = createAsyncQueue<string>();
   *
   *   queue.resultifyAdd(async () => {
   *   const response = await fetch('/api/data');
   *   return response.json();
   *   }).then(result => {
   *   if (result.ok) {
   *   console.log('Data:', result.value);
   *   } else {
   *   console.error('Failed:', result.error);
   *   }
   *   });
   *   ```
   *
   * @example
   *   With Callbacks
   *   ```typescript
   *   queue.resultifyAdd(
   *   async () => processData(),
   *   {
   *   onComplete: (data) => console.log('Processed:', data),
   *   onError: (error) => console.error('Failed:', error),
   *   timeout: 5000
   *   }
   *   );
   *   ```
   *
   * @param fn - Task function that returns a value or throws
   * @param options - Optional configuration for this task
   * @returns Promise that resolves with the task result wrapped in Result
   */
  resultifyAdd(fn: (ctx: RunCtx<I>) => Promise<T> | T, options?: AddOptions<I, T, E>): Promise<Result<T, E | Error>>;
  /**
   * Wait for the queue to become idle (no pending tasks, no queued tasks, and
   * no rate-limit timers)
   *
   * This method resolves when:
   *
   * - All tasks have completed (success or failure)
   * - The queue is stopped due to error (stopOnError), even with remaining tasks
   * - There are no queued tasks, no running tasks, and no pending rate-limit
   *   timers
   *
   * @example
   *   ```typescript
   *   const queue = createAsyncQueue<string>();
   *
   *   // Add multiple tasks
   *   for (let i = 0; i < 10; i++) {
   *   queue.resultifyAdd(async () => `task ${i}`);
   *   }
   *
   *   // Wait for all tasks to complete
   *   await queue.onIdle();
   *
   *   console.log(`Completed: ${queue.completed}, Failed: ${queue.failed}`);
   *   ```
   *
   * @returns Promise that resolves when the queue is idle
   */
  onIdle(): Promise<void>;
  /**
   * Wait until the queued task count is below a limit
   *
   * Resolves immediately if `size < limit` at the moment of calling. This only
   * considers queued (not yet started) tasks; running tasks are tracked by
   * `pending`.
   *
   * @param limit Threshold that `size` must be below to resolve
   */
  onSizeLessThan(limit: number): Promise<void>;
  /**
   * Clear all queued tasks (does not affect currently running tasks)
   *
   * This removes all tasks waiting in the queue but allows currently executing
   * tasks to complete normally.
   *
   * @example
   *   ```typescript
   *   const queue = createAsyncQueue({ concurrency: 1 });
   *
   *   // Add multiple tasks
   *   queue.resultifyAdd(async () => longRunningTask()); // Will start immediately
   *   queue.resultifyAdd(async () => task2()); // Queued
   *   queue.resultifyAdd(async () => task3()); // Queued
   *
   *   // Clear remaining queued tasks
   *   queue.clear();
   *
   *   // Only the first task will complete
   *   await queue.onIdle();
   *   ```;
   */
  clear(): void;
  /** Number of tasks that have completed successfully */
  get completed(): number;
  /** Number of tasks that have failed */
  get failed(): number;
  /** Number of tasks currently being processed */
  get pending(): number;
  /** Number of tasks waiting in the queue to be processed */
  get size(): number;
  /**
   * Manually start processing tasks (only needed if autoStart: false)
   *
   * @example
   *   ```typescript
   *   const queue = createAsyncQueue({ autoStart: false });
   *
   *   // Add tasks without starting processing
   *   queue.resultifyAdd(async () => 'task1');
   *   queue.resultifyAdd(async () => 'task2');
   *
   *   // Start processing when ready
   *   queue.start();
   *   await queue.onIdle();
   *   ```;
   */
  start(): void;
  /**
   * Pause processing new tasks (currently running tasks continue)
   *
   * @example
   *   ```typescript
   *   const queue = createAsyncQueue();
   *
   *   // Start some tasks
   *   queue.resultifyAdd(async () => longRunningTask1());
   *   queue.resultifyAdd(async () => longRunningTask2());
   *
   *   // Pause before more tasks are picked up
   *   queue.pause();
   *
   *   // Later, resume processing
   *   queue.resume();
   *   ```;
   */
  pause(): void;
  /** Resume processing tasks after pause */
  resume(): void;
  /**
   * Reset the queue after being stopped, allowing new tasks to be processed
   *
   * This clears the stopped state and error reason, and resumes processing any
   * remaining queued tasks if autoStart was enabled.
   *
   * @example
   *   ```typescript
   *   const queue = createAsyncQueue({ stopOnError: true });
   *
   *   // Add tasks that will cause the queue to stop
   *   queue.resultifyAdd(async () => { throw new Error('fail'); });
   *   queue.resultifyAdd(async () => 'remaining task');
   *
   *   await queue.onIdle();
   *
   *   if (queue.isStopped) {
   *   console.log(`Queue stopped, ${queue.size} tasks remaining`);
   *
   *   // Reset and process remaining tasks
   *   queue.reset();
   *   await queue.onIdle();
   *   }
   *   ```
   */
  reset(): void;
  /** Whether the queue is stopped due to an error */
  get isStopped(): boolean;
  /** Whether the queue is currently paused */
  get isPaused(): boolean;
  /** Whether the queue has been started (relevant for autoStart: false) */
  get isStarted(): boolean;
  /** The error that caused the queue to stop (if any) */
  get stoppedReason(): Error | undefined;
}
/** AddOptions variant that requires metadata to be provided */
type AddOptionsWithId<I, T, E extends ResultValidErrors> = Omit<AddOptions<I, T, E>, 'meta'> & {
  meta: I;
};
/**
 * AsyncQueue variant that requires metadata for all tasks
 *
 * This class enforces that every task must include metadata, which is useful
 * when you need to track or identify tasks consistently.
 *
 * @example
 *   ```typescript
 *   interface TaskMeta {
 *   id: string;
 *   priority: number;
 *   }
 *
 *   const queue = createAsyncQueueWithMeta<string, TaskMeta>({ concurrency: 2 });
 *
 *   queue.resultifyAdd(
 *   async () => processImportantTask(),
 *   { meta: { id: 'task-1', priority: 1 } }
 *   );
 *
 *   // Listen to events with metadata
 *   queue.events.on('complete', (event) => {
 *   console.log(`Task ${event.payload.meta.id} completed`);
 *   });
 *   ```
 *
 * @template T - The type of value returned by successful tasks
 * @template I - The type of metadata (required for all tasks)
 * @template E - The type of errors that tasks can produce
 */
declare class AsyncQueueWithMeta<T, I, E extends ResultValidErrors = Error> extends AsyncQueue<T, E, I> {
  constructor(options?: AsyncQueueOptions);
  add(fn: (ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>, options: AddOptionsWithId<I, T, E>): Promise<Result<T, E | Error>>;
  resultifyAdd(fn: (ctx: RunCtx<I>) => Promise<T> | T, options: AddOptionsWithId<I, T, E>): Promise<Result<T, E | Error>>;
}
/**
 * Create a new AsyncQueue instance
 *
 * @example
 *   Basic Queue
 *   ```typescript
 *   const queue = createAsyncQueue<string>({ concurrency: 3 });
 *   ```
 *
 * @example
 *   Error Handling Queue
 *   ```typescript
 *   const queue = createAsyncQueue<string>({
 *   concurrency: 2,
 *   stopOnError: true,
 *   rejectPendingOnError: true
 *   });
 *   ```
 *
 * @example
 *   Lazy Start Queue
 *   ```typescript
 *   const queue = createAsyncQueue<string>({
 *   autoStart: false,
 *   concurrency: 1
 *   });
 *   ```
 *
 * @template T - The type of value returned by successful tasks
 * @template E - The type of errors that tasks can produce (defaults to Error)
 * @param options - Configuration options for the queue
 * @returns A new AsyncQueue instance
 */
declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, E>;
/**
 * Create a new AsyncQueueWithMeta instance that requires metadata for all tasks
 *
 * @example
 *   ```typescript
 *   interface TaskInfo {
 *   taskId: string;
 *   userId: string;
 *   }
 *
 *   const queue = createAsyncQueueWithMeta<ProcessResult, TaskInfo>({
 *   concurrency: 5
 *   });
 *
 *   queue.resultifyAdd(
 *   async (ctx) => {
 *   console.log(`Processing task ${ctx.meta.taskId} for user ${ctx.meta.userId}`);
 *   return await processUserTask(ctx.meta.userId);
 *   },
 *   { meta: { taskId: '123', userId: 'user456' } }
 *   );
 *   ```
 *
 * @template T - The type of value returned by successful tasks
 * @template I - The type of metadata (required for all tasks)
 * @template E - The type of errors that tasks can produce (defaults to Error)
 * @param options - Configuration options for the queue
 * @returns A new AsyncQueueWithMeta instance
 */
declare function createAsyncQueueWithMeta<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithMeta<T, I, E>;
//#endregion
export { type AsyncQueue, type AsyncQueueWithMeta, createAsyncQueue, createAsyncQueueWithMeta };