@planet-matrix/mobius-model 0.5.0 → 0.6.0

package/src/event/README.md

@@ -0,0 +1,90 @@
+# Event
+
+## Description
+
+Event 模块提供围绕事件订阅、事件派发与事件代理的通用建模能力，用于在不绑定具体宿主事件系统的前提下组织稳定的事件协作边界。
+
+它关注的不是某个框架、某个 DOM API 或某个类库各自的监听接口差异，而是“事件如何被声明为一组稳定语义、订阅关系如何被管理、以及现有事件源如何被适配进一致边界”这一类基础问题。因此，这个模块更像是一组事件模型能力，而不是某个特定运行时的监听工具集合。
+
+## For Understanding
+
+理解 Event 模块时，首先应把它看作“事件交互边界”的建模层，而不是任意通知机制的杂糅容器。它所要解决的问题，是如何用一套清楚、可维护、可组合的方式表达事件名、订阅者、订阅生命周期以及代理关系，而不是简单地把 `on`、`off`、`emit` 这类常见方法重新包装一遍。
+
+这个模块适合放在以下边界中：
+
+- 你需要在应用内部定义一组清楚的事件表（event map），并希望订阅与派发行为都围绕这组语义稳定演进。
+- 你已经有某个现成事件源，但希望对外暴露更可控的订阅关系管理能力，而不是让外部直接依赖底层事件系统细节。
+- 你需要把“单个对象的事件能力”或“多个目标实例的事件能力”适配到统一模型中，避免上层代码到处感知宿主接口差异。
+
+理解这个模块时，还应守住几条边界原则：
+
+- Event 模块表达的是订阅与派发语义，不负责任务调度、消息持久化、跨进程传输或状态同步。
+- 它可以代理既有事件系统，但不应因为适配某个宿主接口而把该宿主的临时细节直接上升为模块公共语义。
+- 它关注的是“谁可订阅、何时移除、如何派发、如何桥接现有事件源”，而不是发布订阅架构的全部问题。像消息重放、优先级、背压或分布式广播等更高层语义，通常不应直接落入这个模块。
+
+## For Using
+
+当你希望把事件交互整理成一套明确模型，而不是在业务代码里反复拼接监听器注册、移除与调用逻辑时，可以使用 Event 模块。
+
+从使用角度看，这个模块大致可以分为三类能力：
+
+- 事件管理能力：用于在一组明确定义的事件表上维护订阅关系、支持常规订阅和单次订阅，并按同步或异步方式派发事件。
+- 实例级事件代理能力：用于把单个已有事件目标适配为受控代理，在不暴露底层订阅细节的前提下管理多个下游订阅者。
+- 类型级事件代理能力：用于把多个目标实例统一纳入同一代理模型，使上层可以用一致方式管理不同目标上的事件订阅关系。
+
+更合适的接入方式，是先明确事件名及其参数语义，再选择直接使用事件管理器，或通过代理把既有事件源收束到相同边界里。这样可以让事件系统的长期演进围绕模块语义展开，而不是围绕某个宿主 API 的偶然形态展开。
+
+## For Contributing
+
+为 Event 模块贡献内容时，优先判断新增能力是否真的在澄清事件边界，而不是只是在补一个看起来方便的监听包装。这个模块应长期服务于“事件表定义”“订阅生命周期管理”“派发语义”“现有事件源适配”这几类稳定问题。如果一个能力的成立必须依赖某个框架、某个宿主环境或某个业务流转约定，那么它通常不应直接成为该模块的公共组成部分。
+
+扩展这个模块时，应特别警惕以下倾向：把临时监听技巧直接暴露给调用方；把目标事件源的实现细节泄漏进公共 API；把事件代理扩展成通用消息总线；或者把本来应该在上层处理的并发、缓存、持久化、重放等语义塞回到事件模块内部。文档应说明为什么这些边界成立，以及后续演进时哪些原则不能被破坏，而不是复述当前实现的局部技巧。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/event/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/event`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/event/<sub-module-name>`。
+- 对这个模块来说，测试应优先覆盖订阅注册与移除、单次订阅、错误处理、同步与异步派发顺序，以及代理对象与底层目标之间的桥接行为。

