yann-core 0.0.1 → 1.1.0

package/AI_USAGE.md

@@ -0,0 +1,145 @@
+# yann-core：AI 使用指南
+
+供 AI 编码助手在消费 yann-core 时读取。开发人员完整说明见 [README.md](./README.md)。本文描述库使用契约，不是修改仓库的代理工作指令。实际安装版本不同时，以对应版本的声明和实现为准。
+
+## 库与公开入口
+
+- 用途：Vue 响应式状态与浏览器动画帧定时器。
+- Vue peer dependency：`^3.5.13`；包输出 ESM，提供 TypeScript 声明。
+- 安装：`pnpm add yann-core vue@^3.5.13`；已有符合要求的 Vue 时只需添加 `yann-core`。
+- 从公共根入口导入，不生成 `src/`、`dist/` 或内部工具路径导入。
+
+```ts
+import { useState, useRafTimer } from 'yann-core'
+import type {
+  UseStateConfig,
+  UseStateRef,
+  UseStateReturn,
+  Callback,
+  ControlFunctions,
+  RafTimerOptions,
+} from 'yann-core'
+```
+
+公开运行时 API 只有 `useState` 和 `useRafTimer`，不要推测其他 Hook 或工具存在。
+
+## 任务选择
+
+| 需求 | 方案 |
+| --- | --- |
+| 可写 Vue 状态、相等跳过或写入转换 | `useState` |
+| 大对象通过根值替换更新 | `useState(source, { shallow: true })` |
+| 根据 props / getter 持续派生值 | Vue `computed` |
+| 随来源变化同步可写状态 | 显式 Vue `watch` |
+| 浏览器定时任务、串行轮询 | `useRafTimer`，返回或 await 异步任务 |
+| 单次延后任务 | `useRafTimer(callback, delay, { loop: false })` |
+| 服务端或后台可靠调度、精确时钟 | 使用对应环境的调度方案；本 Hook 无 RAF 时不执行 |
+
+## useState 契约
+
+以下是签名摘要，实际声明包含深层、浅层和动态布尔配置的重载：
+
+```ts
+// MaybeRefOrGetter 来自 Vue；返回引用按 shallow 推导
+useState<T>(source: MaybeRefOrGetter<T>, config?: UseStateConfig<T, boolean>)
+// 返回 [state, setState]；setState: (incoming: T) => boolean
+```
+
+1. 脚本用 `state.value` 读值，模板自动解包。setter 接受完整新值，不接受 `(previous) => next` 更新器。
+2. 初始来源通过 Vue `toValue` 解析一次，没有持续同步 watcher，也不深拷贝对象。getter 返回 Ref 时可能复用该 Ref。
+3. `shallow` 默认 `false`：深层 `ref` 解包对象属性中的嵌套 Ref；数组 / Map 遵循 Vue 自身规则。`true` 使用 `shallowRef`，保留普通对象和嵌套 Ref；已有响应式对象保持响应式。
+4. `diff` 默认 `false`。`diff: true` 使用 `Object.is` 或 Lodash `isEqual` 判等。提供 `compare` 就启用比较并替代默认比较，即使 `diff: false` 也如此。
+5. `compare(oldValue, incoming)` 返回 **true 表示相等并跳过**。旧值是状态读取类型，新值是原始输入类型；每次 setter 调用都执行自定义比较器。
+6. setter 顺序：比较旧值与原始输入 → 相等则返回 `false` → `beforeSet(incoming)` 转换 → `unref` 解包根 Ref → 写入并返回 `true`。比较在转换之前。
+7. `true` 表示接受设置，不保证实际变化或视图更新。比较器 / 转换器异常直接传给调用方。
+8. 直接修改 `state.value` 或内部属性会绕过 setter 的比较与转换。比较模式下应构造新对象；原地修改再传同一对象无法比较修改前的快照。
+9. 浅层普通对象内部修改不触发根引用更新；优先替换根值，或显式使用 Vue `triggerRef`。
+
+```ts
+const [count, setCount] = useState(0)
+setCount(count.value + 1)
+
+const [rows, setRows] = useState<Array<{ id: number }>>([], { shallow: true })
+setRows([...rows.value, { id: 1 }])
+
+const [value, setValue] = useState(2, {
+  diff: true,
+  beforeSet: (incoming) => incoming * 2,
+})
+setValue(2) // false，转换不执行
+setValue(1) // true，转换后仍是 2
+```
+
+`UseStateConfig<T, Shallow>`、`UseStateRef<T, Shallow>`、`UseStateReturn<T, Shallow>` 的第二个参数默认 `false`；浅层用 `true`，动态开关用 `boolean`。不要用类型断言掩盖嵌套 Ref 解包差异。
+
+## useRafTimer 契约
+
+```ts
+type Callback = () => void | PromiseLike<void>
+interface ControlFunctions {
+  stop: () => void
+  pause: () => void
+  start: () => void
+}
+interface RafTimerOptions {
+  type?: 'waitAfterCallback' | 'ignoreCallbackTime'
+  loop?: boolean | number
+  onError?: (error: unknown) => void | PromiseLike<void>
+}
+// interval 默认 1000 / 60 毫秒
+useRafTimer(callback: Callback, interval?: number, options?: RafTimerOptions): ControlFunctions
+```
+
+- 自动启动，首次回调在间隔到期后的动画帧执行，不立即执行。立即加载数据应由业务显式实现。
+- 默认 `type: 'ignoreCallbackTime'`、`loop: true`。普通请求轮询可选 `waitAfterCallback`，在回调及错误报告完成后再等待完整间隔。
+- `ignoreCallbackTime` 从本次开始计算下一次间隔，但仍等待当前异步回调结束；不会并发，也不补发遗漏次数。
+- 必须返回 Promise / thenable 才能被等待。不要生成 `() => { void fetchData() }` 并声称它串行等待请求。
+- `pause()` 冻结计时，保留剩余等待时间；`start()` 仅恢复暂停；`stop()` 永久停止，之后 `start()` 无效。恢复停止的任务必须新建实例。
+- 控制器没有 `resume`、`restart`、`isRunning` 或动态更新间隔等 API，不要虚构。
+- `loop: false` 一次；`true` 或 `Infinity` 无限；有限数字向上取整且至少一次（`0` 和负有限数也是一次）。失败尝试也计入次数。
+- interval 必须有限且非负，零间隔每帧最多一次；无效数值抛 `RangeError`。loop 的 `NaN` / 负无穷也抛 `RangeError`。
+- 回调异常通过 `onError` 或默认 `console.error` 报告后继续。异步错误处理器会被等待，其自身异常被捕获并记录。
+- 缺少 RAF 或 cancelRAF 时返回空操作控制器，不执行回调，参数校验仍执行。不要宣称 SSR / Node 中自动降级为可执行的 timeout 定时器。
+- 活跃 Vue effect scope 中同步创建会注册自动清理；作用域外需要手动停止。不要依赖异步 await 后创建时的自动清理。
+- 停止不取消正在运行的 Promise，也不阻止已开始的回调写回数据；按业务需要用 `AbortController` 和销毁标记管理取消及结果保护。
+- 精度受帧率与后台限流影响，长等待结合 timeout 与 RAF；不能承诺精确时间或后台可靠执行。
+
+## 可采用的 Vue 示例
+
+```vue
+<script setup lang="ts">
+import { useRafTimer, useState } from 'yann-core'
+
+const [count, setCount] = useState(0)
+const timer = useRafTimer(() => {
+  setCount(count.value + 1)
+}, 1000, { loop: true })
+</script>
+
+<template>
+  <p>{{ count }}</p>
+  <button @click="timer.pause">暂停</button>
+  <button @click="timer.start">恢复</button>
+  <button @click="timer.stop">永久停止</button>
+</template>
+```
+
+请求轮询及取消的完整示例见 [README 生命周期与取消请求](./README.md#生命周期与取消请求)。生成实际请求代码时，应按业务声明数据类型、检查 HTTP 状态，并确定卸载后是否允许结果写回。
+
+## 生成代码前核对
+
+- 只从公共入口导入已公开 API。
+- setter 使用新值；比较器 true 意味相等跳过；beforeSet 在比较之后执行。
+- 深层与浅层嵌套 Ref 访问方式正确，浅层更新通过替换根值或 triggerRef。
+- 没有把初始化 getter 写成持续同步机制。
+- 定时器自动启动且首次不立即执行，暂停、恢复、永久停止的交互语义正确。
+- 异步回调返回或 await 任务；作用域外显式清理；请求取消由业务自行管理。
+- 不将 setter 返回值解释为实际渲染，不承诺精确时钟、SSR 执行或 Promise 自动取消。
+
+## 仓库内核对依据
+
+API 以 [公共入口](./src/index.ts)、[状态实现](./src/useState/index.ts)、[定时器实现](./src/useTimer/index.ts) 为准。类型边界见 [状态类型用例](./tests/state.types.ts)，行为见 [状态测试](./tests/useState.test.ts) 与 [定时器测试](./tests/useTimer.test.ts)。内部 `src/utils/` 的函数不是公开 API。
+
+在本仓库改动示例或 API 后可运行 `pnpm type-check`、`pnpm test`；核对发布产物时先 `pnpm build`，再 `pnpm verify:package`。消费项目应运行自己的类型检查与测试。
+
+当前 `package.json` 的 `files` 仅包含 `dist`；本文供从仓库读取或作为上下文提供给 AI，不要假定 npm 安装目录包含此文件。

package/README.md

@@ -1,15 +1,234 @@
 # yann-core
 
-## Timer
+面向 Vue 3.5 的 TypeScript 工具库，提供支持异步回调、暂停和作用域清理的定时器，以及带差异比较和写入转换的响应式状态。
+
+| API | 用途 |
+| --- | --- |
+| `useRafTimer` | 按指定间隔执行同步或异步任务 |
+| `useState` | 创建状态，通过 setter 比较、转换和写入新值 |
+
+AI 编码助手请同时阅读 [AI 使用指南](./AI_USAGE.md)。
+
+## 安装与环境
+
+```sh
+pnpm add yann-core vue@^3.5.13
+# 或：npm install yann-core vue@^3.5.13
+```
+
+Vue 是 peer dependency，版本要求为 `^3.5.13`，使用项目自身的 Vue 实例。包输出为 ESM，附带 TypeScript 声明；统一从 `yann-core` 根入口导入。
+
+定时器依赖浏览器的 `requestAnimationFrame` 和 `cancelAnimationFrame`。缺少任一 API 时（如通常的 SSR 环境），返回空操作控制器，不执行回调。
+
+## 快速开始
+
+在 Vue 单文件组件的 `<script setup>` 中同步创建 Hook，定时器会随组件作用域销毁自动停止。
+
+```vue
+<script setup lang="ts">
+import { useRafTimer, useState } from 'yann-core'
+
+const [count, setCount] = useState(0)
+const timer = useRafTimer(() => {
+  setCount(count.value + 1)
+}, 1000)
+</script>
+
+<template>
+  <p>计数：{{ count }}</p>
+  <button @click="timer.pause">暂停</button>
+  <button @click="timer.start">恢复</button>
+  <button @click="timer.stop">永久停止</button>
+</template>
+```
+
+创建后自动开始，首次回调需等待间隔到期。`start()` 恢复暂停，停止后需要重新创建定时器。
+
+## 定时器
+
+```ts
+import { useRafTimer } from 'yann-core'
+
+const timer = useRafTimer(async () => {
+  const response = await fetch('/api/status')
+  if (!response.ok) throw new Error(`请求失败：${response.status}`)
+  // 在这里处理返回结果
+}, 1000, {
+  type: 'ignoreCallbackTime',
+  loop: true,
+  onError: (error) => console.error(error),
+})
+
+timer.pause()
+timer.start() // 恢复暂停
+timer.stop() // 永久停止；start 不会重新启动
+```
+
+### 参数与控制方法
+
+```ts
+useRafTimer(callback, interval?, options?)
+```
+
+| 参数 / 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `callback` | 必填 | `() => void \| PromiseLike<void>`，同步回调或返回 Promise / thenable 的异步回调 |
+| `interval` | `1000 / 60` | 毫秒，有限非负数；零间隔每帧最多执行一次 |
+| `options.type` | `'ignoreCallbackTime'` | 从本次回调开始计算下一次间隔；`'waitAfterCallback'` 从回调及错误报告完成后计算 |
+| `options.loop` | `true` | `true` / `Infinity` 无限循环，`false` 一次，有限数字向上取整且至少一次 |
+| `options.onError` | 无 | `(error: unknown) => void \| PromiseLike<void>`，未提供时使用 `console.error` |
+
+| 方法 | 行为 |
+| --- | --- |
+| `pause()` | 暂停并冻结计时，保留剩余等待时间；不取消正在执行的异步任务 |
+| `start()` | 从暂停处恢复；若回调尚未完成，继续等待，不会重入 |
+| `stop()` | 永久停止并清理待调度任务；不能通过 `start()` 重启 |
+
+### 调度与错误行为
+
+- 创建后自动开始，首次执行在间隔到期后的动画帧；默认间隔为 `1000 / 60` 毫秒。
+- `ignoreCallbackTime`：从本次回调开始计算间隔；`waitAfterCallback`：从回调及错误报告完成后计算间隔。
+- 每个实例最多执行一个回调，支持 Promise 和 thenable。长回调完成后若已过期，只在下一帧执行一次，不补发遗漏次数。
+- 暂停冻结计时；恢复时仍等待尚未完成的回调。`stop` 和 Vue 作用域销毁会清理待调度任务并释放回调引用；用户创建的 Promise 不会自动取消。
+- 异常报告后继续，未配置 `onError` 时使用 `console.error`。异步 `onError` 也会等待；报告器失败会捕获并记录。每次回调尝试，包括失败，都计入次数。
+- `loop: true` 或 `Infinity` 无限循环，`false` 执行一次；有限数字向上取整且至少一次。`NaN` 和负无穷非法。
+- 间隔必须是有限非负数；零间隔每帧最多执行一次。超长延时分段等待。无 RAF 环境（如 SSR）返回无操作的控制方法，不执行回调。
+- 长间隔由 timeout 等待，距离截止时间 20ms 内由 RAF 检查。实际执行精度受帧率和浏览器后台限流影响。
+
+回调必须返回 Promise / thenable 才能被等待；不要在回调中只启动异步任务而不返回，例如 `() => { void fetchData() }`。需要串行轮询时，使用 `async` 回调并 `await` 请求，通常选择 `waitAfterCallback`。
+
+非法间隔或 `loop: NaN` / `loop: -Infinity` 会抛出 `RangeError`；无 RAF 环境中也会先校验参数。控制器只有 `stop`、`pause`、`start`，没有运行状态 Ref 或动态修改间隔的方法。本 Hook 不适合作为精确时钟或服务端调度器。
+
+### 生命周期与取消请求
+
+在活跃 Vue effect scope 中同步创建时，作用域销毁会自动停止。在组件外、作用域外或异步 `await` 之后创建时，不应假定自动清理，应自行调用 `stop()`。
+
+停止不会取消用户创建的 Promise，也不会阻止已开始的回调继续写回数据。请求取消与结果保护由业务管理：
+
+```ts
+import { onScopeDispose } from 'vue'
+import { useRafTimer, useState } from 'yann-core'
+
+// 在 setup 或活跃 effect scope 内同步执行
+const [status, setStatus] = useState<unknown>(null)
+const controller = new AbortController()
+let disposed = false
+
+const timer = useRafTimer(async () => {
+  const response = await fetch('/api/status', { signal: controller.signal })
+  if (!response.ok) throw new Error(`请求失败：${response.status}`)
+  const data: unknown = await response.json()
+  if (!disposed) setStatus(data)
+}, 1000, { type: 'waitAfterCallback' })
+
+const dispose = () => {
+  disposed = true
+  timer.stop()
+  controller.abort()
+}
+onScopeDispose(dispose)
+// 如需主动结束轮询，也调用 dispose()
+```
+
+## 状态
+
+`useState(source, config?)` 返回 `[state, setState]`。输入为普通值、Vue Ref 或 getter；`state` 是 Vue 响应式引用，在脚本中通过 `.value` 读取，在模板中自动解包。
 
 ```ts
-const timer = useRafTimer(()=>{
-    console.log('tick');
-},1000);
+import { useState } from 'yann-core'
+
+const [state, setState] = useState(0)
+setState(1)
+
+const [rows, setRows] = useState([{ id: 1 }], { shallow: true })
+setRows([{ id: 2 }]) // 替换 .value 触发更新
+```
+
+### 配置与更新规则
+
+| 配置 | 默认值 | 说明 |
+| --- | --- | --- |
+| `shallow` | `false` | `true` 使用 `shallowRef`，否则使用深层 `ref` |
+| `diff` | `false` | 启用相等比较，相等时跳过设置 |
+| `compare(oldValue, incoming)` | 无 | 自定义比较；返回 `true` 表示相等。提供后即启用比较，不必设置 `diff` |
+| `beforeSet(incoming)` | 无 | 接受原始输入，返回加工后的新值；仅在比较未跳过时调用 |
+
+setter 接受完整新值，不支持 React 风格的 `setState(previous => next)` 更新器。直接修改 `state.value` 或内部属性会绕过比较与转换。比较模式下应构造新对象；原地修改后传同一对象，默认比较无法检测修改前的内容。
+
+### 深层、浅层与初始化来源
+
+默认使用深层响应式 `ref`，对象属性中的嵌套 Ref 会解包；数组和 Map 中的 Ref 遵循 Vue 自身的规则。`shallow: true` 使用 `shallowRef`，保留输入对象与嵌套 Ref，不为普通对象增加深层代理。已有响应式对象不会被转换回普通对象。浅层内部修改需替换对象或使用 Vue 的 `triggerRef`。
+
+普通值、Ref 和 getter 只在初始化时求值一次，不持续同步源。若 getter 返回 Ref，则遵循 Vue 工厂的 Ref 复用行为；setter 收到根 Ref 时取其内部值再写入，保持读取类型与运行结果一致。比较与 `beforeSet` 仍接收原始输入。
+
+例如 `useState(() => props.initialCount)` 只读取初始值；持续派生值用 Vue `computed`，持续同步可写状态用显式 `watch`。状态不是输入对象的深拷贝。
+
+```ts
+import { ref, triggerRef } from 'vue'
+
+const [deep] = useState({ nested: ref(1) })
+console.log(deep.value.nested) // 1
+
+const [shallow] = useState({ nested: ref(1) }, { shallow: true })
+console.log(shallow.value.nested.value) // 1
+
+const [items] = useState([{ id: 1 }], { shallow: true })
+items.value.push({ id: 2 })
+triggerRef(items) // 普通浅层对象内部修改后，手动通知依赖
 ```
 
-## State
+### 比较顺序与类型
 
 ```ts
-const [state, setState] = useState(0);
-```
+const [value, setValue] = useState(2, {
+  diff: true,
+  beforeSet: (incoming) => incoming * 2,
+})
+setValue(2) // false：比较相等，beforeSet 不执行
+setValue(1) // true：先比较原始输入，再转换为 2
+```
+
+`diff: true` 默认深比较（支持数组、Map、循环引用），先做引用相等快速判断。提供 `compare(oldValue, newValue)` 时始终调用自定义比较器，并启用比较流程，即使未设置 `diff`。旧值类型与状态读取类型一致，新值和 `beforeSet` 使用原始输入类型。
+
+完整顺序：**比较旧值与原始输入 → 相等则跳过 → beforeSet 转换 → 根 Ref 解包 → 写入**。比较器与转换器抛出的异常会传给调用方。
+
+```ts
+import type { UseStateConfig, UseStateReturn } from 'yann-core'
+
+type User = { id: number; name: string }
+const config: UseStateConfig<User> = {
+  compare: (oldValue, incoming) =>
+    oldValue.id === incoming.id && oldValue.name === incoming.name,
+}
+const result: UseStateReturn<User> = useState({ id: 1, name: 'Alice' }, config)
+result[1]({ id: 1, name: 'Alice' }) // false
+result[1]({ id: 1, name: 'Bob' }) // true
+```
+
+setter 返回 `false` 表示比较判定相等而跳过设置，返回 `true` 表示接受设置；未启用比较时，即使 Vue 本身不触发更新，也返回 `true`。类型从根入口导出：`UseStateConfig<T, Shallow>`、`UseStateRef<T, Shallow>`、`UseStateReturn<T, Shallow>`、`Callback`、`ControlFunctions`、`RafTimerOptions`。状态类型第二个参数默认 `false`，动态布尔选项使用 `boolean`。
+
+类型纠错可能使依赖旧声明的代码报错：深层模式的对象 Ref 属性应读取 `state.value.nested`，而不是 `state.value.nested.value`；比较器旧值同样遵循解包类型。
+
+## 验证
+
+以下命令用于维护本仓库；消费项目运行自己的构建和类型检查。
+
+```sh
+pnpm install --frozen-lockfile
+pnpm type-check
+pnpm lint:check
+pnpm test
+pnpm build
+pnpm verify:package
+pnpm benchmark
+```
+
+`type-check` 同时编译运行测试和类型回归用例；`lint:check` 不修改文件。`verify:package` 检查打包后的 ESM、NodeNext/Bundler 类型消费和仅导入定时器时的 tree shaking。基准需要支持 `require(ESM)` 的 Node 22.12+ 及 Git 基线历史；可用 `YANN_BASELINE_REVISION` 指定比较提交。结果写入忽略的 `artifacts/`，方法和实测结果见 [PERFORMANCE.md](./PERFORMANCE.md)。
+
+构建内存与体积可用 `node scripts/measure-build.mjs optimized` 记录；该命令清理 TypeScript 增量缓存以测量冷类型检查。不自动发布版本。
+
+公共入口为 `src/index.ts`，Hook 位于 `src/useState/` 与 `src/useTimer/`，行为与类型用例位于 `tests/`。`build` 包含类型检查，输出 ESM 和类型声明到 `dist/`；`verify:package` 应在构建后运行。
+
+## 许可证
+
+[MIT](./LICENSE)