Plain (educational) promise implementation
Switch branches/tags
Nothing to show


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 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);


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



$ npm install plain-promise

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

Tests Build Status

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

$ npm test