@cmtlyt/lingshu-toolkit 0.6.0 → 0.7.0

package/dist/shared/lock-data/errors/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * lock-data 错误类型的 barrel 导出
+ *
+ * 每个错误类拆分为独立文件，以遵循 biome 的 `noExcessiveClassesPerFile` 规则；
+ * 此文件仅做聚合导出，方便内部模块统一 import
+ */
+export { InvalidOptionsError } from './invalid-options-error';
+export { LockAbortedError } from './lock-aborted-error';
+export { LockDisposedError } from './lock-disposed-error';
+export { LockRevokedError } from './lock-revoked-error';
+export { LockTimeoutError } from './lock-timeout-error';
+export { ReadonlyMutationError } from './readonly-mutation-error';

package/dist/shared/lock-data/errors/index.js

@@ -0,0 +1 @@
+export{InvalidOptionsError}from"./invalid-options-error.js";export{LockAbortedError}from"./lock-aborted-error.js";export{LockDisposedError}from"./lock-disposed-error.js";export{LockRevokedError}from"./lock-revoked-error.js";export{LockTimeoutError}from"./lock-timeout-error.js";export{ReadonlyMutationError}from"./readonly-mutation-error.js";

package/dist/shared/lock-data/errors/invalid-options-error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `options` 不合法时抛出（如 `timeout < 0`、未知的 `syncMode` 等）
+ *
+ * 归类为 TypeError 的原因：这是调用方传参问题，而非运行时故障，
+ * 与 JavaScript 原生对非法 API 用法抛 TypeError 的惯例对齐
+ * 对应 RFC.md「错误类型」章节
+ */
+declare class InvalidOptionsError extends TypeError {
+    constructor(message?: string);
+}
+export { InvalidOptionsError };

package/dist/shared/lock-data/errors/invalid-options-error.js

@@ -0,0 +1 @@
+class r extends TypeError{constructor(r){super(r),this.name="InvalidOptionsError"}}export{r as InvalidOptionsError};

package/dist/shared/lock-data/errors/lock-aborted-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `ActionCallOptions.signal` 在 acquiring / holding 阶段 abort 时抛出
+ *
+ * 与 `LockDisposedError` 区分：本错误仅影响当前调用，actions 实例仍可继续使用
+ * 对应 RFC.md「错误类型」章节
+ */
+declare class LockAbortedError extends Error {
+    constructor(message?: string);
+}
+export { LockAbortedError };

package/dist/shared/lock-data/errors/lock-aborted-error.js

@@ -0,0 +1 @@
+class r extends Error{constructor(r){super(r),this.name="LockAbortedError"}}export{r as LockAbortedError};

package/dist/shared/lock-data/errors/lock-disposed-error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 调用方在 actions 已 `dispose()` 后继续使用时抛出
+ *
+ * 同时覆盖：
+ * - `options.signal.aborted` 后任意调用
+ * - `options.getValue` Promise reject 后共享同一 Entry 的任意调用
+ *   （此时错误 `cause` 字段携带原始 reject 原因）
+ *
+ * 对应 RFC.md「错误类型」章节
+ */
+declare class LockDisposedError extends Error {
+    constructor(message?: string, options?: ErrorOptions);
+}
+export { LockDisposedError };

package/dist/shared/lock-data/errors/lock-disposed-error.js

@@ -0,0 +1 @@
+class r extends Error{constructor(r,o){super(r,o),this.name="LockDisposedError"}}export{r as LockDisposedError};

package/dist/shared/lock-data/errors/lock-revoked-error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 持有锁期间被 `force` 抢占或 `holdTimeout` 触发时抛出
+ *
+ * 持有者后续对 draft 的写入也会继续抛出此错误，防止闭包泄露导致写入无效
+ * 对应 RFC.md「错误类型」章节
+ */
+declare class LockRevokedError extends Error {
+    constructor(message?: string);
+}
+export { LockRevokedError };

package/dist/shared/lock-data/errors/lock-revoked-error.js

@@ -0,0 +1 @@
+class r extends Error{constructor(r){super(r),this.name="LockRevokedError"}}export{r as LockRevokedError};

package/dist/shared/lock-data/errors/lock-timeout-error.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 超过 `timeout` / `acquireTimeout` 仍未获得锁时抛出
+ *
+ * 对应 RFC.md「错误类型」章节
+ */
+declare class LockTimeoutError extends Error {
+    constructor(message?: string);
+}
+export { LockTimeoutError };

package/dist/shared/lock-data/errors/lock-timeout-error.js

@@ -0,0 +1 @@
+class r extends Error{constructor(r){super(r),this.name="LockTimeoutError"}}export{r as LockTimeoutError};

package/dist/shared/lock-data/errors/readonly-mutation-error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 直接修改 `readonly` 视图时抛出
+ *
+ * 归类为 TypeError 的原因：与原生对 frozen 对象写入时的规范语义对齐，
+ * 便于业务代码用同一种 catch 分支处理"写入被阻止"类错误
+ * 对应 RFC.md「错误类型」章节
+ */
+declare class ReadonlyMutationError extends TypeError {
+    constructor(message?: string);
+}
+export { ReadonlyMutationError };

package/dist/shared/lock-data/errors/readonly-mutation-error.js

