Future 上的辅助方法

isFuture 方法

Future.isFuture(obj)

用来判断是否是 Future 的实例对象。

isPromise 方法

Future.isPromise(obj)

用来判断是否是 Future 或 ECMAScript 6 的 Promise 实例对象。

注意，该方法对其它符合 Promise/A+ 规范实现的 thenable 对象进行判断的返回值是 false。

如果你需要一个 promise 对象，保险的做法是用 Future.value() 方法包装一下。

toPromise 方法

Future.toPromise(obj)

如果 obj 是一个 Promise 对象，那么直接返回 obj，否则返回 Future.value(obj)。

all 方法

Future.all(array)

该方法返回一个 promise 对象，该 promise 对象会在数组参数内的所有 promise 都被设置为成功（fulfilled）状态时，才被设置为成功（fulfilled）状态，其值为数组参数中所有 promise 对象的最终展开值组成的数组，其数组元素与原数组元素一一对应。

具体使用方法可参见：MDN: Promise.all()

Future.all 方法与 Promise.all 方法在参数上有一点区别，Future.all 方法的数组参数本身也可以是一个值为数组的 promise 对象。

race 方法

Future.race(array)

该方法返回一个 promise 对象，这个 promise 在数组参数中的任意一个 promise 被设置为成功（fulfilled）或失败（rejected）后，立刻以相同的成功值被设置为成功（fulfilled）或以相同的失败原因被设置为失败（rejected）。

具体使用方法可参见：MDN: Promise.race()

Future.race 方法与 Promise.race 方法在参数上有一点区别，Future.race 方法的数组参数本身也可以是一个值为数组的 promise 对象。

join 方法

Future.join([arg1[, arg2[, arg3...]]]);

该方法的功能同 all 方法类似，但它与 all 方法的参数不同，我们来举例看一下它们的差别：

var Future = hprose.Future;
 
var promise = Future.resolve(3);
 
Future.all([true, promise])
      .then(function(values) {
          console.log(values);
       });
 
Future.join(true, promise)
      .then(function(values) {
          console.log(values);
       });

输出结果如下：

[ true, 3 ]
[ true, 3 ]

any 方法

Future.any(array)

该方法是 race 方法的改进版。

对于 race 方法，如果输入的数组为空，返回的 promise 对象将永远保持为待定（pending）状态。

而对于 any 方法，如果输入的数组为空，返回的 promise 对象将被设置为失败状态，失败原因是一个 RangeError 对象。

对于 race 方法，数组参数中的任意一个 promise 被设置为成功（fulfilled）或失败（rejected）后，返回的 promise 对象就会被设定为成功（fulfilled）或失败（rejected）状态。

而对于 any 方法，只有当数组参数中的所有 promise 被设置为失败状态时，返回的 promise 对象才会被设定为失败状态。否则，返回的 promise 对象被设置为第一个被设置为成功（fulfilled）状态的成功值。

settle 方法

Future.settle(array)

该方法返回一个 promise 对象，该 promise 对象会在数组参数内的所有 promise 都被设置为成功（fulfilled）状态或失败（rejected）状态时，才被设置为成功（fulfilled）状态，其值为数组参数中所有 promise 对象的 inspect 方法返回值，其数组元素与原数组元素一一对应。

例如：

var Future = hprose.Future;
 
var p1 = Future.resolve(3);
var p2 = Future.reject("x");
 
Future.settle([true, p1, p2])
      .then(function(values) {
          console.log(values);
       });

输出结果为：

[ { state: 'fulfilled', value: true },
  { state: 'fulfilled', value: 3 },
  { state: 'rejected', reason: 'x' } ]

attempt 方法

Future.attempt(handler[, arg1[, arg2[, arg3...]]]);

attempt 方法的作用是异步执行 handler 函数并返回一个包含执行结果的 promise 对象，handler 的参数分别为 arg1, arg2, arg3 …。参数可以是普通值，也可以是 promise 对象，如果是 promise 对象，则等待其变为成功（fulfilled）状态时再将其成功值代入 handler 函数。如果变为失败（rejected）状态，attempt 返回的 promise 对象被设置为该失败原因。如果参数中，有多个 promise 对象变为失败（rejected）状态，则第一个变为失败状态的 promise 对象的失败原因被设置为 attempt 返回的 promise 对象的失败原因。当参数中的 promise 对象都变为成功（fulfilled）状态时，handler 函数才会执行，如果在 handler 执行的过程中，抛出了异常，则该异常作为 attempt 返回的 promise 对象的失败原因。如果没有异常，则 handler 函数的返回值，作为 attempt 返回的 promise 对象的成功值。

