zhiaiwan-utils 1.0.3

package/dist/types/_internal/isLength.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 判断 value 是否为合法类数组长度。
+ *
+ * @internal
+ */
+export default function isLength(value: unknown): value is number;

package/dist/types/_internal/isPlainObject.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 内部辅助：判断值是否为“纯对象”（由 `{}` 或 `new Object()` 创建，或原型为 null）。
+ *
+ * 该函数仅供库内部复用，不作为公共 API 导出。
+ *
+ * @internal
+ */
+export default function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/types/_internal/mergeInto.d.ts

@@ -0,0 +1,7 @@
+import { type MergeCustomizer } from './baseMerge';
+/**
+ * 内部辅助：将 sources 合并到 object，可选自定义合并器。
+ *
+ * @internal
+ */
+export default function mergeInto<T>(object: T, sources: unknown[], customizer?: MergeCustomizer): T;

package/dist/types/_internal/repeatString.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 内部辅助：将字符串重复 n 次。
+ *
+ * @internal
+ */
+export default function repeatString(string: string, count: number): string;

package/dist/types/_internal/toInteger.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 内部辅助：将值转为整数，语义对齐 convert/toInteger。
+ *
+ * @internal
+ */
+export default function toInteger(value: unknown): number;

package/dist/types/_internal/toLength.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 内部辅助：将值转为合法类数组长度，语义对齐 convert/toLength。
+ *
+ * @internal
+ */
+export default function toLength(value: unknown): number;

package/dist/types/_internal/toPath.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 内部辅助：将属性路径规范化为字符串键数组。
+ * 支持点号与方括号写法，如 `'a.b[0].c'` → `['a', 'b', '0', 'c']`。
+ *
+ * @internal
+ */
+export default function toPath(path: string | ReadonlyArray<string | number>): string[];

package/dist/types/_internal/upperFirst.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 首字母大写，对齐 Lodash upperFirst。
+ *
+ * @internal
+ */
+export default function upperFirst(string: string): string;

package/dist/types/_internal/validateFieldRule.d.ts

@@ -0,0 +1,26 @@
+export type FieldRuleType = 'string' | 'number' | 'boolean' | 'integer' | 'array' | 'object' | 'email' | 'url' | 'date';
+export interface FieldRule {
+    required?: boolean;
+    type?: FieldRuleType;
+    pattern?: RegExp;
+    min?: number;
+    max?: number;
+    len?: number;
+    enum?: readonly unknown[];
+    message?: string | ((value: unknown, rule: FieldRule) => string);
+    validator?: (ctx: ValidatorContext) => ValidatorReturn;
+}
+export interface ValidatorContext {
+    value: unknown;
+    values: Record<string, unknown>;
+    field: string;
+    rule: FieldRule;
+}
+export type ValidatorReturn = boolean | string | void | Promise<boolean | string | void>;
+export type FieldRuleResult = string | null | Promise<string | null>;
+/**
+ * 执行单条字段规则，失败时返回错误文案，通过时返回 null。
+ *
+ * @internal
+ */
+export default function validateFieldRule(ctx: ValidatorContext): FieldRuleResult;

package/dist/types/_internal/words.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 拆分字符串为单词数组，对齐 Lodash words 默认 pattern。
+ *
+ * @internal
+ */
+export default function words(string: string): string[];

package/dist/types/array/chunk.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 将 array 按指定长度切分为多个子数组。
+ *
+ * @param array - 待切分的数组
+ * @param size - 每个分块的长度，默认 1
+ * @returns 分块后的二维数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.chunk(['a', 'b', 'c', 'd'], 2);
+ * // => [['a', 'b'], ['c', 'd']]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function chunk(array: unknown[] | null | undefined, size?: number): unknown[][];

package/dist/types/array/compact.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 移除数组中所有假值（`false`、`null`、`0`、`""`、`undefined`、`NaN`）。
+ *
+ * @param array - 待处理的数组
+ * @returns 过滤后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.compact([0, 1, false, 2, '', 3]);
+ * // => [1, 2, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function compact(array: unknown): unknown[];

package/dist/types/array/concat.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 创建一个新数组，按顺序拼接各参数；数组参数会展开一层。
+ *
+ * @param array - 第一个数组或元素
+ * @param values - 后续数组或元素
+ * @returns 拼接后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.concat([1], 2, [3], [[4]]);
+ * // => [1, 2, 3, [4]]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function concat(array: unknown, ...values: unknown[]): unknown[];

