Interface IPromise<T>

Create a Promise object that represents the eventual completion (or failure) of an asynchronous operation and its resulting value. This interface definition, closely mirrors the typescript / javascript PromiseLike and Promise definitions as well as providing simular functions as that provided by jQuery deferred objects.

The returned Promise is a proxy for a value not necessarily known when the promise is created. It allows you to associate handlers with an asynchronous action's eventual success value or failure reason. This lets asynchronous methods return values like synchronous methods: instead of immediately returning the final value, the asynchronous method returns a promise to supply the value at some point in the future.

A Promise is in one of these states:

  • pending: initial state, neither fulfilled nor rejected.
  • fulfilled: meaning that the operation was completed successfully.
  • rejected: meaning that the operation failed.

A pending promise can either be fulfilled with a value or rejected with a reason (error). When either of these options happens, the associated handlers queued up by a promise's then method are called synchronously. If the promise has already been fulfilled or rejected when a corresponding handler is attached, the handler will be called synchronously, so there is no race condition between an asynchronous operation completing and its handlers being attached.

As the then() and catch() methods return promises, they can be chained.

interface IPromise<T> {
    catch<TResult>(onRejected?: ((reason: any) => TResult | IPromise<TResult>)): IPromise<T | TResult>;
    catch<TResult>(onRejected?: ((reason: any) => TResult | IPromise<TResult>)): PromiseLike<T | TResult>;
    catch<TResult>(onRejected?: ((reason: any) => TResult | IPromise<TResult>)): Promise<T | TResult>;
    finally(onfinally?: (() => void)): IPromise<T>;
    state?: string;
    then<TResult1, TResult2>(onResolved?: ((value: T) => TResult1 | IPromise<TResult1> | PromiseLike<TResult1>), onRejected?: ((reason: any) => TResult2 | IPromise<TResult2> | PromiseLike<TResult2>)): IPromise<TResult1 | TResult2>;
    then<TResult1, TResult2>(onResolved?: ((value: T) => TResult1 | IPromise<TResult1> | PromiseLike<TResult1>), onRejected?: ((reason: any) => TResult2 | IPromise<TResult2> | PromiseLike<TResult2>)): PromiseLike<TResult1 | TResult2>;
    then<TResult1, TResult2>(onResolved?: ((value: T) => TResult1 | IPromise<TResult1> | PromiseLike<TResult1>), onRejected?: ((reason: any) => TResult2 | IPromise<TResult2> | PromiseLike<TResult2>)): Promise<TResult1 | TResult2>;
}

Type Parameters

  • T

    Identifies the expected return type from the promise

Hierarchy

  • PromiseLike<T>
  • Promise<T>
    • IPromise

Properties

Methods

Properties

state?: string

Returns a string representation of the current state of the promise. The promise can be in one of four states.

  • "pending": The promise is not yet in a completed state (neither "rejected"; or "resolved").
  • "resolved": The promise is in the resolved state.
  • "rejected": The promise is in the rejected state.
let doResolve;
let promise: IPromise<any> = createSyncPromise((resolve) => {
doResolve = resolve;
});

let state: string = promise.state();
console.log("State: " + state); // State: pending
doResolve(true); // Promise will resolve synchronously as it's a synchronous promise
console.log("State: " + state); // State: resolved

Methods

  • Attaches a callback for only the rejection of the Promise.

    Type Parameters

    • TResult = never

    Parameters

    Returns IPromise<T | TResult>

    A Promise for the completion of the callback.

    const promise1 = createPromise((resolve, reject) => {
    throw 'Uh-oh!';
    });

    promise1.catch((error) => {
    console.error(error);
    });
    // expected output: Uh-oh!
  • Attaches a callback for only the rejection of the Promise.

    Type Parameters

    • TResult = never

    Parameters

    Returns PromiseLike<T | TResult>

    A Promise for the completion of the callback.

    const promise1 = createPromise((resolve, reject) => {
    throw 'Uh-oh!';
    });

    promise1.catch((error) => {
    console.error(error);
    });
    // expected output: Uh-oh!
  • Attaches a callback for only the rejection of the Promise.

    Type Parameters

    • TResult = never

    Parameters

    Returns Promise<T | TResult>

    A Promise for the completion of the callback.

    const promise1 = createPromise((resolve, reject) => {
    throw 'Uh-oh!';
    });

    promise1.catch((error) => {
    console.error(error);
    });
    // expected output: Uh-oh!
  • Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.

    Parameters

    • Optionalonfinally: (() => void)

      The callback to execute when the Promise is settled (fulfilled or rejected).

        • (): void
        • Returns void

    Returns IPromise<T>

    A Promise for the completion of the callback.

    function doFunction() {
    return createPromise((resolve, reject) => {
    if (Math.random() > 0.5) {
    resolve('Function has completed');
    } else {
    reject(new Error('Function failed to process'));
    }
    });
    }

    doFunction().then((data) => {
    console.log(data);
    }).catch((err) => {
    console.error(err);
    }).finally(() => {
    console.log('Function processing completed');
    });