var Future = hprose.Future;
 
function add(a, b) {
    return a + b;
}
 
var p1 = Future.resolve(3);
 
Future.attempt(add, 2, p1)
      .then(function(value) {
          console.log(value);
      });

输出结果为：

5

run 方法

Future.run(handler[, thisArg[, arg1[, arg2[, arg3...]]]]);

run 方法跟上面的 attempt 方法功能类似，唯一的区别是 run 方法的第二个参数为 thisArg，他表示 handler 的执行上下文。当 thisArg 的值为 undefine 时，行为跟 attempt 方法完全一致。

例如：

var Future = hprose.Future;
 
function add(a, b) {
    return a + b;
}
 
var p1 = Future.resolve(3);
 
Future.run(console.log, console, Future.attempt(add, 2, p1));

输出结果为：

5

wrap 方法

Future.wrap(handler[, thisArg]);

wrap 方法返回一个包装好的函数，该函数的执行方式跟使用 Future.run 的效果一样。例如：

var Future = hprose.Future;
 
var add = Future.wrap(function(a, b) {
    return a + b;
});
 
var log = Future.wrap(console.log, console);
 
var p1 = Future.resolve(3);
 
log(add(2, p1));

输出结果为：

5

forEach 方法

Future.forEach(array, callback[, thisArg])

该方法你可以认为是 Array.forEach 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。如果在 callback 回调中抛出了异常，则该方法返回的 promise 对象也被设置为失败（rejected）状态，失败原因被设置为抛出的异常值。

var Future = hprose.Future;
 
function logArrayElements(element, index, array) {
  console.log('a[' + index + '] = ' + element);
}
 
// Note elision, there is no member at 2 so it isn't visited
Future.forEach([2, Future.value(5), , 9], logArrayElements);

输出结果为：

a[0] = 2
a[1] = 5
a[3] = 9

every 方法

Future.every(array, callback[, thisArg])

该方法你可以认为是 Array.every 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。如果在 callback 回调中抛出了异常，则该方法返回的 promise 对象也被设置为失败（rejected）状态，失败原因被设置为抛出的异常值。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
function isBigEnough(element, index, array) {
  return element >= 10;
}
 
var a1 = [12, Future.value(5), 8, Future.value(130), 44];
var a2 = [12, Future.value(54), 18, Future.value(130), 44];
var a3 = Future.value(a1);
var a4 = Future.value(a2);
log(Future.every(a1, isBigEnough));   // false
log(Future.every(a2, isBigEnough));   // true
log(Future.every(a3, isBigEnough));   // false
log(Future.every(a4, isBigEnough));   // true

输出结果为：

false
true
false
true

some 方法

Future.some(array, callback[, thisArg])

该方法你可以认为是 Array.some 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。如果在 callback 回调中抛出了异常，则该方法返回的 promise 对象也被设置为失败（rejected）状态，失败原因被设置为抛出的异常值。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
function isBiggerThan10(element, index, array) {
  return element > 10;
}
 
var a1 = [2, Future.value(5), 8, Future.value(1), 4];
var a2 = [12, Future.value(5), 8, Future.value(1), 4];
var a3 = Future.value(a1);
var a4 = Future.value(a2);
log(Future.some(a1, isBiggerThan10));   // false
log(Future.some(a2, isBiggerThan10));   // true
log(Future.some(a3, isBiggerThan10));   // false
log(Future.some(a4, isBiggerThan10));   // true

输出结果为：

false
true
false
true

filter 方法

Future.filter(array, callback[, thisArg])

该方法你可以认为是 Array.filter 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。如果在 callback 回调中抛出了异常，则该方法返回的 promise 对象也被设置为失败（rejected）状态，失败原因被设置为抛出的异常值。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
function isBigEnough(value) {
  return value >= 10;
}
 
var a1 = [12, Future.value(5), 8, Future.value(130), 44];
var a2 = Future.value(a1);
log(Future.filter(a1, isBigEnough));
log(Future.filter(a2, isBigEnough));

输出结果为：

[ 12, 130, 44 ]
[ 12, 130, 44 ]

map 方法

Future.map(array, callback[, thisArg])

该方法你可以认为是 Array.map 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。如果在 callback 回调中抛出了异常，则该方法返回的 promise 对象也被设置为失败（rejected）状态，失败原因被设置为抛出的异常值。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
var numbers = [1, Future.value(4), Future.value(9)];
log(Future.map(numbers, Math.sqrt));
log(Future.map(numbers, function(num) {
  return num * 2;
}));

