Skip to content

Instantly share code, notes, and snippets.

@Taytay
Last active November 18, 2016 21:52
Show Gist options
  • Save Taytay/2f66bc465e43a2f16efe to your computer and use it in GitHub Desktop.
Save Taytay/2f66bc465e43a2f16efe to your computer and use it in GitHub Desktop.
Type definitions for RSVP. Still needs unit tests.
// 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;
}
@richrout
Copy link

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;

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment