@cmtlyt/lingshu-toolkit 0.5.0 → 0.7.0

package/dist/shared/lock-data/drivers/storage.d.ts

@@ -0,0 +1,71 @@
+/**
+ * StorageDriver：基于 localStorage 的跨 Tab 互斥锁
+ *
+ * 适用场景（由 pickDriver 决定）：
+ * - 浏览器环境但既不支持 `navigator.locks`，也不支持 `BroadcastChannel`
+ * - 显式 `mode='storage'` 强制指定
+ *
+ * 本文件是工厂聚合层：
+ * - 前置依赖校验（id 必传 / localStorage 可用）
+ * - 构造 state 容器 + 订阅 storage 事件 + 启动 polling
+ * - 暴露 acquire / destroy
+ *
+ * 协议细节、状态机、CAS 读写、队列操作、drain 逻辑分别放在：
+ * - `./storage-protocol`：存储格式 + 常量 + 校验 + nonce 生成
+ * - `./storage-state`：状态机 + CAS 读写 + 队列 + 心跳 + drain
+ */
+import type { LockDriverContext, LockDriverHandle } from '../types';
+import { type StorageDriverState, type Waiter } from './storage-state';
+import type { LockDriver, LockDriverDeps } from './types';
+/**
+ * 能力探测：localStorage 是否可实际读写
+ *
+ * 与 adapters/authority 的探测同构；pickDriver 已做一次但保留防御性兜底，
+ * 覆盖单元测试直接实例化的场景
+ */
+declare function hasUsableLocalStorage(): boolean;
+/**
+ * 构造 waiter 并绑定 signal / timeout 的 abort 生命周期
+ *
+ * 与 broadcast driver 的 buildWaiter 同构；主要差异：
+ * - 没有 pendingAnnounce / pendingForce 分支（storage driver 的抢锁是 CAS 直接决断，
+ *   没有"进行中的竞选"需要清理）
+ * - abort 时需要 removeWaiter + pumpNextWaiter，让下一个 waiter 继续抢
+ */
+declare function buildWaiter(ctx: LockDriverContext, state: StorageDriverState, resolve: (handle: LockDriverHandle) => void, reject: (error: Error) => void): Waiter;
+/**
+ * force 路径的专用入队 + 抢锁流程
+ *
+ * force 不走 FIFO 队列 —— 直接 CAS 覆盖 holder；成功即进入 holding，失败交由 abort 处理
+ */
+declare function acquireForceLock(state: StorageDriverState, waiter: Waiter): void;
+/**
+ * 快路径抢锁成功时的后处理
+ *
+ * 把 `acquireNonForceLock` 的快路径 `.then` 回调拆出为独立函数，
+ * 降低外层函数圈复杂度；职责不变 —— 根据 destroyed / settled / status 决定：
+ *   - 直接授予 handle
+ *   - 释放刚抢到的锁并 abort waiter
+ *   - 释放刚抢到的锁并降级到慢路径入队
+ */
+declare function handleFastPathGrant(state: StorageDriverState, waiter: Waiter, grantNonce: string): void;
+/**
+ * 非 force 路径的抢锁流程
+ *
+ * 1. 快路径：本地 idle + 无其他 waiter + storage 可直接抢 → tryAcquire 一次，成功即返回
+ * 2. 慢路径：入 storage 队列 + 本地队列 → 等 pumpNextWaiter（由 storage 事件 / polling / release 触发）
+ */
+declare function acquireNonForceLock(state: StorageDriverState, waiter: Waiter): void;
+/**
+ * 把 waiter 加入 storage 队列 + 本地队列
+ *
+ * storage 入队失败（quota / 写冲突重试耗尽）不阻塞 —— 让 waiter 本地排队等 polling / heartbeat
+ * 超时触发 pump；最坏情况下会触发 acquireTimeout
+ */
+declare function enqueueSlowPath(state: StorageDriverState, waiter: Waiter): void;
+declare function acquireStorageLock(state: StorageDriverState, ctx: LockDriverContext): Promise<LockDriverHandle>;
+/**
+ * 创建 StorageDriver 实例
+ */
+declare function createStorageDriver(deps: LockDriverDeps): LockDriver;
+export { acquireForceLock, acquireNonForceLock, acquireStorageLock, buildWaiter, createStorageDriver, enqueueSlowPath, handleFastPathGrant, hasUsableLocalStorage, };

