diff --git a/bluebird/bluebird-tests.ts b/bluebird/bluebird-tests.ts index e5d83db7a..abead4237 100644 --- a/bluebird/bluebird-tests.ts +++ b/bluebird/bluebird-tests.ts @@ -149,17 +149,17 @@ barThen = barProm; // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - fooProm = new Promise((resolve: (value: Foo) => void, reject: (reason: any) => void) => { - if (bool) { - resolve(foo); - } - else { - reject(new Error(str)); - } + if (bool) { + resolve(foo); + } + else { + reject(new Error(str)); + } }); fooProm = new Promise((resolve: (value: Foo) => void) => { - if (bool) { - resolve(foo); - } + if (bool) { + resolve(foo); + } }); // - - - - - - - - - - - - - - - - - - - - - - - @@ -181,11 +181,11 @@ fooProm = new Promise((resolve) => { fooResolver.resolve(foo); -fooResolver.reject(foo); +fooResolver.reject(err); -fooResolver.progress(foo); +fooResolver.progress(bar); -fooResolver.callback = () => { +fooResolver.callback = (err: any, value: Foo) => { }; @@ -204,9 +204,9 @@ x = fooInspection.error(); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - barProm = fooProm.then((value: Foo) => { - return bar; + return bar; }, (reason: any) => { - return bar; + return bar; }, (note: any) => { return bar; }); @@ -216,42 +216,42 @@ barProm = fooProm.then((value: Foo) => { return bar; }); barProm = fooProm.then((value: Foo) => { - return bar; + return bar; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - barProm = fooProm.catch((reason: any) => { - return bar; + return bar; }); barProm = fooProm.caught((reason: any) => { - return bar; + return bar; }); barProm = fooProm.catch((reason: any) => { - return bar; + return bar; }, (reason: any) => { - return bar; + return bar; }); barProm = fooProm.caught((reason: any) => { - return bar; + return bar; }, (reason: any) => { - return bar; + return bar; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - barProm = fooProm.catch(Error, (reason: any) => { - return bar; + return bar; }); barProm = fooProm.caught(Error, (reason: any) => { - return bar; + return bar; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - barProm = fooProm.error((reason: any) => { - return bar; + return bar; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -295,43 +295,43 @@ fooProm = fooProm.bind(obj); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - barProm = fooProm.done((value: Foo) => { - return bar; + return bar; }, (reason: any) => { - return bar; + return bar; }, (note: any) => { }); barProm = fooProm.done((value: Foo) => { - return bar; + return bar; }, (reason: any) => { - return bar; + return bar; }); barProm = fooProm.done((value: Foo) => { - return bar; + return bar; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - barProm = fooProm.done((value: Foo) => { - return barThen; + return barThen; }, (reason: any) => { - return barThen; + return barThen; }, (note: any) => { }); barProm = fooProm.done((value: Foo) => { - return barThen; + return barThen; }, (reason: any) => { - return barThen; + return barThen; }); barProm = fooProm.done((value: Foo) => { - return barThen; + return barThen; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - fooProm = fooProm.progressed((note: any) => { - return foo; + return foo; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -355,37 +355,37 @@ fooProm = fooProm.nodeify((err: any, foo?: Foo) => { // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - barProm = fooProm.fork((value: Foo) => { - return bar; + return bar; }, (reason: any) => { - return bar; + return bar; }, (note: any) => { }); barProm = fooProm.fork((value: Foo) => { - return bar; + return bar; }, (reason: any) => { - return bar; + return bar; }); barProm = fooProm.fork((value: Foo) => { - return bar; + return bar; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - barProm = fooProm.fork((value: Foo) => { - return barThen; + return barThen; }, (reason: any) => { - return barThen; + return barThen; }, (note: any) => { }); barProm = fooProm.fork((value: Foo) => { - return barThen; + return barThen; }, (reason: any) => { - return barThen; + return barThen; }); barProm = fooProm.fork((value: Foo) => { - return barThen; + return barThen; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -438,23 +438,23 @@ obj = fooProm.toJSON(); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - barProm = fooArrProm.spread((one: Foo, two: Bar) => { - return bar; + return bar; }, (reason: any) => { - return bar; + return bar; }); barProm = fooArrProm.spread((one: Foo, two: Bar, twotwo: Foo) => { - return bar; + return bar; }); // - - - - - - - - - - - - - - - - - barProm = fooArrProm.spread((one: Foo, two: Bar) => { - return barThen; + return barThen; }, (reason: any) => { - return barThen; + return barThen; }); barProm = fooArrProm.spread((one: Foo, two: Bar, twotwo: Foo) => { - return barThen; + return barThen; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -504,8 +504,7 @@ fooProm = fooProm.filter((item: Foo) => { // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -///TODO enable try tests -/* + fooProm = Promise.try(() => { return foo; }); @@ -527,7 +526,7 @@ fooProm = Promise.try(() => { fooProm = Promise.try(() => { return fooThen; }, arr, x); -*/ + // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - fooProm = Promise.attempt(() => { @@ -707,16 +706,16 @@ barArrProm = Promise.map(fooArrThen, (item: Foo, index: number, arrayLength: num // fooThenArr barArrProm = Promise.map(fooThenArr, (item: Foo) => { - return bar; + return bar; }); barArrProm = Promise.map(fooThenArr, (item: Foo) => { - return barThen; + return barThen; }); barArrProm = Promise.map(fooThenArr, (item: Foo, index: number, arrayLength: number) => { - return bar; + return bar; }); barArrProm = Promise.map(fooThenArr, (item: Foo, index: number, arrayLength: number) => { - return barThen; + return barThen; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -724,16 +723,16 @@ barArrProm = Promise.map(fooThenArr, (item: Foo, index: number, arrayLength: num // fooArr barArrProm = Promise.map(fooArr, (item: Foo) => { - return bar; + return bar; }); barArrProm = Promise.map(fooArr, (item: Foo) => { - return barThen; + return barThen; }); barArrProm = Promise.map(fooArr, (item: Foo, index: number, arrayLength: number) => { - return bar; + return bar; }); barArrProm = Promise.map(fooArr, (item: Foo, index: number, arrayLength: number) => { - return barThen; + return barThen; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -779,16 +778,16 @@ barProm = Promise.reduce(fooArrThen, (memo: Bar, item: Foo, index: number, array // fooThenArr barProm = Promise.reduce(fooThenArr, (memo: Bar, item: Foo) => { - return memo; + return memo; }, bar); barProm = Promise.reduce(fooThenArr, (memo: Bar, item: Foo) => { - return barThen; + return barThen; }, bar); barProm = Promise.reduce(fooThenArr, (memo: Bar, item: Foo, index: number, arrayLength: number) => { - return memo; + return memo; }, bar); barProm = Promise.reduce(fooThenArr, (memo: Bar, item: Foo, index: number, arrayLength: number) => { - return barThen; + return barThen; }, bar); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -796,7 +795,7 @@ barProm = Promise.reduce(fooThenArr, (memo: Bar, item: Foo, index: number, array // fooArr barProm = Promise.reduce(fooArr, (memo: Bar, item: Foo) => { - return memo; + return memo; }, bar); barProm = Promise.reduce(fooArr, (memo: Bar, item: Foo) => { return barThen; @@ -851,16 +850,16 @@ fooArrProm = Promise.filter(fooArrThen, (item: Foo, index: number, arrayLength: // fooThenArr fooArrProm = Promise.filter(fooThenArr, (item: Foo) => { - return bool; + return bool; }); fooArrProm = Promise.filter(fooThenArr, (item: Foo) => { - return boolThen; + return boolThen; }); fooArrProm = Promise.filter(fooThenArr, (item: Foo, index: number, arrayLength: number) => { - return bool; + return bool; }); fooArrProm = Promise.filter(fooThenArr, (item: Foo, index: number, arrayLength: number) => { - return boolThen; + return boolThen; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -868,16 +867,16 @@ fooArrProm = Promise.filter(fooThenArr, (item: Foo, index: number, arrayLength: // fooArr fooArrProm = Promise.filter(fooArr, (item: Foo) => { - return bool; + return bool; }); fooArrProm = Promise.filter(fooArr, (item: Foo) => { - return boolThen; + return boolThen; }); fooArrProm = Promise.filter(fooArr, (item: Foo, index: number, arrayLength: number) => { - return bool; + return bool; }); fooArrProm = Promise.filter(fooArr, (item: Foo, index: number, arrayLength: number) => { - return boolThen; + return boolThen; }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/bluebird/bluebird.d.ts b/bluebird/bluebird.d.ts index 0d57e49b0..8912ebb88 100644 --- a/bluebird/bluebird.d.ts +++ b/bluebird/bluebird.d.ts @@ -213,10 +213,10 @@ declare class Promise implements Promise.Thenable { * * Alias `.thenReturn();` for compatibility with earlier ECMAScript version. */ + return(): Promise; + thenReturn(): Promise; return(value: U): Promise; thenReturn(value: U): Promise; - return(): Promise; - thenReturn(): Promise; /** * Convenience method for: @@ -250,12 +250,12 @@ declare class Promise implements Promise.Thenable { spread(onFulfill: Function, onReject?: (reason: any) => Promise.Thenable): Promise; spread(onFulfill: Function, onReject?: (reason: any) => U): Promise; /* - // TODO or something like this? - spread(onFulfill: (...values: W[]) => Promise.Thenable, onReject?: (reason: any) => Promise.Thenable): Promise; - spread(onFulfill: (...values: W[]) => Promise.Thenable, onReject?: (reason: any) => U): Promise; - spread(onFulfill: (...values: W[]) => U, onReject?: (reason: any) => Promise.Thenable): Promise; - spread(onFulfill: (...values: W[]) => U, onReject?: (reason: any) => U): Promise; - */ + // TODO or something like this? + spread(onFulfill: (...values: W[]) => Promise.Thenable, onReject?: (reason: any) => Promise.Thenable): Promise; + spread(onFulfill: (...values: W[]) => Promise.Thenable, onReject?: (reason: any) => U): Promise; + spread(onFulfill: (...values: W[]) => U, onReject?: (reason: any) => Promise.Thenable): Promise; + spread(onFulfill: (...values: W[]) => U, onReject?: (reason: any) => U): Promise; + */ /** * Same as calling `Promise.all(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. */ @@ -312,9 +312,288 @@ declare class Promise implements Promise.Thenable { // TODO type inference from array-resolving promise? filter(filterer: (item: U, index: number, arrayLength: number) => Promise.Thenable): Promise; filter(filterer: (item: U, index: number, arrayLength: number) => boolean): Promise; + + /** + * Start the chain of promises with `Promise.try`. Any synchronous exceptions will be turned into rejections on the returned promise. + * + * Note about second argument: if it's specifically a true array, its values become respective arguments for the function call. Otherwise it is passed as is as the first argument for the function call. + * + * Alias for `attempt();` for compatibility with earlier ECMAScript version. + */ + static try(fn: () => Promise.Thenable, args?: any[], ctx?: any): Promise; + static try(fn: () => R, args?: any[], ctx?: any): Promise; + + static attempt(fn: () => Promise.Thenable, args?: any[], ctx?: any): Promise; + static attempt(fn: () => R, args?: any[], ctx?: any): Promise; + + /** + * Returns a new function that wraps the given function `fn`. The new function will always return a promise that is fulfilled with the original functions return values or rejected with thrown exceptions from the original function. + * This method is convenient when a function can sometimes return synchronously or throw synchronously. + */ + static method(fn: Function): Function; + + /** + * Create a promise that is resolved with the given `value`. If `value` is a thenable or promise, the returned promise will assume its state. + */ + static resolve(): Promise; + static resolve(value: Promise.Thenable): Promise; + static resolve(value: R): Promise; + + /** + * Create a promise that is rejected with the given `reason`. + */ + static reject(reason: any): Promise; + static reject(reason: any): Promise; + + /** + * Create a promise with undecided fate and return a `PromiseResolver` to control it. See resolution?: Promise(#promise-resolution). + */ + static defer(): Promise.Resolver; + + /** + * Cast the given `value` to a trusted promise. If `value` is already a trusted `Promise`, it is returned as is. If `value` is not a thenable, a fulfilled is: Promise returned with `value` as its fulfillment value. If `value` is a thenable (Promise-like object, like those returned by jQuery's `$.ajax`), returns a trusted that: Promise assimilates the state of the thenable. + */ + static cast(value: Promise.Thenable): Promise; + static cast(value: R): Promise; + + /** + * Sugar for `Promise.resolve(undefined).bind(thisArg);`. See `.bind()`. + */ + static bind(thisArg: any): Promise; + + /** + * See if `value` is a trusted Promise. + */ + static is(value: any): boolean; + + /** + * Call this right after the library is loaded to enabled long stack traces. Long stack traces cannot be disabled after being enabled, and cannot be enabled after promises have alread been created. Long stack traces imply a substantial performance penalty, around 4-5x for throughput and 0.5x for latency. + */ + static longStackTraces(): void; + + /** + * Returns a promise that will be fulfilled with `value` (or `undefined`) after given `ms` milliseconds. If `value` is a promise, the delay will start counting down when it is fulfilled and the returned promise will be fulfilled with the fulfillment value of the `value` promise. + */ + // TODO enable more overloads + static delay(value: Promise.Thenable, ms: number): Promise; + static delay(value: R, ms: number): Promise; + static delay(ms: number): Promise; + + /** + * Returns a function that will wrap the given `nodeFunction`. Instead of taking a callback, the returned function will return a promise whose fate is decided by the callback behavior of the given node function. The node function should conform to node.js convention of accepting a callback as last argument and calling that callback with error as the first argument and success value on the second argument. + * + * If the `nodeFunction` calls its callback with multiple success values, the fulfillment value will be an array of them. + * + * If you pass a `receiver`, the `nodeFunction` will be called as a method on the `receiver`. + */ + // TODO how to model promisify? + static promisify(nodeFunction: Function, receiver?: any): Function; + + /** + * Promisifies the entire object by going through the object's properties and creating an async equivalent of each function on the object and its prototype chain. The promisified method name will be the original method name postfixed with `Async`. Returns the input object. + * + * Note that the original methods on the object are not overwritten but new methods are created with the `Async`-postfix. For example, if you `promisifyAll()` the node.js `fs` object use `fs.statAsync()` to call the promisified `stat` method. + */ + // TODO how to model promisifyAll? + static promisifyAll(target: Object): Object; + + /** + * Returns a function that can use `yield` to run asynchronous code synchronously. This feature requires the support of generators which are drafted in the next version of the language. Node version greater than `0.11.2` is required and needs to be executed with the `--harmony-generators` (or `--harmony`) command-line switch. + */ + // TODO fix coroutine GeneratorFunction + static coroutine(generatorFunction: Function): Function; + + /** + * Spawn a coroutine which may yield promises to run asynchronous code synchronously. This feature requires the support of generators which are drafted in the next version of the language. Node version greater than `0.11.2` is required and needs to be executed with the `--harmony-generators` (or `--harmony`) command-line switch. + */ + // TODO fix spawn GeneratorFunction + static spawn(generatorFunction: Function): Promise; + + /** + * This is relevant to browser environments with no module loader. + * + * Release control of the `Promise` namespace to whatever it was before this library was loaded. Returns a reference to the library namespace so you can attach it to something else. + */ + static noConflict(): typeof Promise; + + /** + * Add `handler` as the handler to call when there is a possibly unhandled rejection. The default handler logs the error stack to stderr or `console.error` in browsers. + * + * Passing no value or a non-function will have the effect of removing any kind of handling for possibly unhandled rejections. + */ + static onPossiblyUnhandledRejection(handler: (reason: any) => any): void; + + /** + * Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled when all the items in the array are fulfilled. The promise's fulfillment value is an array with fulfillment values at respective positions to the original array. If any promise in the array rejects, the returned promise is rejected with the rejection reason. + */ + // TODO enable more overloads + // promise of array with promises of value + static all(values: Promise.Thenable[]>): Promise; + // promise of array with values + static all(values: Promise.Thenable): Promise; + // array with promises of value + static all(values: Promise.Thenable[]): Promise; + // array with values + static all(values: R[]): Promise; + + /** + * Like ``Promise.all`` but for object properties instead of array items. Returns a promise that is fulfilled when all the properties of the object are fulfilled. The promise's fulfillment value is an object with fulfillment values at respective keys to the original object. If any promise in the object rejects, the returned promise is rejected with the rejection reason. + * + * If `object` is a trusted `Promise`, then it will be treated as a promise for object rather than for its properties. All other objects are treated for their properties as is returned by `Object.keys` - the object's own enumerable properties. + * + * *The original object is not modified.* + */ + // TODO verify this is correct + // trusted promise for object + static props(object: Promise): Promise; + // object + static props(object: Object): Promise; + + /** + * Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled when all the items in the array are either fulfilled or rejected. The fulfillment value is an array of ``PromiseInspection`` instances at respective positions in relation to the input array. + * + * *original: The array is not modified. The input array sparsity is retained in the resulting array.* + */ + // promise of array with promises of value + static settle(values: Promise.Thenable[]>): Promise[]>; + // promise of array with values + static settle(values: Promise.Thenable): Promise[]>; + // array with promises of value + static settle(values: Promise.Thenable[]): Promise[]>; + // array with values + static settle(values: R[]): Promise[]>; + + /** + * Like `Promise.some()`, with 1 as `count`. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly. + */ + // promise of array with promises of value + static any(values: Promise.Thenable[]>): Promise; + // promise of array with values + static any(values: Promise.Thenable): Promise; + // array with promises of value + static any(values: Promise.Thenable[]): Promise; + // array with values + static any(values: R[]): Promise; + + /** + * Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled or rejected as soon as a promise in the array is fulfilled or rejected with the respective rejection reason or fulfillment value. + * + * **Note** If you pass empty array or a sparse array with no values, or a promise/thenable for such, it will be forever pending. + */ + // promise of array with promises of value + static race(values: Promise.Thenable[]>): Promise; + // promise of array with values + static race(values: Promise.Thenable): Promise; + // array with promises of value + static race(values: Promise.Thenable[]): Promise; + // array with values + static race(values: R[]): Promise; + + /** + * Initiate a competetive race between multiple promises or values (values will become immediately fulfilled promises). When `count` amount of promises have been fulfilled, the returned promise is fulfilled with an array that contains the fulfillment values of the winners in order of resolution. + * + * If too many promises are rejected so that the promise can never become fulfilled, it will be immediately rejected with an array of rejection reasons in the order they were thrown in. + * + * *The original array is not modified.* + */ + // promise of array with promises of value + static some(values: Promise.Thenable[]>, count: number): Promise; + // promise of array with values + static some(values: Promise.Thenable, count: number): Promise; + // array with promises of value + static some(values: Promise.Thenable[], count: number): Promise; + // array with values + static some(values: R[], count: number): Promise; + + /** + * Like `Promise.all()` but instead of having to pass an array, the array is generated from the passed variadic arguments. + */ + // variadic array with promises of value + static join(...values: Promise.Thenable[]): Promise; + // variadic array with values + static join(...values: R[]): Promise; + + /** + * Map an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given `mapper` function with the signature `(item, index, arrayLength)` where `item` is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well. + * + * If the `mapper` function returns promises or thenables, the returned promise will wait for all the mapped results to be resolved as well. + * + * *The original array is not modified.* + */ + // promise of array with promises of value + static map(values: Promise.Thenable[]>, mapper: (item: R, index: number, arrayLength: number) => Promise.Thenable): Promise; + static map(values: Promise.Thenable[]>, mapper: (item: R, index: number, arrayLength: number) => U): Promise; + + // promise of array with values + static map(values: Promise.Thenable, mapper: (item: R, index: number, arrayLength: number) => Promise.Thenable): Promise; + static map(values: Promise.Thenable, mapper: (item: R, index: number, arrayLength: number) => U): Promise; + + // array with promises of value + static map(values: Promise.Thenable[], mapper: (item: R, index: number, arrayLength: number) => Promise.Thenable): Promise; + static map(values: Promise.Thenable[], mapper: (item: R, index: number, arrayLength: number) => U): Promise; + + // array with values + static map(values: R[], mapper: (item: R, index: number, arrayLength: number) => Promise.Thenable): Promise; + static map(values: R[], mapper: (item: R, index: number, arrayLength: number) => U): Promise; + + /** + * Reduce an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given `reducer` function with the signature `(total, current, index, arrayLength)` where `item` is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well. + * + * If the reducer function returns a promise or a thenable, the result for the promise is awaited for before continuing with next iteration. + * + * *The original array is not modified. If no `intialValue` is given and the array doesn't contain at least 2 items, the callback will not be called and `undefined` is returned. If `initialValue` is given and the array doesn't have at least 1 item, `initialValue` is returned.* + */ + // promise of array with promises of value + static reduce(values: Promise.Thenable[]>, reducer: (total: U, current: R, index: number, arrayLength: number) => Promise.Thenable, initialValue?: U): Promise; + static reduce(values: Promise.Thenable[]>, reducer: (total: U, current: R, index: number, arrayLength: number) => U, initialValue?: U): Promise; + + // promise of array with values + static reduce(values: Promise.Thenable, reducer: (total: U, current: R, index: number, arrayLength: number) => Promise.Thenable, initialValue?: U): Promise; + static reduce(values: Promise.Thenable, reducer: (total: U, current: R, index: number, arrayLength: number) => U, initialValue?: U): Promise; + + // array with promises of value + static reduce(values: Promise.Thenable[], reducer: (total: U, current: R, index: number, arrayLength: number) => Promise.Thenable, initialValue?: U): Promise; + static reduce(values: Promise.Thenable[], reducer: (total: U, current: R, index: number, arrayLength: number) => U, initialValue?: U): Promise; + + // array with values + static reduce(values: R[], reducer: (total: U, current: R, index: number, arrayLength: number) => Promise.Thenable, initialValue?: U): Promise; + static reduce(values: R[], reducer: (total: U, current: R, index: number, arrayLength: number) => U, initialValue?: U): Promise; + + /** + * Filter an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given `filterer` function with the signature `(item, index, arrayLength)` where `item` is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well. + * + * The return values from the filtered functions are coerced to booleans, with the exception of promises and thenables which are awaited for their eventual result. + * + * *The original array is not modified. + */ + // promise of array with promises of value + static filter(values: Promise.Thenable[]>, filterer: (item: R, index: number, arrayLength: number) => Promise.Thenable): Promise; + static filter(values: Promise.Thenable[]>, filterer: (item: R, index: number, arrayLength: number) => boolean): Promise; + + // promise of array with values + static filter(values: Promise.Thenable, filterer: (item: R, index: number, arrayLength: number) => Promise.Thenable): Promise; + static filter(values: Promise.Thenable, filterer: (item: R, index: number, arrayLength: number) => boolean): Promise; + + // array with promises of value + static filter(values: Promise.Thenable[], filterer: (item: R, index: number, arrayLength: number) => Promise.Thenable): Promise; + static filter(values: Promise.Thenable[], filterer: (item: R, index: number, arrayLength: number) => boolean): Promise; + + // array with values + static filter(values: R[], filterer: (item: R, index: number, arrayLength: number) => Promise.Thenable): Promise; + static filter(values: R[], filterer: (item: R, index: number, arrayLength: number) => boolean): Promise; } declare module Promise { + export interface RangeError extends Error { + } + export interface CancellationError extends Error { + } + export interface TimeoutError extends Error { + } + export interface TypeError extends Error { + } + export interface RejectionError extends Error { + } export interface Thenable { then(onFulfilled: (value: R) => Thenable, onRejected: (error: any) => Thenable): Thenable; @@ -324,10 +603,16 @@ declare module Promise { } export interface Resolver { + /** + * Returns a reference to the controlled promise that can be passed to clients. + */ + promise: Promise; + /** * Resolve the underlying promise with `value` as the resolution value. If `value` is a thenable or a promise, the underlying promise will assume its state. */ resolve(value: R): void; + resolve(): void; /** * Reject the underlying promise with `reason` as the rejection reason. @@ -345,7 +630,7 @@ declare module Promise { * If the the callback is called with multiple success values, the resolver fullfills its promise with an array of the values. */ // TODO specify resolver callback - callback: Function; + callback: (err: any, value: R, ...values: R[]) => void; } export interface Inspection { @@ -378,277 +663,6 @@ declare module Promise { */ error(): any; } - - /** - * Start the chain of promises with `Promise.try`. Any synchronous exceptions will be turned into rejections on the returned promise. - * - * Note about second argument: if it's specifically a true array, its values become respective arguments for the function call. Otherwise it is passed as is as the first argument for the function call. - * - * Alias for `attempt();` for compatibility with earlier ECMAScript version. - */ - // TODO find way to enable try() without tsc borking - // see also: https://typescript.codeplex.com/workitem/2194 - /* - export function try(fn: () => Promise.Thenable, args?: any[], ctx?: any): Promise; - export function try(fn: () => R, args?: any[], ctx?: any): Promise; - */ - - export function attempt(fn: () => Promise.Thenable, args?: any[], ctx?: any): Promise; - export function attempt(fn: () => R, args?: any[], ctx?: any): Promise; - - /** - * Returns a new function that wraps the given function `fn`. The new function will always return a promise that is fulfilled with the original functions return values or rejected with thrown exceptions from the original function. - * This method is convenient when a function can sometimes return synchronously or throw synchronously. - */ - export function method(fn: Function): Function; - - /** - * Create a promise that is resolved with the given `value`. If `value` is a thenable or promise, the returned promise will assume its state. - */ - export function resolve(value: Promise.Thenable): Promise; - export function resolve(value: R): Promise; - - /** - * Create a promise that is rejected with the given `reason`. - */ - export function reject(reason: any): Promise; - - /** - * Create a promise with undecided fate and return a `PromiseResolver` to control it. See resolution?: Promise(#promise-resolution). - */ - export function defer(): Promise.Resolver; - - /** - * Cast the given `value` to a trusted promise. If `value` is already a trusted `Promise`, it is returned as is. If `value` is not a thenable, a fulfilled is: Promise returned with `value` as its fulfillment value. If `value` is a thenable (Promise-like object, like those returned by jQuery's `$.ajax`), returns a trusted that: Promise assimilates the state of the thenable. - */ - export function cast(value: Promise.Thenable): Promise; - export function cast(value: R): Promise; - - /** - * Sugar for `Promise.resolve(undefined).bind(thisArg);`. See `.bind()`. - */ - export function bind(thisArg: any): Promise; - - /** - * See if `value` is a trusted Promise. - */ - export function is(value: any): boolean; - - /** - * Call this right after the library is loaded to enabled long stack traces. Long stack traces cannot be disabled after being enabled, and cannot be enabled after promises have alread been created. Long stack traces imply a substantial performance penalty, around 4-5x for throughput and 0.5x for latency. - */ - export function longStackTraces(): void; - - /** - * Returns a promise that will be fulfilled with `value` (or `undefined`) after given `ms` milliseconds. If `value` is a promise, the delay will start counting down when it is fulfilled and the returned promise will be fulfilled with the fulfillment value of the `value` promise. - */ - // TODO enable more overloads - export function delay(value: Promise.Thenable, ms: number): Promise; - export function delay(value: R, ms: number): Promise; - export function delay(ms: number): Promise; - - /** - * Returns a function that will wrap the given `nodeFunction`. Instead of taking a callback, the returned function will return a promise whose fate is decided by the callback behavior of the given node function. The node function should conform to node.js convention of accepting a callback as last argument and calling that callback with error as the first argument and success value on the second argument. - * - * If the `nodeFunction` calls its callback with multiple success values, the fulfillment value will be an array of them. - * - * If you pass a `receiver`, the `nodeFunction` will be called as a method on the `receiver`. - */ - // TODO how to model promisify? - export function promisify(nodeFunction: Function, receiver?: any): Function; - - /** - * Promisifies the entire object by going through the object's properties and creating an async equivalent of each function on the object and its prototype chain. The promisified method name will be the original method name postfixed with `Async`. Returns the input object. - * - * Note that the original methods on the object are not overwritten but new methods are created with the `Async`-postfix. For example, if you `promisifyAll()` the node.js `fs` object use `fs.statAsync()` to call the promisified `stat` method. - */ - // TODO how to model promisifyAll? - export function promisifyAll(target: Object): Object; - - /** - * Returns a function that can use `yield` to run asynchronous code synchronously. This feature requires the support of generators which are drafted in the next version of the language. Node version greater than `0.11.2` is required and needs to be executed with the `--harmony-generators` (or `--harmony`) command-line switch. - */ - // TODO fix coroutine GeneratorFunction - export function coroutine(generatorFunction: Function): Function; - - /** - * Spawn a coroutine which may yield promises to run asynchronous code synchronously. This feature requires the support of generators which are drafted in the next version of the language. Node version greater than `0.11.2` is required and needs to be executed with the `--harmony-generators` (or `--harmony`) command-line switch. - */ - // TODO fix spawn GeneratorFunction - export function spawn(generatorFunction: Function): Promise; - - /** - * This is relevant to browser environments with no module loader. - * - * Release control of the `Promise` namespace to whatever it was before this library was loaded. Returns a reference to the library namespace so you can attach it to something else. - */ - export function noConflict(): typeof Promise; - - /** - * Add `handler` as the handler to call when there is a possibly unhandled rejection. The default handler logs the error stack to stderr or `console.error` in browsers. - * - * Passing no value or a non-function will have the effect of removing any kind of handling for possibly unhandled rejections. - */ - export function onPossiblyUnhandledRejection(handler: (reason: any) => any): void; - - /** - * Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled when all the items in the array are fulfilled. The promise's fulfillment value is an array with fulfillment values at respective positions to the original array. If any promise in the array rejects, the returned promise is rejected with the rejection reason. - */ - // TODO enable more overloads - // promise of array with promises of value - export function all(values: Thenable[]>): Promise; - // promise of array with values - export function all(values: Thenable): Promise; - // array with promises of value - export function all(values: Thenable[]): Promise; - // array with values - export function all(values: R[]): Promise; - - /** - * Like ``Promise.all`` but for object properties instead of array items. Returns a promise that is fulfilled when all the properties of the object are fulfilled. The promise's fulfillment value is an object with fulfillment values at respective keys to the original object. If any promise in the object rejects, the returned promise is rejected with the rejection reason. - * - * If `object` is a trusted `Promise`, then it will be treated as a promise for object rather than for its properties. All other objects are treated for their properties as is returned by `Object.keys` - the object's own enumerable properties. - * - * *The original object is not modified.* - */ - // TODO verify this is correct - // trusted promise for object - export function props(object: Promise): Promise; - // object - export function props(object: Object): Promise; - - /** - * Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled when all the items in the array are either fulfilled or rejected. The fulfillment value is an array of ``PromiseInspection`` instances at respective positions in relation to the input array. - * - * *original: The array is not modified. The input array sparsity is retained in the resulting array.* - */ - // promise of array with promises of value - export function settle(values: Thenable[]>): Promise[]>; - // promise of array with values - export function settle(values: Thenable): Promise[]>; - // array with promises of value - export function settle(values: Thenable[]): Promise[]>; - // array with values - export function settle(values: R[]): Promise[]>; - - /** - * Like `Promise.some()`, with 1 as `count`. However, if the promise fulfills, the fulfillment value is not an array of 1 but the value directly. - */ - // promise of array with promises of value - export function any(values: Thenable[]>): Promise; - // promise of array with values - export function any(values: Thenable): Promise; - // array with promises of value - export function any(values: Thenable[]): Promise; - // array with values - export function any(values: R[]): Promise; - - /** - * Given an array, or a promise of an array, which contains promises (or a mix of promises and values) return a promise that is fulfilled or rejected as soon as a promise in the array is fulfilled or rejected with the respective rejection reason or fulfillment value. - * - * **Note** If you pass empty array or a sparse array with no values, or a promise/thenable for such, it will be forever pending. - */ - // promise of array with promises of value - export function race(values: Thenable[]>): Promise; - // promise of array with values - export function race(values: Thenable): Promise; - // array with promises of value - export function race(values: Thenable[]): Promise; - // array with values - export function race(values: R[]): Promise; - - /** - * Initiate a competetive race between multiple promises or values (values will become immediately fulfilled promises). When `count` amount of promises have been fulfilled, the returned promise is fulfilled with an array that contains the fulfillment values of the winners in order of resolution. - * - * If too many promises are rejected so that the promise can never become fulfilled, it will be immediately rejected with an array of rejection reasons in the order they were thrown in. - * - * *The original array is not modified.* - */ - // promise of array with promises of value - export function some(values: Thenable[]>, count: number): Promise; - // promise of array with values - export function some(values: Thenable, count: number): Promise; - // array with promises of value - export function some(values: Thenable[], count: number): Promise; - // array with values - export function some(values: R[], count: number): Promise; - - /** - * Like `Promise.all()` but instead of having to pass an array, the array is generated from the passed variadic arguments. - */ - // variadic array with promises of value - export function join(...values: Thenable[]): Promise; - // variadic array with values - export function join(...values: R[]): Promise; - - /** - * Map an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given `mapper` function with the signature `(item, index, arrayLength)` where `item` is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well. - * - * If the `mapper` function returns promises or thenables, the returned promise will wait for all the mapped results to be resolved as well. - * - * *The original array is not modified.* - */ - // promise of array with promises of value - export function map(values: Thenable[]>, mapper: (item: R, index: number, arrayLength: number) => Thenable): Promise; - export function map(values: Thenable[]>, mapper: (item: R, index: number, arrayLength: number) => U): Promise; - - // promise of array with values - export function map(values: Thenable, mapper: (item: R, index: number, arrayLength: number) => Thenable): Promise; - export function map(values: Thenable, mapper: (item: R, index: number, arrayLength: number) => U): Promise; - - // array with promises of value - export function map(values: Thenable[], mapper: (item: R, index: number, arrayLength: number) => Thenable): Promise; - export function map(values: Thenable[], mapper: (item: R, index: number, arrayLength: number) => U): Promise; - - // array with values - export function map(values: R[], mapper: (item: R, index: number, arrayLength: number) => Thenable): Promise; - export function map(values: R[], mapper: (item: R, index: number, arrayLength: number) => U): Promise; - - /** - * Reduce an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given `reducer` function with the signature `(total, current, index, arrayLength)` where `item` is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well. - * - * If the reducer function returns a promise or a thenable, the result for the promise is awaited for before continuing with next iteration. - * - * *The original array is not modified. If no `intialValue` is given and the array doesn't contain at least 2 items, the callback will not be called and `undefined` is returned. If `initialValue` is given and the array doesn't have at least 1 item, `initialValue` is returned.* - */ - // promise of array with promises of value - export function reduce(values: Thenable[]>, reducer: (total: U, current: R, index: number, arrayLength: number) => Thenable, initialValue?: U): Promise; - export function reduce(values: Thenable[]>, reducer: (total: U, current: R, index: number, arrayLength: number) => U, initialValue?: U): Promise; - - // promise of array with values - export function reduce(values: Thenable, reducer: (total: U, current: R, index: number, arrayLength: number) => Thenable, initialValue?: U): Promise; - export function reduce(values: Thenable, reducer: (total: U, current: R, index: number, arrayLength: number) => U, initialValue?: U): Promise; - - // array with promises of value - export function reduce(values: Thenable[], reducer: (total: U, current: R, index: number, arrayLength: number) => Thenable, initialValue?: U): Promise; - export function reduce(values: Thenable[], reducer: (total: U, current: R, index: number, arrayLength: number) => U, initialValue?: U): Promise; - - // array with values - export function reduce(values: R[], reducer: (total: U, current: R, index: number, arrayLength: number) => Thenable, initialValue?: U): Promise; - export function reduce(values: R[], reducer: (total: U, current: R, index: number, arrayLength: number) => U, initialValue?: U): Promise; - - /** - * Filter an array, or a promise of an array, which contains a promises (or a mix of promises and values) with the given `filterer` function with the signature `(item, index, arrayLength)` where `item` is the resolved value of a respective promise in the input array. If any promise in the input array is rejected the returned promise is rejected as well. - * - * The return values from the filtered functions are coerced to booleans, with the exception of promises and thenables which are awaited for their eventual result. - * - * *The original array is not modified. - */ - // promise of array with promises of value - export function filter(values: Thenable[]>, filterer: (item: R, index: number, arrayLength: number) => Thenable): Promise; - export function filter(values: Thenable[]>, filterer: (item: R, index: number, arrayLength: number) => boolean): Promise; - - // promise of array with values - export function filter(values: Thenable, filterer: (item: R, index: number, arrayLength: number) => Thenable): Promise; - export function filter(values: Thenable, filterer: (item: R, index: number, arrayLength: number) => boolean): Promise; - - // array with promises of value - export function filter(values: Thenable[], filterer: (item: R, index: number, arrayLength: number) => Thenable): Promise; - export function filter(values: Thenable[], filterer: (item: R, index: number, arrayLength: number) => boolean): Promise; - - // array with values - export function filter(values: R[], filterer: (item: R, index: number, arrayLength: number) => Thenable): Promise; - export function filter(values: R[], filterer: (item: R, index: number, arrayLength: number) => boolean): Promise; } declare module 'bluebird' {