@yunzai-ng/core 0.1.0

package/src/util/deep.ts

@@ -0,0 +1,272 @@
+/**
+ * 模块职责：对象深操作（合并、克隆、按路径读写、差异路径计算）
+ * 依赖方向：无
+ * 生命周期：纯函数
+ * 注意事项：配置系统的地基。`diffPaths` 算出实际变化的叶子路径，故配置变更只通知
+ *          关心那些路径的订阅者，而不是让每个读配置的地方全量重算。
+ *
+ *          **数组是整体替换，不逐元素合并。** 配置里的数组（主人列表、黑名单）语义上是
+ *          "一个值"，逐元素合并会让使用者无法删除默认项。
+ */
+
+/** 可作为配置节点的普通对象 */
+export type PlainObject = Record<string, unknown>
+
+/**
+ * 判断是否为普通对象（排除数组、null、Date、Buffer、类实例等）
+ * @param value 待判定值
+ * @returns 是否为普通对象
+ */
+export function isPlainObject(value: unknown): value is PlainObject {
+  if (value === null || typeof value !== "object") return false
+  if (Array.isArray(value)) return false
+  const proto = Object.getPrototypeOf(value) as object | null
+  return proto === Object.prototype || proto === null
+}
+
+/**
+ * 深克隆
+ *
+ * 优先用 `structuredClone`（Node 17+ 内置，能处理 Map/Set/Date/循环引用），
+ * 遇到函数等不可克隆值时退回浅拷贝语义。
+ * @param value 源值
+ * @returns 克隆结果
+ */
+export function deepClone<T>(value: T): T {
+  try {
+    return structuredClone(value)
+  } catch {
+    return cloneFallback(value)
+  }
+}
+
+/**
+ * structuredClone 失败时的回退克隆（跳过不可克隆值）
+ * @param value 源值
+ * @returns 克隆结果
+ */
+function cloneFallback<T>(value: T): T {
+  if (Array.isArray(value)) return value.map(item => cloneFallback(item)) as unknown as T
+  if (isPlainObject(value)) {
+    const out: PlainObject = {}
+    for (const [k, v] of Object.entries(value)) out[k] = cloneFallback(v)
+    return out as T
+  }
+  return value
+}
+
+/**
+ * 深合并：把 `source` 覆盖到 `target` 的副本上
+ *
+ * - 普通对象递归合并
+ * - 数组、`Date` 等整体替换
+ * - `source` 中值为 `undefined` 的键被忽略（不会把 target 的值抹成 undefined）
+ * @param target 基准值（不被修改）
+ * @param source 覆盖值
+ * @returns 合并后的新对象
+ */
+export function deepMerge<T extends PlainObject>(target: T, source: PlainObject | undefined): T {
+  if (!source) return deepClone(target)
+  const out: PlainObject = deepClone(target) as PlainObject
+
+  for (const [key, value] of Object.entries(source)) {
+    if (value === undefined) continue
+    // 拒绝原型链污染：合并的数据可能来自 WebUI 提交的 JSON
+    if (key === "__proto__" || key === "constructor" || key === "prototype") continue
+
+    const existing = out[key]
+    if (isPlainObject(value) && isPlainObject(existing)) {
+      out[key] = deepMerge(existing, value)
+    } else {
+      out[key] = deepClone(value)
+    }
+  }
+  return out as T
+}
+
+/**
+ * 深比较
+ * @param a 左值
+ * @param b 右值
+ * @returns 是否深度相等
+ */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true
+  if (typeof a !== typeof b) return false
+  if (a === null || b === null) return false
+
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false
+    return a.every((item, i) => deepEqual(item, b[i]))
+  }
+
+  if (a instanceof Date || b instanceof Date) {
+    return a instanceof Date && b instanceof Date && a.getTime() === b.getTime()
+  }
+
+  if (typeof a === "object" && typeof b === "object") {
+    const ao = a as PlainObject
+    const bo = b as PlainObject
+    const aKeys = Object.keys(ao)
+    const bKeys = Object.keys(bo)
+    if (aKeys.length !== bKeys.length) return false
+    return aKeys.every(k => Object.prototype.hasOwnProperty.call(bo, k) && deepEqual(ao[k], bo[k]))
+  }
+
+  return false
+}
+
+/**
+ * 把点分路径切成键数组
+ *
+ * 支持 `a.b[0].c` 与 `a.b.0.c` 两种写法。
+ * @param path 路径字符串
+ * @returns 键数组
+ */
+export function splitPath(path: string): string[] {
+  if (path === "") return []
+  return path
+    .replace(/\[(\d+)\]/g, ".$1")
+    .split(".")
+    .filter(seg => seg !== "")
+}
+
+/**
+ * 按路径取值
+ * @param obj 源对象
+ * @param path 点分路径；空串返回 obj 本身
+ * @returns 值；路径不存在时 undefined
+ */
+export function getPath(obj: unknown, path: string): unknown {
+  const keys = splitPath(path)
+  let cur: unknown = obj
+  for (const key of keys) {
+    if (cur === null || cur === undefined) return undefined
+    if (typeof cur !== "object") return undefined
+    cur = (cur as PlainObject)[key]
+  }
+  return cur
+}
+
+/**
+ * 按路径写值（原地修改）
+ *
+ * 中间层不存在时自动创建：下一级键是纯数字则建数组，否则建对象。
+ * @param obj 目标对象
+ * @param path 点分路径
+ * @param value 值
+ * @throws 当路径为空或中间层是不可写入的标量时
+ */
+export function setPath(obj: PlainObject, path: string, value: unknown): void {
+  const keys = splitPath(path)
+  if (keys.length === 0) throw new Error("setPath: 路径不能为空")
+
+  let cur: PlainObject | unknown[] = obj
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i]!
+    if (key === "__proto__" || key === "constructor" || key === "prototype") {
+      throw new Error(`setPath: 非法路径片段 ${key}`)
+    }
+    const next = (cur as PlainObject)[key]
+    if (isPlainObject(next) || Array.isArray(next)) {
+      cur = next as PlainObject | unknown[]
+    } else if (next === undefined || next === null) {
+      const created: PlainObject | unknown[] = /^\d+$/.test(keys[i + 1]!) ? [] : {}
+      ;(cur as PlainObject)[key] = created
+      cur = created
+    } else {
+      throw new Error(`setPath: ${keys.slice(0, i + 1).join(".")} 已是标量，无法继续写入`)
+    }
+  }
+
+  const last = keys[keys.length - 1]!
+  if (last === "__proto__" || last === "constructor" || last === "prototype") {
+    throw new Error(`setPath: 非法路径片段 ${last}`)
+  }
+  ;(cur as PlainObject)[last] = value
+}
+
+/**
+ * 按路径删除（原地修改）
+ * @param obj 目标对象
+ * @param path 点分路径
+ * @returns 是否确实删掉了什么
+ */
+export function deletePath(obj: PlainObject, path: string): boolean {
+  const keys = splitPath(path)
+  if (keys.length === 0) return false
+
+  const parentPath = keys.slice(0, -1).join(".")
+  const parent = parentPath === "" ? obj : getPath(obj, parentPath)
+  if (parent === null || typeof parent !== "object") return false
+
+  const last = keys[keys.length - 1]!
+  if (Array.isArray(parent)) {
+    const index = Number(last)
+    if (!Number.isInteger(index) || index < 0 || index >= parent.length) return false
+    parent.splice(index, 1)
+    return true
+  }
+  if (!Object.prototype.hasOwnProperty.call(parent, last)) return false
+  delete (parent as PlainObject)[last]
+  return true
+}
+
+/**
+ * 计算两个对象间发生变化的**叶子路径**
+ *
+ * 这是细粒度配置失效的核心：改了 `bot.masterQQ` 就只通知订阅
+ * `bot.masterQQ`（或其祖先 `bot`）的人，不打扰订阅 `render.*` 的人。
+ *
+ * 数组视为叶子（整体变化），不下钻元素。
+ * @param before 旧值
+ * @param after 新值
+ * @param prefix 内部递归用的路径前缀
+ * @returns 变化路径列表，已去重
+ */
+export function diffPaths(before: unknown, after: unknown, prefix = ""): string[] {
+  if (deepEqual(before, after)) return []
+
+  // 任一侧不是普通对象 → 当前节点整体变化
+  if (!isPlainObject(before) || !isPlainObject(after)) {
+    return prefix === "" ? [""] : [prefix]
+  }
+
+  const out: string[] = []
+  const keys = new Set([...Object.keys(before), ...Object.keys(after)])
+  for (const key of keys) {
+    const path = prefix === "" ? key : `${prefix}.${key}`
+    out.push(...diffPaths(before[key], after[key], path))
+  }
+  return out
+}
+
+/**
+ * 判断某条变化路径是否影响到订阅路径
+ *
+ * 双向前缀匹配：改 `bot` 影响订阅 `bot.masterQQ` 的人（父变子受影响），
+ * 改 `bot.masterQQ` 也影响订阅 `bot` 的人（子变父受影响）。
+ * @param changed 发生变化的路径
+ * @param watched 订阅的路径；空串表示订阅全部
+ * @returns 是否受影响
+ */
+export function pathAffects(changed: string, watched: string): boolean {
+  if (watched === "" || changed === "") return true
+  if (changed === watched) return true
+  return changed.startsWith(`${watched}.`) || watched.startsWith(`${changed}.`)
+}
+
+/**
+ * 摘出对象里的指定路径，组成新对象
+ * @param obj 源对象
+ * @param paths 路径列表
+ * @returns 只含这些路径的新对象
+ */
+export function pickPaths(obj: PlainObject, paths: readonly string[]): PlainObject {
+  const out: PlainObject = {}
+  for (const path of paths) {
+    const value = getPath(obj, path)
+    if (value !== undefined) setPath(out, path, deepClone(value))
+  }
+  return out
+}

