jinbi-utils 1.0.26 → 1.0.28

package/types/money/helpers.d.ts

@@ -0,0 +1,134 @@
+import { Money } from "./index";
+/**
+ * 快捷创建 Money 实例的工厂函数
+ * @param amount - 金额
+ * @returns Money 实例
+ *
+ * @example
+ * ```ts
+ * const price = money('19.99');
+ * const total = money(100);
+ * ```
+ */
+export declare function money(amount: string | number): Money;
+/**
+ * 求和多个金额
+ * @param amounts - 金额数组
+ * @returns Money - 总和
+ *
+ * @example
+ * ```ts
+ * const total = sum([
+ *   new Money('10.5'),
+ *   new Money('20.3'),
+ *   new Money('30.2')
+ * ]); // 61.00
+ * ```
+ */
+export declare function sum(amounts: Money[]): Money;
+/**
+ * 获取多个金额中的最大值
+ * @param amounts - 金额数组
+ * @returns Money - 最大值
+ *
+ * @example
+ * ```ts
+ * const maxAmount = max([
+ *   new Money('10.5'),
+ *   new Money('20.3'),
+ *   new Money('30.2')
+ * ]); // 30.2
+ * ```
+ */
+export declare function max(amounts: Money[]): Money;
+/**
+ * 获取多个金额中的最小值
+ * @param amounts - 金额数组
+ * @returns Money - 最小值
+ *
+ * @example
+ * ```ts
+ * const minAmount = min([
+ *   new Money('10.5'),
+ *   new Money('20.3'),
+ *   new Money('30.2')
+ * ]); // 10.5
+ * ```
+ */
+export declare function min(amounts: Money[]): Money;
+/**
+ * 计算平均值
+ * @param amounts - 金额数组
+ * @param decimalPlaces - 结果保留的小数位数，默认 2
+ * @returns Money - 平均值
+ *
+ * @example
+ * ```ts
+ * const avgAmount = average([
+ *   new Money('10.5'),
+ *   new Money('20.3'),
+ *   new Money('30.2')
+ * ]); // 20.33
+ * ```
+ */
+export declare function average(amounts: Money[], decimalPlaces?: number): Money;
+/**
+ * 判断金额是否在指定范围内（包含边界）
+ * @param amount - 要判断的金额
+ * @param minAmount - 最小值
+ * @param maxAmount - 最大值
+ * @returns boolean
+ *
+ * @example
+ * ```ts
+ * const price = new Money('50');
+ * isInRange(price, new Money('10'), new Money('100')); // true
+ * isInRange(price, new Money('60'), new Money('100')); // false
+ * ```
+ */
+export declare function isInRange(amount: Money, minAmount: Money, maxAmount: Money): boolean;
+/**
+ * 将金额限制在指定范围内
+ * @param amount - 要限制的金额
+ * @param minAmount - 最小值
+ * @param maxAmount - 最大值
+ * @returns Money - 限制后的金额
+ *
+ * @example
+ * ```ts
+ * clamp(new Money('150'), new Money('0'), new Money('100')); // 100
+ * clamp(new Money('-10'), new Money('0'), new Money('100')); // 0
+ * clamp(new Money('50'), new Money('0'), new Money('100')); // 50
+ * ```
+ */
+export declare function clamp(amount: Money, minAmount: Money, maxAmount: Money): Money;
+/**
+ * 按权重分配金额（加权分配）
+ * @param amount - 总金额
+ * @param weights - 权重数组
+ * @returns Money[] - 分配后的金额数组
+ *
+ * @example
+ * ```ts
+ * // 100 元按权重 [3, 2, 1] 分配
+ * const shares = distributeByWeight(new Money('100'), [3, 2, 1]);
+ * // shares: [50.00, 33.33, 16.67]
+ * ```
+ */
+export declare function distributeByWeight(amount: Money, weights: number[]): Money[];
+/**
+ * 计算多个金额的加权平均值
+ * @param amounts - 金额数组
+ * @param weights - 权重数组
+ * @param decimalPlaces - 结果保留的小数位数，默认 2
+ * @returns Money - 加权平均值
+ *
+ * @example
+ * ```ts
+ * const avg = weightedAverage(
+ *   [new Money('100'), new Money('200'), new Money('300')],
+ *   [1, 2, 3]
+ * ); // 233.33
+ * ```
+ */
+export declare function weightedAverage(amounts: Money[], weights: number[], decimalPlaces?: number): Money;

