Diag Promise

Расширяет функционал нативных промисов, работает быстрее, чем Promise на Nodejs < 10 и bluebirdjs, а также работает без полифилов во всех старых браузерах.

Начало работы

var Promise = require("@diag/promise");

Для ES6:

import Promise from "@diag/promise";

Использование

В приведенном ниже примере показаны основные приемы использования библиотеки. Полную документацию по апи библиотеки можно найти в разделе документации.

var Promise = require("@diag/promise");

Promise.
    when(func()_or_Promise_or_value).

    promisify(func(resolveCallb, rejectCallb) {
        any_strange_old_async_code;
        (ok ? resolveCallb : rejectCallb)(value);
    }).
    then(
         func(value)_or_Promise_or_value,
         catchFunc(err)_or_value).
    truth(
          trueFunc(value),
          falseFunc(value),
          catchFunc(err)_or_value).
    lie(
          falseFunc(value),
          trueFunc(value),
          catchFunc(err)_or_value).

    caught(catchFunc(err)_or_value).

    lastly(finallyFunc() {...}).

    anyway(funcAndCatchFunc(value_or_err)).

    fork(
         condition,
         trueFunc(value),
         falseFunc(value)).

    each(func(arrElem) {...});

Promise.each(array, func(arrElem) {...});

Promise.thrown(errorObject);

Promise.all(
            parallelFunc_or_Promise_or_value1,
            parallelFunc_or_Promise_or_value2,
            ...).
	spread(func(result1, result2, ...) {...});

Promise.serial(
               func_or_Promise_or_value1,
               func_or_Promise_or_value2,
               ...);

Документация

new Promise();

Создает новый промис

.anyway(anyway);

То же, что .finally. Функция будет выполнена вне зависимости от того, успешно или с ошибкой выполнился промис.

.cancel();

Отменяет выполнение конкретного промиса

.cancelAll();

Отменяет выполнение всей цепочки промисов

.caught(reject);

Предоставляет промис только для rejection

.caughtReturn(reject);

Предоставляет промис только для Promise.$return

.clone();

Копирует промис

.each(func);

Исполняет переданную функцию для каждого значения массива

.exists(func);

Возвращает true, если функция-предикат вернула true на одном из элементов массива

.filter(func);

Работает как array.filter

.fork(expression, truth, lie);

Исполняет функцию truth или lying в зависимости от значения expression

.get(enquirer);

Передает текущий промис в аргумент функции enquirer

.ifPendingAfter(time, callback);

Исполняется находится ли промис в состоянии Pending через time милисекунд

.isCanceled();

Проверяет находится ли промис в состоянии Canceled

.isFulfilled();

Проверяет находится ли промис в состоянии Fulfilled

.isPending();

Проверяет находится ли промис в состоянии Pending

.isRejected();

Проверяет находится ли промис в состоянии Rejected

.lastly(anyway);

То же что .finally. Функция будет выполнена вне зависимости от того, успешно или с ошибкой выполнился промис. Пробрасывает значения и исключения из цепочки промисов.

.lie(lie, truth, reject);

Выполняется, если полученное значение цепочки было falsy

.log(enquirer);

Включает режим логирования с переданной функцией

.map(func);

Работает как .map

.promisify(executor);

Превращает асинхронную функцию с колбеками в Promise

.reject(reason, type);

Завершает выполнение промиса с исключением

.resolve(value, type);

Завершает выполнение промиса со значением

.spread(resolve, reject);

Раскрывает массив в аргументы

.tap(resolve);

Как then, только переданное на вход значение будет возвращено следующему в цепочке

.then(resolve, reject, flags, lie);

Предоставляет промис для resolution и/или для rejection

.timeout(time);

Исполняет промис спустя заданное время

.truth(truth, lie, reject);

Выполняется, если полученное значение цепочки было truthly

Promise.$break(value);

Используется только в итерируемых промисах. Работает как break в циклах.

Promise.$continue(value);

Используется только в итерируемых промисах. Работает как continue в циклах.

Promise.$return(value);

Служит для полного выхода из цепочки промисов (как thrown). Обработать результат функции можно в .caughtReturn()

Promise.all(promises);

Дожидается выполнения всех переданных значений/функций/промисов, возвращая массив результатов

Promise.args(array);

Возвращает промис, массив аргументов которого будет раскрыт в список аргументов следующего промиса

Promise.begin(begin, wrapped);

Оборачивает переданные функции в промис. begin() выполняется перед wrapped()

Promise.each(arrayOrCount, func, innerValue, flow);

Исполняет переданную функцию для каждого значения массива. Если установить параметр flow, то переданные функции будут выполняться асинхронно.

Promise.exists(array, func, flow);

Возвращает true, если функция-предикат вернула true на одном из элементов массива. Если установить параметр flow, то переданные функции будут выполняться асинхронно.

Promise.filter(array, func, flow);

Работает как array.filter. Если установить параметр flow, то переданные функции будут выполняться асинхронно.

Promise.fork(expression, truth, lying);

Исполняет функцию truth или lying в зависимости от значения expression

Promise.getTimeTracker();

Позволяет получить техническую информацию о времени работы промиса. Используется только в promisify

Promise.is(obj);

Определяет является ли переданный в аргументах obj промисом

Promise.map(array, func, flow);

Работает как [].map. Если установить параметр flow, то переданные функции будут выполняться асинхронно.

Promise.promise(wrapped);

Декорирует функцию, превращая результат выполнения в промис

Promise.promisify(executor, logName, timeLimit);

Превращает асинхронную функцию с колбеками в промис

Promise.props(array, flow);

Работает как Promise.map, но подходит не только для итерируиемых сущностей, но и для объектов. Если установить параметр flow, то переданные функции будут выполняться асинхронно.

Promise.reduce(array, func, accumulator);

Работает как [].reduce

Promise.reject(value);

Заканчивает выполнение промиса с исключением

Promise.resolve(value);

Завершает выполнение промиса со значением

Promise.serial(promises);

Дожидается выполнения всех переданных значений/функций/промисов, возвращая массив результатов. В отличии от Promise.all, все, что было переданно выполняется последовательно.

Promise.setLoggers(loggersObj);

Устанавливает собственные колбеки для логирования. По умолчанию логирование в консоль.

Promise.singleton(creator, update);

Создает промис только при его необходимости (реализует одноименный патерн)

Promise.thrown(reason, code);

Эмуляция throw. Нужна для ie, из-за его тяжёлых исключений (thrown в 1000 раз быстрее нативного throw).

Promise.timeout(timeMilliseconds, value);

Исполняет промис спустя заданное время

Promise.wait(condition, logName, timeLimit, period);

Выполняет цепочку промисов после выполнения функции condition, вызывая condition() каждые period мс (по умолчанию 100)

Promise.when(executor);

Возвращает результат переданной функции в виде промиса

Обратная связь

Обо всех багах/предложениях пишите на почту [email protected] с темой письма "diag/promise" или в канал Slack #diagnostics_support.

Лицензия

The MIT License (MIT)