@fast-china/utils 2.1.8 → 2.1.9

package/dist/async/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/async/index.ts"],"sourcesContent":["/** 统一同步返回值与 PromiseLike 返回值的内部回调签名。 */\ntype AsyncCallback<Arguments extends unknown[], Result> = (...arguments_: Arguments) => Result | PromiseLike<Result>;\n\n/** 记录同一防抖批次中每个调用方独立的 Promise 结算函数。 */\ninterface PromiseWaiter<Result> {\n\t/**\n\t * 使用批次失败原因拒绝当前调用方。\n\t * @param reason - `cancel` 提供的原因或共享回调抛出的原始错误。\n\t */\n\treject: (reason?: unknown) => void;\n\t/**\n\t * 使用共享回调结果完成当前调用方，并采用传入 PromiseLike 的最终状态。\n\t * @param value - 当前防抖批次唯一一次回调执行产生的共享结果。\n\t */\n\tresolve: (value: Result | PromiseLike<Result>) => void;\n}\n\n// 浏览器和 Node.js 的计时器普遍以有符号 32 位整数保存延迟；更大的值可能被\n// 静默截断为约 1 ms，因此公共 API 在进入平台计时器前统一拒绝它。\nconst maximumTimerDelay = 2_147_483_647;\n\n/** 可接收取消信号的通用选项。 */\nexport interface AbortOptions {\n\t/** 已取消时立即失败；运行期间取消时停止等待并拒绝 Promise。 */\n\tsignal?: AbortSignal;\n}\n\n/** {@link withTimeout} 的行为选项。 */\nexport interface TimeoutOptions extends AbortOptions {\n\t/** 超时时使用的开发者消息。 */\n\tmessage?: string;\n}\n\n/** 每次重试操作接收的上下文。 */\nexport interface RetryContext {\n\t/** 从 1 开始的当前尝试次数。 */\n\tattempt: number;\n\t/** 调用方提供的取消信号。 */\n\tsignal?: AbortSignal;\n}\n\n/** {@link retry} 的策略选项。 */\nexport interface RetryOptions extends AbortOptions {\n\t/** 最大尝试次数，包含首次调用；默认 `3`。 */\n\tattempts?: number;\n\t/** 首次重试前的等待毫秒数，最大 2,147,483,647；默认 `200`。 */\n\tdelayMs?: number;\n\t/** 每次失败后的退避倍数，必须不小于 1；默认 `2`。 */\n\tfactor?: number;\n\t/** 单次等待上限，最大 2,147,483,647；默认 `30_000` 毫秒。 */\n\tmaxDelayMs?: number;\n\t/**\n\t * 决定当前失败后是否继续下一次尝试；默认重试所有尚未到达上限的错误。\n\t * @param error - 当前操作抛出或拒绝的原始值。\n\t * @param context - 当前尝试次数和调用方取消信号。\n\t * @returns `false` 时立即原样抛出当前错误；支持同步值或 PromiseLike。\n\t */\n\tshouldRetry?: (error: unknown, context: RetryContext) => boolean | PromiseLike<boolean>;\n}\n\n/** {@link mapConcurrent} 的执行选项。 */\nexport interface ConcurrentMapOptions {\n\t/** 已取消时停止调度新任务；已经开始的映射器需要自行响应同一信号。 */\n\tsignal?: AbortSignal;\n}\n\n/** Promise 感知的防抖函数。 */\nexport interface DebouncedFunction<Arguments extends unknown[], Result> {\n\t/**\n\t * 调度一次调用；同一等待窗口内的调用共享最后一组参数对应的结果。\n\t * @param arguments_ - 传给原始回调的参数；后续调用会覆盖尚未执行批次保存的参数。\n\t * @returns 当前批次的独立 Promise，最终与共享回调结果保持相同状态。\n\t */\n\t(...arguments_: Arguments): Promise<Result>;\n\t/**\n\t * 取消尚未执行的批次，并拒绝该批次的所有 Promise。\n\t * @param reason - 可选拒绝原因；省略时使用内部取消错误。\n\t */\n\tcancel: (reason?: unknown) => void;\n\t/**\n\t * 立即执行待处理批次，不创建第二次回调执行。\n\t * @returns 待处理批次的共享执行 Promise；没有批次时返回 `undefined`。\n\t */\n\tflush: () => Promise<Result> | undefined;\n\t/** @returns 当前存在尚未开始的批次时返回 `true`；正在执行但没有等待批次时返回 `false`。 */\n\tpending: () => boolean;\n}\n\n/** Promise 感知的前缘节流函数。 */\nexport interface ThrottledFunction<Arguments extends unknown[], Result> {\n\t/**\n\t * 在空闲时立即调用原始回调；执行期和冷却期内的调用共享首次调用的 Promise。\n\t * @param arguments_ - 仅窗口内首次调用的参数会传给原始回调。\n\t * @returns 当前执行窗口共享的 Promise。\n\t */\n\t(...arguments_: Arguments): Promise<Result>;\n\t/** 提前结束冷却期；已经开始的操作不会被取消，结束前仍禁止并发重入。 */\n\tcancel: () => void;\n\t/** @returns 原始回调正在执行或计时器仍处于冷却期时返回 `true`。 */\n\tpending: () => boolean;\n}\n\n/**\n * 创建符合 Web Platform 约定的取消错误。\n *\n * @param signal - 已进入取消状态的信号；其 `reason` 会保存在错误的 `cause` 中。\n * @returns 名称为 `AbortError` 的新错误实例。\n */\nconst createAbortError = (signal: AbortSignal): Error => {\n\tconst error = new Error(\"操作已取消。\", { cause: signal.reason });\n\terror.name = \"AbortError\";\n\treturn error;\n};\n\n/**\n * 在启动异步工作前同步拒绝已经取消的信号。\n *\n * @param signal - 可选取消信号；省略或尚未取消时不执行操作。\n * @throws `Error` 当信号已经取消，错误名称为 `AbortError`。\n */\nconst throwIfAborted = (signal: AbortSignal | undefined): void => {\n\tif (signal?.aborted) throw createAbortError(signal);\n};\n\n/**\n * 校验宿主计时器可以稳定表示的延迟。\n *\n * @param milliseconds - 待校验的毫秒数。\n * @param name - 用于错误消息的参数名称。\n * @returns 原始延迟值，便于调用方在校验后直接使用。\n * @throws `RangeError` 当值非有限、为负数或超过 32 位计时器上限。\n */\nconst assertDelay = (milliseconds: number, name = \"milliseconds\"): number => {\n\tif (!Number.isFinite(milliseconds) || milliseconds < 0 || milliseconds > maximumTimerDelay) {\n\t\tthrow new RangeError(`\\`${name}\\` 必须是 0 到 ${maximumTimerDelay} 之间的有限数。`);\n\t}\n\treturn milliseconds;\n};\n\n/**\n * 等待指定时间，并支持 `AbortSignal`。\n *\n * @param milliseconds - 0 至 2,147,483,647 的有限毫秒数。\n * @param options - 可选取消信号。\n * @returns 到期后完成的 Promise。\n * @throws 取消时抛出名称为 `AbortError` 的 `Error`；参数非法时抛出 `RangeError`。\n */\nexport function sleep(milliseconds: number, options: AbortOptions = {}): Promise<void> {\n\tconst delay = assertDelay(milliseconds);\n\tconst signal = options.signal;\n\tthrowIfAborted(signal);\n\n\treturn new Promise<void>((resolve, reject) => {\n\t\tlet timer: ReturnType<typeof setTimeout>;\n\t\t/** 取消计时器并使用标准取消错误拒绝等待。 */\n\t\tfunction onAbort() {\n\t\t\tif (signal === undefined) return;\n\t\t\tclearTimeout(timer);\n\t\t\treject(createAbortError(signal));\n\t\t}\n\t\ttimer = setTimeout(() => {\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tresolve();\n\t\t}, delay);\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t});\n}\n\n/**\n * 为 Promise 增加等待上限。\n *\n * @remarks 超时或取消只停止等待，不能自动取消底层操作；需要真正取消时应同时把\n * 同一个 `AbortSignal` 传给底层 API。\n * @param promise - 需要等待的 Promise 或 PromiseLike。\n * @param timeoutMs - 0 至 2,147,483,647 的有限等待时间。\n * @param options - 取消信号与自定义消息。\n * @returns 底层 Promise 的结果。\n * @throws 超时抛出 `Error`，取消时抛出名称为 `AbortError` 的 `Error`；等待时间非法时抛出 `RangeError`。\n */\nexport function withTimeout<Result>(promise: PromiseLike<Result>, timeoutMs: number, options: TimeoutOptions = {}): Promise<Result> {\n\tconst delay = assertDelay(timeoutMs, \"timeoutMs\");\n\tconst signal = options.signal;\n\tthrowIfAborted(signal);\n\n\treturn new Promise<Result>((resolve, reject) => {\n\t\tlet settled = false;\n\t\tlet timer: ReturnType<typeof setTimeout>;\n\t\t/** 清理竞争结束后不再需要的计时器和监听器。 */\n\t\tfunction cleanup() {\n\t\t\tclearTimeout(timer);\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t}\n\t\t/**\n\t\t * 只允许 Promise、超时和取消三个竞争来源中的首个结果生效。\n\t\t *\n\t\t * @param action - 首个完成来源的结算动作。\n\t\t */\n\t\tfunction settle(action: () => void) {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\taction();\n\t\t}\n\t\t/** 使用调用方取消原因结束当前等待。 */\n\t\tfunction onAbort() {\n\t\t\tif (signal === undefined) return;\n\t\t\tsettle(() => {\n\t\t\t\treject(createAbortError(signal));\n\t\t\t});\n\t\t}\n\t\ttimer = setTimeout(() => {\n\t\t\tsettle(() => {\n\t\t\t\treject(new Error(options.message ?? `操作超过 ${delay} 毫秒仍未完成。`));\n\t\t\t});\n\t\t}, delay);\n\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\tPromise.resolve(promise).then(\n\t\t\t(value) => {\n\t\t\t\tsettle(() => {\n\t\t\t\t\tresolve(value);\n\t\t\t\t});\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tsettle(() => {\n\t\t\t\t\treject(error);\n\t\t\t\t});\n\t\t\t}\n\t\t);\n\t});\n}\n\n/**\n * 使用有上限的指数退避重试操作。\n *\n * @typeParam Result - 操作结果类型。\n * @param operation - 每次尝试都会调用的函数；`attempt` 从 1 开始。\n * @param options - 尝试次数、退避和取消策略。\n * @returns 首次成功结果。\n * @throws 最后一次操作错误、`shouldRetry` 错误或名称为 `AbortError` 的取消错误；策略参数非法时抛出 `RangeError`。\n */\nexport async function retry<Result>(\n\toperation: (context: RetryContext) => Result | PromiseLike<Result>,\n\toptions: RetryOptions = {}\n): Promise<Awaited<Result>> {\n\tconst attempts = options.attempts ?? 3;\n\tconst initialDelay = assertDelay(options.delayMs ?? 200, \"delayMs\");\n\tconst maximumDelay = assertDelay(options.maxDelayMs ?? 30_000, \"maxDelayMs\");\n\tconst factor = options.factor ?? 2;\n\tif (!Number.isSafeInteger(attempts) || attempts <= 0) throw new RangeError(\"`attempts` 必须是正安全整数。\");\n\tif (!Number.isFinite(factor) || factor < 1) throw new RangeError(\"`factor` 必须是大于或等于 1 的有限数。\");\n\n\tfor (let attempt = 1; attempt <= attempts; attempt += 1) {\n\t\tthrowIfAborted(options.signal);\n\t\tconst context: RetryContext = options.signal === undefined ? { attempt } : { attempt, signal: options.signal };\n\t\ttry {\n\t\t\treturn await operation(context);\n\t\t} catch (error) {\n\t\t\tif (attempt === attempts || (options.shouldRetry !== undefined && !(await options.shouldRetry(error, context)))) throw error;\n\t\t\t// `0 * Infinity` is `NaN`; a zero initial delay must remain zero even when\n\t\t\t// a very large factor overflows during a later attempt.\n\t\t\tconst delay = initialDelay === 0 ? 0 : Math.min(initialDelay * factor ** (attempt - 1), maximumDelay);\n\t\t\tawait sleep(delay, options.signal === undefined ? {} : { signal: options.signal });\n\t\t}\n\t}\n\n\tthrow new Error(\"重试结束但未获得结果。\");\n}\n\n/**\n * 以固定并发度映射数组，并保持结果顺序。\n *\n * @remarks 任一映射失败后不会再调度新项目，但已经开始的映射无法自动取消；映射器\n * 应使用传入的 `signal` 取消底层工作。\n * @param items - 不会被修改的输入数组。\n * @param concurrency - 同时运行的最大任务数，必须为正安全整数。\n * @param mapper - 接收项目、索引和取消信号的映射函数。\n * @param options - 可选取消信号。\n * @returns 与输入长度和顺序一致的结果数组；稀疏空位保持为空位且不会调用映射器。\n * @throws `RangeError` 当 `concurrency` 不是正安全整数；取消时抛出名称为 `AbortError` 的 `Error`。\n */\nexport async function mapConcurrent<Item, Result>(\n\titems: readonly Item[],\n\tconcurrency: number,\n\tmapper: (item: Item, index: number, signal: AbortSignal | undefined) => Result | PromiseLike<Result>,\n\toptions: ConcurrentMapOptions = {}\n): Promise<Awaited<Result>[]> {\n\tif (!Number.isSafeInteger(concurrency) || concurrency <= 0) {\n\t\tthrow new RangeError(\"`concurrency` 必须是正安全整数。\");\n\t}\n\tthrowIfAborted(options.signal);\n\n\tconst results = new Array<Awaited<Result>>(items.length);\n\tlet nextIndex = 0;\n\tlet failed = false;\n\t/**\n\t * 从共享游标持续领取映射任务。\n\t *\n\t * @remarks JavaScript 单线程执行保证“读取索引并递增”不会被另一个 Worker 插入，因此每个索引只会领取一次。\n\t * @returns 当前 Worker 没有剩余任务时完成。\n\t * @throws 原样传播取消错误或 Mapper 错误，并阻止其他 Worker 领取新任务。\n\t */\n\tconst worker = async () => {\n\t\twhile (!failed) {\n\t\t\tthrowIfAborted(options.signal);\n\t\t\tconst index = nextIndex;\n\t\t\tif (index >= items.length) return;\n\t\t\tnextIndex += 1;\n\t\t\tif (!(index in items)) continue;\n\t\t\ttry {\n\t\t\t\tresults[index] = await mapper(items[index] as Item, index, options.signal);\n\t\t\t} catch (error) {\n\t\t\t\tfailed = true;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t};\n\n\tconst workerCount = Math.min(concurrency, items.length);\n\tawait Promise.all(Array.from({ length: workerCount }, worker));\n\treturn results;\n}\n\n/**\n * 创建 Promise 感知的防抖函数。\n *\n * @remarks 同一窗口内的所有调用都会等待最后一组参数对应的执行结果；回调错误会原样\n * 拒绝该批次的全部调用，不会留下永久 pending 的 Promise。\n * @param callback - 同步或异步回调。\n * @param delayMs - 0 至 2,147,483,647 的有限等待时间，默认 300 毫秒。\n * @returns 具有取消、立即执行和状态方法的防抖函数。\n * @throws `RangeError` 当延迟不在平台计时器支持范围内。\n */\nexport function debounce<Arguments extends unknown[], Result>(\n\tcallback: AsyncCallback<Arguments, Result>,\n\tdelayMs = 300\n): DebouncedFunction<Arguments, Awaited<Result>> {\n\tconst delay = assertDelay(delayMs, \"delayMs\");\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tlet latestArguments: Arguments | undefined;\n\tlet waiters: PromiseWaiter<Awaited<Result>>[] = [];\n\n\t/**\n\t * 执行并结算当前防抖批次。\n\t *\n\t * @returns 最后一组参数对应的回调结果。\n\t * @throws 没有待处理批次时抛出 `Error`；回调错误会原样传播给批次中的全部调用方。\n\t */\n\tconst execute = async (): Promise<Awaited<Result>> => {\n\t\tconst arguments_ = latestArguments;\n\t\tif (arguments_ === undefined) {\n\t\t\tthrow new Error(\"当前没有待处理的防抖调用。\");\n\t\t}\n\t\tlatestArguments = undefined;\n\t\ttimer = undefined;\n\t\tconst currentWaiters = waiters;\n\t\twaiters = [];\n\t\ttry {\n\t\t\tconst result = await callback(...arguments_);\n\t\t\tcurrentWaiters.forEach((waiter) => {\n\t\t\t\twaiter.resolve(result);\n\t\t\t});\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\tcurrentWaiters.forEach((waiter) => {\n\t\t\t\twaiter.reject(error);\n\t\t\t});\n\t\t\tthrow error;\n\t\t}\n\t};\n\n\t/**\n\t * 更新批次参数并返回当前调用方专属的等待 Promise。\n\t *\n\t * @param arguments_ - 本次调用参数；同批次中只有最后一组参数会执行。\n\t * @returns 与当前批次共享结果、但可独立结算的 Promise。\n\t */\n\tconst debounced = (...arguments_: Arguments) => {\n\t\tlatestArguments = arguments_;\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t\ttimer = setTimeout(() => {\n\t\t\texecute().catch(() => undefined);\n\t\t}, delay);\n\t\treturn new Promise<Awaited<Result>>((resolve, reject) => {\n\t\t\twaiters.push({ reject, resolve });\n\t\t});\n\t};\n\n\tdebounced.cancel = (reason?: unknown) => {\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t\ttimer = undefined;\n\t\tlatestArguments = undefined;\n\t\tconst error = reason ?? new Error(\"防抖调用已取消。\");\n\t\twaiters.forEach((waiter) => {\n\t\t\twaiter.reject(error);\n\t\t});\n\t\twaiters = [];\n\t};\n\tdebounced.flush = () => {\n\t\tif (timer === undefined) return undefined;\n\t\tclearTimeout(timer);\n\t\treturn execute();\n\t};\n\tdebounced.pending = () => timer !== undefined;\n\treturn debounced;\n}\n\n/**\n * 创建 Promise 感知的前缘节流函数。\n *\n * @remarks 窗口内的调用共享首次调用结果。若回调执行时间超过窗口，后续调用仍会等待\n * 当前回调，避免异步操作重入；该函数不安排尾缘调用。\n * @param callback - 同步或异步回调。\n * @param delayMs - 0 至 2,147,483,647 的有限冷却时间，默认 300 毫秒。\n * @returns 具有取消和状态方法的前缘节流函数。\n * @throws `RangeError` 当延迟不在平台计时器支持范围内。\n */\nexport function throttle<Arguments extends unknown[], Result>(\n\tcallback: AsyncCallback<Arguments, Result>,\n\tdelayMs = 300\n): ThrottledFunction<Arguments, Awaited<Result>> {\n\tconst delay = assertDelay(delayMs, \"delayMs\");\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tlet current: Promise<Awaited<Result>> | undefined;\n\tlet cooling = false;\n\tlet settled = false;\n\n\t/**\n\t * 尝试释放当前节流窗口。\n\t *\n\t * @remarks 只有回调和冷却计时器都结束后才清空共享 Promise，避免长回调发生重入。\n\t */\n\tconst release = () => {\n\t\tif (!cooling && settled) current = undefined;\n\t};\n\t/**\n\t * 执行前缘调用或复用当前窗口的共享 Promise。\n\t *\n\t * @param arguments_ - 仅新窗口首个调用会使用的参数。\n\t * @returns 当前窗口首次调用的 Promise。\n\t */\n\tconst throttled = (...arguments_: Arguments) => {\n\t\tif (current !== undefined) return current;\n\t\tcooling = true;\n\t\tsettled = false;\n\t\tlet invocation: Promise<Awaited<Result>>;\n\t\ttry {\n\t\t\tinvocation = Promise.resolve(callback(...arguments_));\n\t\t} catch (error) {\n\t\t\tinvocation = Promise.reject(error);\n\t\t}\n\t\tcurrent = invocation;\n\t\tinvocation.then(\n\t\t\t() => {\n\t\t\t\tsettled = true;\n\t\t\t\trelease();\n\t\t\t},\n\t\t\t() => {\n\t\t\t\tsettled = true;\n\t\t\t\trelease();\n\t\t\t}\n\t\t);\n\t\ttimer = setTimeout(() => {\n\t\t\ttimer = undefined;\n\t\t\tcooling = false;\n\t\t\trelease();\n\t\t}, delay);\n\t\treturn invocation;\n\t};\n\n\tthrottled.cancel = () => {\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t\ttimer = undefined;\n\t\tcooling = false;\n\t\trelease();\n\t};\n\tthrottled.pending = () => current !== undefined;\n\treturn throttled;\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/async/index.ts"],"sourcesContent":["/** 统一同步返回值与 PromiseLike 返回值的内部回调签名。 */\ntype AsyncCallback<Arguments extends unknown[], Result> = (...arguments_: Arguments) => Result | PromiseLike<Result>;\n\n/** 记录同一防抖批次中每个调用方独立的 Promise 结算函数。 */\ninterface PromiseWaiter<Result> {\n\t/**\n\t * 使用批次失败原因拒绝当前调用方。\n\t * @param reason - `cancel` 提供的原因或共享回调抛出的原始错误。\n\t */\n\treject: (reason?: unknown) => void;\n\t/**\n\t * 使用共享回调结果完成当前调用方，并采用传入 PromiseLike 的最终状态。\n\t * @param value - 当前防抖批次唯一一次回调执行产生的共享结果。\n\t */\n\tresolve: (value: Result | PromiseLike<Result>) => void;\n}\n\n// 浏览器和 Node.js 的计时器普遍以有符号 32 位整数保存延迟；更大的值可能被\n// 静默截断为约 1 ms，因此公共 API 在进入平台计时器前统一拒绝它。\nconst maximumTimerDelay = 2_147_483_647;\n\n/** 可接收取消信号的通用选项。 */\nexport interface AbortOptions {\n\t/** 已取消时立即失败；运行期间取消时停止等待并拒绝 Promise。 */\n\tsignal?: AbortSignal;\n}\n\n/** {@link withTimeout} 的行为选项。 */\nexport interface TimeoutOptions extends AbortOptions {\n\t/** 超时时使用的开发者消息 */\n\tmessage?: string;\n}\n\n/** 每次重试操作接收的上下文。 */\nexport interface RetryContext {\n\t/** 从 1 开始的当前尝试次数。 */\n\tattempt: number;\n\t/** 调用方提供的取消信号。 */\n\tsignal?: AbortSignal;\n}\n\n/** {@link retry} 的策略选项。 */\nexport interface RetryOptions extends AbortOptions {\n\t/** 最大尝试次数，包含首次调用；默认 `3`。 */\n\tattempts?: number;\n\t/** 首次重试前的等待毫秒数，最大 2,147,483,647；默认 `200`。 */\n\tdelayMs?: number;\n\t/** 每次失败后的退避倍数，必须不小于 1；默认 `2`。 */\n\tfactor?: number;\n\t/** 单次等待上限，最大 2,147,483,647；默认 `30_000` 毫秒。 */\n\tmaxDelayMs?: number;\n\t/**\n\t * 决定当前失败后是否继续下一次尝试；默认重试所有尚未到达上限的错误。\n\t * @param error - 当前操作抛出或拒绝的原始值。\n\t * @param context - 当前尝试次数和调用方取消信号。\n\t * @returns `false` 时立即原样抛出当前错误；支持同步值或 PromiseLike。\n\t */\n\tshouldRetry?: (error: unknown, context: RetryContext) => boolean | PromiseLike<boolean>;\n}\n\n/** {@link mapConcurrent} 的执行选项。 */\nexport interface ConcurrentMapOptions {\n\t/** 已取消时停止调度新任务；已经开始的映射器需要自行响应同一信号。 */\n\tsignal?: AbortSignal;\n}\n\n/** Promise 感知的防抖函数。 */\nexport interface DebouncedFunction<Arguments extends unknown[], Result> {\n\t/**\n\t * 调度一次调用；同一等待窗口内的调用共享最后一组参数对应的结果。\n\t * @param arguments_ - 传给原始回调的参数；后续调用会覆盖尚未执行批次保存的参数。\n\t * @returns 当前批次的独立 Promise，最终与共享回调结果保持相同状态。\n\t */\n\t(...arguments_: Arguments): Promise<Result>;\n\t/**\n\t * 取消尚未执行的批次，并拒绝该批次的所有 Promise。\n\t * @param reason - 可选拒绝原因；省略时使用内部取消错误。\n\t */\n\tcancel: (reason?: unknown) => void;\n\t/**\n\t * 立即执行待处理批次，不创建第二次回调执行。\n\t * @returns 待处理批次的共享执行 Promise；没有批次时返回 `undefined`。\n\t */\n\tflush: () => Promise<Result> | undefined;\n\t/** @returns 当前存在尚未开始的批次时返回 `true`；正在执行但没有等待批次时返回 `false`。 */\n\tpending: () => boolean;\n}\n\n/** Promise 感知的前缘节流函数。 */\nexport interface ThrottledFunction<Arguments extends unknown[], Result> {\n\t/**\n\t * 在空闲时立即调用原始回调；执行期和冷却期内的调用共享首次调用的 Promise。\n\t * @param arguments_ - 仅窗口内首次调用的参数会传给原始回调。\n\t * @returns 当前执行窗口共享的 Promise。\n\t */\n\t(...arguments_: Arguments): Promise<Result>;\n\t/** 提前结束冷却期；已经开始的操作不会被取消，结束前仍禁止并发重入。 */\n\tcancel: () => void;\n\t/** @returns 原始回调正在执行或计时器仍处于冷却期时返回 `true`。 */\n\tpending: () => boolean;\n}\n\n/**\n * 创建符合 Web Platform 约定的取消错误。\n *\n * @param signal - 已进入取消状态的信号；其 `reason` 会保存在错误的 `cause` 中。\n * @returns 名称为 `AbortError` 的新错误实例。\n */\nconst createAbortError = (signal: AbortSignal): Error => {\n\tconst error = new Error(\"操作已取消。\", { cause: signal.reason });\n\terror.name = \"AbortError\";\n\treturn error;\n};\n\n/**\n * 在启动异步工作前同步拒绝已经取消的信号。\n *\n * @param signal - 可选取消信号；省略或尚未取消时不执行操作。\n * @throws `Error` 当信号已经取消，错误名称为 `AbortError`。\n */\nconst throwIfAborted = (signal: AbortSignal | undefined): void => {\n\tif (signal?.aborted) throw createAbortError(signal);\n};\n\n/**\n * 校验宿主计时器可以稳定表示的延迟。\n *\n * @param milliseconds - 待校验的毫秒数。\n * @param name - 用于错误消息的参数名称。\n * @returns 原始延迟值，便于调用方在校验后直接使用。\n * @throws `RangeError` 当值非有限、为负数或超过 32 位计时器上限。\n */\nconst assertDelay = (milliseconds: number, name = \"milliseconds\"): number => {\n\tif (!Number.isFinite(milliseconds) || milliseconds < 0 || milliseconds > maximumTimerDelay) {\n\t\tthrow new RangeError(`\\`${name}\\` 必须是 0 到 ${maximumTimerDelay} 之间的有限数。`);\n\t}\n\treturn milliseconds;\n};\n\n/**\n * 等待指定时间，并支持 `AbortSignal`。\n *\n * @param milliseconds - 0 至 2,147,483,647 的有限毫秒数。\n * @param options - 可选取消信号。\n * @returns 到期后完成的 Promise。\n * @throws 参数非法时同步抛出 `RangeError`；信号已取消时同步抛出 `AbortError`。运行期间取消则拒绝返回的 Promise。\n */\nexport function sleep(milliseconds: number, options: AbortOptions = {}): Promise<void> {\n\tconst delay = assertDelay(milliseconds);\n\tconst signal = options.signal;\n\tthrowIfAborted(signal);\n\n\treturn new Promise<void>((resolve, reject) => {\n\t\tlet timer: ReturnType<typeof setTimeout>;\n\t\t/** 取消计时器并使用标准取消错误拒绝等待。 */\n\t\tfunction onAbort() {\n\t\t\tif (signal === undefined) return;\n\t\t\tclearTimeout(timer);\n\t\t\treject(createAbortError(signal));\n\t\t}\n\t\ttimer = setTimeout(() => {\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tresolve();\n\t\t}, delay);\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t});\n}\n\n/**\n * 为 Promise 增加等待上限。\n *\n * @remarks 超时或取消只停止等待，不能自动取消底层操作；需要真正取消时应同时把\n * 同一个 `AbortSignal` 传给底层 API。\n * @param promise - 需要等待的 Promise 或 PromiseLike。\n * @param timeoutMs - 0 至 2,147,483,647 的有限等待时间。\n * @param options - 取消信号与自定义消息。\n * @returns 底层 Promise 的结果。\n * @throws 等待时间非法或信号已取消时同步抛错；运行期间的超时、取消及源 Promise 失败通过返回的 Promise 拒绝。\n */\nexport function withTimeout<Result>(promise: PromiseLike<Result>, timeoutMs: number, options: TimeoutOptions = {}): Promise<Result> {\n\tconst delay = assertDelay(timeoutMs, \"timeoutMs\");\n\tconst signal = options.signal;\n\tthrowIfAborted(signal);\n\n\treturn new Promise<Result>((resolve, reject) => {\n\t\tlet settled = false;\n\t\tlet timer: ReturnType<typeof setTimeout>;\n\t\t/** 清理竞争结束后不再需要的计时器和监听器。 */\n\t\tfunction cleanup() {\n\t\t\tclearTimeout(timer);\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t}\n\t\t/**\n\t\t * 只允许 Promise、超时和取消三个竞争来源中的首个结果生效。\n\t\t *\n\t\t * @param action - 首个完成来源的结算动作。\n\t\t */\n\t\tfunction settle(action: () => void) {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tcleanup();\n\t\t\taction();\n\t\t}\n\t\t/** 使用调用方取消原因结束当前等待。 */\n\t\tfunction onAbort() {\n\t\t\tif (signal === undefined) return;\n\t\t\tsettle(() => {\n\t\t\t\treject(createAbortError(signal));\n\t\t\t});\n\t\t}\n\t\ttimer = setTimeout(() => {\n\t\t\tsettle(() => {\n\t\t\t\treject(new Error(options.message ?? `操作超过 ${delay} 毫秒仍未完成。`));\n\t\t\t});\n\t\t}, delay);\n\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\tPromise.resolve(promise).then(\n\t\t\t(value) => {\n\t\t\t\tsettle(() => {\n\t\t\t\t\tresolve(value);\n\t\t\t\t});\n\t\t\t},\n\t\t\t(error: unknown) => {\n\t\t\t\tsettle(() => {\n\t\t\t\t\treject(error);\n\t\t\t\t});\n\t\t\t}\n\t\t);\n\t});\n}\n\n/**\n * 使用有上限的指数退避重试操作。\n *\n * @typeParam Result - 操作结果类型。\n * @param operation - 每次尝试都会调用的函数；`attempt` 从 1 开始。\n * @param options - 尝试次数、退避和取消策略。\n * @returns 首次成功结果。\n * @throws 最后一次操作错误、`shouldRetry` 错误或名称为 `AbortError` 的取消错误；策略参数非法时抛出 `RangeError`。\n */\nexport async function retry<Result>(\n\toperation: (context: RetryContext) => Result | PromiseLike<Result>,\n\toptions: RetryOptions = {}\n): Promise<Awaited<Result>> {\n\tconst attempts = options.attempts ?? 3;\n\tconst initialDelay = assertDelay(options.delayMs ?? 200, \"delayMs\");\n\tconst maximumDelay = assertDelay(options.maxDelayMs ?? 30_000, \"maxDelayMs\");\n\tconst factor = options.factor ?? 2;\n\tif (!Number.isSafeInteger(attempts) || attempts <= 0) throw new RangeError(\"`attempts` 必须是正安全整数。\");\n\tif (!Number.isFinite(factor) || factor < 1) throw new RangeError(\"`factor` 必须是大于或等于 1 的有限数。\");\n\n\tfor (let attempt = 1; attempt <= attempts; attempt += 1) {\n\t\tthrowIfAborted(options.signal);\n\t\tconst context: RetryContext = options.signal === undefined ? { attempt } : { attempt, signal: options.signal };\n\t\ttry {\n\t\t\treturn await operation(context);\n\t\t} catch (error) {\n\t\t\tif (attempt === attempts || (options.shouldRetry !== undefined && !(await options.shouldRetry(error, context)))) throw error;\n\t\t\t// `0 * Infinity` is `NaN`; a zero initial delay must remain zero even when\n\t\t\t// a very large factor overflows during a later attempt.\n\t\t\tconst delay = initialDelay === 0 ? 0 : Math.min(initialDelay * factor ** (attempt - 1), maximumDelay);\n\t\t\tawait sleep(delay, options.signal === undefined ? {} : { signal: options.signal });\n\t\t}\n\t}\n\n\tthrow new Error(\"重试结束但未获得结果。\");\n}\n\n/**\n * 以固定并发度映射数组，并保持结果顺序。\n *\n * @remarks 任一映射失败后不会再调度新项目，但已经开始的映射无法自动取消；映射器\n * 应使用传入的 `signal` 取消底层工作。\n * @param items - 不会被修改的输入数组。\n * @param concurrency - 同时运行的最大任务数，必须为正安全整数。\n * @param mapper - 接收项目、索引和取消信号的映射函数。\n * @param options - 可选取消信号。\n * @returns 与输入长度和顺序一致的结果数组；稀疏空位保持为空位且不会调用映射器。\n * @throws `RangeError` 当 `concurrency` 不是正安全整数；取消时抛出名称为 `AbortError` 的 `Error`。\n */\nexport async function mapConcurrent<Item, Result>(\n\titems: readonly Item[],\n\tconcurrency: number,\n\tmapper: (item: Item, index: number, signal: AbortSignal | undefined) => Result | PromiseLike<Result>,\n\toptions: ConcurrentMapOptions = {}\n): Promise<Awaited<Result>[]> {\n\tif (!Number.isSafeInteger(concurrency) || concurrency <= 0) {\n\t\tthrow new RangeError(\"`concurrency` 必须是正安全整数。\");\n\t}\n\tthrowIfAborted(options.signal);\n\n\tconst results = new Array<Awaited<Result>>(items.length);\n\tlet nextIndex = 0;\n\tlet failed = false;\n\t/**\n\t * 从共享游标持续领取映射任务。\n\t *\n\t * @remarks JavaScript 单线程执行保证“读取索引并递增”不会被另一个 Worker 插入，因此每个索引只会领取一次。\n\t * @returns 当前 Worker 没有剩余任务时完成。\n\t * @throws 原样传播取消错误或 Mapper 错误，并阻止其他 Worker 领取新任务。\n\t */\n\tconst worker = async () => {\n\t\twhile (!failed) {\n\t\t\tthrowIfAborted(options.signal);\n\t\t\tconst index = nextIndex;\n\t\t\tif (index >= items.length) return;\n\t\t\tnextIndex += 1;\n\t\t\tif (!(index in items)) continue;\n\t\t\ttry {\n\t\t\t\tresults[index] = await mapper(items[index] as Item, index, options.signal);\n\t\t\t} catch (error) {\n\t\t\t\tfailed = true;\n\t\t\t\tthrow error;\n\t\t\t}\n\t\t}\n\t};\n\n\tconst workerCount = Math.min(concurrency, items.length);\n\tawait Promise.all(Array.from({ length: workerCount }, worker));\n\treturn results;\n}\n\n/**\n * 创建 Promise 感知的防抖函数。\n *\n * @remarks 同一窗口内的所有调用都会等待最后一组参数对应的执行结果；回调错误会原样\n * 拒绝该批次的全部调用，不会留下永久 pending 的 Promise。\n * @param callback - 同步或异步回调。\n * @param delayMs - 0 至 2,147,483,647 的有限等待时间，默认 300 毫秒。\n * @returns 具有取消、立即执行和状态方法的防抖函数。\n * @throws `RangeError` 当延迟不在平台计时器支持范围内。\n */\nexport function debounce<Arguments extends unknown[], Result>(\n\tcallback: AsyncCallback<Arguments, Result>,\n\tdelayMs = 300\n): DebouncedFunction<Arguments, Awaited<Result>> {\n\tconst delay = assertDelay(delayMs, \"delayMs\");\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tlet latestArguments: Arguments | undefined;\n\tlet waiters: PromiseWaiter<Awaited<Result>>[] = [];\n\n\t/**\n\t * 执行并结算当前防抖批次。\n\t *\n\t * @returns 最后一组参数对应的回调结果。\n\t * @throws 没有待处理批次时抛出 `Error`；回调错误会原样传播给批次中的全部调用方。\n\t */\n\tconst execute = async (): Promise<Awaited<Result>> => {\n\t\tconst arguments_ = latestArguments;\n\t\tif (arguments_ === undefined) {\n\t\t\tthrow new Error(\"当前没有待处理的防抖调用。\");\n\t\t}\n\t\tlatestArguments = undefined;\n\t\ttimer = undefined;\n\t\tconst currentWaiters = waiters;\n\t\twaiters = [];\n\t\ttry {\n\t\t\tconst result = await callback(...arguments_);\n\t\t\tcurrentWaiters.forEach((waiter) => {\n\t\t\t\twaiter.resolve(result);\n\t\t\t});\n\t\t\treturn result;\n\t\t} catch (error) {\n\t\t\tcurrentWaiters.forEach((waiter) => {\n\t\t\t\twaiter.reject(error);\n\t\t\t});\n\t\t\tthrow error;\n\t\t}\n\t};\n\n\t/**\n\t * 更新批次参数并返回当前调用方专属的等待 Promise。\n\t *\n\t * @param arguments_ - 本次调用参数；同批次中只有最后一组参数会执行。\n\t * @returns 与当前批次共享结果、但可独立结算的 Promise。\n\t */\n\tconst debounced = (...arguments_: Arguments) => {\n\t\tlatestArguments = arguments_;\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t\ttimer = setTimeout(() => {\n\t\t\texecute().catch(() => undefined);\n\t\t}, delay);\n\t\treturn new Promise<Awaited<Result>>((resolve, reject) => {\n\t\t\twaiters.push({ reject, resolve });\n\t\t});\n\t};\n\n\tdebounced.cancel = (reason?: unknown) => {\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t\ttimer = undefined;\n\t\tlatestArguments = undefined;\n\t\tconst error = reason ?? new Error(\"防抖调用已取消。\");\n\t\twaiters.forEach((waiter) => {\n\t\t\twaiter.reject(error);\n\t\t});\n\t\twaiters = [];\n\t};\n\tdebounced.flush = () => {\n\t\tif (timer === undefined) return undefined;\n\t\tclearTimeout(timer);\n\t\treturn execute();\n\t};\n\tdebounced.pending = () => timer !== undefined;\n\treturn debounced;\n}\n\n/**\n * 创建 Promise 感知的前缘节流函数。\n *\n * @remarks 窗口内的调用共享首次调用结果。若回调执行时间超过窗口，后续调用仍会等待\n * 当前回调，避免异步操作重入；该函数不安排尾缘调用。\n * @param callback - 同步或异步回调。\n * @param delayMs - 0 至 2,147,483,647 的有限冷却时间，默认 300 毫秒。\n * @returns 具有取消和状态方法的前缘节流函数。\n * @throws `RangeError` 当延迟不在平台计时器支持范围内。\n */\nexport function throttle<Arguments extends unknown[], Result>(\n\tcallback: AsyncCallback<Arguments, Result>,\n\tdelayMs = 300\n): ThrottledFunction<Arguments, Awaited<Result>> {\n\tconst delay = assertDelay(delayMs, \"delayMs\");\n\tlet timer: ReturnType<typeof setTimeout> | undefined;\n\tlet current: Promise<Awaited<Result>> | undefined;\n\tlet cooling = false;\n\tlet settled = false;\n\n\t/**\n\t * 尝试释放当前节流窗口。\n\t *\n\t * @remarks 只有回调和冷却计时器都结束后才清空共享 Promise，避免长回调发生重入。\n\t */\n\tconst release = () => {\n\t\tif (!cooling && settled) current = undefined;\n\t};\n\t/**\n\t * 执行前缘调用或复用当前窗口的共享 Promise。\n\t *\n\t * @param arguments_ - 仅新窗口首个调用会使用的参数。\n\t * @returns 当前窗口首次调用的 Promise。\n\t */\n\tconst throttled = (...arguments_: Arguments) => {\n\t\tif (current !== undefined) return current;\n\t\tcooling = true;\n\t\tsettled = false;\n\t\tlet invocation: Promise<Awaited<Result>>;\n\t\ttry {\n\t\t\tinvocation = Promise.resolve(callback(...arguments_));\n\t\t} catch (error) {\n\t\t\tinvocation = Promise.reject(error);\n\t\t}\n\t\tcurrent = invocation;\n\t\tinvocation.then(\n\t\t\t() => {\n\t\t\t\tsettled = true;\n\t\t\t\trelease();\n\t\t\t},\n\t\t\t() => {\n\t\t\t\tsettled = true;\n\t\t\t\trelease();\n\t\t\t}\n\t\t);\n\t\ttimer = setTimeout(() => {\n\t\t\ttimer = undefined;\n\t\t\tcooling = false;\n\t\t\trelease();\n\t\t}, delay);\n\t\treturn invocation;\n\t};\n\n\tthrottled.cancel = () => {\n\t\tif (timer !== undefined) clearTimeout(timer);\n\t\ttimer = undefined;\n\t\tcooling = false;\n\t\trelease();\n\t};\n\tthrottled.pending = () => current !== undefined;\n\treturn throttled;\n}\n"],"mappings":"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"}

