ut2 1.15.0 → 1.16.0

package/types/get.d.ts

@@ -0,0 +1,21 @@
+import { Many, TPath } from './internals/types';
+/**
+ * 获取对象路径的值。
+ *
+ * @alias module:Object.get
+ * @since 1.16.0
+ * @param {*} object 要查询的对象。
+ * @param {string | number | symbol | Array} path 属性路径字符串或数组。
+ * @param {*} [defaultValue] 替代返回 `undefined` 的默认值。
+ * @returns {*} 属性值。
+ * @example
+ * const obj = { a: [{ b: { c: 1 } }] };
+ *
+ * get(obj, 'a[0].b.c'); // 1
+ *
+ * get(obj, ['a', '0', 'b', 'c']); // 1
+ *
+ * get(obj, 'a.b.c', 'default'); // 'default'
+ */
+declare function get<TDefault = unknown>(object: any, key: Many<TPath>, defaultValue?: TDefault): TDefault | undefined;
+export default get;

package/types/index.d.ts

@@ -128,6 +128,8 @@ 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 fromPathPairs } from './fromPathPairs';
+export { default as get } from './get';
 export { default as invert } from './invert';
 export { default as keys } from './keys';
 export { default as keysIn } from './keysIn';
@@ -137,6 +139,9 @@ export { default as omit } from './omit';
 export { default as omitBy } from './omitBy';
 export { default as pick } from './pick';
 export { default as pickBy } from './pickBy';
+export { default as pathPairs } from './pathPairs';
+export { default as set } from './set';
+export { default as unset } from './unset';
 /**
  * 字符串
  *
@@ -185,6 +190,7 @@ export { default as toFinite } from './toFinite';
 export { default as toInteger } from './toInteger';
 export { default as toLength } from './toLength';
 export { default as toNumber } from './toNumber';
+export { default as toPath } from './toPath';
 export { default as toSafeInteger } from './toSafeInteger';
 export { default as toString } from './toString';
 export { default as tryit } from './tryit';

package/types/internals/isIndex.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 检查值是否为有效的数组索引值。
+ *
+ * @private
+ * @param value 要检查的值。
+ * @returns {boolean} 值是否为有效的数组索引值。
+ * @example
+ * isIndex(0); // true
+ * isIndex('0'); // true
+ * isIndex('42'); // true
+ *
+ * isIndex('a'); // false
+ * isIndex(0.1); // false
+ * isIndex(Infinity); // false
+ */
+declare function isIndex(value: any): boolean;
+export default isIndex;

package/types/internals/native.d.ts

@@ -31,19 +31,19 @@ export declare const selfExisted: false | (Window & typeof globalThis);
 /**
  * @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;
 /**
  * @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;
 /**
  * @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

@@ -7,7 +7,7 @@
  * 3. Web Workers 中等同于 `self`
  *
  * @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/stringToPath.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 将字符串路径转为数组路径
+ *
+ * @private
+ * @param {string} value 字符串路径
+ * @returns {string[]} 路径数组
+ */
+declare function stringToPath(value: string): string[];
+export default stringToPath;

package/types/internals/types.d.ts

@@ -3,6 +3,7 @@ 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>;
+export type TPath = string | symbol | number;
 /**
  * 工具辅助类型
  */

package/types/invert.d.ts

@@ -4,7 +4,7 @@ import { ObjectPredicate, PropertyName, WithNullable } from './internals/types';
  *
  * @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/isBlob.d.ts

@@ -5,8 +5,8 @@
  *
  * @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/isFile.d.ts

@@ -5,7 +5,7 @@
  *
  * @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/isLength.d.ts

@@ -3,7 +3,7 @@
  *
  * @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/isObject.d.ts

@@ -4,7 +4,7 @@ import { FunctionAny } from './internals/types';
  *
  * @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/isTypedArray.d.ts

@@ -3,7 +3,7 @@
  *
  * @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/kebabCase.d.ts

@@ -3,7 +3,7 @@
  *
  * @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/merge.d.ts