package/src/event/class-event-proxy.ts

@@ -0,0 +1,228 @@
+import type { InternalProxySubscriberEntryMap } from "./internal.ts"
+import type {
+  BaseEvents,
+  SubscriberEntry,
+} from "./common.ts"
+
+/**
+ * 表示 ClassEventProxy 用于接入目标实例及其事件系统的适配器。
+ */
+export interface ClassEventProxyTargetAdapter<Target, Events extends BaseEvents> {
+  emit<K extends keyof Events>(target: Target, event: K, ...args: Parameters<Events[K]>): boolean
+  subscribe<K extends keyof Events>(target: Target, event: K, subscriber: Events[K]): void
+  unsubscribe<K extends keyof Events>(target: Target, event: K, subscriber: Events[K]): void
+}
+
+/**
+ * 表示 ClassEventProxy 的构造选项。
+ */
+export interface ClassEventProxyOptions<Target, Events extends BaseEvents> {
+  targetAdapter: ClassEventProxyTargetAdapter<Target, Events>
+  /**
+   * 在代理管理的订阅者执行出错时接收错误与对应订阅项。
+   */
+  onSubscriberError?: (subscriberEntry: SubscriberEntry<Events, keyof Events>, error: unknown) => void
+}
+
+/**
+ * 将一组目标实例的事件系统适配为统一的代理订阅模型。
+ */
+export class ClassEventProxy<Target, Events extends BaseEvents> {
+  protected options: ClassEventProxyOptions<Target, Events>
+  protected subscribers: Map<Target, InternalProxySubscriberEntryMap<Events>>
+
+  constructor(options: ClassEventProxyOptions<Target, Events>) {
+    this.options = options
+    this.subscribers = new Map()
+  }
+
+  /**
+   * 检查给定目标和事件上是否已经管理指定订阅者。
+   */
+  has<K extends keyof Events>(
+    target: Target, event: K, subscriber: Events[K]
+  ): boolean {
+    const proxySubscriberEntryMap = this.subscribers.get(target)
+    if (proxySubscriberEntryMap === undefined) {
+      return false
+    }
+
+    const proxySubscriberEntry = proxySubscriberEntryMap[event]
+    if (proxySubscriberEntry === undefined) {
+      return false
+    }
+
+    const has = proxySubscriberEntry.managedSubscribers.has(subscriber)
+    return has
+  }
+
+  protected internalSubscribe<K extends keyof Events>(
+    target: Target, event: K, subscriber: Events[K], once: boolean
+  ): SubscriberEntry<Events, K> {
+    const proxySubscriberEntryMap = this.subscribers.get(target) ?? ({} as InternalProxySubscriberEntryMap<Events>)
+    this.subscribers.set(target, proxySubscriberEntryMap)
+
+    let proxySubscriberEntry = proxySubscriberEntryMap[event]
+
+    if (proxySubscriberEntry === undefined) {
+      const managedSubscribers = new Map<Events[K], SubscriberEntry<Events, K>>()
+      // oxlint-disable-next-line no-unsafe-type-assertion
+      const proxySubscriber = ((...args: Parameters<Events[K]>) => {
+        const managedSubscriberEntries = [...managedSubscribers.values()]
+        for (const managedSubscriberEntry of managedSubscriberEntries) {
+          try {
+            managedSubscriberEntry.subscriber(...args)
+          } catch (exception) {
+            if (this.options.onSubscriberError !== undefined) {
+              this.options.onSubscriberError(managedSubscriberEntry, exception)
+            } else {
+              console.error(`Error occurred while emitting event "${String(event)}" of target:`, exception)
+            }
+          } finally {
+            if (managedSubscriberEntry.once === true) {
+              managedSubscriberEntry.unsubscribe()
+            }
+          }
+        }
+      }) as Events[K]
+
+      proxySubscriberEntry = {
+        proxySubscriber,
+        managedSubscribers
+      }
+      proxySubscriberEntryMap[event] = proxySubscriberEntry
+      this.options.targetAdapter.subscribe(target, event, proxySubscriber)
+    }
+
+    const existingSubscriberEntry = proxySubscriberEntry.managedSubscribers.get(subscriber)
+    if (existingSubscriberEntry !== undefined) {
+      return existingSubscriberEntry
+    }
+
+    const unsubscribe = (): void => {
+      this.unsubscribe(target, event, subscriber)
+    }
+    const newSubscriberEntry: SubscriberEntry<Events, K> = {
+      event,
+      once,
+      subscriber,
+      unsubscribe,
+    }
+    proxySubscriberEntry.managedSubscribers.set(subscriber, newSubscriberEntry)
+
+    return newSubscriberEntry
+  }
+
+  /**
+   * 为指定目标事件添加常规订阅者，并在首次接入时创建底层代理订阅。
+   */
+  subscribe<K extends keyof Events>(
+    target: Target, event: K, subscriber: Events[K]
+  ): SubscriberEntry<Events, K> {
+    return this.internalSubscribe(target, event, subscriber, false)
+  }
+
+  /**
+   * 为指定目标事件添加只触发一次的订阅者。
+   */
+  subscribeOnce<K extends keyof Events>(
+    target: Target, event: K, listener: Events[K]
+  ): SubscriberEntry<Events, K> {
+    return this.internalSubscribe(target, event, listener, true)
+  }
+
+  /**
+   * 移除指定目标事件上的给定订阅者。
+   */
+  unsubscribe<K extends keyof Events>(
+    target: Target, event: K, listener: Events[K]
+  ): this {
+    const proxySubscriberEntryMap = this.subscribers.get(target)
+    if (proxySubscriberEntryMap === undefined) {
+      return this
+    }
+
+    const proxySubscriberEntry = proxySubscriberEntryMap[event]
+    if (proxySubscriberEntry === undefined) {
+      return this
+    }
+
+    proxySubscriberEntry.managedSubscribers.delete(listener)
+    if (proxySubscriberEntry.managedSubscribers.size === 0) {
+      this.options.targetAdapter.unsubscribe(target, event, proxySubscriberEntry.proxySubscriber)
+      delete proxySubscriberEntryMap[event]
+      if (Object.keys(proxySubscriberEntryMap).length === 0) {
+        this.subscribers.delete(target)
+      }
+    }
+
+    return this
+  }
+
+  /**
+   * 移除指定目标某个事件上的全部代理订阅者。
+   */
+  removeSubscribersOfEvent<K extends keyof Events>(
+    target: Target, event: K
+  ): this {
+    const proxySubscriberEntryMap = this.subscribers.get(target)
+    if (proxySubscriberEntryMap === undefined) {
+      return this
+    }
+
+    const proxySubscriberEntry = proxySubscriberEntryMap[event]
+    if (proxySubscriberEntry === undefined) {
+      return this
+    }
+
+    proxySubscriberEntry.managedSubscribers.clear()
+    this.options.targetAdapter.unsubscribe(target, event, proxySubscriberEntry.proxySubscriber)
+    delete proxySubscriberEntryMap[event]
+    if (Object.keys(proxySubscriberEntryMap).length === 0) {
+      this.subscribers.delete(target)
+    }
+
+    return this
+  }
+
+  /**
+   * 移除指定目标上的全部代理订阅者。
+   */
+  removeSubscribersOfTarget(target: Target): this {
+    const proxySubscriberEntryMap = this.subscribers.get(target)
+    if (proxySubscriberEntryMap === undefined) {
+      return this
+    }
+
+    const events = Object.keys(proxySubscriberEntryMap)
+    for (const event of events) {
+      this.removeSubscribersOfEvent(target, event)
+    }
+    this.subscribers.delete(target)
+
+    return this
+  }
+
+  /**
+   * 移除当前代理管理的全部目标订阅关系。
+   */
+  removeAllSubscribers(): this {
+    const targets = Array.from(this.subscribers.keys())
+
+    for (const target of targets) {
+      this.removeSubscribersOfTarget(target)
+    }
+    this.subscribers.clear()
+
+    return this
+  }
+
+  /**
+   * 通过底层适配器向指定目标派发事件。
+   */
+  emit<K extends keyof Events>(
+    target: Target, event: K, ...args: Parameters<Events[K]>
+  ): boolean {
+    return this.options.targetAdapter.emit(target, event, ...args)
+  }
+}

