zhiaiwan-utils 1.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zhiaiwan-utils
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,92 @@
+# zhiaiwan-utils
+
+> 现代前端与 Node.js 通用工具函数库。支持 UMD / AMD / CMD / CommonJS / ESM，完整 TypeScript 类型，以及子路径按需引入。
+
+## 安装
+
+```bash
+npm install zhiaiwan-utils
+# 或
+pnpm add zhiaiwan-utils
+```
+
+## 使用
+
+### 子路径按需引入（推荐）
+
+```ts
+import { forEach } from 'zhiaiwan-utils/array';
+import { get } from 'zhiaiwan-utils/object';
+
+const collected: number[] = [];
+forEach([1, 2, 3, 4], (n) => collected.push(n));
+// collected => [1, 2, 3, 4]
+```
+
+### 整包引入
+
+```ts
+import { forEach, get, version } from 'zhiaiwan-utils';
+```
+
+### Node.js（CommonJS）
+
+```js
+const { forEach } = require('zhiaiwan-utils');
+const { forEachRight } = require('zhiaiwan-utils/array');
+```
+
+### 浏览器（UMD 全局变量）
+
+```html
+<script src="https://unpkg.com/zhiaiwan-utils/dist/umd/zhiaiwan-utils.min.js"></script>
+<script>
+  zhiaiwanUtils.forEach([1, 2, 3, 4], (n) => console.log(n));
+  zhiaiwanUtils.version;
+</script>
+```
+
+## 模块清单
+
+| 模块 | 引入路径 | 函数 |
+|------|----------|------|
+| `array` | `zhiaiwan-utils/array` | forEach、forEachRight、each、find、findLast、findIndex、findLastIndex、filter、map、some、every、includes、concat、compact、chunk、union、intersection、difference、differenceBy、without、groupBy、keyBy、partition、uniq、uniqBy、sortBy、orderBy、maxBy、minBy、sum、sumBy、meanBy、min、max、mean、reduce、reduceRight、flatten、flattenDeep、head、last、take、drop |
+| `object` | `zhiaiwan-utils/object` | clone、cloneDeep、cloneWith、cloneDeepWith、get、set、has、findKey、findLastKey、pick、pickBy、omit、omitBy、merge、mergeWith、unset、defaults、defaultsDeep、assign、keys、values、mapKeys、mapValues、invert、fromPairs、forOwn、forIn、update、updateWith |
+| `convert` | `zhiaiwan-utils/convert` | toArray、toFinite、toInteger、toLength、toNumber、toSafeInteger、toString、toPath、toPlainObject、toPairs、toPairsIn、toLower、toUpper |
+| `tree` | `zhiaiwan-utils/tree` | traverseTree、traverseTreeBfs、forEachTree、findTreeNode、filterTreeNodes、getParentNodes、toTree、toFlatList、getTreeDepth、mapTree、pruneTree |
+| `string` | `zhiaiwan-utils/string` | trim、trimStart、trimEnd、startsWith、endsWith、pad、padStart、padEnd、escape、unescape、repeat、camelCase、kebabCase、snakeCase、capitalize、lowerCase、upperFirst |
+| `util` | `zhiaiwan-utils/util` | noop、identity、delay、defer、now、uniqueId、sleep、validateFields、defaultTo、size、range、times、constant、negate、iteratee、property、matches、matchesProperty、clamp、inRange、random |
+| `verify` | `zhiaiwan-utils/verify` | isString、isNumber、isBoolean、isArray、isArguments、isArrayBuffer、isTypedArray、isBuffer、isFunction、isNative、isObject、isPlainObject、isUndefined、isNull、isNil、isDate、isRegExp、isSymbol、isInteger、isSafeInteger、isLength、isEmpty、isMap、isSet、isWeakMap、isWeakSet、isError、isEqual、isEqualWith、isNaN、isFinite、isMatch、isMatchWith、isArrayLike、isObjectLike、isElement |
+| `function` | `zhiaiwan-utils/function` | once、debounce、throttle、before、after、memoize、partial、partialRight、flow、flowRight、curry |
+| `color` | `zhiaiwan-utils/color` | rgbToHex、hexToRgb、rgbStringToHex、getCssVariable、getThemePalette |
+
+此外主入口导出 `version`（当前库版本号）。
+
+## 发布产物
+
+| 目录 | 格式 | 说明 |
+|------|------|------|
+| `dist/cjs/` | CommonJS | 保留目录树，支持子路径 `require` |
+| `dist/esm/` | ESM | 支持 Tree Shaking |
+| `dist/types/` | TypeScript 声明 | 与 `package.json` 的 `exports` 字段映射 |
+| `dist/umd/` | UMD 单文件 | `.js` / `.min.js`，全局名 `zhiaiwanUtils` |
+
+## 开发脚本
+
+```bash
+pnpm test           # Jest 单元测试
+pnpm test:coverage  # 覆盖率（阈值 80%）
+pnpm bench          # 性能基准测试
+pnpm lint           # ESLint
+```
+
+## 目录约定
+
+- **一函数一文件**：每个工具函数独占 `.ts` 文件，默认导出
+- **模块聚合**：每个子目录 `index.ts` 统一 re-export
+- **内部共享**：`src/_internal/` 存放库内共享逻辑，不对外 export
+- **版本号**：`src/version.ts` 由构建流程自动生成，勿手改
+
+## License
+
+[MIT](./LICENSE)

