Last active
November 18, 2016 21:52
-
-
Save Taytay/2f66bc465e43a2f16efe to your computer and use it in GitHub Desktop.
Type definitions for RSVP. Still needs unit tests.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
// Type definitions for RSVP | |
// Project: github.com/tildeio/rsvp.js | |
// Definitions by: Taylor Brown <https://github.com/Taytay> | |
// Definitions: https://github.com/borisyankov/DefinitelyTyped | |
// Some of this file was taken from the type definitions for es6-promise https://github.com/borisyankov/DefinitelyTyped/blob/master/es6-promise/es6-promise.d.ts | |
// Credit for that file goes to: François de Campredon <https://github.com/fdecampredon/> | |
// Some of this file was taken from the type definitions for Q : https://github.com/borisyankov/DefinitelyTyped/blob/master/q/Q.d.ts | |
// Credit for that file goes to: Barrie Nemetchek <https://github.com/bnemetchek>, Andrew Gaspar <https://github.com/AndrewGaspar/>, John Reilly <https://github.com/johnnyreilly> | |
// This has been updated to reflect Typescript 2.1, which allows for union types. Furthermore, the old definitions were imprecise, and | |
// were leading to some compilation errors in 2.1 | |
declare module RSVP { | |
interface Thenable<T> { | |
then<U>(onFulfilled?: (value: T) => U | Thenable<U>, onRejected?: (error: any) => U | Thenable<U>): Thenable<U>; | |
then<U>(onFulfilled?: (value: T) => U | Thenable<U>, onRejected?: (error: any) => void): Thenable<U>; | |
} | |
interface Deferred<T> { | |
promise: Promise<T>; | |
resolve(value: T): void; | |
reject(reason: any): void; | |
} | |
class Promise<R> implements Thenable<R> { | |
/** | |
* If you call resolve in the body of the callback passed to the constructor, | |
* your promise is fulfilled with result object passed to resolve. | |
* If you call reject your promise is rejected with the object passed to resolve. | |
* For consistency and debugging (eg stack traces), obj should be an instanceof Error. | |
* Any errors thrown in the constructor callback will be implicitly passed to reject(). | |
*/ | |
constructor(callback: (resolve: (result?: R | Thenable<R>) => void, reject: (error: any) => void) => void); | |
/** | |
* onFulfilled is called when/if "promise" resolves. onRejected is called when/if "promise" rejects. | |
* Both are optional, if either/both are omitted the next onFulfilled/onRejected in the chain is called. | |
* Both callbacks have a single parameter , the fulfillment value or rejection reason. | |
* "then" returns a new promise equivalent to the value you return from onFulfilled/onRejected after being passed through Promise.resolve. | |
* If an error is thrown in the callback, the returned promise rejects with that error. | |
* | |
* @param onFulfilled called when/if "promise" resolves | |
* @param onRejected called when/if "promise" rejects | |
*/ | |
then<U>(onFulfilled?: (value: R) => U | Thenable<U>, onRejected?: (error: any) => U | Thenable<U>): Promise<U>; | |
then<U>(onFulfilled?: (value: R) => U | Thenable<U>, onRejected?: (error: any) => void): Promise<U>; | |
/** | |
* Sugar for promise.then(undefined, onRejected) | |
* | |
* @param onRejected called when/if "promise" rejects | |
*/ | |
catch<U>(onRejected?: (error: any) => U | Thenable<U>): Promise<U>; | |
catch<U>(onRejected?: (error: any) => void): Promise<void>; | |
finally(finallyCallback: () => any): Promise<R>; | |
static all<T>(promises: (T | Thenable<T>)[]): Promise<T[]>; | |
static race<R>(promises: Promise<R>[]): Promise<R>; | |
/** | |
@method resolve | |
@param {Any} value value that the returned promise will be resolved with | |
@param {String} label optional string for identifying the returned promise. | |
Useful for tooling. | |
@return {Promise} a promise that will become fulfilled with the given | |
`value` | |
*/ | |
static resolve<T>(object: T | Thenable<T>): Promise<T>; | |
/** | |
@method cast (Deprecated in favor of resolve | |
@param {Any} value value that the returned promise will be resolved with | |
@param {String} label optional string for identifying the returned promise. | |
Useful for tooling. | |
@return {Promise} a promise that will become fulfilled with the given | |
`value` | |
*/ | |
static cast<T>(object: T | Thenable<T>, label?: string): Promise<T>; | |
/** | |
`RSVP.Promise.reject` returns a promise rejected with the passed `reason`. | |
*/ | |
static reject(reason?: any): Promise<any>; | |
} | |
interface PromiseState<T> { | |
state: string /* "fulfilled", "rejected", "pending" */; | |
value?: T; | |
reason?: any; | |
} | |
interface InstrumentEvent { | |
guid: string; // guid of promise. Must be globally unique, not just within the implementation | |
childGuid: string; // child of child promise (for chained via `then`) | |
eventName: string; // one of ['created', 'chained', 'fulfilled', 'rejected'] | |
detail: any; // fulfillment value or rejection reason, if applicable | |
label: string; // label passed to promise's constructor | |
timeStamp: number; // milliseconds elapsed since 1 January 1970 00:00:00 UTC up until now | |
} | |
export function on(eventName: string, callback: (value: any) => void): void; | |
export function on(eventName: "error", errorHandler: (reason: any) => void): void; | |
export function on(eventName: "created", listener: (event: InstrumentEvent) => void): void; | |
export function on(eventName: "chained", listener: (event: InstrumentEvent) => void): void; | |
export function on(eventName: "fulfilled", listener: (event: InstrumentEvent) => void): void; | |
export function on(eventName: "rejected", listener: (event: InstrumentEvent) => void): void; | |
export function configure(configName: string, value: any): void; | |
export function configure(configName: "instrument", shouldInstrument: boolean): void; | |
/** | |
* configure('onerror', handler) is deprecated in favor of on('error', handler) | |
* @param configName | |
* @param errorHandler | |
*/ | |
export function configure(configName: "onerror", errorHandler: (reason: any) => void): void; | |
/** | |
* Make a promise that fulfills when every item in the array fulfills, and rejects if (and when) any item rejects. | |
* the array passed to all can be a mixture of promise-like objects and other objects. | |
* The fulfillment value is an array (in order) of fulfillment values. The rejection value is the first rejection value. | |
*/ | |
export function all<T>(promises: Thenable<T>[]): Promise<T[]>; | |
export function all<T>(promises: any[]): Promise<T[]>; | |
/** | |
* Make a promise that fulfills when every item in the array fulfills, and rejects if (and when) any item rejects. | |
* the array passed to all can be a mixture of promise-like objects and other objects. | |
* The fulfillment value is an array (in order) of fulfillment values. The rejection value is the first rejection value. | |
* The key difference to the all() function is that both the fulfillment value and the argument to the hash() function | |
* are object literals. This allows you to simply reference the results directly off the returned object without | |
* having to remember the initial order like you would with all(). | |
* | |
*/ | |
export function hash<T>(promises: Thenable<T>[]): Promise<T[]>; | |
export function hash<T>(promises: any[]): Promise<T[]>; | |
/** | |
`RSVP.map` is similar to JavaScript's native `map` method, except that it | |
waits for all promises to become fulfilled before running the `mapFn` on | |
each item in given to `promises`. `RSVP.map` returns a promise that will | |
become fulfilled with the result of running `mapFn` on the values the promises | |
become fulfilled with. | |
*/ | |
export function map<T>(promises: Thenable<T>[], mapFn: (item: any) => any, label?: string): Promise<T[]>; | |
export function map<T>(promises: any[], mapFn: (item: any) => any, label?: string): Promise<T[]>; | |
/** | |
* `RSVP.allSettled` is similar to `RSVP.all`, but instead of implementing | |
* a fail-fast method, it waits until all the promises have returned and | |
* shows you all the results. This is useful if you want to handle multiple | |
* promises' failure states together as a set. | |
*/ | |
export function allSettled<T>(promises: Thenable<T>[]): Promise<PromiseState<T>[]>; | |
export function allSettled<T>(promises: any[]): Promise<PromiseState<T>[]>; | |
/** | |
* `RSVP.hashSettled` is similar to `RSVP.allSettled`, but takes an object | |
* instead of an array for its `promises` argument. | |
* | |
* Unlike `RSVP.all` or `RSVP.hash`, which implement a fail-fast method, | |
* but like `RSVP.allSettled`, `hashSettled` waits until all the | |
* constituent promises have returned and then shows you all the results | |
* with their states and values/reasons. This is useful if you want to | |
* handle multiple promises' failure states together as a set. | |
*/ | |
export function hashSettled<T>(promises: Thenable<T>[]): Promise<PromiseState<T>[]>; | |
export function hashSettled<T>(promises: any[]): Promise<PromiseState<T>[]>; | |
/** | |
* Make a Promise that fulfills when any item fulfills, and rejects if any item rejects. | |
*/ | |
function race<R>(promises: Promise<R>[]): Promise<R>; | |
/** | |
* `RSVP.denodeify` takes a "node-style" function and returns a function that | |
* will return an `RSVP.Promise`. You can use `denodeify` in Node.js or the | |
* browser when you'd prefer to use promises over using callbacks. For example, | |
* `denodeify` transforms the following: | |
*/ | |
export function denodeify<T>(nodeFunction: Function, ...args: any[]): (...args: any[]) => Promise<T>; | |
/** | |
* Favor the Promise Constructor instead (if possible) | |
* | |
*/ | |
export function defer<T>(): Deferred<T>; | |
/** | |
`RSVP.Promise.reject` returns a promise rejected with the passed `reason`. | |
*/ | |
export function reject(reason?: any): Promise<any>; | |
/** | |
`RSVP.Promise.resolve` returns a promise that will become resolved with the | |
passed `value`. | |
*/ | |
export function resolve<T>(object: Thenable<T>): Promise<T>; | |
export function resolve<T>(object: T): Promise<T>; | |
/** | |
* `RSVP.filter` is similar to JavaScript's native `filter` method, except that it | |
* waits for all promises to become fulfilled before running the `filterFn` on | |
* each item in given to `promises`. `RSVP.filter` returns a promise that will | |
* become fulfilled with the result of running `filterFn` on the values the | |
* promises become fulfilled with. | |
*/ | |
export function filter<T>(promises: Thenable<T>[], filterFn: (value: any) => any): Promise<T[]>; | |
/** | |
`RSVP.rethrow` will rethrow an error on the next turn of the JavaScript event | |
loop in order to aid debugging. | |
Promises A+ specifies that any exceptions that occur with a promise must be | |
caught by the promises implementation and bubbled to the last handler. For | |
this reason, it is recommended that you always specify a second rejection | |
handler function to `then`. However, `RSVP.rethrow` will throw the exception | |
outside of the promise, so it bubbles up to your console if in the browser, | |
or domain/cause uncaught exception in Node. `rethrow` will also throw the | |
error again so the error can be handled by the promise per the spec. | |
*/ | |
export function rethrow(reason: any): void; | |
} |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Thank you for doing this, I'm amazed no one else has done it yet.
One change I had to make was to change the "hash" signature, as a hash gets an object, not an array:
export function hash(promises: any): Promise;
export function hash(promises: any): Promise;