package/src/event/common.ts

@@ -0,0 +1,19 @@
+/**
+ * 表示事件表中允许的基础订阅者函数类型。
+*/
+// oxlint-disable-next-line no-explicit-any
+export type BaseSubscriber = (...args: any[]) => void
+/**
+ * 表示由事件名到订阅者函数类型构成的事件表。
+ */
+export type BaseEvents = Record<string, BaseSubscriber>
+
+/**
+ * 表示一次订阅关系的标准化描述。
+ */
+export interface SubscriberEntry<Events extends BaseEvents, K extends keyof Events> {
+  event: K
+  once: boolean
+  subscriber: Events[K]
+  unsubscribe: () => void
+}

package/src/event/event-manager.ts

@@ -0,0 +1,203 @@
+import type { InternalSubscriberEntryMap } from "./internal.ts"
+import type { BaseEvents, SubscriberEntry } from "./common.ts"
+
+/**
+ * 表示 EventManager 的构造选项。
+ */
+export interface EventManagerOptions<Events extends BaseEvents> {
+  /**
+   * 在订阅者执行出错时接收错误与对应订阅项。
+   */
+  onSubscriberError?: (subscriberEntry: SubscriberEntry<Events, keyof Events>, error: unknown) => void
+}
+
+/**
+ * 管理同一事件表下的订阅、取消订阅与事件派发。
+ */
+export class EventManager<Events extends BaseEvents> {
+  protected options: EventManagerOptions<Events>
+  /**
+   * 每一类事件对应一个内部订阅映射，映射中的 key 是订阅者函数，value 是 SubscriberEntry 对象。
+   */
+  protected subscribers: {
+    [K in keyof Events]?: InternalSubscriberEntryMap<Events, K> | undefined
+  }
+
+  constructor(options?: EventManagerOptions<Events>) {
+    this.options = options ?? {}
+    this.subscribers = {}
+  }
+
+  protected internalHandleSubscriberError(
+    subscriberEntry: SubscriberEntry<Events, keyof Events>,
+    error: unknown,
+  ): void {
+    if (this.options.onSubscriberError !== undefined) {
+      this.options.onSubscriberError(subscriberEntry, error)
+    } else {
+      console.error(`Error occurred while emitting event "${String(subscriberEntry.event)}":`, error)
+    }
+  }
+
+  /**
+   * 检查某个事件是否已经注册给定订阅者。
+   */
+  has<K extends keyof Events>(event: K, subscriber: Events[K]): boolean {
+    const subscriberEntryMap = this.subscribers[event]
+    if (subscriberEntryMap === undefined) {
+      return false
+    }
+
+    const has = subscriberEntryMap.has(subscriber)
+    return has
+  }
+
+  protected internalSubscribe<K extends keyof Events>(event: K, subscriber: Events[K], once: boolean): SubscriberEntry<Events, K> {
+    const subscriberEntryMap = this.subscribers[event] ?? new Map<Events[K], SubscriberEntry<Events, K>>()
+    this.subscribers[event] = subscriberEntryMap
+
+    const existingSubscriberEntry = subscriberEntryMap.get(subscriber)
+    if (existingSubscriberEntry !== undefined) {
+      return existingSubscriberEntry
+    }
+
+    const unsubscribe = (): void => {
+      this.unsubscribe(event, subscriber)
+    }
+    const newSubscriberEntry: SubscriberEntry<Events, K> = {
+      event,
+      once,
+      subscriber,
+      unsubscribe,
+    }
+    subscriberEntryMap.set(subscriber, newSubscriberEntry)
+
+    return newSubscriberEntry
+  }
+
+  /**
+   * 为指定事件添加常规订阅者。
+   */
+  subscribe<K extends keyof Events>(event: K, subscriber: Events[K]): SubscriberEntry<Events, K> {
+    return this.internalSubscribe(event, subscriber, false)
+  }
+
+  /**
+   * 为指定事件添加只触发一次的订阅者。
+   */
+  subscribeOnce<K extends keyof Events>(event: K, subscriber: Events[K]): SubscriberEntry<Events, K> {
+    return this.internalSubscribe(event, subscriber, true)
+  }
+
+  /**
+   * 移除指定事件上的给定订阅者。
+   */
+  unsubscribe<K extends keyof Events>(event: K, subscriber: Events[K]): this {
+    const subscriberEntryMap = this.subscribers[event]
+    if (subscriberEntryMap === undefined) {
+      return this
+    }
+
+    subscriberEntryMap.delete(subscriber)
+    if (subscriberEntryMap.size === 0) {
+      delete this.subscribers[event]
+    }
+
+    return this
+  }
+
+  /**
+   * 移除指定事件上的全部订阅者。
+   */
+  removeSubscribersOfEvent<K extends keyof Events>(event: K): this {
+    delete this.subscribers[event]
+    return this
+  }
+
+  /**
+   * 移除当前管理器上的全部订阅者。
+   */
+  removeAllSubscribers(): this {
+    this.subscribers = {}
+    return this
+  }
+
+  /**
+   * 同步派发指定事件。
+   */
+  emit<K extends keyof Events>(event: K, ...args: Parameters<Events[K]>): boolean {
+    const subscriberEntryMap = this.subscribers[event]
+    if (subscriberEntryMap === undefined) {
+      return false
+    }
+
+    // Create a copy of the subscriber entries to avoid issues when
+    // subscribers are modified during event emission
+    const subscriberEntries = [...subscriberEntryMap.values()]
+    for (const subscriberEntry of subscriberEntries) {
+      try {
+        subscriberEntry.subscriber(...args)
+      } catch (exception) {
+        this.internalHandleSubscriberError(subscriberEntry, exception)
+      } finally {
+        if (subscriberEntry.once === true) {
+          subscriberEntry.unsubscribe()
+        }
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * 按订阅顺序异步派发指定事件。
+   */
+  async emitAsync<K extends keyof Events>(event: K, ...args: Parameters<Events[K]>): Promise<boolean> {
+    const subscriberEntryMap = this.subscribers[event]
+    if (subscriberEntryMap === undefined) {
+      return false
+    }
+
+    const subscriberEntries = [...subscriberEntryMap.values()]
+    for (const subscriberEntry of subscriberEntries) {
+      try {
+        const result = subscriberEntry.subscriber(...args)
+        await Promise.resolve(result)
+      } catch (exception) {
+        this.internalHandleSubscriberError(subscriberEntry, exception)
+      } finally {
+        if (subscriberEntry.once === true) {
+          subscriberEntry.unsubscribe()
+        }
+      }
+    }
+
+    return true
+  }
+
+  /**
+   * 并发等待所有订阅者完成后结束异步派发。
+   */
+  async emitConcurrentAsync<K extends keyof Events>(event: K, ...args: Parameters<Events[K]>): Promise<boolean> {
+    const subscriberEntryMap = this.subscribers[event]
+    if (subscriberEntryMap === undefined) {
+      return false
+    }
+
+    const promises = [...subscriberEntryMap.values()].map(async subscriberEntry => {
+      try {
+        const result = subscriberEntry.subscriber(...args)
+        await Promise.resolve(result)
+      } catch (exception) {
+        this.internalHandleSubscriberError(subscriberEntry, exception)
+      } finally {
+        if (subscriberEntry.once === true) {
+          subscriberEntry.unsubscribe()
+        }
+      }
+    })
+    await Promise.all(promises)
+
+    return true
+  }
+}

package/src/event/index.ts

@@ -0,0 +1,4 @@
+export type * from "./common.ts"
+export * from "./event-manager.ts"
+export * from "./instance-event-proxy.ts"
+export * from "./class-event-proxy.ts"