@rainte/js 0.0.55 → 0.0.58

package/dist/types/array/index.d.ts

@@ -1,2 +1,32 @@
+/**
+ * 将树形结构扁平化为一维数组（深度优先，父节点在前）。
+ *
+ * @param tree 树形数组
+ * @param prop 子节点字段名，默认 'children'
+ * @returns 扁平化后的数组，元素类型为去掉子节点字段后的 T
+ *
+ * @example
+ * const tree = [
+ *   { value: 1, children: [{ value: 2 }, { value: 3, children: [{ value: 4 }] }] },
+ *   { value: 5 },
+ * ]
+ * flattenTree(tree)
+ * // => [{ value: 1 }, { value: 2 }, { value: 3 }, { value: 4 }, { value: 5 }]
+ */
 export declare const flattenTree: <T, K extends string = 'children'>(tree: T[], prop?: K) => Omit<T, K>[];
-export declare const findByValue: <T = any>(list: T[], value: unknown, prop?: string) => T | undefined;
+/**
+ * 在数组中按指定字段查找第一个匹配项。
+ * 若传入的 value 是数组，则取其第一个元素作为目标值。
+ *
+ * @param list 待查找的数组
+ * @param value 目标值（或值数组，取第一个）
+ * @param prop 用于比较的字段名，默认 'value'；支持点路径，如 'meta.id'
+ * @returns 匹配项，未找到返回 undefined
+ *
+ * @example
+ * findByValue([{ value: 1 }, { value: 2 }], 2)        // => { value: 2 }
+ * findByValue([{ value: 1 }, { value: 2 }], [2, 3])    // => { value: 2 }
+ * findByValue([{ id: 1 }], 1, 'id')                    // => { id: 1 }
+ * findByValue([{ meta: { id: 1 } }], 1, 'meta.id')     // => { meta: { id: 1 } }
+ */
+export declare const findByValue: <T = unknown>(list: T[], value: unknown, prop?: string) => T | undefined;

package/dist/types/blob/index.d.ts

@@ -1,3 +1,53 @@
+/**
+ * 将 Blob 转为 base64 Data URL 字符串。
+ *
+ * @param blob 待转换的 Blob
+ * @returns Promise<string>，resolve 为 data URL（如 "data:image/png;base64,..."）
+ * @throws FileReader 读取失败时 reject 对应的 DOMException
+ *
+ * @example
+ * const dataUrl = await toBase64(new Blob(['hi'], { type: 'text/plain' }))
+ */
 export declare const toBase64: (blob: Blob) => Promise<string>;
+/**
+ * 将 base64 字符串（或 Data URL）转为 Blob。
+ * 支持三种输入：
+ *  - 完整 Data URL：`data:[<mime>][;base64],<payload>`
+ *  - 裸 base64 前缀：`[<mime>];base64,<payload>`
+ *  - 纯 base64 字符串：`<payload>`（按 base64 解码，mime 为空）
+ *
+ * @param base64 base64 字符串或 Data URL
+ * @param options 可选的 BlobPropertyBag，其 type 优先级高于从字符串解析出的 mime
+ * @returns Blob
+ * @throws payload 非法 base64 时 atob 抛 DOMException
+ *
+ * @example
+ * toBlob('data:text/plain;base64,aGk=')        // Blob { type: 'text/plain', ... }
+ * toBlob('aGk=', { type: 'text/plain' })        // Blob { type: 'text/plain', ... }
+ */
 export declare const toBlob: (base64: string, options?: BlobPropertyBag) => Blob;
+/**
+ * 将 base64 字符串（或 Data URL）转为 File。
+ * 复用 toBlob 的解析逻辑，支持与 toBlob 相同的三种输入。
+ *
+ * @param base64 base64 字符串或 Data URL
+ * @param filename 文件名（File.name）
+ * @param options 可选的 FilePropertyBag，其 type 优先级高于从字符串解析出的 mime
+ * @returns File
+ * @throws payload 非法 base64 时 atob 抛 DOMException
+ *
+ * @example
+ * toFile('data:image/png;base64,iVBORw0KG...', 'a.png')
+ * toFile('aGk=', 'a.txt', { type: 'text/plain' })
+ */
+export declare const toFile: (base64: string, filename: string, options?: FilePropertyBag) => File;
+/**
+ * 触发浏览器下载。
+ *
+ * @param filename 下载文件名
+ * @param obj Blob 或 MediaSource
+ *
+ * @example
+ * download('a.txt', new Blob(['hello'], { type: 'text/plain' }))
+ */
 export declare const download: (filename: string, obj: Blob | MediaSource) => void;

package/dist/types/date/index.d.ts

