Promise.mapSeries

Promise.mapSeries(
    Iterable<any>|Promise<Iterable<any>> input,
    function(any value, int index, int arrayLength) mapper
) -> Promise<Array<any>>

Принимая на вход итерируемый объект (например, массив) или промис, содержащий итерируемый объект, выполняет последовательную итерацию по всем значениям, применяя заданную функцию к каждому элементу. Если элемент является промисом, функция ожидает его разрешения перед продолжением. Функция-маппер имеет вид (value, index, arrayLength) , где value — текущий элемент (или его разрешенное значение, если это промис).

Если на любой итерации:

• Маппер возвращает промис или объект, поддерживающий метод then, он ожидает его разрешения перед переходом к следующей итерации.

• Текущий элемент итерации — неопределённый промис, этот промис будет ожидать разрешения перед запуском маппера.

• Текущий элемент итерации — отклоненный промис, итерация будет остановлена и также отклонена (с той же причиной).

Если все итерации успешно разрешаются, вызов Promise.mapSeries возвращает новый массив, содержащий результаты каждого выполнения mapper, в порядке следования.

Promise.mapSeries очень похож на Promise.each. Разница между Promise.each и Promise.mapSeries заключается в значении разрешения. Promise.mapSeries разрешается массивом, как описано выше, в то время как Promise.each разрешается массивом, содержащим разрешенные значения входных элементов (игнорируя результаты шагов итерации). Таким образом, Promise.each предназначен в основном для операций с побочными эффектами (поскольку выходы итератора по существу отбрасываются), как и встроенный метод .forEach() массивов, в то время как Promise.map предназначен для использования в качестве асинхронной версии встроенного метода .map() массивов.

Базовый пример:

// The array to be mapped over can be a mix of values and promises.
var fileNames = ["1.txt", Promise.resolve("2.txt"), "3.txt", Promise.delay(3000, "4.txt"), "5.txt"];

Promise.mapSeries(fileNames, function(fileName, index, arrayLength) {
    // The iteration will be performed sequentially, awaiting for any
    // promises in the process.
    return fs.readFileAsync(fileName).then(function(fileContents) {
        // ...
        return fileName + "!";
    });
}).then(function(result) {
    // This will run after the last step is done
    console.log("Done!")
    console.log(result); // ["1.txt!", "2.txt!", "3.txt!", "4.txt!", "5.txt!"]
});

Пример с отклоненным промисом в массиве:

// If one of the promises in the original array rejects,
// the iteration will stop once it reaches it
var items = ["A", Promise.delay(8000, "B"), Promise.reject("C"), "D"];

Promise.each(items, function(item) {
    return Promise.delay(4000).then(function() {
        console.log("On mapper: " + item);
    });
}).then(function(result) {
    // This not run
}).catch(function(rejection) {
    console.log("Catch: " + rejection);
});

// The code above outputs the following after 12 seconds (not 16!):
// On mapper: A
// On mapper: B
// Catch: C