package/dist/shared/lock-data/drivers/storage.js

@@ -0,0 +1 @@
+import{throwError as e}from"../../throw-error/index.js";import{isNumber as t,isString as r}from"../../utils/index.js";import{ERROR_FN_NAME as o,LOCK_PREFIX as n}from"../constants.js";import{LockAbortedError as i,LockTimeoutError as s}from"../errors/index.js";import{canFastAcquire as a,drainOnDestroy as l,enqueueInStorage as u,enterHolding as d,pumpNextWaiter as c,releaseHolderInStorage as k,removeWaiter as g,revokeHolding as f,startPolling as m,subscribeStorageEvent as $,tryAcquire as v}from"./storage-state.js";function b(){try{let e=globalThis.localStorage;if(!e)return!1;let t=`${n}:__storage_driver_probe__`;return e.setItem(t,"1"),e.removeItem(t),!0}catch{return!1}}function h(e,r,n,a){let l=!1,u=null;function d(){null!==u&&(clearTimeout(u),u=null),e.signal.removeEventListener("abort",f)}let k={token:e.token,resolve:e=>{l||(l=!0,d(),n(e))},reject:e=>{l||(l=!0,d(),a(e))},abort:e=>{l||(g(r.waiters,k),k.reject(e),c(r))},isSettled:()=>l};function f(){k.abort(new i(`[@cmtlyt/lingshu-toolkit#${o}]: acquire aborted (token=${e.token})`))}if(e.signal.aborted)return queueMicrotask(()=>f()),k;if(e.signal.addEventListener("abort",f,{once:!0}),t(e.acquireTimeout)&&e.acquireTimeout>0){let t=e.acquireTimeout;u=setTimeout(()=>{k.abort(new s(`[@cmtlyt/lingshu-toolkit#${o}]: acquire timed out after ${t}ms (token=${e.token})`))},t)}return k}function y(e,t){let{name:r,logger:n}=e.deps;v(e,t.token,!0).then(s=>{if(null===s)return void t.abort(new i(`[@cmtlyt/lingshu-toolkit#${o}]: force acquire failed after retries (token=${t.token})`));if(e.destroyed){k(e,t.token,s.nonce),t.abort(new i(`[@cmtlyt/lingshu-toolkit#${o}]: storage driver destroyed during force acquire (token=${t.token})`));return}if(t.isSettled())return void k(e,t.token,s.nonce);"holding"!==e.status.kind||e.status.released||f(e,"force");let a=d(e,t.token,s.nonce);n.debug(`[${r}] storage driver: grant (force) token=${t.token}`),t.resolve(a)})}function p(e,t,r){let{name:n,logger:s}=e.deps;if(e.destroyed){k(e,t.token,r),t.abort(new i(`[@cmtlyt/lingshu-toolkit#${o}]: storage driver destroyed during fast acquire (token=${t.token})`));return}if(t.isSettled())return void k(e,t.token,r);if("idle"!==e.status.kind){k(e,t.token,r),w(e,t);return}let a=d(e,t.token,r);s.debug(`[${n}] storage driver: grant (fast-path) token=${t.token}`),t.resolve(a)}function q(e,t){a(e)?v(e,t.token,!1).then(r=>{null!==r?p(e,t,r.nonce):t.isSettled()||w(e,t)}):w(e,t)}function w(e,t){let{name:r,logger:o}=e.deps;e.waiters.push(t),o.debug(`[${r}] storage driver: enqueue token=${t.token}, queue=${e.waiters.length}`),u(e,t.token).then(n=>{n||o.warn(`[${r}] storage driver: enqueueInStorage failed after retries (token=${t.token}); relying on timeout/polling`),c(e)})}function S(e,t){return e.destroyed?Promise.reject(new i(`[@cmtlyt/lingshu-toolkit#${o}]: storage driver has been destroyed (token=${t.token})`)):new Promise((r,o)=>{let n=h(t,e,r,o);t.force?y(e,n):q(e,n)})}function T(t){let{id:s}=t;r(s)&&0!==s.length||e(o,"storage driver requires a non-empty id",TypeError),b()||e(o,"storage driver requires a usable localStorage",TypeError);let a={deps:t,storage:globalThis.localStorage,key:`${n}:${s}:driver-lock`,status:{kind:"idle"},waiters:[],destroyed:!1,pumping:!1,unsubscribeStorageEvent:null,pollTimer:null};function u(e){return new i(`[@cmtlyt/lingshu-toolkit#${o}]: storage driver destroyed (token=${e})`)}return a.unsubscribeStorageEvent=$(a),a.pollTimer=m(a),{acquire:e=>S(a,e),destroy:()=>{a.destroyed||(a.destroyed=!0,l(a,u))}}}export{y as acquireForceLock,q as acquireNonForceLock,S as acquireStorageLock,h as buildWaiter,T as createStorageDriver,w as enqueueSlowPath,p as handleFastPathGrant,b as hasUsableLocalStorage};

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

