Util

工具

Description:

  • 工具

Source:
Since:
  • 1.0.0

Methods

(static) castArray(valueopt) → {Array}

Description:

  • 如果值不是数组，则将其转换为数组。

Source:
Since:
  • 1.0.0
Example
castArray('a'); // ["a"]

castArray(1); // [1]

castArray({ a: 1, b: 2}); // [{ a: 1, b: 2}]

castArray(); // []

castArray(undefined); // [undefined]

castArray(null); // [null]

const arr = [1, 2, 3];
castArray(arr); // [1, 2, 3]
console.log(arr === castArray(arr)); // true
Parameters:
Name Type Attributes Description
value * <optional>

要处理的值。
Returns:

转换后的数组。

Type
Array

(static) conforms(source) → {function}

Description:

  • 创建一个函数，调用 source 的属性名对应的断言函数与传入对象相对应属性名的值进行断言处理。如果都符合返回 true，否则返回 false。

Source:
Since:
  • 1.0.0
Example
const objs =  [
  { a: 1, b: 1 },
  { a: 2, b: 2 }
]

objs.filter(conforms({ b: value => value > 1 })); // [{ a: 2: b: 2 }]
Parameters:
Name Type Description
source Object

要断言属性是否符合的对象。
Returns:

新的函数。

Type
function

(static) conformsTo(object, source) → {boolean}

Description:

  • 通过调用断言 source 的属性与 object 的相应属性值，检查 object 是否符合 source。

Source:
Since:
  • 1.0.0
Example
const object = { a: 1, b: 2 }

conformsTo(object, { b: value => value > 1 }); // true

conformsTo(object, { b: value => value > 2 }); // false
Parameters:
Name Type Description
object Object

要检查的对象。
source Object

要断言属性是否符合的对象。
Returns:

如果 object 符合，返回 true，否则返回 false。

Type
boolean

(static) constant(value) → {function}

Description:

  • 创建一个返回 value 的函数。

Source:
Since:
  • 1.0.0
Example
const obj = { a: 1 }

const returnObj = constant(obj);

console.log(returnObj() === obj); // true
Parameters:
Name Type Description
value *

新函数返回的值。
Returns:

返回新的常量函数。

Type
function

(static) defaultTo(value, defaultValue) → {*}

Description:

  • 检查值以确定是否应在其位置返回默认值。如果值为 NaN null 或 undefined，返回 defaultValue。

Source:
Since:
  • 1.0.0
Example
defaultTo(undefined, 1); // 1

defaultTo(10, 1); // 10

defaultTo(null, undefined); // undefined
Parameters:
Name Type Description
value *

要检查的值。
defaultValue *

默认值。
Returns:

如果值为 NaN null 或 undefined，返回 defaultValue，否则返回 value。

Type
*

(static) eq(value, other, strictCheckopt) → {boolean}

Description:

  • 检查两个值是否相等。

    默认使用了 SameValueZero 做等值比较。如果 strictCheck=true 将使用 SameValue 做等值比较。

Source:
Since:
  • 1.0.0
See:
Example
eq(-0, 0); // true

eq(1, 1); // true

eq(NaN, NaN); // true

eq('a', 'a'); // true

const object = {a: 1};

eq(object, {a: 1}); // false

eq(object, object); // true

eq(-0, 0, true); // false
Parameters:
Name Type Attributes Default Description
value *

要比较的值。
other *

另一个要比较的值。
strictCheck boolean <optional>
 false

严格比较，区分 0 -0。默认 false。
Returns:

如果两个值相等，返回 true，否则返回 false。

Type
boolean

(static) gt(value, other) → {boolean}

Description:

  • 检查 value 是否大于 other。

Source:
Since:
  • 1.0.0
Example
gt(1, 3); // false

gt(3, 3); // false

gt(3, 1); // true
Parameters:
Name Type Description
value *

要比较的值。
other *

另一个要比较的值。
Returns:

如果 value 大于 other 返回 true，否则返回 false。

Type
boolean

(static) gte(value, other) → {boolean}

Description:

  • 检查 value 是否大于或等于 other。

Source:
Since:
  • 1.0.0
Example
gte(1, 3); // false

gte(3, 3); // true

gte(3, 1); // true
Parameters:
Name Type Description
value *

要比较的值。
other *

另一个要比较的值。
Returns:

如果 value 大于或等于 other 返回 true，否则返回 false。

Type
boolean

(static) guard(fn, shouldGuardopt)

Description:

  • 函数守卫。

Source:
Since:
  • 1.14.0
Example
guard(() => 42); // 42
await guard(() => Primise.resolve(42)); // 42

guard(() => { throw new Error() }); // undefined
await guard(() => Promise.reject()); // undefined
Parameters:
Name Type Attributes Description
fn function

要执行的函数。
shouldGuard function <optional>

