blear.utils.plan

1Introduction
2Example
3Static
- 3.1.taskify(fn): task
4Prototype
5Dependencies
6Reference

1Introduction

description：（同步、异步、promise）任务的串、并行计划（流程控制）
author：ydr.me
create：2017-01-08 14:16
update：2017-01-08 14:16
github：https://github.com/blearjs/blear.utils.plan

2Example

var plan = require('blear.utils.plan');

plan 是一个同、异步、promise 任务的串、并行流程处理工具。 plan 是自动实例化的，虽然他是一个 class。

2.1串行计划

plan
    // 异步任务
    .task(function(next) {
        setTimeout(next, 100, null, 1);
    })
    // 同步任务
    .taskSync(function(prev) {
        // 2 + 1
        return 2 + prev;
    })
    // 许诺任务
    .taskPromise(function(prev) {
        return new Promise(function(resolve) {
            // 3 + 3
            resolve(3 + prev);
        });
    })
    // 循环异步任务
    .each([4, 5], function(index, val, next, prev) {
        // 第 1 次：4 + 6
        // 第 2 次：5 + 10
        setTimeout(next, 100, null, val + prev);
    })
    // 循环同步任务
    .eachSync([6, 7], function(index, val, prev) {
        // 第 1 次：6 + 15
        // 第 2 次：7 + 21
        return val + prev;
    })
    // 循环许诺任务
    .eachPromise([8, 9], function(index, val, prev) {
        return new Promise(function(resolve) {
            // 第 1 次：8 + 28
            // 第 2 次：9 + 36
            resolve(val + prev);
        });
    })
    .serial()
    .try(function (ret) {
        // ret === 45
    });

2.2并行计划

plan
    // 异步任务
    .task(function(next) {
        // 第 1 个结果：1
        setTimeout(next, 100, null, 1)
    })
    // 同步任务
    .taskSync(function() {
        // 第 2 个结果：2
        return 2;
    })
    // 许诺任务
    .taskPromise(function() {
        // 第 3 个结果：3
        return new Promise(function(resolve) {
            resolve(3);
        });
    })
    // 循环异步任务
    .each([4, 5], function(index, val, next) {
        // 第 4 个结果：4
        // 第 5 个结果：5
        setTimeout(next, 100, null, val);
    })
    // 循环同步任务
    .eachSync([6, 7], function(index, val) {
        // 第 6 个结果：6
        // 第 7 个结果：7
        return val;
    })
    // 循环许诺任务
    .eachPromise([8, 9], function(index, val) {
        return new Promise(function(resolve) {
            // 第 8 个结果：8
            // 第 9 个结果：9
            resolve(val);
        });
    })
    .parallel()
    .try(function (ret1, ret2, ret3, ret4, ret5, ret6, ret7, ret8, ret9) {
        // ret1 === 1
        // ret2 === 2
        // ret3 === 3
        // ret4 === 4
        // ret5 === 5
        // ret6 === 6
        // ret7 === 7
        // ret8 === 8
        // ret9 === 9
    });

2.3竞速计划

取最快执行的结果，无论失败还是成功。

plan
    // 执行的更快
    .task(function (next) {
        setTimeout(next, 100, new Error('1'));
    })
    .task(function (next) {
        setTimeout(next, 200, null, 2);
    })
    .race()
    .catch(function (err) {
        // err === Error: "1"
    });

2.4尽快计划

取最快执行的成功结果，如果没有取最慢的 Error。

plan
    // 执行的更快，但没有成功
    .task(function (next) {
        setTimeout(next, 100, new Error('1'));
    })
    .task(function (next) {
        setTimeout(next, 200, null, 2);
    })
    .any()
    .try(function (ret) {
        // ret === 2
    });

3Static

3.1`.taskify(fn): task`

将一个回调函数转换为 task 函数。

/**
 * 获取用户的基本信息
 * @param userId {number} 用户 id
 * @param callback {function} 回调
 */
var getUserInfo = function (userId, callback) {
    // 模拟异步情况
    setTimeout(function () {
        callback(null, {
            id: 1,
            username: 'yundanran',
            nickname: '#云淡然'
        });
    }, 1000);
};

/**
 * 获取用户的朋友信息
 * @param userId {number} 用户 id
 * @param limit {number} 朋友数量
 * @param callback {function} 回调
 */
var getUserFriends = function (userId, limit, callback) {
    // 模拟异步情况
    setTimeout(function () {
        callback(null, [{
            id: 2,
            username: 'Timcook',
            nickname: 'Timothy Donald Cook'
        }, {
            id: 3,
            username: 'billGates',
            nickname: 'Bill Gates'
        }]);
    }, 1000);
};

// 计划**并行**获取当前用户的用户信息和当前用户的朋友列表

