plain-promise

Simple promise implementation

Made for Asynchronous JavaScript Interfaces presentation. To walk through this implementation start with Promises slide.

Provides just basic API and for clarity it's free from any micro and macro optimizations.

It's also proof of concept of how straightforward promise implementation can be with its design centered around done method.

Can safely be used in projects where code size is important, it's definitely one of the smallest promise implementations.

Things not covered in this implementation:

Rejection in case of circular resolution

Circular resolution of promises is in most cases result of a bug. Promise/A+ demands to throw TypeError when such action occurs. It's not in effect (at least currently) in ECMAScript 6 version. This implementation to stay away from additional complexity does not handle that as well. Resolving promise with itself leaves promise resolved but in forever locked unsettled state.

Support for foreign promises (thenables)

Promise/A+ requires support for foreign (not coming from same implementation) promise objects, it's also specified behavior for ECMAScript 6 promises. Foreign promises assimilation is tricky and to make sure things won't break (by really unexpected type of implementation) involves numerous security steps. This logic is not important to understand how promises work, so to keep things simple, this library recognizes just own promises.

High level functions all, race etc.

This implementation focuses just on core promise algorithm and any high level functions that operate on multiple promise objects are out of its scope.

Example Usage

Promise

Promise version of fs.readFile for node.js:

var fs = require('fs')
var Promise = require('plain-promise');

var readFilePromised = function (path, encoding) {
  return new Promise(function (resolve, reject) {
    fs.readFile(path, encoding, function (err, data) {
      if (err) reject(err);
      else resolve(data);
    });
  });
};

readFilePromised('/some/file.js', 'utf8').then(function (data) {
  return data.split('\n');
}).done(function (lines) {
 console.log("Lines of JS code", lines);
});;

Deferred

For reference also Deferred interface is provided (as seperate module)

Promise version of fs.readFile for node.js (constructed with Deferred interface)

var fs = require('fs')
var Deferred = require('plain-promise/deferred');

var readFilePromised = function (path, encoding) {
  var deferred = new Deferred();
  fs.readFile(path, encoding, function (err, data) {
    if (err) deferred.reject(err);
    else deferred.resolve(data);
    });
  });
  return deferred.promise
};

Installation

npm

$ npm install plain-promise

Browser

You can easily bundle plain-promise for browser with any CJS bundler (no favorite? Try: Browserify, Webmake or Webpack)

Tests

It passes all Promise/A+ tests, apart of 2.3.1 (Circular resolution case) and 2.3.3 (Support for foreign promises).

$ npm test