@cmtlyt/lingshu-toolkit 0.5.0 → 0.7.0

package/dist/shared/lock-data/types.d.ts

@@ -0,0 +1,347 @@
+/**
+ * lock-data 模块的公开类型定义
+ *
+ * 仅包含 API 表面（options / actions / listeners / adapters 等），
+ * 内部实现使用的类型（Entry / InstanceRegistry / DriverHandle 等）放在对应模块内部。
+ *
+ * 对应 RFC.md「附录 A：完整接口索引」章节。
+ */
+import type { NEVER_TIMEOUT } from './constants';
+/**
+ * 超时参数支持的形态：
+ * - number：毫秒数（0 或负数非法，由参数校验层拦截）
+ * - NEVER_TIMEOUT：永不超时（业务自控）
+ */
+type TimeoutValue = number | typeof NEVER_TIMEOUT;
+/** 跨进程同步模式；本期仅 `'none'` 与 `'storage-authority'` */
+type SyncMode = 'none' | 'storage-authority';
+/**
+ * 锁驱动选择模式
+ *
+ * 对应 RFC.md「能力检测与降级」；`adapters.getLock` 存在时本字段被忽略
+ *
+ * - `'auto'`（默认）：按能力降级链 web-locks → broadcast → storage
+ * - `'web-locks'` / `'broadcast'` / `'storage'`：强制使用对应 driver；能力不可用时抛错
+ */
+type LockMode = 'auto' | 'web-locks' | 'broadcast' | 'storage';
+/**
+ * 持久化策略：
+ * - `'session'`（默认）：所有 Tab 关闭后重置；协作期的天然语义
+ * - `'persistent'`：跨浏览器重启保留；适合用户草稿 / 偏好
+ */
+type Persistence = 'session' | 'persistent';
+/** `actions` 内部状态机的公开子集；用于 listeners.onLockStateChange 事件 */
+type LockPhase = 'idle' | 'acquiring' | 'holding' | 'committing' | 'released' | 'revoked' | 'disposed';
+/** revoke 触发原因 */
+type RevokeReason = 'force' | 'timeout' | 'dispose';
+/** `listeners.onSync` 的触发来源 */
+type SyncSource = 'pull-on-acquire' | 'storage-event' | 'pageshow' | 'visibilitychange';
+/** `listeners.onCommit` 的触发来源 */
+type CommitSource = 'update' | 'replace';
+/**
+ * Draft 执行期间记录的最小路径变更
+ *
+ * 同时服务审计（listeners.onCommit）与回滚（revoke / abort 时反向应用）
+ *
+ * **JSON-only 契约**：lock-data 的 draft 仅支持 JSON 安全类型（plain object / array /
+ * string / number（不含 NaN/Infinity）/ boolean / null），故 mutation op 仅有
+ * 普通对象属性的 `set` / `delete` 两种。Set / Map / Date / class 实例 等非 JSON
+ * 类型在 `createDraftSession` 入口与每次写入处会被显式拒绝（抛 `TypeError`），
+ * 详见 `core/draft.ts` 文件顶部「JSON-only 契约」说明。
+ *
+ * op 语义：
+ * - `'set'`：属性写入 / 新增，`path` 指向被修改的属性，`value` 为新值
+ * - `'delete'`：属性删除，`path` 指向被删除的属性，`value` 不携带
+ */
+type LockDataMutationOp = 'set' | 'delete';
+interface LockDataMutation {
+    readonly path: readonly PropertyKey[];
+    readonly op: LockDataMutationOp;
+    readonly value?: unknown;
+}
+/** 状态流转事件 */
+interface LockStateChangeEvent {
+    readonly phase: LockPhase;
+    readonly token: string;
+}
+/** revoke 事件 */
+interface RevokeEvent {
+    readonly reason: RevokeReason;
+    readonly token: string;
+}
+/** commit 事件（仅 commit 成功时触发） */
+interface CommitEvent<T> {
+    readonly source: CommitSource;
+    readonly token: string;
+    readonly rev: number;
+    readonly mutations: readonly LockDataMutation[];
+    readonly snapshot: T;
+}
+/** sync 事件（仅 syncMode 非 none 时触发） */
+interface SyncEvent<T> {
+    readonly source: SyncSource;
+    readonly rev: number;
+    readonly snapshot: T;
+}
+/** 全部事件监听器；均为可选 */
+interface LockDataListeners<T> {
+    onLockStateChange?: (event: LockStateChangeEvent) => void;
+    onRevoked?: (event: RevokeEvent) => void;
+    onCommit?: (event: CommitEvent<T>) => void;
+    onSync?: (event: SyncEvent<T>) => void;
+}
+/** 每次 action 调用级别的覆盖项 */
+interface ActionCallOptions {
+    /** 覆盖 options.timeout 中的抢锁部分 */
+    acquireTimeout?: TimeoutValue;
+    /** 覆盖 options.timeout 中的持锁部分 */
+    holdTimeout?: TimeoutValue;
+    /** 强制抢占当前持有者 */
+    force?: boolean;
+    /** 仅影响本次调用的取消信号 */
+    signal?: AbortSignal;
+}
+/**
+ * 驱动工厂上下文；用户注入自定义 `adapters.getLock` 时 RFC 约定的参数
+ *
+ * 命名字段与 RFC 「自定义锁驱动」示例对齐，不使用简写
+ */
+interface LockDriverContext {
+    readonly name: string;
+    readonly token: string;
+    readonly force: boolean;
+    readonly acquireTimeout: TimeoutValue;
+    readonly holdTimeout: TimeoutValue;
+    readonly signal: AbortSignal;
+}
+/** 锁驱动句柄；由 `adapters.getLock` 返回 */
+interface LockDriverHandle {
+    /**
+     * 释放锁
+     *
+     * 返回值兼容 Promises/A+ 规范的最小 thenable（仅需实现 `.then`），
+     * 实现侧通过 `Promise.resolve(...).catch(...)` 正规化后挂错误处理
+     */
+    release: () => void | PromiseLike<void>;
+    onRevokedByDriver: (callback: (reason: 'force' | 'timeout') => void) => void;
+}
+/** `AuthorityAdapter` 工厂上下文 */
+interface AuthorityAdapterContext {
+    readonly id: string;
+}
+/** `ChannelAdapter` 工厂上下文 */
+interface ChannelAdapterContext {
+    readonly id: string;
+    readonly channel: 'session' | 'custom';
+}
+/** `SessionStoreAdapter` 工厂上下文 */
+interface SessionStoreAdapterContext {
+    readonly id: string;
+}
+interface AuthorityAdapter {
+    read: () => string | null;
+    write: (raw: string) => void;
+    remove: () => void;
+    subscribe: (onExternalUpdate: (newValue: string | null) => void) => () => void;
+}
+interface ChannelAdapter {
+    postMessage: (message: unknown) => void;
+    subscribe: (onMessage: (message: unknown) => void) => () => void;
+    close: () => void;
+}
+interface SessionStoreAdapter {
+    read: () => string | null;
+    write: (value: string) => void;
+}
+interface LoggerAdapter {
+    warn: (message: string, ...extras: unknown[]) => void;
+    error: (message: string, ...extras: unknown[]) => void;
+    debug?: (message: string, ...extras: unknown[]) => void;
+}
+/**
+ * 顶层数组类型禁止
+ *
+ * wrapper Proxy 方案下，顶层数组会触发 `Object.keys(view)` / `JSON.stringify(view)` 的
+ * length invariant TypeError、`Array.isArray(view)` 永远返回 `false` 等不可调和的不变量冲突
+ *
+ * 编译期把 `T extends unknown[]` 排除为 `never`，运行时由 `core/entry.ts` 的 `Array.isArray(awaited)`
+ * 双重 fail-fast 拒绝，保证用户面错误信息明确（`InvalidOptionsError`）
+ *
+ * 对应 RFC.md「顶层数组禁止」章节
+ */
+type LockDataValueShape<T> = T extends readonly unknown[] ? never : T;
+/**
+ * 所有环境依赖的统一注入入口
+ *
+ * 设计决策：采用工厂函数（`getXxx(ctx) => Adapter`）而非直接传实例，
+ * 理由是锁 / 权威副本 / 通道这些依赖与 id 强绑定，工厂形态允许上层
+ * 在首次创建 Entry 时按 id 组装；无 id 作用域的依赖（logger）直接传实例
+ *
+ * 注：本期不再提供 `clone` 适配器，所有快照派生使用 `JSON.parse(JSON.stringify(...))` 固化语义；
+ * `getValue` resolve 后 + `actions.replace(next)` 入参由 `assertJsonSafe` fail-fast 校验，
+ * 保证 `entry.dataRef.current` 永远只含 JSON 安全值
+ */
+interface LockDataAdapters<_T> {
+    getLock?: (ctx: LockDriverContext) => Promise<LockDriverHandle> | LockDriverHandle;
+    getAuthority?: (ctx: AuthorityAdapterContext) => AuthorityAdapter | null;
+    getChannel?: (ctx: ChannelAdapterContext) => ChannelAdapter | null;
+    getSessionStore?: (ctx: SessionStoreAdapterContext) => SessionStoreAdapter | null;
+    logger?: LoggerAdapter;
+}
+/**
+ * `lockData` 的顶层配置（**单参数 API**）
+ *
+ * - `getValue` 必传：数据来源唯一入口，返回值禁止为顶层数组（`LockDataValueShape<T>` 类型层排除）
+ * - 同步 `getValue()` → `lockData()` 同步返回元组
+ * - 异步 `getValue()` → `lockData()` 返回 Promise<元组>，resolve 后才把元组交付给调用方
+ *
+ * 对应 RFC.md「§3 核心语义」「§API 签名」章节
+ */
+interface LockDataOptions<T> {
+    /**
+     * 锁 id；未传时视为"纯本地只读锁"，不参与跨模块 / 跨 Tab 共享
+     */
+    id?: string;
+    /**
+     * 数据初始化器（**必传**）
+     *
+     * - 返回值在类型层被 `LockDataValueShape<T>` 限制：禁止顶层数组（`T extends readonly unknown[]` 排除为 `never`）
+     * - 返回 `T` → `lockData` 同步返回元组
+     * - 返回 `Promise<T>` → `lockData` 返回 Promise<元组>
+     * - 同步 `getValue()` 抛错 → `lockData()` 调用栈直接抛 `LockDisposedError`（Entry 不构造）
+     * - 异步 `getValue()` reject → `lockData()` 返回的 Promise reject `LockDisposedError`，`cause` 字段携带原因
+     * - 运行时 `Array.isArray(awaited)` 双重 fail-fast 拒绝顶层数组（抛 `InvalidOptionsError`）
+     * - resolve 后由 `assertJsonSafe` 校验 JSON 安全（非 JSON-safe 抛 `InvalidOptionsError`）
+     */
+    getValue: () => LockDataValueShape<T> | Promise<LockDataValueShape<T>>;
+    /** 默认抢锁 + 持锁超时，可被 `ActionCallOptions` 覆盖 */
+    timeout?: TimeoutValue;
+    /**
+     * 锁驱动选择；默认 `'auto'`
+     *
+     * `adapters.getLock` 存在时本字段被忽略（用户自定义 driver 优先级最高）
+     */
+    mode?: LockMode;
+    /** 跨进程同步模式；默认 `'none'` */
+    syncMode?: SyncMode;
+    /** 持久化策略；默认 `'session'`（仅在 syncMode 非 none 时生效） */
+    persistence?: Persistence;
+    /** session-probe 等待窗口；默认 100ms */
+    sessionProbeTimeout?: number;
+    /** 实例级生命周期控制；abort 等价于 dispose() */
+    signal?: AbortSignal;
+    /** 全部事件监听器 */
+    listeners?: LockDataListeners<T>;
+    /** 所有环境依赖的注入入口 */
+    adapters?: LockDataAdapters<T>;
+}
+/**
+ * actions 对象的公开 API
+ *
+ * 每个方法的语义详见 RFC.md「Actions 实现要点」章节
+ */
+interface LockDataActions<T extends object> {
+    /** 当前是否持有锁（释放 / revoke 后为 false） */
+    readonly isHolding: boolean;
+    /** 事务式写入；recipe 失败或被 revoke 时自动回滚 */
+    update: (recipe: (draft: T) => void | Promise<void>, callOptions?: ActionCallOptions) => Promise<void>;
+    /** 整体替换；等价于一次隐式 update 事务；入参由 `assertJsonSafe` fail-fast 校验 */
+    replace: (next: T, callOptions?: ActionCallOptions) => Promise<void>;
+    /**
+     * 不抢锁的快照读取
+     *
+     * 返回 `JSON.parse(JSON.stringify(entry.dataRef.current))` 产出的全新对象，
+     * 与内部 `dataRef.current` 完全隔离；调用方对返回值的任何 mutate 都不会影响内部状态
+     *
+     * 对应 RFC.md「actions.snapshot()」章节
+     */
+    snapshot: () => T;
+    /** 手动抢锁；配合连续 update + release 实现多步事务 */
+    getLock: (callOptions?: ActionCallOptions) => Promise<void>;
+    /**
+     * 只还锁，不销毁实例；actions 仍可继续使用
+     *
+     * 与 `dispose` 的区别：release 对应 getLock，dispose 对应 lockData
+     */
+    release: () => void;
+    /** 还锁 + 销毁实例；调用后本 actions 进入 disposed 终态 */
+    dispose: () => Promise<void>;
+}
+/**
+ * lockData 返回值
+ *
+ * 同步初始化时为元组；异步初始化（getValue 返回 Promise 或 syncMode 非 none）时为 Promise<元组>
+ *
+ * 内部视角类型（第一个元素为裸 T），用于 `core/entry.ts` 及其调用链的实现；
+ * 对外公开契约请使用 `LockDataTuple<T>`（第一个元素为 `ReadonlyView<T>`）
+ */
+type LockDataResult<T extends object> = readonly [T, LockDataActions<T>];
+/**
+ * 深只读视图
+ *
+ * - 函数类型透传不递归（避免破坏 this / 参数类型）
+ * - 对象类型递归加 readonly，所有属性只读
+ * - 其他类型（primitive / symbol）原样透传
+ *
+ * 运行时由 `core/readonly-view.ts::createReadonlyView` 返回深只读 Proxy 保证；
+ * 用户通过 `lockData()` 返回的 tuple 第一个元素拿到的即为 `ReadonlyView<T>` 实例
+ *
+ * 对应 RFC.md「ReadonlyView\<T\>」章节
+ *
+ * 注：`(...args: any[]) => any` 是 RFC 合同语义（匹配任意函数签名的透传），
+ * 无法用 `unknown[]` / `unknown` 替代（否则 `keyof` 分发到函数类型会得出 `never`）
+ */
+type ReadonlyView<T> = T extends (...args: never[]) => unknown ? T : T extends object ? {
+    readonly [K in keyof T]: ReadonlyView<T[K]>;
+} : T;
+/**
+ * lockData 公开契约的返回元组类型
+ *
+ * 与内部 `LockDataResult<T>` 的区别：第一个元素类型为 `ReadonlyView<T>`（深只读代理），
+ * 明确向用户传达"读句柄只读、写操作必须经 `actions.update/replace`"的设计意图
+ *
+ * 对应 RFC.md「签名」章节
+ */
+type LockDataTuple<T extends object> = readonly [ReadonlyView<T>, LockDataActions<T>];
+/**
+ * lockData 返回值类型推断（**单签名 + 条件类型自动推断**）
+ *
+ * 设计动机：避免 `LockDataTuple<T> | Promise<LockDataTuple<T>>` 联合类型在调用点强迫
+ * 用户用 `as` 断言或 `instanceof Promise` 分支判断；类型层直接镜像运行时判定优先级，
+ * 让 `lockData({ getValue: () => ({}) })` 直接得到元组、`lockData({ getValue: () => Promise.resolve({}) })`
+ * 直接得到 Promise，无需 `await` / 断言
+ *
+ * 判定优先级（与 `core/entry.ts` 运行时分支严格对齐）：
+ * 1. `O extends { syncMode: 'storage-authority' }`
+ *    a. 若 `O extends { id: string }` → `Promise<LockDataTuple<T>>`
+ *    b. 若 `O` 缺 `id` 字段 → `never`（**最严格类型层校验**：`syncMode='storage-authority'`
+ *       要求必须传 `id`，否则 authority 无法绑定作用域；编译期 fail-fast 让这种非法组合
+ *       在调用点直接类型报错，避免运行时静默 fallback 到 `'none'`）
+ * 2. 否则若 `ReturnType<O['getValue']> extends Promise<unknown>` → `Promise<LockDataTuple<T>>`
+ * 3. 否则 → `LockDataTuple<T>`
+ *
+ * 注：判定 1.b 用 `LockDataReturnNeverWithoutId` 做条件分支，避免 `O extends { id: string }`
+ * 在 `O` 是宽泛类型（如 `LockDataOptions<T>`）时被推断为 `true` 而绕过校验；
+ * 必须严格匹配 `O` 类型字面量中的 `id` 字段
+ *
+ * 注：第二个泛型参数 `O` 的约束放宽为 `object` 而非 `LockDataOptions<X>`，
+ * 是 TypeScript 条件类型推断的**标准协变兜底用法**：
+ * - `LockDataOptions<T>` 在 `T` 上是双向不变（`listeners.onCommit` 等回调字段使 `T` 既出现在
+ *   协变位置又出现在逆变位置）
+ * - 调用 `lockData<const O extends LockDataOptions<LockDataValueShape<LockDataInfer<O>>>>(options: O)`
+ *   后，把 `O` 传给 `LockDataReturn<T, O>` 时若约束写成 `LockDataOptions<X>`（无论 `X` 是
+ *   `T` / `any` / `unknown`），都会因双向不变而拒绝（参见 tsc TS2344）
+ * - 条件分支只关心 `O` 是否包含 `syncMode` / `id` / `getValue` 字段，不需要 `O` 是
+ *   `LockDataOptions` 的子类型；约束放到 `object` 即可（公开签名 `lockData` 的 `O` 约束
+ *   已保证调用方传入合法 `LockDataOptions<X>`，类型层条件分支无需重复约束）
+ *
+ * 对应 RFC.md「§签名」章节 + 决策 #33 §A
+ */
+type LockDataReturn<T extends object, O extends object> = O extends {
+    syncMode: 'storage-authority';
+} ? O extends {
+    id: string;
+} ? Promise<LockDataTuple<T>> : never : O extends {
+    getValue: () => infer R;
+} ? R extends Promise<unknown> ? Promise<LockDataTuple<T>> : LockDataTuple<T> : LockDataTuple<T>;
+export type { ActionCallOptions, AuthorityAdapter, AuthorityAdapterContext, ChannelAdapter, ChannelAdapterContext, CommitEvent, CommitSource, LockDataActions, LockDataAdapters, LockDataListeners, LockDataMutation, LockDataMutationOp, LockDataOptions, LockDataResult, LockDataReturn, LockDataTuple, LockDataValueShape, LockDriverContext, LockDriverHandle, LockMode, LockPhase, LockStateChangeEvent, LoggerAdapter, Persistence, ReadonlyView, RevokeEvent, RevokeReason, SessionStoreAdapter, SessionStoreAdapterContext, SyncEvent, SyncMode, SyncSource, TimeoutValue, };