package/src/util/defer.ts

@@ -0,0 +1,211 @@
+/**
+ * 模块职责：Promise 原语（外部可控 Promise、超时、休眠、重试）
+ * 依赖方向：仅依赖类型包
+ * 生命周期：纯函数 / 短生命周期对象
+ * 注意事项：所有会挂起的等待均必须可被取消，否则热重载时插件已卸载、
+ *          而 Promise 仍持有定时器，即构成内存泄漏。因此 `Deferred` 暴露
+ *          `reject`，`withTimeout` 必定清除 timer，`sleep` 支持 signal。
+ */
+
+/** 超时错误：与普通业务错误相区分，便于上层决定"重试"或"放弃" */
+export class TimeoutError extends Error {
+  /** 错误名，便于 `err.name === "TimeoutError"` 判定 */
+  override readonly name = "TimeoutError"
+
+  /**
+   * @param message 错误信息
+   */
+  constructor(message = "操作超时") {
+    super(message)
+  }
+}
+
+/** 中止错误：signal 触发时抛出 */
+export class AbortError extends Error {
+  /** 错误名 */
+  override readonly name = "AbortError"
+
+  /**
+   * @param message 错误信息
+   */
+  constructor(message = "操作已被取消") {
+    super(message)
+  }
+}
+
+/** 外部可控的 Promise */
+export interface Deferred<T> {
+  /** Promise 本体 */
+  readonly promise: Promise<T>
+  /**
+   * 兑现
+   * @param value 结果值
+   */
+  resolve(value: T | PromiseLike<T>): void
+  /**
+   * 拒绝
+   * @param reason 原因
+   */
+  reject(reason?: unknown): void
+  /** 是否已结束（兑现或拒绝） */
+  readonly settled: boolean
+}
+
+/**
+ * 创建外部可控的 Promise
+ *
+ * 用于把"回调/事件"风格的等待（如适配器 echo 应答、`e.prompt`）转成 await。
+ * 重复调用 resolve/reject 会被忽略，不会抛错。
+ * @returns Deferred 句柄
+ */
+export function defer<T>(): Deferred<T> {
+  let resolveFn!: (value: T | PromiseLike<T>) => void
+  let rejectFn!: (reason?: unknown) => void
+  let settled = false
+
+  const promise = new Promise<T>((res, rej) => {
+    resolveFn = res
+    rejectFn = rej
+  })
+
+  return {
+    promise,
+    resolve(value) {
+      if (settled) return
+      settled = true
+      resolveFn(value)
+    },
+    reject(reason) {
+      if (settled) return
+      settled = true
+      rejectFn(reason)
+    },
+    get settled() {
+      return settled
+    }
+  }
+}
+
+/**
+ * 休眠
+ * @param ms 毫秒
+ * @param signal 可选中止信号；触发时以 AbortError 拒绝
+ * @returns 到期后兑现
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  if (ms <= 0) return Promise.resolve()
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new AbortError())
+      return
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort)
+      resolve()
+    }, ms)
+    // Node 下 unref 让"只剩一个 sleep"时进程仍能退出
+    if (typeof timer.unref === "function") timer.unref()
+
+    /** 中止回调 */
+    function onAbort(): void {
+      clearTimeout(timer)
+      reject(new AbortError())
+    }
+    signal?.addEventListener("abort", onAbort, { once: true })
+  })
+}
+
+/**
+ * 给 Promise 套超时
+ *
+ * 注意：超时只是让调用方不再等待，**并不能真正取消**底层操作。需要真取消
+ * 的场景（HTTP 请求）请把 signal 传给底层。
+ * @param promise 被包装的 Promise
+ * @param ms 超时毫秒；<=0 表示不限时
+ * @param message 超时错误信息
+ * @returns 原结果，或以 TimeoutError 拒绝
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T> {
+  if (ms <= 0) return promise
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(() => reject(new TimeoutError(message)), ms)
+    if (typeof timer.unref === "function") timer.unref()
+    promise.then(
+      value => {
+        clearTimeout(timer)
+        resolve(value)
+      },
+      reason => {
+        clearTimeout(timer)
+        reject(reason)
+      }
+    )
+  })
+}
+
+/** 重试选项 */
+export interface RetryOptions {
+  /** 最大尝试次数（含首次），缺省 3 */
+  attempts?: number
+  /** 首次退避毫秒，缺省 500 */
+  baseDelay?: number
+  /** 退避上限毫秒，缺省 30000 */
+  maxDelay?: number
+  /** 退避倍率，缺省 2 */
+  factor?: number
+  /** 抖动比例 0~1，缺省 0.2；用于避免多账号重连时步调一致而对服务端造成过载 */
+  jitter?: number
+  /** 中止信号 */
+  signal?: AbortSignal
+  /**
+   * 每次失败后的回调
+   * @param err 本次错误
+   * @param attempt 已尝试次数（从 1 开始）
+   * @param delay 即将等待的毫秒
+   */
+  onRetry?: (err: unknown, attempt: number, delay: number) => void
+}
+
+/**
+ * 计算指数退避（带抖动）的等待时长
+ * @param attempt 已尝试次数（从 1 开始）
+ * @param opts 退避参数
+ * @returns 毫秒
+ */
+export function backoffDelay(attempt: number, opts: RetryOptions = {}): number {
+  const base = opts.baseDelay ?? 500
+  const factor = opts.factor ?? 2
+  const max = opts.maxDelay ?? 30_000
+  const jitter = opts.jitter ?? 0.2
+
+  const raw = Math.min(max, base * factor ** Math.max(0, attempt - 1))
+  // 抖动只往下浮动，保证不会超过 maxDelay
+  const delta = raw * jitter * Math.random()
+  return Math.round(raw - delta)
+}
+
+/**
+ * 带指数退避的重试
+ * @param task 任务；参数为已尝试次数（从 1 开始）
+ * @param opts 重试选项
+ * @returns 任务结果
+ * @throws 最后一次的错误
+ */
+export async function retry<T>(task: (attempt: number) => Promise<T>, opts: RetryOptions = {}): Promise<T> {
+  const attempts = Math.max(1, opts.attempts ?? 3)
+  let lastError: unknown
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    if (opts.signal?.aborted) throw new AbortError()
+    try {
+      return await task(attempt)
+    } catch (err) {
+      lastError = err
+      if (attempt >= attempts) break
+      const delay = backoffDelay(attempt, opts)
+      opts.onRetry?.(err, attempt, delay)
+      await sleep(delay, opts.signal)
+    }
+  }
+  throw lastError
+}