@@ -7,7 +7,7 @@ type Customizer = (objValue: any, srcValue: any, key: string | symbol, object: a
  *
  * 如果不需要合并数组，第三个参数传入 `merge.NOT_MERGE_ARRAYS` 。
  *
- * 如果需要合并继承的属性，第四个参数传入 {@link https://caijf.github.io/ut2/module-Object.html#.allKeysIn allKeysIn} 方法， `merge(object, source, undefined, allKeysIn)`。
+ * 如果需要合并继承的属性，第四个参数传入 {@link https://caijf.github.io/ut2/module-Object.html#.allKeys allKeys} 方法， `merge(object, source, undefined, allKeys)`。
  *
  * @alias module:Object.merge
  * @since 1.0.0

package/types/mergeObject.d.ts

@@ -21,7 +21,7 @@ interface MergeObject {
  * @alias module:Object.mergeObject
  * @since 1.15.0
  * @param {Object | Array} object 目标对象。
- * @param {...object} args 展开的来源对象。
+ * @param {...object} args 来源对象。
  * @returns 目标对象。
  * @example
  *

package/types/move.d.ts

@@ -3,7 +3,7 @@
  *
  * @alias module:Array.move
  * @since 1.10.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Array/splice | splice}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Array/splice splice}
  * @param {Array} array 要处理的数组。
  * @param {number} from 要移动的元素索引。
  * @param {number} to 要移动目标位置的元素索引。

package/types/omitBy.d.ts

@@ -6,7 +6,7 @@ import { ObjectPredicate, WithNullable } from './internals/types';
  *
  * @alias module:Object.omitBy
  * @since 1.0.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/orderBy.d.ts

@@ -16,7 +16,7 @@ interface OrderBy {
  * @function
  * @alias module:Collection.orderBy
  * @since 1.0.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Array/sort | sort}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Array/sort sort}
  * @param {ArrayLike<any> | Object} collection 一个用来迭代的集合。
  * @param {Function | string | number | Symbol | Array} [iteratees] 排序的迭代函数。
  * @param {'asc' | 'desc' | Array} [orders] 迭代函数的排序顺序。

package/types/partition.d.ts

@@ -12,8 +12,8 @@ interface Partition {
  *
  * @alias module:Collection.partition
  * @since 1.0.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Glossary/Truthy | Truthy}
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Glossary/Falsy | Falsy}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Glossary/Truthy Truthy}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Glossary/Falsy Falsy}
  * @param {ArrayLike<any> | Object} collection 一个用来迭代的集合。
  * @param {Function | string | number | Symbol | Array} [predicate=identity] 每次迭代调用的断言函数。默认 `identity`。
  * @returns {Array} 分组后的数组。

package/types/pascalCase.d.ts

@@ -3,7 +3,7 @@
  *
  * @alias module:String.pascalCase
  * @since 1.8.0