// 没有 taskify 之前
plan
    .task(function(next) {
        getUserInfo(1, next);
    })
    .task(function(next) {
        getUserFriends(1, 2, next);
    })
    .parallel()
    .try(function (userInfo, userFriends) {
        // ...
    })
    .catch();

// taskify 之后
plan
    .task(plan.taskify(getUserInfo, 1))
    .task(plan.taskify(getUserFriends, 1, 2))
    .parallel()
    .try(function (userInfo, userFriends) {
        // ...
    })
    .catch();

4Prototype

4.1`#task(asyncTask(next(err, result), prev)): plan`

定义一个异步任务，链式调用返回 plan。

plan.task(function asyncTask(next, prev) {
    // 异步操作……
    next(err, result);
});

4.1.1`asyncTask`

类型：Function
说明：任务处理，如果是串行，则将执行 next 传给下一个任务，否则传到终点

4.1.1.1`asyncTask: next(err, result)`

类型：Function
说明：如果是串行则传给下一个任务，否则传给终点

4.1.1.1.1`asyncTask: next: this`

类型：null

4.1.1.1.2`asyncTask: next: err`

类型：Error
说明：如果错误的话为 Error 实例，否则为 null

4.1.1.1.3`asyncTask: next: result`

类型：*
说明：结果，如果是串行则传给下一个任务，否则传给终点

4.1.1.2`asyncTask: prev`

类型：*
说明：上一个任务结果，如果是串行的话

4.2`#taskSync(syncTask(prev): result): plan`

定义一个同步任务，链式调用返回 plan。

plan.taskSync(function syncTask(prev) {
    // 同步操作……
    return err || result;
});

4.2.1`syncTask`

类型：Function
说明：任务处理，如果是串行，则将返回值传给下一个任务，否则传到终点

4.2.1.1`syncTask: prev`

类型：*
说明：上一个任务结果，如果是串行的话

4.2.1.2`syncTask(): result`

类型：Error | *
说明：同步任务执行结果，如果执行错误，返回 Error 实例

4.3`#taskPromise(promiseTask(prev): promise): plan`

定义一个许诺任务，链式调用返回 plan。

plan.taskPromise(function promiseTask(prev) {
    // 返回一个 promise
    return new Promise();
});

4.3.1`promiseTask`

类型：Function
说明：任务处理，如果是串行，则将返回值传给下一个任务，否则传到终点

4.3.1.1`promiseTask: prev`

类型：*
说明：上一个任务结果，如果是串行的话

4.3.1.2`promiseTask(): promise`

类型：Promise
说明：许诺任务返回一个 Promise 实例

4.4`#each(list, asyncTasker(index, val, next(err, result)), prev): plan`

循环处理异步任务，链式调用返回 plan。

plan.each(['a', 'b'], function(index, val, next, prev) {
    // 异步操作……
    next(err || result);
});

4.4.1`list`

类型：Array | Object
说明：集合，数组、类数组或对象

4.4.2`syncTasker`

类型：Function
说明：任务处理

4.4.2.1`syncTasker: this`

类型：null

4.4.2.2`syncTasker: keyIndex`

类型：Number | String
说明：如果是对象，则为 String，否则为 Number

4.4.2.3`syncTasker: val`

类型：*
说明：遍历的集合值

4.4.2.4`syncTasker: next`

类型：Function
说明：如果是串行则传给下一个任务，否则传给终点

4.4.2.4.1`syncTasker: next: err`

类型：Error
说明：如果错误的话为 Error 实例，否则为 null

4.4.2.4.2`syncTasker: next: result`

类型：*
说明：结果，如果是串行则传给下一个任务，否则传给终点

4.4.2.5`syncTasker: prev`

类型：*
说明：上一个任务的结果，如果是串行的话

4.5`#eachSync(list, syncTasker(keyIndex, val, prev): result): plan`

循环处理异步任务，链式调用返回 plan。

plan.eachSync(['a', 'b'], function(index, val, prev) {
    // 同步操作……
    return err || result;
});

4.5.1`list`

类型：Array | Object
说明：集合，数组、类数组或对象

4.5.2`syncTasker`

类型：Function
说明：任务处理，如果是串行，则将返回值传给下一个任务，否则传到终点

4.5.2.1`syncTasker: this`

类型：null

4.5.2.2`syncTasker: keyIndex`

类型：Number | String
说明：如果是对象，则为 String，否则为 Number

4.5.2.3`syncTasker: val`

类型：*
说明：遍历的集合值

4.5.2.4`syncTasker: prev`

类型：*
说明：上一个任务结果，如果是串行的话

4.5.2.5`syncTasker(): result`

类型：Error || *
说明：如果错误的话为 Error 实例，否则为任务执行结果

4.6`#eachPromise(list, promiseTasker(keyIndex, val, prev): promise): plan`

循环处理许诺任务，链式调用返回 plan。