@@ -0,0 +1,73 @@
+/**
+ * drivers 层的内部类型契约
+ *
+ * 对应 RFC.md「架构分层」与「能力检测与降级」章节：
+ * - `LockDriver`：drivers 层统一抽象；Entry 持有 driver，所有 action 走 `driver.acquire`
+ *   拿到一个 `LockHandle`；driver 是**按 id 进程内单例**的（由 InstanceRegistry 持有）
+ * - `LockHandle`（已在 `../types` 中以 `LockDriverHandle` 名义向用户暴露）：单次持有
+ *   的生命周期对象，`release` 还锁、`onRevokedByDriver` 桥接驱逐事件
+ * - `LockDriverDeps`：driver 构造依赖；不同 driver 子集不同，工厂函数签名统一
+ *
+ * 本文件仅导出**内部类型**，不对外 re-export。
+ */
+import type { ResolvedLoggerAdapter } from '../adapters/logger';
+import type { ChannelAdapter, ChannelAdapterContext, LockDataAdapters, LockDriverContext, LockDriverHandle } from '../types';
+/**
+ * driver 构造依赖；由 `pickDriver` 从 `entry.adapters` 中分拣后传入
+ *
+ * 字段设计原则：
+ * - `logger` 对所有 driver 必传；driver 内部统一用此 logger 输出 warn / error / debug
+ * - `name` 已是拼好 `${LOCK_PREFIX}:${id}` 的完整锁作用域名；driver 无需关心前缀规则
+ * - `getChannel` 仅 `BroadcastDriver` 需要；其他 driver 允许为 undefined
+ * - `userGetLock` 仅 `CustomDriver` 需要；其他 driver 为 undefined
+ *
+ * **关于 `userGetLock` 的 `unknown` 泛型**：
+ * `LockDataAdapters<T>` 的泛型参数 `_T` 在 `getLock` 签名中并不出现（getLock
+ * 只接触锁调度上下文，不接触数据类型）；此处用 `unknown` 表示"本 driver 层对
+ * 数据类型不可见"，等价于 `LockDataAdapters<any>['getLock']` 但无 any 污染
+ */
+interface LockDriverDeps {
+    /** 已拼前缀的锁作用域名 `${LOCK_PREFIX}:${id}`；无 id 场景下为 `${LOCK_PREFIX}:__local__` 占位 */
+    readonly name: string;
+    /** lockData 的原始 id；CustomDriver / 日志输出时需要（未 scope 化） */
+    readonly id: string | undefined;
+    /** Resolved logger（三方法齐全，下游可直接调用无需 guard） */
+    readonly logger: ResolvedLoggerAdapter;
+    /** 工厂：提供广播通道（仅 BroadcastDriver 消费） */
+    readonly getChannel?: (ctx: ChannelAdapterContext) => ChannelAdapter | null;
+    /** 用户注入的自定义 `adapters.getLock`（仅 CustomDriver 消费） */
+    readonly userGetLock?: LockDataAdapters<unknown>['getLock'];
+}
+/**
+ * 锁驱动统一抽象
+ *
+ * 所有 driver 实现均为"进程内 + id 作用域"单例；由 InstanceRegistry 首次创建
+ * Entry 时构造一次，Entry 销毁时调用 `destroy()` 清理内部长生命周期资源
+ * （心跳定时器、订阅、BroadcastChannel 实例等）
+ *
+ * 并发语义：
+ * - `acquire` 可被同一 driver 实例并发调用（例如同进程内两个 lockData 实例，均指向
+ *   同一 id），driver 内部负责**串行化**（FIFO 排队 / WebLocks 原生排队 / token 协议）
+ * - `force: true` 的 `acquire` 会让当前持有者的 `LockHandle.onRevokedByDriver` 以
+ *   `'force'` 回调并立即释放；当前持有者后续 `release` 仍需可调用（幂等 no-op）
+ * - `acquireTimeout` 在 `acquire` 内部处理；到期抛 `LockTimeoutError`
+ * - `signal.aborted`（acquiring 阶段）抛 `LockAbortedError`
+ */
+interface LockDriver {
+    /**
+     * 抢锁；返回一个单次持有的 `LockHandle`
+     *
+     * 抛错语义：
+     * - `LockTimeoutError`：acquireTimeout 到期
+     * - `LockAbortedError`：ctx.signal aborted / driver 已 destroy
+     * - 其他错误：driver 内部故障（logger.error 后原样透传）
+     */
+    readonly acquire: (ctx: LockDriverContext) => Promise<LockDriverHandle>;
+    /**
+     * Entry 引用计数归零 / dispose 时调用；清理 driver 内部长生命周期资源
+     *
+     * 幂等：重复调用 no-op；`destroy` 后再次 `acquire` 必抛 `LockAbortedError`
+     */
+    readonly destroy: () => void;
+}
+export type { LockDriver, LockDriverDeps };