@@ -1,11 +1,31 @@
-import dayjs from 'dayjs';
-export { dayjs };
+import { DateTime } from 'luxon';
+/**
+ * 常用日期时间格式常量（Luxon format token）。
+ *
+ * @example
+ * now().toFormat(FORMAT.DATETIME) // '2026-11-08 12:34:56'
+ */
 export declare const FORMAT: {
-    DATETIME: string;
-    DATE: string;
-    TIME: string;
-    YEAR: string;
-    MONTH: string;
-    HOUR: string;
-    MINUTE: string;
+    readonly DATETIME: 'yyyy-MM-dd HH:mm:ss';
+    readonly DATE: 'yyyy-MM-dd';
+    readonly TIME: 'HH:mm:ss';
+    readonly YEAR: 'yyyy';
+    readonly MONTH: 'yyyy-MM';
+    readonly HOUR: 'yyyy-MM-dd HH';
+    readonly MINUTE: 'yyyy-MM-dd HH:mm';
 };
+/**
+ * 常用时区常量（IANA 时区名）。
+ */
+export declare const ZONE: {
+    readonly CN: 'Asia/Shanghai';
+};
+/**
+ * 获取当前时间，并设置为中国时区（Asia/Shanghai）。
+ *
+ * @returns 处于 Asia/Shanghai 时区的当前 DateTime
+ *
+ * @example
+ * now().toFormat(FORMAT.DATETIME) // '2026-11-08 12:34:56'（上海时间）
+ */
+export declare const now: () => DateTime;

package/dist/types/hash/index.d.ts

@@ -1,3 +1,39 @@
-export declare const SHA256: (input: unknown, toJson?: boolean) => Promise<string>;
+/**
+ * 计算 SHA-256 摘要，返回小写十六进制字符串（64 字符）。
+ *
+ * @param text 待哈希的字符串
+ * @returns Promise<string>，64 位小写十六进制摘要
+ *
+ * @example
+ * await SHA256('hello')
+ * await SHA256(JSON.stringify({ a: 1 }))
+ */
+export declare function SHA256(text: string): Promise<string>;
+/**
+ * 对任意值先做原生 JSON 序列化，再计算 SHA-256 摘要。
+ *
+ * @param input 待哈希内容，必须是 JSON 可表达的值
+ * @returns Promise<string>，64 位小写十六进制摘要
+ *
+ * @example
+ * await SHA256Json({ a: 1 }) // 等价于 SHA256('{"a":1}')
+ */
+export declare const SHA256Json: (input: unknown) => Promise<string>;
+/**
+ * 生成一个 32 位无符号随机整数（[0, 2^32 - 1]），使用 crypto.getRandomValues。
+ *
+ * @returns 随机整数
+ *
+ * @example
+ * random() // 例如 3735928559
+ */
 export declare const random: () => number;
+/**
+ * 生成一个 22 位 Base62 字符串 ID，随机熵与 UUID v4 相同（122 位）。
+ *
+ * @returns 22 位 Base62 字符串
+ *
+ * @example
+ * id() // 例如 '4kX9mP2nQ7rT1sV5wY8zA3'
+ */
 export declare const id: () => string;

package/dist/types/http/axios.d.ts

@@ -1,7 +1,40 @@
 export declare const ACCESS_TOKEN = "access_token";
+/**
+ * 从后端返回体中提取错误信息，兼容 `message` / `msg` 字段。
+ *
+ * @param data 响应体或错误对象
+ * @param text 兜底文案
+ * @returns 错误信息字符串
+ */
 export declare const message: <T = string>(data: any, text?: string) => T;
 export declare const axios: import("axios").AxiosInstance;
+/**
+ * 请求拦截器：自动从本地存储读取 token，注入 Authorization 头。
+ *
+ * @returns 拦截器 id，可用于 `axios.interceptors.request.eject`
+ */
 export declare const tokenRequestInterceptor: () => number;
+/** 响应拦截器透传的响应体类型 */
+export type ResponseData<T = unknown> = {
+    data: T;
+} & Record<string, unknown>;
+/**
+ * 响应拦截器：
+ * - 2xx：若响应体是 `{ data: ... }` 信封则解包，否则原样返回；
+ * - 非 2xx：构造 Error 交给 onRejected 或 reject；
+ * - 网络/超时错误：交给 onRejected 或 reject。
+ *
+ * @param onRejected 可选的统一错误处理函数
+ * @returns 拦截器 id，可用于 `axios.interceptors.response.eject`
+ */
 export declare const responseInterceptor: (onRejected?: ((error: any) => any) | null) => number;
+/**
+ * 401 重试逻辑：token 刷新期间到达的请求进入队列，刷新成功后统一重放；
+ * 刷新失败则队列内所有请求统一 reject。
+ *
+ * @param error Axios 抛出的错误
+ * @param refreshRequest 刷新 token 的函数
+ * @returns 重放后的响应，或 reject
+ */
 export declare const retry: (error: any, refreshRequest: () => Promise<unknown>) => Promise<unknown>;
 export default axios;