package/dist/shared/lock-data/utils/json-safe.d.ts

@@ -0,0 +1,69 @@
+/**
+ * lock-data 模块的 JSON 安全校验工具
+ *
+ * 设计动机：wrapper 方案下所有进入 `entry.dataRef.current` 的值都必须是 JSON 安全的，
+ * 否则 `JSON.parse(JSON.stringify(...))` 会静默丢失 Set / Map / Date / class instance / undefined 等
+ *
+ * 边界一致：
+ * - getValue resolve 后入口走 `assertJsonSafe(awaited, ...)` fail-fast
+ * - actions.replace(next) 入口走 `assertJsonSafe(next, ...)` fail-fast
+ * - draft.ts 的写入路径同样复用本模块的 assertJsonSafe（共享同一份语义）
+ *
+ * 顶层数组在类型层（`LockDataValueShape<T>`）已被排除为 `never`；运行时通过
+ * `assertNotTopLevelArray` 双重 fail-fast 拦截类型擦除路径下的误用
+ *
+ * 对应 fixes/api-getvalue-only-redesign.md §14.4 / RFC.md「JSON 安全契约」章节
+ */
+/**
+ * 描述非 JSON 值的具体类型，用于错误信息
+ *
+ * 例：`Set` / `Map` / `Date` / `class instance (Foo)` / `function` / `bigint` / `NaN`
+ */
+declare function describeNonJsonValue(value: unknown): string;
+/**
+ * 校验值是否为 JSON 安全类型；遇到非法值 / 循环引用立即抛 `TypeError`
+ *
+ * 允许：string / number（不含 NaN/Infinity）/ boolean / null / plain object / array
+ * 禁止：undefined / bigint / symbol / function / Set / Map / Date / RegExp / class 实例 /
+ *       TypedArray / WeakMap / WeakSet / 循环引用 等
+ *
+ * `seen` 仅跟踪当前路径上访问过的容器（递归回溯时 `delete`），保证「同一兄弟节点的相同
+ * 引用」不会被误判为环
+ *
+ * @param subject 错误信息中的来源描述（如 `'getValue() result'` / `'actions.replace(next)'` / `'draft'`）
+ */
+declare function assertJsonSafe(value: unknown, path: readonly PropertyKey[], seen: WeakSet<object>, subject: string): void;
+/**
+ * 顶层数组运行时拒绝（fail-fast）
+ *
+ * 类型层已通过 `LockDataValueShape<T> = T extends readonly unknown[] ? never : T` 排除，
+ * 本函数仅作类型擦除路径下的最后一道防线 —— 抛 `InvalidOptionsError`
+ *
+ * @param value 待检查的值
+ * @param subject 错误信息中的来源描述（如 `'getValue() result'` / `'actions.replace(next)'`）
+ */
+declare function assertNotTopLevelArray(value: unknown, subject: string): void;
+/**
+ * JSON 拷贝隔离：把任意 JSON 安全的值深拷贝为全新引用
+ *
+ * 调用方必须保证 input 已通过 `assertJsonSafe` —— 本函数不做校验，直接 `JSON.parse(JSON.stringify(...))`
+ *
+ * 用途：
+ * - `entry.dataRef.current = cloneByJson(getValue 返回值)`：getValue 与内部状态隔离
+ * - `entry.dataRef.current = cloneByJson(committedNext)`：commit 与 draft 隔离
+ * - `actions.snapshot() = cloneByJson(entry.dataRef.current)`：调用方与内部状态隔离
+ * - `commitEvent.snapshot = cloneByJson(entry.dataRef.current)`：listener 与内部状态隔离
+ */
+declare function cloneByJson<T>(value: T): T;
+/**
+ * 入口便捷封装：组合 `assertNotTopLevelArray` + `assertJsonSafe`
+ *
+ * 用于 getValue / actions.replace 等"外部入参"边界的统一 fail-fast：
+ * 1. 顶层数组判定（双重 fail-fast 的运行时一道）
+ * 2. 整体 JSON 安全校验
+ *
+ * 同步链路抛 `InvalidOptionsError`（顶层数组）/ `TypeError`（其他非 JSON-safe），
+ * 调用方拿到错误后应原样向上抛
+ */
+declare function assertJsonSafeInput(value: unknown, subject: string): void;
+export { assertJsonSafe, assertJsonSafeInput, assertNotTopLevelArray, cloneByJson, describeNonJsonValue };