函数守卫断言。如果返回 Truthy 表示需要守卫，否则不需要守卫。
Returns:

如果函数执行成功，正常返回结果；如果异步函数拒绝或抛出错误时，有函数守卫返回 undefined，否则抛出错误。

(static) identity(value)

Description:

  • 返回第一个参数。

Source:
Since:
  • 1.0.0
Example
const obj = { a: 1, b: 2 };

console.log(identity(obj) === obj); // true
Parameters:
Name Type Description
value *

任意值。
Returns:

返回 value。

(static) list(n, iterateeopt) → {Array}

Description:

  • 调用 iteratee n 次，每次调用返回的结果存入到数组中。

    iteratee 调用传入一个参数 index。

    注：原方法名为 times，自 v1.12.0 版本调整为 list。

Source:
Since:
  • 1.12.0
Example
list(3); // [0, 1, 2]

list(3, String); // ['0', '1', '2']

list(4, () => 0); // [0, 0, 0, 0]
Parameters:
Name Type Attributes Default Description
n number

调用 iteratee 的次数。
iteratee function <optional>
 identity

每次迭代调用的函数。默认 identity。
Returns:

调用结果的数组。

Type
Array

(static) lt(value, other) → {boolean}

Description:

  • 检查 value 是否小于 other。

Source:
Since:
  • 1.0.0
Example
lt(1, 3); // true

lt(3, 3); // false

lt(3, 1); // false
Parameters:
Name Type Description
value *

要比较的值。
other *

另一个要比较的值。
Returns:

如果 value 小于 other 返回 true，否则返回 false。

Type
boolean

(static) lte(value, other) → {boolean}

Description:

  • 检查 value 是否小于或等于 other。

Source:
Since:
  • 1.0.0
Example
lte(1, 3); // true

lte(3, 3); // true

lte(3, 1); // false
Parameters:
Name Type Description
value *

要比较的值。
other *

另一个要比较的值。
Returns:

如果 value 小于或等于 other 返回 true，否则返回 false。

Type
boolean

(static) noop()

Description:

  • 空函数，返回 undefined。

Source:
Since:
  • 1.0.0
Example
noop(); // undefined

(static) nthArg(nopt)

Description:

  • 创建一个函数，该函数返回第 n 个参数。如果 n 为负数，则返回从结尾开始的第 n 个参数。

Source:
Since:
  • 1.0.0
Example
const func1 = nthArg(1);

func1('a', 'b', 'c', 'd'); // 'b'

const func2 = nthArg(-2);

func2('a', 'b', 'c', 'd'); // 'c'
Parameters:
Name Type Attributes Default Description
n number <optional>
 0

要返回参数的索引值。默认 0。
Returns:

新函数。

(static) range(startopt, end, stepopt) → {Array.<number>}

Description:

  • 创建一个升序或降序的数字数组。

    如果省略 start 默认为 0。

Source:
Since:
  • 1.6.0
Example
range(4); // [0, 1, 2, 3]
range(-4); // [0, -1, -2, -3]
range(1, 5); // [1, 2, 3, 4]
range(0, 20, 5); // [0, 5, 10, 15]
range(0, -4, -1); // [1, 2, 3]
range(1, 4, 0); // [1, 2, 3]
range(0); // []
Parameters:
Name Type Attributes Default Description
start number <optional>
 0

开始值。默认 0。
end number

结束值。
step number <optional>

要增加或减少的值。如果值为 0，将视为无效参数。如果 start 在 end 之前。默认为 1，否则默认为 -1。
Returns:

从开始值（包含）到结束值（不包含）逐步递增或递减的数字数组。

Type
Array.<number>

(async, static) retry(fn, optionsopt)

Description:

  • 异步函数错误重试。

Source:
Since:
  • 1.14.0
Example
let count = 1;
const fn = () => ++count < 3 ? Promise.reject('error') : Promise.resolve('success');
const result = await retry(fn); // 'success';

try{
  // 延迟使用指数后退。
  await retry(verifySecret, { times: 100, backoff(count){ return count*count } })
}catch(err){
  console.log(err);
}
Parameters:
Name Type Attributes Description
fn function

异步函数。
options Object <optional>

配置项。

Properties
Name Type Attributes Default Description
times number <optional>
 3

异步函数发生错误，最多重试次数。默认 3。
delay number <optional>

重试延迟时长，单位毫秒。
backoff function <optional>

类似于延迟，便于实现指数后退。
exit function <optional>

主动退出断言。
Returns:

如果异步函数 resolve ，返回异步函数结果，否则抛出错误。

(static) sleep(msopt) → {Promise.<void>}

Description:

  • 异步方法中等待时间后继续执行。

Source:
Since:
  • 1.0.0
Example
async ()=>{
  await sleep();
  // do something
}

