zhiaiwan-utils 1.0.3

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

@@ -0,0 +1,16 @@
+/**
+ * 将字符串首字符转换为大写。
+ *
+ * @param string - 待转换字符串
+ * @returns 首字符大写后的字符串
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.upperFirst('fred');
+ * // => 'Fred'
+ * ```
+ *
+ * @since 1.0.0
+ * @category String
+ */
+export default function upperFirst(string?: unknown): string;

package/dist/types/tree/filterTreeNodes.d.ts

@@ -0,0 +1,29 @@
+import type { FilterTreeNodesOptions, TreeRoot } from '../_internal/baseTreeTraverse';
+export type { FilterTreeNodesOptions };
+/**
+ * 收集树中所有满足 `options.predicate` 的节点；DFS 遍历全部节点。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与匹配配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 命中节点数组；`predicate` 未传或非函数时返回 `[]`
+ *
+ * @example
+ * ```ts
+ * filterTreeNodes(
+ *   {
+ *     id: 1,
+ *     title: '根',
+ *     children: [
+ *       { id: 2, title: '启用', status: 1 },
+ *       { id: 3, title: '禁用', status: 0 },
+ *     ],
+ *   },
+ *   { predicate: (node) => node.status === 1 },
+ * );
+ * // => [{ id: 2, title: '启用', status: 1 }]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function filterTreeNodes<T>(tree: TreeRoot<T> | null | undefined, options: FilterTreeNodesOptions<T>): T[];

package/dist/types/tree/findTreeNode.d.ts

@@ -0,0 +1,22 @@
+import type { FindTreeNodeOptions, TreeRoot } from '../_internal/baseTreeTraverse';
+export type { FindTreeNodeOptions };
+/**
+ * 在树中查找第一个满足 `options.predicate` 的节点；找到后立即停止 DFS 遍历。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与匹配配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 命中的节点；`predicate` 未传或非函数时返回 `null`，未找到时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * findTreeNode(
+ *   { id: 1, title: '根', children: [{ id: 2, title: '子' }] },
+ *   { predicate: (node) => node.id === 2 },
+ * );
+ * // => { id: 2, title: '子' }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function findTreeNode<T>(tree: TreeRoot<T> | null | undefined, options: FindTreeNodeOptions<T>): T | null | undefined;

package/dist/types/tree/forEachTree.d.ts

@@ -0,0 +1,25 @@
+import { type TreeIteratee, type TreeIterateeMeta, type TreePredicate, type TreeRoot, type TreeTraverseOptions } from '../_internal/baseTreeTraverse';
+export type { TreeIteratee, TreeIterateeMeta, TreePredicate, TreeRoot, TreeTraverseOptions };
+/**
+ * 深度优先遍历树；iteratee 返回 `false` 时立即停止，并返回原树。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param iteratee - 每次访问节点时调用，接收 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 遍历选项，含 `maxDepth`、`childrenKey`、`keyField`、`parentIdField`、`labelField`、`getKey`、`getParentKey`、`getLabel`
+ * @returns 原树
+ *
+ * @example
+ * ```ts
+ * forEachTree(
+ *   { id: 1, children: [{ id: 2 }, { id: 3 }] },
+ *   (node) => {
+ *     if (node.id === 2) return false;
+ *   },
+ * );
+ * // 访问 1、2 后停止
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function forEachTree<T>(tree: TreeRoot<T> | null | undefined, iteratee: TreeIteratee<T>, options?: TreeTraverseOptions): TreeRoot<T> | null | undefined;

package/dist/types/tree/getParentNodes.d.ts

@@ -0,0 +1,26 @@
+import type { GetParentNodesOptions, TreeRoot } from '../_internal/baseTreeTraverse';
+export type { GetParentNodesOptions };
+/**
+ * 查找第一个满足 `options.predicate` 的目标节点，并返回其全部父级节点（从根到直接父节点，不含目标节点本身）。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与匹配配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 父级节点数组；根节点命中时返回 `[]`；`predicate` 未传或非函数时返回 `null`；未找到或空树时返回 `undefined`
+ *
+ * @example
+ * ```ts
+ * getParentNodes(
+ *   {
+ *     id: 1,
+ *     title: '根',
+ *     children: [{ id: 2, title: '子', children: [{ id: 3, title: '孙' }] }],
+ *   },
+ *   { predicate: (node) => node.id === 3 },
+ * );
+ * // => [{ id: 1, title: '根' }, { id: 2, title: '子' }]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function getParentNodes<T>(tree: TreeRoot<T> | null | undefined, options: GetParentNodesOptions<T>): T[] | null | undefined;

package/dist/types/tree/getTreeDepth.d.ts

@@ -0,0 +1,22 @@
+import { type TreeRoot, type TreeTraverseOptions } from '../_internal/baseTreeTraverse';
+export type { TreeTraverseOptions as GetTreeDepthOptions };
+/**
+ * 获取树（或森林）的最大深度；根节点 `depth` 为 `0`。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 与 `forEachTree` 相同的 `TreeTraverseOptions`（`maxDepth` 限制下探范围）
+ * @returns 最大深度；`null`/`undefined` 时返回 `0`
+ *
+ * @example
+ * ```ts
+ * getTreeDepth({
+ *   id: 1,
+ *   children: [{ id: 2, children: [{ id: 3 }] }],
+ * });
+ * // => 2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function getTreeDepth<T>(tree: TreeRoot<T> | null | undefined, options?: TreeTraverseOptions): number;

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

@@ -0,0 +1,14 @@
+export { default as traverseTree } from './traverseTree';
+export { default as traverseTreeBfs } from './traverseTreeBfs';
+export { default as forEachTree } from './forEachTree';
+export { default as findTreeNode } from './findTreeNode';
+export { default as filterTreeNodes } from './filterTreeNodes';
+export { default as getParentNodes } from './getParentNodes';
+export { default as toTree } from './toTree';
+export { default as toFlatList } from './toFlatList';
+export { default as getTreeDepth } from './getTreeDepth';
+export { default as mapTree } from './mapTree';
+export { default as pruneTree } from './pruneTree';
+export type { TreeMapper } from './mapTree';
+export type { FilterTreeNodesOptions, FindTreeNodeOptions, GetParentNodesOptions, PruneTreeOptions, TreeIteratee, TreeIterateeMeta, TreePredicate, TreeRoot, TreeTraverseOptions, } from '../_internal/baseTreeTraverse';
+export { DEFAULT_TREE_TRAVERSE_FIELDS } from '../_internal/baseTreeTraverse';

package/dist/types/tree/mapTree.d.ts

@@ -0,0 +1,23 @@
+import { type TreeIterateeMeta, type TreeRoot, type TreeTraverseOptions } from '../_internal/baseTreeTraverse';
+export type TreeMapper<T, R = T> = (node: T, parent: T | null, depth: number, index: number, meta: TreeIterateeMeta<T>) => R;
+/**
+ * 映射树节点并保留树形结构；不修改原树，返回新树。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param mapper - 节点映射函数，签名为 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 与 `forEachTree` 相同的 `TreeTraverseOptions`（`maxDepth` 限制递归深度）
+ * @returns 映射后的新树；`null`/`undefined` 原样返回
+ *
+ * @example
+ * ```ts
+ * mapTree(
+ *   { id: 1, title: '根', children: [{ id: 2, title: '子' }] },
+ *   (node) => ({ ...node, title: `[${node.title}]` }),
+ * );
+ * // => { id: 1, title: '[根]', children: [{ id: 2, title: '[子]' }] }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function mapTree<T, R = T>(tree: TreeRoot<T> | null | undefined, mapper: TreeMapper<T, R>, options?: TreeTraverseOptions): TreeRoot<R> | null | undefined;

package/dist/types/tree/pruneTree.d.ts

@@ -0,0 +1,32 @@
+import { type PruneTreeOptions, type TreeRoot } from '../_internal/baseTreeTraverse';
+export type { PruneTreeOptions };
+/**
+ * 按条件剔除树节点并返回新树；不修改原树。
+ *
+ * - `predicate` 返回真值的节点会被剔除；命中中间节点时，其子树一并移除，子节点不会上提。
+ * - 若某节点原有子节点，剔除后 `children` 为空，则该节点也会被剔除，并向上递归剔除空壳父节点。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 遍历与剔除配置，含 `predicate`、`maxDepth` 及字段映射项
+ * @returns 剔除后的新树；`predicate` 未传或非函数时返回 `null`；根被全部剔除时单根返回 `undefined`、森林返回 `[]`
+ *
+ * @example
+ * ```ts
+ * pruneTree(
+ *   {
+ *     id: 1,
+ *     title: '根',
+ *     children: [
+ *       { id: 2, title: '' },
+ *       { id: 3, title: '保留' },
+ *     ],
+ *   },
+ *   { predicate: (node) => !node.title?.trim() },
+ * );
+ * // => { id: 1, title: '根', children: [{ id: 3, title: '保留' }] }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function pruneTree<T>(tree: TreeRoot<T> | null | undefined, options: PruneTreeOptions<T>): TreeRoot<T> | null | undefined;

package/dist/types/tree/toFlatList.d.ts

@@ -0,0 +1,26 @@
+import type { TreeRoot, TreeTraverseOptions } from '../_internal/baseTreeTraverse';
+export type { TreeTraverseOptions as ToFlatListOptions };
+/**
+ * 将嵌套树（或森林）深度优先展开为扁平列表；移除 `childrenKey` 并按层级写入 `parentIdField`。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param options - 与 `forEachTree` 相同的 `TreeTraverseOptions`（含 `maxDepth`）
+ * @returns 扁平节点数组；`null`/`undefined` 时返回 `[]`
+ *
+ * @example
+ * ```ts
+ * toFlatList({
+ *   id: 1,
+ *   title: '根',
+ *   children: [{ id: 2, title: '子' }],
+ * });
+ * // => [
+ * //   { id: 1, title: '根' },
+ * //   { id: 2, title: '子', parentId: 1 },
+ * // ]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function toFlatList<T>(tree: TreeRoot<T> | null | undefined, options?: TreeTraverseOptions): T[];

package/dist/types/tree/toTree.d.ts

@@ -0,0 +1,22 @@
+import { type TreeTraverseOptions } from '../_internal/baseTreeTraverse';
+export type { TreeTraverseOptions as ToTreeOptions };
+/**
+ * 将扁平列表（含节点键与父键）转换为嵌套树；返回根节点数组（森林）。
+ *
+ * @param list - 扁平节点列表
+ * @param options - 字段映射与 `forEachTree` 同名的 `TreeTraverseOptions`（`maxDepth` 不参与构建）
+ * @returns 根节点数组；空列表或 `null`/`undefined` 时返回 `[]`
+ *
+ * @example
+ * ```ts
+ * toTree([
+ *   { id: 1, title: '根' },
+ *   { id: 2, title: '子', parentId: 1 },
+ * ]);
+ * // => [{ id: 1, title: '根', children: [{ id: 2, title: '子', parentId: 1 }] }]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function toTree<T>(list: ReadonlyArray<T> | null | undefined, options?: TreeTraverseOptions): T[];

package/dist/types/tree/traverseTree.d.ts

@@ -0,0 +1,22 @@
+import { type TreeIteratee, type TreeIterateeMeta, type TreePredicate, type TreeRoot, type TreeTraverseOptions } from '../_internal/baseTreeTraverse';
+export type { TreeIteratee, TreeIterateeMeta, TreePredicate, TreeRoot, TreeTraverseOptions };
+/**
+ * 深度优先遍历树（前序）；遍历完所有节点，不因 iteratee 返回值中断。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param iteratee - 每次访问节点时调用，接收 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 遍历选项，含 `maxDepth`、`childrenKey`、`keyField`、`parentIdField`、`labelField`、`getKey`、`getParentKey`、`getLabel`
+ *
+ * @example
+ * ```ts
+ * traverseTree(
+ *   { id: 1, children: [{ id: 2 }] },
+ *   (node) => console.log(node.id),
+ * );
+ * // 输出 1、2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function traverseTree<T>(tree: TreeRoot<T> | null | undefined, iteratee: TreeIteratee<T>, options?: TreeTraverseOptions): void;

package/dist/types/tree/traverseTreeBfs.d.ts

@@ -0,0 +1,22 @@
+import { type TreeIteratee, type TreeIterateeMeta, type TreePredicate, type TreeRoot, type TreeTraverseOptions } from '../_internal/baseTreeTraverse';
+export type { TreeIteratee, TreeIterateeMeta, TreePredicate, TreeRoot, TreeTraverseOptions };
+/**
+ * 广度优先遍历树（按层）；遍历完所有节点，不因 iteratee 返回值中断。
+ *
+ * @param tree - 树根节点或根节点数组
+ * @param iteratee - 每次访问节点时调用，接收 `(node, parent, depth, index, meta)`，`meta` 含 `parentNodes`
+ * @param options - 遍历选项，含 `maxDepth`、`childrenKey`、`keyField`、`parentIdField`、`labelField`、`getKey`、`getParentKey`、`getLabel`
+ *
+ * @example
+ * ```ts
+ * traverseTreeBfs(
+ *   { id: 1, children: [{ id: 2, children: [{ id: 3 }] }] },
+ *   (node) => console.log(node.id),
+ * );
+ * // 输出 1、2、3
+ * ```
+ *
+ * @since 1.0.0
+ * @category Tree
+ */
+export default function traverseTreeBfs<T>(tree: TreeRoot<T> | null | undefined, iteratee: TreeIteratee<T>, options?: TreeTraverseOptions): void;

