@ybgnb/utils 0.1.7 → 0.1.8

package/dist/core/error/common-error.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 通用错误
+ */
+export declare class CommonError extends Error {
+    rawError?: Error;
+    constructor(message: string, rawError?: unknown);
+    toString(): string;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,17 @@
+export * from './error/common-error.js';
+export * from './result/biz-result.js';
+export * from './result/exec-biz.js';
+export * from './types/helpers.js';
+export * from './types/physical.js';
+export * from './utils/array.js';
+export * from './utils/error.js';
+export * from './utils/fetch.js';
+export * from './utils/function.js';
+export * from './utils/github.js';
+export * from './utils/random.js';
+export * from './utils/serialize.js';
+export * from './utils/sleep.js';
+export * from './utils/time.js';
+export * from './utils/type.js';
+export * from './utils/url.js';
+export * from './utils/number/format.js';

package/dist/core/result/biz-result.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 业务执行结果
+ */
+export 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>;
+}

package/dist/core/result/exec-biz.d.ts

@@ -0,0 +1,6 @@
+import { BizResult } from './biz-result.js';
+/**
+ * 执行业务（自动包裹BuResult）
+ * @param run 执行方法
+ */
+export declare const execBiz: <T>(run: () => Promise<T>) => Promise<BizResult<T>>;

package/dist/core/types/helpers.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 提取getter属性
+ */
+export 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;
+};
+/**
+ * 至少包含一个字段
+ */
+export 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];
+/**
+ * 用元组限制长度
+ */
+export type MaxLengthArray<T, N extends number> = T[] & {
+    length: N;
+};
+/**
+ * 提取 T 中所有值类型为 V 的键
+ */
+export type KeysMatching<T, V> = {
+    [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T];
+/**
+ * 任意方法
+ */
+export type AnyFn = (...args: any[]) => any;
+/**
+ * 提取所有方法
+ */
+export type MethodKeys<T> = {
+    [K in keyof T]-?: T[K] extends AnyFn ? K : never;
+}[keyof T];
+/**
+ * 方法参数类型
+ */
+export type MethodParams<T> = T extends (...args: infer P) => any ? P : never;
+/**
+ * 方法返回类型
+ */
+export type MethodReturn<T> = T extends (...args: any[]) => infer R ? R : never;
+/**
+ * 提取所有函数 key
+ */
+export type FunctionKeys<T> = {
+    [K in keyof T]: T[K] extends AnyFn ? K : never;
+}[keyof T];
+/**
+ * 拥有指定键集合的对象类型
+ */
+export type ObjectWithKeys<K extends string | symbol> = {
+    [key in K]: any;
+};

package/dist/core/types/physical.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 物理像素的区域数据
+ */
+export interface PhysicalRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * 物理像素的点位
+ */
+export interface PhysicalPoint {
+    x: number;
+    y: number;
+}

package/dist/core/utils/array.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 是否为空数组
+ * @param data
+ */
+export declare function isEmptyArr(data: unknown): boolean;
+/**
+ * 将数组分块为指定大小的多个子数组
+ * @param arr 原数组
+ * @param size 每个块的长度
+ * @example chunk([1,2,3,4,5], 2) => [[1,2],[3,4],[5]]
+ */
+export declare function chunk<T>(arr: T[], size: number): T[][];

package/dist/core/utils/error.d.ts

@@ -0,0 +1,22 @@
+import { CommonError } from '../error/common-error.js';
+/**
+ * 是否为取消操作的错误
+ */
+export declare function isCanceledError(err: unknown): boolean;
+/**
+ * 创建取消错误
+ * @param msg
+ */
+export declare function createAbortError(msg?: string): Error;
+/**
+ * 是否为通用错误对象
+ */
+export declare function isCommonError(error: unknown): error is CommonError;
+/**
+ * 转换到通用异常
+ */
+export declare function convertToCommonError(error: unknown, prefix?: string): Error;
+/**
+ * 获取异常信息
+ */
+export declare function getErrorMessage(error: unknown): string;

package/dist/core/utils/fetch.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 用于指定 `fetch` 响应体的解析方式。
+ * 对应 `Response` 对象的不同解析方法（`.json()`、`.text()` 等）。
+ */
+export type ResponseBodyFormat = 'json' | 'text' | 'blob' | 'arrayBuffer' | 'formData';
+/**
+ * 创建响应错误
+ */
+export declare function createResponseError(response: Response): Error;
+/**
+ * 使用指定的响应解析格式发起 fetch 请求
+ */
+export declare function fetchWithFormat<T = any>(url: string, format: ResponseBodyFormat, init?: RequestInit): Promise<T>;

package/dist/core/utils/function.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 随机运行参数
+ * @param fns
+ * @param maxCount 最多执行次数（1 ~ fns.length）
+ */
+export 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]
+ * })
+ */
+export declare function processRangeInBatches(start: number, end: number, batchSize: number, processor: (batch: number[]) => Promise<void>): Promise<void>;
+/**
+ * 动态调用
+ * @param root  对象
+ * @param path  调用路径
+ * @param args  参数
+ */
+export declare function dynamicCall<T = any>(root: any, path: string, ...args: any[]): T;

