@types/async 3.2.4 → 3.2.8

async/README.md

@@ -8,7 +8,7 @@ This package contains type definitions for Async (https://github.com/caolan/asyn
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/async.
 
 ### Additional Details
- * Last updated: Thu, 12 Nov 2020 20:50:55 GMT
+ * Last updated: Sat, 18 Sep 2021 09:31:20 GMT
  * Dependencies: none
  * Global values: `async`
 

async/index.d.ts

@@ -41,6 +41,7 @@ export interface AsyncAutoTaskFunction<R1, R extends Dictionary<any>, E = Error>
 
 export interface DataContainer<T> {
     data: T;
+    priority: number;
 }
 
 export interface CallbackContainer {
@@ -51,74 +52,181 @@ export interface PriorityContainer {
     priority: number;
 }
 
-export interface AsyncQueue<T> {
+export interface QueueObject<T> {
+    /**
+     * Returns the number of items waiting to be processed.
+     */
     length(): number;
+
+    /**
+     * Indicates whether or not any items have been pushed and processed by the queue.
+     */
     started: boolean;
+
+    /**
+     * Returns the number of items currently being processed.
+     */
     running(): number;
+
+    /**
+     * Returns an array of items currently being processed.
+     */
+    workersList<TWorker extends DataContainer<T>, CallbackContainer>(): TWorker[];
+
+    /**
+     * Returns false if there are items waiting or being processed, or true if not.
+     */
     idle(): boolean;
+
+    /**
+     * An integer for determining how many worker functions should be run in parallel.
+     * This property can be changed after a queue is created to alter the concurrency on-the-fly.
+     */
     concurrency: number;
-    push<R, E = Error>(task: T | T[], callback?: AsyncResultCallback<R, E>): void;
-    unshift<E = Error>(task: T | T[], callback?: ErrorCallback<E>): void;
+
+    /**
+     * An integer that specifies how many items are passed to the worker function at a time.
+     * Only applies if this is a cargo object
+     */
+    payload: number;
+
+    /**
+     * Add a new task to the queue. Calls `callback` once the worker has finished
+     * processing the task.
+     *
+     * Instead of a single task, a tasks array can be submitted.
+     * The respective callback is used for every task in the list.
+     */
+    push<R>(task: T | T[]): Promise<R>;
+    push<R, E = Error>(task: T | T[], callback: AsyncResultCallback<R, E>): void;
+
+    /**
+     * Add a new task to the front of the queue
+     */
+    unshift<R>(task: T | T[]): Promise<R>;
+    unshift<R, E = Error>(task: T | T[], callback: AsyncResultCallback<R, E>): void;
+
+    /**
+     * The same as `q.push`, except this returns a promise that rejects if an error occurs.
+     * The `callback` arg is ignored
+     */
+    pushAsync<R>(task: T | T[]): Promise<R>;
+
+    /**
+     * The same as `q.unshift`, except this returns a promise that rejects if an error occurs.
+     * The `callback` arg is ignored
+     */
+    unshiftAsync<R>(task: T | T[]): Promise<R>;
+
+    /**
+     * Remove items from the queue that match a test function.
+     * The test function will be passed an object with a `data` property,
+     * and a `priority` property, if this is a `priorityQueue` object.
+     */
     remove(filter: (node: DataContainer<T>) => boolean): void;
 
+    /**
+     * A function that sets a callback that is called when the number of
+     * running workers hits the `concurrency` limit, and further tasks will be
+     * queued.
+     *
+     * If the callback is omitted, `q.saturated()` returns a promise
+     * for the next occurrence.
+     */
     saturated(): Promise<void>;
     saturated(handler: () => void): void;
+
+    /**
+     * A function that sets a callback that is called when the number
+     * of running workers is less than the `concurrency` & `buffer` limits,
+     * and further tasks will not be queued
+     *
+     * If the callback is omitted, `q.unsaturated()` returns a promise
+     * for the next occurrence.
+     */
+    unsaturated(): Promise<void>;
+    unsaturated(handler: () => void): void;
+
+    /**
+     * A minimum threshold buffer in order to say that the `queue` is `unsaturated`.
+     */
+    buffer: number;
+
+    /**
+     * A function that sets a callback that is called when the last item from the `queue`
+     * is given to a `worker`.
+     *
+     * If the callback is omitted, `q.empty()` returns a promise for the next occurrence.
+     */
     empty(): Promise<void>;
     empty(handler: () => void): void;
+
+    /**
+     * A function that sets a callback that is called when the last item from
+     * the `queue` has returned from the `worker`.
+     *
+     * If the callback is omitted, `q.drain()` returns a promise for the next occurrence.
+     */
     drain(): Promise<void>;
     drain(handler: () => void): void;
 
-    paused: boolean;
-    pause(): void;
-    resume(): void;
-    kill(): void;
-    workersList<TWorker extends DataContainer<T>, CallbackContainer>(): TWorker[];
-
-    error(): Promise<void>;
+    /**
+     * A function that sets a callback that is called when a task errors.
+     *
+     * If the callback is omitted, `q.error()` returns a promise that rejects on the next error.
+     */
+    error(): Promise<never>;
     error(handler: (error: Error, task: T) => void): void;
 
-    unsaturated(): void;
-    buffer: number;
-}
-
-export interface AsyncPriorityQueue<T> {
-    length(): number;
-    concurrency: number;
-    started: boolean;
+    /**
+     * A boolean for determining whether the queue is in a paused state.
+     */
     paused: boolean;
-    push<R, E = Error>(task: T | T[], priority: number, callback?: AsyncResultArrayCallback<R, E>): void;
-    saturated: () => any;
-    empty: () => any;
-    drain: () => any;
-    running(): number;
-    idle(): boolean;
-    pause(): void;
-    resume(): void;
-    kill(): void;
-    workersList<TWorker extends DataContainer<T>, CallbackContainer, PriorityContainer>(): TWorker[];
-    error(error: Error, data: any): void;
-    unsaturated(): void;
-    buffer: number;
-}
 
-export interface AsyncCargo {
-    length(): number;
-    payload?: number;
-    push(task: any, callback?: Function): void;
-    saturated(): void;
-    empty(): void;
     /**
-     * a function that sets a callback that is called when the last item from the queue has returned from the worker.
-     * If the callback is omitted, q.drain() returns a promise for the next occurrence.
+     * A function that pauses the processing of tasks until `q.resume()` is called.
      */
-    drain(): Promise<void>;
-    drain(handler: () => void): void;
-    idle(): boolean;
     pause(): void;
+
+    /**
+     * A function that resumes the processing of queued tasks when the queue
+     * is paused.
+     */
     resume(): void;
+
+    /**
+     * A function that removes the drain callback and empties remaining tasks
+     * from the queue forcing it to go idle. No more tasks should be pushed to
+     * the queue after calling this function.
+     */
     kill(): void;
 }
 
+/**
+ * A priorityQueue object to manage the tasks.
+ *
+ * There are two differences between queue and priorityQueue objects:
+ * - `push(task, priority, [callback])` — priority should be a number. If an array of tasks is given, all tasks will be assigned the same priority.
+ * - The `unshift` method was removed.
+ */
+// FIXME: can not use Omit due to ts version restriction. Replace Pick with Omit, when ts 3.5+ will be allowed
+export interface AsyncPriorityQueue<T> extends Pick<QueueObject<T>, Exclude<keyof QueueObject<T>, 'push' | 'unshift'>> {
+    push<R>(task: T | T[], priority?: number): Promise<R>;
+    push<R, E = Error>(task: T | T[], priority: number, callback: AsyncResultCallback<R, E>): void;
+}
+
+/**
+ * @deprecated this is a type that left here for backward compatibility.
+ * Please use QueueObject instead
+ */
+export type AsyncQueue<T> = QueueObject<T>;
+
+/**
+ * @deprecated this is a type that left here for backward compatibility.
+ * Please use QueueObject instead
+ */
+export type AsyncCargoQueue<T = any> = QueueObject<T>;
+
 // Collections
 export function each<T, E = Error>(arr: IterableCollection<T>, iterator: AsyncIterator<T, E>, callback: ErrorCallback<E>): void;
 export function each<T, E = Error>(arr: IterableCollection<T>, iterator: AsyncIterator<T, E>): Promise<void>;
@@ -223,42 +331,53 @@ export function compose(...fns: Function[]): Function;
 export function seq(...fns: Function[]): Function;
 export function applyEach(fns: Function[], ...argsAndCallback: any[]): void;           // applyEach(fns, args..., callback). TS does not support ... for a middle argument. Callback is optional.
 export function applyEachSeries(fns: Function[], ...argsAndCallback: any[]): void;     // applyEachSeries(fns, args..., callback). TS does not support ... for a middle argument. Callback is optional.
-export function queue<T, E = Error>(worker: AsyncWorker<T, E>, concurrency?: number): AsyncQueue<T>;
-export function queue<T, R, E = Error>(worker: AsyncResultIterator<T, R, E>, concurrency?: number): AsyncQueue<T>;
-export function priorityQueue<T, E = Error>(worker: AsyncWorker<T, E>, concurrency: number): AsyncPriorityQueue<T>;
-export function cargo<E = Error>(worker: (tasks: any[], callback: ErrorCallback<E>) => void, payload?: number): AsyncCargo;
-export function auto<R extends Dictionary<any>, E = Error>(tasks: AsyncAutoTasks<R, E>, concurrency?: number, callback?: AsyncResultCallback<R, E>): void;
-export function auto<R extends Dictionary<any>, E = Error>(tasks: AsyncAutoTasks<R, E>, callback?: AsyncResultCallback<R, E>): void;
+export function queue<T, E = Error>(worker: AsyncWorker<T, E>, concurrency?: number): QueueObject<T>;
+export function queue<T, R, E = Error>(worker: AsyncResultIterator<T, R, E>, concurrency?: number): QueueObject<T>;
+export function priorityQueue<T, E = Error>(worker: AsyncWorker<T, E>, concurrency?: number): AsyncPriorityQueue<T>;
+export function cargo<T, E = Error>(worker: AsyncWorker<T[], E>, payload?: number): QueueObject<T>;
+export function cargoQueue<T, E = Error>(
+    worker: AsyncWorker<T[], E>,
+    concurrency?: number,
+    payload?: number,
+): QueueObject<T>;
+export function auto<R extends Dictionary<any>, E = Error>(tasks: AsyncAutoTasks<R, E>, concurrency?: number): Promise<R>;
+export function auto<R extends Dictionary<any>, E = Error>(tasks: AsyncAutoTasks<R, E>, concurrency: number, callback: AsyncResultCallback<R, E>): void;
+export function auto<R extends Dictionary<any>, E = Error>(tasks: AsyncAutoTasks<R, E>, callback: AsyncResultCallback<R, E>): void;
 export function autoInject<E = Error>(tasks: any, callback?: AsyncResultCallback<any, E>): void;
 
-export interface RetryOptions {
-    times?: number;
-    interval?: number | ((retryCount: number) => number);
-    errorFilter?: (error: Error) => boolean;
+export interface RetryOptions<E> {
+    times?: number | undefined;
+    interval?: number | ((retryCount: number) => number) | undefined;
+    errorFilter?: ((error: E) => boolean) | undefined;
 }
 export function retry<T, E = Error>(
-    opts?: number | RetryOptions,
-    task?: (callback: AsyncResultCallback<T, E>, results: any) => void,
-): Promise<void>;
+    task: (() => Promise<T>) | ((callback: AsyncResultCallback<T, E>) => void),
+): Promise<T>;
+export function retry<T, E = Error>(
+    opts: number | RetryOptions<E>,
+    task: (() => Promise<T>) | ((callback: AsyncResultCallback<T, E>) => void),
+): Promise<T>;
+export function retry<T, E = Error>(
+    task: (() => Promise<T>) | ((callback: AsyncResultCallback<T, E>) => void),
+    callback: AsyncResultCallback<T, E>,
+): void;
 export function retry<T, E = Error>(
-    opts?: number | RetryOptions,
-    task?: (callback: AsyncResultCallback<T, E>, results: any) => void,
-    callback?: AsyncResultCallback<any, E>,
+    opts: number | RetryOptions<E>,
+    task: (() => Promise<T>) | ((callback: AsyncResultCallback<T, E>) => void),
+    callback: AsyncResultCallback<T, E>,
 ): void;
 
 export function retryable<T, E = Error>(task: AsyncFunction<T, E>): AsyncFunction<T, E>;
 export function retryable<T, E = Error>(
-    opts:
-        | number
-        | RetryOptions & {arity?: number},
-     task: AsyncFunction<T, E>
+    opts: number | (RetryOptions<E> & { arity?: number | undefined }),
+    task: AsyncFunction<T, E>,
 ): AsyncFunction<T, E>;
 export function apply<E = Error>(fn: Function, ...args: any[]): AsyncFunction<any, E>;
 export function nextTick(callback: Function, ...args: any[]): void;
 export const setImmediate: typeof nextTick;
 
-export function reflect<T, E = Error>(fn: AsyncFunction<T, E>): (callback: (err: null, result: {error?: E, value?: T}) => void) => void;
-export function reflectAll<T, E = Error>(tasks: Array<AsyncFunction<T, E>>): Array<(callback: (err: null, result: {error?: E, value?: T}) => void) => void>;
+export function reflect<T, E = Error>(fn: AsyncFunction<T, E>): (callback: (err: null, result: {error?: E | undefined, value?: T | undefined}) => void) => void;
+export function reflectAll<T, E = Error>(tasks: Array<AsyncFunction<T, E>>): Array<(callback: (err: null, result: {error?: E | undefined, value?: T | undefined}) => void) => void>;
 
 export function timeout<T, E = Error>(fn: AsyncFunction<T, E>, milliseconds: number, info?: any): AsyncFunction<T, E>;
 export function timeout<T, R, E = Error>(fn: AsyncResultIterator<T, R, E>, milliseconds: number, info?: any): AsyncResultIterator<T, R, E>;

async/package.json

@@ -1,7 +1,8 @@
 {
     "name": "@types/async",
-    "version": "3.2.4",
+    "version": "3.2.8",
     "description": "TypeScript definitions for Async",
+    "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/async",
     "license": "MIT",
     "contributors": [
         {
@@ -59,6 +60,6 @@
     },
     "scripts": {},
     "dependencies": {},
-    "typesPublisherContentHash": "a39b1e6d179968610731335032c5b4c80b79666a75a9d9257ba1032cf3699eb1",
-    "typeScriptVersion": "3.2"
+    "typesPublisherContentHash": "3f35b238c96275a2c048c3cb20dc43836163366b79ac6be29293d6c83bbbafdf",
+    "typeScriptVersion": "3.7"
 }