package/dist/types/util/clamp.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 将 number 限制在 [lower, upper] 闭区间内。
+ *
+ * @param number - 待限制的数
+ * @param lower - 下界
+ * @param upper - 上界
+ * @returns 限制后的数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.clamp(-10, -5, 5);
+ * // => -5
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function clamp(number: number, lower?: number, upper?: number): number;

package/dist/types/util/constant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 返回一个始终返回 value 的函数。
+ *
+ * @param value - 固定返回值
+ * @returns 常量函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.constant(5)();
+ * // => 5
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function constant<T>(value: T): () => T;

package/dist/types/util/defaultTo.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 若 value 为 `null` 或 `undefined`，返回 defaultValue，否则返回 value。
+ *
+ * @param value - 待检查的值
+ * @param defaultValue - 默认值
+ * @returns value 或 defaultValue
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.defaultTo(null, 42);
+ * // => 42
+ *
+ * zhiaiwanUtils.defaultTo(undefined, 42);
+ * // => 42
+ *
+ * zhiaiwanUtils.defaultTo(0, 42);
+ * // => 0
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function defaultTo<T>(value: T | null | undefined, defaultValue: T): T;

package/dist/types/util/defer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 推迟到当前调用栈清空后再调用 func，并传入 args。等效于 `delay(func, 1, ...args)`。
+ *
+ * @param func - 要推迟调用的函数
+ * @param args - 传给 func 的参数
+ * @returns `setTimeout` 返回的定时器 ID
+ *
+ * @example
+ * ```ts
+ * defer((text) => console.log(text), 'deferred');
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function defer(func: (...args: unknown[]) => unknown, ...args: unknown[]): ReturnType<typeof setTimeout>;

package/dist/types/util/delay.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 延迟 wait 毫秒后调用 func，并传入 args。wait 会按 Lodash 规则数值化，无效值视为 0。
+ *
+ * @param func - 要延迟调用的函数
+ * @param wait - 延迟毫秒数，默认为 0
+ * @param args - 传给 func 的参数
+ * @returns `setTimeout` 返回的定时器 ID
+ *
+ * @example
+ * ```ts
+ * delay((msg) => console.log(msg), 1000, 'later');
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function delay(func: (...args: unknown[]) => unknown, wait?: unknown, ...args: unknown[]): ReturnType<typeof setTimeout>;