package/dist/cjs/_internal/MapCache.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 内部辅助：memoize 默认缓存，接口对齐 Lodash MapCache。
+ *
+ * @internal
+ */
+class MapCache {
+    constructor() {
+        this.store = new Map();
+    }
+    clear() {
+        this.store.clear();
+    }
+    delete(key) {
+        return this.store.delete(key);
+    }
+    get(key) {
+        return this.store.get(key);
+    }
+    has(key) {
+        return this.store.has(key);
+    }
+    set(key, value) {
+        this.store.set(key, value);
+        return this;
+    }
+}
+exports.default = MapCache;

package/dist/cjs/_internal/assignSources.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assignSources = assignSources;
+/**
+ * 内部辅助：将 sources 的自有可枚举属性浅拷贝到 object。
+ *
+ * @internal
+ */
+function assignSources(object, sources, onlyUndefined) {
+    const target = (object == null ? {} : object);
+    for (const source of sources) {
+        if (source == null || typeof source !== 'object') {
+            continue;
+        }
+        for (const key of Object.keys(source)) {
+            const value = source[key];
+            if (onlyUndefined && target[key] !== undefined) {
+                continue;
+            }
+            target[key] = value;
+        }
+    }
+    return target;
+}

package/dist/cjs/_internal/assignValue.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = assignValue;
+/**
+ * 安全赋值，避免 __proto__ 污染，对齐 Lodash assignValue。
+ *
+ * @internal
+ */
+function assignValue(object, key, value) {
+    if (key === '__proto__') {
+        Object.defineProperty(object, key, {
+            configurable: true,
+            enumerable: true,
+            value,
+            writable: true,
+        });
+        return;
+    }
+    object[key] = value;
+}

