@ybgnb/utils 0.1.7 → 0.1.9

package/dist/core.d.cts

@@ -0,0 +1,369 @@
+/**
+ * 通用错误
+ */
+declare class CommonError extends Error {
+    rawError?: Error;
+    constructor(message: string, rawError?: unknown);
+    toString(): string;
+}
+
+/**
+ * 业务执行结果
+ */
+declare class BizResult<T> {
+    success: boolean;
+    msg: string;
+    data?: T;
+    constructor(success: boolean, msg: string, data?: T);
+    static createSuccess<T>(data: T): BizResult<T>;
+    static createFail<T>(msg?: string, data?: T): BizResult<T>;
+    static createError<T>(e: unknown): BizResult<T>;
+    /**
+     * 展开成Promise
+     */
+    toPromise(): Promise<void>;
+    toPromise<T>(): Promise<T>;
+}
+
+/**
+ * 执行业务（自动包裹BuResult）
+ * @param run 执行方法
+ */
+declare const execBiz: <T>(run: () => Promise<T>) => Promise<BizResult<T>>;
+
+/**
+ * 提取getter属性
+ */
+type ExtractGetterProperties<T> = {
+    [K in keyof T as K extends `get${infer Rest}` ? Uncapitalize<Rest> : never]: T[K] extends (...args: any[]) => Promise<infer R> ? R : never;
+};
+/**
+ * 至少包含一个字段
+ */
+type RequireAtLeastOne<T, Keys extends keyof T = keyof T> = Pick<T, Exclude<keyof T, Keys>> & {
+    [K in Keys]: Required<Pick<T, K>> & Partial<Pick<T, Exclude<Keys, K>>>;
+}[Keys];
+/**
+ * 用元组限制长度
+ */
+type MaxLengthArray<T, N extends number> = T[] & {
+    length: N;
+};
+/**
+ * 提取 T 中所有值类型为 V 的键
+ */
+type KeysMatching<T, V> = {
+    [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T];
+/**
+ * 任意方法
+ */
+type AnyFn = (...args: any[]) => any;
+/**
+ * 提取所有方法
+ */
+type MethodKeys<T> = {
+    [K in keyof T]-?: T[K] extends AnyFn ? K : never;
+}[keyof T];
+/**
+ * 方法参数类型
+ */
+type MethodParams<T> = T extends (...args: infer P) => any ? P : never;
+/**
+ * 方法返回类型
+ */
+type MethodReturn<T> = T extends (...args: any[]) => infer R ? R : never;
+/**
+ * 提取所有函数 key
+ */
+type FunctionKeys<T> = {
+    [K in keyof T]: T[K] extends AnyFn ? K : never;
+}[keyof T];
+/**
+ * 拥有指定键集合的对象类型
+ */
+type ObjectWithKeys<K extends string | symbol> = {
+    [key in K]: any;
+};
+
+/**
+ * 物理像素的区域数据
+ */
+interface PhysicalRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * 物理像素的点位
+ */
+interface PhysicalPoint {
+    x: number;
+    y: number;
+}
+
+/**
+ * 是否为空数组
+ * @param data
+ */
+declare function isEmptyArr(data: unknown): boolean;
+/**
+ * 将数组分块为指定大小的多个子数组
+ * @param arr 原数组
+ * @param size 每个块的长度
+ * @example chunk([1,2,3,4,5], 2) => [[1,2],[3,4],[5]]
+ */
+declare function chunk<T>(arr: T[], size: number): T[][];
+
+/**
+ * 是否为取消操作的错误
+ */
+declare function isCanceledError(err: unknown): boolean;
+/**
+ * 创建取消错误
+ * @param msg
+ */
+declare function createAbortError(msg?: string): Error;
+/**
+ * 是否为通用错误对象
+ */
+declare function isCommonError(error: unknown): error is CommonError;
+/**
+ * 转换到通用异常
+ */
+declare function convertToCommonError(error: unknown, prefix?: string): Error;
+/**
+ * 获取异常信息
+ */
+declare function getErrorMessage(error: unknown): string;
+
+/**
+ * 用于指定 `fetch` 响应体的解析方式。
+ * 对应 `Response` 对象的不同解析方法（`.json()`、`.text()` 等）。
+ */
+type ResponseBodyFormat = 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData';
+/**
+ * 创建响应错误
+ */
+declare function createResponseError(response: Response): Error;
+/**
+ * 使用指定的响应解析格式发起 fetch 请求
+ */
+declare function fetchWithFormat<T = any>(url: string, format: ResponseBodyFormat, init?: RequestInit): Promise<T>;
+
+/**
+ * 随机运行参数
+ * @param fns
+ * @param maxCount 最多执行次数（1 ~ fns.length）
+ */
+declare function runRandomFunctions(fns: Array<() => void>, maxCount?: number): void;
+/**
+ * 将数字范围按批次处理，每个批次调用一次异步函数
+ *
+ * @param start - 起始值（包含）
+ * @param end   - 结束值（包含）
+ * @param batchSize - 每批最大元素个数
+ * @param processor - 处理单批数字数组的异步函数
+ *
+ * @example
+ * // 分批处理 1..10，每批最多 3 个数字
+ * await processRangeInBatches(1, 10, 3, async (batch) => {
+ *   console.log(batch) // 输出: [1,2,3], [4,5,6], [7,8,9], [10]
+ * })
+ */
+declare function processRangeInBatches(start: number, end: number, batchSize: number, processor: (batch: number[]) => Promise<void>): Promise<void>;
+/**
+ * 动态调用
+ * @param root  对象
+ * @param path  调用路径
+ * @param args  参数
+ */
+declare function dynamicCall<T = any>(root: any, path: string, ...args: any[]): T;
+
+/** github 仓库信息 */
+interface GitHubRepo {
+    /** 仓库所有者（用户或组织名） */
+    owner: string;
+    /** 仓库名称 */
+    repo: string;
+}
+/** github 仓库分支信息 */
+type GitHubRepoBranch = GitHubRepo & {
+    /** 分支名称 */
+    branch: string;
+};
+/** github 仓库文件信息 */
+type GitHubRepoFile = GitHubRepoBranch & {
+    /** 文件路径 */
+    filePath: string;
+};
+/**
+ * 从 url 解析 github 仓库信息
+ * @param repositoryUrl 仓库 URL（支持带有git+前缀、具体文件路径）
+ */
+declare function parseGithubRepoUrl(repositoryUrl: string): GitHubRepoBranch;
+/**
+ * 解析 github 仓库文件的原始内容的 url
+ */
+declare function parseGithubRawUrl(gitHubRepoFile: GitHubRepoFile): string;
+/**
+ * 获取 github 仓库文件的 json 内容并解析为对象 T
+ * @param gitHubRepoFile
+ */
+declare function getGithubRawJson<O>(gitHubRepoFile: GitHubRepoFile): Promise<O>;
+
+/**
+ * 数组洗牌
+ */
+declare function shuffle<T>(arr: T[]): T[];
+/**
+ * 获取 [min, max] 的随机整数
+ */
+declare function randomInt(min: number, max: number): number;
+/**
+ * 获取 [min, max) 的随机浮点数
+ */
+declare function randomFloat(min: number, max: number): number;
+/**
+ * 从数组中随机取若干项，不可重复
+ */
+declare function sample<T>(arr: T[], count: number): T[];
+/**
+ * 从数组中随机取若干项，可重复
+ */
+declare function sampleWithReplacement<T>(arr: T[], count: number): T[];
+/**
+ * 从数组中获取随机项
+ */
+declare function sampleOne<T>(arr: T[]): T;
+/**
+ * 获取 1~n 的随机数
+ */
+declare function random1ToN(n: number): number;
+
+/**
+ * 递归移除对象（或数组）中的所有函数属性，返回一个可安全序列化的副本。
+ *
+ * @typeParam T - 输入值的类型。
+ * @param value - 待处理的值（基本类型、对象、数组等）。
+ * @param seen - 内部使用的 WeakMap，用于记录已访问过的对象，防止循环引用。
+ *               调用方通常无需传递此参数。
+ * @returns 处理后的新副本，其中所有函数属性都被移除。
+ *          基本类型（string, number, boolean, null, undefined）将原样返回。
+ */
+declare function stripFunctions<T>(value: T, seen?: WeakMap<object, any>): T;
+/**
+ * 将错误转换为可 JSON 序列化的普通对象。
+ */
+declare function serializeError(err: unknown): {
+    name: string;
+    message: string;
+    stack: string | undefined;
+} | {
+    name: string;
+    message: string;
+    stack?: undefined;
+};
+
+/**
+ * 支持取消的 sleep
+ * @param ms      延迟毫秒数
+ * @param signal  取消信号
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * 支持取消的随机 sleep
+ * @param minMS   最小延迟毫秒数
+ * @param maxMS   最大延迟毫秒数
+ * @param signal  取消信号
+ */
+declare function sleepRandom(minMS: number, maxMS: number, signal?: AbortSignal): Promise<void>;
+
+/**
+ * 格式化日期
+ */
+declare function formatDate(date: Date, pattern: 'date' | 'time' | 'datetime'): string;
+/**
+ * 格式化时间为 2020-02-02 20:20:20 的字符串
+ * @param date 需要格式化的时间，为空则获取当前时间
+ */
+declare function getFormattedDateTime(date?: Date): string;
+/**
+ * 格式化时间为 2020-02-02 20:20:20 的字符串
+ * @param date 需要格式化的时间，为空则获取当前时间
+ */
+declare function getFormattedDate(date?: Date): string;
+/**
+ * 格式化时间为 20:20:20 的字符串
+ * @param date 需要格式化的时间，为空则获取当前时间
+ */
+declare function getFormattedTime(date?: Date): string;
+
+/**
+ * 判断一个值是否为纯对象
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 包括类实例、普通对象，不包括 数组、null 和原始类型
+ */
+declare function isObject<K extends string | symbol>(value: unknown, key?: K): value is ObjectWithKeys<K>;
+
+/** URL query 中必须编码的保留字符 (RFC 3986) */
+declare const invalidCharRegex: RegExp;
+/** 查询参数 */
+type QueryParams = Record<string, string | number | boolean | null | undefined>;
+/**
+ * 已解析的 url
+ */
+interface ParsedUrl {
+    baseUrl: string;
+    searchParams: URLSearchParams;
+}
+/**
+ * 判断字符串是否为有效的 HTTP/HTTPS URL
+ * @param path - 待检测的字符串
+ */
+declare function isHttpUrl(path: string): boolean;
+/**
+ * 解析 url
+ * @param url
+ */
+declare function parseUrl(url: string): ParsedUrl;
+/**
+ * 编码 URL 参数
+ * @param params          查询参数
+ * @param keepEmptyValues 保留 null/undefined的值（空字符串）
+ */
+declare function encodeURLParams(params: QueryParams, keepEmptyValues?: boolean): string;
+/**
+ *
+ */
+/**
+ * 合并查询参数
+ * @param urlSearchParams url解析后查询参数
+ * @param params          单独传的查询参数
+ */
+declare function mergeQueryParams(urlSearchParams: URLSearchParams, params?: QueryParams): QueryParams;
+
+/**
+ * 格式化后的单位数据（如文件大小）
+ */
+interface FormattedUnitSize {
+    /** 换算后该单位的数值（未四舍五入） */
+    size: number;
+    /** 单位名称，如 'MB' */
+    unit: string;
+    /** 显示文本：数值四舍五入保留两位小数 + 单位，如 '1.50 MB' */
+    text: string;
+}
+/**
+ * 按进制自动格式化单位
+ * @param value 数值
+ * @param base 进制（1024 / 1000）
+ * @param units 单位列表
+ * @param invalidText 无效值返回文本
+ */
+declare function formatUnitSize(value: number, base: number, units: string[], invalidText?: string): FormattedUnitSize;
+
+export { type AnyFn, BizResult, CommonError, type ExtractGetterProperties, type FormattedUnitSize, type FunctionKeys, type GitHubRepo, type GitHubRepoBranch, type GitHubRepoFile, type KeysMatching, type MaxLengthArray, type MethodKeys, type MethodParams, type MethodReturn, type ObjectWithKeys, type ParsedUrl, type PhysicalPoint, type PhysicalRect, type QueryParams, type RequireAtLeastOne, type ResponseBodyFormat, chunk, convertToCommonError, createAbortError, createResponseError, dynamicCall, encodeURLParams, execBiz, fetchWithFormat, formatDate, formatUnitSize, getErrorMessage, getFormattedDate, getFormattedDateTime, getFormattedTime, getGithubRawJson, invalidCharRegex, isCanceledError, isCommonError, isEmptyArr, isHttpUrl, isObject, isPlainObject, mergeQueryParams, parseGithubRawUrl, parseGithubRepoUrl, parseUrl, processRangeInBatches, random1ToN, randomFloat, randomInt, runRandomFunctions, sample, sampleOne, sampleWithReplacement, serializeError, shuffle, sleep, sleepRandom, stripFunctions };