@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/oxlint.config.ts

@@ -0,0 +1,6 @@
+import { defineConfig } from "oxlint"
+import { Lint } from "@planet-matrix/mobius-mono"
+
+const config: Lint.OxlintConfig = defineConfig(Lint.defineOxlintConfig({}))
+
+export default config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@planet-matrix/mobius-model",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Mobius model.",
   "keywords": [
     "mobius",
@@ -53,21 +53,27 @@
     "directory": "packages/model"
   },
   "scripts": {
-    "lint": "bun oxlint",
+    "lint": "bun oxlint --type-aware --type-check",
     "test": "vitest watch",
     "build": "bun ./scripts/build.ts",
     "prepublishOnly": "bun run build"
   },
-  "dependencies": {},
+  "dependencies": {
+    "ua-parser-js": "^2.0.9",
+    "html-to-image": "^1.11.13",
+    "@standard-schema/spec": "^v1.1.0",
+    "arktype": "^2.2.0",
+    "@dotenvx/dotenvx": "^1.54.1"
+  },
   "devDependencies": {
-    "@planet-matrix/mobius-mono": "0.7.0",
-    "@types/bun": "^1.3.8",
-    "oxlint": "^1.42.0",
-    "oxlint-tsgolint": "^0.13.0",
+    "@planet-matrix/mobius-mono": "0.8.0",
+    "@types/bun": "^1.3.10",
+    "oxlint": "^1.55.0",
+    "oxlint-tsgolint": "^0.16.0",
     "typescript": "^5.9.3",
-    "@typescript/native-preview": "^7.0.0-dev.20260130.1",
-    "vite": "^7.3.1",
-    "vitest": "^4.0.18"
+    "@typescript/native-preview": "^7.0.0-dev.20260311.1",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
   },
   "peerDependencies": {},
   "peerDependenciesMeta": {},

package/src/abort/README.md

@@ -0,0 +1,92 @@
+# Abort
+
+## Description
+
+Abort 模块提供围绕中止信号（Abort Signal）的统一建模能力，用于表达、传递、组合与观察取消语义。
+
+它关注的不是某一个具体异步 API 的取消写法，而是“中止应如何被稳定表示、如何沿调用链传递、以及多个中止来源应如何组合”这一类基础问题。模块中的能力因此更偏向语义整理与边界对齐，而不是面向业务流程的临时封装。
+
+## For Understanding
+
+Abort 模块适合放在异步任务、资源加载、请求封装、响应式调度器或其它需要“可取消执行”语义的边界层之间。它试图回答的核心问题不是“如何立即停止某段代码”，而是“当系统中的多个参与方都可能发出中止意图时，应该如何用一套稳定、可组合、可维护的模型来表达它”。
+
+理解这个模块时，应该先把握几个前提：
+
+- 中止是一种显式控制语义，而不是异常兜底。它表达的是“后续不应继续推进”，而不是“当前实现发生了错误”。
+- 这个模块关心的是中止状态的表达、传播与组合，而不是任务调度、重试策略、超时策略或资源生命周期本身。后者如果要接入中止，应建立在本模块提供的稳定语义之上，而不是反过来让 Abort 模块吸收那些更高层的业务含义。
+- 这里的“组合”主要指多个上游中止来源之间的关系建模，例如“任一来源中止即可停止”或“全部来源都中止后才停止”，而不是泛化为任意事件系统。
+- 这里的“适配”主要指把不同形态的中止感知输入对齐到共同边界，例如从控制器（AbortController）、信号（AbortSignal）或已具备中止语义的管理对象中解析出一致的中止表示。
+- 这里的“监听管理”只服务于稳定地感知中止状态变化，避免重复注册、难以拆除或让外部调用方直接依赖脆弱的监听细节。它不应该演变成通用事件总线或宿主环境监听框架。
+
+如果某个能力的核心价值已经不再是“表达中止语义”，而是“安排任务什么时候开始”“实现某种副作用策略”“驱动特定运行时资源”，那么它通常就不应继续放在 Abort 模块中，即使它表面上也会接触 `AbortSignal`。
+
+## For Using
+
+当你希望把“取消”视为一项独立、可组合的基础能力，而不是在每一层业务代码里临时传几个布尔值、状态位或回调函数时，可以使用 Abort 模块。
+
+这个模块通常适合以下几类使用场景：
+
+- 统一中止输入边界：当调用方传入的可能是 `AbortSignal`、`AbortController`，或某个已经承载中止语义的对象时，可以先把这些输入统一到一致的中止模型，再让后续逻辑围绕统一边界工作。
+- 在分层调用链中传递取消语义：当一个底层能力需要接收来自上层的中止意图，并继续向更下游转交时，可以通过本模块保持中止边界显式、稳定且易于组合，而不是在不同层里各自定义非兼容约定。
+- 组合多个上游来源：当某个任务是否停止取决于多个来源，例如调用方取消、父任务结束、宿主环境销毁或上游流程提前终止时，可以把这些来源组合成一个可继续传递的中止模型，而不是在业务逻辑里散落多个条件分支。
+- 管理与中止信号相关的监听关系：当你需要围绕 `AbortSignal` 建立可重复添加、可显式移除、并且不会把监听管理细节泄漏给外部调用方的能力时，可以把这部分职责收束到本模块中。
+- 桥接选项对象与中止能力：当一个函数、类或工厂通过选项对象接收中止相关配置时，可以借助本模块把“是否携带中止信号”与“如何继续向下游传播”整理为一致约定。
+
+使用这个模块时，推荐把它放在“业务逻辑之前、宿主接口之后”的边界层。也就是说，先用它把中止语义整理干净，再由更高层能力决定收到中止后应该怎样停止请求、释放资源或结束流程。这样可以避免把业务细节反向耦合进 Abort 模块本身。
+
+## For Contributing
+
+Abort 模块服务的不是某一种具体业务，而是“中止能力如何被表达、传递、组合与观察”这一类基础问题。为这个模块做贡献时，优先考虑新增能力是否真的在澄清中止语义边界，还是只是在为某个当前实现补一个便捷入口。如果一个能力离开当前业务背景后就失去意义，或者必须依赖特定任务模型、宿主环境细节、框架生命周期才能成立，它通常就不应成为 Abort 模块的公共部分。
+
+这个模块更关注中止约定的清晰度，而不是功能堆叠。新增内容时，优先回答以下问题：它是否真的属于中止模型的一部分；它是在统一调用方的取消语义，还是只是在暴露某段实现细节；它是否能让上游、下游和组合关系更清楚；它是否能在不同运行时和调用层次中保持稳定语义。若这些问题没有明确答案，应谨慎扩展公共 API。
+
+同时，说明文件应聚焦于模块目标、边界、原则与长期约束，而不是复述当前实现细节。实现如何达成，应主要交由源码表达；文档应说明为什么值得这样设计，以及哪些边界不能被破坏。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让调用方在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/abort/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与中止相关的实现应优先围绕“状态判定”“输入适配”“上游关系组合”“监听关系管理”这类清晰职责组织，避免把重试、调度、资源释放策略等更高层语义混入本模块。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让调用方依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的中止语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/abort`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/abort/<sub-module-name>`。
+- 对这个模块来说，测试应优先覆盖不同中止来源之间的组合关系、状态传播、监听注册与移除行为，以及选项对象桥接时的典型边界场景。

