@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/storage/table.ts

@@ -0,0 +1,449 @@
+import type { BaseEvents } from "#Source/event/index.ts"
+import { EventManager } from "#Source/event/index.ts"
+import { Mutex } from "#Source/orchestration/index.ts"
+
+/**
+ * 表式运行时存储结构的事件集合。
+ */
+export interface TableEvents<Row extends BaseRow = BaseRow> extends BaseEvents {
+  valueChanged: (rows: Row[]) => void
+}
+
+/**
+ * 表行数据的基础结构。
+ */
+export type BaseRow = Record<string, unknown>
+
+/**
+ * 表式运行时存储结构的构造选项。
+ */
+export interface BaseTableOptions<Row extends BaseRow = BaseRow> {
+  /**
+   * 返回行的唯一标识。
+   *
+   * 不要在这个回调里修改行数据。
+   */
+  uniqueGetter: (row: Row) => string
+}
+
+/**
+ * 以唯一标识组织行数据集合的基础表模型。
+ */
+export abstract class BaseTable<RowType extends BaseRow = BaseRow> {
+  protected options: BaseTableOptions<RowType>
+  protected map: Map<string, RowType>
+  protected mutex: Mutex
+
+  /**
+   * 表数据变更事件管理器。
+   */
+  event: EventManager<TableEvents<RowType>>
+
+  /**
+   * 创建一个基础表实例。
+   */
+  constructor(options: BaseTableOptions<RowType>) {
+    this.options = options
+    this.map = new Map()
+    this.mutex = new Mutex()
+    this.event = new EventManager()
+  }
+
+  protected getUnique(row: RowType): string {
+    return this.options.uniqueGetter(row)
+  }
+
+  private internalEmitValueChanged(): void {
+    this.event.emit("valueChanged", structuredClone(Array.from(this.map.values())))
+  }
+
+  private internalAssertBatchRowsHaveUniqueValues(rows: RowType[]): void {
+    const uniqueSet = new Set<string>()
+    for (const row of rows) {
+      const unique = this.getUnique(row)
+      if (uniqueSet.has(unique)) {
+        throw new Error(`Duplicate row unique "${unique}" found in batch, failed row: ${JSON.stringify(row)}`)
+      }
+      uniqueSet.add(unique)
+    }
+  }
+
+  private internalFindRows(getter: (row: RowType) => boolean): RowType[] {
+    const matchedRows: RowType[] = []
+    for (const row of this.map.values()) {
+      if (getter(structuredClone(row))) {
+        matchedRows.push(row)
+      }
+    }
+    return matchedRows
+  }
+
+  private internalSetRows(rows: RowType[]): void {
+    for (const row of structuredClone(rows)) {
+      const unique = this.getUnique(row)
+      this.map.set(unique, row)
+    }
+    this.internalEmitValueChanged()
+  }
+
+  private internalUnsetRows(rows: RowType[]): void {
+    for (const row of structuredClone(rows)) {
+      const unique = this.getUnique(row)
+      this.map.delete(unique)
+    }
+    this.internalEmitValueChanged()
+  }
+
+  /**
+   * 清空整张表。
+   */
+  async clearTable(): Promise<void> {
+    return await this.mutex.runExclusive(() => {
+      this.map.clear()
+      this.internalEmitValueChanged()
+    })
+  }
+
+  /**
+   * 按条件读取第一条匹配的行快照。
+   *
+   * @returns { Promise<RowType | undefined> } Row, or undefined if not found.
+   */
+  async getRow(getter: (row: RowType) => boolean): Promise<RowType | undefined> {
+    return await this.mutex.runExclusive(() => {
+      const row = this.internalFindRows(getter)[0]
+      return structuredClone(row)
+    })
+  }
+
+  /**
+   * 按条件读取全部匹配的行快照。
+   *
+   * @returns { Promise<RowType[]> } Rows.
+   */
+  async getRows(getter: (row: RowType) => boolean): Promise<RowType[]> {
+    return await this.mutex.runExclusive(() => {
+      const rows = this.internalFindRows(getter)
+      return structuredClone(rows)
+    })
+  }
+
+  /**
+   * 安全插入一条新行。
+   *
+   * @returns { Promise<RowType> } Inserted row.
+   * @throws { Error } If row with unique already exists.
+   */
+  async safeInsertRow(row: RowType): Promise<RowType> {
+    return await this.mutex.runExclusive(() => {
+      const unique = this.getUnique(row)
+      if (this.map.has(unique)) {
+        throw new Error(`Row with unique "${unique}" already exists, failed row: ${JSON.stringify(row)}`)
+      }
+      this.internalSetRows([row])
+      return structuredClone(row)
+    })
+  }
+
+  /**
+   * 插入一条新行；若唯一标识已存在则返回 undefined。
+   *
+   * @returns { Promise<RowType | undefined> } Inserted row, or undefined if row with unique already exists.
+   */
+  async insertRow(row: RowType): Promise<RowType | undefined> {
+    try {
+      return await this.safeInsertRow(row)
+    }
+    catch {
+      return undefined
+    }
+  }
+
+  /**
+   * 安全插入多条新行。
+   *
+   * @returns { Promise<RowType[]> } Inserted rows.
+   * @throws { Error } If row with unique already exists.
+   */
+  async safeInsertRows(rows: RowType[]): Promise<RowType[]> {
+    return await this.mutex.runExclusive(() => {
+      this.internalAssertBatchRowsHaveUniqueValues(rows)
+      const toInsertRows: RowType[] = []
+      for (const row of rows) {
+        const unique = this.getUnique(row)
+        if (this.map.has(unique)) {
+          throw new Error(`Row with unique "${unique}" already exists, failed row: ${JSON.stringify(row)}`)
+        }
+        toInsertRows.push(row)
+      }
+      this.internalSetRows(toInsertRows)
+      return structuredClone(rows)
+    })
+  }
+
+  /**
+   * 按唯一标识做浅合并更新，并返回更新后的行。
+   *
+   * @throws { Error } If row not found.
+   */
+  async safeSimpleUpdateRow(row: RowType): Promise<RowType> {
+    return await this.mutex.runExclusive(() => {
+      const unique = this.getUnique(row)
+      const existRow = this.map.get(unique)
+      if (existRow === undefined) {
+        throw new Error(`Row not found, target row: ${JSON.stringify(row)}`)
+      }
+      const updatedRow = { ...existRow, ...row }
+      this.internalSetRows([updatedRow])
+      return structuredClone(updatedRow)
+    })
+  }
+
+  /**
+   * 按唯一标识做浅合并更新；若行不存在则返回 undefined。
+   */
+  async simpleUpdateRow(row: RowType): Promise<RowType | undefined> {
+    try {
+      return await this.safeSimpleUpdateRow(row)
+    }
+    catch {
+      return undefined
+    }
+  }
+
+  /**
+   * 按唯一标识批量做浅合并更新，并返回更新后的行。
+   *
+   * @throws { Error } If any row is not found or the batch contains duplicate uniques.
+   */
+  async safeSimpleUpdateRows(rows: RowType[]): Promise<RowType[]> {
+    return await this.mutex.runExclusive(() => {
+      this.internalAssertBatchRowsHaveUniqueValues(rows)
+      const updatedRows: RowType[] = []
+      for (const row of rows) {
+        const unique = this.getUnique(row)
+        const existRow = this.map.get(unique)
+        if (existRow === undefined) {
+          throw new Error(`Row not found, target row: ${JSON.stringify(row)}`)
+        }
+        updatedRows.push({ ...existRow, ...row })
+      }
+      this.internalSetRows(updatedRows)
+      return structuredClone(updatedRows)
+    })
+  }
+
+  /**
+   * 按条件查找第一条行并用 updater 生成新值。
+   *
+   * @returns { Promise<RowType> } Updated row.
+   * @throws { Error } If row not found, or unique changed between before and after.
+   */
+  async safeUpdateRow(getter: (row: RowType) => boolean, updater: (row: RowType) => RowType): Promise<RowType> {
+    return await this.mutex.runExclusive(() => {
+      const row = this.internalFindRows(getter)[0]
+      if (row === undefined) {
+        throw new Error("Row not found.")
+      }
+      const oldUnique = this.getUnique(row)
+      const newRow = updater(structuredClone(row))
+      const newUnique = this.getUnique(newRow)
+      if (oldUnique !== newUnique) {
+        throw new Error(`Unique cannot be changed, before row: ${JSON.stringify(row)}, after row: ${JSON.stringify(newRow)}`)
+      }
+      this.internalSetRows([newRow])
+      return structuredClone(newRow)
+    })
+  }
+
+  /**
+   * 按条件查找第一条行并更新；若未找到或唯一标识被改变则返回 undefined。
+   *
+   * @returns { Promise<RowType | undefined> } Updated row, or undefined if row not found, or unique changed between before and after.
+   */
+  async updateRow(getter: (row: RowType) => boolean, updater: (row: RowType) => RowType): Promise<RowType | undefined> {
+    try {
+      return await this.safeUpdateRow(getter, updater)
+    }
+    catch {
+      return undefined
+    }
+  }
+
+  /**
+   * 按条件批量更新匹配到的全部行。
+   *
+   * @returns { Promise<RowType[]> } Updated rows.
+   * @throws { Error } If unique changed between before and after.
+   */
+  async updateRows(getter: (row: RowType) => boolean, updater: (row: RowType) => RowType): Promise<RowType[]> {
+    return await this.mutex.runExclusive(() => {
+      const rows = this.internalFindRows(getter)
+      const updatedRows: RowType[] = []
+      for (const row of rows) {
+        const oldUnique = this.getUnique(row)
+        const newRow = updater(structuredClone(row))
+        const newUnique = this.getUnique(newRow)
+        if (oldUnique !== newUnique) {
+          throw new Error(`Unique cannot be changed, before row: ${JSON.stringify(row)}, after row: ${JSON.stringify(newRow)}`)
+        }
+        updatedRows.push(newRow)
+      }
+      this.internalSetRows(updatedRows)
+      return structuredClone(updatedRows)
+    })
+  }
+
+  /**
+   * 按唯一标识插入或浅合并一条行。
+   *
+   * @returns { Promise<RowType> } Upserted row.
+   */
+  async upsertRow(newRow: RowType): Promise<RowType> {
+    const upserted = await this.mutex.runExclusive(() => {
+      const unique = this.getUnique(newRow)
+      const existRow = this.map.get(unique)
+      if (existRow === undefined) {
+        this.internalSetRows([newRow])
+        return structuredClone(newRow)
+      }
+      else {
+        const updatedRow = { ...existRow, ...newRow }
+        this.internalSetRows([updatedRow])
+        return structuredClone(updatedRow)
+      }
+    })
+    return upserted
+  }
+
+  /**
+   * 按唯一标识批量插入或浅合并多条行。
+   *
+   * @returns { Promise<RowType[]> } Upserted rows.
+   * @throws { Error } If the batch contains duplicate uniques.
+   */
+  async upsertRows(rows: RowType[]): Promise<RowType[]> {
+    return await this.mutex.runExclusive(() => {
+      this.internalAssertBatchRowsHaveUniqueValues(rows)
+      const upsertedRows: RowType[] = []
+      for (const row of rows) {
+        const unique = this.getUnique(row)
+        const existRow = this.map.get(unique)
+        if (existRow === undefined) {
+          upsertedRows.push(row)
+        }
+        else {
+          upsertedRows.push({ ...existRow, ...row })
+        }
+      }
+      this.internalSetRows(upsertedRows)
+      return structuredClone(upsertedRows)
+    })
+  }
+
+  /**
+   * 按唯一标识安全删除一条行，并返回被删除的存量行。
+   *
+   * @throws { Error } If row not found.
+   */
+  async safeSimpleDeleteRow(row: RowType): Promise<RowType> {
+    return await this.mutex.runExclusive(() => {
+      const unique = this.getUnique(row)
+      const existRow = this.map.get(unique)
+      if (existRow === undefined) {
+        throw new Error(`Row not found, target row: ${JSON.stringify(row)}`)
+      }
+      this.internalUnsetRows([existRow])
+      return structuredClone(existRow)
+    })
+  }
+
+  /**
+   * 按唯一标识删除一条行；若不存在则返回 undefined。
+   */
+  async simpleDeleteRow(row: RowType): Promise<RowType | undefined> {
+    try {
+      return await this.safeSimpleDeleteRow(row)
+    }
+    catch {
+      return undefined
+    }
+  }
+
+  /**
+   * 按唯一标识批量删除多条行，并返回被删除的存量行。
+   *
+   * @throws { Error } If any row is not found or the batch contains duplicate uniques.
+   */
+  async simpleDeleteRows(rows: RowType[]): Promise<RowType[]> {
+    return await this.mutex.runExclusive(() => {
+      this.internalAssertBatchRowsHaveUniqueValues(rows)
+      const toDeleteRows: RowType[] = []
+      for (const row of rows) {
+        const unique = this.getUnique(row)
+        const existRow = this.map.get(unique)
+        if (existRow === undefined) {
+          throw new Error(`Row not found, target row: ${JSON.stringify(row)}`)
+        }
+        toDeleteRows.push(existRow)
+      }
+      this.internalUnsetRows(toDeleteRows)
+      return structuredClone(toDeleteRows)
+    })
+  }
+
+  /**
+   * 按条件安全删除唯一一条匹配行。
+   *
+   * @returns { Promise<RowType> } Deleted row.
+   * @throws { Error } If multiple rows found, or row not found.
+   */
+  async safeDeleteRow(getter: (row: RowType) => boolean): Promise<RowType> {
+    return await this.mutex.runExclusive(() => {
+      const rows = this.internalFindRows(getter)
+      if (rows.length > 1) {
+        throw new Error(`Multiple rows found, target rows: ${JSON.stringify(rows)}`)
+      }
+      const row = rows[0]
+      if (row === undefined) {
+        throw new Error(`Row not found.`)
+      }
+      this.internalUnsetRows([row])
+      return structuredClone(row)
+    })
+  }
+
+  /**
+   * 按条件删除唯一一条匹配行；若不存在则返回 undefined。
+   *
+   * @returns { Promise<RowType | undefined> } Deleted row, or undefined if row not found.
+   * @throws { Error } If multiple rows found.
+   */
+  async deleteRow(getter: (row: RowType) => boolean): Promise<RowType | undefined> {
+    return await this.mutex.runExclusive(() => {
+      const rows = this.internalFindRows(getter)
+      if (rows.length > 1) {
+        throw new Error(`Multiple rows found, target rows: ${JSON.stringify(rows)}`)
+      }
+      const row = rows[0]
+      if (row === undefined) {
+        return undefined
+      }
+      this.internalUnsetRows([row])
+      return structuredClone(row)
+    })
+  }
+
+  /**
+   * 按条件删除全部匹配行。
+   *
+   * @returns { Promise<RowType[]> } Deleted rows.
+   */
+  async deleteRows(getter: (row: RowType) => boolean): Promise<RowType[]> {
+    return await this.mutex.runExclusive(() => {
+      const rows = this.internalFindRows(getter)
+      this.internalUnsetRows(rows)
+      return structuredClone(rows)
+    })
+  }
+}

