@resolid/utils/dist/index.d.mts

Common utils

import { DateInput } from "@formkit/tempo";

//#region src/array/index.d.ts
/**
* 将任意值转换为数组形式
*
* - 如果传入的值本身就是数组，则原样返回。
* - 如果传入的是单个值，则包装成单元素数组返回。
*
* @param input - 单个值或数组
* @returns 始终返回一个数组
*/
declare function asArray<T>(input: T | T[]): T[];
/**
* 将数组按指定大小分块
*
* @template T 数组元素类型
* @param arr 要分块的数组
* @param size 每块的最大长度
* @returns 分块后的二维数组
*/
declare function chunk<T>(arr: readonly T[], size: number): T[][];
/**
* 在指定位置插入一个元素，返回一个新的数组（不会修改原数组）
*
* @param input - 原始数组
* @param index - 要插入的位置索引（从 0 开始）
* @param item - 要插入的元素
* @returns 一个包含新元素的新数组
*
*/
declare function insert<T>(input: T[], index: number, item: T): T[];
/**
* 从数组中移除指定的元素
*
* @template T - 数组元素的类型
* @param {T[]} input - 要操作的数组
* @param {T} item - 需要移除的元素
* @returns {boolean} - 如果数组中存在该元素并成功移除返回 true，否则返回 false
*/
declare function remove<T>(input: T[], item: T): boolean;
/**
* 将一个数组按条件函数（predicate）分成两组
*
* @param input - 要处理的数组（只读，不会被修改）
* @param predicate - 判断函数，返回 true 的元素会放入第一组，否则放入第二组
* @returns [符合条件的数组, 不符合条件的数组]
*/
declare function partition<T>(input: T[], predicate: (element: T) => boolean): [Array<T>, Array<T>];
//#endregion
//#region src/date/index.d.ts
/**
* 将一个日期限制在指定范围内。
*
* @param date 要限制的日期
* @param min 最小值（可选）
* @param max 最大值（可选）
* @returns 被 clamp 后的日期（新对象）
*/
declare function clampDate(date: DateInput, min?: DateInput | null, max?: DateInput | null): DateInput;
type DateRange = {
  start?: DateInput | null;
  end?: DateInput | null;
};
/**
* 判断指定日期是否在日期区间
*
* @param date 指定日期
* @param range 日期区间
* @param range.start 开始
* @param range.end 结束
* @returns 是否在区间
*/
declare function isDateInRange(date: DateInput, range: DateRange): boolean;
/**
* 日期列表排序
*
* @param dates 日期列表
* @param order 排序方向，'asc' 升序（默认），'desc' 降序
* @returns 排序后的日期
*/
declare function sortDates(dates: (DateInput | null | undefined)[], order?: "asc" | "desc"): DateInput[];
/**
* 调整日期区间的开始和结束日期
* 若 start 晚于 end，则自动交换，确保 start <= end
*
* @param range 日期区间
* @param range.start 开始
* @param range.end 结束
* @returns 调整后的日期区间
*/
declare function adjustDateRange(range: DateRange): DateRange;
type GetDatesInRangeOptions = {
  /**
  * 时间单位
  * @default "day"
  */
  unit?: "day" | "month" | "year";
  /**
  * 偏移步长
  * @default 1
  */
  step?: number;
};
/**
* 枚举两个日期之间的所有日期
*
* @param start 起始日期
* @param end 结束日期
* @param options 选项
* @param options.unit - 单位: `"day"` | `"month"` | `"year"`. 默认 `"day"`
* @param options.step - 步长: 必须大于 0. 默认 `1`
*
* @returns 介于 start 和 end 之间的日期数组
*/
declare function getDatesInRange(start: DateInput, end: DateInput, options?: GetDatesInRangeOptions): DateInput[];
//#endregion
//#region src/file/index.d.ts
declare const UNITS: readonly ["Bytes", "KB", "MB", "GB", "TB"];
type Unit = (typeof UNITS)[number];
/**
* 将字节数格式化为带单位的可读字符串
*
* @param bytes - 字节数
* @param precision - 小数点后的精度位数，默认值为 2
* @param unit - 可选的强制单位, 默认进行自动单位计算
*
* @returns 格式化后的字符串
*/
declare function formatBytes(bytes: number, precision?: number, unit?: Unit | null): string;
/**
* 检查文件是否匹配 accept 规则
*
* @param fileName - 文件名
* @param mimeType - 文件的 MIME 类型
* @param accept - 接受的文件类型规则
*
* @returns 如果文件匹配任一规则则返回 true,否则返回 false
*/
declare function matchesAccept(fileName: string, mimeType: string, accept: string): boolean;
//#endregion
//#region src/types/index.d.ts
type Booleanish = boolean | "true" | "false";
type Simplify<T> = { [K in keyof T]: T[K] } & {};
type ValueOrFunction<T, A extends unknown[] = []> = T | ((...args: A) => T);
//#endregion
//#region src/function/index.d.ts
/**
* 空函数（no operation）。
*
* 什么也不做，通常用于占位、默认回调或避免 undefined 调用。
*/
declare function noop(): void;
/**
* 异步等待指定毫秒数。
*
* @param ms - 要等待的毫秒数
* @returns 一个在指定时间后 resolve 的 Promise
*/
declare function sleep(ms: number): Promise<void>;
/**
* 创建一个始终返回固定值的函数。
*
* @param value - 要固定返回的值
* @returns 一个无参数函数，每次调用都会返回该值
*/
declare function always<T>(value: T): () => T;
/**
* 将一个 Promise 转换为 [error, data] 的形式，便于 async/await 异常处理。
*
* 作用类似 try/catch，但可以用解构直接获取结果和错误：
*
* @param promise - 要处理的 Promise 对象
* @returns 一个 Promise，resolve 为一个长度为 2 的元组：
*          - 成功时：[null, data]
*          - 失败时：[error, undefined]
*/
declare function to<T, E = Error>(promise: Promise<T>): Promise<[E, undefined] | [null, T]>;
/**
* 如果传入的是函数，则执行它并返回结果；否则直接返回该值。
*
* 常用于允许参数既可以是静态值，也可以是动态函数的场景。
*
* @template T - 返回值类型
* @template A - 函数参数类型
* @param value - 值或函数
* @param args - 如果 value 是函数，传递给它的参数
* @returns 如果 value 是函数，则返回函数执行结果，否则直接返回 value
*/
declare function runIf<T, A extends unknown[]>(value: ValueOrFunction<T, A>, ...args: A): T;
/**
* 将多个函数组合成一个函数，同时调用所有非空函数。
*
* 常用于事件处理器、回调组合，避免手动逐个调用。
*
* @template T - 函数类型
* @param fns - 要组合的函数数组，允许 null 或 undefined
* @returns 一个新函数，调用时会依次调用 fns 中所有非空函数
*/
declare function callAll<T extends (...args: any[]) => void>(...fns: (T | null | undefined)[]): (...args: Parameters<T>) => void;
//#endregion
//#region src/is/index.d.ts
declare const __DEV__: boolean;
declare const isBrowser: boolean;
type Truthy<T> = T extends false | "" | 0 | null | undefined ? never : T;
/**
* 判断一个值是否为“真值”（truthy）。
*
* 在 JavaScript 中，以下值会被认为是“假值”（falsy）：
* - false
* - 0
* - -0
* - 0n
* - ""
* - null
* - undefined
* - NaN
*
* 除此之外的值都被认为是“真值”（truthy）。
*
* @param value - 要判断的值
* @returns 如果值为真值则返回 true，否则返回 false
*/
declare function isTruthy<T>(value: T): value is Truthy<T>;
/**
* 判断一个值是否为 `undefined`。
*
* @param value - 要判断的值
* @returns 如果值为 `undefined`，返回 true，否则返回 false
*/
declare function isUndefined(value: unknown): value is undefined;
/**
* 判断一个值是否已定义（即不为 `undefined` 或 `null`）。
*
* @param value - 要判断的值
* @returns 如果值既不是 `undefined` 也不是 `null`，则返回 true
*/
declare function isDefined<T>(value: T): value is NonNullable<T>;
/**
* 判断一个值是否为布尔类型（boolean）。
*
* @param value - 要判断的值
* @returns 如果值是布尔类型，返回 true，否则返回 false
*/
declare function isBoolean(value: unknown): value is boolean;
/**
* 判断一个值是否为数字类型（number）。
*
* @param value - 要判断的值
* @returns 如果值是数字则返回 true，否则返回 false
*/
declare function isNumber(value: unknown): value is number;
/**
* 判断一个值是否为字符串类型。
*
* @param value - 要判断的值
* @returns 如果值是字符串则返回 true，否则返回 false
*/
declare function isString(value: unknown): value is string;
/**
* 判断一个值是否为对象类型（排除 null）。
*
* @param value - 要判断的值
* @returns 如果值是对象（且不为 null）则返回 true，否则返回 false
*/
declare function isObject(value: unknown): value is Record<string, unknown>;
/**
* 判断一个值是否为 `undefined` 或 `null`（即“nullish”）。
*
* @param value - 要判断的值
* @returns 如果值是 `undefined` 或 `null`，则返回 true，否则返回 false
*/
declare function isNullish(value: unknown): value is null | undefined;
/**
* 判断一个值是否为函数类型。
*
* @param value - 要判断的值
* @returns 如果值是函数则返回 true，否则返回 false
*/
declare function isFunction(value: unknown): value is Function;
/**
* 判断一个值是否为 Date 对象。
*
* @param value - 要判断的值
* @returns 如果值是 Date 对象则返回 true，否则返回 false
*/
declare function isDate(value: unknown): value is Date;
/**
* 判断一个值是否为 BigInt 对象。
*
* @param value - 要判断的值
* @returns 如果值是 BigInt 对象则返回 true，否则返回 false
*/
declare function isBigInt(value: unknown): value is bigint;
/**
* 判断一个值是否“为空”。
*
* 规则：
* - null 或 undefined → 为空
* - 数字 0 → 为空
* - 字符串只包含空白字符 → 为空
* - 空数组 → 为空
* - 空对象 → 为空
* - 其他类型 → 不为空
*
* @param value - 要判断的值
* @returns 如果值为空则返回 true，否则返回 false
*/
declare function isEmpty(value: unknown): boolean;
/**
* 判断一个值是否为 Promise 对象。
*
* @param value - 要判断的值
* @returns 如果值是 Promise 对象则返回 true，否则返回 false
*/
declare function isPromise(value: unknown): value is Promise<unknown>;
//#endregion
//#region src/number/index.d.ts
/**
* 将一个数值限制在指定范围内（支持 number 与 bigint）。
*
* @param value 要限制的数值
* @param min 最小值（可选）
* @param max 最大值（可选）
* @returns 如果 value 小于 min，则返回 min；如果大于 max，则返回 max；否则返回 value 本身
*/
declare function clamp<T extends number | bigint>(value: T, min?: T | null, max?: T | null): T;
/**
* 生成一个从 start 到 end（包含 end）的整数数组。
*
* @param start - 起始值（包含）
* @param end - 结束值（包含）
* @returns 包含从 start 到 end 的整数数组，如果 start > end，则返回空数组
*/
declare function range(start: number, end: number): number[];
//#endregion
//#region src/object/index.d.ts
/**
* 创建一个新对象，排除指定的键。
*
* @template T - 原始对象类型
* @template K - 要排除的键的联合类型
* @param object - 原始对象
* @param keys - 要排除的键数组
* @returns 一个新对象，包含原对象的所有属性，除了 keys 中指定的属性
*/
declare function omit<T extends object, K extends keyof T>(object: T, keys: readonly K[]): Omit<T, K>;
/**
* 根据回调函数过滤对象属性，返回一个新对象，只保留回调返回 false 的属性。
*
* @template T - 原始对象类型
* @param object - 要处理的对象
* @param should - 回调函数，接收 value 和 key：
*                     - 返回 true → 忽略该属性
*                     - 返回 false → 保留该属性
* @returns 一个新对象，包含原对象中未被 omit 的属性
*/
declare function omitBy<T extends object>(object: T, should: (value: T[keyof T], key: keyof T) => boolean): Partial<T>;
/**
* 从对象中挑选指定的键，返回一个新对象。
*
* @template T - 原始对象类型
* @template K - 要挑选的键的联合类型
* @param object - 原始对象
* @param keys - 要挑选的键数组
* @returns 一个新对象，只包含 keys 中指定的属性
*/
declare function pick<T extends object, K extends keyof T>(object: T, keys: readonly K[]): Pick<T, K>;
/**
* 根据回调函数过滤对象属性，返回一个新对象，只保留回调返回 true 的属性。
*
* @template T - 原始对象类型
* @param object - 要处理的对象
* @param should - 回调函数，接收 value 和 key：
*                     - 返回 true → 保留该属性
*                     - 返回 false → 忽略该属性
* @returns 一个新对象，包含原对象中被 pick 的属性
*/
declare function pickBy<T extends object>(object: T, should: (value: T[keyof T], key: keyof T) => boolean): Partial<T>;
/**
* 根据给定的路径字符串，安全地获取对象中的深层属性值。
*
* @template T 默认值类型
* @param value 要读取的目标对象
* @param path 属性访问路径
* @param defaultValue 当路径不存在或解析失败时返回的默认值
* @returns 解析得到的属性值或默认值
*/
declare function get<T = unknown>(value: any, path: string, defaultValue?: T): T;
//#endregion
//#region src/string/index.d.ts
/**
* 将字符串的首字母转换为大写，其余保持不变。
*
* @param str - 要处理的字符串
* @returns 首字母大写后的字符串，如果传入空字符串或 falsy 值，返回空字符串
*/
declare function capitalize(str: string): string;
/**
* 将字符串转换为驼峰命名(camelCase)格式
*
* @param str - 需要转换的字符串
* @returns 驼峰命名格式的字符串
*/
declare function camelCase(str: string): string;
/**
* 将字符串转换为帕斯卡命名(PascalCase)格式
*
* @param str - 需要转换的字符串
* @returns 帕斯卡命名格式的字符串
*/
declare function pascalCase(str: string): string;
/**
* 将字符串转换为短横线(kebab-case)格式
*
* @param str - 需要转换的字符串
* @returns 短横线格式的字符串
*/
declare function kebabCase(str: string): string;
/**
* 将字符串转换为蛇形命名(snake_case)格式
*
* @param str - 需要转换的字符串
* @returns 蛇形命名格式的字符串
*/
declare function snakeCase(str: string): string;
/**
* 判断字符串是否以指定前缀开头，可选择忽略大小写。
*
* @param text - 要检查的字符串
* @param prefix - 前缀字符串
* @param ignoreCase - 是否忽略大小写，默认 true
* @returns 如果 text 以 prefix 开头，则返回 true，否则返回 false
*/
declare function startsWith(text: string, prefix: string, ignoreCase?: boolean): boolean;
/**
* 判断字符串是否以指定后缀结尾，可选择忽略大小写。
*
* @param text - 要检查的字符串
* @param suffix - 后缀字符串
* @param ignoreCase - 是否忽略大小写，默认 true
* @returns 如果 text 以 suffix 结尾，则返回 true，否则返回 false
*/
declare function endsWith(text: string, suffix: string, ignoreCase?: boolean): boolean;
/**
* 如果字符串以指定前缀开头，则去掉该前缀。
*
* @param text - 要处理的字符串
* @param prefix - 要移除的前缀
* @param ignoreCase - 是否忽略大小写，默认 true
* @returns 去掉前缀后的字符串，如果 text 不以 prefix 开头，则返回原字符串
*/
declare function trimStart(text: string, prefix: string, ignoreCase?: boolean): string;
/**
* 如果字符串以指定后缀结尾，则去掉该后缀。
*
* @param text - 要处理的字符串
* @param suffix - 要移除的后缀
* @param ignoreCase - 是否忽略大小写，默认 true
* @returns 去掉后缀后的字符串，如果 text 不以 suffix 结尾，则返回原字符串
*/
declare function trimEnd(text: string, suffix: string, ignoreCase?: boolean): string;
/**
* 生成指定长度的随机字符串
* 使用数字、大小写字母作为字符集
*
* @param size - 生成字符串的长度，默认为 16
* @returns 随机生成的字符串
*/
declare function random(size?: number): string;
//#endregion
//#region src/throttle/index.d.ts
type ThrottleOptions = {
  start?: boolean;
  middle?: boolean;
  once?: boolean;
};
type Throttler<T extends unknown[]> = {
  (...args: T): void;
  cancel: () => void;
};
/**
* 创建一个节流函数，限制回调在指定时间间隔内执行次数。
*
* @template T - 回调函数参数类型
* @param callback - 要节流执行的函数
* @param wait - 节流时间间隔（毫秒），默认 0
* @param options - 配置选项
*                  - start: 是否立即执行第一次，默认 true
*                  - middle: 是否在间隔时间内允许再次执行，默认 true
*                  - once: 是否执行一次后自动取消，默认 false
* @returns 一个节流后的函数，并附带 cancel 方法可取消
*/
declare function throttle<T extends unknown[]>(callback: (...args: T) => unknown, wait?: number, {
  start,
  middle,
  once
}?: ThrottleOptions): Throttler<T>;
/**
* 创建一个防抖函数，在连续调用时只在停止调用后执行回调。
*
* @template T - 回调函数参数类型
* @param callback - 要防抖执行的函数
* @param wait - 防抖时间间隔（毫秒），默认 0
* @param options - 配置选项（同 throttle）
*                  - start: 是否立即执行第一次，默认 false
*                  - middle: 是否允许间隔内触发，默认 false
*                  - once: 是否执行一次后自动取消，默认 false
* @returns 一个防抖后的函数，并附带 cancel 方法可取消
*/
declare function debounce<T extends unknown[]>(callback: (...args: T) => unknown, wait?: number, {
  start,
  middle,
  once
}?: ThrottleOptions): Throttler<T>;
//#endregion
export { Booleanish, DateRange, Simplify, ThrottleOptions, Throttler, ValueOrFunction, __DEV__, adjustDateRange, always, asArray, callAll, camelCase, capitalize, chunk, clamp, clampDate, debounce, endsWith, formatBytes, get, getDatesInRange, insert, isBigInt, isBoolean, isBrowser, isDate, isDateInRange, isDefined, isEmpty, isFunction, isNullish, isNumber, isObject, isPromise, isString, isTruthy, isUndefined, kebabCase, matchesAccept, noop, omit, omitBy, partition, pascalCase, pick, pickBy, random, range, remove, runIf, sleep, snakeCase, sortDates, startsWith, throttle, to, trimEnd, trimStart };