package/dist/cjs/_internal/baseClone.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = baseClone;
+function cloneArrayBuffer(buffer, deep, seen) {
+    if (deep) {
+        const cached = seen.get(buffer);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = buffer.slice(0);
+        seen.set(buffer, result);
+        return result;
+    }
+    const result = new ArrayBuffer(buffer.byteLength);
+    new Uint8Array(result).set(new Uint8Array(buffer));
+    return result;
+}
+function cloneDataView(dataView, deep, seen, options) {
+    const buffer = deep
+        ? baseClone(dataView.buffer, seen, options)
+        : cloneArrayBuffer(dataView.buffer, false, seen);
+    const result = new DataView(buffer, dataView.byteOffset, dataView.byteLength);
+    if (deep) {
+        seen.set(dataView, result);
+    }
+    return result;
+}
+function cloneTypedArray(typed, deep, seen, options) {
+    const buffer = deep
+        ? baseClone(typed.buffer, seen, options)
+        : typed.buffer;
+    const Ctor = typed.constructor;
+    const result = new Ctor(buffer, typed.byteOffset, typed.byteLength);
+    if (deep) {
+        seen.set(typed, result);
+    }
+    return result;
+}
+function cloneError(value) {
+    const Ctor = value.constructor;
+    const result = new Ctor(value.message);
+    result.name = value.name;
+    if (value.stack) {
+        result.stack = value.stack;
+    }
+    return result;
+}
+function cloneBoxedPrimitive(value) {
+    return Object(value.valueOf());
+}
+function cloneProperties(source, result, deep, seen, options) {
+    const { customizer } = options;
+    for (const key of Reflect.ownKeys(source)) {
+        const subValue = source[key];
+        if (customizer) {
+            const customized = customizer(subValue, key, result, seen);
+            if (customized !== undefined) {
+                result[key] = customized;
+                continue;
+            }
+        }
+        result[key] = deep ? baseClone(subValue, seen, options) : subValue;
+    }
+}
+/**
+ * 内部共享克隆实现，对齐 Lodash baseClone 的常见类型与 customizer 语义。
+ *
+ * @internal
+ */
+function baseClone(value, seen = new WeakMap(), options = {}) {
+    const { deep = false, customizer } = options;
+    if (customizer) {
+        const customized = customizer(value, undefined, undefined, seen);
+        if (customized !== undefined) {
+            return customized;
+        }
+    }
+    if (value === null || typeof value !== 'object') {
+        return value;
+    }
+    const objValue = value;
+    if (deep) {
+        const cached = seen.get(objValue);
+        if (cached !== undefined) {
+            return cached;
+        }
+    }
+    if (value instanceof Error) {
+        const result = cloneError(value);
+        if (deep) {
+            seen.set(objValue, result);
+        }
+        return result;
+    }
+    if (value instanceof WeakMap || value instanceof WeakSet) {
+        return value;
+    }
+    if (value instanceof Boolean ||
+        value instanceof Number ||
+        value instanceof String) {
+        return cloneBoxedPrimitive(value);
+    }
+    if (value instanceof Date) {
+        const result = new Date(value.getTime());
+        if (deep) {
+            seen.set(objValue, result);
+        }
+        return result;
+    }
+    if (value instanceof RegExp) {
+        const cloned = new RegExp(value.source, value.flags);
+        cloned.lastIndex = value.lastIndex;
+        if (deep) {
+            seen.set(objValue, cloned);
+        }
+        return cloned;
+    }
+    if (value instanceof ArrayBuffer || (typeof SharedArrayBuffer !== 'undefined' && value instanceof SharedArrayBuffer)) {
+        return cloneArrayBuffer(value, deep, seen);
+    }
+    if (value instanceof DataView) {
+        return cloneDataView(value, deep, seen, options);
+    }
+    if (ArrayBuffer.isView(value)) {
+        return cloneTypedArray(value, deep, seen, options);
+    }
+    if (Array.isArray(value)) {
+        const result = [];
+        if (deep) {
+            seen.set(objValue, result);
+        }
+        for (let i = 0; i < value.length; i++) {
+            const item = value[i];
+            if (customizer) {
+                const customized = customizer(item, i, result, seen);
+                if (customized !== undefined) {
+                    result[i] = customized;
+                    continue;
+                }
+            }
+            result[i] = deep ? baseClone(item, seen, options) : item;
+        }
+        return result;
+    }
+    if (value instanceof Map) {
+        const result = new Map();
+        if (deep) {
+            seen.set(objValue, result);
+        }
+        value.forEach((mapValue, mapKey) => {
+            let nextKey = mapKey;
+            let nextValue = mapValue;
+            if (customizer) {
+                const customizedKey = customizer(mapKey, undefined, result, seen);
+                if (customizedKey !== undefined) {
+                    nextKey = customizedKey;
+                }
+                const customizedValue = customizer(mapValue, undefined, result, seen);
+                if (customizedValue !== undefined) {
+                    nextValue = customizedValue;
+                }
+            }
+            result.set(deep ? baseClone(nextKey, seen, options) : nextKey, deep ? baseClone(nextValue, seen, options) : nextValue);
+        });
+        return result;
+    }
+    if (value instanceof Set) {
+        const result = new Set();
+        if (deep) {
+            seen.set(objValue, result);
+        }
+        value.forEach((setValue) => {
+            let nextValue = setValue;
+            if (customizer) {
+                const customized = customizer(setValue, undefined, result, seen);
+                if (customized !== undefined) {
+                    nextValue = customized;
+                }
+            }
+            result.add(deep ? baseClone(nextValue, seen, options) : nextValue);
+        });
+        return result;
+    }
+    const result = Object.create(Object.getPrototypeOf(value));
+    if (deep) {
+        seen.set(objValue, result);
+    }
+    cloneProperties(value, result, deep, seen, options);
+    return result;
+}

