zhiaiwan-utils 1.0.3

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

@@ -0,0 +1,15 @@
+/**
+ * 返回一个在 ms 毫秒后 resolve 的 Promise，用于异步等待。
+ *
+ * @param ms - 等待毫秒数
+ * @returns Promise
+ *
+ * @example
+ * ```ts
+ * await sleep(1000);
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function sleep(ms: number): Promise<void>;

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

@@ -0,0 +1,17 @@
+/**
+ * 调用 iteratee n 次并收集结果。
+ *
+ * @param n - 调用次数
+ * @param iteratee - 每次调用函数，接收 index
+ * @returns 结果数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.times(3, String);
+ * // => ['0', '1', '2']
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function times(n?: number, iteratee?: (index: number) => unknown): unknown[];

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

@@ -0,0 +1,19 @@
+/**
+ * 生成递增的唯一 ID 字符串，可选前缀 prefix。
+ *
+ * @param prefix - 可选前缀，null/undefined 视为空字符串
+ * @returns 唯一 ID 字符串
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.uniqueId();
+ * // => '1'
+ *
+ * zhiaiwanUtils.uniqueId('contact_');
+ * // => 'contact_2'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function uniqueId(prefix?: string | null): string;

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

@@ -0,0 +1,46 @@
+import type { FieldRule } from '../_internal/validateFieldRule';
+export type { FieldRule, FieldRuleType, ValidatorContext, ValidatorReturn } from '../_internal/validateFieldRule';
+export type { FieldRule as ValidateFieldRule };
+export type ValidateRules = Record<string, FieldRule | FieldRule[]>;
+export interface ValidateOptions {
+    /** 仅校验指定 fields path，默认校验 rules 中的全部 key */
+    fields?: string[];
+}
+export interface ValidateResult {
+    valid: boolean;
+    errors: Record<string, string[]>;
+    firstError?: {
+        field: string;
+        message: string;
+    };
+}
+/**
+ * 按规则对象校验表单/数据对象。rules 的 key 为字段路径（与 `get` 相同的路径写法），
+ * value 为单条规则或规则数组。自定义 `validator` 返回 `true` / `void` 表示通过，
+ * 返回 `false` 或非空字符串表示失败。
+ *
+ * @param values - 待校验的数据对象
+ * @param rules - 字段路径到规则的映射
+ * @param options - 可选配置
+ * @returns 校验结果；存在异步 validator 时返回 Promise
+ *
+ * @example
+ * ```ts
+ * validateFields(
+ *   { user: { name: '' }, password: 'abc', confirmPassword: '456' },
+ *   {
+ *     'user.name': { required: true, message: '请输入姓名' },
+ *     confirmPassword: {
+ *       validator: ({ value, values }) => {
+ *         if (value !== values.password) return '两次密码不一致';
+ *       },
+ *     },
+ *   },
+ * );
+ * // => { valid: false, errors: { 'user.name': ['请输入姓名'], ... } }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Util
+ */
+export default function validateFields(values: Record<string, unknown> | null | undefined, rules: ValidateRules, options?: ValidateOptions): ValidateResult | Promise<ValidateResult>;

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

@@ -0,0 +1,36 @@
+export { default as isString } from './isString';
+export { default as isNumber } from './isNumber';
+export { default as isBoolean } from './isBoolean';
+export { default as isArray } from './isArray';
+export { default as isArguments } from './isArguments';
+export { default as isArrayBuffer } from './isArrayBuffer';
+export { default as isTypedArray } from './isTypedArray';
+export { default as isBuffer } from './isBuffer';
+export { default as isFunction } from './isFunction';
+export { default as isNative } from './isNative';
+export { default as isObject } from './isObject';
+export { default as isPlainObject } from './isPlainObject';
+export { default as isUndefined } from './isUndefined';
+export { default as isNull } from './isNull';
+export { default as isNil } from './isNil';
+export { default as isDate } from './isDate';
+export { default as isRegExp } from './isRegExp';
+export { default as isSymbol } from './isSymbol';
+export { default as isInteger } from './isInteger';
+export { default as isSafeInteger } from './isSafeInteger';
+export { default as isLength } from './isLength';
+export { default as isEmpty } from './isEmpty';
+export { default as isMap } from './isMap';
+export { default as isSet } from './isSet';
+export { default as isWeakMap } from './isWeakMap';
+export { default as isWeakSet } from './isWeakSet';
+export { default as isError } from './isError';
+export { default as isEqual } from './isEqual';
+export { default as isEqualWith, type EqualCustomizer } from './isEqualWith';
+export { default as isNaN } from './isNaN';
+export { default as isFinite } from './isFinite';
+export { default as isMatch } from './isMatch';
+export { default as isMatchWith, type MatchCustomizer } from './isMatchWith';
+export { default as isArrayLike } from './isArrayLike';
+export { default as isObjectLike } from './isObjectLike';
+export { default as isElement } from './isElement';