@@ -0,0 +1 @@
+class r extends TypeError{constructor(r){super(r),this.name="ReadonlyMutationError"}}export{r as ReadonlyMutationError};

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

@@ -0,0 +1,57 @@
+import type { LockDataOptions, LockDataReturn, LockDataValueShape } from './types';
+/**
+ * 创建一个带锁的数据容器（**单参数 API + getValue 必传 + 条件类型自动推断返回值**）
+ *
+ * 单签名 + 严格条件类型契约（对应 RFC.md「§3 核心语义 / §API 签名」+ 决策 #33 §A）：
+ * - `getValue: () => T | Promise<T>` 必传 —— 数据来源唯一入口
+ * - `T` 必须满足 `LockDataValueShape<T> = T extends readonly unknown[] ? never : T`，
+ *   即 **类型层禁止顶层数组**（`lockData<string[]>` 在类型层即被排除为 `never`）
+ * - **返回值类型由 `LockDataReturn<T, O>` 条件类型从入参 `O` 直接推断**，无需调用方断言：
+ *   1. `O extends { syncMode: 'storage-authority' }` → 必须配 `id: string`，否则编译期 `never`（最严格）
+ *   2. 否则若 `ReturnType<O['getValue']> extends Promise<unknown>` → `Promise<LockDataTuple<T>>`
+ *   3. 否则 → `LockDataTuple<T>`
+ * - 同步抛错 → 同步抛 `LockDisposedError`（Entry 不构造）
+ * - 异步 reject → 返回的 Promise reject `LockDisposedError`，`cause` 字段携带原因
+ * - 运行时双重 fail-fast：`Array.isArray(awaited)` 拒绝顶层数组（抛 `InvalidOptionsError`），
+ *   非 JSON-safe 抛 `InvalidOptionsError`
+ *
+ * 返回元组：
+ * - 第一个元素：深只读视图（`ReadonlyView<T>`，wrapper Proxy 实现），业务只能读取不能直接写入
+ * - 第二个元素：actions（`update` / `replace` / `snapshot` / `dispose` 等），通过事务 API 修改数据
+ *
+ * ### 同步初始化（直接得元组，无需 await / 断言）
+ *
+ * ```ts
+ * const [view, actions] = lockData<{ count: number }>({
+ *   getValue: () => ({ count: 0 }),
+ * });
+ * view.count; // 0
+ * await actions.update((draft) => { draft.count = 1; });
+ * ```
+ *
+ * ### 异步初始化（getValue 返回 Promise → 类型自动收窄为 Promise<LockDataTuple<T>>）
+ *
+ * ```ts
+ * const [view, actions] = await lockData<User>({
+ *   getValue: () => fetch('/api/user').then((r) => r.json()),
+ * });
+ * ```
+ *
+ * ### 跨 Tab 同步（syncMode='storage-authority' 必须配 id，否则编译期报错）
+ *
+ * ```ts
+ * const [view, actions] = await lockData<{ count: number }>({
+ *   id: 'shared-counter',
+ *   syncMode: 'storage-authority',
+ *   getValue: () => ({ count: 0 }),
+ * });
+ * ```
+ */
+type LockDataInfer<O> = O extends {
+    getValue: () => infer R;
+} ? Awaited<R> extends infer T extends object ? T : never : never;
+type LockDataResolveReturn<O extends object> = LockDataValueShape<LockDataInfer<O>> extends infer T extends object ? LockDataReturn<T, O> : never;
+declare function lockData<const O extends LockDataOptions<unknown>>(options: O): LockDataResolveReturn<O>;
+export { NEVER_TIMEOUT } from './constants';
+export { InvalidOptionsError, LockAbortedError, LockDisposedError, LockRevokedError, LockTimeoutError, ReadonlyMutationError, } from './errors';
+export { lockData };

package/dist/shared/lock-data/index.js

@@ -0,0 +1 @@
+import{lockData as r}from"./core/entry.js";function o(o){let t=r(o);return t instanceof Promise,t}export{NEVER_TIMEOUT}from"./constants.js";export{InvalidOptionsError,LockAbortedError,LockDisposedError,LockRevokedError,LockTimeoutError,ReadonlyMutationError}from"./errors/index.js";export{o as lockData};

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/throw-error/index.d.ts

@@ -1,4 +1,11 @@
-declare function createError(fnName: string, message: string, ErrorClass?: ErrorConstructor): Error;
-declare function throwError(fnName: string, message: string, ErrorClass?: ErrorConstructor): never;
-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 +1 @@
-function r(o,t,n=Error){return new n(`[@cmtlyt/lingshu-toolkit#${o}]: ${t}`)}function o(t,n,e=Error){throw r(t,n,e)}function t(r,t){o(r,t,TypeError)}export{r as createError,o as throwError,t as 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmtlyt/lingshu-toolkit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/shared.js",
   "module": "./dist/shared.js",
@@ -41,7 +41,7 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.11",
-    "@cmtlyt/unplugin-shadcn-registry-generate": "^0.1.5",
+    "@cmtlyt/unplugin-shadcn-registry-generate": "^0.1.6",
     "@commitlint/cli": "^20.5.0",
     "@commitlint/config-conventional": "^20.5.0",
     "@rslib/core": "^0.21.0",