package/dist/types/array/difference.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 创建按 SameValueZero 排除其余数组元素后的新数组。
+ *
+ * @param array - 待处理的数组
+ * @param values - 要排除的数组（可传多个）
+ * @returns 差集数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.difference([2, 1], [2, 3]);
+ * // => [1]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function difference(array: unknown[], ...values: unknown[][]): unknown[];

package/dist/types/array/differenceBy.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 类似 difference，但按 iteratee 返回值比较排除项。
+ *
+ * @param array - 待处理的数组
+ * @param values - 要排除的数组（可传多个），最后一项可为 iteratee
+ * @param iteratee - 比较依据的函数或简写
+ * @returns 差集数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.differenceBy([2.1, 1.2], [2.3, 3.4], Math.floor);
+ * // => [1.2]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function differenceBy(array: unknown[], ...args: unknown[]): unknown[];

package/dist/types/array/drop.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 从 array 头部跳过 n 个元素。
+ *
+ * @param array - 待处理的数组
+ * @param n - 跳过数量，默认 1
+ * @returns 剩余元素组成的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.drop([1, 2, 3], 2);
+ * // => [3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function drop(array: unknown[], n?: number): unknown[];

package/dist/types/array/each.d.ts

@@ -0,0 +1,18 @@
+import forEach from './forEach';
+/**
+ * `forEach` 的别名，遍历集合元素；iteratee 返回 `false` 时立即停止。
+ *
+ * @param collection - 待遍历的集合（数组、对象、字符串或类数组）
+ * @param iteratee - 每次迭代调用的函数，接收 `(value, index|key, collection)`
+ * @returns 原集合
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.each([1, 2, 3], (n) => console.log(n));
+ * // => [1, 2, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default forEach;

package/dist/types/array/every.d.ts

@@ -0,0 +1,21 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 检查 collection 中是否所有元素均满足 predicate。
+ *
+ * @param collection - 待检查的集合
+ * @param predicate - 每次迭代调用的断言函数或简写
+ * @returns 若全部通过返回 true；空集合返回 true
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.every([true, 1, null, 'yes'], Boolean);
+ * // => false
+ *
+ * zhiaiwanUtils.every([], Boolean);
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function every(collection: unknown, predicate?: IterateeShorthand): boolean;

package/dist/types/array/filter.d.ts

@@ -0,0 +1,18 @@
+import type { IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 遍历 collection，返回 predicate 为真值的所有元素组成的新数组。
+ *
+ * @param collection - 待筛选的集合
+ * @param predicate - 每次迭代调用的断言函数或简写
+ * @returns 筛选后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.filter([1, 2, 3, 4], (n) => n % 2 === 0);
+ * // => [2, 4]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function filter(collection: unknown, predicate?: IterateeShorthand): unknown[];

package/dist/types/array/find.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 返回集合中第一个满足 `predicate` 的元素。
+ *
+ * @param collection - 待查找的集合（数组、对象、字符串或类数组）
+ * @param predicate - 匹配函数，接收 `(value, index|key, collection)`，默认匹配真值
+ * @param fromIndex - 类数组的起始下标
+ * @returns 匹配元素，未找到时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * const users = [
+ *   { user: 'barney', age: 36, active: true },
+ *   { user: 'fred', age: 40, active: false },
+ * ];
+ *
+ * find(users, ({ age }) => age < 40);
+ * // => { user: 'barney', age: 36, active: true }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function find<C>(collection: C, predicate?: (value: unknown, indexOrKey: number | string, collection: C) => unknown, fromIndex?: number): unknown;

package/dist/types/array/findIndex.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 返回数组中第一个满足 `predicate` 的下标。
+ *
+ * @param array - 待查找的数组或类数组
+ * @param predicate - 匹配函数，接收 `(value, index, array)`，默认匹配真值
+ * @param fromIndex - 起始下标
+ * @returns 匹配下标，未找到时返回 `-1`
+ *
+ * @example
+ * ```ts
+ * findIndex([1, 2, 3, 4], (n) => n % 2 === 0);
+ * // => 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function findIndex<T>(array: T, predicate?: (value: unknown, index: number, array: T) => unknown, fromIndex?: number): number;

package/dist/types/array/findLast.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 从右往左返回集合中最后一个满足 `predicate` 的元素。
+ *
+ * @param collection - 待查找的集合（数组、对象、字符串或类数组）
+ * @param predicate - 匹配函数，接收 `(value, index|key, collection)`，默认匹配真值
+ * @param fromIndex - 类数组的起始下标
+ * @returns 匹配元素，未找到时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * findLast([1, 2, 3, 4], (n) => n % 2 === 1);
+ * // => 3
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function findLast<C>(collection: C, predicate?: (value: unknown, indexOrKey: number | string, collection: C) => unknown, fromIndex?: number): unknown;

package/dist/types/array/findLastIndex.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 从右往左返回数组中最后一个满足 `predicate` 的下标。
+ *
+ * @param array - 待查找的数组或类数组
+ * @param predicate - 匹配函数，接收 `(value, index, array)`，默认匹配真值
+ * @param fromIndex - 起始下标
+ * @returns 匹配下标，未找到时返回 `-1`
+ *
+ * @example
+ * ```ts
+ * findLastIndex([1, 2, 3, 4], (n) => n % 2 === 1);
+ * // => 2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function findLastIndex<T>(array: T, predicate?: (value: unknown, index: number, array: T) => unknown, fromIndex?: number): number;

package/dist/types/array/flatten.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 将 array 展平一层。
+ *
+ * @param array - 待展平的数组
+ * @returns 展平后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.flatten([1, [2, [3, [4]], 5]]);
+ * // => [1, 2, [3, [4]], 5]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function flatten(array: unknown): unknown[];

package/dist/types/array/flattenDeep.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 递归展平 array 的所有嵌套层级。
+ *
+ * @param array - 待展平的数组
+ * @returns 完全展平后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.flattenDeep([1, [2, [3, [4]], 5]]);
+ * // => [1, 2, 3, 4, 5]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function flattenDeep(array: unknown): unknown[];

package/dist/types/array/forEach.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 遍历集合元素；iteratee 返回 `false` 时立即停止。
+ *
+ * @param collection - 待遍历的集合（数组、对象、字符串或类数组）
+ * @param iteratee - 每次迭代调用的函数，接收 `(value, index|key, collection)`
+ * @returns 原集合
+ *
+ * @example
+ * ```ts
+ * forEach([1, 2, 3], (n) => {
+ *   if (n === 2) return false;
+ *   console.log(n);
+ * });
+ * // 输出 1
+ *
+ * forEach({ a: 1, b: 2 }, (value, key) => console.log(key, value));
+ * // => { a: 1, b: 2 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function forEach<C>(collection: C, iteratee: (value: unknown, indexOrKey: number | string, collection: C) => unknown): C;

package/dist/types/array/forEachRight.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 从右向左遍历集合元素；iteratee 返回 `false` 时立即停止。
+ *
+ * @param collection - 待遍历的集合（数组、对象、字符串或类数组）
+ * @param iteratee - 每次迭代调用的函数，接收 `(value, index|key, collection)`
+ * @returns 原集合
+ *
+ * @example
+ * ```ts
+ * forEachRight([1, 2, 3], (n) => console.log(n));
+ * // 输出 3, 2, 1
+ *
+ * forEachRight({ a: 1, b: 2 }, (value, key) => console.log(key, value));
+ * // 输出 b 2, a 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function forEachRight<C>(collection: C, iteratee: (value: unknown, indexOrKey: number | string, collection: C) => unknown): C;

package/dist/types/array/groupBy.d.ts

@@ -0,0 +1,18 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 根据 iteratee 返回值对 collection 分组，返回键为分组值、值为元素数组的对象。
+ *
+ * @param collection - 待分组的集合
+ * @param iteratee - 分组依据的函数或简写
+ * @returns 分组结果
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.groupBy([6.1, 4.2, 6.3], Math.floor);
+ * // => { '4': [4.2], '6': [6.1, 6.3] }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function groupBy(collection: unknown, iteratee?: IterateeShorthand): Record<string, unknown[]>;

package/dist/types/array/head.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 获取 array 的第一个元素。
+ *
+ * @param array - 待查询的数组
+ * @returns 第一个元素
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.head([1, 2, 3]);
+ * // => 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function head(array: unknown[]): unknown;

package/dist/types/array/includes.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 检查 collection 是否包含 value；数组与字符串支持 fromIndex。
+ *
+ * @param collection - 待检查的集合
+ * @param value - 要查找的值
+ * @param fromIndex - 数组或字符串的起始下标
+ * @returns 若包含返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.includes([1, 2, 3], 2);
+ * // => true
+ *
+ * zhiaiwanUtils.includes({ a: 1, b: 2 }, 2);
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function includes(collection: unknown, value: unknown, fromIndex?: number): boolean;

package/dist/types/array/index.d.ts

@@ -0,0 +1,43 @@
+export { default as forEach } from './forEach';
+export { default as forEachRight } from './forEachRight';
+export { default as each } from './each';
+export { default as find } from './find';
+export { default as findLast } from './findLast';
+export { default as findIndex } from './findIndex';
+export { default as findLastIndex } from './findLastIndex';
+export { default as filter } from './filter';
+export { default as map } from './map';
+export { default as union } from './union';
+export { default as groupBy } from './groupBy';
+export { default as orderBy } from './orderBy';
+export { default as uniqBy } from './uniqBy';
+export { default as concat } from './concat';
+export { default as includes } from './includes';
+export { default as intersection } from './intersection';
+export { default as maxBy } from './maxBy';
+export { default as minBy } from './minBy';
+export { default as sortBy } from './sortBy';
+export { default as some } from './some';
+export { default as sum } from './sum';
+export { default as sumBy } from './sumBy';
+export { default as meanBy } from './meanBy';
+export { default as partition } from './partition';
+export { default as every } from './every';
+export { default as reduce } from './reduce';
+export { default as reduceRight } from './reduceRight';
+export { default as compact } from './compact';
+export { default as flatten } from './flatten';
+export { default as flattenDeep } from './flattenDeep';
+export { default as uniq } from './uniq';
+export { default as keyBy } from './keyBy';
+export { default as chunk } from './chunk';
+export { default as difference } from './difference';
+export { default as differenceBy } from './differenceBy';
+export { default as without } from './without';
+export { default as head } from './head';
+export { default as last } from './last';
+export { default as take } from './take';
+export { default as drop } from './drop';
+export { default as min } from './min';
+export { default as max } from './max';
+export { default as mean } from './mean';

package/dist/types/array/intersection.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 创建各数组按 SameValueZero 取交集后的新数组，保留首次出现顺序。
+ *
+ * @param arrays - 一个或多个数组
+ * @returns 交集数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.intersection([2, 1], [2, 3]);
+ * // => [2]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function intersection(...arrays: unknown[][]): unknown[];

package/dist/types/array/keyBy.d.ts

@@ -0,0 +1,24 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 根据 iteratee 返回值将 collection 转为键值对象，同键保留最后一个元素。
+ *
+ * @param collection - 待转换的集合
+ * @param iteratee - 生成键名的函数或简写
+ * @returns 键值映射对象
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.keyBy(
+ *   [
+ *     { dir: 'left', code: 97 },
+ *     { dir: 'right', code: 100 },
+ *   ],
+ *   'dir',
+ * );
+ * // => { left: { dir: 'left', code: 97 }, right: { dir: 'right', code: 100 } }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function keyBy(collection: unknown, iteratee?: IterateeShorthand): Record<string, unknown>;

package/dist/types/array/last.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 获取 array 的最后一个元素。
+ *
+ * @param array - 待查询的数组
+ * @returns 最后一个元素
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.last([1, 2, 3]);
+ * // => 3
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function last(array: unknown[]): unknown;

package/dist/types/array/map.d.ts

@@ -0,0 +1,18 @@
+import type { IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 遍历 collection，对每个元素执行 iteratee 并返回结果组成的新数组。
+ *
+ * @param collection - 待映射的集合
+ * @param iteratee - 每次迭代调用的函数或简写
+ * @returns 映射后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.map([1, 2, 3], (n) => n * 2);
+ * // => [2, 4, 6]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function map(collection: unknown, iteratee?: IterateeShorthand): unknown[];

package/dist/types/array/max.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 计算 array 中的最大值。
+ *
+ * @param array - 待计算的数组
+ * @returns 最大值；空数组返回 undefined
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.max([4, 2, 8, 6]);
+ * // => 8
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function max(array: unknown[]): unknown;

package/dist/types/array/maxBy.d.ts

@@ -0,0 +1,18 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 返回 iteratee 返回值最大的元素。
+ *
+ * @param collection - 待查找的集合
+ * @param iteratee - 比较依据的函数或简写
+ * @returns 最大值对应的元素
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.maxBy([{ n: 1 }, { n: 2 }], 'n');
+ * // => { n: 2 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function maxBy(collection: unknown, iteratee?: IterateeShorthand): unknown;