package/dist/types/verify/isArguments.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 检查 value 是否是 `arguments` 对象。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是 arguments 对象，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * (function () {
+ *   return zhiaiwanUtils.isArguments(arguments);
+ * })();
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export { default } from '../_internal/isArguments';

package/dist/types/verify/isArray.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 检查 value 是否是一个数组。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是数组，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isArray([1, 2, 3]); // => true
+ * isArray('abc');     // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isArray(value: unknown): value is unknown[];

package/dist/types/verify/isArrayBuffer.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 检查 value 是否是 `ArrayBuffer` 对象。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是 ArrayBuffer，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isArrayBuffer(new ArrayBuffer(8));
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isArrayBuffer(value: unknown): value is ArrayBuffer;

package/dist/types/verify/isArrayLike.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 检查 value 是否为类数组（含 `length` 且非函数）。
+ *
+ * @param value - 要检查的值
+ * @returns 若为类数组返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isArrayLike([1, 2, 3]);
+ * // => true
+ *
+ * isArrayLike('abc');
+ * // => true
+ *
+ * isArrayLike({ length: 0 });
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isArrayLike(value: unknown): value is {
+    length: number;
+};

package/dist/types/verify/isBoolean.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 检查 value 是否是原始 boolean 或 Boolean 对象。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是布尔值，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isBoolean(false); // => true
+ * isBoolean(null);  // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isBoolean(value: unknown): value is boolean;

package/dist/types/verify/isBuffer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 检查 value 是否是 Node.js `Buffer` 对象；非 Node 环境恒为 false。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是 Buffer，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * // Node.js 环境
+ * isBuffer(Buffer.from('abc'));
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isBuffer(value: unknown): boolean;

package/dist/types/verify/isDate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 检查 value 是否是一个 Date 对象。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是 Date 对象，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isDate(new Date()); // => true
+ * isDate('2026-01-01'); // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isDate(value: unknown): value is Date;

package/dist/types/verify/isElement.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 检查 value 是否是 DOM Element 节点（`nodeType === 1`）。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是 DOM 元素，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * // 浏览器环境
+ * isElement(document.body);
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isElement(value: unknown): value is Element;

package/dist/types/verify/isEmpty.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 检查 value 是否为空。判定规则：`null` / `undefined`、长度为 0 的数组/字符串/`arguments`、
+ * size 为 0 的 Map / Set、没有自身可枚举属性的对象，均视为空；布尔值与数字等原始值同样视为空。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 为空，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isEmpty(null);      // => true
+ * isEmpty('');        // => true
+ * isEmpty([]);        // => true
+ * isEmpty({});        // => true
+ * isEmpty([1, 2, 3]); // => false
+ * isEmpty({ a: 1 });  // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isEmpty(value: unknown): boolean;

package/dist/types/verify/isEqual.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 执行深比较，判断两个值是否相等。支持数组、普通对象、`Date`、`RegExp`、`Map`、`Set`、
+ * `ArrayBuffer`、`DataView`、`TypedArray`、包装对象与循环引用；使用 `SameValueZero` 比较原始值。
+ *
+ * @param value - 要比较的值
+ * @param other - 另一个值
+ * @returns 若相等返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isEqual({ a: [1] }, { a: [1] });
+ * // => true
+ *
+ * isEqual(NaN, NaN);
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isEqual(value: unknown, other: unknown): boolean;

package/dist/types/verify/isEqualWith.d.ts

