Promise chaining

The then method of a promise returns a new promise.

const promise = new Promise(resolve => setTimeout(resolve, 5000));

promise
    // 5 seconds later
    .then(() => 2)
    // returning a value from a then callback will cause
    // the new promise to resolve with this value
    .then(value => { /* value === 2 */ });

Returning a Promise from a then callback will append it to the promise chain.

function wait(millis) {
    return new Promise(resolve => setTimeout(resolve, millis));
}

const p = wait(5000).then(() => wait(4000)).then(() => wait(1000));
p.then(() => { /* 10 seconds have passed */ });

A catch allows a rejected promise to recover, similar to how catch in a try/catch statement works. Any chained then after a catch will execute its resolve handler using the value resolved from the catch.

const p = new Promise(resolve => {throw 'oh no'});
p.catch(() => 'oh yes').then(console.log.bind(console));  // outputs "oh yes"

If there are no catch or reject handlers in the middle of the chain, a catch at the end will capture any rejection in the chain:

p.catch(() => Promise.reject('oh yes'))
  .then(console.log.bind(console))      // won't be called
  .catch(console.error.bind(console));  // outputs "oh yes"

On certain occasions, you may want to “branch” the execution of the functions. You can do it by returning different promises from a function depending on the condition. Later in the code, you can merge all of these branches into one to call other functions on them and/or to handle all errors in one place.

promise
    .then(result => {          
        if (result.condition) {
            return handlerFn1() 
                .then(handlerFn2);
        } else if (result.condition2) {
            return handlerFn3()
                .then(handlerFn4);
        } else {
            throw new Error("Invalid result");
        }
    })
    .then(handlerFn5)
    .catch(err => {
        console.error(err);
    });

Thus, the execution order of the functions looks like:

promise --> handlerFn1 -> handlerFn2 --> handlerFn5 ~~> .catch()
         |                            ^
         V                            |
         -> handlerFn3 -> handlerFn4 -^

The single catch will get the error on whichever branch it may occur.

Found a mistake? Have a question or improvement idea? Let me know.

Promises:

* Syntax

* Remarks

* Introduction

* Promise chaining

* Waiting for multiple concurrent promises

* Reduce an array to chained promises

* Waiting for the first of multiple concurrent promises

* Promisifying functions with callbacks

* Error Handling

* Reconciling synchronous and asynchronous operations

* Delay function call

* Promisifying values

* Using ES2017 async / await

* forEach() with promises

* Performing cleanup with finally

* Asynchronous API request

Table Of Contents

0 Getting started

1 Comments

2 Basic data types

3 Built-in constants

4 Variables

5 Declarations and assignments

6 Reserved keywords

7 Data types in JavaScript

8 Strings

9 Escape sequences

10 Template Literals

11 Arrays

12 Objects

13 Prototypes objects

14 Classes

15 Variable coercion / conversion

16 Map

17 Set

18 Arithmetic Math

19 Bitwise operators

20 Bitwise operators

21 Unary Operators

22 Comparison operations

23 Conditions

24 Loops

25 Functions

26 Arrow functions

27 Date

28 Date comparison

29 Scope

30 AJAX

31 Promises

32 Regular Expression

33 Error Handling

34 Geolocation

35 Cookies

36 Intervals and timeouts

37 Generators

38 History of visited urls

39 Strict mode

40 Custom Elements

41 JSON

42 Binary Data

43 Web Storage

44 Fetch

45 Modules

46 Screen

47 Inheritance

48 Timestamps

49 Destructuring assignment

50 Web Worker

51 Debugging

52 Notifications API

53 WebSockets

54 Web Cryptography API

55 Async functions, async / await

56 Constructor functions

57 execCommand and contenteditable

58 Performance Tips

59 Design patterns

60 requestAnimationFrame

61 Method chaining

62 Global error handling in browsers

63 File API, blobs and FileReaders

64 Console

65 Tail call optimization

66 Detecting browser

67 Enumerations

68 Symbols

69 Localization

70 Selection API

71 Callbacks

72 Functional JavaScript

73 Modals

74 Data attributes

75 Event Loop

76 Events

77 Data manipulation

78 BOM Browser Object Model

79 Unit Testing

80 Linters for ensuring code quality

81 Automatic Semicolon Insertion

82 IndexedDB

83 Anti-patterns

84 Navigator Object

85 Modularization techniques

86 Proxy

87 Same origin policy, cross-origin communication

88 postMessage and MessageEvent

89 WeakMap

90 WeakSet

91 Behaviroal Design Patterns

92 Server-sent events

93 Async iterators

94 Namespacing

95 Evaluating JavaScript

96 Memory efficiency

97 How to make iterator usable inside async callback function

98 Context this

99 Setters and getters

100 Vibration API

101 Fluent API

102 Tilde

103 Security issues

104 Get and set CSS custom variables

105 Contributors