package/dist/shared/lock-data/utils/json-safe.js

@@ -0,0 +1 @@
+import{throwError as e}from"../../throw-error/index.js";import{ERROR_FN_NAME as t}from"../constants.js";import{InvalidOptionsError as r}from"../errors/index.js";function n(e){if(0===e.length)return"<root>";let t="";for(let r=0;r<e.length;r++){let n=e[r];if("number"==typeof n||"string"==typeof n&&/^\d+$/u.test(n)){t+=`[${String(n)}]`;continue}t+=0===r?String(n):`.${String(n)}`}return t}function o(e){if(void 0===e)return"undefined";if("number"==typeof e){if(Number.isNaN(e))return"NaN";if(!Number.isFinite(e))return e>0?"Infinity":"-Infinity"}let t=typeof e;if("object"!==t)return t;if(null===e)return"null";let r=Object.prototype.toString.call(e).slice(8,-1);if("Object"!==r)return r;let n=e.constructor;return n&&n!==Object&&"string"==typeof n.name&&n.name.length>0?`class instance (${n.name})`:"non-plain object"}function s(r,i,l,a){let u;if(null===r)return;void 0===r&&e(t,`${a} only supports JSON-safe values, got "undefined" at "${n(i)}" (use "null" instead)`,TypeError);let f=typeof r;if("string"===f||"boolean"===f)return;if("number"===f){Number.isFinite(r)||e(t,`${a} only supports JSON-safe values, got "${o(r)}" at "${n(i)}"`,TypeError);return}if("object"!==f&&e(t,`${a} only supports JSON-safe values, got "${o(r)}" at "${n(i)}"`,TypeError),l.has(r)&&e(t,`${a} detected cyclic reference at "${n(i)}"`,TypeError),Array.isArray(r)){l.add(r);for(let e=0;e<r.length;e++)s(r[e],[...i,e],l,a);l.delete(r);return}(u=Object.getPrototypeOf(r))!==Object.prototype&&null!==u&&e(t,`${a} only supports JSON-safe values (plain object / array / string / number / boolean / null), got "${o(r)}" at "${n(i)}"`,TypeError),l.add(r),Object.getOwnPropertySymbols(r).length>0&&e(t,`${a} only supports JSON-safe values, got symbol-keyed property at "${n(i)}"`,TypeError);let p=Object.keys(r);for(let e=0;e<p.length;e++){let t=p[e];s(r[t],[...i,t],l,a)}l.delete(r)}function i(n,o){Array.isArray(n)&&e(t,`${o} must not return an array; lockData rejects top-level arrays (wrap in object {} instead)`,r)}function l(e){return JSON.parse(JSON.stringify(e))}function a(e,t){i(e,t),s(e,[],new WeakSet,t)}export{s as assertJsonSafe,a as assertJsonSafeInput,i as assertNotTopLevelArray,l as cloneByJson,o as describeNonJsonValue};