package/dist/function/index.mjs

@@ -4,6 +4,7 @@
 *
 * @remarks 首次成功返回后，后续调用返回同一结果；Promise 会保持引用不变。首次同步抛错时缓存错误，后续调用重新抛出同一错误。
 * 包装函数使用首次调用时的参数和 `this`，之后传入的参数不会再次执行原函数。
+* 首次调用尚未返回时同步重入会抛出 `Error`，不会重复执行原函数；该错误如向外传播，会作为首次错误缓存。
 * @param callback - 只允许执行一次的函数。
 * @returns 保持原参数与返回类型的包装函数。
 * @throws `TypeError` 当 `callback` 不是函数。
@@ -15,20 +16,23 @@ function once(callback) {
 		switch (state.status) {
 			case "returned": return state.value;
 			case "threw": throw state.error;
-			case "pending": try {
-				const value = callback.apply(this, arguments_);
-				state = {
-					status: "returned",
-					value
-				};
-				return value;
-			} catch (error) {
-				state = {
-					error,
-					status: "threw"
-				};
-				throw error;
-			}
+			case "running": throw new Error("`once` 回调尚未返回，不能同步重入。");
+			case "pending":
+				state = { status: "running" };
+				try {
+					const value = callback.apply(this, arguments_);
+					state = {
+						status: "returned",
+						value
+					};
+					return value;
+				} catch (error) {
+					state = {
+						error,
+						status: "threw"
+					};
+					throw error;
+				}
 		}
 	};
 }

