zhiaiwan-utils 1.0.3

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

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

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

@@ -0,0 +1,18 @@
+import type { IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 计算 array 中 iteratee 返回值的平均值。
+ *
+ * @param array - 待计算的数组
+ * @param iteratee - 每次迭代调用的函数或简写
+ * @returns 平均值；空数组返回 NaN
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.meanBy([{ n: 4 }, { n: 2 }, { n: 8 }], 'n');
+ * // => 4.666666666666667
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function meanBy(array: unknown[], iteratee?: IterateeShorthand): number;

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

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

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

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

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

@@ -0,0 +1,23 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 按 iteratee 与 orders 对 collection 排序并返回新数组。
+ *
+ * @param collection - 待排序的集合
+ * @param iteratees - 排序依据的函数、简写或数组
+ * @param orders - 排序方向 `'asc'` 或 `'desc'`，可为数组
+ * @returns 排序后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.orderBy(
+ *   [{ user: 'fred', age: 48 }, { user: 'barney', age: 34 }],
+ *   ['user', 'age'],
+ *   ['asc', 'desc'],
+ * );
+ * // => [{ user: 'barney', age: 34 }, { user: 'fred', age: 48 }]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function orderBy(collection: unknown, iteratees?: IterateeShorthand | IterateeShorthand[], orders?: 'asc' | 'desc' | Array<'asc' | 'desc'>): unknown[];

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

@@ -0,0 +1,18 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 根据 predicate 将 collection 拆分为 `[匹配项, 未匹配项]` 两个数组。
+ *
+ * @param collection - 待拆分的集合
+ * @param predicate - 每次迭代调用的断言函数或简写
+ * @returns 二元组 `[truthy, falsy]`
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.partition([1, 2, 3, 4], (n) => n % 2);
+ * // => [[1, 3], [2, 4]]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function partition(collection: unknown, predicate?: IterateeShorthand): [unknown[], unknown[]];

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

@@ -0,0 +1,19 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 将 collection 累约为单个值。
+ *
+ * @param collection - 待遍历的集合
+ * @param iteratee - 每次迭代调用的函数或简写
+ * @param accumulator - 初始累加值；未提供时使用首个元素
+ * @returns 累加结果
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.reduce([1, 2], (sum, n) => sum + (n as number), 0);
+ * // => 3
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function reduce(collection: unknown, iteratee?: IterateeShorthand, accumulator?: unknown): unknown;

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

@@ -0,0 +1,19 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 从右向左将 collection 累约为单个值。
+ *
+ * @param collection - 待遍历的集合
+ * @param iteratee - 每次迭代调用的函数或简写
+ * @param accumulator - 初始累加值；未提供时使用末尾元素
+ * @returns 累加结果
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.reduceRight([[0, 1], [2, 3], [4, 5]], (flat, other) => flat.concat(other), []);
+ * // => [4, 5, 2, 3, 0, 1]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function reduceRight(collection: unknown, iteratee?: IterateeShorthand, accumulator?: unknown): unknown;

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

@@ -0,0 +1,18 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 检查 collection 中是否存在 predicate 为真值的元素。
+ *
+ * @param collection - 待检查的集合
+ * @param predicate - 每次迭代调用的断言函数或简写
+ * @returns 若存在匹配元素返回 true，否则返回 false
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.some([null, 0, 1], Boolean);
+ * // => true
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function some(collection: unknown, predicate?: IterateeShorthand): boolean;

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

@@ -0,0 +1,18 @@
+import type { IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 按 iteratee 升序排序 collection 并返回新数组。
+ *
+ * @param collection - 待排序的集合
+ * @param iteratees - 排序依据的函数、简写或数组
+ * @returns 排序后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.sortBy([{ x: 2 }, { x: 1 }], 'x');
+ * // => [{ x: 1 }, { x: 2 }]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function sortBy(collection: unknown, iteratees?: IterateeShorthand | IterateeShorthand[]): unknown[];

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

@@ -0,0 +1,16 @@
+/**
+ * 对 array 中的值求和（使用 `+` 做 Lodash 式数值 coercion）。
+ *
+ * @param array - 待求和的数组
+ * @returns 总和
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.sum([4, 2, 8, 6]);
+ * // => 20
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function sum(array: unknown[] | null | undefined): number;

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

@@ -0,0 +1,18 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 对 array 中 iteratee 返回值求和。
+ *
+ * @param array - 待求和的数组
+ * @param iteratee - 每次迭代调用的函数或简写
+ * @returns 总和
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.sumBy([{ n: 4 }, { n: 2 }, { n: 8 }], 'n');
+ * // => 14
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function sumBy(array: unknown[] | null | undefined, iteratee?: IterateeShorthand): number;

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

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

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

@@ -0,0 +1,16 @@
+/**
+ * 创建一个按 SameValueZero 去重后的并集数组。
+ *
+ * @param arrays - 一个或多个数组
+ * @returns 去重并集
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.union([2], [1, 2], [2, 3]);
+ * // => [2, 1, 3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function union(...arrays: unknown[][]): unknown[];

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

@@ -0,0 +1,16 @@
+/**
+ * 使用 SameValueZero 比较对 array 去重，保留首次出现的元素。
+ *
+ * @param array - 待去重的数组
+ * @returns 去重后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.uniq([2, 1, 2]);
+ * // => [2, 1]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function uniq(array: unknown[]): unknown[];

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

@@ -0,0 +1,18 @@
+import { type IterateeShorthand } from '../_internal/baseIteratee';
+/**
+ * 按 iteratee 返回值对 collection 去重，保留首次出现的元素。
+ *
+ * @param array - 待去重的数组
+ * @param iteratee - 唯一性依据的函数或简写
+ * @returns 去重后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.uniqBy([2.1, 1.2, 2.3], Math.floor);
+ * // => [2.1, 1.2]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function uniqBy(array: unknown[], iteratee?: IterateeShorthand): unknown[];

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

@@ -0,0 +1,17 @@
+/**
+ * 创建排除指定值后的新数组，使用 SameValueZero 比较。
+ *
+ * @param array - 待处理的数组
+ * @param values - 要排除的值
+ * @returns 过滤后的新数组
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.without([2, 1, 2, 3], 1, 2);
+ * // => [3]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Array
+ */
+export default function without(array: unknown[], ...values: unknown[]): unknown[];

package/dist/types/color/getCssVariable.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 读取元素上的 CSS 自定义属性（变量）值。
+ *
+ * @param element - DOM 元素；浏览器环境默认 `document.body`
+ * @param property - CSS 变量名，如 `--primary-color`
+ * @param fallback - 无法读取时的回退值
+ * @returns 变量值或回退值
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.getCssVariable(document.body, '--primary-color', '#3370FF');
+ * // => '#3370FF'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Color
+ */
+export default function getCssVariable(element?: Element | null, property?: string, fallback?: string): string;

package/dist/types/color/getThemePalette.d.ts

@@ -0,0 +1,28 @@
+export interface ThemePalette {
+    /** 主色，#RRGGBB 大写 */
+    primary: string;
+    /** light-1 ~ light-9，rgb(r, g, b) 字符串 */
+    light: string[];
+    /** dark-1 ~ dark-9，rgb(r, g, b) 字符串 */
+    dark: string[];
+}
+/**
+ * 根据单个主色生成 Element Plus 风格的主题色板（primary + light/dark 各 9 档）。
+ *
+ * @param primaryColor - 十六进制主色，支持 `#RGB`、`#RRGGBB` 及不带 `#` 的写法
+ * @returns 色板对象；无效输入返回 `null`
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.getThemePalette('#405189');
+ * // => {
+ * //   primary: '#405189',
+ * //   light: ['rgb(83, 98, 149)', ...],
+ * //   dark: ['rgb(60, 75, 125)', ...],
+ * // }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Color
+ */
+export default function getThemePalette(primaryColor: string): ThemePalette | null;

package/dist/types/color/hexToRgb.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 将十六进制颜色转换为 CSS `rgb(r, g, b)` 字符串。
+ *
+ * @param hex - 十六进制颜色，支持 `#RGB`、`#RRGGBB` 及不带 `#` 的写法
+ * @returns 解析成功返回 `rgb(r, g, b)`；无效输入返回 `null`
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.hexToRgb('#f03');
+ * // => 'rgb(255, 0, 51)'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Color
+ */
+export default function hexToRgb(hex: string): string | null;

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

@@ -0,0 +1,6 @@
+export { default as rgbToHex } from './rgbToHex';
+export { default as hexToRgb } from './hexToRgb';
+export { default as rgbStringToHex } from './rgbStringToHex';
+export { default as getCssVariable } from './getCssVariable';
+export { default as getThemePalette } from './getThemePalette';
+export type { ThemePalette } from './getThemePalette';

package/dist/types/color/rgbStringToHex.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 将 `rgb()` / `rgba()` 字符串转换为十六进制颜色。
+ *
+ * @param rgbString - CSS rgb/rgba 字符串
+ * @returns 转换成功返回 `#RRGGBB` 或 `#RRGGBBAA`；无法解析时返回 `null`
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.rgbStringToHex('rgb(255, 0, 51)');
+ * // => '#FF0033'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Color
+ */
+export default function rgbStringToHex(rgbString: string): string | null;

package/dist/types/color/rgbToHex.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 将 RGB 分量转换为 `#RRGGBB` 十六进制颜色字符串。
+ *
+ * @param r - 红色分量（0–255）
+ * @param g - 绿色分量（0–255）
+ * @param b - 蓝色分量（0–255）
+ * @returns 大写十六进制颜色，如 `#FF0033`
+ *
+ * @example
+ * ```ts
+ * zhiaiwanUtils.rgbToHex(255, 0, 51);
+ * // => '#FF0033'
+ * ```
+ *
+ * @since 1.0.0
+ * @category Color
+ */
+export default function rgbToHex(r: number, g: number, b: number): string;

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

@@ -0,0 +1,13 @@
+export { default as toArray } from './toArray';
+export { default as toFinite } from './toFinite';
+export { default as toInteger } from './toInteger';
+export { default as toLength } from './toLength';
+export { default as toNumber } from './toNumber';
+export { default as toSafeInteger } from './toSafeInteger';
+export { default as toString } from './toString';
+export { default as toPath } from './toPath';
+export { default as toPlainObject } from './toPlainObject';
+export { default as toPairs } from './toPairs';
+export { default as toPairsIn } from './toPairsIn';
+export { default as toLower } from './toLower';
+export { default as toUpper } from './toUpper';

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

@@ -0,0 +1,19 @@
+/**
+ * 将 value 转为数组。
+ *
+ * @param value - 待转换的值
+ * @returns 新数组
+ *
+ * @example
+ * ```ts
+ * toArray({ a: 1, b: 2 });
+ * // => [1, 2]
+ *
+ * toArray('abc');
+ * // => ['a', 'b', 'c']
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toArray<T>(value: T): unknown[];

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

@@ -0,0 +1,19 @@
+/**
+ * 将 value 转为有限数值；`Infinity` 截断为 `Number.MAX_VALUE`，`NaN` 转为 `0`。
+ *
+ * @param value - 待转换的值
+ * @returns 有限数值
+ *
+ * @example
+ * ```ts
+ * toFinite('3.2');
+ * // => 3.2
+ *
+ * toFinite(Infinity);
+ * // => 1.7976931348623157e+308
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toFinite(value: unknown): number;

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

@@ -0,0 +1,19 @@
+/**
+ * 将 value 转为整数（向 0 取整）；`NaN` / 非有限值转为 `0`。
+ *
+ * @param value - 待转换的值
+ * @returns 整数
+ *
+ * @example
+ * ```ts
+ * toInteger(3.7);
+ * // => 3
+ *
+ * toInteger('3.7');
+ * // => 3
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toInteger(value: unknown): number;

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

@@ -0,0 +1,19 @@
+/**
+ * 将 value 转为合法类数组长度（`0` 到 `2^32 - 1`）。
+ *
+ * @param value - 待转换的值
+ * @returns 合法长度
+ *
+ * @example
+ * ```ts
+ * toLength(3.7);
+ * // => 3
+ *
+ * toLength(-1);
+ * // => 0
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toLength(value: unknown): number;

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

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

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

@@ -0,0 +1,19 @@
+/**
+ * 将 value 转为数值，对齐 Lodash `toNumber` 的解析规则。
+ *
+ * @param value - 待转换的值
+ * @returns 转换后的数值
+ *
+ * @example
+ * ```ts
+ * toNumber('3.2');
+ * // => 3.2
+ *
+ * toNumber('0b101');
+ * // => 5
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toNumber(value: unknown): number;

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

@@ -0,0 +1,16 @@
+/**
+ * 将 object 转为自身可枚举属性的 `[key, value]` 数组。
+ *
+ * @param object - 待转换的对象
+ * @returns 键值对数组
+ *
+ * @example
+ * ```ts
+ * toPairs({ a: 1, b: 2 });
+ * // => [['a', 1], ['b', 2]]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toPairs(object: object | null | undefined): [string, unknown][];

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

@@ -0,0 +1,20 @@
+/**
+ * 将 object 转为可枚举属性（含继承）的 `[key, value]` 数组。
+ *
+ * @param object - 待转换的对象
+ * @returns 键值对数组
+ *
+ * @example
+ * ```ts
+ * const parent = { a: 1 };
+ * const child = Object.create(parent);
+ * child.b = 2;
+ *
+ * toPairsIn(child);
+ * // => [['a', 1], ['b', 2]]
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toPairsIn(object: object | null | undefined): [string, unknown][];

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

@@ -0,0 +1,16 @@
+/**
+ * 将 path 转为键数组，支持 `'a.b[0].c'` 与数组路径。
+ *
+ * @param value - 属性路径
+ * @returns 键数组
+ *
+ * @example
+ * ```ts
+ * toPath('a.b[0].c');
+ * // => ['a', 'b', '0', 'c']
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export { default } from '../_internal/toPath';

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

@@ -0,0 +1,19 @@
+/**
+ * 将 value 转为普通对象，复制可枚举属性（含继承属性）。
+ *
+ * @param value - 待转换的值
+ * @returns 普通对象
+ *
+ * @example
+ * ```ts
+ * class Foo {
+ *   a = 1;
+ * }
+ * toPlainObject(new Foo());
+ * // => { a: 1 }
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toPlainObject(value: unknown): Record<string, unknown>;

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

@@ -0,0 +1,19 @@
+/**
+ * 将 value 转为安全整数，超出范围时截断到边界值。
+ *
+ * @param value - 待转换的值
+ * @returns 安全整数
+ *
+ * @example
+ * ```ts
+ * toSafeInteger('3');
+ * // => 3
+ *
+ * toSafeInteger(Number.MAX_SAFE_INTEGER + 1);
+ * // => 9007199254740991
+ * ```
+ *
+ * @since 1.0.0
+ * @category Convert
+ */
+export default function toSafeInteger(value: unknown): number;