package/dist/shared/logger/index.d.ts

@@ -2,9 +2,9 @@ type Logger = {
     [K in keyof Omit<Console, 'table'> as Console[K] extends (...args: any[]) => any ? K : never]: Console[K] extends (...args: [any, ...infer AS]) => infer R ? (fnName: string, ...args: AS) => R : never;
 };
 declare global {
-    var $$lingshu$$: {
+    var $$lingshu$$: Partial<{
         disableLogger: boolean;
-    };
+    }>;
 }
 export declare const logger: Logger;
 export {};

package/dist/shared/logger/index.js

@@ -1,10 +1 @@
-const logger = new Proxy(console, {
-    get (target, prop, receiver) {
-        if ((globalThis.$$lingshu$$ || {}).disableLogger) return ()=>void 0;
-        const oldLog = Reflect.get(target, prop, receiver).bind(console);
-        return (fnName, ...args)=>{
-            oldLog(`[@cmtlyt/lingshu-toolkit#${fnName}]:`, ...args);
-        };
-    }
-});
-export { logger };
+let e=new Proxy(console,{get(e,l,o){if((globalThis.$$lingshu$$||{}).disableLogger)return()=>void 0;let t=Reflect.get(e,l,o).bind(console);return(e,...l)=>{t(`[@cmtlyt/lingshu-toolkit#${e}]:`,...l)}}});export{e as logger};