package/dist/function/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":[],"sources":["../../src/function/index.ts"],"sourcesContent":["/** 函数首次调用前的内部状态。 */\ninterface PendingOnceState {\n\treadonly status: \"pending\";\n}\n\n/** 函数成功返回后的内部状态。 */\ninterface ReturnedOnceState<Result> {\n\treadonly status: \"returned\";\n\treadonly value: Result;\n}\n\n/** 函数同步抛错后的内部状态。 */\ninterface ThrewOnceState {\n\treadonly error: unknown;\n\treadonly status: \"threw\";\n}\n\ntype OnceState<Result> = PendingOnceState | ReturnedOnceState<Result> | ThrewOnceState;\n\n/**\n * 创建最多执行一次并缓存首次结果的函数。\n *\n * @remarks 首次成功返回后，后续调用返回同一结果；Promise 会保持引用不变。首次同步抛错时缓存错误，后续调用重新抛出同一错误。\n * 包装函数使用首次调用时的参数和 `this`，之后传入的参数不会再次执行原函数。\n * @param callback - 只允许执行一次的函数。\n * @returns 保持原参数与返回类型的包装函数。\n * @throws `TypeError` 当 `callback` 不是函数。\n */\nexport function once<This, Arguments extends unknown[], Result>(\n\tcallback: (this: This, ...arguments_: Arguments) => Result\n): (this: This, ...arguments_: Arguments) => Result {\n\tif (typeof callback !== \"function\") throw new TypeError(\"`callback` 必须是函数。\");\n\tlet state: OnceState<Result> = { status: \"pending\" };\n\treturn function (this: This, ...arguments_: Arguments): Result {\n\t\tswitch (state.status) {\n\t\t\tcase \"returned\":\n\t\t\t\treturn state.value;\n\t\t\tcase \"threw\":\n\t\t\t\tthrow state.error;\n\t\t\tcase \"pending\":\n\t\t\t\ttry {\n\t\t\t\t\tconst value = callback.apply(this, arguments_);\n\t\t\t\t\tstate = { status: \"returned\", value };\n\t\t\t\t\treturn value;\n\t\t\t\t} catch (error) {\n\t\t\t\t\tstate = { error, status: \"threw\" };\n\t\t\t\t\tthrow error;\n\t\t\t\t}\n\t\t}\n\t};\n}\n"],"mappings":";;;;;;;;;;AA4BA,SAAgB,KACf,UACmD;CACnD,IAAI,OAAO,aAAa,YAAY,MAAM,IAAI,UAAU,mBAAmB;CAC3E,IAAI,QAA2B,EAAE,QAAQ,UAAU;CACnD,OAAO,SAAsB,GAAG,YAA+B;EAC9D,QAAQ,MAAM,QAAd;GACC,KAAK,YACJ,OAAO,MAAM;GACd,KAAK,SACJ,MAAM,MAAM;GACb,KAAK,WACJ,IAAI;IACH,MAAM,QAAQ,SAAS,MAAM,MAAM,UAAU;IAC7C,QAAQ;KAAE,QAAQ;KAAY;IAAM;IACpC,OAAO;GACR,SAAS,OAAO;IACf,QAAQ;KAAE;KAAO,QAAQ;IAAQ;IACjC,MAAM;GACP;EACF;CACD;AACD"}
+{"version":3,"file":"index.mjs","names":[],"sources":["../../src/function/index.ts"],"sourcesContent":["/** 函数首次调用前的内部状态。 */\ninterface PendingOnceState {\n\treadonly status: \"pending\";\n}\n\n/** 函数成功返回后的内部状态。 */\ninterface ReturnedOnceState<Result> {\n\treadonly status: \"returned\";\n\treadonly value: Result;\n}\n\n/** 函数同步抛错后的内部状态。 */\ninterface ThrewOnceState {\n\treadonly error: unknown;\n\treadonly status: \"threw\";\n}\n\n/** 首次调用尚未返回的内部状态 */\ninterface RunningOnceState {\n\treadonly status: \"running\";\n}\n\ntype OnceState<Result> = PendingOnceState | RunningOnceState | ReturnedOnceState<Result> | ThrewOnceState;\n\n/**\n * 创建最多执行一次并缓存首次结果的函数。\n *\n * @remarks 首次成功返回后，后续调用返回同一结果；Promise 会保持引用不变。首次同步抛错时缓存错误，后续调用重新抛出同一错误。\n * 包装函数使用首次调用时的参数和 `this`，之后传入的参数不会再次执行原函数。\n * 首次调用尚未返回时同步重入会抛出 `Error`，不会重复执行原函数；该错误如向外传播，会作为首次错误缓存。\n * @param callback - 只允许执行一次的函数。\n * @returns 保持原参数与返回类型的包装函数。\n * @throws `TypeError` 当 `callback` 不是函数。\n */\nexport function once<This, Arguments extends unknown[], Result>(\n\tcallback: (this: This, ...arguments_: Arguments) => Result\n): (this: This, ...arguments_: Arguments) => Result {\n\tif (typeof callback !== \"function\") throw new TypeError(\"`callback` 必须是函数。\");\n\tlet state: OnceState<Result> = { status: \"pending\" };\n\treturn function (this: This, ...arguments_: Arguments): Result {\n\t\tswitch (state.status) {\n\t\t\tcase \"returned\":\n\t\t\t\treturn state.value;\n\t\t\tcase \"threw\":\n\t\t\t\tthrow state.error;\n\t\t\tcase \"running\":\n\t\t\t\tthrow new Error(\"`once` 回调尚未返回，不能同步重入。\");\n\t\t\tcase \"pending\":\n\t\t\t\tstate = { status: \"running\" };\n\t\t\t\ttry {\n\t\t\t\t\tconst value = callback.apply(this, arguments_);\n\t\t\t\t\tstate = { status: \"returned\", value };\n\t\t\t\t\treturn value;\n\t\t\t\t} catch (error) {\n\t\t\t\t\tstate = { error, status: \"threw\" };\n\t\t\t\t\tthrow error;\n\t\t\t\t}\n\t\t}\n\t};\n}\n"],"mappings":";;;;;;;;;;;AAkCA,SAAgB,KACf,UACmD;CACnD,IAAI,OAAO,aAAa,YAAY,MAAM,IAAI,UAAU,mBAAmB;CAC3E,IAAI,QAA2B,EAAE,QAAQ,UAAU;CACnD,OAAO,SAAsB,GAAG,YAA+B;EAC9D,QAAQ,MAAM,QAAd;GACC,KAAK,YACJ,OAAO,MAAM;GACd,KAAK,SACJ,MAAM,MAAM;GACb,KAAK,WACJ,MAAM,IAAI,MAAM,uBAAuB;GACxC,KAAK;IACJ,QAAQ,EAAE,QAAQ,UAAU;IAC5B,IAAI;KACH,MAAM,QAAQ,SAAS,MAAM,MAAM,UAAU;KAC7C,QAAQ;MAAE,QAAQ;MAAY;KAAM;KACpC,OAAO;IACR,SAAS,OAAO;KACf,QAAQ;MAAE;MAAO,QAAQ;KAAQ;KACjC,MAAM;IACP;EACF;CACD;AACD"}