package/types/money/helpers.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/money/index.d.ts

@@ -0,0 +1,260 @@
+import Decimal from "decimal.js";
+import type { MoneyInput, MoneyFormatOptions } from "./types";
+/**
+ * 可比较的金额类型
+ */
+export declare type ComparableAmount = string | number | Money;
+/**
+ * 金额计算工具类
+ * 基于 decimal.js 实现精确的货币计算，避免 JavaScript 浮点数精度问题
+ *
+ * @example
+ * ```ts
+ * const price = new Money('19.99');
+ * const total = price.multiply(3); // 59.97
+ * const tax = total.multiply('0.13'); // 7.7961
+ * const finalPrice = total.add(tax).round(2); // 67.77
+ * console.log(finalPrice.format()); // "¥67.77"
+ * ```
+ */
+export declare class Money {
+    private readonly value;
+    /**
+     * 创建 Money 实例
+     * @param amount - 金额，支持 string | number | Decimal
+     */
+    constructor(amount: MoneyInput);
+    /**
+     * 加法运算
+     * @param amount - 要相加的金额
+     * @returns 新的 Money 实例
+     */
+    add(amount: ComparableAmount): Money;
+    /**
+     * 减法运算
+     * @param amount - 要相减的金额
+     * @returns 新的 Money 实例
+     */
+    subtract(amount: ComparableAmount): Money;
+    /**
+     * 乘法运算
+     * @param multiplier - 乘数
+     * @returns 新的 Money 实例
+     */
+    multiply(multiplier: MoneyInput): Money;
+    /**
+     * 除法运算
+     * @param divisor - 除数
+     * @returns 新的 Money 实例
+     */
+    divide(divisor: MoneyInput): Money;
+    /**
+     * 求余运算
+     * @param divisor - 除数
+     * @returns 新的 Money 实例
+     */
+    mod(divisor: MoneyInput): Money;
+    /**
+     * 绝对值
+     * @returns 新的 Money 实例
+     */
+    abs(): Money;
+    /**
+     * 取反
+     * @returns 新的 Money 实例
+     */
+    negate(): Money;
+    /**
+     * 四舍五入到指定小数位
+     * @param decimalPlaces - 小数位数，默认 2
+     * @param roundingMode - 舍入模式，默认 ROUND_HALF_UP（四舍五入）
+     * @returns 新的 Money 实例
+     *
+     * @example
+     * ```ts
+     * new Money('1.125').round(2); // 1.13 (四舍五入)
+     * new Money('1.124').round(2); // 1.12
+     * new Money('1.125').round(2, Decimal.ROUND_DOWN); // 1.12 (向下舍入)
+     * ```
+     */
+    round(decimalPlaces?: number, roundingMode?: Decimal.Rounding): Money;
+    /**
+     * 向上取整到指定小数位
+     * @param decimalPlaces - 小数位数，默认 2
+     * @returns 新的 Money 实例
+     *
+     * @example
+     * ```ts
+     * new Money('1.121').ceil(2); // 1.13
+     * new Money('1.129').ceil(2); // 1.13
+     * ```
+     */
+    ceil(decimalPlaces?: number): Money;
+    /**
+     * 向下取整到指定小数位
+     * @param decimalPlaces - 小数位数，默认 2
+     * @returns 新的 Money 实例
+     *
+     * @example
+     * ```ts
+     * new Money('1.128').floor(2); // 1.12
+     * new Money('1.121').floor(2); // 1.12
+     * ```
+     */
+    floor(decimalPlaces?: number): Money;
+    /**
+     * 截断到指定小数位（直接切割，不进行舍入）
+     * @param decimalPlaces - 小数位数，默认 2
+     * @returns 新的 Money 实例
+     *
+     * @example
+     * ```ts
+     * new Money('1.12999').truncate(2); // 1.12
+     * new Money('1.12111').truncate(2); // 1.12
+     * new Money('1.19999').truncate(2); // 1.19
+     * ```
+     */
+    truncate(decimalPlaces?: number): Money;
+    /**
+     * 比较：是否大于
+     * @param amount - 要比较的金额
+     * @returns boolean
+     */
+    isGreaterThan(amount: ComparableAmount): boolean;
+    /**
+     * 比较：是否大于等于
+     * @param amount - 要比较的金额
+     * @returns boolean
+     */
+    isGreaterThanOrEqualTo(amount: ComparableAmount): boolean;
+    /**
+     * 比较：是否小于
+     * @param amount - 要比较的金额
+     * @returns boolean
+     */
+    isLessThan(amount: ComparableAmount): boolean;
+    /**
+     * 比较：是否小于等于
+     * @param amount - 要比较的金额
+     * @returns boolean
+     */
+    isLessThanOrEqualTo(amount: ComparableAmount): boolean;
+    /**
+     * 比较：是否相等
+     * @param amount - 要比较的金额
+     * @returns boolean
+     */
+    equals(amount: ComparableAmount): boolean;
+    /**
+     * 是否为零
+     * @returns boolean
+     */
+    isZero(): boolean;
+    /**
+     * 是否为正数
+     * @returns boolean
+     */
+    isPositive(): boolean;
+    /**
+     * 是否为负数
+     * @returns boolean
+     */
+    isNegative(): boolean;
+    /**
+     * 转换为字符串（完整精度）
+     * @returns string
+     */
+    toString(): string;
+    /**
+     * 转换为指定精度的字符串（使用精确切割，不是 toFixed）
+     * @param decimalPlaces - 小数位数，默认 2
+     * @param roundingMode - 舍入模式，默认 ROUND_HALF_UP
+     * @returns string
+     *
+     * @example
+     * ```ts
+     * new Money('1.12999').toFixedString(2); // "1.13"
+     * new Money('1.12999').toFixedString(4); // "1.1300"
+     * ```
+     */
+    toFixedString(decimalPlaces?: number, roundingMode?: Decimal.Rounding): string;
+    /**
+     * 转换为数字（警告：可能丢失精度，仅用于显示）
+     * @returns number
+     */
+    toNumber(): number;
+    /**
+     * 转换为 Decimal 对象
+     * @returns Decimal
+     */
+    toDecimal(): Decimal;
+    /**
+     * 格式化为货币字符串
+     * @param options - 格式化选项
+     * @returns string
+     *
+     * @example
+     * ```ts
+     * new Money('1234.56').format(); // "¥1,234.56"
+     * new Money('1234.56').format({ symbol: '$' }); // "$1,234.56"
+     * new Money('1234.56').format({ symbol: '￥', decimalPlaces: 0 }); // "￥1,235"
+     * new Money('1234.56').format({ thousandsSeparator: '' }); // "¥1234.56"
+     * ```
+     */
+    format(options?: MoneyFormatOptions): string;
+    /**
+     * 按比例分配金额（解决分账/分摊场景的精度问题）
+     * @param ratios - 分配比例数组
+     * @returns Money[] - 分配后的金额数组
+     *
+     * @example
+     * ```ts
+     * // 100 元按 1:2:3 比例分配
+     * const [a, b, c] = new Money('100').allocate([1, 2, 3]);
+     * // a: 16.67, b: 33.33, c: 50.00 (总和仍为 100.00)
+     *
+     * // 订单 99.99 元，3人平摊
+     * const shares = new Money('99.99').allocate([1, 1, 1]);
+     * // shares: [33.33, 33.33, 33.33] (总和 99.99)
+     * ```
+     */
+    allocate(ratios: number[]): Money[];
+    /**
+     * 计算百分比
+     * @param percentage - 百分比值（如：15 表示 15%）
+     * @param decimalPlaces - 结果保留的小数位数，默认 2
+     * @returns Money - 计算结果
+     *
+     * @example
+     * ```ts
+     * new Money('100').percentage(15); // 15.00 (100 的 15%)
+     * new Money('99.99').percentage(8.5); // 8.50 (99.99 的 8.5%)
+     * ```
+     */
+    percentage(percentage: MoneyInput, decimalPlaces?: number): Money;
+    /**
+     * 计算折扣后的价格
+     * @param discount - 折扣率（如：0.8 表示 8折，20 表示 8折）
+     * @param isPercentage - discount 是否为百分比形式，默认 false
+     * @param decimalPlaces - 结果保留的小数位数，默认 2
+     * @returns Money - 折扣后的价格
+     *
+     * @example
+     * ```ts
+     * // 方式1：直接传折扣率
+     * new Money('100').applyDiscount(0.8); // 80.00 (8折后)
+     *
+     * // 方式2：传百分比
+     * new Money('100').applyDiscount(20, true); // 80.00 (打8折，折扣20%)
+     * ```
+     */
+    applyDiscount(discount: MoneyInput, isPercentage?: boolean, decimalPlaces?: number): Money;
+    /**
+     * 内部辅助方法：将 ComparableAmount 转换为 Decimal
+     * @private
+     */
+    private toDecimalValue;
+}
+export type { MoneyInput, MoneyFormatOptions } from "./types";
+export { RoundingMode } from "./constants";
+export { Decimal };