package/src/abort/abort-manager.ts

@@ -0,0 +1,278 @@
+import { getGlobalAbortSignalListenerManager } from "./abort-signal-listener-manager.ts"
+
+/**
+ * 表示支持的中止感知输入。
+ */
+export type Abortable = AbortSignal | AbortController | AbortManager
+
+/**
+ * 表示可能包含 `abortSignal` 的选项对象。
+ */
+export interface WithAbortSignal {
+  abortSignal?: AbortSignal | undefined
+}
+/**
+ * 从选项类型中移除 `abortSignal` 字段。
+ */
+export type WithoutAbortSignal<T> = Omit<T, "abortSignal">
+
+/**
+ * 从中止感知输入中解析出 `AbortSignal`。
+ */
+export const getAbortSignal = (abortable: Abortable): AbortSignal => {
+  if (abortable instanceof AbortSignal) {
+    return abortable
+  }
+  else if (abortable instanceof AbortController) {
+    return abortable.signal
+  }
+  else if (abortable instanceof AbortManager) {
+    return abortable.abortSignal
+  }
+  else {
+    throw new TypeError("Unsupported abortable type.")
+  }
+}
+/**
+ * 检查中止感知输入是否已经中止。
+ */
+export const isAborted = (abortable: Abortable): boolean => {
+  const signal = getAbortSignal(abortable)
+  return signal.aborted
+}
+
+/**
+ * 表示暴露 `AbortManager` 与 `abort` 操作的对象。
+ */
+export interface AbortFriendly {
+  readonly abortManager: AbortManager
+
+  /**
+   * 此方法中应该将 {@link abortManager} 中止。
+   */
+  abort: (reason: string) => void
+}
+/**
+ * 表示可提供上游 `AbortManager` 的选项。
+ */
+export interface AbortFriendlyOptions {
+  abortManager?: AbortManager | undefined
+}
+
+/**
+ * 定义支持的中止判定模式。
+ */
+export const ABORT_MANAGER_MODE = {
+  ALL: "all",
+  ANY: "any",
+} as const
+/**
+ * 表示 `AbortManager` 使用的中止模式。
+ */
+export type AbortManagerMode = typeof ABORT_MANAGER_MODE[keyof typeof ABORT_MANAGER_MODE]
+interface Upstream {
+  abortable: Abortable
+  listener: () => void
+  connect: () => void
+  disconnect: () => void
+  remove: () => void
+}
+/**
+ * 表示 `AbortManager` 的构造选项。
+ */
+export interface AbortManagerOptions extends AbortFriendlyOptions {
+  /**
+   * 如果为 true，则在中止后移除全部上游。
+   *
+   * @default true
+   */
+  autoRemoveUpstreamsAfterAbort?: boolean | undefined
+}
+/**
+ * 协调一个或多个上游中止源的下游中止状态。
+ */
+export class AbortManager implements AbortFriendly {
+  readonly abortManager: AbortManager
+  readonly abortController: AbortController
+  readonly abortSignal: AbortSignal
+  protected upstreamMap: Map<Abortable, Upstream>
+  protected mode: AbortManagerMode
+  protected autoRemoveUpstreamsAfterAbort: boolean
+
+  constructor(options: AbortManagerOptions) {
+    this.abortManager = this
+    this.abortController = new AbortController()
+    this.abortSignal = this.abortController.signal
+    this.upstreamMap = new Map()
+    this.mode = ABORT_MANAGER_MODE.ALL
+    this.autoRemoveUpstreamsAfterAbort = options.autoRemoveUpstreamsAfterAbort ?? true
+
+    const abortManagerFromOptions = options.abortManager
+    if (abortManagerFromOptions !== undefined) {
+      this.addUpstreams([abortManagerFromOptions])
+    }
+  }
+
+  /**
+    * 检查当前管理器是否已经中止。
+   */
+  isAborted(): boolean {
+    return this.abortSignal.aborted
+  }
+
+  /**
+    * 设置中止判定模式。
+   */
+  setMode(mode: AbortManagerMode): this {
+    this.mode = mode
+    return this
+  }
+
+  /**
+    * 添加需要观察的上游中止源。
+   */
+  addUpstreams(abortables: Abortable[]): this {
+    const globalAbortSignalListenerManager = getGlobalAbortSignalListenerManager()
+
+    abortables
+      .forEach((abortable) => {
+        const abortSignal = getAbortSignal(abortable)
+        const listener = (): void => {
+          this.tryToAbort() // 任一上游中止后都应重新尝试判定是否中止
+        }
+        const connect = (): void => {
+          globalAbortSignalListenerManager.addEventListener(abortSignal, listener)
+        }
+        const disconnect = (): void => {
+          globalAbortSignalListenerManager.removeEventListener(abortSignal, listener)
+        }
+        const remove = (): void => {
+          disconnect()
+          this.upstreamMap.delete(abortable)
+        }
+        this.upstreamMap.set(abortable, {
+          abortable,
+          listener,
+          connect,
+          disconnect,
+          remove,
+        })
+        connect()
+      })
+
+    // 添加上游后，立即重新判定是否需要中止
+    this.tryToAbort()
+
+    return this
+  }
+
+  /**
+    * 移除指定的上游中止源。
+   */
+  removeUpstreams(abortables: Abortable[]): this {
+    abortables
+      .forEach((abortable) => {
+        const upstream = this.upstreamMap.get(abortable)
+        if (upstream !== undefined) {
+          upstream.remove()
+        }
+      })
+
+    // 移除上游后，立即重新判定是否需要中止
+    this.tryToAbort()
+
+    return this
+  }
+
+  /**
+    * 移除全部已注册的上游中止源。
+   */
+  removeAllUpstreams(): this {
+    const upstreamAbortables = Array.from(this.upstreamMap.keys())
+    this.removeUpstreams(upstreamAbortables)
+
+    return this
+  }
+
+  /**
+    * 根据当前模式评估上游状态，并在满足条件时中止。
+   */
+  tryToAbort(): void {
+    const upstreams = Array.from(this.upstreamMap.values())
+
+    let shouldAbort: boolean
+    if (this.mode === ABORT_MANAGER_MODE.ALL) {
+      shouldAbort = upstreams.every(upstream => isAborted(upstream.abortable))
+    }
+    else if (this.mode === ABORT_MANAGER_MODE.ANY) {
+      shouldAbort = upstreams.some(upstream => isAborted(upstream.abortable))
+    }
+    else {
+      throw new TypeError("Unsupported mode.")
+    }
+
+    // 满足中止条件且当前尚未中止时，执行中止
+    if (shouldAbort === true && this.abortSignal.aborted === false) {
+      this.abort(`Abort by upstream, mode: ${this.mode}.`)
+    }
+  }
+
+  /**
+   * 使用给定原因中止当前管理器。
+   */
+  abort(reason: string): void {
+    this.abortController.abort(reason)
+    if (this.autoRemoveUpstreamsAfterAbort === true) {
+      this.removeAllUpstreams()
+    }
+  }
+}
+
+/**
+ * 基于单个上游中止源创建 `AbortManager`。
+ */
+export const fromAbortable = (abortable: Abortable): AbortManager => {
+  const abortManager = new AbortManager({})
+  abortManager.addUpstreams([abortable])
+  return abortManager
+}
+
+/**
+ * 创建在任一上游中止时中止的 `AbortManager`。
+ */
+export const any = (abortables: Array<Abortable | undefined | null>): AbortManager => {
+  const abortManager = new AbortManager({})
+  abortManager.setMode(ABORT_MANAGER_MODE.ANY)
+  abortManager.addUpstreams(abortables.filter(item => item !== undefined && item !== null))
+  return abortManager
+}
+
+/**
+ * 创建在全部上游中止时中止的 `AbortManager`。
+ */
+export const all = (abortables: Array<Abortable | undefined | null>): AbortManager => {
+  const abortManager = new AbortManager({})
+  abortManager.setMode(ABORT_MANAGER_MODE.ALL)
+  abortManager.addUpstreams(abortables.filter(item => item !== undefined && item !== null))
+  return abortManager
+}
+
+/**
+ * 从可能携带 `abortSignal` 的选项对象创建 `AbortManager`。
+ */
+export const fromWithAbortSignal = <T extends WithAbortSignal>(options: T): AbortManager => {
+  const { abortSignal } = options
+  const abortManager = new AbortManager({})
+  if (abortSignal !== undefined) {
+    abortManager.addUpstreams([abortSignal])
+  }
+  return abortManager
+}
+
+/**
+ * 从中止友好的选项对象创建 `AbortManager`。
+ */
+export const fromAbortFriendlyOptions = <T extends AbortFriendlyOptions>(options: T): AbortManager => {
+  const abortManager = new AbortManager({ ...options })
+  return abortManager
+}

