nfx-ui 0.6.2 → 0.7.1

package/dist/utils.d.ts

@@ -1,486 +1 @@
-import { Options } from 'async-retry';
-
-/** 错误响应。Error response. */
-declare interface ApiErrorBody {
-    /** 状态码。Status code. */
-    status?: number;
-    /** 错误码。Error code. */
-    errCode?: string;
-    /** 消息。Message. */
-    message?: string;
-    /** 详情。Details. */
-    details?: unknown;
-    /** 追踪 ID。Trace ID. */
-    traceId?: string;
-}
-
-/**
- * 数组类型。Array type.
- * @example Array<string> => string[]
- */
-declare type Array_2<T> = T[];
-
-/** 可实例化的构造函数类型。Instantiable constructor type. */
-declare type Constructor<T extends object = object> = new (...args: unknown[]) => T;
-
-/**
- * 从字符串列表创建键值映射对象；可选 valueMapper 指定值
- * Create record from string list; optional valueMapper for values.
- * @param list - 字符串数组（作为键）
- * @param valueMapper - 可选，(item, index) => value，缺省时值为键本身
- * @returns Record<list[number], V>
- * @example createMap(["a","b","c"]) // { a: "a", b: "b", c: "c" }
- * @example createMap(["a","b","c"], (_, i) => i) // { a: 0, b: 1, c: 2 }
- */
-export declare function createMap<T extends string, V = T>(list: ReadonlyArray<T>, valueMapper?: (item: T, index: number) => V): Record<T, V>;
-
-/**
- * 可为 null、undefined 或空字符串。Emptyable: T | null | undefined | "".
- * @example Emptyable<string> => string | null | undefined | ""
- */
-declare type Emptyable<T> = T | null | undefined | "";
-
-/**
- * 构造失败结果（非 Error 会包装为 Error）。Create a failed result; non-Error wrapped in Error.
- * @param e - 错误或任意值。Error or any value.
- * @returns [null, Error]
- * @example err(new Error("fail")) // [null, Error]
- */
-export declare const err: (e: unknown) => Result<never>;
-
-/**
- * 格式化日期仅年月日 (YYYY/MM/DD)，用于生日等
- * Format date as year/month/day only.
- * @param dateString - 日期字符串，如 "2000-01-15" 或 ISO
- * @returns 格式化后的日期字符串，无效则返回原串
- */
-export declare const formatDate: (dateString: string) => string;
-
-/**
- * 格式化时间显示年月日时分 (YYYY/MM/DD HH:mm)
- * Format date-time as year/month/day hour:minute.
- * @param dateString - 时间字符串
- * @returns 格式化后的时间字符串，无效则返回原串
- */
-export declare const formatDateTime: (dateString: string) => string;
-
-/**
- * 格式化日期为 YYYY/MM/DD（空或无效返回 ""）
- * Format date as YYYY/MM/DD; empty or invalid returns "".
- * @param dateString - 日期字符串
- * @returns 格式化后的日期字符串，无效则 ""
- */
-export declare const formatDisplayDate: (dateString: string | undefined | null) => string;
-
-/**
- * 格式化时间显示月日时分 (MM/DD HH:mm)
- * Format date-time as month/day hour:minute.
- * @param dateString - 时间字符串
- * @returns 格式化后的时间字符串，无效则返回原串
- */
-export declare const formatMonthDayTime: (dateString: string) => string;
-
-/**
- * 数字缩写显示（如 1.2k+、3.5M+、1.1B+）
- * Format number to abbreviated string (e.g. 1.2k+, 3.5M+, 1.1B+).
- * @param num - 数字
- * @returns 缩写字符串
- */
-export declare function formatNumberAbbreviated(num: number): string;
-
-/**
- * 格式化为相对时间（如 2 days ago, 3 months ago）
- * Format as relative time (e.g. 2 days ago, 3 months ago).
- * @param dateString - 日期字符串
- * @returns 相对时间字符串，无效为 "Invalid date"，空为 "Unknown"
- */
-export declare const formatRelativeTime: (dateString: string | undefined | null) => string;
-
-/**
- * 格式化 ISO 日期为图表轴/提示用短格式（如：Jan 4, 02:30 PM）
- * Format ISO date for chart axis/tooltip (e.g. Jan 4, 02:30 PM).
- * @param iso - ISO 日期字符串
- * @returns 格式化字符串，解析失败则返回原串
- */
-export declare function formatTickDate(iso: string): string;
-
-/**
- * 格式化时间显示时分 (HH:mm)
- * Format time as hour:minute.
- * @param dateString - 时间字符串
- * @returns 格式化后的时间字符串，无效则返回原串
- */
-export declare const formatTime: (dateString: string) => string;
-
-/**
- * 仅当为后端错误（有 response.data）时解析为 ApiErrorBody，否则返回 null
- * Parse to ApiErrorBody only when response.data exists; otherwise null.
- * @param error - 通常为 Axios 错误或 unknown
- * @returns ApiErrorBody 或 null
- */
-export declare function getApiError(error: unknown): ApiErrorBody | null;
-
-/**
- * UI 展示用错误文案：优先 i18n errors 命名空间（errCode），其次 api.message，最后 fallback
- * Get display message: i18n errors namespace (by errCode) → api.message → fallback.
- * @param error - 通常为 Axios 错误
- * @param fallback - 无法解析时的默认文案
- * @returns 展示用字符串
- */
-export declare function getApiErrorMessage(error: unknown, fallback: string): string;
-
-/**
- * 从电话号码解析国家/地区码（基于 google-libphonenumber）
- * Get country code from phone number (google-libphonenumber).
- * @param phoneNumber - 电话号码字符串
- * @returns 国家码数字
- */
-export declare const getCountryCode: (phoneNumber: string) => number;
-
-export declare function getItem(key: string): Nilable<string>;
-
-/**
- * 将 HEX 颜色转换为 RGBA
- * @param hex - HEX 颜色字符串，格式: "#RRGGBB" 或 "#RGB"
- * @param alpha - 透明度，范围 0-1
- * @returns RGBA 颜色字符串，格式: "rgba(r, g, b, alpha)"
- *
- * @example
- * hexToRGBA("#FA1E16", 0.3) // "rgba(250, 30, 22, 0.3)"
- */
-export declare const hexToRGBA: (hex: string, alpha: number) => string;
-
-/**
- * 在两色之间按 factor 线性插值（支持 hex / rgb）
- * Linear color interpolation between start and end by factor (0–1); supports hex and rgb.
- * @param start - 起始颜色
- * @param end - 结束颜色
- * @param factor - 插值系数 0–1
- * @returns rgb(r, g, b) 字符串
- */
-export declare const interpolateColor: (start: string, end: string, factor: number) => string;
-
-/**
- * 校验邮箱格式是否有效（简单正则：含 @ 与点）
- * Check if email format is valid (simple regex: contains @ and dot).
- * @param email - 待校验的邮箱字符串
- * @returns 是否有效
- */
-export declare const isValidEmail: (email: string) => boolean;
-
-/**
- * 校验电话号码是否有效（基于 google-libphonenumber）
- * Check if phone number is valid (google-libphonenumber).
- * @param phoneNumber - 电话号码字符串
- * @returns 是否有效
- */
-export declare const isValidPhoneNumber: (phoneNumber: string) => boolean;
-
-/**
- * 可为 undefined。Maybe: T | undefined.
- * @example Maybe<number> => number | undefined
- */
-declare type Maybe<T> = T | undefined;
-
-/**
- * 按 id 将 items 合并进数组：insert 仅插入新 id，upsert 覆盖同 id 并插入新 id；可 prepend 或 append
- * Merge items into array by id: insert = only new ids, upsert = overwrite same id + insert new; place = prepend | append.
- * @param arr - 原数组
- * @param items - 待合并项
- * @param idOf - 取 id 的函数
- * @param place - 新项插入位置
- * @param mode - insert 不覆盖已有 id；upsert 覆盖同 id
- * @returns 合并后的新数组
- */
-export declare function mergeById<T>(arr: Array_2<T>, items: Array_2<T>, idOf: (x: T) => string, place: "prepend" | "append", mode: "insert" | "upsert"): Array_2<T>;
-
-/**
- * 可为 null 或 undefined。Nilable: T | null | undefined.
- * @example Nilable<boolean> => boolean | null | undefined
- */
-declare type Nilable<T> = T | null | undefined;
-
-/**
- * 可为 null 或 undefined。Nilable: T | null | undefined.
- * @example Nilable<boolean> => boolean | null | undefined
- */
-declare type Nilable_2<T> = T | null | undefined;
-
-/**
- * 规范化地址字符串：去除首尾空白并将连续空白合并为单个空格
- * Normalize address string: trim and collapse consecutive spaces to one.
- * @param address - 原始地址字符串
- * @returns 规范化后的地址
- */
-export declare function normalizeAddress(address: string): string;
-
-/**
- * 可为 null。Nullable: T | null.
- * @example Nullable<string> => string | null
- */
-declare type Nullable<T> = T | null;
-
-/**
- * 构造成功结果。Create a successful result.
- * @param v - 结果值。Result value.
- * @returns [v, null]
- * @example ok(42) // [42, null]
- */
-export declare const ok: <T>(v: T) => Result<T>;
-
-/**
- * 从对象中剔除指定键，返回新对象（不修改原对象）
- * Omit specified keys from object and return a new object.
- * @param obj - 源对象
- * @param keys - 要剔除的键（数组或单个键，可再接多个键）
- * @returns 剔除后的新对象
- * @example omit({ a: 1, b: 2, c: 3 }, ['a', 'c']) // { b: 2 }
- * @example omit({ a: 1, b: 2, c: 3 }, 'a', 'b')  // { c: 3 }
- */
-export declare function omit<Obj extends object, Key extends keyof Obj>(obj: Obj, keys: Key[] | Key, ...restKeys: Key[]): Omit<Obj, Key>;
-
-/**
- * 包装为「仅执行一次」的异步函数（重复调用返回同一 Promise）。
- * Wrap async function so it runs only once; repeated calls return the same promise.
- * @param fn - 要执行的异步函数。Async function to run once.
- * @returns 包装后的函数，多次调用只执行一次。Wrapped function; only first call runs.
- * @example const loadOnce = onceAsync(() => fetch("/api/config")); loadOnce(); loadOnce(); // 只请求一次
- */
-export declare function onceAsync<T, Args extends unknown[]>(fn: (...args: Args) => Promise<T>): (...args: Args) => Promise<T>;
-
-/**
- * 按 key 仅执行一次的异步函数（同一 key 重复调用返回同一 Promise）。
- * Async function that runs only once per key; same key returns same promise.
- * @param fn - 要执行的异步函数。Async function to run.
- * @param keyExtractor - 从参数中提取 key 的函数。Function to extract key from args.
- * @returns 包装后的函数。Wrapped function.
- * @example const fetchUser = onceAsyncByKey((id: string) => api.getUser(id), (id) => id); fetchUser("1"); fetchUser("1"); // 同 id 只请求一次
- */
-export declare function onceAsyncByKey<T, Args extends unknown[]>(fn: (...args: Args) => Promise<T>, keyExtractor: (...args: Args) => string): (...args: Args) => Promise<T>;
-
-/**
- * 轮询直到 isOK(data) 为 true（内部用 withRetryResult 重试）。
- * Poll until fetcher returns data that satisfies isOK; uses withRetryResult.
- * @param fetcher - 拉取数据的函数。Function that fetches data.
- * @param isOK - 判断数据是否满足条件。Predicate to check if data is OK.
- * @param opts - 重试选项。Retry options.
- * @returns Promise<Result<T>>
- * @example const [job] = await pollUntil(() => getJob(id), (j) => j.status === "done", { retries: 10 });
- */
-export declare function pollUntil<T>(fetcher: () => Promise<T>, isOK: (data: T) => boolean, opts?: WithRetryOptions): Promise<Result<T>>;
-
-/**
- * 从数组中移除 id 在集合 ids 中的项，返回新数组
- * Remove elements whose id is in the given set; return new array.
- * @param arr - 原数组
- * @param ids - 要移除的 id 集合
- * @param idOf - 取 id 的函数
- * @returns 若无变化返回原数组，否则返回新数组
- */
-export declare function pruneArray<T>(arr: Array_2<T>, ids: ReadonlySet<string>, idOf: (x: T) => string): Array_2<T>;
-
-export declare function removeItem(key: string): void;
-
-/**
- * 结果类型：成功为 [T, null]，失败为 [null, Error]。
- * Result type: success [T, null], failure [null, Error].
- * @template T - 成功时的值类型。Value type on success.
- * @example const [data, err] = await withRetryResult(() => fetchData()); if (err) return; use(data);
- */
-export declare type Result<T> = [T, null] | [null, Error];
-
-/**
- * 将 RGB 颜色转换为 RGBA
- * @param rgb - RGB 颜色字符串，格式: "rgb(r, g, b)"
- * @param alpha - 透明度，范围 0-1
- * @returns RGBA 颜色字符串，格式: "rgba(r, g, b, alpha)"
- *
- * @example
- * rgbToRgba("rgb(250, 30, 22)", 0.3) // "rgba(250, 30, 22, 0.3)"
- */
-export declare const rgbToRgba: (rgb: string, alpha: number) => string;
-
-/**
- * 将 Nilable 数组规范为数组：null/undefined 转为 [] 或 defaultValue。返回类型 Array&lt;T&gt;（即 T[]）。
- * Normalize Nilable array to array: null/undefined to [] or defaultValue. Returns Array&lt;T&gt; (i.e. T[]).
- * @param value - 可能为 null 或 undefined 的数组 (array that may be null or undefined)
- * @param defaultValue - 可选，当 value 为 null/undefined 时使用；缺省为 [] (optional default when value is null/undefined; default is [])
- * @returns value ?? defaultValue ?? [] (never null/undefined)
- * @example safeArray(product.tags) // product.tags ?? []
- * @example safeArray(product.tags, ['default'])
- */
-export declare function safeArray<T>(value: Nilable_2<Array_2<T>>, defaultValue?: Array_2<T>): Array_2<T>;
-
-/**
- * 将 Nilable 规范为 Maybe：null 转为 undefined，undefined 与 T 原样返回。返回类型 Maybe&lt;T&gt;。等同 value ?? undefined。
- * Normalize Nilable to Maybe: convert null to undefined; undefined and T unchanged. Returns Maybe&lt;T&gt;. Same as value ?? undefined.
- * @param value - 可能为 null 或 undefined 的值 (value that may be null or undefined)
- * @returns 若为 null 或 undefined 则 undefined，否则原值 (undefined if null/undefined, otherwise value)
- * @example safeMaybe(product.price) // 代替 product.price ?? undefined
- */
-export declare function safeMaybe<T>(value: Nilable_2<T>): Maybe<T>;
-
-/**
- * 将 Emptyable 字符串规范为 Nilable：空字符串转为 undefined，null/undefined/非空串原样。返回类型 Nilable&lt;T&gt;。常用于表单、接口字段。
- * Normalize Emptyable string to Nilable: "" to undefined; null, undefined, non-empty string unchanged. Returns Nilable&lt;T&gt;. For form/API fields.
- * @param value - 可能为 null、undefined 或空字符串 (value that may be null, undefined or "")
- * @returns 若为 "" 则 undefined，否则原值 (undefined if "", otherwise value)
- * @example safeNilable(product.remark) // "" 也视为「无值」
- */
-export declare function safeNilable<T extends string>(value: Emptyable<T>): Nilable_2<T>;
-
-/**
- * 将 Nilable 规范为 Nullable：undefined 转为 null，null 与 T 原样返回。返回类型 Nullable&lt;T&gt;。
- * Normalize Nilable to Nullable: convert undefined to null; null and T unchanged. Returns Nullable&lt;T&gt;.
- * @param value - 可能为 null 或 undefined 的值 (value that may be null or undefined)
- * @returns 若为 undefined 则 null，否则原值 (null if undefined, otherwise value)
- * @example safeNullable(apiResponse.data) // undefined → null，便于区分「未设置」与「空」
- */
-export declare function safeNullable<T>(value: Nilable_2<T>): Nullable<T>;
-
-/**
- * 安全取数字：null/undefined/NaN 转为 undefined，合法数字原样。返回类型 Maybe&lt;number&gt;。
- * Safe number: null/undefined/NaN to undefined; valid number unchanged. Returns Maybe&lt;number&gt;.
- * @param value - 可能为 null、undefined 或非数字 (value that may be null, undefined or NaN)
- * @returns 若为 null、undefined 或 NaN 则 undefined，否则数字 (undefined if null/undefined/NaN, otherwise number)
- * @example safeNum(product.price) // 用于严格「有值才用」的场景
- */
-export declare function safeNum(value: Nilable_2<number>): Maybe<number>;
-
-/**
- * 若值为 null/undefined 则返回默认值，否则返回原值。等同 value ?? defaultValue。
- * Return defaultValue when value is null/undefined, otherwise value. Same as value ?? defaultValue.
- * @param value - 可能为 null 或 undefined 的值 (value that may be null or undefined)
- * @param defaultValue - 默认值 (default value)
- * @returns value ?? defaultValue
- * @example safeOr(product.stock, 0)
- * @example safeOr(product.name, '')
- */
-export declare function safeOr<T, D>(value: Nilable_2<T>, defaultValue: D): T | D;
-
-/**
- * 将 Emptyable 字符串规范为 Stringable：null/undefined/"" 转为 ""。返回类型 Stringable&lt;string&gt;（即 string，"" 为兜底）。
- * Normalize Emptyable string to Stringable: null/undefined/"" to "". Returns Stringable&lt;string&gt; (string with "" as fallback).
- * @param value - 可能为 null、undefined 或空字符串 (value that may be null, undefined or "")
- * @returns 若为 null、undefined 或 "" 则 ""，否则原值 ("" if null/undefined/"", otherwise value)
- * @example safeStringable(product.name) // 代替 product.name ?? ""
- */
-export declare function safeStringable<T extends string>(value: Emptyable<T>): Stringable<T>;
-
-/**
- * 将 Nilable 数值规范为 Zeroable：null/undefined 转为 0。返回类型 Zeroable&lt;number&gt;（即 number，0 为兜底）。
- * Normalize Nilable number to Zeroable: null/undefined to 0. Returns Zeroable&lt;number&gt; (number with 0 as fallback).
- * @param value - 可能为 null 或 undefined 的数值 (number that may be null or undefined)
- * @returns value ?? 0 (never null/undefined)
- * @example safeZeroable(product.stock) // 代替 product.stock ?? 0
- */
-export declare function safeZeroable(value: Nilable_2<number>): Zeroable<number>;
-
-export declare function setItem(key: string, value: string): void;
-
-/**
- * 单例工厂：将传入的构造函数包装为单例模式；Proxy 拦截 construct，多次 new 返回同一实例。
- * Singleton factory: wrap constructor so that multiple new calls return the same instance.
- *
- * @template T - 实例类型（需为 object）。Instance type (must be object).
- * @param className - 被包装的构造函数（class）。Constructor (class) to wrap.
- * @returns 代理后的构造函数，调用时始终返回同一实例。Proxied constructor returning same instance.
- *
- * @example
- * ```ts
- * class MyService { ... }
- * const SingletonService = singleton(MyService);
- * const a = new SingletonService();
- * const b = new SingletonService();
- * console.log(a === b); // true
- * ```
- */
-export declare const singleton: <T extends object>(className: Constructor<T>) => Constructor<T>;
-
-/**
- * 可为空字符串的类型。Stringable: T | ""，T 为 string 子类型。
- * @example Stringable<string> => string | ""
- */
-declare type Stringable<T extends string> = T | "";
-
-/**
- * 若值为 null/undefined 则抛出 Promise 使 React Suspense 挂起，否则返回该值。
- * If value is null/undefined, throw a promise to suspend (React Suspense); otherwise return value.
- * @param value - 待检查的值。Value to check.
- * @param delay - 重试前的延迟（毫秒）。Delay in ms before retry.
- * @returns 非空时的 value。Value when non-null.
- * @example const data = suspenseIfNull(resource); // 在 Suspense 边界内，data 非空时才渲染
- */
-export declare function suspenseIfNull<T>(value: Nilable_2<T>, delay?: number): T;
-
-/**
- * 显示价格 → 数据库价格（分）。用于提交到后端、保存草稿等
- * Display price to database price (cents). For submit/save.
- * @param displayPrice - 展示用价格（元）
- * @returns 数据库存储价格（分）
- */
-export declare function toDatabasePrice(displayPrice: number): number;
-
-/**
- * 数据库价格（分）→ 显示价格字符串（两位小数）
- * Database price (cents) to display string (2 decimal places).
- * @param databasePrice - 数据库价格（分）
- * @returns 如 "12.34"
- */
-export declare function toDisplayPrice(databasePrice: number): string;
-
-/**
- * 数据库价格（分）→ 显示价格数字。用于表单、计算等
- * Database price (cents) to display number.
- * @param databasePrice - 数据库价格（分）
- * @returns 数字（元）
- */
-export declare function toDisplayPriceNumber(databasePrice: number): number;
-
-/**
- * 将任意值转为数字输入框可用的字符串（用于表单回显）
- * Convert any value to a string suitable for number input (e.g. form display).
- * @param value - 任意值
- * @returns 字符串；null/undefined → ""；非有限数字 → ""；数组取首项
- */
-export declare function toNumberInputValue(value: unknown): string;
-
-/**
- * 将任意颜色统一为指定透明度的 RGBA（rgb/rgba/hex 均用新 alpha 覆盖）
- * Convert any color to RGBA with given alpha (overwrites existing alpha).
- * @param color - rgb / rgba / hex 字符串
- * @param alpha - 透明度 0–1
- * @returns rgba(r, g, b, alpha) 字符串
- */
-export declare const toRgbaWithAlpha: (color: string, alpha: number) => string;
-
-/**
- * 将任意值转为文本输入框可用的字符串（用于表单回显）
- * Convert any value to a string suitable for text input (e.g. form display).
- * @param value - 任意值
- * @returns 字符串；null/undefined → ""；数组 → 逗号拼接；对象 → JSON 字符串
- */
-export declare function toTextInputValue(value: unknown): string;
-
-export declare type WithRetryOptions = Options & {
-    /** 若返回 true 则不再重试，直接 bail。If true, do not retry and bail. */
-    isNonRetryable?: (e: Error) => boolean;
-};
-
-/**
- * 带重试执行异步函数，成功返回 ok(value)，失败返回 err(error)。
- * Retry async function until success or max attempts; returns Result.
- * @param fn - 可接收 bail 与 attempt 的异步函数。Async function receiving bail and attempt.
- * @param opts - async-retry 选项及 isNonRetryable。async-retry options and isNonRetryable.
- * @returns Promise<Result<T>>
- * @example const [data, err] = await withRetryResult(() => fetchData(), { retries: 3 });
- */
-export declare function withRetryResult<T>(fn: (bail: (e: Error) => void, attempt: number) => Promise<T>, opts?: WithRetryOptions): Promise<Result<T>>;
-
-/**
- * 可为 0 的数值类型。Zeroable: T | 0，T 为 number 子类型。
- * @example Zeroable<number> => number | 0
- */
-declare type Zeroable<T extends number> = T | 0;
-
 export { }