Home

Awesome

Chained Promise: functional programming tools for recurring promises

Build Status Coverage Status Join the chat at https://gitter.im/google/chained-promise

We often find recurring patterns when handling asynchronous logic with promises, such as an HTTP endpoint that paginates and gives you a URL pointer to the next available dataset.

Chained Promise provides an extended Promise class that you can use to easily abstract out recurring patterns. See jsdocs for more detailed explanations.

Example

Suppose we are querying Wikipedia API to get the list of all linked pages from "Plato" page:

const apiPoint = "https://en.wikipedia.org/w/api.php?" +
  "action=query&prop=links&format=json&plnamespace=0&titles=Plato&pllimit=500";

With fetch we can turn the end point into a promise. Then we can use ChainedPromise to extend the promise:

import ChainedPromise from "chained-promise";

ChainedPromise.from(fetch(apiPoint))

First thing we want to do is to parse the resulting JSON:

  .flatMap((res) => res.json())

Now we have a promise that resolves into a JS object. Next we need to map the result into the format that ChainedPromise is expecting.

  .map((v) => {
    return {
      data: v.query.pages,
      next: v.continue ?
          fetch(apiPoint + '&plcontinue=' + encodeURIComponent(v.continue.plcontinue)) :
          {[ChainedPromise.DONE]: 'done fetching links from Plato page'}
    };
  })

The data field contains the material content of the value, while the next field contains either the promise to the next batch of data, or {[ChainedPromise.DONE]: lastNode} which ChainedPromise recognizes to be the terminal node.

Now that the chaining of the value has been configured, we can work on the series of data.

  .forEach((v) => {
    Object.keys(v.data).forEach((pageId) => {
      v.data[pageId].links.forEach((link) => {
        console.log(link.title);
      });
    });
  })

This executes the given callback function, and the result itself is a promise that resolves into the value of the terminal node when it reaches the end.

See the example project for the full example code. Also see jsdoc to ChainedPromise.ts for more explanation of other functions such as flatMap.

Disclaimer: This is not an official Google product.