sleep(300).then(()=>{
  // do something
})
Parameters:
Name Type Attributes Default Description
ms number <optional>
 1000

等待时间，单位毫秒。默认 1000。
Returns:

异步对象。

Type
Promise.<void>

(static) toFinite(value) → {number}

Description:

  • 转换 value 为一个有限数字。

Source:
Since:
  • 1.0.0
Example
toFinite(3.2); // 3.2

toFinite('3.2'); // 3.2

toFinite(-0); // -0

toFinite('-0'); // -0

toFinite('0'); // 0

toFinite(NaN); // 0

toFinite(Infinity); // 1.7976931348623157e+308

toFinite(-Infinity); // -1.7976931348623157e+308
Parameters:
Name Type Description
value *

要转换的值。
Returns:

转换后的数字。

Type
number

(static) toInteger(value) → {number}

Description:

  • 转换 value 为一个整数。

    注意: 这个方法基于 ToIntegerOrInfinity ，区别在于 -0 会返回 -0。

Source:
Since:
  • 1.0.0
Example
toInteger(3.2); // 3

toInteger('3.2'); // 3

toInteger(-0); // -0

toInteger('-0'); // -0

toInteger('0'); // 0

toInteger(NaN); // 0

toInteger(Infinity); // Infinity

toInteger(-Infinity); // -Infinity
Parameters:
Name Type Description
value *

要转换的值。
Returns:

转换后的整数。

Type
number

(static) toLength(value) → {number}

Description:

  • 转换 value 为数组对象的长度整数。

Source:
Since:
  • 1.0.0
See:
Example
toLength(3.2); // 3

toLength('3.2'); // 3

toLength(-0); // 0

toLength('-0'); // 0

toLength('0'); // 0

toLength(NaN); // 0

toLength(Infinity); // 4294967295

toLength(-Infinity); // 0
Parameters:
Name Type Description
value *

要转换的值。
Returns:

转换后的整数。

Type
number

(static) toNumber(value) → {number}

Description:

  • 转换 value 为数字。

Source:
Since:
  • 1.0.0
Example
toNumber(3.2); // 3.2

toNumber('3.2'); // 3.2

toNumber(-0); // -0

toNumber('-0'); // -0

toNumber('0'); // 0

toNumber(NaN); // NaN

toNumber(Infinity); // Infinity

toNumber(-Infinity); // -Infinity
Parameters:
Name Type Description
value *

要处理的值。
Returns:

转换后的数字。

Type
number

(static) toSafeInteger(value) → {number}

Description:

  • 转换 value 为一个安全整数。

Source:
Since:
  • 1.0.0
Example
toSafeInteger(3.2); // 3

toSafeInteger('3.2'); // 3

toSafeInteger(-0); // -0

toSafeInteger('-0'); // -0

toSafeInteger('0'); // 0

toSafeInteger(NaN); // 0

toSafeInteger(Infinity); // 9007199254740991

toSafeInteger(-Infinity); // -9007199254740991
Parameters:
Name Type Description
value *

要转换的值。
Returns:

转换后的整数。

Type
number

(static) toString(value) → {string}

Description:

  • 转换 value 为字符串。null 和 undefined 将返回空字符串。-0 将被转换为 "-0"。

Source:
Since:
  • 1.0.0
Example
toString(null); // ''

toString(-0); // '-0'

// 数组中的 `null` `undefined` 返回 'null' 'undefined'
toString([undefined, null]); // 'undefined,null'

toString('a'); // 'a'

toString(3); // '3'
Parameters:
Name Type Description
value *

要处理的值。
Returns:

转换后的字符串。

Type
string

(static) tryit(fn)

Description:

  • 包装一个函数（支持异步函数），将其转为错误优先函数。

Source:
Since:
  • 1.13.0
Example
const getGreet = async (name: string) => {
  return 'hello ' + name;
}
const [err, result] = await tryit(getGreet)('jeff');
console.log([err, result]);
// [null, 'hello jeff']


const errorFn = async (name: string) => {
  throw new Error('error message');
  return 'hello ' + name;
}
const [err2, result2] = await tryit(errorFn)('jeff');
console.log([err2, result2]);
// [Error: error message, undefined]
Parameters:
Name Type Description
fn function

要包装的函数。
Returns:

如果执行成功返回 [null, result]，否则返回 [Error, undefined]。

(static) uniqueId(prefixopt) → {string}

Description:

  • 生成唯一ID。如果提供了 prefix，会被添加到ID前缀上。

Source:
Since:
  • 1.0.0
Example
uniqueId(); // '_vn1'

uniqueId(); // '_vn2'

uniqueId('abc_'); // 'abc_3'
Parameters:
Name Type Attributes Description
prefix string <optional>

要添加到ID前缀的值。默认 "_" + 2个随机生成的字符。
Returns:

唯一ID。

Type
string