package/dist/core/utils/github.d.ts

@@ -0,0 +1,31 @@
+/** github 仓库信息 */
+export interface GitHubRepo {
+    /** 仓库所有者（用户或组织名） */
+    owner: string;
+    /** 仓库名称 */
+    repo: string;
+}
+/** github 仓库分支信息 */
+export type GitHubRepoBranch = GitHubRepo & {
+    /** 分支名称 */
+    branch: string;
+};
+/** github 仓库文件信息 */
+export type GitHubRepoFile = GitHubRepoBranch & {
+    /** 文件路径 */
+    filePath: string;
+};
+/**
+ * 从 url 解析 github 仓库信息
+ * @param repositoryUrl 仓库 URL（支持带有git+前缀、具体文件路径）
+ */
+export declare function parseGithubRepoUrl(repositoryUrl: string): GitHubRepoBranch;
+/**
+ * 解析 github 仓库文件的原始内容的 url
+ */
+export declare function parseGithubRawUrl(gitHubRepoFile: GitHubRepoFile): string;
+/**
+ * 获取 github 仓库文件的 json 内容并解析为对象 T
+ * @param gitHubRepoFile
+ */
+export declare function getGithubRawJson<O>(gitHubRepoFile: GitHubRepoFile): Promise<O>;

package/dist/core/utils/number/format.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 格式化后的单位数据（如文件大小）
+ */
+export interface FormattedUnitSize {
+    /** 换算后该单位的数值（未四舍五入） */
+    size: number;
+    /** 单位名称，如 'MB' */
+    unit: string;
+    /** 显示文本：数值四舍五入保留两位小数 + 单位，如 '1.50 MB' */
+    text: string;
+}
+/**
+ * 按进制自动格式化单位
+ * @param value 数值
+ * @param base 进制（1024 / 1000）
+ * @param units 单位列表
+ * @param invalidText 无效值返回文本
+ */
+export declare function formatUnitSize(value: number, base: number, units: string[], invalidText?: string): FormattedUnitSize;

package/dist/core/utils/random.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 数组洗牌
+ */
+export declare function shuffle<T>(arr: T[]): T[];
+/**
+ * 获取 [min, max] 的随机整数
+ */
+export declare function randomInt(min: number, max: number): number;
+/**
+ * 获取 [min, max) 的随机浮点数
+ */
+export declare function randomFloat(min: number, max: number): number;
+/**
+ * 从数组中随机取若干项，不可重复
+ */
+export declare function sample<T>(arr: T[], count: number): T[];
+/**
+ * 从数组中随机取若干项，可重复
+ */
+export declare function sampleWithReplacement<T>(arr: T[], count: number): T[];
+/**
+ * 从数组中获取随机项
+ */
+export declare function sampleOne<T>(arr: T[]): T;
+/**
+ * 获取 1~n 的随机数
+ */
+export declare function random1ToN(n: number): number;