package/dist/cjs/_internal/baseCollectionKeys.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.baseKeys = baseKeys;
+exports.baseValues = baseValues;
+const isArrayLike_1 = __importDefault(require("./isArrayLike"));
+/**
+ * 返回集合的键名列表，语义对齐 Lodash keys。
+ *
+ * @internal
+ */
+function baseKeys(collection) {
+    var _a;
+    if (collection == null) {
+        return [];
+    }
+    if (typeof collection === 'string') {
+        return [...collection].map((_, index) => String(index));
+    }
+    if (Array.isArray(collection)) {
+        return collection.map((_, index) => String(index));
+    }
+    if ((0, isArrayLike_1.default)(collection)) {
+        const length = (_a = collection.length) !== null && _a !== void 0 ? _a : 0;
+        return Array.from({ length }, (_, index) => String(index));
+    }
+    if (typeof collection === 'object') {
+        return Object.keys(collection);
+    }
+    return [];
+}
+/**
+ * 返回集合的值列表，语义对齐 Lodash values。
+ *
+ * @internal
+ */
+function baseValues(collection) {
+    var _a;
+    if (collection == null) {
+        return [];
+    }
+    if (typeof collection === 'string') {
+        return [...collection];
+    }
+    if (Array.isArray(collection)) {
+        return [...collection];
+    }
+    if ((0, isArrayLike_1.default)(collection)) {
+        const arrayLike = collection;
+        const length = (_a = arrayLike.length) !== null && _a !== void 0 ? _a : 0;
+        return Array.from({ length }, (_, index) => arrayLike[index]);
+    }
+    if (typeof collection === 'object') {
+        return Object.values(collection);
+    }
+    return [];
+}

package/dist/cjs/_internal/baseDefaultsDeep.js

@@ -0,0 +1,59 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = baseDefaultsDeep;
+const isPlainObject_1 = __importDefault(require("./isPlainObject"));
+function shouldRecurse(target, source) {
+    return (((0, isPlainObject_1.default)(target) && (0, isPlainObject_1.default)(source)) ||
+        (Array.isArray(target) && Array.isArray(source)));
+}
+function defaultsDeepArray(target, source) {
+    const length = source.length;
+    for (let index = 0; index < length; index++) {
+        const srcValue = source[index];
+        const objValue = target[index];
+        if (objValue === undefined) {
+            target[index] = srcValue;
+            continue;
+        }
+        if (shouldRecurse(objValue, srcValue)) {
+            baseDefaultsDeep(objValue, srcValue);
+        }
+    }
+}
+function defaultsDeepObject(target, source) {
+    for (const key of Object.keys(source)) {
+        const srcValue = source[key];
+        const objValue = target[key];
+        if (objValue === undefined) {
+            target[key] = srcValue;
+            continue;
+        }
+        if (shouldRecurse(objValue, srcValue)) {
+            baseDefaultsDeep(objValue, srcValue);
+        }
+    }
+}
+/**
+ * 将 source 深合并到 object，仅填充 undefined 属性，语义对齐 Lodash defaultsDeep。
+ *
+ * @internal
+ */
+function baseDefaultsDeep(object, source) {
+    if (source == null || object == null) {
+        return;
+    }
+    if (Array.isArray(source)) {
+        if (!Array.isArray(object)) {
+            return;
+        }
+        defaultsDeepArray(object, source);
+        return;
+    }
+    if (!(0, isPlainObject_1.default)(source) || !(0, isPlainObject_1.default)(object)) {
+        return;
+    }
+    defaultsDeepObject(object, source);
+}

package/dist/cjs/_internal/baseDifference.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = baseDifference;
+/**
+ * difference / without / differenceBy 共享内核。
+ *
+ * @internal
+ */
+function baseDifference(array, values, iteratee) {
+    if (!array.length) {
+        return [];
+    }
+    const mappedValues = iteratee ? values.map(iteratee) : values;
+    const result = [];
+    outer: for (const value of array) {
+        const computed = iteratee ? iteratee(value) : value;
+        for (const excluded of mappedValues) {
+            if (Object.is(excluded, computed)) {
+                continue outer;
+            }
+        }
+        result.push(value);
+    }
+    return result;
+}

