UNPKG

7.38 kBTypeScriptView Raw
1// Type definitions for Orchestrator 0.3
2// Project: https://github.com/orchestrator/orchestrator
3// Definitions by: Qubo <https://github.com/tkQubo>, TeamworkGuy2 <https://github.com/TeamworkGuy2>
4// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
5// TypeScript Version: 2.3
6
7/// <reference types="node" />
8
9import * as events from "events";
10import * as stream from "stream";
11import * as Q from "q";
12
13/** A module for sequencing and executing tasks and dependencies in maximum concurrency
14 */
15declare class Orchestrator extends events.EventEmitter {
16 doneCallback?: ((error?: any) => any) | undefined;
17 isRunning: boolean;
18 seq: any[];
19 tasks: { [name: string]: Orchestrator.Task };
20
21 reset(): Orchestrator;
22
23 /** Define a task
24 * @param name The name of the task.
25 * @param fn The function that performs the task's operations. For asynchronous tasks, you need to provide a hint when the task is complete:
26 * - Take in a callback
27 * - Return a stream or a promise
28 */
29 add(name: string, fn?: Orchestrator.TaskFunc): Orchestrator;
30 /** Define a task
31 * @param name The name of the task.
32 * @param deps An array of task names to be executed and completed before your task will run.
33 * @param fn The function that performs the task's operations. For asynchronous tasks, you need to provide a hint when the task is complete:
34 * - Take in a callback
35 * - Return a stream or a promise
36 */
37 add(name: string, deps?: string[], fn?: Orchestrator.TaskFunc): Orchestrator;
38
39 task(name: string): Orchestrator.Task;
40 task(name: string, fn: Orchestrator.TaskFunc): void;
41 task(name: string, dep: string[], fn: Orchestrator.TaskFunc): void;
42
43 /** Have you defined a task with this name?
44 * @param name The task name to query
45 */
46 hasTask(name: string): boolean;
47
48 start: Orchestrator.StartMethod;
49
50 stop(err?: any, successfulFinish?: boolean): void;
51
52 sequence: Orchestrator.Sequencify;
53
54 allDone(): boolean;
55
56 /** Listen to orchestrator internals
57 * @param event Event name to listen to:
58 * - start: from start() method, shows you the task sequence
59 * - stop: from stop() method, the queue finished successfully
60 * - err: from stop() method, the queue was aborted due to a task error
61 * - task_start: from _runTask() method, task was started
62 * - task_stop: from _runTask() method, task completed successfully
63 * - task_err: from _runTask() method, task errored
64 * - task_not_found: from start() method, you're trying to start a task that doesn't exist
65 * - task_recursion: from start() method, there are recursive dependencies in your task list
66 * @param cb Passes single argument: e: event details
67 */
68 on(event: Orchestrator.EventNames, cb: (e: Orchestrator.OnCallbackEvent) => any): this;
69
70 /** Listen to all orchestrator events from one callback
71 * @param cb Passes single argument: e: event details
72 */
73 onAll(cb: (e: Orchestrator.OnAllCallbackEvent) => any): void;
74
75 // probably supposed to be private methods, but still available on Orchestrator prototype
76 _resetTask(task: Orchestrator.Task): void;
77
78 _resetAllTasks(): void;
79
80 _resetSpecificTasks(names: string[]): void;
81
82 _runStep(): void;
83
84 _readyToRunTask(task: Orchestrator.Task): boolean;
85
86 _stopTask(task: Orchestrator.Task, meta: Orchestrator.Meta): void;
87
88 _emitTaskDone(task: Orchestrator.Task, message: string, err?: any): void;
89
90 _runTask(task: Orchestrator.Task): void;
91}
92
93declare namespace Orchestrator {
94 type Strings = string | string[];
95
96 /** The method export generated by orchestrator/lib/runTask.js */
97 type RunTask = (task: Orchestrator.TaskFunc, done: (err: any, meta: Orchestrator.Meta) => void) => void;
98
99 /** The module export of the sequencify package: https://www.npmjs.com/package/sequencify */
100 type Sequencify = (tasks: Array<{ dep: string[]; }>, names: string[]) => {
101 sequence: string[];
102 missingTasks: string[];
103 recursiveDependencies: string[];
104 };
105
106 /** A task, can either call a callback to indicate task completion or return a promise or a stream: (task is marked complete when promise.then() resolves/fails or stream ends)
107 */
108 type TaskFunc = (callback: (err?: any) => void) => Q.Promise<any> | stream.Stream | any;
109
110 interface AddMethod {
111 /** Define a task
112 * @param name The name of the task.
113 * @param fn The function that performs the task's operations. For asynchronous tasks, you need to provide a hint when the task is complete:
114 * - Take in a callback
115 * - Return a stream or a promise
116 */
117 (name: string, fn?: TaskFunc): Orchestrator;
118 /** Define a task
119 * @param name The name of the task.
120 * @param deps An array of task names to be executed and completed before your task will run.
121 * @param fn The function that performs the task's operations. For asynchronous tasks, you need to provide a hint when the task is complete:
122 * - Take in a callback
123 * - Return a stream or a promise
124 */
125 (name: string, deps?: string[], fn?: TaskFunc): Orchestrator;
126 }
127
128 /** Start running the tasks
129 */
130 interface StartMethod {
131 /** Start running the tasks
132 * @param tasks Tasks to be executed. You may pass any number of tasks as individual arguments.
133 * @param cb Callback to call after run completed.
134 */
135 (tasks: Strings, cb?: (error?: any) => any): Orchestrator;
136 /** Start running the tasks
137 * @param tasks Tasks to be executed. You may pass any number of tasks as individual arguments.
138 * @param cb Callback to call after run completed.
139 */
140 (...tasks: Strings[]/*, cb?: (error: any) => any */): Orchestrator;
141 // TODO: TypeScript 2.1.5 cannot express varargs followed by callback as a last argument...
142 (task1: Strings, task2: Strings, cb?: (error?: any) => any): Orchestrator;
143 (task1: Strings, task2: Strings, task3: Strings, cb?: (error?: any) => any): Orchestrator;
144 (task1: Strings, task2: Strings, task3: Strings, task4: Strings, cb?: (error?: any) => any): Orchestrator;
145 (task1: Strings, task2: Strings, task3: Strings, task4: Strings, task5: Strings, cb?: (error?: any) => any): Orchestrator;
146 (task1: Strings, task2: Strings, task3: Strings, task4: Strings, task5: Strings, task6: Strings, cb?: (error?: any) => any): Orchestrator;
147 }
148
149 interface OnCallbackEvent {
150 message: string;
151 task: string;
152 err: any;
153 duration?: number | undefined;
154 }
155
156 interface OnAllCallbackEvent extends OnCallbackEvent {
157 src: string;
158 }
159
160 interface Task {
161 fn: TaskFunc;
162 dep: string[];
163 name: string;
164 done?: boolean | undefined;
165 duration?: number | undefined;
166 hrDuration?: [number, number] | undefined;
167 running?: boolean | undefined;
168 }
169
170 interface Meta {
171 duration: number;
172 hrDuration: [number, number];
173 runMethod: ("callback" | "catch" | "promise" | "stream" | "sync");
174 }
175
176 type EventNames = ("start" | "stop" | "err" | "task_start" | "task_stop" | "task_err" | "task_not_found" | "task_recursion");
177}
178
179export = Orchestrator;