zhiaiwan-utils 1.0.3

package/dist/types/convert/toString.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 将 value 转为字符串；`null` / `undefined` 转为 `''`。
+ *
+ * @param value - 待转换的值
+ * @returns 字符串
+ *
+ * @example
+ * ```ts
+ * toString(null);
+ * // => ''
+ *
+ * toString(-0);
+ * // => '-0'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toString(value: unknown): string;

package/dist/types/convert/toUpper.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 将 value 转为大写字符串。
+ *
+ * @param value - 待转换的值
+ * @returns 大写字符串
+ *
+ * @example
+ * ```ts
+ * toUpper('--Foo-Bar--');
+ * // => '--FOO-BAR--'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toUpper(value: unknown): string;

package/dist/types/function/after.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 创建一个跳过前 `n - 1` 次调用的函数；从第 n 次起执行 func。
+ *
+ * @param n - 开始执行的调用序号（从 1 起计）
+ * @param func - 要延迟执行的函数
+ * @returns 包装后的新函数
+ *
+ * @example
+ * ```ts
+ * let count = 0;
+ * const delayed = after(3, () => ++count);
+ * delayed(); // => undefined
+ * delayed(); // => undefined
+ * delayed(); // => 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function after<A extends unknown[], R>(n: number, func: (...args: A) => R): (...args: A) => R | undefined;

package/dist/types/function/before.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 创建一个最多调用 func `n - 1` 次的函数；达到上限后返回最后一次调用结果。
+ *
+ * @param n - 调用次数上限（不含第 n 次实际执行）
+ * @param func - 要限制的函数
+ * @returns 限制后的新函数
+ *
+ * @example
+ * ```ts
+ * let count = 0;
+ * const limited = before(3, () => ++count);
+ * limited(); // => 1
+ * limited(); // => 2
+ * limited(); // => 2
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function before<A extends unknown[], R>(n: number, func: (...args: A) => R): (...args: A) => R | undefined;

package/dist/types/function/curry.d.ts