package/dist/types/http/index.d.ts

@@ -1,6 +1,42 @@
-import type { AxiosRequestConfig } from 'axios';
+import type { AxiosRequestConfig, AxiosResponse } from 'axios';
 export * from './axios';
-export declare const get: (url: string, params?: ObjectProps) => Promise<import("axios").AxiosResponse<any, any, {}, any>>;
-export declare const post: (url: string, data?: ObjectProps) => Promise<import("axios").AxiosResponse<any, any, {}, any>>;
-export declare const download: (config: AxiosRequestConfig) => Promise<import("axios").AxiosResponse<any, any, {}, any>>;
-export declare const request: (config: AxiosRequestConfig) => Promise<import("axios").AxiosResponse<any, any, {}, any>>;
+/**
+ * GET 请求。
+ *
+ * @param url 请求地址
+ * @param params 查询参数
+ * @returns Axios 响应 Promise
+ *
+ * @example
+ * get('/api/user', { id: 1 })
+ */
+export declare const get: <T = unknown>(url: string, params?: ObjectProps) => Promise<AxiosResponse<T>>;
+/**
+ * POST 请求，默认 `Content-Type: application/json`。
+ *
+ * @param url 请求地址
+ * @param data 请求体
+ * @returns Axios 响应 Promise
+ *
+ * @example
+ * post('/api/user', { name: 'foo' })
+ */
+export declare const post: <T = unknown>(url: string, data?: ObjectProps) => Promise<AxiosResponse<T>>;
+/**
+ * 下载请求，强制 `responseType = 'blob'`（除非调用方显式指定了其他值）。
+ *
+ * @param config 请求配置
+ * @returns 响应 Promise，`data` 为 Blob（或调用方指定的其他类型）
+ *
+ * @example
+ * const res = await download({ url: '/api/export', method: 'GET' })
+ * const blob = res.data as Blob
+ */
+export declare const download: <T = Blob>(config: AxiosRequestConfig) => Promise<AxiosResponse<T>>;
+/**
+ * 统一请求入口：注入默认 `Content-Type`，透传给 Axios 实例。
+ *
+ * @param config 请求配置
+ * @returns 响应 Promise
+ */
+export declare const request: <T = unknown>(config: AxiosRequestConfig) => Promise<AxiosResponse<T>>;

package/dist/types/json/index.d.ts

@@ -1,3 +1,25 @@
-import { type Options } from 'jsan';
-export declare const stringify: (value?: unknown, replacer?: (key: string, value: unknown) => unknown | Array<number | string> | null, space?: string | number, _options?: Options | boolean) => string;
-export declare const parse: <T = any>(text: string, reviver?: (key: string, value: unknown) => unknown) => T;
+/**
+ * 基于 superjson 的 JSON 序列化，支持 Date、RegExp、Map、Set、BigInt、undefined 等
+ * 原生 JSON.stringify 会丢失或报错的数据类型。
+ *
+ * @param value 待序列化的值
+ * @returns 序列化后的字符串，结构为 `{"json": ..., "meta": ...}`
+ * @throws 值包含不可序列化内容（如函数、DOM 节点、循环引用中 superjson 不支持的部分）时抛错
+ *
+ * @example
+ * stringify({ a: 1, b: undefined, c: new Date(0) })
+ * // => '{"json":{"a":1,"c":"1970-01-01T00:00:00.000Z"},"meta":{"values":{"b":["undefined"],"c":["Date"]}}}'
+ */
+export declare const stringify: (value: unknown) => string;
+/**
+ * 基于 superjson 的反序列化，能还原 superjson.stringify 产生的特殊类型。
+ *
+ * @param text 待解析的字符串
+ * @returns 解析后的值，泛型 T 由调用方指定（默认 unknown）
+ * @throws 字符串不是合法 JSON 或不是 superjson 信封格式时抛错
+ *
+ * @example
+ * parse<{ date: Date }>('{"json":{"date":"1970-01-01T00:00:00.000Z"},"meta":{"values":{"date":["Date"]}}}')
+ * // => { date: Date(0) }
+ */
+export declare const parse: <T = unknown>(text: string) => T;

package/dist/types/lib.d.ts

@@ -1,10 +1,8 @@
 export * as array from './array';
 export * as blob from './blob';
-export * as database from './database';
 export * as date from './date';
 export * as hash from './hash';
 export * as http from './http';
 export * as json from './json';
-export * as storage from './storage';
 export * as system from './system';
 export * as url from './url';

package/dist/types/system/index.d.ts

