README.md

Tillthen

A minimal implementation of Promises/A+ tested on Promises/A+ Compliance Test Suite.

Please note that the current implementation conforms to v1.0 of Promises/A+ as expressed by v1.3.2 of the test suite. Compliance with Promises/A+ v1.1 (2.x versions of the test suite) is either work in progess or not happening, depending on the author's time constraints.

Tillthen is useful as a consise, easy-to-digest implementation of the spec. The source (excluding the UMD boilerplate which deals with exporting the module) is in the 100-line ballpark and an annotated version is also maintained. Having said that, real-world use is not within the author's original intentions as richer, battle-hardened libraries already exist.

Set up

Tillthen may be used as a CommonJS module on Node or in a browser, either through a plain <script> tag or as an AMD module. It will be automatically exported in the correct format depending on the detected environment. To get it, git clone git://github.com/biril/tillthen or npm install tillthen.

• When working in a browser, without an AMD module loader, include tillthen.js:

  ...
  <script type="text/javascript" src="tillthen.js"></script>
  ...

  and the module will be exposed as the global tillthen:

  console.log("working with version " + tillthen.version);

• require when working with CommonJS (e.g. Node). Assuming Tillthen is npm installed:

  var tillthen = require("tillthen");
  console.log("working with version " + tillthen.version);

• Or list as a dependency when working with an AMD loader (e.g. require.js):

  // Your module
  define(["tillthen"], function (tillthen) {
  	console.log("working with version " + tillthen.version);
  });

Usage

Besides the self-explanatory version property, Tillthen features a single method defer which may be used to create a deferred object, i.e. a pending promise featuring resolve and reject methods. As an example:

var deferred = tillthen.defer();
readFile("foo.txt", "utf-8", function (error, text) {
    if (error) {
        deferred.reject(new Error(error));
    } else {
        deferred.resolve(text);
    }
});
return deferred.promise;

defer.resolve(result) will resolve the promise with given result. Thus, it will fulfill the promise if result is a value, or cause it to assume result's (future) state if it's a promise itself. defer.reject(reason) will reject the promise with given reason.

deferred.promise exposes the deferred's underlying promise. Besides the then method, it features a state property exposing the current state, and a result property exposing the eventual fulfillment value or rejection reason.

Note that the deferred object may be used in place of the underlying promise as it also implements then and exposes state and result.

Testing

Tillthen is tested on Promises/A+ Compliance Test Suite. To run it, either make test or npm test (after npm installing).

License

Licensed and freely distributed under the MIT License (LICENSE.txt).

Copyright (c) 2013-2015 Alex Lambiris