package/types/money/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/money/types.d.ts

@@ -0,0 +1,22 @@
+import type Decimal from "decimal.js";
+/**
+ * 金额格式化选项
+ */
+export interface MoneyFormatOptions {
+    /** 货币符号，默认 "¥" */
+    symbol?: string;
+    /** 小数位数，默认 2 */
+    decimalPlaces?: number;
+    /** 千分位分隔符，默认 "," */
+    thousandsSeparator?: string;
+    /** 小数点分隔符，默认 "." */
+    decimalSeparator?: string;
+    /** 符号位置，默认 "prefix" */
+    symbolPosition?: "prefix" | "suffix";
+    /** 舍入模式，默认 ROUND_HALF_UP */
+    roundingMode?: Decimal.Rounding;
+}
+/**
+ * Money 类接受的输入类型
+ */
+export declare type MoneyInput = string | number | Decimal;

package/types/sm3.d.ts

@@ -0,0 +1,30 @@
+/**
+ * SM3 国密哈希算法工具
+ * @description 使用 sm-crypto 库对敏感数据（如密码）进行 SM3 加密
+ *
+ * SM3 是中国国家密码管理局发布的密码杂凑算法标准
+ * 输出 256 位（32 字节）的哈希值
+ */
+/**
+ * SM3 哈希计算
+ * @param message 待哈希的字符串
+ * @returns 64 位十六进制字符串
+ *
+ * @example
+ * ```ts
+ * const hash = sm3('hello world');
+ * ```
+ */
+export declare function sm3(message: string): string;
+/**
+ * 对密码进行 SM3 加密
+ * @param password 原始密码
+ * @returns SM3 加密后的密码（64 位十六进制字符串）
+ *
+ * @example
+ * ```ts
+ * const encryptedPassword = encryptPassword('admin123');
+ * ```
+ */
+export declare function encryptPassword(password: string): string;
+export default sm3;