package/dist/index.d.mts

@@ -102,7 +102,7 @@ export interface AbortOptions {
 }
 /** {@link withTimeout} 的行为选项。 */
 export interface TimeoutOptions extends AbortOptions {
-  /** 超时时使用的开发者消息。 */
+  /** 超时时使用的开发者消息 */
   message?: string;
 }
 /** 每次重试操作接收的上下文。 */
@@ -175,7 +175,7 @@ export interface ThrottledFunction<Arguments extends unknown[], Result> {
  * @param milliseconds - 0 至 2,147,483,647 的有限毫秒数。
  * @param options - 可选取消信号。
  * @returns 到期后完成的 Promise。
- * @throws 取消时抛出名称为 `AbortError` 的 `Error`；参数非法时抛出 `RangeError`。
+ * @throws 参数非法时同步抛出 `RangeError`；信号已取消时同步抛出 `AbortError`。运行期间取消则拒绝返回的 Promise。
  */
 export declare function sleep(milliseconds: number, options?: AbortOptions): Promise<void>;
 /**
@@ -187,7 +187,7 @@ export declare function sleep(milliseconds: number, options?: AbortOptions): Pro
  * @param timeoutMs - 0 至 2,147,483,647 的有限等待时间。
  * @param options - 取消信号与自定义消息。
  * @returns 底层 Promise 的结果。
- * @throws 超时抛出 `Error`，取消时抛出名称为 `AbortError` 的 `Error`；等待时间非法时抛出 `RangeError`。
+ * @throws 等待时间非法或信号已取消时同步抛错；运行期间的超时、取消及源 Promise 失败通过返回的 Promise 拒绝。
  */
 export declare function withTimeout<Result>(promise: PromiseLike<Result>, timeoutMs: number, options?: TimeoutOptions): Promise<Result>;
 /**
@@ -1049,6 +1049,7 @@ export declare function isTabletUserAgent(userAgent?: string, maxTouchPoints?: n
  *
  * @remarks 首次成功返回后，后续调用返回同一结果；Promise 会保持引用不变。首次同步抛错时缓存错误，后续调用重新抛出同一错误。
  * 包装函数使用首次调用时的参数和 `this`，之后传入的参数不会再次执行原函数。
+ * 首次调用尚未返回时同步重入会抛出 `Error`，不会重复执行原函数；该错误如向外传播，会作为首次错误缓存。
  * @param callback - 只允许执行一次的函数。
  * @returns 保持原参数与返回类型的包装函数。
  * @throws `TypeError` 当 `callback` 不是函数。
@@ -1360,22 +1361,22 @@ export declare function isEqual(left: unknown, right: unknown): boolean;
 /**
  * 从对象中选择指定自有可枚举属性。
  *
- * @remarks 字面量键数组保留精确返回类型；普通 `string[]` 等动态键数组返回 `Partial<Source>`。
+ * @remarks 固定键元组保留精确返回类型；动态数组中可能被选择或排除的键在返回类型中保持可选。
  * @param source - 不会被修改的源对象。
  * @param keys - 需要保留的键；不存在的键被忽略。
  * @returns 新对象，保持 `keys` 的遍历顺序。
  */
-export declare function pick<Source extends object, const Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Pick<Source, Keys[number]>;
+export declare function pick<Source extends object, const Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): number extends Keys["length"] ? Partial<Pick<Source, Keys[number]>> : Pick<Source, Keys[number]>;
 export declare function pick<Source extends object>(source: Source, keys: readonly PropertyKey[]): Partial<Source>;
 /**
  * 浅复制对象并删除指定属性。
  *
- * @remarks 字面量键数组保留精确返回类型；普通 `string[]` 等动态键数组返回 `Partial<Source>`。
+ * @remarks 固定键元组保留精确返回类型；动态数组中可能被选择或排除的键在返回类型中保持可选。
  * @param source - 不会被修改的源对象。
  * @param keys - 需要排除的键。
  * @returns 包含其余自有可枚举字符串与 Symbol 属性的新对象。
  */