- * @see {@link https://en.wikipedia.org/wiki/Camel_case | Camel_case}
+ * @see {@link https://en.wikipedia.org/wiki/Camel_case Camel_case}
  * @param {string} string 要转换的字符串。
  * @param {RegExp | string} [pattern] 拆分词组的匹配模式。
  * @returns {string} 帕斯卡写法的字符串。

package/types/pathPairs.d.ts

@@ -0,0 +1,30 @@
+import { TPath } from './internals/types';
+/**
+ * 将对象转为属性路径/值对的数组。与 [`fromPathPairs`](#.fromPathPairs) 相反。
+ *
+ * @alias module:Object.pathPairs
+ * @since 1.16.0
+ * @param {Object|Array} object 对象或数组。
+ * @returns {Array} 属性路径/值对的数组。
+ * @example
+ * pathPairs({ date: { start: '2024-10-10', end: '2024-12-31' } });
+ * // [
+ * //   [['date', 'start'], '2024-10-10'],
+ * //   [['date', 'end'], '2024-12-31']
+ * // ]
+ *
+ * pathPairs({ date: ['2024-10-10', '2024-12-31'] });
+ * // [
+ * //   [['date', 0], '2024-10-10'],
+ * //   [['date', 1], '2024-12-31']
+ * // ]
+ *
+ * pathPairs([{ date: '2024-10-10' }, { date: '2024-12-31' }]);
+ * // [
+ * //   [[0, 'date'], '2024-10-10'],
+ * //   [[1, 'date'], '2024-12-31']
+ * // ]
+ *
+ */
+declare function pathPairs(object: Record<string, any> | any[]): [TPath[], any][];
+export default pathPairs;

package/types/pickBy.d.ts

@@ -6,7 +6,7 @@ import { ObjectPredicate, WithNullable } from './internals/types';
  *
  * @alias module:Object.pickBy
  * @since 1.0.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} obj 来源对象。
  * @param {Function} [predicate] 调用每一个属性的函数，返回 `Truthy` 表示要提取该属性，否则不提取。
  * @returns {Object} 新对象。

package/types/round.d.ts

@@ -5,7 +5,7 @@
  *
  * @alias module:Math.round
  * @since 1.0.0
- * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Math/round#小数舍入 | 小数舍入}
+ * @see {@link https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Math/round#小数舍入 小数舍入}
  * @param {number} number 要四舍五入的值。
  * @param {number} [precision=0] 四舍五入的精度。默认 `0`。
  * @returns {number} 四舍五入的值。

package/types/set.d.ts

@@ -0,0 +1,24 @@
+import { Many, TPath } from './internals/types';
+type TCustomizer = (objValue: any, key: TPath, nested: any) => any;
+/**
+ * 设置对象属性路径值。
+ *
+ * @alias module:Object.set
+ * @since 1.16.0
+ * @param {Object | Array} object 对象或数组。
+ * @param {string | number | symbol | Array} path 属性路径字符串或数组。
+ * @param {*} value 要设置的值。
+ * @param {Function} [customizer] 自定义指定值。
+ * @returns `object`。
+ * @example
+ * const obj = {};
+ *
+ * set(obj, 'a.b', 1);
+ * console.log(obj); // { a: { b: 1 } }
+ *
+ * set(obj, ['x', '0', 'y'], 2);
+ * console.log(obj); // { a: { b: 1 }, x: [{ y: 2 }] }
+ *
+ */
+declare function set<T extends object>(object: T, path: Many<TPath>, value: any, customizer?: TCustomizer): T;
+export default set;

package/types/snakeCase.d.ts

@@ -3,7 +3,7 @@
  *
  * @alias module:String.snakeCase
  * @since 1.0.0
- * @see {@link https://en.wikipedia.org/wiki/Snake_case | snake case}
+ * @see {@link https://en.wikipedia.org/wiki/Snake_case snake case}
  * @param {string} string 要转换的字符串。
  * @param {RegExp | string} [pattern] 拆分词组的匹配模式。
  * @returns {string} 转换后的字符串。

package/types/toLength.d.ts

@@ -3,7 +3,7 @@
  *
  * @alias module:Util.toLength
  * @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}
  * @param {*} value 要转换的值。
  * @returns {number} 转换后的整数。
  * @example

package/types/toPath.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 将值转为属性路径数组。
+ *
+ * @alias module:Util.toPath
+ * @since 1.16.0
+ * @param {*} value 要转换的值。
+ * @param {Object} [object] 用于查询键的对象，可选。
+ * @returns {Array} 一个新的属性路径数组。
+ * @example
+ * toPath('a.b.c'); // ['a', 'b', 'c']
+ *
+ * toPath('a[0].b.c'); // ['a', '0', 'b', 'c']
+ *
+ * toPath(['a', 'b', 'c']); // ['a', 'b', 'c']
+ */
+declare function toPath(value: any, object?: object): (string | symbol)[];
+export default toPath;

package/types/unset.d.ts

@@ -0,0 +1,20 @@
+import { Many, TPath } from './internals/types';
+/**
+ * 删除对象路径的属性。
+ *
+ * @alias module:Object.unset
+ * @since 1.16.0
+ * @param {*} object 要修改的对象。
+ * @param {string | number | symbol | Array} path 属性路径字符串或数组。
+ * @returns {boolean} 如果删除成功返回`true`，否则返回`false`。
+ * @example
+ * const obj = { a: [{ b: { c: 1 } }] };
+ *
+ * unset(obj, 'a[0].b.c'); // true
+ * console.log(obj); // { a: [{ b: {} }] }
+ *
+ * unset(obj, ['a', '0', 'b', 'c']); // true
+ * console.log(obj); // { a: [{ b: {} }] }
+ */
+declare function unset(object: any, path: Many<TPath>): boolean;
+export default unset;

package/types/words.d.ts

@@ -3,7 +3,7 @@
  *
  * @alias module:String.words
  * @since 1.0.0
- * @see {@link https://zh.wikipedia.org/wiki/ASCII | ASCII}
+ * @see {@link https://zh.wikipedia.org/wiki/ASCII ASCII}
  * @param {string} string 要拆分的字符串。
  * @param {RegExp | string} [pattern=/[^\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\x7f]+/g] 匹配模式。默认 `/[^\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\x7f]+/g`。
  * @returns {string[]} 拆分后的数组。