zhiaiwan-utils 1.0.3

package/dist/esm/object/clone.js

@@ -0,0 +1,23 @@
+import baseClone from '../_internal/baseClone';
+/**
+ * 创建 `value` 的浅拷贝。数组、Map、Set 会复制一层容器；
+ * `ArrayBuffer` 会复制字节；`TypedArray` 共享底层 buffer；嵌套引用仍与源值共享。
+ *
+ * @param value - 要拷贝的值
+ * @returns 浅拷贝后的新值
+ *
+ * @example
+ * ```ts
+ * const obj = { a: { b: 1 } };
+ * const copy = zhiaiwanUtils.clone(obj);
+ * copy.a.b = 2;
+ * obj.a.b;
+ * // => 2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function clone(value) {
+    return baseClone(value);
+}

package/dist/esm/object/cloneDeep.js

@@ -0,0 +1,24 @@
+import baseClone from '../_internal/baseClone';
+/**
+ * 递归创建 `value` 的深拷贝。支持数组、普通对象、`Date`、`RegExp`、`Map`、`Set`、
+ * `ArrayBuffer`、`DataView`、`TypedArray`、`Error`、包装对象以及循环引用；
+ * `WeakMap`/`WeakSet` 与函数会原样返回。
+ *
+ * @param value - 要深拷贝的值
+ * @returns 深拷贝后的新值
+ *
+ * @example
+ * ```ts
+ * const obj = { a: [{ b: 1 }] };
+ * const copy = zhiaiwanUtils.cloneDeep(obj);
+ * copy.a[0].b = 2;
+ * obj.a[0].b;
+ * // => 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function cloneDeep(value) {
+    return baseClone(value, new WeakMap(), { deep: true });
+}

package/dist/esm/object/cloneDeepWith.js

@@ -0,0 +1,24 @@
+import baseClone from '../_internal/baseClone';
+/**
+ * 递归创建 `value` 的深拷贝，并通过 `customizer` 自定义克隆结果。
+ * 当 `customizer` 返回 `undefined` 时，回退到默认深拷贝逻辑。
+ *
+ * @param value - 要深拷贝的值
+ * @param customizer - 自定义克隆函数，签名为 `(value, key?, object?, stack?)`
+ * @returns 深拷贝后的新值
+ *
+ * @example
+ * ```ts
+ * const copy = zhiaiwanUtils.cloneDeepWith({ a: { b: 1 } }, (val) => {
+ *   if (typeof val === 'number') {
+ *     return 0;
+ *   }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function cloneDeepWith(value, customizer) {
+    return baseClone(value, new WeakMap(), { deep: true, customizer });
+}

package/dist/esm/object/cloneWith.js

@@ -0,0 +1,24 @@
+import baseClone from '../_internal/baseClone';
+/**
+ * 创建 `value` 的浅拷贝，并通过 `customizer` 自定义克隆结果。
+ * 当 `customizer` 返回 `undefined` 时，回退到默认克隆逻辑。
+ *
+ * @param value - 要拷贝的值
+ * @param customizer - 自定义克隆函数，签名为 `(value, key?, object?, stack?)`
+ * @returns 浅拷贝后的新值
+ *
+ * @example
+ * ```ts
+ * const copy = zhiaiwanUtils.cloneWith({ a: 1 }, (val) => {
+ *   if (typeof val === 'number') {
+ *     return val + 1;
+ *   }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function cloneWith(value, customizer) {
+    return baseClone(value, new WeakMap(), { customizer });
+}

package/dist/esm/object/defaults.js

@@ -0,0 +1,20 @@
+import { assignSources } from '../_internal/assignSources';
+/**
+ * 将 sources 的自有可枚举属性浅合并到 object，仅当 object 上对应属性为 undefined 时才赋值。
+ *
+ * @param object - 目标对象
+ * @param sources - 一个或多个源对象
+ * @returns 合并后的 object
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.defaults({ a: 1 }, { b: 2 }, { a: 3, b: 4 });
+ * // => { a: 1, b: 2 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function defaults(object, ...sources) {
+    return assignSources(object, sources, true);
+}

package/dist/esm/object/defaultsDeep.js

@@ -0,0 +1,38 @@
+import baseDefaultsDeep from '../_internal/baseDefaultsDeep';
+import isPlainObject from '../_internal/isPlainObject';
+/**
+ * 将 sources 的自有可枚举属性深合并到 object，仅当 object 上对应属性为 undefined 时才赋值。
+ *
+ * @param object - 目标对象
+ * @param sources - 一个或多个源对象
+ * @returns 合并后的 object
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.defaultsDeep({ a: { b: 2 } }, { a: { b: 3, c: 5 }, d: 4 });
+ * // => { a: { b: 2, c: 5 }, d: 4 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function defaultsDeep(object, ...sources) {
+    const target = (object == null ? {} : object);
+    for (const source of sources) {
+        if (source == null || typeof source !== 'object') {
+            continue;
+        }
+        if (Array.isArray(source)) {
+            if (!Array.isArray(target)) {
+                continue;
+            }
+            baseDefaultsDeep(target, source);
+            continue;
+        }
+        if (!isPlainObject(source)) {
+            continue;
+        }
+        baseDefaultsDeep(target, source);
+    }
+    return target;
+}

package/dist/esm/object/findKey.js

@@ -0,0 +1,23 @@
+import { baseFindKey } from '../_internal/baseFind';
+/**
+ * 返回对象中第一个满足 `predicate` 的键名。
+ *
+ * @param object - 待查找的对象
+ * @param predicate - 匹配函数，接收 `(value, key, object)`，默认匹配真值
+ * @returns 匹配键名，未找到时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * findKey({ a: 1, b: 2 }, (value) => value === 2);
+ * // => 'b'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function findKey(object, predicate) {
+    if (object == null) {
+        return undefined;
+    }
+    return baseFindKey(object, predicate, false);
+}

package/dist/esm/object/findLastKey.js

@@ -0,0 +1,23 @@
+import { baseFindKey } from '../_internal/baseFind';
+/**
+ * 从右往左返回对象中最后一个满足 `predicate` 的键名。
+ *
+ * @param object - 待查找的对象
+ * @param predicate - 匹配函数，接收 `(value, key, object)`，默认匹配真值
+ * @returns 匹配键名，未找到时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * findLastKey({ a: 1, b: 2, c: 3 }, (value) => value < 3);
+ * // => 'b'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function findLastKey(object, predicate) {
+    if (object == null) {
+        return undefined;
+    }
+    return baseFindKey(object, predicate, true);
+}

package/dist/esm/object/forIn.js

@@ -0,0 +1,23 @@
+import { baseForIn } from '../_internal/baseForOwn';
+import identity from '../_internal/identity';
+/**
+ * 遍历 object 自有与继承的可枚举属性。
+ *
+ * @param object - 待遍历对象
+ * @param iteratee - 每次迭代调用的函数
+ * @returns 原 object
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.forIn({ a: 1 }, (value, key) => console.log(key, value));
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function forIn(object, iteratee = identity) {
+    if (object == null) {
+        return object;
+    }
+    return baseForIn(object, iteratee);
+}

package/dist/esm/object/forOwn.js

@@ -0,0 +1,23 @@
+import { baseForOwn } from '../_internal/baseForOwn';
+import identity from '../_internal/identity';
+/**
+ * 遍历 object 自有可枚举属性。
+ *
+ * @param object - 待遍历对象
+ * @param iteratee - 每次迭代调用的函数
+ * @returns 原 object
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.forOwn({ a: 1, b: 2 }, (value, key) => console.log(key, value));
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function forOwn(object, iteratee = identity) {
+    if (object == null) {
+        return object;
+    }
+    return baseForOwn(object, iteratee);
+}

package/dist/esm/object/fromPairs.js

@@ -0,0 +1,25 @@
+/**
+ * toPairs 的逆运算，将键值对数组转为对象。
+ *
+ * @param pairs - 键值对数组
+ * @returns 新对象
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.fromPairs([['a', 1], ['b', 2]]);
+ * // => { a: 1, b: 2 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function fromPairs(pairs) {
+    const result = {};
+    if (pairs == null) {
+        return result;
+    }
+    for (const pair of pairs) {
+        result[String(pair[0])] = pair[1];
+    }
+    return result;
+}

package/dist/esm/object/get.js

@@ -0,0 +1,31 @@
+import toPath from '../_internal/toPath';
+/**
+ * 根据路径 path 获取 object 上的值。若解析到的值为 undefined，则返回 defaultValue。
+ *
+ * @param object - 要检索的对象
+ * @param path - 属性路径，支持 `'a.b[0].c'` 字符串或键数组
+ * @param defaultValue - 解析值为 undefined 时返回的默认值
+ * @returns 解析得到的值
+ *
+ * @example
+ * ```ts
+ * const obj = { a: [{ b: { c: 3 } }] };
+ * get(obj, 'a[0].b.c');       // => 3
+ * get(obj, ['a', '0', 'b', 'c']); // => 3
+ * get(obj, 'a.b.c', 'default'); // => 'default'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function get(object, path, defaultValue) {
+    const keys = toPath(path);
+    let current = object;
+    for (const key of keys) {
+        if (current == null) {
+            return defaultValue;
+        }
+        current = current[key];
+    }
+    return current === undefined ? defaultValue : current;
+}

package/dist/esm/object/has.js

@@ -0,0 +1,33 @@
+import toPath from '../_internal/toPath';
+/**
+ * 检查 path 是否是 object 的自有属性路径（路径上每一级均为自有属性，不含继承属性）。
+ *
+ * @param object - 要检索的对象
+ * @param path - 属性路径，支持 `'a.b[0].c'` 字符串或键数组
+ * @returns 如果路径存在，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * const obj = { a: { b: 2 } };
+ * has(obj, 'a.b');   // => true
+ * has(obj, 'a.c');   // => false
+ * has(obj, ['a', 'b']); // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function has(object, path) {
+    const keys = toPath(path);
+    if (keys.length === 0) {
+        return false;
+    }
+    let current = object;
+    for (const key of keys) {
+        if (current == null || !Object.prototype.hasOwnProperty.call(Object(current), key)) {
+            return false;
+        }
+        current = current[key];
+    }
+    return true;
+}

package/dist/esm/object/index.js

@@ -0,0 +1,29 @@
+export { default as clone } from './clone';
+export { default as cloneDeep } from './cloneDeep';
+export { default as cloneWith } from './cloneWith';
+export { default as cloneDeepWith } from './cloneDeepWith';
+export { default as get } from './get';
+export { default as set } from './set';
+export { default as has } from './has';
+export { default as findKey } from './findKey';
+export { default as findLastKey } from './findLastKey';
+export { default as pick } from './pick';
+export { default as omit } from './omit';
+export { default as merge } from './merge';
+export { default as mergeWith } from './mergeWith';
+export { default as unset } from './unset';
+export { default as defaults } from './defaults';
+export { default as defaultsDeep } from './defaultsDeep';
+export { default as assign } from './assign';
+export { default as keys } from './keys';
+export { default as values } from './values';
+export { default as pickBy } from './pickBy';
+export { default as omitBy } from './omitBy';
+export { default as mapKeys } from './mapKeys';
+export { default as mapValues } from './mapValues';
+export { default as invert } from './invert';
+export { default as fromPairs } from './fromPairs';
+export { default as forOwn } from './forOwn';
+export { default as forIn } from './forIn';
+export { default as update } from './update';
+export { default as updateWith } from './updateWith';

package/dist/esm/object/invert.js

@@ -0,0 +1,31 @@
+import { baseForOwn } from '../_internal/baseForOwn';
+/**
+ * 反转 object 的键值；重复值时后者覆盖前者。
+ *
+ * @param object - 源对象
+ * @returns 键值反转后的新对象
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.invert({ a: 1, b: 2, c: 1 });
+ * // => { '1': 'c', '2': 'b' }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function invert(object) {
+    const result = {};
+    if (object == null) {
+        return result;
+    }
+    baseForOwn(object, (value, key) => {
+        let normalized = value;
+        if (value != null && typeof value.toString !== 'function') {
+            normalized = Object.prototype.toString.call(value);
+        }
+        result[String(normalized)] = key;
+        return undefined;
+    });
+    return result;
+}

package/dist/esm/object/keys.js

@@ -0,0 +1,22 @@
+import { baseKeys } from '../_internal/baseCollectionKeys';
+/**
+ * 返回 object 的自有可枚举属性名数组；数组与类数组返回下标字符串。
+ *
+ * @param object - 要查询的对象或集合
+ * @returns 属性名数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.keys({ a: 1, b: 2 });
+ * // => ['a', 'b']
+ *
+ * zhiaiwanUtils.keys([1, 2, 3]);
+ * // => ['0', '1', '2']
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function keys(object) {
+    return baseKeys(object);
+}

package/dist/esm/object/mapKeys.js

@@ -0,0 +1,31 @@
+import assignValue from '../_internal/assignValue';
+import { baseForOwn } from '../_internal/baseForOwn';
+import baseIteratee from '../_internal/baseIteratee';
+/**
+ * 遍历 object 自有属性并生成新键名。
+ *
+ * @param object - 源对象
+ * @param iteratee - 生成新键名的函数或简写
+ * @returns 键名映射后的新对象
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.mapKeys({ a: 1, b: 2 }, (value, key) => key + value);
+ * // => { a1: 1, b2: 2 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function mapKeys(object, iteratee = baseIteratee()) {
+    const result = {};
+    if (object == null) {
+        return result;
+    }
+    const resolvedIteratee = baseIteratee(iteratee);
+    baseForOwn(object, (value, key, coll) => {
+        assignValue(result, resolvedIteratee(value, key, coll), value);
+        return undefined;
+    });
+    return result;
+}

package/dist/esm/object/mapValues.js

@@ -0,0 +1,31 @@
+import assignValue from '../_internal/assignValue';
+import { baseForOwn } from '../_internal/baseForOwn';
+import baseIteratee from '../_internal/baseIteratee';
+/**
+ * 遍历 object 自有属性并生成新值。
+ *
+ * @param object - 源对象
+ * @param iteratee - 生成新值的函数或简写
+ * @returns 值映射后的新对象
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.mapValues({ a: 1, b: 2 }, (n) => (n as number) * 3);
+ * // => { a: 3, b: 6 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function mapValues(object, iteratee = baseIteratee()) {
+    const result = {};
+    if (object == null) {
+        return result;
+    }
+    const resolvedIteratee = baseIteratee(iteratee);
+    baseForOwn(object, (value, key, coll) => {
+        assignValue(result, key, resolvedIteratee(value, key, coll));
+        return undefined;
+    });
+    return result;
+}

package/dist/esm/object/merge.js

@@ -0,0 +1,23 @@
+import mergeInto from '../_internal/mergeInto';
+/**
+ * 递归合并 sources 到 object。普通对象深合并，数组合并按索引覆盖。
+ * 若 object 为 null 或 undefined，会创建并返回新对象。
+ *
+ * @param object - 目标对象
+ * @param sources - 一个或多个源对象
+ * @returns 合并后的 object
+ *
+ * @example
+ * ```ts
+ * const object = { a: [{ b: 2 }, { d: 4 }] };
+ * const other = { a: [{ c: 3 }, { e: 5 }] };
+ * zhiaiwanUtils.merge(object, other);
+ * // => { a: [{ b: 2, c: 3 }, { d: 4, e: 5 }] }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function merge(object, ...sources) {
+    return mergeInto(object, sources);
+}

package/dist/esm/object/mergeWith.js

@@ -0,0 +1,35 @@
+import mergeInto from '../_internal/mergeInto';
+/**
+ * 与 merge 相同，但允许通过 customizer 定制合并结果。
+ * customizer 返回 undefined 时回退到默认合并逻辑。
+ *
+ * @param object - 目标对象
+ * @param sources - 一个或多个源对象
+ * @param customizer - 自定义合并函数
+ * @returns 合并后的 object
+ *
+ * @example
+ * ```ts
+ * const object = { users: [{ name: 'a' }] };
+ * const other = { users: [{ name: 'b' }] };
+ * zhiaiwanUtils.mergeWith(object, other, (obj, src) => {
+ *   if (Array.isArray(obj)) {
+ *     return obj.concat(src);
+ *   }
+ * });
+ * // => { users: [{ name: 'a' }, { name: 'b' }] }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function mergeWith(object, ...args) {
+    const sources = [...args];
+    let customizer;
+    const last = sources[sources.length - 1];
+    if (typeof last === 'function') {
+        customizer = last;
+        sources.pop();
+    }
+    return mergeInto(object, sources, customizer);
+}

package/dist/esm/object/omit.js

@@ -0,0 +1,30 @@
+import baseClone from '../_internal/baseClone';
+import baseUnset from '../_internal/baseUnset';
+import flattenPaths from '../_internal/flattenPaths';
+/**
+ * 从 object 中排除指定路径上的自有属性，返回深拷贝后的新对象。
+ *
+ * @param object - 源对象
+ * @param paths - 要排除的属性路径，支持 `'a.b'` 字符串、键数组或混合传入
+ * @returns 排除指定属性后的新对象
+ *
+ * @example
+ * ```ts
+ * const obj = { a: { b: 1, c: 2 }, d: 3 };
+ * zhiaiwanUtils.omit(obj, 'a.b');
+ * // => { a: { c: 2 }, d: 3 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function omit(object, ...paths) {
+    if (object == null) {
+        return {};
+    }
+    const result = baseClone(object, new WeakMap(), { deep: true });
+    for (const path of flattenPaths(paths)) {
+        baseUnset(result, path);
+    }
+    return result;
+}

package/dist/esm/object/omitBy.js

@@ -0,0 +1,32 @@
+import baseIteratee from '../_internal/baseIteratee';
+import baseKeysIn from '../_internal/baseKeysIn';
+/**
+ * 返回 object 中 predicate 不为真值的属性组成的新对象。
+ *
+ * @param object - 源对象
+ * @param predicate - 每次属性检查调用的函数或简写
+ * @returns 排除后的新对象
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.omitBy({ a: 1, b: '2', c: 3 }, (value) => typeof value === 'number');
+ * // => { b: '2' }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function omitBy(object, predicate = baseIteratee()) {
+    if (object == null) {
+        return {};
+    }
+    const resolvedPredicate = baseIteratee(predicate);
+    const result = {};
+    for (const key of baseKeysIn(object)) {
+        const value = object[key];
+        if (!resolvedPredicate(value, key, object)) {
+            result[key] = value;
+        }
+    }
+    return result;
+}

package/dist/esm/object/pick.js

@@ -0,0 +1,31 @@
+import flattenPaths from '../_internal/flattenPaths';
+import { getPathValue, hasPath, setPathValue } from '../_internal/basePath';
+/**
+ * 从 object 中选取指定路径上的自有属性，组成新对象。
+ *
+ * @param object - 源对象
+ * @param paths - 要选取的属性路径，支持 `'a.b'` 字符串、键数组或混合传入
+ * @returns 由选取属性组成的新对象
+ *
+ * @example
+ * ```ts
+ * const obj = { a: { b: 1 }, c: 3 };
+ * zhiaiwanUtils.pick(obj, 'a.b', 'c');
+ * // => { a: { b: 1 }, c: 3 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function pick(object, ...paths) {
+    if (object == null) {
+        return {};
+    }
+    const result = {};
+    for (const path of flattenPaths(paths)) {
+        if (hasPath(object, path)) {
+            setPathValue(result, path, getPathValue(object, path));
+        }
+    }
+    return result;
+}