package/src/util/dispose.ts

@@ -0,0 +1,169 @@
+/**
+ * 模块职责：资源回收登记簿
+ * 依赖方向：依赖类型包的 Disposer
+ * 生命周期：与其宿主（插件实例 / 账号连接 / 应用）同寿
+ * 注意事项：**内核提供给插件的每一个注册型 API 都返回 Disposer**，并自动登记到该插件的
+ *          registry。插件卸载时逆序全量回收，故插件作者不需要（也无从忘记）手工清理 ——
+ *          否则改十次代码就有十份定时器在跑同一件事。
+ *
+ *          逆序回收是有意的：后注册的往往依赖先注册的（如先 provide 服务再
+ *          注册用到它的命令），倒着拆才不会拆到一半引用空对象。
+ */
+import type { Disposer } from "@yunzai-ng/types"
+
+/** 回收过程中收集到的错误 */
+export interface DisposeFailure {
+  /** 登记时的标签 */
+  label: string
+  /** 抛出的错误 */
+  error: unknown
+}
+
+/**
+ * 资源回收登记簿
+ *
+ * 线程模型：同进程单线程，无需加锁；但 `dispose()` 可能重入
+ * （插件在 disposer 里又触发卸载），故有 `#disposed` 幂等保护。
+ */
+export class DisposalRegistry {
+  /** 登记的回收器，按登记顺序存放 */
+  readonly #entries: { label: string; dispose: Disposer }[] = []
+  /** 是否已回收 */
+  #disposed = false
+  /** 归属标识，仅用于日志 */
+  readonly #owner: string
+
+  /**
+   * @param owner 归属标识（插件名等），出错时用于定位
+   */
+  constructor(owner: string) {
+    this.#owner = owner
+  }
+
+  /** 是否已回收 */
+  get disposed(): boolean {
+    return this.#disposed
+  }
+
+  /** 尚未回收的登记项数量 */
+  get size(): number {
+    return this.#entries.length
+  }
+
+  /**
+   * 登记一个回收器
+   *
+   * 若 registry 已回收，传入的 disposer 会**立即执行** —— 这防止"卸载竞态"：
+   * 异步初始化的插件在卸载后才完成注册，资源没人回收。
+   * @param dispose 回收函数
+   * @param label 标签，用于报错定位
+   * @returns 取消登记并执行回收的函数；重复调用无副作用
+   */
+  add(dispose: Disposer, label = "anonymous"): Disposer {
+    if (this.#disposed) {
+      this.#runOne({ label, dispose })
+      return () => undefined
+    }
+
+    const entry = { label, dispose }
+    this.#entries.push(entry)
+
+    let done = false
+    return () => {
+      if (done) return
+      done = true
+      const index = this.#entries.indexOf(entry)
+      if (index >= 0) this.#entries.splice(index, 1)
+      this.#runOne(entry)
+    }
+  }
+
+  /**
+   * 登记一个 `Map`/`Set` 条目的清理
+   * @param collection 容器
+   * @param key 键
+   * @param label 标签
+   * @returns 回收函数
+   */
+  addEntry<K>(collection: { delete(key: K): unknown }, key: K, label = "entry"): Disposer {
+    return this.add(() => void collection.delete(key), label)
+  }
+
+  /**
+   * 登记一个定时器
+   *
+   * 顺带 `unref`，让"只剩定时器"时进程能正常退出。
+   * @param timer 定时器句柄
+   * @param label 标签
+   * @returns 回收函数
+   */
+  addTimer(timer: NodeJS.Timeout, label = "timer"): Disposer {
+    if (typeof timer.unref === "function") timer.unref()
+    return this.add(() => clearTimeout(timer), label)
+  }
+
+  /**
+   * 创建从属子登记簿
+   *
+   * 父簿回收时自动带走子簿。用于"插件里的账号连接"这类嵌套生命周期。
+   * @param owner 子簿归属标识
+   * @returns 子登记簿
+   */
+  child(owner: string): DisposalRegistry {
+    const sub = new DisposalRegistry(`${this.#owner}/${owner}`)
+    this.add(() => void sub.dispose(), `child:${owner}`)
+    return sub
+  }
+
+  /**
+   * 逆序回收全部登记项
+   *
+   * 单个 disposer 抛错**不会**中断后续回收 —— 一个插件写错清理逻辑不应该
+   * 导致其余资源全部泄漏。所有错误汇总返回，由调用方（插件宿主）记日志。
+   * @returns 回收过程中发生的错误列表；无错时为空数组
+   */
+  dispose(): DisposeFailure[] {
+    if (this.#disposed) return []
+    this.#disposed = true
+
+    const failures: DisposeFailure[] = []
+    // 逆序：后注册的可能依赖先注册的
+    for (let i = this.#entries.length - 1; i >= 0; i--) {
+      const failure = this.#runOne(this.#entries[i]!)
+      if (failure) failures.push(failure)
+    }
+    this.#entries.length = 0
+    return failures
+  }
+
+  /**
+   * 执行单个回收器并捕获错误
+   * @param entry 登记项
+   * @returns 出错时返回错误信息，否则 undefined
+   */
+  #runOne(entry: { label: string; dispose: Disposer }): DisposeFailure | undefined {
+    try {
+      entry.dispose()
+      return undefined
+    } catch (error) {
+      return { label: `${this.#owner}:${entry.label}`, error }
+    }
+  }
+}
+
+/**
+ * 把多个 Disposer 合成一个
+ * @param disposers 回收函数列表（可含 undefined，便于条件注册）
+ * @returns 合成后的回收函数；逆序执行，单个抛错不影响其余
+ */
+export function combineDisposers(...disposers: (Disposer | undefined)[]): Disposer {
+  return () => {
+    for (let i = disposers.length - 1; i >= 0; i--) {
+      try {
+        disposers[i]?.()
+      } catch {
+        // 合成 disposer 拿不到 logger，只能忽略；需要记录的场景请用 DisposalRegistry
+      }
+    }
+  }
+}