1 |
|
2 |
|
3 |
|
4 |
|
5 |
|
6 |
|
7 |
|
8 |
|
9 |
|
10 |
|
11 | export = Q;
|
12 | export as namespace Q;
|
13 |
|
14 |
|
15 |
|
16 |
|
17 |
|
18 |
|
19 | declare function Q<T>(promise: PromiseLike<T> | T): Q.Promise<T>;
|
20 |
|
21 |
|
22 |
|
23 | declare function Q(): Q.Promise<void>;
|
24 |
|
25 | declare namespace Q {
|
26 | export type IWhenable<T> = PromiseLike<T> | T;
|
27 | export type IPromise<T> = PromiseLike<T>;
|
28 |
|
29 | export interface Deferred<T> {
|
30 | promise: Promise<T>;
|
31 |
|
32 | |
33 |
|
34 |
|
35 |
|
36 |
|
37 |
|
38 |
|
39 | resolve(value?: IWhenable<T>): void;
|
40 |
|
41 | |
42 |
|
43 |
|
44 | reject(reason?: any): void;
|
45 |
|
46 | |
47 |
|
48 |
|
49 |
|
50 | notify(value: any): void;
|
51 |
|
52 | |
53 |
|
54 |
|
55 |
|
56 | makeNodeResolver(): (reason: any, value: T) => void;
|
57 | }
|
58 |
|
59 | export interface Promise<T> {
|
60 | |
61 |
|
62 |
|
63 | then<U>(
|
64 | onFulfill?: ((value: T) => IWhenable<U>) | null,
|
65 | onReject?: ((error: any) => IWhenable<U>) | null,
|
66 | onProgress?: ((progress: any) => any) | null,
|
67 | ): Promise<U>;
|
68 | then<U = T, V = never>(
|
69 | onFulfill?: ((value: T) => IWhenable<U>) | null,
|
70 | onReject?: ((error: any) => IWhenable<V>) | null,
|
71 | onProgress?: ((progress: any) => any) | null,
|
72 | ): Promise<U | V>;
|
73 | /**
|
74 | * Like a finally clause, allows you to observe either the fulfillment or rejection of a promise, but to do so
|
75 | * without modifying the final value. This is useful for collecting resources regardless of whether a job succeeded,
|
76 | * like closing a database connection, shutting a server down, or deleting an unneeded key from an object.
|
77 | * finally returns a promise, which will become resolved with the same fulfillment value or rejection reason
|
78 | * as promise. However, if callback returns a promise, the resolution of the returned promise will be delayed
|
79 | * until the promise returned from callback is finished. Furthermore, if the returned promise rejects, that
|
80 | * rejection will be passed down the chain instead of the previous result.
|
81 | */
|
82 | finally(finallyCallback: () => any): Promise<T>;
|
83 |
|
84 | /**
|
85 | * Alias for finally() (for non-ES5 browsers)
|
86 | */
|
87 | fin(finallyCallback: () => any): Promise<T>;
|
88 |
|
89 | /**
|
90 | * Like then, but "spreads" the array into a variadic fulfillment handler. If any of the promises in the array are
|
91 | * rejected, instead calls onRejected with the first rejected promise's rejection reason.
|
92 | * This is especially useful in conjunction with all
|
93 | */
|
94 | spread<U>(onFulfill: (...args: any[]) => IWhenable<U>, onReject?: (reason: any) => IWhenable<U>): Promise<U>;
|
95 |
|
96 | /**
|
97 | * A sugar method, equivalent to promise.then(undefined, onRejected).
|
98 | */
|
99 | catch<U>(onRejected: (reason: any) => IWhenable<U>): Promise<U>;
|
100 |
|
101 | /**
|
102 | * Alias for catch() (for non-ES5 browsers)
|
103 | */
|
104 | fail<U>(onRejected: (reason: any) => IWhenable<U>): Promise<U>;
|
105 |
|
106 | /**
|
107 | * A sugar method, equivalent to promise.then(undefined, undefined, onProgress).
|
108 | */
|
109 | progress(onProgress: (progress: any) => any): Promise<T>;
|
110 |
|
111 | /**
|
112 | * Much like then, but with different behavior around unhandled rejection. If there is an unhandled rejection,
|
113 | * either because promise is rejected and no onRejected callback was provided, or because onFulfilled or onRejected
|
114 | * threw an error or returned a rejected promise, the resulting rejection reason is thrown as an exception in a
|
115 | * future turn of the event loop.
|
116 | * This method should be used to terminate chains of promises that will not be passed elsewhere. Since exceptions
|
117 | * thrown in then callbacks are consumed and transformed into rejections, exceptions at the end of the chain are
|
118 | * easy to accidentally, silently ignore. By arranging for the exception to be thrown in a future turn of the
|
119 | * event loop, so that it won't be caught, it causes an onerror event on the browser window, or an uncaughtException
|
120 | * event on Node.js's process object.
|
121 | * Exceptions thrown by done will have long stack traces, if Q.longStackSupport is set to true. If Q.onerror is set,
|
122 | * exceptions will be delivered there instead of thrown in a future turn.
|
123 | * The Golden Rule of done vs. then usage is: either return your promise to someone else, or if the chain ends
|
124 | * with you, call done to terminate it. Terminating with catch is not sufficient because the catch handler may
|
125 | * itself throw an error.
|
126 | */
|
127 | done(
|
128 | onFulfilled?: ((value: T) => any) | null,
|
129 | onRejected?: ((reason: any) => any) | null,
|
130 | onProgress?: ((progress: any) => any) | null,
|
131 | ): void;
|
132 |
|
133 | /**
|
134 | * If callback is a function, assumes it's a Node.js-style callback, and calls it as either callback(rejectionReason)
|
135 | * when/if promise becomes rejected, or as callback(null, fulfillmentValue) when/if promise becomes fulfilled.
|
136 | * If callback is not a function, simply returns promise.
|
137 | */
|
138 | nodeify(callback: (reason: any, value: any) => void): Promise<T>;
|
139 |
|
140 | /**
|
141 | * Returns a promise to get the named property of an object. Essentially equivalent to
|
142 | *
|
143 | * @example
|
144 | * promise.then(function (o) { return o[propertyName]; });
|
145 | */
|
146 | get<U>(propertyName: string): Promise<U>;
|
147 |
|
148 | set<U>(propertyName: string, value: any): Promise<U>;
|
149 |
|
150 | delete<U>(propertyName: string): Promise<U>;
|
151 |
|
152 | /**
|
153 | * Returns a promise for the result of calling the named method of an object with the given array of arguments.
|
154 | * The object itself is this in the function, just like a synchronous method call. Essentially equivalent to
|
155 | *
|
156 | * @example
|
157 | * promise.then(function (o) { return o[methodName].apply(o, args); });
|
158 | */
|
159 | post<U>(methodName: string, args: any[]): Promise<U>;
|
160 |
|
161 | /**
|
162 | * Returns a promise for the result of calling the named method of an object with the given variadic arguments.
|
163 | * The object itself is this in the function, just like a synchronous method call.
|
164 | */
|
165 | invoke<U>(methodName: string, ...args: any[]): Promise<U>;
|
166 |
|
167 | /**
|
168 | * Returns a promise for an array of the property names of an object. Essentially equivalent to
|
169 | *
|
170 | * @example
|
171 | * promise.then(function (o) { return Object.keys(o); });
|
172 | */
|
173 | keys(): Promise<string[]>;
|
174 |
|
175 | /**
|
176 | * Returns a promise for the result of calling a function, with the given array of arguments. Essentially equivalent to
|
177 | *
|
178 | * @example
|
179 | * promise.then(function (f) {
|
180 | * return f.apply(undefined, args);
|
181 | * });
|
182 | */
|
183 | fapply<U>(args: any[]): Promise<U>;
|
184 |
|
185 | /**
|
186 | * Returns a promise for the result of calling a function, with the given variadic arguments. Has the same return
|
187 | * value/thrown exception translation as explained above for fbind.
|
188 | * In its static form, it is aliased as Q.try, since it has semantics similar to a try block (but handling both
|
189 | * synchronous exceptions and asynchronous rejections). This allows code like
|
190 | *
|
191 | * @example
|
192 | * Q.try(function () {
|
193 | * if (!isConnectedToCloud()) {
|
194 | * throw new Error("The cloud is down!");
|
195 | * }
|
196 | * return syncToCloud();
|
197 | * })
|
198 | * .catch(function (error) {
|
199 | * console.error("Couldn't sync to the cloud", error);
|
200 | * });
|
201 | */
|
202 | fcall<U>(...args: any[]): Promise<U>;
|
203 |
|
204 | /**
|
205 | * A sugar method, equivalent to promise.then(function () { return value; }).
|
206 | */
|
207 | thenResolve<U>(value: U): Promise<U>;
|
208 |
|
209 | /**
|
210 | * A sugar method, equivalent to promise.then(function () { throw reason; }).
|
211 | */
|
212 | thenReject<U = T>(reason?: any): Promise<U>;
|
213 |
|
214 | /**
|
215 | * Attaches a handler that will observe the value of the promise when it becomes fulfilled, returning a promise for
|
216 | * that same value, perhaps deferred but not replaced by the promise returned by the onFulfilled handler.
|
217 | */
|
218 | tap(onFulfilled: (value: T) => any): Promise<T>;
|
219 |
|
220 | /**
|
221 | * Returns a promise that will have the same result as promise, except that if promise is not fulfilled or rejected
|
222 | * before ms milliseconds, the returned promise will be rejected with an Error with the given message. If message
|
223 | * is not supplied, the message will be "Timed out after " + ms + " ms".
|
224 | */
|
225 | timeout(ms: number, message?: string): Promise<T>;
|
226 |
|
227 | /**
|
228 | * Returns a promise that will have the same result as promise, but will only be fulfilled or rejected after at least
|
229 | * ms milliseconds have passed.
|
230 | */
|
231 | delay(ms: number): Promise<T>;
|
232 |
|
233 | /**
|
234 | * Returns whether a given promise is in the fulfilled state. When the static version is used on non-promises, the
|
235 | * result is always true.
|
236 | */
|
237 | isFulfilled(): boolean;
|
238 |
|
239 | /**
|
240 | * Returns whether a given promise is in the rejected state. When the static version is used on non-promises, the
|
241 | * result is always false.
|
242 | */
|
243 | isRejected(): boolean;
|
244 |
|
245 | /**
|
246 | * Returns whether a given promise is in the pending state. When the static version is used on non-promises, the
|
247 | * result is always false.
|
248 | */
|
249 | isPending(): boolean;
|
250 |
|
251 | valueOf(): any;
|
252 |
|
253 | /**
|
254 | * Returns a "state snapshot" object, which will be in one of three forms:
|
255 | *
|
256 | * - { state: "pending" }
|
257 | * - { state: "fulfilled", value: <fulfllment value> }
|
258 | * - { state: "rejected", reason: <rejection reason> }
|
259 | */
|
260 | inspect(): PromiseState<T>;
|
261 | }
|
262 |
|
263 | export interface PromiseState<T> {
|
264 | state: "fulfilled" | "rejected" | "pending";
|
265 | value?: T | undefined;
|
266 | reason?: any;
|
267 | }
|
268 |
|
269 | /**
|
270 | * Returns a "deferred" object with a:
|
271 | * promise property
|
272 | * resolve(value) method
|
273 | * reject(reason) method
|
274 | * notify(value) method
|
275 | * makeNodeResolver() method
|
276 | */
|
277 | export function defer<T>(): Deferred<T>;
|
278 |
|
279 | /**
|
280 | * Calling resolve with a pending promise causes promise to wait on the passed promise, becoming fulfilled with its
|
281 | * fulfillment value or rejected with its rejection reason (or staying pending forever, if the passed promise does).
|
282 | * Calling resolve with a rejected promise causes promise to be rejected with the passed promise's rejection reason.
|
283 | * Calling resolve with a fulfilled promise causes promise to be fulfilled with the passed promise's fulfillment value.
|
284 | * Calling resolve with a non-promise value causes promise to be fulfilled with that value.
|
285 | */
|
286 | export function resolve<T>(object?: IWhenable<T>): Promise<T>;
|
287 |
|
288 | /**
|
289 | * Returns a promise that is rejected with reason.
|
290 | */
|
291 | export function reject<T>(reason?: any): Promise<T>;
|
292 |
|
293 | // If no value provided, returned promise will be of void type
|
294 | export function when(): Promise<void>;
|
295 |
|
296 | // if no fulfill, reject, or progress provided, returned promise will be of same type
|
297 | export function when<T>(value: IWhenable<T>): Promise<T>;
|
298 |
|
299 | // If a non-promise value is provided, it will not reject or progress
|
300 | export function when<T, U>(
|
301 | value: IWhenable<T>,
|
302 | onFulfilled: (val: T) => IWhenable<U>,
|
303 | onRejected?: ((reason: any) => IWhenable<U>) | null,
|
304 | onProgress?: ((progress: any) => any) | null,
|
305 | ): Promise<U>;
|
306 |
|
307 | /**
|
308 | * (Deprecated) Returns a new function that calls a function asynchronously with the given variadic arguments, and returns a promise.
|
309 | * Notably, any synchronous return values or thrown exceptions are transformed, respectively, into fulfillment values
|
310 | * or rejection reasons for the promise returned by this new function.
|
311 | * This method is especially useful in its static form for wrapping functions to ensure that they are always
|
312 | * asynchronous, and that any thrown exceptions (intentional or accidental) are appropriately transformed into a
|
313 | * returned rejected promise. For example:
|
314 | *
|
315 | * @example
|
316 | * var getUserData = Q.fbind(function (userName) {
|
317 | * if (!userName) {
|
318 | * throw new Error("userName must be truthy!");
|
319 | * }
|
320 | * if (localCache.has(userName)) {
|
321 | * return localCache.get(userName);
|
322 | * }
|
323 | * return getUserFromCloud(userName);
|
324 | * });
|
325 | */
|
326 | export function fbind<T>(method: (...args: any[]) => IWhenable<T>, ...args: any[]): (...args: any[]) => Promise<T>;
|
327 |
|
328 | |
329 |
|
330 |
|
331 |
|
332 |
|
333 |
|
334 |
|
335 |
|
336 |
|
337 |
|
338 |
|
339 |
|
340 |
|
341 |
|
342 |
|
343 |
|
344 |
|
345 | export function fcall<T>(method: (...args: any[]) => T, ...args: any[]): Promise<T>;
|
346 |
|
347 |
|
348 | |
349 |
|
350 |
|
351 | export { fcall as try };
|
352 |
|
353 | |
354 |
|
355 |
|
356 |
|
357 | export function invoke<T>(obj: any, functionName: string, ...args: any[]): Promise<T>;
|
358 |
|
359 | |
360 |
|
361 |
|
362 | export function send<T>(obj: any, functionName: string, ...args: any[]): Promise<T>;
|
363 |
|
364 | |
365 |
|
366 |
|
367 | export function mcall<T>(obj: any, functionName: string, ...args: any[]): Promise<T>;
|
368 |
|
369 | |
370 |
|
371 |
|
372 |
|
373 |
|
374 |
|
375 |
|
376 |
|
377 |
|
378 |
|
379 |
|
380 |
|
381 |
|
382 |
|
383 |
|
384 |
|
385 |
|
386 |
|
387 |
|
388 | export function nfbind<T>(nodeFunction: (...args: any[]) => any, ...args: any[]): (...args: any[]) => Promise<T>;
|
389 |
|
390 | |
391 |
|
392 |
|
393 | export function denodeify<T>(nodeFunction: (...args: any[]) => any, ...args: any[]): (...args: any[]) => Promise<T>;
|
394 |
|
395 | |
396 |
|
397 |
|
398 |
|
399 |
|
400 |
|
401 |
|
402 |
|
403 |
|
404 |
|
405 |
|
406 | export function nbind<T>(
|
407 | nodeFunction: (...args: any[]) => any,
|
408 | thisArg: any,
|
409 | ...args: any[]
|
410 | ): (...args: any[]) => Promise<T>;
|
411 |
|
412 | |
413 |
|
414 |
|
415 |
|
416 |
|
417 |
|
418 |
|
419 |
|
420 |
|
421 |
|
422 |
|
423 |
|
424 |
|
425 |
|
426 |
|
427 |
|
428 |
|
429 |
|
430 |
|
431 | export function nfapply<T>(nodeFunction: (...args: any[]) => any, args: any[]): Promise<T>;
|
432 |
|
433 | |
434 |
|
435 |
|
436 |
|
437 |
|
438 |
|
439 |
|
440 |
|
441 |
|
442 |
|
443 |
|
444 |
|
445 | export function nfcall<T>(nodeFunction: (...args: any[]) => any, ...args: any[]): Promise<T>;
|
446 |
|
447 | |
448 |
|
449 |
|
450 |
|
451 |
|
452 |
|
453 |
|
454 |
|
455 | export function npost<T>(nodeModule: any, functionName: string, args: any[]): Promise<T>;
|
456 |
|
457 | |
458 |
|
459 |
|
460 |
|
461 |
|
462 |
|
463 |
|
464 |
|
465 | export function ninvoke<T>(nodeModule: any, functionName: string, ...args: any[]): Promise<T>;
|
466 |
|
467 | |
468 |
|
469 |
|
470 | export function nsend<T>(nodeModule: any, functionName: string, ...args: any[]): Promise<T>;
|
471 |
|
472 | |
473 |
|
474 |
|
475 | export function all<A, B, C, D, E, F>(
|
476 | promises: IWhenable<[IWhenable<A>, IWhenable<B>, IWhenable<C>, IWhenable<D>, IWhenable<E>, IWhenable<F>]>,
|
477 | ): Promise<[A, B, C, D, E, F]>;
|
478 | |
479 |
|
480 |
|
481 | export function all<A, B, C, D, E>(
|
482 | promises: IWhenable<[IWhenable<A>, IWhenable<B>, IWhenable<C>, IWhenable<D>, IWhenable<E>]>,
|
483 | ): Promise<[A, B, C, D, E]>;
|
484 | |
485 |
|
486 |
|
487 | export function all<A, B, C, D>(
|
488 | promises: IWhenable<[IWhenable<A>, IWhenable<B>, IWhenable<C>, IWhenable<D>]>,
|
489 | ): Promise<[A, B, C, D]>;
|
490 | |
491 |
|
492 |
|
493 | export function all<A, B, C>(promises: IWhenable<[IWhenable<A>, IWhenable<B>, IWhenable<C>]>): Promise<[A, B, C]>;
|
494 | |
495 |
|
496 |
|
497 | export function all<A, B>(promises: IWhenable<[IPromise<A>, IPromise<B>]>): Promise<[A, B]>;
|
498 | export function all<A, B>(promises: IWhenable<[A, IPromise<B>]>): Promise<[A, B]>;
|
499 | export function all<A, B>(promises: IWhenable<[IPromise<A>, B]>): Promise<[A, B]>;
|
500 | export function all<A, B>(promises: IWhenable<[A, B]>): Promise<[A, B]>;
|
501 | |
502 |
|
503 |
|
504 | export function all<T>(promises: IWhenable<Array<IWhenable<T>>>): Promise<T[]>;
|
505 |
|
506 | |
507 |
|
508 |
|
509 | export function race<T>(promises: Array<IWhenable<T>>): Promise<T>;
|
510 |
|
511 | |
512 |
|
513 |
|
514 |
|
515 | export function allSettled<T>(promises: IWhenable<Array<IWhenable<T>>>): Promise<Array<PromiseState<T>>>;
|
516 |
|
517 | |
518 |
|
519 |
|
520 | export function allResolved<T>(promises: IWhenable<Array<IWhenable<T>>>): Promise<Array<Promise<T>>>;
|
521 |
|
522 | |
523 |
|
524 |
|
525 |
|
526 |
|
527 | export function spread<T, U>(
|
528 | promises: Array<IWhenable<T>>,
|
529 | onFulfilled: (...args: T[]) => IWhenable<U>,
|
530 | onRejected?: (reason: any) => IWhenable<U>,
|
531 | ): Promise<U>;
|
532 |
|
533 | |
534 |
|
535 |
|
536 |
|
537 |
|
538 | export function timeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
|
539 |
|
540 | |
541 |
|
542 |
|
543 | export function delay<T>(promiseOrValue: Promise<T> | T, ms: number): Promise<T>;
|
544 | |
545 |
|
546 |
|
547 | export function delay(ms: number): Promise<void>;
|
548 |
|
549 | |
550 |
|
551 |
|
552 | export function isFulfilled(promise: Promise<any>): boolean;
|
553 |
|
554 | |
555 |
|
556 |
|
557 | export function isRejected(promise: Promise<any>): boolean;
|
558 |
|
559 | |
560 |
|
561 |
|
562 | export function isPending(promiseOrObject: Promise<any> | any): boolean;
|
563 |
|
564 | |
565 |
|
566 |
|
567 |
|
568 |
|
569 |
|
570 |
|
571 |
|
572 | export function Promise<T>(
|
573 | resolver: (
|
574 | resolve: (val?: IWhenable<T>) => void,
|
575 | reject: (reason?: any) => void,
|
576 | notify: (progress: any) => void,
|
577 | ) => void,
|
578 | ): Promise<T>;
|
579 |
|
580 | |
581 |
|
582 |
|
583 |
|
584 |
|
585 |
|
586 |
|
587 | export function promised<T>(callback: (...args: any[]) => T): (...args: any[]) => Promise<T>;
|
588 |
|
589 | |
590 |
|
591 |
|
592 | export function isPromise(object: any): object is Promise<any>;
|
593 |
|
594 | |
595 |
|
596 |
|
597 | export function isPromiseAlike(object: any): object is IPromise<any>;
|
598 |
|
599 | |
600 |
|
601 |
|
602 |
|
603 |
|
604 |
|
605 |
|
606 | export function nearer<T>(promise: Promise<T>): T;
|
607 |
|
608 | |
609 |
|
610 |
|
611 |
|
612 | export function async<T>(generatorFunction: any): (...args: any[]) => Promise<T>;
|
613 |
|
614 | export function nextTick(callback: (...args: any[]) => any): void;
|
615 |
|
616 | |
617 |
|
618 |
|
619 |
|
620 |
|
621 | export let onerror: (reason: any) => void;
|
622 | |
623 |
|
624 |
|
625 |
|
626 |
|
627 | export let longStackSupport: boolean;
|
628 |
|
629 | |
630 |
|
631 |
|
632 |
|
633 |
|
634 | export function noConflict(): typeof Q;
|
635 | }
|