Доброго времени суток. Сегодня я представляю вашему вниманию последнюю статью из цикла переводов "JavaScript Promises. There and back again." Данная статья содержит исчерпывающее описание API промисов и может служить справочным материалом, как для начинающих фронт-энд разработчиков, так и для тех, кто вполне знаком с концепцией, но еще не привык к нативному интерфейсу промисов. В любом случаи, если вас интересуют JavaScript-промисы, то обратите внимание на эту небольшую статью.

Описание API промисов



Все методы работают в Chrome, Opera и в Firefox Nightly, если не указано обратное. Polyfill предоставляет эту функциональность для всех браузеров.

Статические методы



Promise.cast(promise);
Возвращает промис(только если promise.constructor == Promise)
Внимание: На данный момент реализован только в Chrome и Opera

Promise.cast(obj);
Создает промис, который выполняется с результатом obj.
Внимание: На данный момент реализован только в Chrome и Opera

Promise.resolve(thenable);
Создает новый промис из thenable. Thenable — это промисообразный объект, то есть тот, у которого есть метод "then". Этот метод так же создает новый объект-промис, если, как параметр, ему передать JavaScript-промис. Таким образом, он менее удобен для приведения типов, чем Promise.cast.
Promise.resolve(obj);
Создает промис, который выполняется с результатом obj. В этом случаи, идентичен Promise.cast(obj).

Promise.reject(obj);
Создает промис, который завершается отказом, с результатом obj. Для консистентности и удобства отладки(то есть сохранение стека вызовов), в качестве obj рекомендуется использовать объекты Error.

Promise.all(array);
Создает промис, который выполниться, в случаи, если все элементы массива array выполняться, и завершится отказом, если(и когда) любой из элементов завершиться отказом. Каждый элемент массива, передается в функцию Promise.cast, таким образом, массив может состоять из смеси промисообразных объектов и обычных объектов. Результатом выполнения будет массив из результатов выполнения элементов входящего массива(в соответствующем порядке). Значение отказа будет соответствовать значению первого элемента завершившегося отказом.
Внимание: На данный момент реализован только в Chrome и Opera

Promise.race(array);
Содает промис, который выполниться, как только выполняться любой из элементов массива и завершиться отказом, как только любой из элементов завершиться отказом.
Внимание: На данный момент реализован только в Chrome и Opera. Кроме того, я немколько сомниваюсь в его полезности. Я бы предпочел иметь метод обратный к Promise.all, то есть такой, который будет завершаться отказом, только в случаи отказа всех элементов массива.

Конструктор



new Promise(function(resolve, reject) {});

Параметры

resolve(thenable)
Ваш промис будет выполнен/завершится отказом, на основании результата выполнения thenable(с тем же результатом и значением)

resolve(obj)
Ваш промис будет выполнен со значением obj

reject(obj)
Ваш промис завершается отказом со значением obj. Для консистентности и удобства отладки(то есть сохранение стека вызовов), в качестве obj рекомендуется использовать объекты Error. Любые ошибки выброшенные в процессе выполнения функции-конструктора, будут автоматически переданы в reject().

Методы экземпляра



promise.then(onFulfilled, onRejected)
onFulfilled вызывается, в случаи(и в тот момент), когда промис выполняется.
onRejected вызывается, в случаи(и в тот момент), когда промис завершится отказом.
Оба параметра необязательны, в случаи, если любой/оба опущены, то следующий в цепочке onFulfilled/onRejected будет вызван. Обе функции принимают единственный параметр, значение выполнения или причину отказа. "then" возвращает новый промис, соответствующий значению, возвращаемому из onFulfilled/onRejected после обработки методом Promise.resolve. В случаи возникновения в одной из этих функций ошибки, будет возвращен промис, завершающийся отказом со значением равным выброшенному объекту ошибке.

promise.catch(onRejected)
Синтаксический сахар для promise.then(undefined, onRejected)


Хочу от души поблагодарить Аннэ ван Кестерен, Доменика Дениколу, Тома Ашворса, Реми Шарпа, Эдди Османи, Артуру Эвансу и Ютака Хирано, которые вычитали это и внесли свои правки и рекомендации.
Так же, благодарю Матиаса Байненса, за дополнения различных частей этой статьи.
6

Комментарии

Для того, чтоб оставлять комментарии или зарегистрируйтесь.