package/dist/shared/lock-data/drivers/web-locks.d.ts

@@ -0,0 +1,123 @@
+/**
+ * WebLocksDriver：基于 `navigator.locks` 的跨 Tab 互斥锁实现（首选 driver）
+ *
+ * 适用场景（由 pickDriver 决定）：
+ * - `mode === 'auto'` 且运行时检测到 `navigator.locks`（现代浏览器 / Chromium 内核环境）
+ * - `mode === 'web-locks'` 强制指定
+ *
+ * 实现要点（对应 RFC.md「WebLocksDriver（首选）」）：
+ * - 核心 API：`navigator.locks.request(name, { mode: 'exclusive', steal, signal }, callback)`
+ * - `callback` 持锁期间必须返回一个 Promise；锁会一直持有直到该 Promise settle
+ *   → 这里构造一个外部可 resolve 的 `holdPromise`，`LockHandle.release` 就是 resolve 它
+ * - `force: true` → `steal: true`；原持有者的 callback 会以 `AbortError` reject，
+ *   捕获后把原 handle 的 `onRevokedByDriver('force')` 触发
+ * - `acquireTimeout` → `AbortController.abort()`；`navigator.locks.request` 会 reject
+ *   `AbortError`（注意需要与 steal 场景区分：本 handle 还没拿到锁就 abort，而非被抢）
+ * - `signal.aborted`（外部 signal）同 `acquireTimeout` 通过合并 AbortController 统一处理
+ * - `destroy`：对所有仍持有锁的 handle 调用 release；等待中的 acquire 由各自的 signal
+ *   负责清理（destroy 会广播 abort 给内部 controller）
+ *
+ * 与其他 driver 的关键差异：
+ * - 互斥语义由浏览器保证（跨 Tab），无需自研排队协议
+ * - `release` 是**同步**触发（resolve holdPromise），但底层 navigator.locks 的清理
+ *   是微任务队列，所以上层看到的 release Promise 下一轮 tick 才 settle
+ */
+import type { LockDriverContext } from '../types';
+import type { LockDriver, LockDriverDeps } from './types';
+/**
+ * Web Locks API 的最小化类型定义
+ *
+ * 为什么不直接用 `lib.dom` 内置 types：
+ * - TypeScript 4.x / 早期 5.x 的 lib.dom 对 `LockManager` 的定义不完整
+ *   （缺 `steal` / `ifAvailable` 字段）；本地定义保证 strict 下可编译
+ * - 仅声明 driver 内部实际用到的子集，不追求全面
+ */
+interface WebLockRequestOptions {
+    mode?: 'exclusive' | 'shared';
+    ifAvailable?: boolean;
+    steal?: boolean;
+    signal?: AbortSignal;
+}
+interface WebLockManager {
+    readonly request: <T>(name: string, options: WebLockRequestOptions, callback: (lock: unknown) => Promise<T> | T) => Promise<T>;
+}
+/**
+ * 从运行时获取 `navigator.locks`；不存在则返回 null
+ *
+ * 正常路径下 pickDriver 会在选中本 driver 前做能力检测，本函数兜底覆盖两种边缘场景：
+ * 1. 上层绕过 pickDriver 直接实例化本 driver（如单元测试）
+ * 2. 运行时 `navigator` 对象缺失（非浏览器环境 + Node 22+ 的部分运行时）
+ * 返回 null 时由 `createWebLocksDriver` 构造期抛错，不会静默降级
+ */
+declare function getWebLockManager(): WebLockManager | null;
+/**
+ * 内部持有态：一次成功 acquire 产生一条
+ *
+ * - `holdPromise`：callback 期间返回给 navigator.locks 的 Promise；resolve 时锁释放
+ * - `resolveHold`：从外部 resolve holdPromise 的闭包引用，`release` 调用它
+ * - `revokeCallback`：用户（actions 层）通过 `onRevokedByDriver` 注册的回调
+ * - `released`：幂等开关
+ */
+interface WebLockHolding {
+    readonly token: string;
+    readonly holdPromise: Promise<void>;
+    readonly resolveHold: () => void;
+    revokeCallback: ((reason: 'force' | 'timeout') => void) | null;
+    released: boolean;
+}
+/**
+ * 把 `ctx.signal` 与 `acquireTimeout` 合并为单一 AbortSignal 传给 navigator.locks
+ *
+ * 为什么需要合并：
+ * - navigator.locks.request 只接受单个 signal 作为"放弃抢锁"的开关
+ * - 需要同时响应"外部 signal abort"与"acquireTimeout 到期"两条路径
+ * - 用 `AbortController` 手动合并比 `AbortSignal.any` 兼容面更广
+ *
+ * 返回的 cleanup 必须在 `navigator.locks.request` settle 后调用，清理 timer + listener
+ */
+declare function mergeSignalWithTimeout(externalSignal: AbortSignal, acquireTimeout: LockDriverContext['acquireTimeout'], token: string): {
+    signal: AbortSignal;
+    cleanup: () => void;
+    getTimeoutFired: () => boolean;
+};
+/** 判定错误是否属于 navigator.locks abort 类型（DOMException 'AbortError'） */
+declare function isAbortLikeError(error: unknown): boolean;
+/** 顶层辅助函数共享的 driver 级依赖容器 */
+interface DriverScope {
+    readonly holdings: Set<WebLockHolding>;
+    readonly logger: LockDriverDeps['logger'];
+    readonly driverName: string;
+}
+/**
+ * 已拿到锁后被 steal / force 驱逐的处理路径
+ *
+ * W3C 规范：原持有者的 `navigator.locks.request` 返回 Promise 以 AbortError reject；
+ * 必须显式 `resolveHold()` 避免 callback 里的 holdPromise 永远挂起（虽然 navigator.locks
+ * 此时已释放锁，但不 resolve 会造成本地 Promise 泄漏 + 后续 release 的幂等判定失效）
+ *
+ * 提至模块顶层，通过 `scope` 容器传入 driver 级依赖，降低 `createWebLocksDriver` 的
+ * linesPerFunction（biome noExcessiveLinesPerFunction = 100）
+ */
+declare function handleStealRejection(seized: WebLockHolding, scope: DriverScope): void;
+/**
+ * 处理 navigator.locks.request 的 settle —— 分三种情况：
+ *   1. resolve 路径（正常 release）→ 兜底清理 holding
+ *   2. reject + 已持有 → steal 路径，触发 onRevokedByDriver('force')
+ *   3. reject + 未持有 → 未拿到锁就被 abort / 非法参数等，把错误传给 acquire 入口
+ */
+declare function wireRequestSettle(requestPromise: Promise<unknown>, getHolding: () => WebLockHolding | null, rejectGranted: (error: unknown) => void, scope: DriverScope): void;
+declare function createWebLocksDriver(deps: LockDriverDeps): LockDriver;
+/**
+ * destroy 时排空 holdings：把所有未 released 的 holding 同步释放
+ *
+ * 提至模块顶层的原因：
+ * - `holding.released === true` 的 false 分支在正常运行路径下不可达（release/handleStealRejection
+ *   都同步从 holdings 删除 + 置 released=true），属于防御性死代码
+ * - 抽出顶层后允许测试直接构造混合 holdings 集合（含已 released 的元素），命中防御分支
+ *
+ * 复制一份再遍历，避免 resolveHold 触发的副作用修改 `holdings`
+ * 用 Array.from + for 循环代替 forEach —— biome.useIterableCallbackReturn 禁止 forEach 回调有返回值
+ */
+declare function drainHoldingsOnDestroy(holdings: Set<WebLockHolding>): void;
+export type { DriverScope, WebLockHolding, WebLockManager };
+export { createWebLocksDriver, drainHoldingsOnDestroy, getWebLockManager, handleStealRejection, isAbortLikeError, mergeSignalWithTimeout, wireRequestSettle, };