package/dist/shared/priority-queue/index.d.ts

@@ -0,0 +1,45 @@
+import type { PriorityQueueOptions } from './types';
+declare class PriorityQueue<T> {
+    private readonly heap;
+    private readonly itemSet;
+    private readonly compare;
+    private readonly allowDuplicate;
+    private insertCounter;
+    constructor(options?: PriorityQueueOptions<T>);
+    private swapItems;
+    private heapifyUp;
+    private heapifyDown;
+    private isDuplicate;
+    enqueue(item: T): boolean;
+    enqueueMany(items: T[]): boolean[];
+    dequeue(): T | undefined;
+    peek(): T | undefined;
+    size(): number;
+    isEmpty(): boolean;
+    clear(): void;
+    /**
+     * 返回队列中所有元素的有序数组副本
+     *
+     * @description
+     * 该方法返回一个新数组，包含队列中的所有元素，按照以下顺序排列：
+     * 1. 优先级从小到大（根据 compare 函数）
+     * 2. 相同优先级的元素按照插入顺序（FIFO）
+     *
+     * 注意：返回的是数组副本，修改返回的数组不会影响原队列
+     *
+     * @returns 按优先级和插入顺序排序的元素数组
+     *
+     * @example
+     * ```ts
+     * const queue = priorityQueue<number>();
+     * queue.enqueue(3);
+     * queue.enqueue(1);
+     * queue.enqueue(2);
+     *
+     * console.log(queue.toArray()); // [1, 2, 3]
+     * ```
+     */
+    toArray(): T[];
+}
+declare function priorityQueue<T>(options?: PriorityQueueOptions<T>): PriorityQueue<T>;
+export { priorityQueue };

