Pledge.js

Make a promise: build an ES6-style implementation

Javascript promises are versatile tools for managing asynchronous results. They are portable and can attach handler functions to an eventual value, in multiple places. Compared to the dead end of standard async callbacks, they restore normal control flow — letting you chain results, return new values, and catch errors where most convenient.

One way to understand a thing is to build it yourself. This repo contains a Jasmine 2.0 test spec (split into thematic chapters). Following the spec in order, we will build a constructor-style promise library similar to native ECMAScript Promises, which we will call pledge.js. Our promises will be named $Promise to avoid triggering browser code. To focus on concepts, pledge.js will use public variables and not be standards-compliant (see below).

Instructions

You'll need Node.js and its package manager npm installed.

npm install # automatically builds the docs and opens them
npm test

You will see all the upcoming tests as "pending" (yellow). Start writing your own code in the pledge.js file. When you pass a test (green), change the next pending test from xit to it and save. This spec is iterative and opinionated; it is recommended that you do the tests in order and not xit out any previous specs. For debugging, you can "focus" Jasmine specs/suites with fit/fdescribe.

Associated learning materials

The repo contains the lecture slides and a .then flowchart, both in PDF format.

The state of the art

There were once multiple proposed CommonJS promise standards, but one leading standard Promises/A+ and now a compliant ES6 implementation won out. However, many developers use Bluebird for its faster-than-native optimizations and many clever features.

Historically, there have been two ways to generate new promises: CommonJS-style deferreds, and simplified ES6-style constructors. We will study the ES6 style, which has emerged as both the official and de facto standard.

Warning

Legacy jQuery codebases beware! While jQuery 2 has a version of promises through $.Deferred, that implementation differed from current standards and is considered flawed. See Kris Kowal’s guide. However, modern jQuery users rejoice! jQuery 3 now features P/A+ compliant promises.

Technical note on non-compliance

Our pledge.js library is intended to be a learning exercise. Some of the Promises/A+ standards and general OOP principles that pledge.js will not cover include:

Handler functions should always be called in an async wrapper (e.g. setTimeout). This makes their behavior more deterministic as they execute after a following synchronous code line.
The .then() function should handle assimilation of promises from other libraries ("thenables"). That makes promises interoperable.
A promise's state and value should not be directly editable (public), only influenced or accessed through the resolver functions and .then().
For simplicity's sake, pledge.js does not always follow strict standards terminology. For example, it considers a pledge's value as meaning either its fulfillment data or rejection reason.

These and other technical details are important, but for someone just beginning to learn they distract from the core behavior and use patterns.

External Resources for Further Reading

Canon

MDN: ES6 Promises (native functions)
The Promises/A+ Standard (with use patterns and an example implementation)

General

Strongloop: Promises in Node.js: an Alternative to Callbacks
You Don't Know JS: Async and Performance
HTML5 Rocks: Promises (deep walkthrough with use patterns)
Nolan Lawson: We Have a Problem with Promises
DailyJS: Javascript Promises in Wicked Detail (build an ES6-style implementation)
Promise Nuggets (use patterns)
Promise Anti-Patterns

Libraries

Bluebird (the current favorite for speed & features among many JS developers)
Kris Kowal & Domenic Denicola: Q (the library Angular's $q mimics; great examples & resources)

jn9cn/pledge_workshop