package/types/tree/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @description 树节点类型定义
+ */
+export declare type TreeNode = {
+    id?: number | string;
+    parentId?: number | string | null;
+    pathList?: Array<number | string>;
+    uniqueId?: number | string;
+    children?: TreeNode[];
+    [key: string]: unknown;
+};
+/**
+ * @description 提取菜单树中的每一项uniqueId
+ * @param tree 树
+ * @returns 每一项uniqueId组成的数组
+ */
+export declare const extractPathList: (tree: TreeNode[]) => Array<number | string>;
+/**
+ * @description 如果父级下children的length为1，删除children并自动组建唯一uniqueId
+ * @param tree 树
+ * @param pathList 每一项的id组成的数组
+ * @returns 组件唯一uniqueId后的树
+ */
+export declare const deleteChildren: (tree: TreeNode[], pathList?: Array<number | string>) => TreeNode[];
+/**
+ * @description 创建层级关系
+ * @param tree 树
+ * @param pathList 每一项的id组成的数组
+ * @returns 创建层级关系后的树
+ */
+export declare const buildHierarchyTree: (tree: TreeNode[], pathList?: Array<number | string>) => TreeNode[];
+/**
+ * @description 广度优先遍历，根据唯一uniqueId找当前节点信息
+ * @param tree 树
+ * @param uniqueId 唯一uniqueId
+ * @returns 当前节点信息
+ */
+export declare const getNodeByUniqueId: (tree: TreeNode[], uniqueId: number | string) => TreeNode | undefined;
+/**
+ * @description 向当前唯一uniqueId节点中追加字段
+ * @param tree 树
+ * @param uniqueId 唯一uniqueId
+ * @param fields 需要追加的字段
+ * @returns 追加字段后的树
+ */
+export declare const appendFieldByUniqueId: (tree: TreeNode[], uniqueId: number | string, fields: Record<string, unknown>) => TreeNode[];
+/**
+ * @description 构造树型结构数据
+ * @param data 数据源
+ * @param id id字段 默认id
+ * @param parentId 父节点字段，默认parentId
+ * @param children 子节点字段，默认children
+ * @returns 追加字段后的树
+ */
+export declare const handleTree: (data: TreeNode[], id?: string | undefined, parentId?: string | undefined, children?: string | undefined) => TreeNode[];