package/dist/cjs/_internal/baseExtremum.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = baseExtremum;
+const identity_1 = __importDefault(require("./identity"));
+const compareValues_1 = require("./compareValues");
+function isComparable(value) {
+    return value != null && typeof value !== 'symbol';
+}
+/**
+ * min / max 共享内核，对齐 Lodash baseExtremum。
+ *
+ * @internal
+ */
+function baseExtremum(array, iteratee = identity_1.default, preferMax) {
+    let result;
+    let computedResult;
+    for (const value of array) {
+        const current = iteratee(value);
+        const shouldUpdate = current != null &&
+            (computedResult === undefined
+                ? isComparable(current)
+                : preferMax
+                    ? (0, compareValues_1.compareAsc)(current, computedResult) > 0
+                    : (0, compareValues_1.compareAsc)(current, computedResult) < 0);
+        if (shouldUpdate) {
+            result = value;
+            computedResult = current;
+        }
+    }
+    return result;
+}

package/dist/cjs/_internal/baseExtremumBy.js

@@ -0,0 +1,63 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = baseExtremumBy;
+const baseIteratee_1 = __importDefault(require("./baseIteratee"));
+const compareValues_1 = require("./compareValues");
+const isArrayLike_1 = __importDefault(require("./isArrayLike"));
+/**
+ * 按 iteratee 返回值查找最大或最小元素。
+ *
+ * @internal
+ */
+function baseExtremumBy(collection, iteratee, preferMax) {
+    var _a;
+    const resolvedIteratee = (0, baseIteratee_1.default)(iteratee);
+    let result;
+    let computedResult;
+    const compare = (value, indexOrKey, coll) => {
+        const computed = resolvedIteratee(value, indexOrKey, coll);
+        if (computedResult === undefined) {
+            result = value;
+            computedResult = computed;
+            return;
+        }
+        const compared = (0, compareValues_1.compareAsc)(computed, computedResult);
+        if (preferMax ? compared > 0 : compared < 0) {
+            result = value;
+            computedResult = computed;
+        }
+    };
+    if (collection == null) {
+        return undefined;
+    }
+    if (typeof collection === 'string') {
+        const chars = [...collection];
+        for (let index = 0; index < chars.length; index++) {
+            compare(chars[index], index, collection);
+        }
+        return result;
+    }
+    if (Array.isArray(collection)) {
+        for (let index = 0; index < collection.length; index++) {
+            compare(collection[index], index, collection);
+        }
+        return result;
+    }
+    if ((0, isArrayLike_1.default)(collection)) {
+        const arrayLike = collection;
+        const length = (_a = arrayLike.length) !== null && _a !== void 0 ? _a : 0;
+        for (let index = 0; index < length; index++) {
+            compare(arrayLike[index], index, collection);
+        }
+        return result;
+    }
+    if (typeof collection === 'object') {
+        for (const key of Object.keys(collection)) {
+            compare(collection[key], key, collection);
+        }
+    }
+    return result;
+}

package/dist/cjs/_internal/baseFilter.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = baseFilter;
+const isArrayLike_1 = __importDefault(require("./isArrayLike"));
+const baseIteratee_1 = __importDefault(require("./baseIteratee"));
+/**
+ * 遍历集合并保留 predicate 为真值的元素，语义对齐 Lodash filter。
+ *
+ * @internal
+ */
+function baseFilter(collection, predicate = (0, baseIteratee_1.default)()) {
+    var _a;
+    const resolvedPredicate = (0, baseIteratee_1.default)(predicate);
+    const result = [];
+    if (collection == null) {
+        return result;
+    }
+    if (typeof collection === 'string') {
+        const chars = [...collection];
+        for (let index = 0; index < chars.length; index++) {
+            const value = chars[index];
+            if (resolvedPredicate(value, index, collection)) {
+                result.push(value);
+            }
+        }
+        return result;
+    }
+    if (Array.isArray(collection)) {
+        for (let index = 0; index < collection.length; index++) {
+            const value = collection[index];
+            if (resolvedPredicate(value, index, collection)) {
+                result.push(value);
+            }
+        }
+        return result;
+    }
+    if ((0, isArrayLike_1.default)(collection)) {
+        const arrayLike = collection;
+        const length = (_a = arrayLike.length) !== null && _a !== void 0 ? _a : 0;
+        for (let index = 0; index < length; index++) {
+            const value = arrayLike[index];
+            if (resolvedPredicate(value, index, collection)) {
+                result.push(value);
+            }
+        }
+        return result;
+    }
+    if (typeof collection === 'object') {
+        const keys = Object.keys(collection);
+        for (const key of keys) {
+            const value = collection[key];
+            if (resolvedPredicate(value, key, collection)) {
+                result.push(value);
+            }
+        }
+    }
+    return result;
+}