package/dist/shared/priority-queue/index.js

@@ -0,0 +1 @@
+import{$dt as e,$t as t,dataHandler as i}from"../data-handler/index.js";import{logger as h}from"../logger/index.js";import{tryCall as r}from"../try-call/index.js";import{defaultCompare as s,getLeftChildIndex as a,getParentIndex as p,getRightChildIndex as n,updateSmallestIndex as l}from"./utils.js";let o=e({compare:t.function(()=>s),allowDuplicate:t.boolean(!1)});class u{heap=[];itemSet=new Set;compare;allowDuplicate;insertCounter=0;constructor(e={}){let{compare:t,allowDuplicate:h}=i(e||{},o,{unwrap:!0});this.compare=t,this.allowDuplicate=h}swapItems(e,t){[this.heap[e],this.heap[t]]=[this.heap[t],this.heap[e]]}heapifyUp(e){let t=e;for(;t>0;){let e=p(t),i=this.heap[t],h=this.heap[e];if(0>this.compare(i.item,h.item))this.swapItems(t,e),t=e;else break}}heapifyDown(e){let t=e,i=this.heap.length;for(;t<i;){let e=a(t),h=n(t),r=t;if(r=l(e,r,i,this.heap,this.compare),(r=l(h,r,i,this.heap,this.compare))===t)break;this.swapItems(t,r),t=r}}isDuplicate(e){return!this.allowDuplicate&&this.itemSet.has(e)}enqueue(e){if(this.isDuplicate(e)){let t=r(()=>"object"==typeof e&&null!==e?JSON.stringify(e):String(e),()=>Object.prototype.toString.call(e));return h.warn("PriorityQueue.enqueue",`Duplicate item detected: ${t}`),!1}let t={item:e,insertOrder:this.insertCounter++};return this.allowDuplicate||this.itemSet.add(e),this.heap.push(t),this.heapifyUp(this.heap.length-1),!0}enqueueMany(e){return e.map(e=>this.enqueue(e))}dequeue(){let e;if(0!==this.heap.length)return 1===this.heap.length?e=this.heap.pop().item:(e=this.heap[0].item,this.heap[0]=this.heap.pop(),this.heapifyDown(0)),this.itemSet.delete(e),e}peek(){if(0!==this.heap.length)return this.heap[0].item}size(){return this.heap.length}isEmpty(){return 0===this.heap.length}clear(){this.heap.length=0,this.itemSet.clear(),this.insertCounter=0}toArray(){let e=[...this.heap];return e.sort((e,t)=>{let i=this.compare(e.item,t.item);return 0!==i?i:e.insertOrder-t.insertOrder}),e.map(e=>e.item)}}function m(e){return new u(e)}export{m as priorityQueue};

