How do I return a value from a promise chain so the next step can use it?

Think of each .then() as producing a new promise. What its fulfillment handler returns determines the value that the next fulfillment handler receives: an ordinary returned value is passed along, while a returned promise makes the chain wait for that promise’s outcome. Returning nothing gives the next handler undefined. [S1]

For example:

Promise.resolve(4)
  .then((number) => {
    return number * 3;
  })
  .then((result) => {
    console.log(result); // 12
    return result + 1;
  })
  .then((nextResult) => {
    console.log(nextResult); // 13
  });

Value flow: the first handler receives 4, returns 12, and the second receives 12. It returns 13, which the third receives. Each handler must return the value that should continue down the chain.

With a block-bodied arrow function, the braces require an explicit return if you want the handler to pass something back. Without it, the handler returns nothing, so the next step sees undefined; starting asynchronous work inside the handler does not by itself make the chain wait for that work. [S1]

Missing return:

getRecord()
  .then((record) => {
    saveRecord(record);
  })
  .then((savedRecord) => {
    console.log(savedRecord); // undefined
  });

If saveRecord(record) returns a promise and the next step depends on its outcome, return it:

getRecord()
  .then((record) => {
    return saveRecord(record);
  })
  .then((savedRecord) => {
    console.log(savedRecord); // outcome returned by saveRecord
  });

Here the second handler waits for the returned promise to settle, then receives its fulfillment value. This assumes saveRecord returns a promise that fulfills with a useful value; if it fulfills without a value, the next handler receives undefined.

Return the extracted value from the first handler. If getting that value itself involves a promise, return that promise too. For example, assuming loadSettings() returns a promise for an object with a theme property, and loadThemeDetails(theme) returns a promise:

loadSettings()
  .then((settings) => {
    return settings.theme;
  })
  .then((theme) => {
    console.log(theme); // the theme value
    return loadThemeDetails(theme);
  })
  .then((details) => {
    console.log(details); // fulfillment value from loadThemeDetails
  });

Value flow: loadSettings() fulfills with settings; the first handler returns settings.theme; the next receives that theme and returns a promise; the final handler receives that promise’s fulfillment value. Returning the promise is what connects the asynchronous result to the chain. [S1]

For a concise handler that returns one expression, you can omit braces: .then(settings => settings.theme). An expression-bodied arrow returns its expression. If you use braces, include return explicitly.

Read the chain from top to bottom and label each handler with two things: what it receives and what it returns. Then check every block-bodied handler. If a later step needs a value or asynchronous outcome from that handler, make sure the handler returns it.

A reusable annotation might look like this:

startTask()                         // fulfills with: input
  .then((input) => {                // receives: input
    return transform(input);        // returns: transformed value
  })
  .then((transformed) => {          // receives: transformed value
    return finishAsync(transformed); // returns: a promise
  })
  .then((finished) => {              // receives: finishAsync's fulfillment value
    showResult(finished);
  });

The names here are placeholders; replace them with your functions and values. The comments describe the intended flow, not guaranteed return values. Check what your actual functions return. In particular, returning a promise only helps if that promise fulfills with the value you expect; the return and waiting behavior does not establish what any application-specific function returns. [S1]