package/dist/types/util/identity.d.ts

@@ -0,0 +1,17 @@
+import identity from '../_internal/identity';
+/**
+ * 返回第一个参数。
+ *
+ * @param value - 任意值
+ * @returns 传入的 value
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.identity(42);
+ * // => 42
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default identity;

package/dist/types/util/inRange.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 检查 number 是否位于 [start, end) 区间内。
+ *
+ * @param number - 待检查的值
+ * @param start - 区间起点；仅传两参时表示 end，start 置 0
+ * @param end - 区间终点（不含）
+ * @returns 是否在区间内
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.inRange(3, 2, 4);
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function inRange(number: number, start?: number, end?: number): boolean;

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

@@ -0,0 +1,22 @@
+export { default as noop } from './noop';
+export { default as identity } from './identity';
+export { default as delay } from './delay';
+export { default as defer } from './defer';
+export { default as now } from './now';
+export { default as uniqueId } from './uniqueId';
+export { default as sleep } from './sleep';
+export { default as validateFields } from './validateFields';
+export { default as defaultTo } from './defaultTo';
+export { default as size } from './size';
+export { default as range } from './range';
+export { default as times } from './times';
+export { default as constant } from './constant';
+export { default as negate } from './negate';
+export { default as iteratee } from './iteratee';
+export { default as property } from './property';
+export { default as matches } from './matches';
+export { default as matchesProperty } from './matchesProperty';
+export { default as clamp } from './clamp';
+export { default as inRange } from './inRange';
+export { default as random } from './random';
+export type { FieldRule, FieldRuleType, ValidateFieldRule, ValidateOptions, ValidateResult, ValidateRules, ValidatorContext, ValidatorReturn, } from './validateFields';

package/dist/types/util/iteratee.d.ts

@@ -0,0 +1,17 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 将 value 转为统一 iteratee 回调。
+ *
+ * @param func - 函数、属性路径、匹配对象或数组
+ * @returns 回调函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.iteratee('user')({ user: 'fred' });
+ * // => 'fred'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function iteratee(func?: IterateeShorthand): (value: unknown, indexOrKey?: number | string, collection?: unknown) => unknown;

package/dist/types/util/matches.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 创建部分深度匹配 source 属性的断言函数。
+ *
+ * @param source - 要匹配的属性对象
+ * @returns 断言函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.matches({ a: 1 })({ a: 1, b: 2 });
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function matches(source: object): (object: unknown) => boolean;

package/dist/types/util/matchesProperty.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 创建比较 object 指定路径值与 srcValue 的断言函数。
+ *
+ * @param path - 属性路径
+ * @param srcValue - 期望值
+ * @returns 断言函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.matchesProperty('a', 1)({ a: 1, b: 2 });
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function matchesProperty(path: string | ReadonlyArray<string | number>, srcValue: unknown): (object: unknown) => boolean;

package/dist/types/util/negate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 创建一个对 predicate 结果取反的函数。
+ *
+ * @param predicate - 原断言函数
+ * @returns 取反后的函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.negate(Boolean)(1);
+ * // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function negate(predicate: (...args: unknown[]) => unknown): (...args: unknown[]) => boolean;

package/dist/types/util/noop.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 一个什么都不做的函数，常用作默认回调。
+ *
+ * @returns `undefined`
+ *
+ * @example
+ * ```ts
+ * noop();
+ * // => undefined
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function noop(): void;

package/dist/types/util/now.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 返回当前时间的毫秒时间戳，等效于 `Date.now()`。
+ *
+ * @returns 毫秒时间戳
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.now();
+ * // => 1700000000000
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function now(): number;

package/dist/types/util/property.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 创建读取 object 指定路径值的访问器函数。
+ *
+ * @param path - 属性路径
+ * @returns 访问器函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.property('a')({ a: 1 });
+ * // => 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function property(path: string | ReadonlyArray<string | number>): (object: unknown) => unknown;

package/dist/types/util/random.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 生成 [lower, upper] 范围内的随机数。
+ *
+ * @param lower - 下界，默认 0
+ * @param upper - 上界，默认 1
+ * @param floating - 是否返回浮点数
+ * @returns 随机数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.random(0, 5);
+ * // => 0 到 5 的整数
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function random(lower?: number | boolean, upper?: number | boolean, floating?: boolean): number;

package/dist/types/util/range.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 创建从 start 到 end（不含）按 step 递增的数字数组。
+ *
+ * @param start - 起始值；仅传一个参数时表示 end，start 置 0
+ * @param end - 结束值（不含）
+ * @param step - 步长，默认 1 或 -1
+ * @returns 数字数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.range(4);
+ * // => [0, 1, 2, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function range(start?: number, end?: number, step?: number): number[];

package/dist/types/util/size.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 返回 collection 的长度；Map / Set 返回 size，对象返回自有可枚举键数量。
+ *
+ * @param collection - 待检查的集合
+ * @returns 集合长度
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.size([1, 2, 3]);
+ * // => 3
+ *
+ * zhiaiwanUtils.size({ a: 1, b: 2 });
+ * // => 2
+ *
+ * zhiaiwanUtils.size('abc');
+ * // => 3
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function size(collection: unknown): number;