| 1 | import { EventEmitter } from "../";
|
| 2 |
|
| 3 | /**
|
| 4 | * promise
|
| 5 | */
|
| 6 |
|
| 7 | export namespace promise {
|
| 8 | // region Functions
|
| 9 |
|
| 10 | /**
|
| 11 | * Determines whether a {@code value} should be treated as a promise.
|
| 12 | * Any object whose 'then' property is a function will be considered a
|
| 13 | * promise.
|
| 14 | */
|
| 15 | function isPromise(value: any): boolean;
|
| 16 |
|
| 17 | /**
|
| 18 | * Creates a promise that will be resolved at a set time in the future.
|
| 19 | */
|
| 20 | function delayed(ms: number): Promise<void>;
|
| 21 |
|
| 22 | /**
|
| 23 | * Calls a function for each element in an array, and if the function returns
|
| 24 | * true adds the element to a new array.
|
| 25 | *
|
| 26 | * If the return value of the filter function is a promise, this function
|
| 27 | * will wait for it to be fulfilled before determining whether to insert the
|
| 28 | * element into the new array.
|
| 29 | *
|
| 30 | * If the filter function throws or returns a rejected promise, the promise
|
| 31 | * returned by this function will be rejected with the same reason. Only the
|
| 32 | * first failure will be reported; all subsequent errors will be silently
|
| 33 | * ignored.
|
| 34 | */
|
| 35 | function filter<T, V>(
|
| 36 | arr: T[] | Promise<T[]>,
|
| 37 | fn: (element: T, index: number, array: T[]) => V,
|
| 38 | // value
|
| 39 | optSelf?: any,
|
| 40 | ): Promise<V[]>;
|
| 41 |
|
| 42 | /**
|
| 43 | * Calls a function for each element in an array and inserts the result into a
|
| 44 | * new array, which is used as the fulfillment value of the promise returned
|
| 45 | * by this function.
|
| 46 | *
|
| 47 | * If the return value of the mapping function is a promise, this function
|
| 48 | * will wait for it to be fulfilled before inserting it into the new array.
|
| 49 | *
|
| 50 | * If the mapping function throws or returns a rejected promise, the
|
| 51 | * promise returned by this function will be rejected with the same reason.
|
| 52 | * Only the first failure will be reported; all subsequent errors will be
|
| 53 | * silently ignored.
|
| 54 | */
|
| 55 | function map<T, V>(
|
| 56 | arr: T[] | Promise<T[]>,
|
| 57 | fn: (self: any, type: T, index: number, array: T[]) => V,
|
| 58 | optSelf?: any,
|
| 59 | ): Promise<V[]>;
|
| 60 |
|
| 61 | /**
|
| 62 | * Wraps a function that expects a node-style callback as its final
|
| 63 | * argument. This callback expects two arguments: an error value (which will
|
| 64 | * be null if the call succeeded), and the success value as the second
|
| 65 | * argument. The callback will the resolve or reject the returned promise,
|
| 66 | * based on its arguments.
|
| 67 | */
|
| 68 | function checkedNodeCall<T>(fn: Function, ...varArgs: any[]): Promise<T>;
|
| 69 |
|
| 70 | /**
|
| 71 | * Returns a promise that will be resolved with the input value in a
|
| 72 | * fully-resolved state. If the value is an array, each element will be fully
|
| 73 | * resolved. Likewise, if the value is an object, all keys will be fully
|
| 74 | * resolved. In both cases, all nested arrays and objects will also be
|
| 75 | * fully resolved. All fields are resolved in place; the returned promise
|
| 76 | * will resolve on {@code value} and not a copy.
|
| 77 | *
|
| 78 | * Warning: This function makes no checks against objects that contain
|
| 79 | * cyclical references:
|
| 80 | *
|
| 81 | * var value = {};
|
| 82 | * value['self'] = value;
|
| 83 | * promise.fullyResolved(value); // Stack overflow.
|
| 84 | */
|
| 85 | function fullyResolved(value: any): Promise<any>;
|
| 86 |
|
| 87 | /**
|
| 88 | * Registers a listener to invoke when a promise is resolved, regardless
|
| 89 | * of whether the promise's value was successfully computed. This function
|
| 90 | * is synonymous with the {@code finally} clause in a synchronous API:
|
| 91 | *
|
| 92 | * // Synchronous API:
|
| 93 | * try {
|
| 94 | * doSynchronousWork();
|
| 95 | * } finally {
|
| 96 | * cleanUp();
|
| 97 | * }
|
| 98 | *
|
| 99 | * // Asynchronous promise API:
|
| 100 | * doAsynchronousWork().finally(cleanUp);
|
| 101 | *
|
| 102 | * __Note:__ similar to the {@code finally} clause, if the registered
|
| 103 | * callback returns a rejected promise or throws an error, it will silently
|
| 104 | * replace the rejection error (if any) from this promise:
|
| 105 | *
|
| 106 | * try {
|
| 107 | * throw Error('one');
|
| 108 | * } finally {
|
| 109 | * throw Error('two'); // Hides Error: one
|
| 110 | * }
|
| 111 | *
|
| 112 | * let p = Promise.reject(Error('one'));
|
| 113 | * promise.finally(p, function() {
|
| 114 | * throw Error('two'); // Hides Error: one
|
| 115 | * });
|
| 116 | */
|
| 117 | function thenFinally<R>(promise: any, callback: () => R | Promise<R>): Promise<R>;
|
| 118 |
|
| 119 | // endregion
|
| 120 | }
|