package/dist/shared/priority-queue/types.d.ts

@@ -0,0 +1,10 @@
+type CompareFn<T> = (first: T, second: T) => number;
+interface PriorityQueueOptions<T> {
+    compare?: CompareFn<T>;
+    allowDuplicate?: boolean;
+}
+interface HeapItem<T> {
+    item: T;
+    insertOrder: number;
+}
+export type { CompareFn, HeapItem, PriorityQueueOptions };

package/dist/shared/priority-queue/utils.d.ts

@@ -0,0 +1,7 @@
+import type { CompareFn, HeapItem } from './types';
+declare function defaultCompare<T>(left: T, right: T): number;
+declare function getParentIndex(index: number): number;
+declare function getLeftChildIndex(index: number): number;
+declare function getRightChildIndex(index: number): number;
+declare function updateSmallestIndex<T>(childIndex: number, smallestIndex: number, size: number, heap: HeapItem<T>[], compare: CompareFn<T>): number;
+export { defaultCompare, getLeftChildIndex, getParentIndex, getRightChildIndex, updateSmallestIndex };

package/dist/shared/priority-queue/utils.js

@@ -0,0 +1 @@
+import{logger as e}from"../logger/index.js";import{getType as t}from"../utils/index.js";let r=new Set(["number","string","date"]);function n(n,i){return r.has(t(n))&&r.has(t(i))?n<i?-1:+(n>i):(e.warn("PriorityQueue",`Unsupported type: ${t(n)} ${t(i)}`),0)}function i(e){return Math.floor((e-1)/2)}function u(e){return 2*e+1}function o(e){return 2*e+2}function d(e,t,r,n,i){if(e>=r)return t;let u=i(n[e].item,n[t].item);return u<0||0===u&&n[e].insertOrder<n[t].insertOrder?e:t}export{n as defaultCompare,u as getLeftChildIndex,i as getParentIndex,o as getRightChildIndex,d as updateSmallestIndex};

package/dist/shared/throw-error/index.d.ts

@@ -1,3 +1,11 @@
-export declare function createError(fnName: string, message: string, ErrorClass?: ErrorConstructor): Error;
-export declare function throwError(fnName: string, message: string, ErrorClass?: ErrorConstructor): never;
-export declare function throwType(fnName: string, message: string): never;
+interface ErrorOptions {
+    /** 原始错误（ES2022 Error.cause），便于错误链追踪 */
+    cause?: unknown;
+}
+declare function createError(fnName: string, message: string, ErrorClass?: ErrorConstructor, options?: ErrorOptions): Error;
+declare function createError(fnName: string, message: string, options?: ErrorOptions): Error;
+declare function throwError(fnName: string, message: string, ErrorClass?: ErrorConstructor, options?: ErrorOptions): never;
+declare function throwError(fnName: string, message: string, options?: ErrorOptions): never;
+declare function throwType(fnName: string, message: string, options?: ErrorOptions): never;
+export type { ErrorOptions };
+export { createError, throwError, throwType };

package/dist/shared/throw-error/index.js

@@ -1,10 +1 @@
-function createError(fnName, message, ErrorClass = Error) {
-    return new ErrorClass(`[@cmtlyt/lingshu-toolkit#${fnName}]: ${message}`);
-}
-function throwError(fnName, message, ErrorClass = Error) {
-    throw createError(fnName, message, ErrorClass);
-}
-function throwType(fnName, message) {
-    throwError(fnName, message, TypeError);
-}
-export { createError, throwError, throwType };
+function r(o,t,e=Error,n){let c="function"==typeof e,u=c?e:Error,i=c?n:e,E=`[@cmtlyt/lingshu-toolkit#${o}]: ${t}`;return i&&"cause"in i?new u(E,{cause:i.cause}):new u(E)}function o(t,e,n=Error,c){throw r(t,e,n,c)}function t(r,t,e){o(r,t,TypeError,e)}export{r as createError,o as throwError,t as throwType};

package/dist/shared/try-call/index.d.ts

@@ -9,7 +9,7 @@ type TryCallFinalArgs<R, E> = TryCallResultValue<R, E> | Error;
  * @param cb 回调函数
  * @param onError 错误处理函数
  */