输出结果为：

[ 1, 2, 3 ]
[ 2, 8, 18 ]

reduce 方法

Future.reduce(array, callback[, initialValue])

该方法你可以认为是 Array.reduce 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。如果在 callback 回调中抛出了异常，则该方法返回的 promise 对象也被设置为失败（rejected）状态，失败原因被设置为抛出的异常值。

initialValue 的值也可以是一个 promise 对象。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
var numbers = [Future.value(0), 1, Future.value(2), 3, Future.value(4)];
 
function callback(previousValue, currentValue, index, array) {
  return previousValue + currentValue;
}
 
log(Future.reduce(numbers, callback));
log(Future.reduce(numbers, callback, 10));
log(Future.reduce(numbers, callback, Future.value(20)));

输出结果为：

10
20
30

reduceRight 方法

Future.reduceRight(array, callback[, initialValue])

该方法你可以认为是 Array.reduceRight 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。如果在 callback 回调中抛出了异常，则该方法返回的 promise 对象也被设置为失败（rejected）状态，失败原因被设置为抛出的异常值。

initialValue 的值也可以是一个 promise 对象。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
function concat(a, b) {
    return a.concat(b);
}
 
var array = [[0, 1], Future.value([2, 3]), Future.value([4, 5])];
 
log(Future.reduceRight(array, concat, []));
log(Future.reduceRight(array, concat, Future.value([6, 7])));

输出结果为：

[ 4, 5, 2, 3, 0, 1 ]
[ 6, 7, 4, 5, 2, 3, 0, 1 ]

indexOf 方法

Future.indexOf(array, searchElement[, fromIndex])

该方法你可以认为是 Array.indexOf 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。

searchElement 的值也可以是一个 promise 对象。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
var array = [1, Future.value(2), Future.value(3)];
 
log(Future.indexOf(array, 2));
log(Future.indexOf(array, Future.value(3), 1));
log(Future.indexOf(array, 1, 1));

输出结果为：

1
2
-1

lastIndexOf 方法

Future.lastIndexOf(array, searchElement[, fromIndex])

该方法你可以认为是 Array.lastIndexOf 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。

searchElement 的值也可以是一个 promise 对象。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
var array = [1, Future.value(2), Future.value(3)];
 
log(Future.lastIndexOf(array, 2));
log(Future.lastIndexOf(array, Future.value(3), 1));
log(Future.lastIndexOf(array, 1, 1));

输出结果为：

1
-1
0

includes 方法

Future.includes(array, searchElement[, fromIndex])

该方法你可以认为是 Array.includes 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。

searchElement 的值也可以是一个 promise 对象。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
var array = [1, Future.value(2), Future.value(3)];
 
log(Future.includes(array, 2));
log(Future.includes(array, Future.value(3), 1));
log(Future.includes(array, 1, 1));

输出结果为：

true
true
false

find 方法

Future.find(array, predicate[, thisArg])

该方法你可以认为是 Array.find 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。predicate 是一个回调方法。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
function isPrime(element, index, array) {
  var start = 2;
  while (start <= Math.sqrt(element)) {
    if (element % start++ < 1) {
      return false;
    }
  }
  return element > 1;
}
 
var array1 = [4, Future.value(6), 8, Future.value(12)];
var array2 = [4, Future.value(5), 7, Future.value(12)];
 
log(Future.find(array1, isPrime));
log(Future.find(array2, isPrime));

输出结果为：

undefined
5

findIndex 方法

Future.findIndex(array, predicate[, thisArg])

该方法你可以认为是 Array.findIndex 的 promise 版本，其中参数 array 可以是一个包含了 promise 元素的数组，也可以是一个包含了数组的 promise 对象。返回值是一个 promise 对象。如果参数数组中的 promise 对象为失败（rejected）状态，则该方法返回的 promise 对象被设置为失败（rejected）状态，且设为相同失败原因。predicate 是一个回调方法。

var Future = hprose.Future;
 
var log = Future.wrap(console.log, console);
 
function isPrime(element, index, array) {
  var start = 2;
  while (start <= Math.sqrt(element)) {
    if (element % start++ < 1) {
      return false;
    }
  }
  return element > 1;
}
 
var array1 = [4, Future.value(6), 8, Future.value(12)];
var array2 = [4, Future.value(5), 7, Future.value(12)];
 
log(Future.findIndex(array1, isPrime));
log(Future.findIndex(array2, isPrime));

输出结果为：

-1
1