teepromise

TeePromise

TeePromise is a very simple utility subclass that makes promises more convenient to use in some situations by exposing resolve and reject on the promise object itself.

const tp = new TeePromise();

tp.resolve(5);                // resolve a value
tp.reject(new Error('oops')); // reject a value
await tp;                     // await a value

Some use cases include:

• Multiple callbacks already might call resolve and reject, and adding another callback to pass to the Promise constructor would make the code more difficult to read.
• A method is adding an entry to a job queue and then returning with results when the job is completed. You can include the TeePromise in your job entry and also return it.

Shortcomings:

• Could be seen as violating the interface segregation principle if you're passing a TeePromise to code that only uses the resolve, reject, or then. This could be mitigated in typescript applications by creating interfaces including only the reject and resolve methods, which conventionally would be named IResolver and IRejecter.

Compared with Promise.withResolvers():

Promise.withResolvers() - you get the promise, and separately resolve and reject.

const { promise, resolve } = Promise.withResolvers();
doSomethingAsync(value => resolve(value));
return promise;

TeePromise - you get a thenable which also implements resolve and reject.

const tp = new TeePromise();
doSomethingAsync(value => tp.resolve(value));
return tp;

Use Cases

Queue

In the implementation of a job queue, TeePromise makes it convenient to include resolve in an entry of the queue without introducing any unnecessary Promise constructor.

class SomeQueueMananger {

    // ...

    print (document) {
        const tp = new TeePromise();
        this.entries.push({
            ...entry,
            donePrinting: printCompletionInfo => {
                tp.resolve(printCompletionInfo);
            },
        });
        
        return tp;
    }
}

Dialog or modal

When a component must return a promise that is resolved or rejected only when the user acts (e.g. clicks OK or Cancel), TeePromise keeps the API simple.

function confirm (message) {
    const tp = new TeePromise();
    showModal({
        message,
        onOk: () => tp.resolve(true),
        onCancel: () => tp.resolve(false),
    });
    return tp;
}

Timeout or abort

TeePromise is useful when you need to reject a promise from outside, for example when implementing a timeout or an abort signal.

function withTimeout (promise, ms) {
    const tp = new TeePromise();
    promise.then(tp.resolve, tp.reject);
    const id = setTimeout(() => tp.reject(new Error('timeout')), ms);
    tp.then(() => clearTimeout(id), () => clearTimeout(id));
    return tp;
}

Callback-to-promise bridge

When wrapping a callback-based API, you can avoid the Promise constructor and pass resolve and reject directly into the callback.

function readFile (path) {
    const tp = new TeePromise();
    fs.readFile(path, (err, data) => {
        if (err) tp.reject(err);
        else tp.resolve(data);
    });
    return tp;
}