package/dist/shared/lock-data/drivers/web-locks.js

@@ -0,0 +1 @@
+import{throwError as e}from"../../throw-error/index.js";import{isFunction as r,isNumber as t,isObject as o}from"../../utils/index.js";import{withResolvers as l}from"../../with-resolvers/index.js";import{ERROR_FN_NAME as n}from"../constants.js";import{LockAbortedError as i,LockTimeoutError as a}from"../errors/index.js";function s(){if("u"<typeof navigator)return null;let{locks:e}=navigator;return e||null}function d(e,r,o){let l=new AbortController,i=!1,s=null;if(e.aborted)return l.abort(e.reason),{signal:l.signal,cleanup:()=>void 0,getTimeoutFired:()=>i};function d(){l.abort(e.reason)}return e.addEventListener("abort",d,{once:!0}),t(r)&&r>0&&(s=setTimeout(()=>{i=!0,l.abort(new a(`[@cmtlyt/lingshu-toolkit#${n}]: acquire timed out after ${r}ms (token=${o})`))},r)),{signal:l.signal,cleanup:function(){null!==s&&(clearTimeout(s),s=null),e.removeEventListener("abort",d)},getTimeoutFired:()=>i}}function u(e){if(!o(e))return!1;let{name:r}=e;return"AbortError"===r}function c(e,t){if(e.released)return;let{holdings:o,logger:l,driverName:n}=t;if(e.released=!0,o.delete(e),e.resolveHold(),l.debug(`[${n}] web-locks driver: revoked by steal token=${e.token}`),r(e.revokeCallback))try{e.revokeCallback("force")}catch(e){l.error(`[${n}] web-locks driver: revoke callback threw`,e)}}function k(e,r,t,o){let{holdings:l}=o;e.then(()=>{let e=r();e&&!e.released&&(e.released=!0,l.delete(e))}).catch(e=>{let l=r();l?c(l,o):t(e)})}function v(r){let{name:t,logger:o}=r,c=s();c||e(n,"web-locks driver requires navigator.locks; use auto mode or fallback driver",TypeError);let v=new Set,m=!1;return{acquire:async function r(r){m&&e(n,"web-locks driver has been destroyed",i);let{signal:s,cleanup:b,getTimeoutFired:f}=d(r.signal,r.acquireTimeout,r.token),g=l(),$=null,w=l(),h=!0===r.force?{mode:"exclusive",steal:!0}:{mode:"exclusive",signal:s};k(c.request(t,h,()=>($={token:r.token,holdPromise:g.promise,resolveHold:g.resolve,revokeCallback:null,released:!1},v.add($),o.debug(`[${t}] web-locks driver: grant token=${r.token} steal=${!0===r.force}`),w.resolve($),g.promise)),()=>$,w.reject,{holdings:v,logger:o,driverName:t});try{var y;let l=await w.promise;return b(),m&&(l.released=!0,v.delete(l),l.resolveHold(),e(n,`web-locks driver destroyed during acquire (token=${r.token})`,i)),y=l,{release:()=>{y.released||(y.released=!0,v.delete(y),y.resolveHold(),o.debug(`[${t}] web-locks driver: release token=${y.token}`))},onRevokedByDriver:e=>{y.revokeCallback=e}}}catch(l){throw b(),f()&&e(n,`acquire timed out after ${String(r.acquireTimeout)}ms (token=${r.token})`,a,{cause:l}),(u(l)||r.signal.aborted)&&e(n,`acquire aborted (token=${r.token})`,i,{cause:l}),o.error(`[${t}] web-locks driver: request failed (token=${r.token})`,l),l}},destroy:function(){m||(m=!0,o.debug(`[${t}] web-locks driver: destroy (active holdings=${v.size})`),b(v))}}}function b(e){let r=Array.from(e);for(let t=0;t<r.length;t++){let o=r[t];o.released||(o.released=!0,e.delete(o),o.resolveHold())}}export{v as createWebLocksDriver,b as drainHoldingsOnDestroy,s as getWebLockManager,c as handleStealRejection,u as isAbortLikeError,d as mergeSignalWithTimeout,k as wireRequestSettle};

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};