package/dist/core/utils/serialize.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 递归移除对象（或数组）中的所有函数属性，返回一个可安全序列化的副本。
+ *
+ * @typeParam T - 输入值的类型。
+ * @param value - 待处理的值（基本类型、对象、数组等）。
+ * @param seen - 内部使用的 WeakMap，用于记录已访问过的对象，防止循环引用。
+ *               调用方通常无需传递此参数。
+ * @returns 处理后的新副本，其中所有函数属性都被移除。
+ *          基本类型（string, number, boolean, null, undefined）将原样返回。
+ */
+export declare function stripFunctions<T>(value: T, seen?: WeakMap<object, any>): T;
+/**
+ * 将错误转换为可 JSON 序列化的普通对象。
+ */
+export declare function serializeError(err: unknown): {
+    name: string;
+    message: string;
+    stack: string | undefined;
+} | {
+    name: string;
+    message: string;
+    stack?: undefined;
+};

package/dist/core/utils/sleep.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 支持取消的 sleep
+ * @param ms      延迟毫秒数
+ * @param signal  取消信号
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+/**
+ * 支持取消的随机 sleep
+ * @param minMS   最小延迟毫秒数
+ * @param maxMS   最大延迟毫秒数
+ * @param signal  取消信号
+ */
+export declare function sleepRandom(minMS: number, maxMS: number, signal?: AbortSignal): Promise<void>;

package/dist/core/utils/time.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 格式化日期
+ */
+export declare function formatDate(date: Date, pattern: 'date' | 'time' | 'datetime'): string;
+/**
+ * 格式化时间为 2020-02-02 20:20:20 的字符串
+ * @param date 需要格式化的时间，为空则获取当前时间
+ */
+export declare function getFormattedDateTime(date?: Date): string;
+/**
+ * 格式化时间为 2020-02-02 20:20:20 的字符串
+ * @param date 需要格式化的时间，为空则获取当前时间
+ */
+export declare function getFormattedDate(date?: Date): string;
+/**
+ * 格式化时间为 20:20:20 的字符串
+ * @param date 需要格式化的时间，为空则获取当前时间
+ */
+export declare function getFormattedTime(date?: Date): string;

package/dist/core/utils/type.d.ts

@@ -0,0 +1,9 @@
+import { ObjectWithKeys } from '../types/helpers.js';
+/**
+ * 判断一个值是否为纯对象
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 包括类实例、普通对象，不包括 数组、null 和原始类型
+ */
+export declare function isObject<K extends string | symbol>(value: unknown, key?: K): value is ObjectWithKeys<K>;

package/dist/core/utils/url.d.ts

@@ -0,0 +1,36 @@
+/** URL query 中必须编码的保留字符 (RFC 3986) */
+export declare const invalidCharRegex: RegExp;
+/** 查询参数 */
+export type QueryParams = Record<string, string | number | boolean | null | undefined>;
+/**
+ * 已解析的 url
+ */
+export interface ParsedUrl {
+    baseUrl: string;
+    searchParams: URLSearchParams;
+}
+/**
+ * 判断字符串是否为有效的 HTTP/HTTPS URL
+ * @param path - 待检测的字符串
+ */
+export declare function isHttpUrl(path: string): boolean;
+/**
+ * 解析 url
+ * @param url
+ */
+export declare function parseUrl(url: string): ParsedUrl;
+/**
+ * 编码 URL 参数
+ * @param params          查询参数
+ * @param keepEmptyValues 保留 null/undefined的值（空字符串）
+ */
+export declare function encodeURLParams(params: QueryParams, keepEmptyValues?: boolean): string;
+/**
+ *
+ */
+/**
+ * 合并查询参数
+ * @param urlSearchParams url解析后查询参数
+ * @param params          单独传的查询参数
+ */
+export declare function mergeQueryParams(urlSearchParams: URLSearchParams, params?: QueryParams): QueryParams;

package/dist/core.d.ts

@@ -0,0 +1,2 @@
+export * from './core/index.js';
+export {};