@@ -0,0 +1,27 @@
+export interface CurriedFunction {
+    (...args: unknown[]): unknown;
+    placeholder: object;
+}
+export declare const curryPlaceholder: {};
+/**
+ * 创建可柯里化的函数。
+ *
+ * @param func - 原函数
+ * @param arity - 参数个数，默认 func.length
+ * @returns 柯里化函数
+ *
+ * @example
+ * ```ts
+ * const curried = zhiaiwanUtils.curry((a: number, b: number, c: number) => [a, b, c]);
+ * curried(1)(2)(3);
+ * // => [1, 2, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+declare function curry(func: (...args: unknown[]) => unknown, arity?: number): CurriedFunction;
+declare namespace curry {
+    var placeholder: {};
+}
+export default curry;

package/dist/types/function/debounce.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 创建一个防抖函数，在最后一次调用后等待 wait 毫秒才执行 func。
+ * 返回的函数带有 `cancel` 与 `flush` 方法；在 trailing 触发前重复调用会返回上次 func 的执行结果。
+ *
+ * @param func - 要防抖的函数
+ * @param wait - 延迟毫秒数，默认为 0
+ * @param options - 配置项：`leading` 是否在超时前沿触发；`trailing` 是否在超时后沿触发；`maxWait` 允许延迟的最长时间
+ * @returns 防抖后的新函数
+ *
+ * @example
+ * ```ts
+ * const save = debounce(() => persist(), 300);
+ * window.addEventListener('resize', save);
+ *
+ * const sendMail = debounce(send, 300, { leading: true, trailing: false });
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export interface DebounceOptions {
+    leading?: boolean;
+    maxWait?: number;
+    trailing?: boolean;
+}
+export interface DebouncedFunction<A extends unknown[], R> {
+    (...args: A): R | undefined;
+    cancel(): void;
+    flush(): R | undefined;
+}
+export default function debounce<A extends unknown[], R>(func: (...args: A) => R, wait?: number, options?: DebounceOptions): DebouncedFunction<A, R>;

package/dist/types/function/flow.d.ts

@@ -0,0 +1,18 @@
+type FlowFunction = (...args: unknown[]) => unknown;
+/**
+ * 创建一个按顺序组合多个函数的复合函数。
+ *
+ * @param funcs - 待组合的函数（可传数组）
+ * @returns 复合函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.flow([(a: number) => a + 1, (a: number) => a * 2])(1);
+ * // => 4
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+declare const _default: (...funcs: Array<FlowFunction | FlowFunction[]>) => (this: unknown, ...args: unknown[]) => unknown;
+export default _default;

package/dist/types/function/flowRight.d.ts

@@ -0,0 +1,18 @@
+type FlowFunction = (...args: unknown[]) => unknown;
+/**
+ * 创建一个从右向左组合多个函数的复合函数。
+ *
+ * @param funcs - 待组合的函数（可传数组）
+ * @returns 复合函数
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.flowRight([(a: number) => a + 1, (a: number) => a * 2])(1);
+ * // => 3
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function flowRight(...funcs: Array<FlowFunction | FlowFunction[]>): FlowFunction;
+export {};

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

@@ -0,0 +1,11 @@
+export { default as once } from './once';
+export { default as debounce, type DebounceOptions, type DebouncedFunction } from './debounce';
+export { default as throttle, type ThrottleOptions, type ThrottledFunction } from './throttle';
+export { default as before } from './before';
+export { default as after } from './after';
+export { default as memoize, type MemoizedFunction } from './memoize';
+export { default as partial, partialPlaceholder } from './partial';
+export { default as partialRight } from './partialRight';
+export { default as flow } from './flow';
+export { default as flowRight } from './flowRight';
+export { default as curry, curryPlaceholder, type CurriedFunction } from './curry';

package/dist/types/function/memoize.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 创建一个记忆化函数，缓存 func 的计算结果。默认以第一个参数作为缓存键，
+ * 可通过 resolver 自定义键生成逻辑。
+ *
+ * @param func - 要记忆化的函数
+ * @param resolver - 自定义缓存键生成函数
+ * @returns 带 cache 属性的记忆化函数
+ *
+ * @example
+ * ```ts
+ * let count = 0;
+ * const sum = memoize((a: number, b: number) => {
+ *   count += 1;
+ *   return a + b;
+ * });
+ * sum(1, 2); // => 3, count === 1
+ * sum(1, 2); // => 3, count === 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export interface MemoizeCache<R> {
+    clear(): void;
+    delete(key: unknown): boolean;
+    get(key: unknown): R | undefined;
+    has(key: unknown): boolean;
+    set(key: unknown, value: R): MemoizeCache<R>;
+}
+export interface MemoizedFunction<A extends unknown[], R> {
+    (...args: A): R;
+    cache: MemoizeCache<R>;
+}
+export interface MemoizeCacheConstructor<R> {
+    new (): MemoizeCache<R>;
+}
+declare function memoize<A extends unknown[], R>(func: (...args: A) => R, resolver?: (...args: A) => unknown): MemoizedFunction<A, R>;
+declare namespace memoize {
+    var Cache: MemoizeCacheConstructor<unknown>;
+}
+export default memoize;

package/dist/types/function/once.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 创建一个只能调用 func 一次的函数。重复调用返回首次调用的结果。
+ *
+ * @param func - 要限制的函数
+ * @returns 限制后的新函数
+ *
+ * @example
+ * ```ts
+ * let count = 0;
+ * const init = once(() => ++count);
+ * init(); // => 1
+ * init(); // => 1
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export default function once<A extends unknown[], R>(func: (...args: A) => R): (...args: A) => R;

package/dist/types/function/partial.d.ts

@@ -0,0 +1,26 @@
+import { partialPlaceholder } from '../_internal/composePartials';
+export { partialPlaceholder };
+/**
+ * 创建一个偏函数，将 partials 参数预置到 func 参数列表前部。
+ * 可用 `partial.placeholder` 占位，调用时再填入实参。
+ *
+ * @param func - 原函数
+ * @param partials - 预置参数
+ * @returns 偏函数
+ *
+ * @example
+ * ```ts
+ * const fn = (a: number, b: number, c: number) => [a, b, c];
+ * const preset = partial(fn, partial.placeholder, 2);
+ * preset(1, 3);
+ * // => [1, 2, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+declare function partial<A extends unknown[], R>(func: (...args: A) => R, ...partials: unknown[]): (...args: unknown[]) => R;
+declare namespace partial {
+    var placeholder: typeof partialPlaceholder;
+}
+export default partial;

package/dist/types/function/partialRight.d.ts

@@ -0,0 +1,25 @@
+import { partialPlaceholder } from '../_internal/composePartials';
+/**
+ * 创建一个偏函数，将 partials 参数预置到 func 参数列表尾部。
+ * 可用 `partialRight.placeholder` 占位，调用时再填入实参。
+ *
+ * @param func - 原函数
+ * @param partials - 预置参数
+ * @returns 偏函数
+ *
+ * @example
+ * ```ts
+ * const fn = (a: number, b: number, c: number) => [a, b, c];
+ * const preset = partialRight(fn, 2, partialRight.placeholder);
+ * preset(1, 3);
+ * // => [1, 2, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+declare function partialRight<A extends unknown[], R>(func: (...args: A) => R, ...partials: unknown[]): (...args: unknown[]) => R;
+declare namespace partialRight {
+    var placeholder: typeof partialPlaceholder;
+}
+export default partialRight;

package/dist/types/function/throttle.d.ts

@@ -0,0 +1,26 @@
+import { type DebouncedFunction } from './debounce';
+/**
+ * 创建一个节流函数，在 wait 毫秒内最多执行 func 一次。
+ * 基于 debounce 实现，默认 `leading` 与 `trailing` 均为 true。
+ * 返回的函数带有 `cancel` 与 `flush` 方法。
+ *
+ * @param func - 要节流的函数
+ * @param wait - 时间窗口毫秒数，默认为 0
+ * @param options - 配置项：`leading` 是否在窗口开始时触发；`trailing` 是否在窗口结束时触发
+ * @returns 节流后的新函数
+ *
+ * @example
+ * ```ts
+ * const onScroll = throttle(() => update(), 200);
+ * window.addEventListener('scroll', onScroll);
+ * ```
+ *
+ * @since 1.0.0
+ * @category Function
+ */
+export interface ThrottleOptions {
+    leading?: boolean;
+    trailing?: boolean;
+}
+export type ThrottledFunction<A extends unknown[], R> = DebouncedFunction<A, R>;
+export default function throttle<A extends unknown[], R>(func: (...args: A) => R, wait?: number, options?: ThrottleOptions): ThrottledFunction<A, R>;

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+export { version } from './version';
+export * from './array';
+export * from './object';
+export * from './string';
+export * from './convert';
+export * from './tree';
+export * from './util';
+export * from './verify';
+export * from './function';
+export * from './color';