package/src/abort/abort-signal-listener-manager.ts

@@ -0,0 +1,81 @@
+
+type Listener = () => void
+/**
+ * 管理绑定到 `AbortSignal` 实例上的监听器。
+ */
+export class AbortSignalListenerManager {
+  readonly abortSignalMap: WeakMap<AbortSignal, {
+    syntheticListener: Listener
+    managedListenerSet: Set<Listener>
+  }>
+
+  constructor() {
+    this.abortSignalMap = new WeakMap()
+  }
+
+  /**
+    * 检查某个监听器当前是否由指定 `AbortSignal` 管理。
+   */
+  hasEventListener(abortSignal: AbortSignal, listener: Listener): boolean {
+    const listeners = this.abortSignalMap.get(abortSignal)
+    if (listeners === undefined) {
+      return false
+    }
+    return listeners.managedListenerSet.has(listener)
+  }
+
+  /**
+    * 为 `AbortSignal` 添加一个受管监听器。
+   */
+  addEventListener(abortSignal: AbortSignal, listener: Listener): this {
+    let listeners = this.abortSignalMap.get(abortSignal)
+    if (listeners === undefined) {
+      listeners = {
+        syntheticListener: (): void => {
+          // 在调用受管监听器之前，先将它们复制到一个新的数组中，以避免在调用过程中被修改。
+          const managedListenerSet = [...listeners?.managedListenerSet ?? []]
+          for (const managedListener of managedListenerSet) {
+            managedListener()
+          }
+        },
+        managedListenerSet: new Set(),
+      }
+      this.abortSignalMap.set(abortSignal, listeners)
+      abortSignal.addEventListener("abort", listeners.syntheticListener)
+    }
+    if (listeners.managedListenerSet.has(listener) === false) {
+      listeners.managedListenerSet.add(listener)
+    }
+
+    return this
+  }
+
+  /**
+    * 从 `AbortSignal` 移除一个受管监听器。
+   */
+  removeEventListener(abortSignal: AbortSignal, listener: Listener): this {
+    const listeners = this.abortSignalMap.get(abortSignal)
+    if (listeners === undefined) {
+      return this
+    }
+    listeners.managedListenerSet.delete(listener)
+    if (listeners.managedListenerSet.size === 0) {
+      abortSignal.removeEventListener("abort", listeners.syntheticListener)
+      this.abortSignalMap.delete(abortSignal)
+    }
+    return this
+  }
+}
+
+/**
+ * 获取全局单例的 `AbortSignalListenerManager` 实例。
+ */
+export const getGlobalAbortSignalListenerManager: () => AbortSignalListenerManager = (
+  () => {
+    let instance: AbortSignalListenerManager | undefined = undefined
+    return (): AbortSignalListenerManager => {
+      instance = instance ?? new AbortSignalListenerManager()
+      return instance
+    }
+  }
+)()

package/src/abort/index.ts

@@ -0,0 +1,2 @@
+export * from "./abort-signal-listener-manager.ts"
+export * from './abort-manager.ts'