-export declare function omit<Source extends object, const Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): Omit<Source, Keys[number]>;
+export declare function omit<Source extends object, const Keys extends readonly (keyof Source)[]>(source: Source, keys: Keys): number extends Keys["length"] ? Omit<Source, Keys[number]> & Partial<Pick<Source, Keys[number]>> : Omit<Source, Keys[number]>;
 export declare function omit<Source extends object>(source: Source, keys: readonly PropertyKey[]): Partial<Source>;
 /**
  * 按条件排除对象的自有可枚举属性。
@@ -1447,7 +1448,7 @@ export interface StorageConfiguration {
   crypto?: boolean;
   /** 返回 Unix 毫秒时间戳的时钟；默认使用 `Date.now`，主要用于 TTL 测试与受控时间源。 */
   now?: () => number;
-  /** 所有物理键使用的非空命名空间前缀； */
+  /** 所有物理键使用的非空命名空间前缀，默认 `fast__`。 */
   prefix?: string;
 }
 /** 单次 Storage 读取配置。 */
@@ -1481,7 +1482,7 @@ export interface StorageArea {
    */
   get: <Value = string>(key: string, options?: StorageReadOptions) => Value | undefined;
   /**
-   * 判断一个可成功读取且未过期的业务键是否存在。
+   * 判断业务键是否具有有效且未过期的包络；不解码业务值。
    * @param key - 不含全局前缀的非空业务键。
    * @returns 键存在且包络有效时返回 `true`。
    */
@@ -1527,12 +1528,12 @@ export declare const Session: StorageArea;
  *
  * @remarks 不调用时在首次操作上使用 `fast__`、JSON Codec 与 `Date.now`。首次激活后只允许以完全相同的值和引用重复调用。若检测到
  * 全局 `uni`，则自动使用其同步 Storage 且只启用 `Local`，否则使用浏览器 `localStorage` 与 `sessionStorage`。
- * `crypto: true` 仅恢复旧版 Base64 混淆行为，不能保护敏感数据。
- * @param options - 可选的全局键前缀、Codec、旧版混淆选项与时钟。
+ * `crypto: true` 仅执行可逆 Base64 混淆，不能保护敏感数据。
+ * @param options - 可选的全局键前缀、Codec、Base64 混淆选项与时钟。
  * @throws 配置非法、重复配置冲突或目标平台 Storage 不可用时抛出错误。
  */
 export declare function configureStorage(options?: StorageConfiguration): void;
-/** 返回全局 Storage 是否已经由应用入口配置。 */
+/** 返回 Storage 是否已经显式配置，或由首次 Storage 操作激活默认配置。 */
 export declare function isStorageConfigured(): boolean;
 //#endregion
 //#region src/string/index.d.ts