ut2 1.12.0 → 1.14.0

package/types/fromPairs.d.ts

@@ -7,7 +7,6 @@ interface FromPairs {
  *
  * 与 [Object.entries](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Object/entries) 正好相反。
  *
- * @static
  * @alias module:Array.fromPairs
  * @since 1.0.0
  * @param {Array} array 键值对数组。

package/types/groupBy.d.ts

@@ -10,7 +10,6 @@ interface GroupBy {
  *
  * `iteratee` 调用时会传入三个参数 `value` `index|key` `collection`。
  *
- * @static
  * @alias module:Collection.groupBy
  * @since 1.0.0
  * @param {ArrayLike<any> | Object} collection 一个用来迭代的集合。

package/types/guard.d.ts

@@ -0,0 +1,22 @@
+import { SingleAsyncFn, SingleSyncFn } from './internals/types';
+interface Guard {
+    <R>(fn: SingleAsyncFn<R>, shouldGuard?: () => boolean): Promise<R | undefined>;
+    <R>(fn: SingleSyncFn<R>, shouldGuard?: () => boolean): R | undefined;
+}
+/**
+ * 函数守卫。
+ *
+ * @alias module:Util.guard
+ * @since 1.14.0
+ * @param {Function} fn 要执行的函数。
+ * @param {Function} [shouldGuard] 函数守卫断言。如果返回 `Truthy` 表示需要守卫，否则不需要守卫。
+ * @returns 如果函数执行成功，正常返回结果；如果异步函数拒绝或抛出错误时，有函数守卫返回 `undefined`，否则抛出错误。
+ * @example
+ * guard(() => 42); // 42
+ * await guard(() => Primise.resolve(42)); // 42
+ *
+ * guard(() => { throw new Error() }); // undefined
+ * await guard(() => Promise.reject()); // undefined
+ */
+declare const guard: Guard;
+export default guard;

package/types/identity.d.ts

@@ -1,7 +1,6 @@
 /**
  * 返回第一个参数。
  *
- * @static
  * @alias module:Util.identity
  * @since 1.0.0
  * @param {*} value 任意值。

package/types/inRange.d.ts

@@ -3,7 +3,6 @@
  *
  * 如果 `start` 大于 `end` 会自动交换范围参数。
  *
- * @static
  * @alias module:Number.inRange
  * @since 1.0.0
  * @param {number} number 要检查的值。

package/types/index.d.ts

@@ -127,6 +127,7 @@ export { default as randomInt } from './randomInt';
  */
 export { default as allKeys } from './allKeys';
 export { default as allKeysIn } from './allKeysIn';
+export { default as findKey } from './findKey';
 export { default as invert } from './invert';
 export { default as keys } from './keys';
 export { default as keysIn } from './keysIn';
@@ -168,14 +169,16 @@ export { default as defaultTo } from './defaultTo';
 export { default as eq } from './eq';
 export { default as gt } from './gt';
 export { default as gte } from './gte';
+export { default as guard } from './guard';
 export { default as identity } from './identity';
+export { default as list } from './list';
 export { default as lt } from './lt';
 export { default as lte } from './lte';
 export { default as noop } from './noop';
 export { default as nthArg } from './nthArg';
 export { default as range } from './range';
+export { default as retry } from './retry';
 export { default as sleep } from './sleep';
-export { default as list } from './list';
 export { default as times } from './times';
 export { default as toFinite } from './toFinite';
 export { default as toInteger } from './toInteger';
@@ -183,6 +186,7 @@ export { default as toLength } from './toLength';
 export { default as toNumber } from './toNumber';
 export { default as toSafeInteger } from './toSafeInteger';
 export { default as toString } from './toString';
+export { default as tryit } from './tryit';
 export { default as uniqueId } from './uniqueId';
 export { MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, MAX_ARRAY_LENGTH } from './internals/native';
 export { VERSION, isBrowser } from './internals/helpers';

package/types/internals/helpers.d.ts

@@ -1,14 +1,10 @@
 /**
- * ut2 版本号。
- *
- * @static
+ * @summary ut2 版本号。
  * @since 1.0.0
  */
 export declare const VERSION: string;
 /**
- * 当前运行环境是否为浏览器
- *
- * @static
+ * @summary 当前运行环境是否为浏览器。
  * @since 1.10.0
  */
 export declare const isBrowser: boolean;

package/types/internals/native.d.ts

@@ -29,27 +29,21 @@ export declare const globalThisExisted: false | typeof globalThis;
 export declare const globalExisted: false | typeof globalThis;
 export declare const selfExisted: false | (Window & typeof globalThis);
 /**
- * 最大安全整数。
- *
- * @static
+ * @summary 最大安全整数。
  * @since 1.0.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER MAX_SAFE_INTEGER}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER | MAX_SAFE_INTEGER}
  */
 export declare const MAX_SAFE_INTEGER: number;
 /**
- * 最小安全整数。
- *
- * @static
+ * @summary 最小安全整数。
  * @since 1.0.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER MIN_SAFE_INTEGER}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Number/MIN_SAFE_INTEGER | MIN_SAFE_INTEGER}
  */
 export declare const MIN_SAFE_INTEGER: number;
 /**
- * 最大数组长度 `Math.pow(2,32) - 1`。
- *
- * @static
+ * @summary 最大数组长度 `Math.pow(2,32) - 1`。
  * @since 1.0.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Array/length length}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Array/length | length}
  */
 export declare const MAX_ARRAY_LENGTH = 4294967295;
 export declare const bigIntTag = "[object BigInt]";

package/types/internals/root.d.ts

@@ -1,14 +1,13 @@
 /**
- * 全局对象。
+ * @summary 全局对象。
  *
  * 不同的 JavaScript 环境都可以获取到对应的全局对象：
  * 1. Web 中等同于 `globalThis` / `window` / `self` / `frames` （兼容旧浏览器）
  * 2. Node.js 中等同于 `globalThis` / `global` （兼容低版本 Node.js）
  * 3. Web Workers 中等同于 `self`
  *
- * @static
  * @since 1.10.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/globalThis globalThis}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/globalThis | globalThis}
  */
 declare const root: typeof globalThis;
 export default root;

package/types/internals/types.d.ts

@@ -1,4 +1,8 @@
 export type FunctionAny = (...args: any[]) => any;
+export type SyncFn<P extends any[], R> = (...args: P) => R;
+export type AsyncFn<P extends any[], R> = (...args: P) => Promise<R>;
+export type SingleSyncFn<R> = () => R;
+export type SingleAsyncFn<R> = () => Promise<R>;
 /**
  * 工具辅助类型
  */
@@ -6,6 +10,9 @@ export type Many<T> = T | T[];
 export type WithNullable<T> = T | null | undefined;
 export type PropertyName = string | number | symbol;
 export type ObjectPredicate<T extends object, K extends keyof T = keyof T> = (value: T[K], key: K) => boolean;
+export type MapValue<T extends Map<any, any>> = ReturnType<T['get']>;
+export type MapKey<T extends Map<any, any>> = Parameters<T['get']>[0];
+export type MapPredicate<T extends Map<any, any>> = (value: MapValue<T>, key: MapKey<T>) => boolean;
 /**
  * 迭代参数
  */

package/types/intersection.d.ts

@@ -6,7 +6,6 @@ import { IterateeParam } from './internals/types';
  *
  * 默认使用了 [`SameValueZero`](https://tc39.es/ecma262/#sec-samevaluezero) 做等值比较。如果 `strictCheck=true` 将使用 [`SameValue`](https://tc39.es/ecma262/#sec-samevalue) 做等值比较。
  *
- * @static
  * @alias module:Array.intersection
  * @since 1.0.0
  * @param {Array} array 要检查的数组。

package/types/invert.d.ts

@@ -2,10 +2,9 @@ import { ObjectPredicate, PropertyName, WithNullable } from './internals/types';
 /**
  * 创建一个对象，该对象由 `object` 自身可枚举属性（包含 `Symbol` 属性）和值反转组成。
  *
- * @static
  * @alias module:Object.invert
  * @since 1.8.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Glossary/Truthy Truthy}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Glossary/Truthy | Truthy}
  * @param {Object} object 来源对象。
  * @param {Function} [predicate] 调用每一个属性的函数，返回 `Truthy` 表示要反转，否则不反转。
  * @returns {Object} 新对象。

package/types/isArguments.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `arguments` 对象。
  *
- * @static
  * @alias module:Language.isArguments
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isArray.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `Array` 对象。
  *
- * @static
  * @alias module:Language.isArray
  * @since 1.0.0
  * @param {*} value 要检查的值

package/types/isArrayBuffer.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `ArrayBuffer` 对象。
  *
- * @static
  * @alias module:Language.isArrayBuffer
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isArrayLike.d.ts

@@ -3,7 +3,6 @@
  *
  * 如果一个值不是函数并且其 `value.length` 是大于或等于 `0` 且小于或等于 `Number.MAX_SAFE_INTEGER` 的整数，则该值被视为类数组。
  *
- * @static
  * @alias module:Language.isArrayLike
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isArrayLikeObject.d.ts

@@ -5,7 +5,6 @@ type ArrayLikeObject = Array<any> | {
 /**
  * 检查值是否为类数组对象。
  *
- * @static
  * @alias module:Language.isArrayLikeObject
  * @since 1.0.0
  * @param {*} value 要检查的值

package/types/isBigInt.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 bigint 类型或对象。
  *
- * @static
  * @alias module:Language.isBigInt
  * @since 1.8.0
  * @param {*} value 要检查的值。

package/types/isBlob.d.ts

@@ -3,11 +3,10 @@
  *
  * 浏览器环境的 `Blob` 或 `File` 对象，或其他继承自 `Blob` 的实例，都将返回 `true`。
  *
- * @static
  * @alias module:Language.isBlob
  * @since 1.0.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/Blob Blob}
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/File File}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/Blob | Blob}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/File | File}
  * @param {*} value 要检查的值。
  * @returns {boolean} 如果值为 `Blob` 对象，返回 `true`，否则返回 `false`。
  * @example

package/types/isBoolean.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为布尔类型或对象。
  *
- * @static
  * @alias module:Language.isBoolean
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isBuffer.d.ts

@@ -3,7 +3,6 @@
  *
  * 非 Node.js 环境，始终返回 `false`。
  *
- * @static
  * @alias module:Language.isBuffer
  * @since 1.0.0
  * @param {*} value 要检查的值

package/types/isDataView.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `DataView` 对象。
  *
- * @static
  * @alias module:Language.isDataView
  * @since 1.2.0
  * @param {*} value 要检查的值。

package/types/isDate.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `Date` 对象。
  *
- * @static
  * @alias module:Language.isDate
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isElement.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否可能为 `DOM` 元素。
  *
- * @static
  * @alias module:Language.isElement
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isEmpty.d.ts

@@ -5,7 +5,6 @@
  *
  * 非上述类型值，都将被认为是空的。
  *
- * @static
  * @alias module:Language.isEmpty
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isEqual.d.ts

@@ -10,7 +10,6 @@ import isEqualDeep from './internals/isEqualDeep';
  * 2. `typeof` 不同类型，如 `1` `Object(1)`
  * 3. 无效日期对象，如 `new Date('')` `new Date('abc')`
  *
- * @static
  * @alias module:Language.isEqual
  * @since 1.3.0
  * @param {*} value 要比较的值。

package/types/isError.d.ts

@@ -3,7 +3,6 @@
  *
  * 继承自 `Error` 的对象，如 `EvalError` `RangeError` `ReferenceError` `SyntaxError` `TypeError` `URIError` `AggregateError`，都将返回 `true`。
  *
- * @static
  * @alias module:Language.isError
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isFile.d.ts

@@ -3,10 +3,9 @@
  *
  * 浏览器环境的 `File` 对象，或其他继承自 `File` 的实例，都将返回 `true`。
  *
- * @static
  * @alias module:Language.isFile
  * @since 1.11.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/File File}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/API/File | File}
  * @param {*} value 要检查的值。
  * @returns {boolean} 如果值为 `File` 对象，返回 `true`，否则返回 `false`。
  * @example

package/types/isFinite.d.ts

@@ -3,7 +3,6 @@
  *
  * 同 `Number.isFinite`。
  *
- * @static
  * @alias module:Language.isFinite
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isFunction.d.ts

@@ -4,7 +4,6 @@ import { FunctionAny } from './internals/types';
  *
  * `Function` `AsyncFunction` `GeneratorFunction` `Proxy` 都将返回 `true`。
  *
- * @static
  * @alias module:Language.isFunction
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isInteger.d.ts

@@ -3,7 +3,6 @@
  *
  * 同 `Number.isInteger`。
  *
- * @static
  * @alias module:Language.isInteger
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isLength.d.ts

@@ -1,10 +1,9 @@
 /**
  * 检查值是否为有效的类数组长度。
  *
- * @static
  * @alias module:Language.isLength
  * @since 1.0.0
- * @see {@link https://tc39.es/ecma262/#sec-tolength ToLength}
+ * @see {@link https://tc39.es/ecma262/#sec-tolength | ToLength}
  * @param {*} value 要检查的值。
  * @returns {boolean} 如果值为有效的类数组长度，返回 `true`，否则返回 `false`。
  * @example

package/types/isMap.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `Map` 对象。
  *
- * @static
  * @alias module:Language.isMap
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isMatch.d.ts

@@ -10,7 +10,6 @@ type Customizer = (objValue: any, srcValue: any, key?: number | string | symbol,
  * 2. `typeof` 不同类型，如 `1` `Object(1)`
  * 3. 无效日期对象，如 `new Date('')` `new Date('abc')`
  *
- * @static
  * @alias module:Language.isMatch
  * @since 1.4.0
  * @requires module:Language.isEqual

package/types/isNaN.d.ts

@@ -3,7 +3,6 @@
  *
  * 和 `Number.isNaN` 区别是 `new Number(NaN)` 也被认为是 `NaN`。
  *
- * @static
  * @alias module:Language.isNaN
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isNil.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `undefined` 或 `null`。
  *
- * @static
  * @alias module:Language.isNil
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isNull.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `null`。
  *
- * @static
  * @alias module:Language.isNull
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isNumber.d.ts

@@ -3,7 +3,6 @@
  *
  * `Infinity` `-Infinity` `NaN` 都归类为数字。如果要排除，请使用 `isFinite` 方法。
  *
- * @static
  * @alias module:Language.isNumber
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isObject.d.ts

@@ -2,10 +2,9 @@ import { FunctionAny } from './internals/types';
 /**
  * 检查值是否为对象。(例如，数组、函数、对象、正则表达式、new Number(0) 和 new String(''))。
  *
- * @static
  * @alias module:Language.isObject
  * @since 1.0.0
- * @see {@link https://tc39.es/ecma262/#sec-ecmascript-language-types language type}
+ * @see {@link https://tc39.es/ecma262/#sec-ecmascript-language-types | language type}
  * @param {*} value 要检查的值。
  * @returns {boolean} 如果值为对象，返回 `true`，否则返回 `false`。
  * @example

package/types/isObjectLike.d.ts

@@ -3,7 +3,6 @@
  *
  * 如果一个值不为 `null` 并且 `typeof` 结果为 `object`，则该值是类对象。
  *
- * @static
  * @alias module:Language.isObjectLike
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isPlainObject.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为普通对象，即由 `Object` 构造函数创建或 `[[Prototype]]` 为 `null` 的对象。
  *
- * @static
  * @alias module:Language.isPlainObject
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isPromiseLike.d.ts

@@ -3,7 +3,6 @@
  *
  * 如果一个对象包含 `then` 方法，它就是类似 `Promise` 对象。
  *
- * @static
  * @alias module:Language.isPromiseLike
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isRegExp.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `RegExp` 对象。
  *
- * @static
  * @alias module:Language.isRegExp
  * @since 1.0.0
  * @param {*} value 要检查的值

package/types/isSafeInteger.d.ts

@@ -5,7 +5,6 @@
  *
  * 如果一个整数是一个 `IEEE-754` 双精度数字，它不是四舍五入的不安全整数的结果，那么它就是安全的。安全整数范围为 `-(2^53 - 1)` 到 `2^53 - 1` 之间的整数，包含 `-(2^53 - 1)` 和 `2^53 - 1`。
  *
- * @static
  * @alias module:Language.isSafeInteger
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isSet.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `Set` 对象。
  *
- * @static
  * @alias module:Language.isSet
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isString.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为字符串类型或对象。
  *
- * @static
  * @alias module:Language.isString
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isSymbol.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `Symbol` 类型或对象。
  *
- * @static
  * @alias module:Language.isSymbol
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isTypedArray.d.ts

@@ -1,10 +1,9 @@
 /**
  * 检查值是否为类型化数组。
  *
- * @static
  * @alias module:Language.isTypedArray
  * @since 1.0.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Typed_arrays Typed_arrays}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Guide/Typed_arrays | Typed_arrays}
  * @param {*} value 要检查的值。
  * @returns {boolean} 如果值为类型化数组，返回 `true`，否则返回 `false`。
  * @example

package/types/isUndefined.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `undefined`。
  *
- * @static
  * @alias module:Language.isUndefined
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isWeakMap.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `WeakMap` 对象。
  *
- * @static
  * @alias module:Language.isWeakMap
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isWeakSet.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `WeakSet` 对象。
  *
- * @static
  * @alias module:Language.isWeakSet
  * @since 1.0.0
  * @param {*} value 要检查的值。

package/types/isWindow.d.ts

@@ -1,7 +1,6 @@
 /**
  * 检查值是否为 `Window` 对象。
  *
- * @static
  * @alias module:Language.isWindow
  * @since 1.10.0
  * @param {*} value 要检查的值。

package/types/kebabCase.d.ts

@@ -1,10 +1,9 @@
 /**
  * 转换字符串为连接符小写。
  *
- * @static
  * @alias module:String.kebabCase
  * @since 1.0.0
- * @see {@link https://en.wikipedia.org/wiki/Letter_case#Special_case_styles kebab case}
+ * @see {@link https://en.wikipedia.org/wiki/Letter_case#Special_case_styles | kebab case}
  * @param {string} string 要转换的字符串。
  * @param {RegExp | string} [pattern] 拆分词组的匹配模式。
  * @returns {string} 转换后的字符串。

package/types/keys.d.ts

@@ -3,7 +3,6 @@
  *
  * 同 `Object.keys`。
  *
- * @static
  * @alias module:Object.keys
  * @since 1.7.0
  * @param {Object} object 要查询的对象。

package/types/keysIn.d.ts

@@ -3,7 +3,6 @@
  *
  * 同 `key...in`。
  *
- * @static
  * @alias module:Object.keysIn
  * @since 1.1.0
  * @param {Object} object 要查询的对象。

package/types/lowerCase.d.ts

@@ -1,7 +1,6 @@
 /**
  * 转换字符串为空格分隔的小写单词。
  *
- * @static
  * @alias module:String.lowerCase
  * @since 1.0.0
  * @param {string} string 要转换的字符串。

package/types/map.d.ts

@@ -10,7 +10,6 @@ interface Map {
  *
  * `iteratee` 调用时会传入三个参数 `value` `index|key` `collection`。
  *
- * @static
  * @alias module:Collection.map
  * @since 1.7.0
  * @param {ArrayLike<any> | Object} collection 要迭代的集合。