uselesspickles / promise-delegate

Object-Oriented Promise Wrapper

PromiseDelegate

A simple type-safe wrapper around a Promise that provides an object-oriented interface for settling (resolving/rejecting) the promise.

Written in TypeScript, and distributed as both an ES module and CJS module with type definitions and source maps.

Contents

• PromiseDelegate
• Contents
• Why? (example)
• Installation
• Usage
  • Import
  • Instantiate
  • Properties
    • promise
    • settled
  • Methods
    • resolve
    • reject

Why? (example)

Sometimes code is designed/organized in such a way that implementing a Promise becomes very tedious. For example, if you need to instantiate and have a reference to your Promise before and separate from code that triggers the eventual settling of that Promise.

NOTE: I'm not promoting this as "good practice" in general if avoidable, but just acknowledging that it is sometimes practically/pragmatically unavoidable for a variety of reasons.

Here's an oversimplified example with a raw Promise:

class Foo {
    private readonly namePromise: Promise<string>;
    private resolveNamePromise!: (value: string) => void;

    constructor() {
        this.namePromise = new Promise<string>((resolve) => {
            // Store the resolve function so we can call it
            // later.
            this.resolveNamePromise = resolve;
        });
    }

    public getName(): Promise<string> {
        return this.namePromise;
    }

    public initStuff(): void {
        // hardcoded value for simplified example only
        this.resolveNamePromise("Bob");
    }
}

Here's the same example, but simplified by using PromiseDelegate:

import { PromiseDelegate } from "promise-delegate";

class Foo {
    private readonly namePromiseDelegate = new PromiseDelegate<string>();

    public getName(): Promise<string> {
        return this.namePromiseDelegate.promise;
    }

    public initStuff(): void {
        // hardcoded value for simplified example only
        this.namePromiseDelegate.resolve("Bob");
    }
}

Installation

Install via NPM:

npm i -s promise-delegate

Usage

Import

TypeScript/ES6:

import { PromiseDelegate } from "promise-delegate";

JavaScript:

const PromiseDelegate = require("promise-delegate").PromiseDelegate;

Instantiate

constructor<ValueType = void>(ignoreMultipleSettles: boolean = false)

Use the PromiseDelegate constructor to create a new PromiseDelegate with a corresponding new underlying Promise.

The ValueType type parameter specifies the type of resolve value. Defaults to void if unspecified, which represents a PromiseDelegate that can resolved without a value to simply indicate that something has finished.

The optional ignoreMultipleSettles parameter controls what happens if you attempt to settle (resolve/reject) the PromiseDelegate after it has already been settled:

• false: (default) An exception is thrown upon subsequent attempts to settle.
• true: Subsequent attempts to settle are silently ignored.

TypeScript:

// specify type of the promise value
const numberPromiseDelegate = new PromiseDelegate<number>();

// defaults to a `void` promise if type is unspecified
// (no resolved value; only signals the completion of something)
const voidPromiseDelegate = new PromiseDelegate();

JavaScript:

// You're on your own for the type of the value :)
const promiseDelegate = new PromiseDelegate();

Properties

promise

promise: Promise<ValueType>

A reference to the underlying Promise that can be settled (resolved/rejected) by the PromiseDelegate.

settled

settled: boolean;

True if this PromiseDelegate has been settled (resolved/rejected).

Methods

resolve

resolve(value: ValueType | PromiseLike<ValueType>): void

Resolves the underlying Promise with the specified value and marks this PromiseDelegate as settled.

Throws an error if this PromiseDelegate was already previously settled, and it was not instantiated with allowMultipleSettles = true.

NOTE: If ValueType is void, then the value parameter may be omitted completely, or must be exactly undefined if specified.

reject

reject(reason?: any): void

Rejects the underlying Promise with the specified reason and marks this PromiseDelegate as settled.

Throws an error if this PromiseDelegate was already previously settled, and it was not instantiated with allowMultipleSettles = true.