-export declare function tryCallFunc<A extends any[], R, E = never>(cb: (...args: A) => R, onError?: ((err: any) => E) | null, onFinal?: (result: TryCallFinalArgs<R, E>) => void): (...args: A) => TryCallResult<R, E>;
+declare function tryCallFunc<A extends any[], R, E = never>(cb: (...args: A) => R, onError?: ((err: any) => E) | null, onFinal?: (result: TryCallFinalArgs<R, E>) => void): (...args: A) => TryCallResult<R, E>;
 /**
  * 尝试调用函数
  *
@@ -18,5 +18,5 @@ export declare function tryCallFunc<A extends any[], R, E = never>(cb: (...args:
  * @param cb 回调函数
  * @param onError 错误处理函数
  */
-export declare function tryCall<R, E = never>(this: any, cb: () => R, onError?: ((err: any) => E) | null, onFinal?: (result: TryCallFinalArgs<R, E>) => void): TryCallResult<R, E>;
-export {};
+declare function tryCall<R, E = never>(this: any, cb: () => R, onError?: ((err: any) => E) | null, onFinal?: (result: TryCallFinalArgs<R, E>) => void): TryCallResult<R, E>;
+export { tryCall, tryCallFunc };

package/dist/shared/try-call/index.js

@@ -1,59 +1 @@
-import { throwType } from "../throw-error/index.js";
-import { isFunction, isPromiseLike } from "../utils/verify.js";
-const EMPTY = Symbol('EMPTY');
-function tryCallFunc(cb, onError, onFinal) {
-    if (!isFunction(cb)) throwType('tryCallFunc', 'callback is not a function');
-    const catchFn = (self, ctx, error)=>{
-        if (isFunction(onError)) try {
-            ctx.errorResult = Reflect.apply(onError, self, [
-                error
-            ]);
-        } catch (err) {
-            ctx.error = err;
-        }
-        else ctx.error = error;
-        return ctx.errorResult;
-    };
-    const finallyFn = (self, ctx, result)=>{
-        try {
-            if (ctx.error !== EMPTY) throw ctx.error;
-        } finally{
-            if (isFunction(onFinal)) if (ctx.errorResult !== EMPTY) Reflect.apply(onFinal, self, [
-                ctx.errorResult
-            ]);
-            else if (ctx.error !== EMPTY) Reflect.apply(onFinal, self, [
-                ctx.error
-            ]);
-            else Reflect.apply(onFinal, self, [
-                result
-            ]);
-        }
-    };
-    return function(...args) {
-        const ctx = {
-            oriResult: EMPTY,
-            errorResult: EMPTY,
-            error: EMPTY
-        };
-        const asyncFn = async ()=>{
-            try {
-                ctx.oriResult = Reflect.apply(cb, this, args);
-                return ctx.oriResult;
-            } catch (error) {
-                return catchFn(this, ctx, error);
-            }
-        };
-        const fnPromise = asyncFn().catch((error)=>catchFn(this, ctx, error));
-        if (isPromiseLike(ctx.oriResult)) return fnPromise.then((result)=>{
-            finallyFn(this, ctx, result);
-            return result;
-        });
-        finallyFn(this, ctx, ctx.oriResult);
-        return ctx.oriResult !== EMPTY ? ctx.oriResult : ctx.errorResult;
-    };
-}
-function tryCall(cb, onError, onFinal) {
-    if (!isFunction(cb)) throwType('tryCall', 'callback is not a function');
-    return tryCallFunc(cb, onError, onFinal).call(this);
-}
-export { tryCall, tryCallFunc };
+import{throwType as r}from"../throw-error/index.js";import{isFunction as t,isPromiseLike as e}from"../utils/verify.js";let l=Symbol("EMPTY");function o(o,i,n){t(o)||r("tryCallFunc","callback is not a function");let u=(r,e,l)=>{if(t(i))try{e.errorResult=Reflect.apply(i,r,[l])}catch(r){e.error=r}else e.error=l;return e.errorResult},s=(r,e,o)=>{try{if(e.error!==l)throw e.error}finally{t(n)&&Reflect.apply(n,r,e.error===l?[o]:[e.error])}};return function(...r){let t={oriResult:l,errorResult:l,error:l},i=(async()=>{try{return t.oriResult=Reflect.apply(o,this,r),t.oriResult}catch(r){return u(this,t,r)}})().catch(r=>u(this,t,r));if(e(t.oriResult))return i.then(r=>(s(this,t,r),r));let n=t.oriResult===l?t.errorResult:t.oriResult;return s(this,t,n),n}}function i(e,l,i){return t(e)||r("tryCall","callback is not a function"),o(e,l,i).call(this)}export{i as tryCall,o as tryCallFunc};

package/dist/shared/types/index.js

@@ -1,2 +1 @@
-export * from "./base.js";
-export * from "./pack.js";
+export*from"./base.js";export*from"./pack.js";

package/dist/shared/types/pack.d.ts

@@ -1,7 +1,7 @@
 declare const __PACK__: unique symbol;
-export type Pack<T> = {
+export interface Pack<T> {
     [__PACK__]: T;
-};
+}
 export type Unpack<T extends Pack<any>> = T extends Pack<infer U> ? U : never;
 export type SafeUnpack<T> = T extends Pack<infer U> ? U : T;
 export type IsPack<T> = Pack<any> extends T ? true : false;