ris0 / promise_deferred

Promise library

Pledge.js

Make a promise: build a deferral-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 deferral-style promise library similar to AngularJS's $q service (based on the Q library by Kris Kowal & Domenic Denicola), 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. Assuming that is true, you can globally-install the Testem spec runner with:

npm install -g testem

Next, you'll need to clone this repo to your local machine and cd into it:

git clone https://github.com/glebec/make-promise.git
cd make-promise

Then to execute the spec, simply run testem in that directory and open the link displayed in your terminal. 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.

Associated learning materials

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

$q and the state of the art

There are multiple proposed CommonJS promise standards, one leading standard Promises/A+, and upcoming native ES6 browser implementations. Developers of the MEAN stack should become familiar with AngularJS's $q service, a lightweight adaptation of the Q library. Bluebird is also making waves as a highly-performant and powerful library.

Adding to the potential confusion, $q has two possible ways to generate promises: simplified ES6-style constructors, and CommonJS-style deferreds. We will study deferreds because they are more explicit and include a useful method, .notify(). If you can grasp the deferral model, the constructor model will be comparatively straightforward.

Warning

jQuery gurus beware! While jQuery has a version of promises through $.Deferred, that implementation differs from current standards and is considered flawed. See Kris Kowal’s guide.

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 follow strict standards terminology. For example, it treats "resolved" and "fulfilled" as synonyms and only uses the former; similarly, it considers a pledge's value as meaning either its fulfilled data or rejected 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

• 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

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

Angular and Related

• AngularJS documentation for $q
• AngularJS Corner: Using promises and $q to handle asynchronous calls
• Xebia: Promises and Design Patterns in AngularJS
• AngularJS / UI Router / Resolve