@@ -1,4 +1,28 @@
-export declare const sleep: (ms: number) => Promise<unknown>;
-export declare const log: (message: any, type?: string) => void;
+/**
+ * 延迟指定毫秒。
+ *
+ * @param ms 毫秒数，负数按 0 处理
+ * @param signal 可选的 AbortSignal，abort 时 Promise 以 AbortError reject
+ * @returns Promise<void>，到时 resolve
+ *
+ * @example
+ * await sleep(1000)
+ *
+ * const ctrl = new AbortController()
+ * setTimeout(() => ctrl.abort(), 100)
+ * await sleep(1000, ctrl.signal).catch(() => {})
+ */
+export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+/**
+ * 抛出错误，用于表达"此处不应继续"。
+ *
+ * @param message 错误信息
+ * @returns 永不返回（类型为 never）
+ * @throws 总是抛出 Error
+ *
+ * @example
+ * function assert(cond: unknown): asserts cond {
+ *   if (!cond) fail('assertion failed')
+ * }
+ */
 export declare const fail: (message: string) => never;
-export declare const loadModules: (modules: ObjectProps) => Promise<ObjectProps>;

package/dist/types/url/index.d.ts

@@ -1,3 +1,36 @@
-export declare const search: () => URLSearchParams;
-export declare const params: () => ObjectProps;
+/**
+ * 将 query 字符串解析为 URLSearchParams。
+ *
+ * @param query 待解析的 query 字符串，默认取当前页面 `location.search`
+ * @returns URLSearchParams 实例
+ *
+ * @example
+ * search('?a=1&b=2').get('a') // '1'
+ * search().get('a')           // 当前页面 URL 中的 a 参数
+ */
+export declare const search: (query?: string) => URLSearchParams;
+/**
+ * 将 query 字符串解析为普通对象。
+ * 同名参数会合并为数组，单个参数保持字符串。
+ *
+ * @param query 待解析的 query 字符串，默认取当前页面 `location.search`
+ * @returns 键值对对象；无参数时返回空对象
+ *
+ * @example
+ * params('?a=1&b=2&b=3') // { a: '1', b: ['2', '3'] }
+ * params()               // 当前页面的 query 对象
+ */
+export declare const params: (query?: string) => ObjectProps;
+/**
+ * 打开新窗口/标签页。
+ *
+ * @param url 目标地址，默认 `about:blank`
+ * @param target 窗口名，默认 `'_blank'`
+ * @param features 窗口特性字符串
+ * @returns 新窗口的 Window 引用；被浏览器拦截时返回 null
+ *
+ * @example
+ * open('https://example.com')
+ * open('/detail/1', '_self')
+ */
 export declare const open: (url?: string | URL, target?: string, features?: string) => Window | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rainte/js",
-  "version": "0.0.55",
+  "version": "0.0.58",
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -36,18 +36,16 @@
   },
   "dependencies": {
     "axios": "^1.21.0",
-    "dayjs": "^1.11.23",
-    "dexie": "^4.4.7",
-    "jsan": "^3.1.14"
+    "luxon": "^3.7.2",
+    "superjson": "^2.2.6"
   },
   "devDependencies": {
-    "@types/jsan": "^3.1.5",
+    "@types/luxon": "^3.7.6",
     "@types/node": "^26.6.6",
-    "fake-indexeddb": "^6.2.7",
     "happy-dom": "^21.0.4",
-    "oxlint": "^1.90.0",
+    "oxlint": "^1.92.0",
     "typescript": "^7.0.2",
-    "vite": "^8.3.5",
+    "vite": "^8.3.6",
     "vitest": "^5.1.0"
   }
 }

package/dist/types/database/index.d.ts

@@ -1,14 +0,0 @@
-import Dexie, { type Table } from 'dexie';
-export interface DexieRow {
-    id?: number;
-    key: string;
-    value: any;
-}
-export declare class SubDexie extends Dexie {
-    rows: Table<DexieRow, number>;
-    constructor(name?: string);
-}
-export declare const getDB: (name?: string) => SubDexie;
-export declare const db: SubDexie;
-export declare const get: <T = any>(key: string, raw?: boolean) => Promise<T | undefined>;
-export declare const set: (key: string, value: any) => import("dexie").PromiseExtended<number>;

package/dist/types/storage/index.d.ts

@@ -1,13 +0,0 @@
-declare class Cache {
-    private storage?;
-    constructor(storage?: Storage);
-    getRaw(key: string, defaultValue?: string | null): string | null;
-    setRaw(key: string, value: string): void;
-    get<T = any>(key: string, defaultValue?: T | null): T | null;
-    set(key: string, value: any): void;
-    del(key: string): void;
-    clear(): void;
-}
-export declare const local: Cache;
-export declare const session: Cache;
-export {};