package/types/uploadSpeed.d.ts

@@ -0,0 +1,85 @@
+/**
+ * 上传速度计算和时间预估工具
+ * 使用滑动窗口算法计算实时上传速度
+ */
+export declare class UploadSpeedCalculator {
+    private speedPoints;
+    private readonly windowSize;
+    private readonly minPoints;
+    private startTime;
+    private totalBytes;
+    /**
+     * @param windowSize 滑动窗口大小（秒），默认 10 秒
+     * @param minPoints 最少记录点数，默认 3 个
+     */
+    constructor(windowSize?: number, minPoints?: number);
+    /**
+     * 开始计算
+     * @param totalBytes 总字节数
+     */
+    start(totalBytes: number): void;
+    /**
+     * 添加速度记录点
+     * @param uploadedBytes 已上传字节数
+     */
+    addPoint(uploadedBytes: number): void;
+    /**
+     * 计算当前上传速度（字节/秒）
+     */
+    getCurrentSpeed(): number;
+    /**
+     * 计算平均上传速度（字节/秒）
+     */
+    getAverageSpeed(): number;
+    /**
+     * 计算剩余时间（秒）
+     * @param uploadedBytes 已上传字节数
+     * @returns 剩余秒数，-1 表示无法计算
+     */
+    getRemainingTime(uploadedBytes: number): number;
+    /**
+     * 格式化速度（自动选择单位）
+     * @param bytesPerSecond 速度（字节/秒）
+     */
+    static formatSpeed(bytesPerSecond: number): string;
+    /**
+     * 格式化剩余时间（友好显示）
+     * @param seconds 剩余秒数
+     */
+    static formatRemainingTime(seconds: number): string;
+    /**
+     * 获取上传进度百分比
+     * @param uploadedBytes 已上传字节数
+     */
+    getProgress(uploadedBytes: number): number;
+    /**
+     * 重置计算器
+     */
+    reset(): void;
+}
+/**
+ * 全局速度计算器管理器
+ * 为每个文件维护独立的速度计算器
+ */
+export declare class SpeedCalculatorManager {
+    private calculators;
+    /**
+     * 获取或创建文件的速度计算器
+     * @param fileId 文件 ID
+     */
+    getCalculator(fileId: string): UploadSpeedCalculator;
+    /**
+     * 移除文件的速度计算器
+     * @param fileId 文件 ID
+     */
+    removeCalculator(fileId: string): void;
+    /**
+     * 清空所有计算器
+     */
+    clear(): void;
+    /**
+     * 获取所有文件的总速度
+     */
+    getTotalSpeed(): number;
+}
+export declare const speedCalculatorManager: SpeedCalculatorManager;

package/types/uploadValidation.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 文件上传前验证工具
+ * 包含文件大小、类型、配额、网络等验证
+ */
+export interface ValidationResult {
+    valid: boolean;
+    error?: string;
+    code?: string;
+}
+export interface ValidationConfig {
+    maxFileSize?: number;
+    maxTotalSize?: number;
+    allowedTypes?: string[];
+    maxFilesCount?: number;
+    checkNetwork?: boolean;
+    checkQuota?: boolean;
+}
+/**
+ * 文件大小验证器
+ */
+export declare function validateFileSize(file: File, maxSize?: number): ValidationResult;
+/**
+ * 总文件大小验证器
+ */
+export declare function validateTotalSize(files: File[], maxTotalSize?: number): ValidationResult;
+/**
+ * 文件类型验证器
+ */
+export declare function validateFileType(file: File, allowedTypes?: string[]): ValidationResult;
+/**
+ * 文件数量验证器
+ */
+export declare function validateFilesCount(currentCount: number, newFilesCount: number, maxCount?: number): ValidationResult;
+/**
+ * 网络状态检测器
+ */
+export declare function checkNetworkStatus(): ValidationResult;
+/**
+ * 配额检查器（模拟，实际需要调用后端 API）
+ */
+export declare function checkStorageQuota(filesTotalSize: number): Promise<ValidationResult>;
+/**
+ * 综合验证器 - 执行所有验证
+ */
+export declare function validateFilesBeforeUpload(files: File[], currentFiles?: File[], config?: ValidationConfig): Promise<ValidationResult[]>;
+/**
+ * 格式化文件大小
+ */
+export declare function formatFileSize(bytes: number): string;
+/**
+ * 获取友好的错误提示
+ */
+export declare function getValidationErrorMessage(results: ValidationResult[]): string;