README.md

Tillthen

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

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 authors original intentions as richer, tried 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).

Caveats / WTF

• Uses ES5 syntax, namely Object.defineProperties, to expose immutable properties and will therefore break on non-compliant browsers.

License

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

Copyright (c) 2013 Alex Lambiris