ThenFail v0.4

Just another Promises/A+ implementation written in TypeScript that provides control flow tools like Promise.break, Promise.goto and disposable context.

Documentation

https://vilic.github.io/thenfail/doc

Install

npm install thenfail --save

Usage

import Promise from 'thenfail';

First call

ThenFail added a static then method for the first call, which is equivalent to Promise.resolve().then. While method Promise.resolve can also handle both normal value and promise-like value, using the static then method can make sure errors thrown are caught.

Promise
    .then(() => {
        if (foo) {
            return Promise.resolve('foo');
        } else if (bar) {
            return 'bar';
        } else {
            throw new Error();
        }
    })
    .then(value => {
        console.log(value);
    });

Create promise for event emitters

It is common to pipe a stream to another, taking piping a read stream to a write stream for example:

import * as FS from 'fs';

function copy(src: string, dest: string): Promise<void> {
    let readStream = FS.createReadStream(src);
    let writeStream = FS.createWriteStream(dest);

    readStream.pipe(writeStream);

    // Listen to `close` event of `writeStream` for fulfillment,
    // And listen to `error` event of `writeStream` as well as `readStream` for rejection.
    return Promise.for(writeStream, 'close', [readStream]);
}

Control flow features

Promise.break

Sometimes chaining promises could be annoying. For example:

Promise
    .then(() => {
        // step 1
    })
    .then(() => {
        // step 2
        if (noNeedToContinue) {
            // How to break here?
        }
    })
    .then(() => {
        // step 3.1
    }, reason => {
        // step 3.2
    })
    .then(() => {
        // step 4
    });

Now it's easy with ThenFail:

Promise
    .then(() => {
        // step 1
    })
    .then(() => {
        // step 2
        if (noNeedToContinue) {
            Promise.break;
        }
    })
    .then(() => {
        // step 3.1
    }, reason => {
        // step 3.2
    })
    .then(() => {
        // step 4
    })
    // enclose current context so it won't break too many.
    // it should be required if this could be directly chained somewhere else.
    // e.g. Returned as your method result.
    .enclose();

Promise.goto

Promise
    .then(() => {
        if (someCondition) {
            Promise.goto('label-a');
        } else {
            Promise.goto('label-b');
        }
    })
    .then(() => {
        // will not be called.
    })
    .label('label-a', () => {
        // step 3.1
    }, reason => {
        // step 3.2
    })
    .label('label-b', () => {
        // step 4
        // be aware that `goto` `"label-a"` won't prevent the execution of `"label-b"`.
    });

Promise context

There's situations we may want to cancel a promise chain, not only from inside (like using Promise.break), but also from outside:

page.on('load', () => {
    Promise
        .then(() => {
            // do some works...
        })
        .then(() => {
            // more works...
        })
        .then(() => {
            // ...
        });
});

page.on('unload', () => {
    // how can we cancel the promise chain?
});

With ThenFail, every promise has something called context. And if the context is disposed, the chain gets cancelled.

import { Context } from 'thenfail';

let context: Context;

page.on('load', () => {
    let promise = Promise
        .then(() => {
            // do some works...
        })
        .then(() => {
            // more works...
        })
        .then(() => {
            // ...
        });

    context = promise.context;
});

page.on('unload', () => {
    // dispose the context.
    if (context) {
        context.dispose();
        context = undefined;
    }
});

As what you might guess, The enclose method we mentioned before can mark current context as enclosed, and no longer accept new promises being under the same context. Which means a new context will be created when the then method is called.

Notable basics

States

Promises/A+ defines 3 states of a promise: pending, fulfilled and rejected. And only the pending state may transform to other states.

In the implementation of ThenFail, one more state skipped is added to specify the state of promises skipped by (fake) break, goto or a disposed context (However, the promise of which onfulfilled or onrejected has been called will not be skipped).

Resolve

Resolve is a process that may change the state of promise from pending to either fulfilled or rejected (not just the former state).

Terms

Promise

A promise in the documentation means the implementation of Promises/A+ in ThenFail.

Thenable/PromiseLike

A thenable or promise-like in the documentation means any other implementation that might act somewhat or exactly as we may expect a Promises/A or Promises/A+ implementation will.

Resolvable

A resolvable in the documentation means a thenable/promise-like or a normal value.

License

MIT License.