plan.eachPromise(['a', 'b'], function(index, val, prev) {
    // 返回一个 promise
    return new Promise();
});

4.6.1`list`

类型：Array | Object
说明：集合，数组、类数组或对象

4.6.2`promiseTasker`

类型：Function
说明：任务处理，如果是串行，则将返回值传给下一个任务，否则传到终点

4.6.2.1`promiseTasker: this`

类型：null

4.6.2.2`promiseTasker: keyIndex`

类型：Number | String
说明：如果是对象，则为 String，否则为 Number

4.6.2.3`promiseTasker: val`

类型：*
说明：遍历的集合值

4.6.2.4`promiseTasker: prev`

类型：*
说明：上一个任务结果，如果是串行的话

4.6.2.5`promiseTasker(): promise`

类型：Promise
说明：返回一个 Promise 实例

4.7`#repeat(times): plan`

再重复上一个任务的次数，如果上一步是 each 任务，只会重复最后一次遍历任务，链式调用返回 plan。

plan.taskSync(function taskA() {
    // 任务 A
}).repeat(2);
// 任务 A 将会被执行 1 + 2 = 3 次

4.7.1`times`

类型：Number
说明：再执行次数

4.8`#wait(timeout): plan`

空闲等待时间，单位 ms，链式调用返回 plan。

plan.wait(10);
// 等待 10ms

4.8.1`timeout`

类型：Number
说明：超时时间，单位 ms，异步

4.9`#serial(done(err, result)): plan`

串行执行任务，链式调用返回 plan。

plan
    .task(taskA)
    .task(taskB)
    .serial();
// 串行执行 taskA 和 taskB

4.9.1`done`

类型：Function
说明：完成后回调，如果有一个任务出错，则标记为失败

4.9.1.1`done: this`

类型：null

4.9.1.2`done: err`

类型：Error | null
说明：如果出错的话为 Error 实例，否则为 null

4.9.1.3`done: result`

类型：*
说明：一个结果

4.10`#parallel(done(err, ...result)): plan`

并行执行任务，链式调用返回 plan。

plan
    .task(taskA)
    .task(taskB)
    .parallel();
// 并行执行 taskA 和 taskB

4.10.1`done`

类型：Function
说明：完成后回调，如果有一个任务出错，则标记为失败

4.10.1.1`done: this`

类型：null

4.10.1.2`done: err`

类型：Error | null
说明：如果出错的话为 Error 实例，否则为 null

4.10.1.3`done: ...result`

类型：*
说明：任务数量个结果

4.11`#race(done(err, result)): plan`

竞速执行任务（取最快执行的结果，无论成功还是失败），链式调用返回 plan。

plan
    .task(taskA)
    .task(taskB)
    .race();
// 竞速执行 taskA 和 taskB

4.11.1`done`

类型：Function
说明：完成后回调，如果有一个任务出错，则标记为失败

4.11.1.1`done: this`

类型：null

4.11.1.2`done: err`

类型：Error | null
说明：如果出错的话为 Error 实例，否则为 null

4.11.1.3`done: result`

类型：*
说明：最快的结果

4.12`#any(done(err, result)): plan`

尽快执行任务（取最快执行的成功结果，如果没有，则返回最后一个 Error），链式调用返回 plan。

plan
    .task(taskA)
    .task(taskB)
    .any();
// 尽快执行 taskA 和 taskB

4.12.1`done`

类型：Function
说明：完成后回调，如果有一个任务出错，则标记为失败

4.12.1.1`done: this`

类型：null

4.12.1.2`done: err`

类型：Error | null
说明：如果出错的话为 Error 实例，否则为 null

4.12.1.3`done: result`

类型：*
说明：尽快的结果

4.13`#try(success(...result)): plan`

任务成功，链式调用返回 plan。

plan
    .task(taskA)
    .task(taskB)
    .serial()
    .try(function(resultAB) {
        // 串行执行成功
    });

plan
    .task(taskA)
    .task(taskB)
    .parallel()
    .try(function(resultA, resultB) {
        // 并行执行成功
    });

4.13.1`success`

类型：Function
说明：成功后回调

4.13.1.1`success: this`

类型：null

4.13.1.2`success: ...result`

类型：*
说明：如果是串行，则只有一个结果；如果是并行，则有任务数量个结果

4.14`#catch(error(err)): plan`

任务失败，链式调用返回 plan。

plan
    .task(taskA)
    .task(taskB)
    .serial()
    .catch(function(err) {
        // 串行执行失败
    });

plan
    .task(taskA)
    .task(taskB)
    .parallel()
    .catch(function(err) {
        // 并行执行失败
    });

4.14.1`error`

类型：Function
说明：失败后回调

4.14.1.1`error: this`

类型：null

4.14.1.2`error: err`

类型：Error | null
说明：如果出错的话为 Error 实例，否则为 null