@types/async 3.2.1 → 3.2.5

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: Mon, 27 Apr 2020 16:08:33 GMT
+ * Last updated: Mon, 30 Nov 2020 19:12:26 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>;
@@ -149,9 +257,9 @@ export function mapValuesLimit<T, R, E = Error>(
     callback: AsyncResultObjectCallback<R, E>
     ): void;
 export function mapValuesLimit<T, R, E = Error>(
-	obj: Dictionary<T>,
-	limit: number,
-	iteratee: (value: T, key: string, callback: AsyncResultCallback<R, E>) => void
+    obj: Dictionary<T>,
+    limit: number,
+    iteratee: (value: T, key: string, callback: AsyncResultCallback<R, E>) => void
 ): Promise<R>;
 
 export function mapValues<T, R, E = Error>(obj: Dictionary<T>, iteratee: (value: T, key: string, callback: AsyncResultCallback<R, E>) => void, callback: AsyncResultObjectCallback<R, E>): void;
@@ -207,8 +315,8 @@ export function parallel<T, R, E = Error>(tasks: Array<AsyncFunction<T, E>> | Di
 export function parallelLimit<T, E = Error>(tasks: Array<AsyncFunction<T, E>>, limit: number, callback?: AsyncResultArrayCallback<T, E>): void;
 export function parallelLimit<T, E = Error>(tasks: Dictionary<AsyncFunction<T, E>>, limit: number, callback?: AsyncResultObjectCallback<T, E>): void;
 export function parallelLimit<T, R, E = Error>(tasks: Array<AsyncFunction<T, E>> | Dictionary<AsyncFunction<T, E>>, limit: number): Promise<R>;
-export function whilst<E = Error>(test: () => boolean, fn: AsyncVoidFunction<E>, callback: ErrorCallback<E>): void;
-export function whilst<R, E = Error>(test: () => boolean, fn: AsyncVoidFunction<E>): Promise<R>;
+export function whilst<E = Error>(test: (cb: (err: any, truth: boolean) => boolean) => boolean, fn: AsyncVoidFunction<E>, callback: ErrorCallback<E>): void;
+export function whilst<R, E = Error>(test: (cb: (err: any, truth: boolean) => boolean) => boolean, fn: AsyncVoidFunction<E>): Promise<R>;
 export function doWhilst<T, E = Error>(fn: AsyncFunctionEx<T, E>, test: (...results: T[]) => boolean, callback: ErrorCallback<E>): void;
 export function doWhilst<T, R, E = Error>(fn: AsyncFunctionEx<T, E>, test: (...results: T[]) => boolean): Promise<R>;
 export function until<E = Error>(test: () => boolean, fn: AsyncVoidFunction<E>, callback: ErrorCallback<E>): void;
@@ -223,37 +331,41 @@ 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 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, 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 function retry<T, E = Error>(
-    opts?:
-        | number
-        | {
-              times?: number;
-              interval?: number | ((retryCount: number) => number);
-              errorFilter?: (error: Error) => boolean;
-          },
+    opts?: number | RetryOptions,
     task?: (callback: AsyncResultCallback<T, E>, results: any) => void,
 ): Promise<void>;
 export function retry<T, E = Error>(
-    opts?:
-        | number
-        | {
-              times?: number;
-              interval?: number | ((retryCount: number) => number);
-              errorFilter?: (error: Error) => boolean;
-          },
+    opts?: number | RetryOptions,
     task?: (callback: AsyncResultCallback<T, E>, results: any) => void,
     callback?: AsyncResultCallback<any, E>,
 ): void;
 
-export function retryable<T, E = Error>(opts: number | {times: number, interval: number}, task: AsyncFunction<T, E>): AsyncFunction<T, E>;
+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>
+): 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;

async/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/async",
-    "version": "3.2.1",
+    "version": "3.2.5",
     "description": "TypeScript definitions for Async",
     "license": "MIT",
     "contributors": [
@@ -59,6 +59,6 @@
     },
     "scripts": {},
     "dependencies": {},
-    "typesPublisherContentHash": "58ccc56b70520fa2b8b746c864a55a12aa2f4247c1f388d6f1b27400edba83cc",
-    "typeScriptVersion": "2.8"
+    "typesPublisherContentHash": "5d3403505c739b80abfffa8203dc15c69212c682e9995f3b0e840012bd4e0ebe",
+    "typeScriptVersion": "3.3"
 }