package/src/timer/README.md

@@ -0,0 +1,86 @@
+# Timer
+
+## Description
+
+Timer 模块提供围绕时间、时点、持续时间以及定时触发相关语义的基础建模能力，用于在不同运行时中组织一类可以长期维护的时间边界。
+
+它关注的不是对 `setTimeout`、`setInterval` 之类宿主 API 做一层临时包装，而是“哪些与时间有关的能力值得被抽象成稳定模型”。当前这里包含 expiration 这一子模块，用于表达过期状态及其派生剩余时间；但 Timer 本身不应被理解为只等于“过期倒计时”，后续也可能继续承载 timer engine 等其它与时间调度相关、且边界清楚的子问题域。
+
+## For Understanding
+
+理解 Timer 模块时，重点应放在“时间语义如何被建模”为稳定公共边界，而不是把它当成各种计时技巧的收纳箱。它适合表达的是这类问题：某个命名目标在什么时刻进入某种时间状态，哪些结果可以从这些时间状态稳定派生出来，以及时间推进过程中哪些变化值得被调度或被观察。
+
+因此，Timer 模块适合放在以下边界中：
+
+- 你需要围绕绝对时点、剩余时间或时间推进过程定义一组可长期复用的基础语义，而不是在业务里散落零碎的计时逻辑。
+- 你需要把“时间到了会发生什么”与“业务具体怎么处理”分离开，让上层只接入稳定的状态与事件模型。
+- 你预计未来会出现多个彼此相关但职责不同的时间子问题域，例如过期管理、调度引擎、时钟适配或时间驱动状态派生，并希望它们在同一父边界下协作。
+
+同时也要守住几个边界：
+
+- Timer 模块表达的是时间相关模型，不负责替代任务队列、工作流编排、分布式调度或动画系统。
+- 某个能力若只是对单一宿主 API 的便捷封装，而没有形成稳定的时间语义，通常不应进入这个模块。
+- 不是所有“和时间有关”的代码都适合放进来。只有当它能表达清楚的问题域边界，并能对外做出长期语义承诺时，才适合成为该模块或其子模块的一部分。
+
+## For Using
+
+当你需要复用一类已经被明确建模的时间能力，而不想在业务代码里反复拼接时间戳比较、到期检查、剩余时长换算和定时触发逻辑时，可以从 Timer 模块中选择合适的子模块接入。
+
+从当前使用角度看，Timer 模块主要承载两类方向：一类是围绕“某个命名目标何时到期”的过期状态管理能力；另一类是围绕这些基础时间状态继续派生出的观测、调度或驱动能力。当前仓库中已经落地的是 expiration 子模块，它更适合处理具名过期状态、剩余时间观察以及暂停恢复等问题；未来若加入其它子模块，也应继续围绕更广义的时间模型边界展开，而不是让父模块退化成只服务某一个现有子模块的命名容器。
+
+接入时更合理的方式，是先判断你的问题是否确实属于“时间模型”边界，再决定应使用哪个子模块。若问题本质上是过期状态及其派生值，应从 expiration 入手；若未来出现更偏向调度引擎或时钟抽象的能力，则应在相应子模块边界内理解和使用，而不是把所有时间问题都压到同一个现有实现上。
+
+## For Contributing
+
+贡献 Timer 模块时，应首先判断新增内容表达的是不是稳定的时间问题域，而不是某段实现中一时方便的计时技巧。尤其需要注意，当前存在 expiration 子模块，并不意味着 Timer 的整体边界已经被它完全定义；后续若出现 timer engine、时钟适配、时间驱动协调等其它子问题域，只要它们边界稳定且能被独立理解，就仍然适合继续放在 Timer 之下。
+
+扩展时应避免两类常见偏差。一类是把 Timer 缩窄成“只处理过期”的专用目录，导致其它合理的时间子模型无处安放；另一类是把各种与时间沾边的实现都塞进来，最终让模块失去清楚边界。更稳妥的做法，是优先明确新增能力到底是在表达时间状态、时间推进、时间派生，还是某种宿主专属调度技巧；只有前者形成了稳定问题域，才值得进入这个模块。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/timer/internal.ts`。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 与时间相关的实现应优先围绕时间状态、时间推进、时间派生与时间调度边界组织，避免把只服务于某个宿主的临时技巧直接提升为 Timer 的长期公共语义。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的时间语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/timer`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/timer/<sub-module-name>`。
+- 对时间相关能力，应优先覆盖时间推进、暂停恢复、边界时刻、派生状态以及定时器生命周期管理等场景。