From 5e338fd078925201041ed0fa75a461e630412330 Mon Sep 17 00:00:00 2001 From: Bart van der Schoor Date: Thu, 20 Feb 2014 00:39:06 +0100 Subject: [PATCH 1/3] first pass at making bluebird promise definitions generic ! not ready to merge ! definitions and tests should have all the methods, but: * some missing overloads * some problematic members * some members or tests commented out --- bluebird/bluebird.d.ts | 1062 +++++++++++++++++++++++----------------- 1 file changed, 612 insertions(+), 450 deletions(-) diff --git a/bluebird/bluebird.d.ts b/bluebird/bluebird.d.ts index 5db21d63ed..ba5c60ded5 100644 --- a/bluebird/bluebird.d.ts +++ b/bluebird/bluebird.d.ts @@ -1,499 +1,661 @@ // Type definitions for bluebird 1.0.0 // Project: https://github.com/petkaantonov/bluebird // Definitions by: Bart van der Schoor -// Definitions: https://github.com/borisyankov/DefinitelyTyped -// Note: these are preliminary non-generic typings using `any`: the generic versions are ready but need (tsc >= v1.0.0) due to issues in the compiler -// - https://github.com/borisyankov/DefinitelyTyped/issues/1563 -// - https://github.com/borisyankov/DefinitelyTyped/tree/def/bluebird/bluebird +// ES6 model with generics overload was sourced and trans-multiplied from es6-promises.d.ts +// By: Campredon +// By: Igorbek -declare class Promise { - /** - * Create a new promise. The passed in function will receive functions `resolve` and `reject` as its arguments which can be called to seal the fate of the created promise. - */ - constructor(resolver: (resolve: (value: any) => void, reject: (reason: any) => any) => void); - /** - * Promises/A+ `.then()` with progress handler. Returns a new promise chained from this promise. The new promise will be rejected or resolved dedefer on the passed `fulfilledHandler`, `rejectedHandler` and the state of this promise. - */ - then(fulfilledHandler?: (value: any) => any, rejectedHandler?: (reason: any) => any, progressHandler?: (note: any) => any):Promise; +// Note: replicate changes to all overloads in both definition and test file +// Note: keep both static and instance members inline (so similar) - /** - * This is a catch-all exception handler, shortcut for calling `.then(null, handler)` on this promise. Any exception happening in a `.then`-chain will propagate to nearest `.catch` handler. - * - * Alias `.caught();` for compatibility with earlier ECMAScript version. - */ - catch(handler: (reason: any) => any):Promise; - caught(handler: (reason: any) => any):Promise; +//TODO fix all TODO annotations in the file - /** - * This extends `.catch` to work more like catch-clauses in languages like Java or C#. Instead of manually checking `instanceof` or `.name === "SomeError"`, you may specify a number of error constructors which are eligible for this catch handler. The catch handler that is first met that has eligible constructors specified, is the one that will be called. - * - * This method also supports predicate-based filters. If you pass a predicate function instead of an error constructor, the predicate will receive the error as an argument. The return result of the predicate will be used determine whether the error handler should be called. - * - * Alias `.caught();` for compatibility with earlier ECMAScript version. - */ - //TODO expand this complex overload (weird) - catch(predicate: (reason: any) => boolean, handler: (reason: any) => any): Promise; - caught(predicate: (reason: any) => boolean, handler: (reason: any) => any): Promise; +//TODO support to have no return statement in handlers to get a Promise (more overloads?) - catch(ErrorClass: Function, handler: (reason: any) => any): Promise; - caught(ErrorClass: Function, handler: (reason: any) => any): Promise; - - /** - * Like `.catch` but instead of catching all types of exceptions, it only catches those that don't originate from thrown errors but rather from explicit rejections. - */ - error(rejectedHandler: (reason: any) => any): Promise; - - /** - * Pass a handler that will be called regardless of this promise's fate. Returns a new promise chained from this promise. There are special semantics for `.finally()` in that the final value cannot be modified from the handler. - * - * Alias `.lastly();` for compatibility with earlier ECMAScript version. - */ - finally(handler: (value: any) => any): Promise; - lastly(handler: (value: any) => any): Promise; - - /** - * Create a promise that follows this promise, but is bound to the given `thisArg` value. A bound promise will call its handlers with the bound value set to `this`. Additionally promises derived from a bound promise will also be bound promises with the same `thisArg` binding as the original promise. - */ - bind(thisArg: any): Promise; - - /** - * Like `.then()`, but any unhandled rejection that ends up here will be thrown as an error. - */ - done(fulfilledHandler?: (value: any) => any, rejectedHandler?: (reason: any) => any, progressHandler?: (note: any) => any): Promise; - - /** - * Shorthand for `.then(null, null, handler);`. Attach a progress handler that will be called if this promise is progressed. Returns a new promise chained from this promise. - */ - progressed(handler: (note: any) => any): Promise; - - /** - * Same as calling `Promise.delay(this, ms)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - delay(ms: number): Promise; - - /** - * Returns a promise that will be fulfilled with this promise's fulfillment value or rejection reason. However, if this promise is not fulfilled or rejected within `ms` milliseconds, the returned promise is rejected with a `Promise.TimeoutError` instance. - * - * You may specify a custom error message with the `message` parameter. - */ - - timeout(ms: number, message?: string): Promise; - - /** - * Register a node-style callback on this promise. When this promise is is either fulfilled or rejected, the node callback will be called back with the node.js convention where error reason is the first argument and success value is the second argument. The error argument will be `null` in case of success. - * Returns back this promise instead of creating a new one. If the `callback` argument is not a function, this method does not do anything. - */ - nodeify(callback?: Function): Promise; - - /** - * Marks this promise as cancellable. Promises by default are not cancellable after v0.11 and must be marked as such for `.cancel()` to have any effect. Marking a promise as cancellable is infectious and you don't need to remark any descendant promise. - */ - cancellable(): Promise; - - /** - * Cancel this promise. The cancellation will propagate to farthest cancellable ancestor promise which is still pending. - * - * That ancestor will then be rejected with a `CancellationError` (get a reference from `Promise.CancellationError`) object as the rejection reason. - * - * In a promise rejection handler you may check for a cancellation by seeing if the reason object has `.name === "Cancel"`. - * - * Promises are by default not cancellable. Use `.cancellable()` to mark a promise as cancellable. - */ - cancel(): Promise; - - /** - * Like `.then()`, but cancellation of the the returned promise or any of its descendant will not propagate cancellation to this promise or this promise's ancestors. - */ - fork(fulfilledHandler?: (value: any) => any, rejectedHandler?: (reason: any) => any, progressHandler?: (note: any) => any): Promise; - - /** - * Create an uncancellable promise based on this promise. - */ - uncancellable(): Promise; - - /** - * See if this promise can be cancelled. - */ - isCancellable(): boolean; - - /** - * See if this `promise` has been fulfilled. - */ - isFulfilled(): boolean; - - /** - * See if this `promise` has been rejected. - */ - isRejected(): boolean; - - /** - * See if this `promise` is still defer. - */ - isPending(): boolean; - - /** - * See if this `promise` is resolved -> either fulfilled or rejected. - */ - isResolved(): boolean; - - /** - * Synchronously inspect the state of this `promise`. The `Promise.Inspection` will represent the state of the promise as snapshotted at the time of calling `.inspect()`. - */ - inspect(): Promise.Inspection; - - /** - * This is a convenience method for doing: - * - * - * promise.then(function(obj){ - * return obj[propertyName].call(obj, arg...); - * }); - * - */ - call(propertyName: string, ...args: any[]): Promise; - - /** - * This is a convenience method for doing: - * - * - * promise.then(function(obj){ - * return obj[propertyName]; - * }); - * - */ - get(propertyName: string): Promise; - - /** - * Convenience method for: - * - * - * .then(function() { - * return value; - * }); - * - * - * in the case where `value` doesn't change its value. That means `value` is bound at the time of calling `.return()` - * - * Alias `.thenReturn();` for compatibility with earlier ECMAScript version. - */ - return(value: any): Promise; - thenReturn(): Promise; - - /** - * Convenience method for: - * - * - * .then(function() { - * throw reason; - * }); - * - * Same limitations apply as with `.return()`. - * - * Alias `.thenThrow();` for compatibility with earlier ECMAScript version. - */ - throw(reason: any): Promise; - thenThrow(): Promise; - - /** - * Convert to String. - */ - toString(): string; - - /** - * This is implicitly called by `JSON.stringify` when serializing the object. Returns a serialized representation of the `Promise`. - */ - toJSON(): Object; - - /** - * 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. - */ - all(): Promise; - - /** - * Same as calling `Promise.props(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - props(): Promise; - - /** - * Same as calling `Promise.settle(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - settle(): Promise; - - /** - * Same as calling `Promise.any(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - any(): Promise; - - /** - * Same as calling `Promise.race(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - some(count: number): Promise; - - /** - * Same as calling `Promise.some(thisPromise, count)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - race(): Promise; - - /** - * Like calling `.then`, but the fulfillment value or rejection reason is assumed to be an array, which is flattened to the formal parameters of the handlers. - */ - spread(fulfilledHandler?: (value: any) => any, rejectedHandler?: (reason: any) => any): Promise; - - /** - * Same as calling `Promise.map(thisPromise, mapper)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - map(mapper: (item: any, index: number, arrayLength: number) => any): Promise; - - /** - * Same as calling `Promise.reduce(thisPromise, Function reducer, initialValue)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - reduce(reducer: (total: number, current: any, index: number, arrayLength: number) => any, initialValue?: any): Promise; - - /** - * Same as calling ``Promise.filter(thisPromise, filterer)``. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - filter(filterer: (item: any, index: number, arrayLength: number) => any): Promise; +interface Thenable { + then(onFulfilled:(value:R) => Thenable, onRejected:(error:any) => Thenable): Thenable; + then(onFulfilled:(value:R) => Thenable, onRejected?:(error:any) => U): Thenable; + then(onFulfilled:(value:R) => U, onRejected:(error:any) => Thenable): Thenable; + then(onFulfilled?:(value:R) => U, onRejected?:(error:any) => U): Thenable; } +interface ArrayLike { + length:number; +} + +declare class Promise implements Thenable { + /** + * Create a new promise. The passed in function will receive functions `resolve` and `reject` as its arguments which can be called to seal the fate of the created promise. + */ + constructor(callback:(resolve:(result:R) => void, reject:(error:any) => void) => void); + constructor(callback:(resolve:(thenable:Thenable) => void, reject:(error:any) => void) => void); + + /** + * Promises/A+ `.then()` with progress handler. Returns a new promise chained from this promise. The new promise will be rejected or resolved dedefer on the passed `fulfilledHandler`, `rejectedHandler` and the state of this promise. + */ + then(onFulfill:(value:R) => Thenable, onReject:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; + then(onFulfill:(value:R) => Thenable, onReject?:(error:any) => U, onProgress?:(note:any) => any):Promise; + then(onFulfill:(value:R) => U, onReject:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; + then(onFulfill?:(value:R) => U, onReject?:(error:any) => U, onProgress?:(note:any) => any):Promise; + + /** + * This is a catch-all exception handler, shortcut for calling `.then(null, handler)` on this promise. Any exception happening in a `.then`-chain will propagate to nearest `.catch` handler. + * + * Alias `.caught();` for compatibility with earlier ECMAScript version. + */ + catch(onReject?:(error:any) => Thenable):Promise; + caught(onReject?:(error:any) => Thenable):Promise; + + catch(onReject?:(error:any) => U):Promise; + caught(onReject?:(error:any) => U):Promise; + + /** + * This extends `.catch` to work more like catch-clauses in languages like Java or C#. Instead of manually checking `instanceof` or `.name === "SomeError"`, you may specify a number of error constructors which are eligible for this catch handler. The catch handler that is first met that has eligible constructors specified, is the one that will be called. + * + * This method also supports predicate-based filters. If you pass a predicate function instead of an error constructor, the predicate will receive the error as an argument. The return result of the predicate will be used determine whether the error handler should be called. + * + * Alias `.caught();` for compatibility with earlier ECMAScript version. + */ + catch(predicate:(error:any) => boolean, onReject:(error:any) => Thenable):Promise; + caught(predicate:(error:any) => boolean, onReject:(error:any) => Thenable):Promise; + + catch(predicate:(error:any) => boolean, onReject:(error:any) => U):Promise; + caught(predicate:(error:any) => boolean, onReject:(error:any) => U):Promise; + + catch(ErrorClass:Function, onReject:(error:any) => Thenable):Promise; + caught(ErrorClass:Function, onReject:(error:any) => Thenable):Promise; + + catch(ErrorClass:Function, onReject:(error:any) => U):Promise; + caught(ErrorClass:Function, onReject:(error:any) => U):Promise; + + /** + * Like `.catch` but instead of catching all types of exceptions, it only catches those that don't originate from thrown errors but rather from explicit rejections. + */ + error(onReject:(reason:any) => Thenable):Promise; + error(onReject:(reason:any) => U):Promise; + + /** + * Pass a handler that will be called regardless of this promise's fate. Returns a new promise chained from this promise. There are special semantics for `.finally()` in that the final value cannot be modified from the handler. + * + * Alias `.lastly();` for compatibility with earlier ECMAScript version. + */ + finally(handler:(value:R) => Thenable):Promise; + finally(handler:(value:R) => R):Promise; + + lastly(handler:(value:R) => Thenable):Promise; + lastly(handler:(value:R) => R):Promise; + + /** + * Create a promise that follows this promise, but is bound to the given `thisArg` value. A bound promise will call its handlers with the bound value set to `this`. Additionally promises derived from a bound promise will also be bound promises with the same `thisArg` binding as the original promise. + */ + bind(thisArg:any):Promise; + + /** + * Like `.then()`, but any unhandled rejection that ends up here will be thrown as an error. + */ + done(onFulfilled:(value:R) => Thenable, onRejected:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; + done(onFulfilled:(value:R) => Thenable, onRejected?:(error:any) => U, onProgress?:(note:any) => any):Promise; + done(onFulfilled:(value:R) => U, onRejected:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; + done(onFulfilled?:(value:R) => U, onRejected?:(error:any) => U, onProgress?:(note:any) => any):Promise; + + /** + * Shorthand for `.then(null, null, handler);`. Attach a progress handler that will be called if this promise is progressed. Returns a new promise chained from this promise. + */ + progressed(handler:(note:any) => any):Promise; + + /** + * Same as calling `Promise.delay(this, ms)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + delay(ms:number):Promise; + + /** + * Returns a promise that will be fulfilled with this promise's fulfillment value or rejection reason. However, if this promise is not fulfilled or rejected within `ms` milliseconds, the returned promise is rejected with a `Promise.TimeoutError` instance. + * + * You may specify a custom error message with the `message` parameter. + */ + timeout(ms:number, message?:string):Promise; + + /** + * Register a node-style callback on this promise. When this promise is is either fulfilled or rejected, the node callback will be called back with the node.js convention where error reason is the first argument and success value is the second argument. The error argument will be `null` in case of success. + * Returns back this promise instead of creating a new one. If the `callback` argument is not a function, this method does not do anything. + */ + nodeify(callback:(err:any, value?:R) => void):Promise; + nodeify(...sink:any[]):void; + + /** + * Marks this promise as cancellable. Promises by default are not cancellable after v0.11 and must be marked as such for `.cancel()` to have any effect. Marking a promise as cancellable is infectious and you don't need to remark any descendant promise. + */ + cancellable():Promise; + + /** + * Cancel this promise. The cancellation will propagate to farthest cancellable ancestor promise which is still pending. + * + * That ancestor will then be rejected with a `CancellationError` (get a reference from `Promise.CancellationError`) object as the rejection reason. + * + * In a promise rejection handler you may check for a cancellation by seeing if the reason object has `.name === "Cancel"`. + * + * Promises are by default not cancellable. Use `.cancellable()` to mark a promise as cancellable. + */ + //TODO what to do with this? + cancel():Promise; + + /** + * Like `.then()`, but cancellation of the the returned promise or any of its descendant will not propagate cancellation to this promise or this promise's ancestors. + */ + fork(onFulfilled:(value:R) => Thenable, onRejected:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; + fork(onFulfilled:(value:R) => Thenable, onRejected?:(error:any) => U, onProgress?:(note:any) => any):Promise; + fork(onFulfilled:(value:R) => U, onRejected:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; + fork(onFulfilled?:(value:R) => U, onRejected?:(error:any) => U, onProgress?:(note:any) => any):Promise; + + /** + * Create an uncancellable promise based on this promise. + */ + uncancellable():Promise; + + /** + * See if this promise can be cancelled. + */ + isCancellable():boolean; + + /** + * See if this `promise` has been fulfilled. + */ + isFulfilled():boolean; + + /** + * See if this `promise` has been rejected. + */ + isRejected():boolean; + + /** + * See if this `promise` is still defer. + */ + isPending():boolean; + + /** + * See if this `promise` is resolved -> either fulfilled or rejected. + */ + isResolved():boolean; + + /** + * Synchronously inspect the state of this `promise`. The `PromiseInspection` will represent the state of the promise as snapshotted at the time of calling `.inspect()`. + */ + inspect():PromiseInspection; + + /** + * This is a convenience method for doing: + * + * + * promise.then(function(obj){ + * return obj[propertyName].call(obj, arg...); + * }); + * + */ + call(propertyName:string, ...args:any[]):Promise; + + /** + * This is a convenience method for doing: + * + * + * promise.then(function(obj){ + * return obj[propertyName]; + * }); + * + */ + //TODO find way to fix get() + // get(propertyName:string):Promise; + + /** + * Convenience method for: + * + * + * .then(function() { + * return value; + * }); + * + * + * in the case where `value` doesn't change its value. That means `value` is bound at the time of calling `.return()` + * + * Alias `.thenReturn();` for compatibility with earlier ECMAScript version. + */ + return(value?:U):Promise; + thenReturn(value?:U):Promise; + + /** + * Convenience method for: + * + * + * .then(function() { + * throw reason; + * }); + * + * Same limitations apply as with `.return()`. + * + * Alias `.thenThrow();` for compatibility with earlier ECMAScript version. + */ + throw(reason:any):Promise; + thenThrow(reason:any):Promise; + + /** + * Convert to String. + */ + toString():string; + + /** + * This is implicitly called by `JSON.stringify` when serializing the object. Returns a serialized representation of the `Promise`. + */ + toJSON():Object; + + /** + * Like calling `.then`, but the fulfillment value or rejection reason is assumed to be an array, which is flattened to the formal parameters of the handlers. + */ + //TODO how to model instance.spread()? + // like Q? + //spread(onFulfilled: Function, onRejected: Function): Promise; + /* + spread(onFulfill:(...values:W[]) => Thenable, onReject?:(reason:any) => Thenable):Promise; + spread(onFulfill:(...values:W[]) => Thenable, onReject?:(reason:any) => U):Promise; + spread(onFulfill:(...values:W[]) => U, onReject?:(reason:any) => 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. + */ + //TODO how to model instance.all()? + all():Promise; + + /** + * Same as calling `Promise.props(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + //TODO how to model instance.props()? + props():Promise; + + /** + * Same as calling `Promise.settle(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + //TODO how to model instance.settle()? + settle():Promise[]>; + + /** + * Same as calling `Promise.any(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + //TODO how to model instance.any()? + any():Promise; + + /** + * Same as calling `Promise.some(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + //TODO how to model instance.some()? + some(count:number):Promise; + + /** + * Same as calling `Promise.race(thisPromise, count)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + //TODO how to model instance.race()? + race():Promise; + + /** + * Same as calling `Promise.map(thisPromise, mapper)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + //TODO how to model instance.map()? + map(mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; + map(mapper:(item:R, index:number, arrayLength:number) => U):Promise; + + /** + * Same as calling `Promise.reduce(thisPromise, Function reducer, initialValue)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + //TODO how to model instance.reduce()? + reduce(reducer:(total:number, current:R, index:number, arrayLength:number) => Thenable, initialValue?:any):Promise; + reduce(reducer:(total:number, current:R, index:number, arrayLength:number) => U, initialValue?:any):Promise; + + /** + * Same as calling ``Promise.filter(thisPromise, filterer)``. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + //TODO how to model instance.filter()? + filter(filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; + filter(filterer:(item:R, index:number, arrayLength:number) => U):Promise; +} + +interface PromiseResolver { + /** + * 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; + + /** + * Reject the underlying promise with `reason` as the rejection reason. + */ + reject(reason:any):void; + + /** + * Progress the underlying promise with `value` as the progression value. + */ + progress(value:any):void; + + /** + * Gives you a callback representation of the `PromiseResolver`. Note that this is not a method but a property. The callback accepts error object in first argument and success values on the 2nd parameter and the rest, I.E. node js conventions. + * + * 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; +} + +interface PromiseInspection { + /** + * See if the underlying promise was fulfilled at the creation time of this inspection object. + */ + isFulfilled():boolean; + + /** + * See if the underlying promise was rejected at the creation time of this inspection object. + */ + isRejected():boolean; + + /** + * See if the underlying promise was defer at the creation time of this inspection object. + */ + isPending():boolean; + + /** + * Get the fulfillment value of the underlying promise. Throws if the promise wasn't fulfilled at the creation time of this inspection object. + * + * throws `TypeError` + */ + value():R; + + /** + * Get the rejection reason for the underlying promise. Throws if the promise wasn't rejected at the creation time of this inspection object. + * + * throws `TypeError` + */ + error():any; +} declare module 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. + */ + //TODO find way to enable try() without tsc borking + // see also: https://typescript.codeplex.com/workitem/2194 + /* + function try(fn:() => Thenable, args?:any[], ctx?:any):Promise; + function try(fn:() => R, args?:any[], ctx?:any):Promise; + // custom array-like + function try(fn:() => Thenable, args?:ArrayLike, ctx?:any):Promise; + function try(fn:() => R, args?:ArrayLike, ctx?:any):Promise; + */ - interface Resolver { - /** - * 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: any): void; + function attempt(fn:() => Thenable, args?:any[], ctx?:any):Promise; + function attempt(fn:() => R, args?:any[], ctx?:any):Promise; + // custom array-like + function attempt(fn:() => Thenable, args?:ArrayLike, ctx?:any):Promise; + function attempt(fn:() => R, args?:ArrayLike, ctx?:any):Promise; - /** - * Reject the underlying promise with `reason` as the rejection reason. - */ - reject(reason: any): void; + /** + * 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. + */ + function method(fn:Function):Function; - /** - * Progress the underlying promise with `value` as the progression value. - */ - progress(value: any): void; + /** + * Create a promise that is resolved with the given `value`. If `value` is a thenable or promise, the returned promise will assume its state. + */ + function resolve(value:Thenable):Promise; + function resolve(value:R):Promise; - /** - * Gives you a callback representation of the `Promise.Resolver`. Note that this is not a method but a property. The callback accepts error object in first argument and success values on the 2nd parameter and the rest, I.E. node js conventions. - * - * If the the callback is called with multiple success values, the resolver fullfills its promise with an array of the values. - */ - callback:Function; - } + /** + * Create a promise that is rejected with the given `reason`. + */ + function reject(reason:any):Promise; - interface Inspection { - /** - * See if the underlying promise was fulfilled at the creation time of this inspection object. - */ - isFulfilled(): boolean; + /** + * Create a promise with undecided fate and return a `PromiseResolver` to control it. See resolution?:Promise(#promise-resolution). + */ + function defer():PromiseResolver; - /** - * See if the underlying promise was rejected at the creation time of this inspection object. - */ - isRejected(): boolean; + /** + * 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. + */ + function cast(value:Thenable):Promise; + function cast(value:R):Promise; - /** - * See if the underlying promise was defer at the creation time of this inspection object. - */ - isPending(): boolean; + /** + * Sugar for `Promise.resolve(undefined).bind(thisArg);`. See `.bind()`. + */ + function bind(thisArg:any):Promise; - /** - * Get the fulfillment value of the underlying promise. Throws if the promise wasn't fulfilled at the creation time of this inspection object. - * - * throws `TypeError` - */ - value(): any; + /** + * See if `value` is a trusted Promise. + */ + function is(value:any):boolean; - /** - * Get the rejection reason for the underlying promise. Throws if the promise wasn't rejected at the creation time of this inspection object. - * - * throws `TypeError` - */ - error(): any; - } + /** + * 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. + */ + function longStackTraces():void; - /** - * 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. - */ - // function try(fn: () => any, args?: any[], ctx?: any): Promise; + /** + * 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 + function delay(value:Thenable, ms:number):Promise; + // function delay(value:R, ms:number):Promise; + function delay(ms:number):Promise; - function attempt(fn: () => any, args?: any[], ctx?: any): 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? + function promisify(nodeFunction:Function, receiver?:any):Function; - /** - * 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. - */ - function method(fn: Function): 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? + function promisifyAll(target:Object):Object; - /** - * Create a promise that is resolved with the given `value`. If `value` is a thenable or promise, the returned promise will assume its state. - */ - function resolve(value: any): Promise; + /** + * 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 + function coroutine(generatorFunction:Function):Function; - /** - * Create a promise that is rejected with the given `reason`. - */ - function reject(reason: any): Promise; + /** + * 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 + function spawn(generatorFunction:Function):Promise; - /** - * Create a promise with undecided fate and return a `Promise.Resolver` to control it. See resolution?:Promise(#promise-resolution). - */ - function defer(): Promise.Resolver; + /** + * 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. + */ + function noConflict():typeof Promise; - /** - * 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. - */ - function cast(value: any): 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. + */ + function onPossiblyUnhandledRejection(handler:(reason:any) => any):void; - /** - * Sugar for `Promise.resolve(undefined).bind(thisArg);`. See `.bind()`. - */ - function bind(thisArg: any): 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 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 + // function all(values:Thenable[]>):Promise; + // promise of array with values + // function all(values:Thenable):Promise; + // array with promises of value + function all(values:Thenable[]):Promise; + // array with values + function all(values:R[]):Promise; - /** - * See if `value` is a trusted Promise. - */ - function is(value: any): boolean; + /** + * 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.* + */ + // trusted promise for object + function props(object:Promise):Promise; + // object + function props(object:Object):Promise; - /** - * 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. - */ - function longStackTraces(): 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 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.* + */ + //TODO enable more overloads + // promise of array with promises of value + // function settle(values:Thenable[]>):Promise[]>; + // promise of array with values + // function settle(values:Thenable):Promise[]>; + // array with promises of value + function settle(values:Thenable[]):Promise[]>; + // array with values + function settle(values:R[]):Promise[]>; - /** - * 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. - */ - function delay(value: Promise, ms: number): 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. + */ + //TODO enable more overloads + // promise of array with promises of value + // function any(values:Thenable[]>):Promise; + // promise of array with values + // function any(values:Thenable):Promise; + // array with promises of value + function any(values:Thenable[]):Promise; + // array with values + function any(values:R[]):Promise; - function delay(value: any, ms: number): 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. + */ + //TODO enable more overloads + // promise of array with promises of value + // function race(values:Thenable[]>):Promise; + // promise of array with values + // function race(values:Thenable):Promise; + // array with promises of value + function race(values:Thenable[]):Promise; + // array with values + function race(values:R[]):Promise; - function delay(ms: number): 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.* + */ + //TODO enable more overloads + // promise of array with promises of value + // function some(values:Thenable[]>, count:number):Promise; + // promise of array with values + // function some(values:Thenable, count:number):Promise; + // array with promises of value + function some(values:Thenable[], count:number):Promise; + // array with values + function some(values:R[], count: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`. - */ - function promisify(nodeFunction: Function, receiver?: any): Function; + /** + * Like `Promise.all()` but instead of having to pass an array, the array is generated from the passed variadic arguments. + */ + //TODO not quite like Promise.all() or does it miss something? + // variadic array with promises of value + function join(...values:Thenable[]):Promise; + // variadic array with values + function join(...values:R[]):Promise; - /** - * This overload has been **deprecated**. The overload will continue working for now. The recommended method for promisifying multiple methods at once is ``Promise.promisifyAll(Object target)`` - */ - function promisify(target: Object): Object; + /** + * 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.* + */ + //TODO enable more overloads + // promise of array with promises of value + // function map(values:Thenable[]>, mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; + // function map(values:Thenable[]>, mapper:(item:R, index:number, arrayLength:number) => U):Promise; - /** - * 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. - */ - function promisifyAll(target: Object): Object; + // promise of array with values + // function map(values:Thenable, mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; + // function map(values:Thenable, mapper:(item:R, index:number, arrayLength:number) => U):Promise; - /** - * 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. - */ - function coroutine(generatorFunction: Function): Function; + // array with promises of value + function map(values:Thenable[], mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; + function map(values:Thenable[], mapper:(item:R, index:number, arrayLength:number) => U):Promise; - /** - * 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. - */ - function spawn(generatorFunction: Function): Promise; + // array with values + function map(values:R[], mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; + function map(values:R[], mapper:(item:R, index:number, arrayLength:number) => U):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. - */ - function noConflict(): Object; + /** + * 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.* + */ + //TODO enable more overloads + // promise of array with promises of value + // function reduce(values:Thenable[]>, reducer:(total:U, current:R, index:number, arrayLength:number) => Thenable, initialValue?:U):Promise; + // function reduce(values:Thenable[]>, reducer:(total:U, current:R, index:number, arrayLength:number) => U, initialValue?:U):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. - */ - function onPossiblyUnhandledRejection(handler: (reason: any) => any): void; + // promise of array with values + // function reduce(values:Thenable, reducer:(total:U, current:R, index:number, arrayLength:number) => Thenable, initialValue?:U):Promise; + // function reduce(values:Thenable, reducer:(total:U, current:R, index:number, arrayLength:number) => U, initialValue?:U):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 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. - */ - function all(values: any[]): Promise; + // array with promises of value + function reduce(values:Thenable[], reducer:(total:U, current:R, index:number, arrayLength:number) => Thenable, initialValue?:U):Promise; + function reduce(values:Thenable[], reducer:(total:U, current:R, index:number, arrayLength:number) => U, initialValue?:U):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.* - */ - function props(object: Promise): Promise; + // array with values + function reduce(values:R[], reducer:(total:U, current:R, index:number, arrayLength:number) => Thenable, initialValue?:U):Promise; + function reduce(values:R[], reducer:(total:U, current:R, index:number, arrayLength:number) => U, initialValue?:U):Promise; - function props(object: Object): 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. + */ + //TODO enable more overloads + // promise of array with promises of value + // function filter(values:Thenable[]>, filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; + // function filter(values:Thenable[]>, filterer:(item:R, index:number, arrayLength:number) => boolean):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 ``Promise.Inspection`` 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.* - */ - function settle(values: any[]): Promise; + // promise of array with values + // function filter(values:Thenable, filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; + // function filter(values:Thenable, filterer:(item:R, index:number, arrayLength:number) => boolean):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. - */ - function any(values: any[]): Promise; + // array with promises of value + function filter(values:Thenable[], filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; + function filter(values:Thenable[], filterer:(item:R, index:number, arrayLength:number) => boolean):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. - */ - function race(values: any[]): 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.* - */ - function some(values: any[], count: number): Promise; - - /** - * Like `Promise.all()` but instead of having to pass an array, the array is generated from the passed variadic arguments. - */ - function join(...values: any[]): 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.* - */ - function map(values: any[], mapper: (item: any, index: number, arrayLength: number) => any): 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.* - */ - function reduce(values: any[], reducer: (total: number, current: any, index: number, arrayLength: number) => any, initialValue?: any): 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. - */ - function filter(values: any[], filterer: (item: any, index?: number, arrayLength?: number) => any): Promise; + // array with values + function filter(values:R[], filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; + function filter(values:R[], filterer:(item:R, index:number, arrayLength:number) => boolean):Promise; } declare module 'bluebird' { From 64a7c7e391c7d77197f14f23470c478c5539400a Mon Sep 17 00:00:00 2001 From: Bart van der Schoor Date: Tue, 25 Feb 2014 02:09:07 +0100 Subject: [PATCH 2/3] Second pass at bluebird generics for TS > v0.9.7 (v1.0.0) Rebased on recent infrastructure --- bluebird/bluebird-tests.ts | 975 ++++++++++++++++++++++------- bluebird/bluebird.d.ts | 1208 ++++++++++++++++++------------------ 2 files changed, 1361 insertions(+), 822 deletions(-) diff --git a/bluebird/bluebird-tests.ts b/bluebird/bluebird-tests.ts index 14528b9b57..ff4b85e2e2 100644 --- a/bluebird/bluebird-tests.ts +++ b/bluebird/bluebird-tests.ts @@ -1,319 +1,868 @@ /// -// Note: try to maintain the ordering and separators +// Tests by: Bart van der Schoor -var obj:Object; -var bool:boolean; -var num:number; -var str:string; -var x:any = null; -var f:Function; -var arr:any[]; -var exp:RegExp; -var strArr:string[]; -var numArr:string[]; +// Note: replicate changes to all overloads in both definition and test file +// Note: keep both static and instance members inline (so similar) +// Note: try to maintain the ordering and separators, and keep to the pattern -var value:any = null; -var reason:any = null; +var obj: Object; +var bool: boolean; +var num: number; +var str: string; +var err: Error; +var x: any; +var f: Function; +var func: Function; +var arr: any[]; +var exp: RegExp; +var anyArr: any[]; +var strArr: string[]; +var numArr: number[]; -var promise:Promise; -var p:Promise; +// - - - - - - - - - - - - - - - - - -var resolver:Promise.Resolver; -var inspection:Promise.Inspection; +var value: any; +var reason: any; +var insanity: any; -// - - - - - - - - - - - - - - - - - - - - - - - - +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -var promise = new Promise((resolve:(value:any) => void, reject:(reason:any) => void) => { - if(true) { - resolve(123); - } - else { - reject(new Error('nope')); - } +interface Foo { + foo(): string; +} +interface Bar { + bar(): string; +} + +// - - - - - - - - - - - - - - - - - + +interface StrFooMap { + [key:string]:Foo; +} + +interface StrBarMap { + [key:string]:Bar; +} + +// - - - - - - - - - - - - - - - - - + +interface StrFooArrMap { + [key:string]:Foo[]; +} + +interface StrBarArrMap { + [key:string]:Bar[]; +} + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +var foo: Foo; +var bar: Bar; + +var fooArr: Foo[]; +var barArr: Bar[]; + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +var numProm: Promise; +var strProm: Promise; +var anyProm: Promise; +var boolProm: Promise; +var objProm: Promise; +var voidProm: Promise; + +var fooProm: Promise; +var barProm: Promise; + +// - - - - - - - - - - - - - - - - - + +var numThen: Promise.Thenable; +var strThen: Promise.Thenable; +var anyThen: Promise.Thenable; +var boolThen: Promise.Thenable; +var objThen: Promise.Thenable; +var voidThen: Promise.Thenable; + +var fooThen: Promise.Thenable; +var barThen: Promise.Thenable; + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +var numArrProm: Promise; +var strArrProm: Promise; +var anyArrProm: Promise; + +var fooArrProm: Promise; +var barArrProm: Promise; + +// - - - - - - - - - - - - - - - - - + +var numArrThen: Promise.Thenable; +var strArrThen: Promise.Thenable; +var anyArrThen: Promise.Thenable; + +var fooArrThen: Promise.Thenable; +var barArrThen: Promise.Thenable; + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +var numPromArr: Promise[]; +var strPromArr: Promise[]; +var anyPromArr: Promise[]; + +var fooPromArr: Promise[]; +var barPromArr: Promise[]; + +// - - - - - - - - - - - - - - - - - + +var numThenArr: Promise.Thenable[]; +var strThenArr: Promise.Thenable[]; +var anyThenArr: Promise.Thenable[]; + +var fooThenArr: Promise.Thenable[]; +var barThenArr: Promise.Thenable[]; + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// booya! +var fooThenArrThen: Promise.Thenable[]>; +var barThenArrThen: Promise.Thenable[]>; + +var fooResolver: Promise.Resolver; +var barResolver: Promise.Resolver; + +var fooInspection: Promise.Inspection; +var barInspection: Promise.Inspection; + +var fooInspectionArrProm: Promise[]>; +var barInspectionArrProm: Promise[]>; + +var BlueBird: typeof Promise; + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooThen = fooProm; +barThen = barProm; + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = new Promise((resolve: (value: Foo) => void, reject: (reason: any) => void) => { + if (bool) { + resolve(foo); + } + else { + reject(new Error(str)); + } +}); +fooProm = new Promise((resolve: (value: Foo) => void) => { + if (bool) { + resolve(foo); + } }); -// - - - - - - - - - - - - - - - - - - - - - - - - +// - - - - - - - - - - - - - - - - - - - - - - - -resolver.resolve(x); +// needs a hint when used untyped? +fooProm = new Promise((resolve, reject) => { + if (bool) { + resolve(fooThen); + } + else { + reject(new Error(str)); + } +}); +fooProm = new Promise((resolve) => { + resolve(fooThen); +}); -resolver.reject(x); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -resolver.progress(x); +fooResolver.resolve(foo); -resolver.callback = () => { +fooResolver.reject(foo); + +fooResolver.progress(foo); + +fooResolver.callback = () => { }; -// - - - - - - - - - - - - - - - - - - - - - - - - +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -bool = inspection.isFulfilled(); +bool = fooInspection.isFulfilled(); -bool = inspection.isRejected(); +bool = fooInspection.isRejected(); -bool = inspection.isPending(); +bool = fooInspection.isPending(); -x = inspection.value(); +foo = fooInspection.value(); -x = inspection.error(); +x = fooInspection.error(); -// - - - - - - - - - - - - - - - - - - - - - - - - +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = promise.then((value:any) => { +barProm = fooProm.then((value: Foo) => { + return bar; +}, (reason: any) => { + return bar; +}, (note: any) => { + return bar; +}); +barProm = fooProm.then((value: Foo) => { + return bar; +}, (reason: any) => { + return bar; +}); +barProm = fooProm.then((value: Foo) => { + return bar; +}); -}, (reason:any) => { +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -}, (note:any) => { +barProm = fooProm.catch((reason: any) => { + return bar; +}); +barProm = fooProm.caught((reason: any) => { + return bar; +}); + +barProm = fooProm.catch((reason: any) => { + return bar; +}, (reason: any) => { + return bar; +}); +barProm = fooProm.caught((reason: any) => { + return bar; +}, (reason: any) => { + return bar; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +barProm = fooProm.catch(Error, (reason: any) => { + return bar; +}); +barProm = fooProm.caught(Error, (reason: any) => { + return bar; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +barProm = fooProm.error((reason: any) => { + return bar; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = fooProm.finally((value: Foo) => { + // return is ignored + return foo; +}); +fooProm = fooProm.finally((value: Foo) => { + // return is ignored + return fooThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = fooProm.lastly((value: Foo) => { + // return is ignored + return foo; +}); +fooProm = fooProm.lastly((value: Foo) => { + // return is ignored + return fooThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = fooProm.bind(obj); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +barProm = fooProm.done((value: Foo) => { + return bar; +}, (reason: any) => { + return bar; +}, (note: any) => { }); -p = promise.then((value:any) => { +barProm = fooProm.done((value: Foo) => { + return bar; +}, (reason: any) => { + return bar; +}); +barProm = fooProm.done((value: Foo) => { + return bar; +}); -}, (reason:any) => { +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +barProm = fooProm.done((value: Foo) => { + return barThen; +}, (reason: any) => { + return barThen; +}, (note: any) => { }); -p = promise.then((value:any) => { +barProm = fooProm.done((value: Foo) => { + return barThen; +}, (reason: any) => { + return barThen; +}); +barProm = fooProm.done((value: Foo) => { + return barThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = fooProm.progressed((note: any) => { + return foo; +}); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = fooProm.delay(num); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = fooProm.timeout(num); +fooProm = fooProm.timeout(num, str); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm.nodeify(); +fooProm = fooProm.nodeify((err: any) => { + +}); +fooProm = fooProm.nodeify((err: any, foo?: Foo) => { }); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = promise.catch((reason:any) => { +barProm = fooProm.fork((value: Foo) => { + return bar; +}, (reason: any) => { + return bar; +}, (note: any) => { }); -p = promise.caught((reason:any) => { - +barProm = fooProm.fork((value: Foo) => { + return bar; +}, (reason: any) => { + return bar; }); -p = promise.catch((reason:any) => { - return true; -}, (reason:any) => { - -}); -p = promise.caught((reason:any) => { - return true; -}, (reason:any) => { - +barProm = fooProm.fork((value: Foo) => { + return bar; }); -p = promise.catch(Error, (reason:any) => { +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +barProm = fooProm.fork((value: Foo) => { + return barThen; +}, (reason: any) => { + return barThen; +}, (note: any) => { }); -p = promise.caught(Error, (reason:any) => { - +barProm = fooProm.fork((value: Foo) => { + return barThen; +}, (reason: any) => { + return barThen; +}); +barProm = fooProm.fork((value: Foo) => { + return barThen; }); -p = promise.error((reason:any) => { +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +barProm = fooProm.cancel(); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = fooProm.cancellable(); +fooProm = fooProm.uncancellable(); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +bool = fooProm.isCancellable(); +bool = fooProm.isFulfilled(); +bool = fooProm.isRejected(); +bool = fooProm.isPending(); +bool = fooProm.isResolved(); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooInspection = fooProm.inspect(); + +anyProm = fooProm.call(str); +anyProm = fooProm.call(str, 1, 2, 3); + +//TODO enable get() test when implemented +// barProm = fooProm.get(str); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +barProm = fooProm.return(bar); +barProm = fooProm.thenReturn(bar); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooProm +fooProm = fooProm.throw(err); +fooProm = fooProm.thenThrow(err); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +str = fooProm.toString(); + +obj = fooProm.toJSON(); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +barProm = fooArrProm.spread((one: Foo, two: Bar) => { + return bar; +}, (reason: any) => { + return bar; +}); +barProm = fooArrProm.spread((one: Foo, two: Bar, twotwo: Foo) => { + return bar; }); -p = promise.finally((value:any) => { +// - - - - - - - - - - - - - - - - - +barProm = fooArrProm.spread((one: Foo, two: Bar) => { + return barThen; +}, (reason: any) => { + return barThen; }); -p = promise.lastly((value:any) => { - +barProm = fooArrProm.spread((one: Foo, two: Bar, twotwo: Foo) => { + return barThen; }); -p = promise.bind(x); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = promise.done((value:any) => { +//TODO fix collection inference -}, (reason:any) => { +barArrProm = fooProm.all(); -}, (note:any) => { +objProm = fooProm.props(); +barInspectionArrProm = fooProm.settle(); + +barProm = fooProm.any(); + +barArrProm = fooProm.some(num); + +barProm = fooProm.race(); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +//TODO fix collection inference + +barProm = fooProm.map((item: Foo, index: number, arrayLength: number) => { + return bar; }); -p = promise.done((value:any) => { - -}, (reason:any) => { - -}); -p = promise.done((value:any) => { - +barProm = fooProm.map((item: Foo) => { + return bar; }); -p = promise.progressed((note:any) => { +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -}); - -p = promise.delay(x); - -p = promise.timeout(x); -p = promise.timeout(x, str); - -p = promise.nodeify(); -p = promise.nodeify(function(err:any) { - -}); - -p = promise.cancellable(); - -p = promise.cancel(); - -p = promise.fork((value:any) => { - -}, (reason:any) => { - -}, (note:any) => { - -}); -p = promise.fork((value:any) => { - -}, (reason:any) => { - -}); -p = promise.fork((value:any) => { - -}); - -p = promise.uncancellable(); - -bool = promise.isCancellable(); - -bool = promise.isFulfilled(); - -bool = promise.isRejected(); - -bool = promise.isPending(); - -bool = promise.isResolved(); - -inspection = promise.inspect(); - -p = promise.call(str, 1, 2, 3); - -p = promise.get(str); - -p = promise.return(value); -p = promise.thenReturn(); - -p = promise.throw(x); -p = promise.thenThrow(); - -str = promise.toString(); - -obj = promise.toJSON(); - -p = promise.all(); - -p = promise.props(); - -p = promise.settle(); - -p = promise.any(); - -p = promise.some(x); - -p = promise.race(); - -p = promise.spread((value:any) => { - -}, (reason:any) => { - -}); -p = promise.spread((value:any) => { - -}); - -p = promise.map((item:any, index:number, arrayLength:number) => { - return x; -}); - -p = promise.reduce((total:number, memo:any, index:number, arrayLength:number) => { +barProm = fooProm.reduce((memo: Bar, item: Foo, index: number, arrayLength: number) => { return memo; }); -p = promise.reduce((total:number, memo:any, index:number, arrayLength:number) => { +barProm = fooProm.reduce((memo: Bar, item: Foo) => { return memo; -}, x); +}, bar); -p = promise.filter((item:any, index?:number, arrayLength?:number) => { - return true; +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = fooProm.filter((item: Foo, index: number, arrayLength: number) => { + return bool; +}); +fooProm = fooProm.filter((item: Foo) => { + return bool; }); -// - - - - - - - - - - - - - - - - - - - - - - - - - -p = new Promise((resolve:(value:any) => any, reject:(reason:any) => any) => { - if(true) { - resolve(value); - } - else { - reject(new Error('xyz')); - } -}); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +///TODO enable try tests /* - p = Promise.try(() => {}); - p = Promise.try(() => {}, arr); - p = Promise.try(() => {}, arr, x); - */ +fooProm = Promise.try(() => { + return foo; +}); +fooProm = Promise.try(() => { + return foo; +}, arr); +fooProm = Promise.try(() => { + return foo; +}, arr, x); -p = Promise.attempt(() => {}); -p = Promise.attempt(() => {}, arr); -p = Promise.attempt(() => {}, arr, x); +// - - - - - - - - - - - - - - - - - -f = Promise.method(function() { +fooProm = Promise.try(() => { + return fooThen; +}); +fooProm = Promise.try(() => { + return fooThen; +}, arr); +fooProm = Promise.try(() => { + return fooThen; +}, arr, x); +*/ +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = Promise.attempt(() => { + return foo; +}); +fooProm = Promise.attempt(() => { + return foo; +}, arr); +fooProm = Promise.attempt(() => { + return foo; +}, arr, x); + +// - - - - - - - - - - - - - - - - - + +fooProm = Promise.attempt(() => { + return fooThen; +}); +fooProm = Promise.attempt(() => { + return fooThen; +}, arr); +fooProm = Promise.attempt(() => { + return fooThen; +}, arr, x); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +func = Promise.method(function () { }); -p = Promise.resolve(value); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = Promise.reject(reason); +fooProm = Promise.resolve(foo); +fooProm = Promise.resolve(fooThen); -resolver = Promise.defer(); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = Promise.cast(value); +voidProm = Promise.reject(reason); -p = Promise.bind(x); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooResolver = Promise.defer(); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooProm = Promise.cast(foo); +fooProm = Promise.cast(fooThen); + +voidProm = Promise.bind(x); bool = Promise.is(value); Promise.longStackTraces(); -p = Promise.delay(p, x); -p = Promise.delay(value, x); -p = Promise.delay(x); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -f = Promise.promisify(f); -f = Promise.promisify(f, x); +//TODO enable delay -obj = Promise.promisify(obj); +fooProm = Promise.delay(fooThen, num); +fooProm = Promise.delay(foo, num); +voidProm = Promise.delay(num); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +func = Promise.promisify(f); +func = Promise.promisify(f, obj); +; obj = Promise.promisifyAll(obj); -f = Promise.coroutine(f); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = Promise.spawn(f); +//TODO enable generator +/* + func = Promise.coroutine(f); -obj = Promise.noConflict(); + barProm = Promise.spawn(f); + */ +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -Promise.onPossiblyUnhandledRejection((reason:any) => { +BlueBird = Promise.noConflict(); + +Promise.onPossiblyUnhandledRejection((reason: any) => { }); -p = Promise.all(arr); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = Promise.props(p); -p = Promise.props(obj); +//TODO expand tests to overloads +fooArrProm = Promise.all(fooThenArrThen); +fooArrProm = Promise.all(fooArrProm); +fooArrProm = Promise.all(fooThenArr); +fooArrProm = Promise.all(fooArr); -p = Promise.settle(arr); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = Promise.any(arr); +objProm = Promise.props(objProm); +objProm = Promise.props(obj); -p = Promise.race(arr); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = Promise.some(arr, x); +//TODO expand tests to overloads +fooInspectionArrProm = Promise.settle(fooThenArrThen); +fooInspectionArrProm = Promise.settle(fooArrProm); +fooInspectionArrProm = Promise.settle(fooThenArr); +fooInspectionArrProm = Promise.settle(fooArr); -p = Promise.join(1, 2, 3); +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -p = Promise.map(arr, (item:any, index:number, arrayLength:number) => { - return x; +//TODO expand tests to overloads +fooProm = Promise.any(fooThenArrThen); +fooProm = Promise.any(fooArrProm); +fooProm = Promise.any(fooThenArr); +fooProm = Promise.any(fooArr); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +//TODO expand tests to overloads +fooProm = Promise.race(fooThenArrThen); +fooProm = Promise.race(fooArrProm); +fooProm = Promise.race(fooThenArr); +fooProm = Promise.race(fooArr); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +//TODO expand tests to overloads +fooArrProm = Promise.some(fooThenArrThen, num); +fooArrProm = Promise.some(fooArrThen, num); +fooArrProm = Promise.some(fooThenArr, num); +fooArrProm = Promise.some(fooArr, num); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +fooArrProm = Promise.join(foo, foo, foo); +fooArrProm = Promise.join(fooThen, fooThen, fooThen); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// map() + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooThenArrThen + +barArrProm = Promise.map(fooThenArrThen, (item: Foo) => { + return bar; +}); +barArrProm = Promise.map(fooThenArrThen, (item: Foo) => { + return barThen; +}); +barArrProm = Promise.map(fooThenArrThen, (item: Foo, index: number, arrayLength: number) => { + return bar; +}); +barArrProm = Promise.map(fooThenArrThen, (item: Foo, index: number, arrayLength: number) => { + return barThen; }); -p = Promise.reduce(arr, (total:number, memo:any, index:number, arrayLength:number) => { +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooArrThen + +barArrProm = Promise.map(fooArrThen, (item: Foo) => { + return bar; +}); +barArrProm = Promise.map(fooArrThen, (item: Foo) => { + return barThen; +}); +barArrProm = Promise.map(fooArrThen, (item: Foo, index: number, arrayLength: number) => { + return bar; +}); +barArrProm = Promise.map(fooArrThen, (item: Foo, index: number, arrayLength: number) => { + return barThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooThenArr + +barArrProm = Promise.map(fooThenArr, (item: Foo) => { + return bar; +}); +barArrProm = Promise.map(fooThenArr, (item: Foo) => { + return barThen; +}); +barArrProm = Promise.map(fooThenArr, (item: Foo, index: number, arrayLength: number) => { + return bar; +}); +barArrProm = Promise.map(fooThenArr, (item: Foo, index: number, arrayLength: number) => { + return barThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooArr + +barArrProm = Promise.map(fooArr, (item: Foo) => { + return bar; +}); +barArrProm = Promise.map(fooArr, (item: Foo) => { + return barThen; +}); +barArrProm = Promise.map(fooArr, (item: Foo, index: number, arrayLength: number) => { + return bar; +}); +barArrProm = Promise.map(fooArr, (item: Foo, index: number, arrayLength: number) => { + return barThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// reduce() + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooThenArrThen + +barProm = Promise.reduce(fooThenArrThen, (memo: Bar, item: Foo) => { return memo; -}); -p = Promise.reduce(arr, (total:number, memo:any, index:number, arrayLength:number) => { +}, bar); +barProm = Promise.reduce(fooThenArrThen, (memo: Bar, item: Foo) => { + return barThen; +}, bar); +barProm = Promise.reduce(fooThenArrThen, (memo: Bar, item: Foo, index: number, arrayLength: number) => { return memo; -}, x); +}, bar); +barProm = Promise.reduce(fooThenArrThen, (memo: Bar, item: Foo, index: number, arrayLength: number) => { + return barThen; +}, bar); -p = Promise.filter(arr, (item:any, index?:number, arrayLength?:number) => { - return true; +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooArrThen + +barProm = Promise.reduce(fooArrThen, (memo: Bar, item: Foo) => { + return memo; +}, bar); +barProm = Promise.reduce(fooArrThen, (memo: Bar, item: Foo) => { + return barThen; +}, bar); +barProm = Promise.reduce(fooArrThen, (memo: Bar, item: Foo, index: number, arrayLength: number) => { + return memo; +}, bar); +barProm = Promise.reduce(fooArrThen, (memo: Bar, item: Foo, index: number, arrayLength: number) => { + return barThen; +}, bar); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooThenArr + +barProm = Promise.reduce(fooThenArr, (memo: Bar, item: Foo) => { + return memo; +}, bar); +barProm = Promise.reduce(fooThenArr, (memo: Bar, item: Foo) => { + return barThen; +}, bar); +barProm = Promise.reduce(fooThenArr, (memo: Bar, item: Foo, index: number, arrayLength: number) => { + return memo; +}, bar); +barProm = Promise.reduce(fooThenArr, (memo: Bar, item: Foo, index: number, arrayLength: number) => { + return barThen; +}, bar); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooArr + +barProm = Promise.reduce(fooArr, (memo: Bar, item: Foo) => { + return memo; +}, bar); +barProm = Promise.reduce(fooArr, (memo: Bar, item: Foo) => { + return barThen; +}, bar); +barProm = Promise.reduce(fooArr, (memo: Bar, item: Foo, index: number, arrayLength: number) => { + return memo; +}, bar); +barProm = Promise.reduce(fooArr, (memo: Bar, item: Foo, index: number, arrayLength: number) => { + return barThen; +}, bar); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// filter() + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooThenArrThen + +fooArrProm = Promise.filter(fooThenArrThen, (item: Foo) => { + return bool; }); +fooArrProm = Promise.filter(fooThenArrThen, (item: Foo) => { + return boolThen; +}); +fooArrProm = Promise.filter(fooThenArrThen, (item: Foo, index: number, arrayLength: number) => { + return bool; +}); +fooArrProm = Promise.filter(fooThenArrThen, (item: Foo, index: number, arrayLength: number) => { + return boolThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooArrThen + +fooArrProm = Promise.filter(fooArrThen, (item: Foo) => { + return bool; +}); +fooArrProm = Promise.filter(fooArrThen, (item: Foo) => { + return boolThen; +}); +fooArrProm = Promise.filter(fooArrThen, (item: Foo, index: number, arrayLength: number) => { + return bool; +}); +fooArrProm = Promise.filter(fooArrThen, (item: Foo, index: number, arrayLength: number) => { + return boolThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooThenArr + +fooArrProm = Promise.filter(fooThenArr, (item: Foo) => { + return bool; +}); +fooArrProm = Promise.filter(fooThenArr, (item: Foo) => { + return boolThen; +}); +fooArrProm = Promise.filter(fooThenArr, (item: Foo, index: number, arrayLength: number) => { + return bool; +}); +fooArrProm = Promise.filter(fooThenArr, (item: Foo, index: number, arrayLength: number) => { + return boolThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + +// fooArr + +fooArrProm = Promise.filter(fooArr, (item: Foo) => { + return bool; +}); +fooArrProm = Promise.filter(fooArr, (item: Foo) => { + return boolThen; +}); +fooArrProm = Promise.filter(fooArr, (item: Foo, index: number, arrayLength: number) => { + return bool; +}); +fooArrProm = Promise.filter(fooArr, (item: Foo, index: number, arrayLength: number) => { + return boolThen; +}); + +// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/bluebird/bluebird.d.ts b/bluebird/bluebird.d.ts index ba5c60ded5..13494cb829 100644 --- a/bluebird/bluebird.d.ts +++ b/bluebird/bluebird.d.ts @@ -1,663 +1,653 @@ // Type definitions for bluebird 1.0.0 // Project: https://github.com/petkaantonov/bluebird // Definitions by: Bart van der Schoor +// Definitions: https://github.com/borisyankov/DefinitelyTyped // ES6 model with generics overload was sourced and trans-multiplied from es6-promises.d.ts // By: Campredon -// By: Igorbek + +// Warning: recommended to use `tsc > v1.0.0` (critical bugs in generic code: +// - https://github.com/borisyankov/DefinitelyTyped/issues/1563 +// - https://github.com/borisyankov/DefinitelyTyped/tree/def/bluebird // Note: replicate changes to all overloads in both definition and test file // Note: keep both static and instance members inline (so similar) -//TODO fix all TODO annotations in the file +// TODO fix remaining TODO annotations in both definition and test -//TODO support to have no return statement in handlers to get a Promise (more overloads?) +// TODO verify support to have no return statement in handlers to get a Promise (more overloads?) -interface Thenable { - then(onFulfilled:(value:R) => Thenable, onRejected:(error:any) => Thenable): Thenable; - then(onFulfilled:(value:R) => Thenable, onRejected?:(error:any) => U): Thenable; - then(onFulfilled:(value:R) => U, onRejected:(error:any) => Thenable): Thenable; - then(onFulfilled?:(value:R) => U, onRejected?:(error:any) => U): Thenable; +declare class Promise implements Promise.Thenable { + /** + * Create a new promise. The passed in function will receive functions `resolve` and `reject` as its arguments which can be called to seal the fate of the created promise. + */ + constructor(callback: (resolve: (thenable: Promise.Thenable) => void, reject: (error: any) => void) => void); + constructor(callback: (resolve: (result: R) => void, reject: (error: any) => void) => void); + + /** + * Promises/A+ `.then()` with progress handler. Returns a new promise chained from this promise. The new promise will be rejected or resolved dedefer on the passed `fulfilledHandler`, `rejectedHandler` and the state of this promise. + */ + then(onFulfill: (value: R) => Promise.Thenable, onReject: (error: any) => Promise.Thenable, onProgress?: (note: any) => any): Promise; + then(onFulfill: (value: R) => Promise.Thenable, onReject?: (error: any) => U, onProgress?: (note: any) => any): Promise; + then(onFulfill: (value: R) => U, onReject: (error: any) => Promise.Thenable, onProgress?: (note: any) => any): Promise; + then(onFulfill?: (value: R) => U, onReject?: (error: any) => U, onProgress?: (note: any) => any): Promise; + + /** + * This is a catch-all exception handler, shortcut for calling `.then(null, handler)` on this promise. Any exception happening in a `.then`-chain will propagate to nearest `.catch` handler. + * + * Alias `.caught();` for compatibility with earlier ECMAScript version. + */ + catch(onReject?: (error: any) => Promise.Thenable): Promise; + caught(onReject?: (error: any) => Promise.Thenable): Promise; + + catch(onReject?: (error: any) => U): Promise; + caught(onReject?: (error: any) => U): Promise; + + /** + * This extends `.catch` to work more like catch-clauses in languages like Java or C#. Instead of manually checking `instanceof` or `.name === "SomeError"`, you may specify a number of error constructors which are eligible for this catch handler. The catch handler that is first met that has eligible constructors specified, is the one that will be called. + * + * This method also supports predicate-based filters. If you pass a predicate function instead of an error constructor, the predicate will receive the error as an argument. The return result of the predicate will be used determine whether the error handler should be called. + * + * Alias `.caught();` for compatibility with earlier ECMAScript version. + */ + catch(predicate: (error: any) => boolean, onReject: (error: any) => Promise.Thenable): Promise; + caught(predicate: (error: any) => boolean, onReject: (error: any) => Promise.Thenable): Promise; + + catch(predicate: (error: any) => boolean, onReject: (error: any) => U): Promise; + caught(predicate: (error: any) => boolean, onReject: (error: any) => U): Promise; + + catch(ErrorClass: Function, onReject: (error: any) => Promise.Thenable): Promise; + caught(ErrorClass: Function, onReject: (error: any) => Promise.Thenable): Promise; + + catch(ErrorClass: Function, onReject: (error: any) => U): Promise; + caught(ErrorClass: Function, onReject: (error: any) => U): Promise; + + /** + * Like `.catch` but instead of catching all types of exceptions, it only catches those that don't originate from thrown errors but rather from explicit rejections. + */ + error(onReject: (reason: any) => Promise.Thenable): Promise; + error(onReject: (reason: any) => U): Promise; + + /** + * Pass a handler that will be called regardless of this promise's fate. Returns a new promise chained from this promise. There are special semantics for `.finally()` in that the final value cannot be modified from the handler. + * + * Alias `.lastly();` for compatibility with earlier ECMAScript version. + */ + finally(handler: (value: R) => Promise.Thenable): Promise; + finally(handler: (value: R) => R): Promise; + + lastly(handler: (value: R) => Promise.Thenable): Promise; + lastly(handler: (value: R) => R): Promise; + + /** + * Create a promise that follows this promise, but is bound to the given `thisArg` value. A bound promise will call its handlers with the bound value set to `this`. Additionally promises derived from a bound promise will also be bound promises with the same `thisArg` binding as the original promise. + */ + bind(thisArg: any): Promise; + + /** + * Like `.then()`, but any unhandled rejection that ends up here will be thrown as an error. + */ + done(onFulfilled: (value: R) => Promise.Thenable, onRejected: (error: any) => Promise.Thenable, onProgress?: (note: any) => any): Promise; + done(onFulfilled: (value: R) => Promise.Thenable, onRejected?: (error: any) => U, onProgress?: (note: any) => any): Promise; + done(onFulfilled: (value: R) => U, onRejected: (error: any) => Promise.Thenable, onProgress?: (note: any) => any): Promise; + done(onFulfilled?: (value: R) => U, onRejected?: (error: any) => U, onProgress?: (note: any) => any): Promise; + + /** + * Shorthand for `.then(null, null, handler);`. Attach a progress handler that will be called if this promise is progressed. Returns a new promise chained from this promise. + */ + progressed(handler: (note: any) => any): Promise; + + /** + * Same as calling `Promise.delay(this, ms)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + delay(ms: number): Promise; + + /** + * Returns a promise that will be fulfilled with this promise's fulfillment value or rejection reason. However, if this promise is not fulfilled or rejected within `ms` milliseconds, the returned promise is rejected with a `Promise.TimeoutError` instance. + * + * You may specify a custom error message with the `message` parameter. + */ + timeout(ms: number, message?: string): Promise; + + /** + * Register a node-style callback on this promise. When this promise is is either fulfilled or rejected, the node callback will be called back with the node.js convention where error reason is the first argument and success value is the second argument. The error argument will be `null` in case of success. + * Returns back this promise instead of creating a new one. If the `callback` argument is not a function, this method does not do anything. + */ + nodeify(callback: (err: any, value?: R) => void): Promise; + nodeify(...sink: any[]): void; + + /** + * Marks this promise as cancellable. Promises by default are not cancellable after v0.11 and must be marked as such for `.cancel()` to have any effect. Marking a promise as cancellable is infectious and you don't need to remark any descendant promise. + */ + cancellable(): Promise; + + /** + * Cancel this promise. The cancellation will propagate to farthest cancellable ancestor promise which is still pending. + * + * That ancestor will then be rejected with a `CancellationError` (get a reference from `Promise.CancellationError`) object as the rejection reason. + * + * In a promise rejection handler you may check for a cancellation by seeing if the reason object has `.name === "Cancel"`. + * + * Promises are by default not cancellable. Use `.cancellable()` to mark a promise as cancellable. + */ + // TODO what to do with this? + cancel(): Promise; + + /** + * Like `.then()`, but cancellation of the the returned promise or any of its descendant will not propagate cancellation to this promise or this promise's ancestors. + */ + fork(onFulfilled: (value: R) => Promise.Thenable, onRejected: (error: any) => Promise.Thenable, onProgress?: (note: any) => any): Promise; + fork(onFulfilled: (value: R) => Promise.Thenable, onRejected?: (error: any) => U, onProgress?: (note: any) => any): Promise; + fork(onFulfilled: (value: R) => U, onRejected: (error: any) => Promise.Thenable, onProgress?: (note: any) => any): Promise; + fork(onFulfilled?: (value: R) => U, onRejected?: (error: any) => U, onProgress?: (note: any) => any): Promise; + + /** + * Create an uncancellable promise based on this promise. + */ + uncancellable(): Promise; + + /** + * See if this promise can be cancelled. + */ + isCancellable(): boolean; + + /** + * See if this `promise` has been fulfilled. + */ + isFulfilled(): boolean; + + /** + * See if this `promise` has been rejected. + */ + isRejected(): boolean; + + /** + * See if this `promise` is still defer. + */ + isPending(): boolean; + + /** + * See if this `promise` is resolved -> either fulfilled or rejected. + */ + isResolved(): boolean; + + /** + * Synchronously inspect the state of this `promise`. The `PromiseInspection` will represent the state of the promise as snapshotted at the time of calling `.inspect()`. + */ + inspect(): Promise.Inspection; + + /** + * This is a convenience method for doing: + * + * + * promise.then(function(obj){ + * return obj[propertyName].call(obj, arg...); + * }); + * + */ + call(propertyName: string, ...args: any[]): Promise; + + /** + * This is a convenience method for doing: + * + * + * promise.then(function(obj){ + * return obj[propertyName]; + * }); + * + */ + // TODO find way to fix get() + // get(propertyName: string): Promise; + + /** + * Convenience method for: + * + * + * .then(function() { + * return value; + * }); + * + * + * in the case where `value` doesn't change its value. That means `value` is bound at the time of calling `.return()` + * + * Alias `.thenReturn();` for compatibility with earlier ECMAScript version. + */ + return(value?: U): Promise; + thenReturn(value?: U): Promise; + + /** + * Convenience method for: + * + * + * .then(function() { + * throw reason; + * }); + * + * Same limitations apply as with `.return()`. + * + * Alias `.thenThrow();` for compatibility with earlier ECMAScript version. + */ + throw(reason: Error): Promise; + thenThrow(reason: Error): Promise; + + /** + * Convert to String. + */ + toString(): string; + + /** + * This is implicitly called by `JSON.stringify` when serializing the object. Returns a serialized representation of the `Promise`. + */ + toJSON(): Object; + + /** + * Like calling `.then`, but the fulfillment value or rejection reason is assumed to be an array, which is flattened to the formal parameters of the handlers. + */ + // TODO how to model instance.spread()? like Q? + 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; + */ + /** + * 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. + */ + // TODO type inference from array-resolving promise? + all(): Promise; + + /** + * Same as calling `Promise.props(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + // TODO how to model instance.props()? + props(): Promise; + + /** + * Same as calling `Promise.settle(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + // TODO type inference from array-resolving promise? + settle(): Promise[]>; + + /** + * Same as calling `Promise.any(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + // TODO type inference from array-resolving promise? + any(): Promise; + + /** + * Same as calling `Promise.some(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + // TODO type inference from array-resolving promise? + some(count: number): Promise; + + /** + * Same as calling `Promise.race(thisPromise, count)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + // TODO type inference from array-resolving promise? + race(): Promise; + + /** + * Same as calling `Promise.map(thisPromise, mapper)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + // TODO type inference from array-resolving promise? + map(mapper: (item: Q, index: number, arrayLength: number) => Promise.Thenable): Promise; + map(mapper: (item: Q, index: number, arrayLength: number) => U): Promise; + + /** + * Same as calling `Promise.reduce(thisPromise, Function reducer, initialValue)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + // TODO type inference from array-resolving promise? + reduce(reducer: (memo: U, item: Q, index: number, arrayLength: number) => Promise.Thenable, initialValue?: U): Promise; + reduce(reducer: (memo: U, item: Q, index: number, arrayLength: number) => U, initialValue?: U): Promise; + + /** + * Same as calling ``Promise.filter(thisPromise, filterer)``. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. + */ + // 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; } -interface ArrayLike { - length:number; -} - -declare class Promise implements Thenable { - /** - * Create a new promise. The passed in function will receive functions `resolve` and `reject` as its arguments which can be called to seal the fate of the created promise. - */ - constructor(callback:(resolve:(result:R) => void, reject:(error:any) => void) => void); - constructor(callback:(resolve:(thenable:Thenable) => void, reject:(error:any) => void) => void); - - /** - * Promises/A+ `.then()` with progress handler. Returns a new promise chained from this promise. The new promise will be rejected or resolved dedefer on the passed `fulfilledHandler`, `rejectedHandler` and the state of this promise. - */ - then(onFulfill:(value:R) => Thenable, onReject:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; - then(onFulfill:(value:R) => Thenable, onReject?:(error:any) => U, onProgress?:(note:any) => any):Promise; - then(onFulfill:(value:R) => U, onReject:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; - then(onFulfill?:(value:R) => U, onReject?:(error:any) => U, onProgress?:(note:any) => any):Promise; - - /** - * This is a catch-all exception handler, shortcut for calling `.then(null, handler)` on this promise. Any exception happening in a `.then`-chain will propagate to nearest `.catch` handler. - * - * Alias `.caught();` for compatibility with earlier ECMAScript version. - */ - catch(onReject?:(error:any) => Thenable):Promise; - caught(onReject?:(error:any) => Thenable):Promise; - - catch(onReject?:(error:any) => U):Promise; - caught(onReject?:(error:any) => U):Promise; - - /** - * This extends `.catch` to work more like catch-clauses in languages like Java or C#. Instead of manually checking `instanceof` or `.name === "SomeError"`, you may specify a number of error constructors which are eligible for this catch handler. The catch handler that is first met that has eligible constructors specified, is the one that will be called. - * - * This method also supports predicate-based filters. If you pass a predicate function instead of an error constructor, the predicate will receive the error as an argument. The return result of the predicate will be used determine whether the error handler should be called. - * - * Alias `.caught();` for compatibility with earlier ECMAScript version. - */ - catch(predicate:(error:any) => boolean, onReject:(error:any) => Thenable):Promise; - caught(predicate:(error:any) => boolean, onReject:(error:any) => Thenable):Promise; - - catch(predicate:(error:any) => boolean, onReject:(error:any) => U):Promise; - caught(predicate:(error:any) => boolean, onReject:(error:any) => U):Promise; - - catch(ErrorClass:Function, onReject:(error:any) => Thenable):Promise; - caught(ErrorClass:Function, onReject:(error:any) => Thenable):Promise; - - catch(ErrorClass:Function, onReject:(error:any) => U):Promise; - caught(ErrorClass:Function, onReject:(error:any) => U):Promise; - - /** - * Like `.catch` but instead of catching all types of exceptions, it only catches those that don't originate from thrown errors but rather from explicit rejections. - */ - error(onReject:(reason:any) => Thenable):Promise; - error(onReject:(reason:any) => U):Promise; - - /** - * Pass a handler that will be called regardless of this promise's fate. Returns a new promise chained from this promise. There are special semantics for `.finally()` in that the final value cannot be modified from the handler. - * - * Alias `.lastly();` for compatibility with earlier ECMAScript version. - */ - finally(handler:(value:R) => Thenable):Promise; - finally(handler:(value:R) => R):Promise; - - lastly(handler:(value:R) => Thenable):Promise; - lastly(handler:(value:R) => R):Promise; - - /** - * Create a promise that follows this promise, but is bound to the given `thisArg` value. A bound promise will call its handlers with the bound value set to `this`. Additionally promises derived from a bound promise will also be bound promises with the same `thisArg` binding as the original promise. - */ - bind(thisArg:any):Promise; - - /** - * Like `.then()`, but any unhandled rejection that ends up here will be thrown as an error. - */ - done(onFulfilled:(value:R) => Thenable, onRejected:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; - done(onFulfilled:(value:R) => Thenable, onRejected?:(error:any) => U, onProgress?:(note:any) => any):Promise; - done(onFulfilled:(value:R) => U, onRejected:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; - done(onFulfilled?:(value:R) => U, onRejected?:(error:any) => U, onProgress?:(note:any) => any):Promise; - - /** - * Shorthand for `.then(null, null, handler);`. Attach a progress handler that will be called if this promise is progressed. Returns a new promise chained from this promise. - */ - progressed(handler:(note:any) => any):Promise; - - /** - * Same as calling `Promise.delay(this, ms)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - delay(ms:number):Promise; - - /** - * Returns a promise that will be fulfilled with this promise's fulfillment value or rejection reason. However, if this promise is not fulfilled or rejected within `ms` milliseconds, the returned promise is rejected with a `Promise.TimeoutError` instance. - * - * You may specify a custom error message with the `message` parameter. - */ - timeout(ms:number, message?:string):Promise; - - /** - * Register a node-style callback on this promise. When this promise is is either fulfilled or rejected, the node callback will be called back with the node.js convention where error reason is the first argument and success value is the second argument. The error argument will be `null` in case of success. - * Returns back this promise instead of creating a new one. If the `callback` argument is not a function, this method does not do anything. - */ - nodeify(callback:(err:any, value?:R) => void):Promise; - nodeify(...sink:any[]):void; - - /** - * Marks this promise as cancellable. Promises by default are not cancellable after v0.11 and must be marked as such for `.cancel()` to have any effect. Marking a promise as cancellable is infectious and you don't need to remark any descendant promise. - */ - cancellable():Promise; - - /** - * Cancel this promise. The cancellation will propagate to farthest cancellable ancestor promise which is still pending. - * - * That ancestor will then be rejected with a `CancellationError` (get a reference from `Promise.CancellationError`) object as the rejection reason. - * - * In a promise rejection handler you may check for a cancellation by seeing if the reason object has `.name === "Cancel"`. - * - * Promises are by default not cancellable. Use `.cancellable()` to mark a promise as cancellable. - */ - //TODO what to do with this? - cancel():Promise; - - /** - * Like `.then()`, but cancellation of the the returned promise or any of its descendant will not propagate cancellation to this promise or this promise's ancestors. - */ - fork(onFulfilled:(value:R) => Thenable, onRejected:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; - fork(onFulfilled:(value:R) => Thenable, onRejected?:(error:any) => U, onProgress?:(note:any) => any):Promise; - fork(onFulfilled:(value:R) => U, onRejected:(error:any) => Thenable, onProgress?:(note:any) => any):Promise; - fork(onFulfilled?:(value:R) => U, onRejected?:(error:any) => U, onProgress?:(note:any) => any):Promise; - - /** - * Create an uncancellable promise based on this promise. - */ - uncancellable():Promise; - - /** - * See if this promise can be cancelled. - */ - isCancellable():boolean; - - /** - * See if this `promise` has been fulfilled. - */ - isFulfilled():boolean; - - /** - * See if this `promise` has been rejected. - */ - isRejected():boolean; - - /** - * See if this `promise` is still defer. - */ - isPending():boolean; - - /** - * See if this `promise` is resolved -> either fulfilled or rejected. - */ - isResolved():boolean; - - /** - * Synchronously inspect the state of this `promise`. The `PromiseInspection` will represent the state of the promise as snapshotted at the time of calling `.inspect()`. - */ - inspect():PromiseInspection; - - /** - * This is a convenience method for doing: - * - * - * promise.then(function(obj){ - * return obj[propertyName].call(obj, arg...); - * }); - * - */ - call(propertyName:string, ...args:any[]):Promise; - - /** - * This is a convenience method for doing: - * - * - * promise.then(function(obj){ - * return obj[propertyName]; - * }); - * - */ - //TODO find way to fix get() - // get(propertyName:string):Promise; - - /** - * Convenience method for: - * - * - * .then(function() { - * return value; - * }); - * - * - * in the case where `value` doesn't change its value. That means `value` is bound at the time of calling `.return()` - * - * Alias `.thenReturn();` for compatibility with earlier ECMAScript version. - */ - return(value?:U):Promise; - thenReturn(value?:U):Promise; - - /** - * Convenience method for: - * - * - * .then(function() { - * throw reason; - * }); - * - * Same limitations apply as with `.return()`. - * - * Alias `.thenThrow();` for compatibility with earlier ECMAScript version. - */ - throw(reason:any):Promise; - thenThrow(reason:any):Promise; - - /** - * Convert to String. - */ - toString():string; - - /** - * This is implicitly called by `JSON.stringify` when serializing the object. Returns a serialized representation of the `Promise`. - */ - toJSON():Object; - - /** - * Like calling `.then`, but the fulfillment value or rejection reason is assumed to be an array, which is flattened to the formal parameters of the handlers. - */ - //TODO how to model instance.spread()? - // like Q? - //spread(onFulfilled: Function, onRejected: Function): Promise; - /* - spread(onFulfill:(...values:W[]) => Thenable, onReject?:(reason:any) => Thenable):Promise; - spread(onFulfill:(...values:W[]) => Thenable, onReject?:(reason:any) => U):Promise; - spread(onFulfill:(...values:W[]) => U, onReject?:(reason:any) => 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. - */ - //TODO how to model instance.all()? - all():Promise; - - /** - * Same as calling `Promise.props(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - //TODO how to model instance.props()? - props():Promise; - - /** - * Same as calling `Promise.settle(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - //TODO how to model instance.settle()? - settle():Promise[]>; - - /** - * Same as calling `Promise.any(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - //TODO how to model instance.any()? - any():Promise; - - /** - * Same as calling `Promise.some(thisPromise)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - //TODO how to model instance.some()? - some(count:number):Promise; - - /** - * Same as calling `Promise.race(thisPromise, count)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - //TODO how to model instance.race()? - race():Promise; - - /** - * Same as calling `Promise.map(thisPromise, mapper)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - //TODO how to model instance.map()? - map(mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; - map(mapper:(item:R, index:number, arrayLength:number) => U):Promise; - - /** - * Same as calling `Promise.reduce(thisPromise, Function reducer, initialValue)`. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - //TODO how to model instance.reduce()? - reduce(reducer:(total:number, current:R, index:number, arrayLength:number) => Thenable, initialValue?:any):Promise; - reduce(reducer:(total:number, current:R, index:number, arrayLength:number) => U, initialValue?:any):Promise; - - /** - * Same as calling ``Promise.filter(thisPromise, filterer)``. With the exception that if this promise is bound to a value, the returned promise is bound to that value too. - */ - //TODO how to model instance.filter()? - filter(filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; - filter(filterer:(item:R, index:number, arrayLength:number) => U):Promise; -} - -interface PromiseResolver { - /** - * 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; - - /** - * Reject the underlying promise with `reason` as the rejection reason. - */ - reject(reason:any):void; - - /** - * Progress the underlying promise with `value` as the progression value. - */ - progress(value:any):void; - - /** - * Gives you a callback representation of the `PromiseResolver`. Note that this is not a method but a property. The callback accepts error object in first argument and success values on the 2nd parameter and the rest, I.E. node js conventions. - * - * 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; -} - -interface PromiseInspection { - /** - * See if the underlying promise was fulfilled at the creation time of this inspection object. - */ - isFulfilled():boolean; - - /** - * See if the underlying promise was rejected at the creation time of this inspection object. - */ - isRejected():boolean; - - /** - * See if the underlying promise was defer at the creation time of this inspection object. - */ - isPending():boolean; - - /** - * Get the fulfillment value of the underlying promise. Throws if the promise wasn't fulfilled at the creation time of this inspection object. - * - * throws `TypeError` - */ - value():R; - - /** - * Get the rejection reason for the underlying promise. Throws if the promise wasn't rejected at the creation time of this inspection object. - * - * throws `TypeError` - */ - error():any; -} declare module 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. - */ - //TODO find way to enable try() without tsc borking - // see also: https://typescript.codeplex.com/workitem/2194 - /* - function try(fn:() => Thenable, args?:any[], ctx?:any):Promise; - function try(fn:() => R, args?:any[], ctx?:any):Promise; - // custom array-like - function try(fn:() => Thenable, args?:ArrayLike, ctx?:any):Promise; - function try(fn:() => R, args?:ArrayLike, ctx?:any):Promise; - */ - function attempt(fn:() => Thenable, args?:any[], ctx?:any):Promise; - function attempt(fn:() => R, args?:any[], ctx?:any):Promise; - // custom array-like - function attempt(fn:() => Thenable, args?:ArrayLike, ctx?:any):Promise; - function attempt(fn:() => R, args?:ArrayLike, ctx?:any):Promise; + export interface Thenable { + then(onFulfilled: (value: R) => Thenable, onRejected: (error: any) => Thenable): Thenable; + then(onFulfilled: (value: R) => Thenable, onRejected?: (error: any) => U): Thenable; + then(onFulfilled: (value: R) => U, onRejected: (error: any) => Thenable): Thenable; + then(onFulfilled?: (value: R) => U, onRejected?: (error: any) => U): Thenable; + } - /** - * 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. - */ - function method(fn:Function):Function; + export interface Resolver { + /** + * 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; - /** - * Create a promise that is resolved with the given `value`. If `value` is a thenable or promise, the returned promise will assume its state. - */ - function resolve(value:Thenable):Promise; - function resolve(value:R):Promise; + /** + * Reject the underlying promise with `reason` as the rejection reason. + */ + reject(reason: any): void; - /** - * Create a promise that is rejected with the given `reason`. - */ - function reject(reason:any):Promise; + /** + * Progress the underlying promise with `value` as the progression value. + */ + progress(value: any): void; - /** - * Create a promise with undecided fate and return a `PromiseResolver` to control it. See resolution?:Promise(#promise-resolution). - */ - function defer():PromiseResolver; + /** + * Gives you a callback representation of the `PromiseResolver`. Note that this is not a method but a property. The callback accepts error object in first argument and success values on the 2nd parameter and the rest, I.E. node js conventions. + * + * 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; + } - /** - * 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. - */ - function cast(value:Thenable):Promise; - function cast(value:R):Promise; + export interface Inspection { + /** + * See if the underlying promise was fulfilled at the creation time of this inspection object. + */ + isFulfilled(): boolean; - /** - * Sugar for `Promise.resolve(undefined).bind(thisArg);`. See `.bind()`. - */ - function bind(thisArg:any):Promise; + /** + * See if the underlying promise was rejected at the creation time of this inspection object. + */ + isRejected(): boolean; - /** - * See if `value` is a trusted Promise. - */ - function is(value:any):boolean; + /** + * See if the underlying promise was defer at the creation time of this inspection object. + */ + isPending(): 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. - */ - function longStackTraces():void; + /** + * Get the fulfillment value of the underlying promise. Throws if the promise wasn't fulfilled at the creation time of this inspection object. + * + * throws `TypeError` + */ + value(): R; - /** - * 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 - function delay(value:Thenable, ms:number):Promise; - // function delay(value:R, ms:number):Promise; - function delay(ms:number):Promise; + /** + * Get the rejection reason for the underlying promise. Throws if the promise wasn't rejected at the creation time of this inspection object. + * + * throws `TypeError` + */ + error(): any; + } - /** - * 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? - function promisify(nodeFunction:Function, receiver?:any):Function; + /** + * 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; + */ - /** - * 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? - function promisifyAll(target:Object):Object; + export function attempt(fn: () => Promise.Thenable, args?: any[], ctx?: any): Promise; + export function attempt(fn: () => R, args?: any[], ctx?: any): Promise; - /** - * 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 - function coroutine(generatorFunction:Function):Function; + /** + * 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; - /** - * 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 - function spawn(generatorFunction:Function):Promise; + /** + * 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; - /** - * 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. - */ - function noConflict():typeof Promise; + /** + * Create a promise that is rejected with the given `reason`. + */ + export function reject(reason: any): 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. - */ - function onPossiblyUnhandledRejection(handler:(reason:any) => any):void; + /** + * Create a promise with undecided fate and return a `PromiseResolver` to control it. See resolution?: Promise(#promise-resolution). + */ + export function defer(): Promise.Resolver; - /** - * 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 - // function all(values:Thenable[]>):Promise; - // promise of array with values - // function all(values:Thenable):Promise; - // array with promises of value - function all(values:Thenable[]):Promise; - // array with values - function all(values:R[]):Promise; + /** + * 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; - /** - * 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.* - */ - // trusted promise for object - function props(object:Promise):Promise; - // object - function props(object:Object):Promise; + /** + * Sugar for `Promise.resolve(undefined).bind(thisArg);`. See `.bind()`. + */ + export function bind(thisArg: any): 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.* - */ - //TODO enable more overloads - // promise of array with promises of value - // function settle(values:Thenable[]>):Promise[]>; - // promise of array with values - // function settle(values:Thenable):Promise[]>; - // array with promises of value - function settle(values:Thenable[]):Promise[]>; - // array with values - function settle(values:R[]):Promise[]>; + /** + * See if `value` is a trusted Promise. + */ + export function is(value: any): boolean; - /** - * 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. - */ - //TODO enable more overloads - // promise of array with promises of value - // function any(values:Thenable[]>):Promise; - // promise of array with values - // function any(values:Thenable):Promise; - // array with promises of value - function any(values:Thenable[]):Promise; - // array with values - function any(values:R[]):Promise; + /** + * 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; - /** - * 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. - */ - //TODO enable more overloads - // promise of array with promises of value - // function race(values:Thenable[]>):Promise; - // promise of array with values - // function race(values:Thenable):Promise; - // array with promises of value - function race(values:Thenable[]):Promise; - // array with values - function race(values:R[]):Promise; + /** + * 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; - /** - * 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.* - */ - //TODO enable more overloads - // promise of array with promises of value - // function some(values:Thenable[]>, count:number):Promise; - // promise of array with values - // function some(values:Thenable, count:number):Promise; - // array with promises of value - function some(values:Thenable[], count:number):Promise; - // array with values - function some(values:R[], count: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; - /** - * Like `Promise.all()` but instead of having to pass an array, the array is generated from the passed variadic arguments. - */ - //TODO not quite like Promise.all() or does it miss something? - // variadic array with promises of value - function join(...values:Thenable[]):Promise; - // variadic array with values - function join(...values:R[]):Promise; + /** + * 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; - /** - * 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.* - */ - //TODO enable more overloads - // promise of array with promises of value - // function map(values:Thenable[]>, mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; - // function map(values:Thenable[]>, mapper:(item:R, index:number, arrayLength:number) => U):Promise; + /** + * 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; - // promise of array with values - // function map(values:Thenable, mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; - // function map(values:Thenable, mapper:(item:R, index:number, arrayLength:number) => U):Promise; + /** + * 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; - // array with promises of value - function map(values:Thenable[], mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; - function map(values:Thenable[], mapper:(item:R, index:number, arrayLength:number) => U):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; - // array with values - function map(values:R[], mapper:(item:R, index:number, arrayLength:number) => Thenable):Promise; - function map(values:R[], mapper:(item:R, index:number, arrayLength:number) => U):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; - /** - * 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.* - */ - //TODO enable more overloads - // promise of array with promises of value - // function reduce(values:Thenable[]>, reducer:(total:U, current:R, index:number, arrayLength:number) => Thenable, initialValue?:U):Promise; - // function reduce(values:Thenable[]>, reducer:(total:U, current:R, index:number, arrayLength:number) => U, initialValue?:U):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 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; - // promise of array with values - // function reduce(values:Thenable, reducer:(total:U, current:R, index:number, arrayLength:number) => Thenable, initialValue?:U):Promise; - // function reduce(values:Thenable, reducer:(total:U, current:R, index:number, arrayLength:number) => U, initialValue?:U):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; - // array with promises of value - function reduce(values:Thenable[], reducer:(total:U, current:R, index:number, arrayLength:number) => Thenable, initialValue?:U):Promise; - function reduce(values:Thenable[], reducer:(total:U, current:R, index:number, arrayLength:number) => U, initialValue?:U):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[]>; - // array with values - function reduce(values:R[], reducer:(total:U, current:R, index:number, arrayLength:number) => Thenable, initialValue?:U):Promise; - function reduce(values:R[], reducer:(total:U, current:R, index:number, arrayLength:number) => U, initialValue?:U):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; - /** - * 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. - */ - //TODO enable more overloads - // promise of array with promises of value - // function filter(values:Thenable[]>, filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; - // function filter(values:Thenable[]>, filterer:(item:R, index:number, arrayLength:number) => boolean):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; - // promise of array with values - // function filter(values:Thenable, filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; - // function filter(values:Thenable, filterer:(item:R, index:number, arrayLength:number) => boolean):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; - // array with promises of value - function filter(values:Thenable[], filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; - function filter(values:Thenable[], filterer:(item:R, index:number, arrayLength:number) => boolean):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; - // array with values - function filter(values:R[], filterer:(item:R, index:number, arrayLength:number) => Thenable):Promise; - function filter(values:R[], filterer:(item:R, index:number, arrayLength:number) => boolean):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' { -export = Promise; + export = Promise; } From a490e14f0121a8823d9bf4400de827e0d088456a Mon Sep 17 00:00:00 2001 From: Bart van der Schoor Date: Fri, 7 Mar 2014 18:38:29 +0100 Subject: [PATCH 3/3] Small fixes for bluebird generics --- bluebird/bluebird-tests.ts | 15 +++++++++++++++ bluebird/bluebird.d.ts | 13 ++++++++----- 2 files changed, 23 insertions(+), 5 deletions(-) diff --git a/bluebird/bluebird-tests.ts b/bluebird/bluebird-tests.ts index ff4b85e2e2..e5d83db7a6 100644 --- a/bluebird/bluebird-tests.ts +++ b/bluebird/bluebird-tests.ts @@ -264,6 +264,12 @@ fooProm = fooProm.finally((value: Foo) => { // return is ignored return fooThen; }); +fooProm = fooProm.finally((value: Foo) => { + // return is ignored +}); +fooProm = fooProm.finally(() => { + // return is ignored +}); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -275,6 +281,12 @@ fooProm = fooProm.lastly((value: Foo) => { // return is ignored return fooThen; }); +fooProm = fooProm.lastly((value: Foo) => { + // return is ignored +}); +fooProm = fooProm.lastly(() => { + // return is ignored +}); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - @@ -408,6 +420,9 @@ anyProm = fooProm.call(str, 1, 2, 3); barProm = fooProm.return(bar); barProm = fooProm.thenReturn(bar); +voidProm = fooProm.return(); +voidProm = fooProm.thenReturn(); + // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - // fooProm diff --git a/bluebird/bluebird.d.ts b/bluebird/bluebird.d.ts index 13494cb829..0d57e49b02 100644 --- a/bluebird/bluebird.d.ts +++ b/bluebird/bluebird.d.ts @@ -6,9 +6,8 @@ // ES6 model with generics overload was sourced and trans-multiplied from es6-promises.d.ts // By: Campredon -// Warning: recommended to use `tsc > v1.0.0` (critical bugs in generic code: +// Warning: recommended to use `tsc > v0.9.7` (critical bugs in earlier generic code): // - https://github.com/borisyankov/DefinitelyTyped/issues/1563 -// - https://github.com/borisyankov/DefinitelyTyped/tree/def/bluebird // Note: replicate changes to all overloads in both definition and test file // Note: keep both static and instance members inline (so similar) @@ -75,9 +74,11 @@ declare class Promise implements Promise.Thenable { */ finally(handler: (value: R) => Promise.Thenable): Promise; finally(handler: (value: R) => R): Promise; + finally(handler: (value: R) => void): Promise; lastly(handler: (value: R) => Promise.Thenable): Promise; lastly(handler: (value: R) => R): Promise; + lastly(handler: (value: R) => void): Promise; /** * Create a promise that follows this promise, but is bound to the given `thisArg` value. A bound promise will call its handlers with the bound value set to `this`. Additionally promises derived from a bound promise will also be bound promises with the same `thisArg` binding as the original promise. @@ -212,8 +213,10 @@ declare class Promise implements Promise.Thenable { * * Alias `.thenReturn();` for compatibility with earlier ECMAScript version. */ - return(value?: U): Promise; - thenReturn(value?: U): Promise; + return(value: U): Promise; + thenReturn(value: U): Promise; + return(): Promise; + thenReturn(): Promise; /** * Convenience method for: @@ -341,7 +344,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 + // TODO specify resolver callback callback: Function; }