package/dist/types/object/assign.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 将 sources 的自有可枚举属性浅合并到 object，后续来源覆盖先前值。
+ *
+ * @param object - 目标对象
+ * @param sources - 一个或多个源对象
+ * @returns 合并后的 object
+ *
+ * @example
+ * ```ts
+ * const obj = { a: 1 };
+ * zhiaiwanUtils.assign(obj, { b: 2 }, { b: 3, c: 4 });
+ * // => { a: 1, b: 3, c: 4 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Object
+ */
+export default function assign<T extends object>(object: T, ...sources: unknown[]): T;

package/dist/types/object/clone.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 创建 `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<T>(value: T): T;

package/dist/types/object/cloneDeep.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 递归创建 `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<T>(value: T): T;

package/dist/types/object/cloneDeepWith.d.ts

@@ -0,0 +1,23 @@
+import { type CloneCustomizer } 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<T>(value: T, customizer?: CloneCustomizer): T;
+export type { CloneCustomizer };

package/dist/types/object/cloneWith.d.ts

@@ -0,0 +1,23 @@
+import { type CloneCustomizer } 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<T>(value: T, customizer?: CloneCustomizer): T;
+export type { CloneCustomizer };

package/dist/types/object/defaults.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 将 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<T extends object>(object: T, ...sources: unknown[]): T;

package/dist/types/object/defaultsDeep.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 将 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<T extends object>(object: T, ...sources: unknown[]): T;

package/dist/types/object/findKey.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 返回对象中第一个满足 `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<T extends object>(object: T | null | undefined, predicate?: (value: unknown, key: string, object: T) => unknown): string | undefined;

package/dist/types/object/findLastKey.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 从右往左返回对象中最后一个满足 `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<T extends object>(object: T | null | undefined, predicate?: (value: unknown, key: string, object: T) => unknown): string | undefined;

package/dist/types/object/forIn.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 遍历 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<T extends object>(object: T | null | undefined, iteratee?: (value: unknown, key: string, object: T) => unknown): T | null | undefined;

package/dist/types/object/forOwn.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 遍历 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<T extends object>(object: T | null | undefined, iteratee?: (value: unknown, key: string, object: T) => unknown): T | null | undefined;

package/dist/types/object/fromPairs.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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: ReadonlyArray<readonly [PropertyKey, unknown]> | null | undefined): Record<string, unknown>;

package/dist/types/object/get.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 根据路径 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<T = unknown>(object: unknown, path: string | ReadonlyArray<string | number>, defaultValue?: T): T | undefined;

package/dist/types/object/has.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 检查 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: unknown, path: string | ReadonlyArray<string | number>): boolean;

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

@@ -0,0 +1,29 @@
+export { default as clone } from './clone';
+export { default as cloneDeep } from './cloneDeep';
+export { default as cloneWith, type CloneCustomizer } 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, type MergeCustomizer } 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, type UpdateCustomizer } from './updateWith';