No description, website, or topics provided.
Clone or download
Pull request Compare This branch is 71 commits behind ga-wdi-boston:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
data
grunt
lib
snippets
spec
.editorconfig
.eslintrc.json
.gitignore
.remarkrc
CONTRIBUTING.md
Gruntfile.js
LICENSE
README.md
STYLE.md
notes.md
output.json
package.json

README.md

General Assembly Logo

Using Promises with the Node API

Prerequisites

Objectives

By the end of this, developers should be able to:

  • Explain the value of using promises instead of callback interfaces.
  • Read Node documentation that uses callbacks and translate that into implementations using promises.
  • Rewrite Node scripts using callbacks as scripts using promises.

Preparation

  1. Fork and clone this repository.
  2. Install dependencies with npm install.

Drawbacks to Callbacks

Asynchronous code necessitates callbacks. But dealing with lots of callbacks can be tricky:

  • Callbacks can be messy when they're nested: "callback hell". See lib/copy-json.js.
  • Each callback will have to handle it's own errors if necessary.
  • In complex programs, it will be hard to tell in what order callbacks fire.

Fortunately, there's a better way: Promises.

Lab: Research the Promises API

Promises are objects that represent steps in an asynchronous process. As of 2016, they are natively supported in Node.

Take a few minutes to read the API documentation on Promises. Note function signatures and argument types as you read. What arguments does a promise take when it is constructed?

  1. Promise Syntax
  2. Promise.prototype

Annotate-Along: Using Promises Instead of Callbacks

Promises offer several advantages over callbacks.

  • Promises, like callbacks, make asynchronicity explicit.
  • Promises, unlike callbacks, clarify the order of execution.
  • Promises are easier to read than callbacks.
  • Promises can simplify error handling.
// remember that callback is something you write, in this case to perform some
// processing on parsed JSON

const readJSON = function (filename, callback) {
  fs.readFile(filename, 'utf8', function (err, res) {
    if (err) {
      return callback(err) // what's going on here?
    }
    callback(null, JSON.parse(res)) // what if JSON.parse errors out?
  })
}

What are some weaknesses in this code? And the following?

const readJSON = function (filename, callback) { // 👀 here
  fs.readFile(filename, 'utf8', function (err, res) {
    if (err) {
      return callback(err) // pass the error from readFile
    }
    try {
      res = JSON.parse(res)
    } catch (ex) {
      return callback(ex) // pass the error from JSON.parse
    }
    callback(null, res) // don't pass the error, since we should have caught it
  })
}

What about this instead?

const readJSON = function (filename) { // <-- look here
  return new Promise((resolve, reject) => {
    fs.readFile(filename, { encoding: 'utf8' }, (err, res) => {
      if (err) {
        reject(err)
      } else {
        resolve(res)
      }
    })
  })
  .then((res) => {
    return JSON.parse(res)
  })
}

readJSON('./example.json')
  .then((pojo) => {
    modifierFunc(pojo)  // modify object
    return pojo // explicitly returns pojo
  })
  .catch((err) => { // handle error conditions
    console.error(err)
  })

That's too verbose. This is better:

const readJSON = function (filename) {
  return new Promise((resolve, reject) => {
    fs.readFile(filename, { encoding: 'utf8' }, (err, res) => {
      if (err) {
        reject(err)
      } else {
        resolve(res)
      }
    })
  })
  .then(JSON.parse) // what can we surmise about .then?
}

readJSON('./example.json')
  .then(modifierFunc) // modify object --> returns what callback(prev) returns
  .catch(console.error)  // handle error conditions

Rules for Promisifying Your Code:

1. Only ever pass a function as a call back. NEVER pass a function invocation!

Why? The difference is `.then()` _expects_ a callback. If you invoke the function, the `.then` gets a _value_ NOT a function to invoke later.
.then(JSON.parse)
// vs
.then(JSON.parse(json))

2. ALWAYS consider WHAT is being return from each block of a promise chain. Be explicit if you need to!

Why? Because some methods don't return what you expect them to. If you're ever unsure, BE SURE by making it explicit!

3. Safety third

Why? 'cause it should never be first or second.

4. Indent once at the start, and then lineup your .thens and .catchs

Why? Because formatting is important to humans.
startingFunction()
  .then(JSON.parse)
  .catch(console.error)

5. Never nest .thens--return out, and continue with the next .then in-line. Why? Because nesting .thens defeats the purpose of promises.

startingFunction()
  .then(JSON.parse)
  .then((pojo) => {
    functionThatReturnsAPromise(pojo)
      .then(dontDoThis!) // <-- creates promise hell!
  })
  .then(doThisInstead!) // <-- narrowly avoids promise hell!
  .catch(console.error)

Code-Along: Promisify copy-json.js

Lab: Promisify hey-yall.js

Lab: Promisify randomizer.js

Additional Resources

License

  1. All content is licensed under a CC­BY­NC­SA 4.0 license.
  2. All software code is licensed under GNU GPLv3. For commercial use or alternative licensing, please contact legal@ga.co.