@@ -0,0 +1,24 @@
+import { type EqualCustomizer } from '../_internal/baseIsEqual';
+/**
+ * 执行深比较，并通过 `customizer` 自定义比较结果。
+ * 当 `customizer` 返回 `undefined` 时，回退到默认深比较逻辑。
+ *
+ * @param value - 要比较的值
+ * @param other - 另一个值
+ * @param customizer - 自定义比较函数
+ * @returns 若相等返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isEqualWith({ a: 1 }, { a: 2 }, (left, right) => {
+ *   if (typeof left === 'number' && typeof right === 'number') {
+ *     return Math.abs(left - right) <= 1;
+ *   }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isEqualWith(value: unknown, other: unknown, customizer?: EqualCustomizer): boolean;
+export type { EqualCustomizer };

package/dist/types/verify/isError.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 检查 value 是否是 Error、EvalError、RangeError、ReferenceError、SyntaxError、
+ * TypeError 或 URIError 对象。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是错误对象，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isError(new Error());     // => true
+ * isError(new TypeError()); // => true
+ * isError('Error');         // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isError(value: unknown): value is Error;

package/dist/types/verify/isFinite.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 检查 value 是否为有限数值（非 `NaN`、`Infinity`、`-Infinity`）。
+ *
+ * @param value - 要检查的值
+ * @returns 若 value 为有限数返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isFinite(3);
+ * // => true
+ *
+ * isFinite(Infinity);
+ * // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isFinite(value: unknown): value is number;

package/dist/types/verify/isFunction.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 检查 value 是否是一个函数。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是函数，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isFunction(() => {}); // => true
+ * isFunction(/abc/);    // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isFunction(value: unknown): value is Function;

package/dist/types/verify/isInteger.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 检查 value 是否是一个整数（仅原始 number，不含 Number 对象）。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是整数，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isInteger(3);    // => true
+ * isInteger(3.14); // => false
+ * isInteger('3');  // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isInteger(value: unknown): value is number;

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

@@ -0,0 +1,19 @@
+/**
+ * 检查 value 是否是合法类数组长度（`0` 到 `Number.MAX_SAFE_INTEGER` 的整数）。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是合法长度，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isLength(3);
+ * // => true
+ *
+ * isLength(-1);
+ * // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export { default } from '../_internal/isLength';

package/dist/types/verify/isMap.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 检查 value 是否是一个 Map 对象。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是 Map，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isMap(new Map()); // => true
+ * isMap(new Set()); // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isMap(value: unknown): value is Map<unknown, unknown>;

package/dist/types/verify/isMatch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 判断 object 是否包含 source 定义的全部属性值（部分匹配）。
+ * 嵌套对象、`Date`、`RegExp`、`Map`、`Set` 等按值递归匹配。
+ *
+ * @param object - 被检查的对象
+ * @param source - 属性模板
+ * @returns 若匹配返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isMatch({ a: 1, b: 2 }, { b: 2 });
+ * // => true
+ *
+ * isMatch({ a: { x: 1 } }, { a: { x: 1 } });
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isMatch(object: unknown, source: unknown): boolean;

package/dist/types/verify/isMatchWith.d.ts

@@ -0,0 +1,24 @@
+import { type MatchCustomizer } from '../_internal/baseIsMatch';
+/**
+ * 判断 object 是否包含 source 定义的全部属性值，并通过 `customizer` 自定义匹配逻辑。
+ * 当 `customizer` 返回 `undefined` 时，回退到默认匹配逻辑。
+ *
+ * @param object - 被检查的对象
+ * @param source - 属性模板
+ * @param customizer - 自定义匹配函数
+ * @returns 若匹配返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isMatchWith({ a: 1.1 }, { a: 1 }, (left, right) => {
+ *   if (typeof left === 'number' && typeof right === 'number') {
+ *     return Math.floor(left) === right;
+ *   }
+ * });
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isMatchWith(object: unknown, source: unknown, customizer?: MatchCustomizer): boolean;
+export type { MatchCustomizer };

package/dist/types/verify/isNaN.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 检查 value 是否为 `NaN`（含 Number 对象包装的 NaN）。
+ *
+ * @param value - 要检查的值
+ * @returns 若 value 为 NaN 返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isNaN(NaN);
+ * // => true
+ *
+ * isNaN('a');
+ * // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isNaN(value: unknown): value is number;

package/dist/types/verify/isNative.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 检查 value 是否是原生函数（`toString` 结果为 `[native code]`）。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是原生函数，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isNative(Array.prototype.push);
+ * // => true
+ *
+ * isNative(() => {});
+ * // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isNative(value: unknown): boolean;

package/dist/types/verify/isNil.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 检查 value 是否是 `null` 或 `undefined`。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是 null 或 undefined，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isNil(null);
+ * // => true
+ *
+ * isNil(undefined);
+ * // => true
+ *
+ * isNil('');
+ * // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isNil(value: unknown): value is null | undefined;

package/dist/types/verify/isNull.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 检查 value 是否是 null。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是 null，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isNull(null);   // => true
+ * isNull(void 0); // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isNull(value: unknown): value is null;

package/dist/types/verify/isNumber.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 检查 value 是否是原始数值或 Number 对象。
+ *
+ * 注意：`NaN` 也会返回 true，与 lodash 行为一致。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是数值，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isNumber(3);      // => true
+ * isNumber(NaN);    // => true
+ * isNumber('3');    // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isNumber(value: unknown): value is number;

package/dist/types/verify/isObject.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 检查 value 是否为语言意义上的 Object（如数组、函数、对象、正则、`new Number(0)` 等）。
+ * `null` 返回 false。
+ *
+ * @param value - 要检查的值
+ * @returns 如果 value 是对象，返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isObject({});        // => true
+ * isObject([1, 2, 3]); // => true
+ * isObject(() => {});  // => true
+ * isObject(null);      // => false
+ * isObject(1);         // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isObject(value: unknown): value is object;

package/dist/types/verify/isObjectLike.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 检查 value 是否类似对象（`typeof value` 为 `object` 且不为 `null`）。
+ *
+ * @param value - 要检查的值
+ * @returns 若 value 类似对象则返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * isObjectLike({});
+ * // => true
+ *
+ * isObjectLike([1, 2, 3]);
+ * // => true
+ *
+ * isObjectLike(null);
+ * // => false
+ *
+ * isObjectLike(() => {});
+ * // => false
+ * ```
+ *
+ * @since 1.0.0
+ * @category Verify
+ */
+export default function isObjectLike(value: unknown): value is object;