Daring Dassie

Pacta now complies with the ECMAScript 2015 Promise specification meaning the addition of the following functions:

• new Promise(executor);
• Promise#catch(onRejected);
• Promise.resolve(value);
• Promise.reject(reason);
• Promise.all(iterable);
• Promise.race(iterable).

The API should otherwise be entirely backward-compatible with previous versions of Pacta. This new, higher-level API is implemented in terms of the existing algebraic primitives such as map, onRejected, append, etc.

mapError has been removed from the documentation as it can be implemented purely in terms of onRejected but is still available.

onRejected now propagates resolved values (similar to the way map propagates rejected ones) so that it can be more easily chained.

Install the latest version via npm or bower:

$ npm install pacta
$ bower install pacta

Courageous Cuscus

Thanks to @benschulz, this patch release of Pacta fixes issues with chain, chainError and empty.

Specifically, chain and chainError now encapsulate exceptions raised if the functions passed to them don't return a promise themselves (e.g. if they throw an exception):

var p = Promise.of(1).chain(function () {
    throw new TypeError();
});

p.onRejected(function (r) {
    // r will now contain the TypeError thrown above
});

empty now works for unresolved promises as well as resolved ones:

var p = new Promise();

p.concat(p.empty()); // will no longer throw an error because p has no value

As ever, install the latest version via npm or Bower:

$ npm install pacta
$ bower install pacta

Clamouring Cuscus

Driven by contributions from Rodolphe Belouin, this version of Pacta adds two new functions: mapError and chainError. It also improves support for rejected promises when using map by propagating rejection.

var promise = new Promise();
promise.reject('Type error at line 214');

promise.mapError(function (x) {
  console.log(x);

  return 'Error: ' + x;
}); //=> Rejected promise with "Error: Type error at line 214" as reason

chainError can be used like so:

var criticalAjaxCallThatMayFail = function() {
    var p = new Promise();

    setTimeout(function () {
        if (Date.now() % 2 === 0) {
            p.reject('Request timed out');
        } else {
            p.resolve('This is a critical sentence.');
        }
    }, 2000);

    return p;
};

var getMessage = function (error) {
    if (error) {
        console.error('Error received: ' + error);
        console.log('Retrying...');
    }

    console.log('Sending request...');
    return criticalAjaxCallThatMayFail();
};

/* Retry 2 times if it fails */
getMessage()
    .chainError(getMessage)
    .chainError(getMessage)
    .map(console.log)
    .mapError(console.error);

As ever, consult the README for full usage and API documentation.

Burgeoning Binturong

An updated version of Pacta that is compliant with version 1.1 of the Promises/A+ specification.

An important API change is that Pacta will now encapsulate any uncaught exceptions within calls to map and onRejected. Any such error will now cause the resulting promise to be rejected. This is similar to Scala's Futures and Promises and how they deal with failure.

This allows for recovery from errors like so:

var p = new Promise();
p.map(function (x) {
    if (x === 'foo') {
        throw 'Unacceptable foo!';
    } else {
        return x;
    }
}).onRejected(function (reason) {
    if (reason === 'Fatal error') {
        throw 'No coming back from this!';
    } else {
        return 'Some safe default';
    }
}).map(console.log);

p.resolve('foo');
//=> Logs "Some safe default"

As ever, consult the README for full usage and API documentation.

Auspicious Axolotl

The first release of Pacta that is compatible with both node.js and web browsers (including AMD loaders such as RequireJS). As such, it can be installed via Bower with bower install pacta.

In node, simply require like so (note you no longer need .Promise as that is now the sole export of the library):

var Promise = require('pacta');

In a browser, simply include pacta.js which will provide you with a Promise global on the window object, e.g.:

<script src="/path/to/pacta.js"></script>
<script>
(function () {
    var p = new Promise();
    // ...
}());
</script>

Or use RequireJS to avoid the global variable:

require(["pacta"], function (Promise) {
    var p = new Promise();
    // ...
});

Browser support was tested back to Internet Explorer 6 (thanks to Rowan Manning's proclaim) but please raise issues if you have any problems.

As ever, consult the README for full usage and API documentation.