@planet-matrix/mobius-model 0.5.0 → 0.6.0

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

@@ -0,0 +1,186 @@
+import type { InternalProxySubscriberEntryMap } from "./internal.ts"
+import type {
+  BaseEvents,
+  SubscriberEntry,
+} from "./common.ts"
+
+/**
+ * 表示 InstanceEventProxy 用于接入底层事件目标的适配器。
+ */
+export interface InstanceEventProxyTargetAdapter<Events extends BaseEvents> {
+  emit<K extends keyof Events>(event: K, ...args: Parameters<Events[K]>): boolean
+  subscribe<K extends keyof Events>(event: K, subscriber: Events[K]): void
+  unsubscribe<K extends keyof Events>(event: K, subscriber: Events[K]): void
+}
+
+/**
+ * 表示 InstanceEventProxy 的构造选项。
+ */
+export interface InstanceEventProxyOptions<Events extends BaseEvents> {
+  targetAdapter: InstanceEventProxyTargetAdapter<Events>
+  /**
+   * 在代理管理的订阅者执行出错时接收错误与对应订阅项。
+   */
+  onSubscriberError?: (subscriberEntry: SubscriberEntry<Events, keyof Events>, error: unknown) => void
+}
+
+/**
+ * 将单个事件目标适配为可管理下游订阅关系的代理。
+ */
+export class InstanceEventProxy<Events extends BaseEvents> {
+  protected options: InstanceEventProxyOptions<Events>
+  protected subscribers: InternalProxySubscriberEntryMap<Events>
+
+  constructor(options: InstanceEventProxyOptions<Events>) {
+    this.options = options
+    this.subscribers = {}
+  }
+
+  /**
+   * 检查某个事件是否已经管理给定订阅者。
+   */
+  has<K extends keyof Events>(
+    event: K, subscriber: Events[K]
+  ): boolean {
+    const proxySubscriberEntry = this.subscribers[event]
+    if (proxySubscriberEntry === undefined) {
+      return false
+    }
+
+    const has = proxySubscriberEntry.managedSubscribers.has(subscriber)
+    return has
+  }
+
+  protected internalSubscribe<K extends keyof Events>(
+    event: K, subscriber: Events[K], once: boolean
+  ): SubscriberEntry<Events, K> {
+    let proxySubscriberEntry = this.subscribers[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)}":`, exception)
+            }
+          } finally {
+            if (managedSubscriberEntry.once === true) {
+              managedSubscriberEntry.unsubscribe()
+            }
+          }
+        }
+      }) as Events[K]
+
+      proxySubscriberEntry = {
+        proxySubscriber,
+        managedSubscribers
+      }
+      this.subscribers[event] = proxySubscriberEntry
+      this.options.targetAdapter.subscribe(event, proxySubscriber)
+    }
+
+    const existingSubscriberEntry = proxySubscriberEntry.managedSubscribers.get(subscriber)
+    if (existingSubscriberEntry !== undefined) {
+      return existingSubscriberEntry
+    }
+
+    const unsubscribe = (): void => {
+      this.unsubscribe(event, subscriber)
+    }
+    const newSubscriberEntry: SubscriberEntry<Events, K> = {
+      event,
+      once,
+      subscriber,
+      unsubscribe,
+    }
+    proxySubscriberEntry.managedSubscribers.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, listener: Events[K]
+  ): SubscriberEntry<Events, K> {
+    return this.internalSubscribe(event, listener, true)
+  }
+
+  /**
+   * 移除指定事件上的给定订阅者。
+   */
+  unsubscribe<K extends keyof Events>(
+    event: K, listener: Events[K]
+  ): this {
+    const proxySubscriberEntry = this.subscribers[event]
+    if (proxySubscriberEntry === undefined) {
+      return this
+    }
+
+    proxySubscriberEntry.managedSubscribers.delete(listener)
+    if (proxySubscriberEntry.managedSubscribers.size === 0) {
+      this.options.targetAdapter.unsubscribe(event, proxySubscriberEntry.proxySubscriber)
+      delete this.subscribers[event]
+    }
+
+    return this
+  }
+
+  /**
+   * 移除指定事件上的全部代理订阅者。
+   */
+  removeSubscribersOfEvent<K extends keyof Events>(
+    event: K
+  ): this {
+    const proxySubscriberEntry = this.subscribers[event]
+    if (proxySubscriberEntry === undefined) {
+      return this
+    }
+
+    proxySubscriberEntry.managedSubscribers.clear()
+    this.options.targetAdapter.unsubscribe(event, proxySubscriberEntry.proxySubscriber)
+    delete this.subscribers[event]
+
+    return this
+  }
+
+  /**
+   * 移除代理当前管理的全部订阅者。
+   */
+  removeAllSubscribers(): this {
+    const events = Object.keys(this.subscribers)
+
+    for (const event of events) {
+      this.removeSubscribersOfEvent(event)
+    }
+    this.subscribers = {}
+
+    return this
+  }
+
+  /**
+   * 通过底层适配器派发指定事件。
+   */
+  emit<K extends keyof Events>(
+    event: K, ...args: Parameters<Events[K]>
+  ): boolean {
+    return this.options.targetAdapter.emit(event, ...args)
+  }
+}

package/src/event/internal.ts

@@ -0,0 +1,24 @@
+import type { BaseEvents, SubscriberEntry } from "./common.ts"
+
+/**
+ * 表示某一事件名下由订阅者函数到订阅项的内部映射。
+ */
+export type InternalSubscriberEntryMap<Events extends BaseEvents, K extends keyof Events> = Map<
+  Events[K],
+  SubscriberEntry<Events, K>
+>
+
+/**
+ * 表示代理订阅项及其所管理的下游订阅集合的内部结构。
+ */
+export interface InternalProxySubscriberEntry<Events extends BaseEvents, K extends keyof Events> {
+  managedSubscribers: InternalSubscriberEntryMap<Events, K>
+  proxySubscriber: Events[K]
+}
+
+/**
+ * 使用对象而非 Map 来保存事件到代理订阅项的内部映射。
+ */
+export type InternalProxySubscriberEntryMap<Events extends BaseEvents> = {
+  [K in keyof Events]?: InternalProxySubscriberEntry<Events, K> | undefined
+}

package/src/exception/README.md

@@ -0,0 +1,96 @@
+# Exception
+
+## Description
+
+Exception 模块提供围绕宿主环境全局异常入口（global exception entry）的监听、标准化与组合能力，用于把浏览器和 Node.js 暴露出来的异常来源整理成稳定、可清理、可组合的公共异常模型。
+
+它关注的是“异常从哪里被捕获、如何被整理成稳定记录”，而不是“异常之后如何打印、上报、恢复、吞掉或终止进程”。
+
+## For Understanding
+
+理解 Exception 模块时，应把它视为“异常来源层”，而不是“异常处理策略层”。这个模块的职责边界非常明确：
+
+- 它负责封装宿主提供的全局异常入口。
+- 它负责把宿主原始事件整理成更稳定的异常记录结构。
+- 它负责提供可清理的监听语义与批量组合入口。
+- 它不负责日志发送、监控上报、默认阻止、错误恢复或退出进程等策略决策。
+
+当前模块主要覆盖两类宿主：
+
+- 浏览器侧异常入口，例如 `error` 事件、`window.onerror` 与 `unhandledrejection`。
+- Node.js 侧异常入口，例如 `uncaughtExceptionMonitor`、`uncaughtException` 与 `unhandledRejection`。
+
+在建模上，这个模块采用“保留来源差异，同时提供标准化记录”的方式，而不是过早追求绝对统一。也就是说，浏览器与 Node.js 的来源种类、原始参数和补充字段可以不同，但它们都可以被整理成带有 runtime、source、exception、message、timestamp 等稳定字段的公共记录。这种分层有助于同时满足宿主特定处理与跨宿主消费。
+
+## For Using
+
+当应用需要在入口层、基础设施层、日志层或诊断层统一接入宿主全局异常时，可以使用这个模块，把分散在不同宿主 API 上的异常来源整理成更清楚的订阅接口。
+
+当前公共能力大致可以按以下几类理解：
+
+- 单一入口监听：用于单独监听浏览器或 Node.js 的某一种异常来源。
+- 批量入口监听：用于按宿主一次性安装一组常见异常入口，并返回统一清理函数。
+- 异常记录标准化：用于把浏览器或 Node.js 的原始输入整理成稳定的异常记录结构。
+- 类型与清理语义：用于表达异常来源种类、记录形状以及取消监听的统一返回类型。
+
+使用时应把它接在 logger、遥测、监控、恢复策略或业务错误处理的上游，而不是期待它直接替代这些能力。它更适合作为异常输入层，而不是最终处理层。
+
+## For Contributing
+
+贡献 Exception 模块时，应优先判断新增能力是否表达了稳定、可复用的宿主级异常来源，还是只是某个框架、某个应用内部错误流的便捷包装。只有前者才适合进入这个模块。
+
+在扩展时，应优先遵守以下边界：
+
+- 公共能力应围绕宿主异常入口、标准化记录与监听清理语义展开。
+- 不要在监听逻辑中默认执行日志输出、上报请求、`preventDefault`、`process.exit` 或其它强策略动作，除非 API 名称与文档已经明确承诺。
+- 组合入口只负责批量安装监听器与汇总清理，不负责掩盖宿主差异或替调用方做策略决策。
+- 与 Environment 的关系应保持清楚：Environment 可以帮助判断和获取宿主上下文，Exception 则负责安装异常监听器。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/exception/internal.ts`；若共享只存在于浏览器或 Node.js 子问题域内部，也可以放在对应文件中。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 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/exception`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/exception/<sub-module-name>`。
+- 测试应重点覆盖监听注册、清理行为、默认包含的入口集合、记录标准化结果，以及宿主不可用时的失败或空操作语义是否稳定。

package/src/exception/browser.ts

@@ -0,0 +1,219 @@
+import { useBrowser } from "#Source/environment/index.ts"
+
+import { normalizeBrowserExceptionRecord } from "./normalize.ts"
+import type {
+  BrowserExceptionRecord,
+  ExceptionListenerCleanup,
+  ObserveExceptionsOptions,
+} from "./types.ts"
+
+/**
+ * 表示浏览器侧异常监听回调。
+ */
+export type BrowserExceptionListener = (record: BrowserExceptionRecord) => void
+
+/**
+ * 监听浏览器侧通过 `error` 事件暴露的全局异常。
+ */
+export const onBrowserGlobalError = (
+  listener: BrowserExceptionListener,
+  options?: ObserveExceptionsOptions | undefined,
+): ExceptionListenerCleanup => {
+  return useBrowser(({ window }) => {
+    const internalListener = (event: ErrorEvent): void => {
+      listener(normalizeBrowserExceptionRecord({
+        source: "browser.global-error",
+        exception: event.error ?? event.message,
+        message: event.message,
+        timestamp: options?.captureTimestamp?.() ?? Date.now(),
+        originalEvent: event,
+        filename: event.filename,
+        lineno: event.lineno,
+        colno: event.colno,
+      }))
+    }
+
+    window.addEventListener("error", internalListener)
+
+    return () => {
+      window.removeEventListener("error", internalListener)
+    }
+  }, () => {
+    return (): void => {
+      return undefined
+    }
+  })
+}
+
+type InternalBrowserOnErrorListener = (
+  message: string | Event,
+  source?: string | undefined,
+  lineno?: number | undefined,
+  colno?: number | undefined,
+  error?: Error | undefined,
+) => boolean
+interface InternalBrowserOnErrorState {
+  previousOnError: OnErrorEventHandler | null
+  currentOnError: OnErrorEventHandler
+  listeners: Set<InternalBrowserOnErrorListener>
+}
+const internalBrowserOnErrorStateMap = new WeakMap<Window, InternalBrowserOnErrorState>()
+const internalGetBrowserOnErrorState = (window: Window): InternalBrowserOnErrorState => {
+  const existingState = internalBrowserOnErrorStateMap.get(window)
+
+  if (existingState !== undefined) {
+    return existingState
+  }
+
+  const internalListeners = new Set<InternalBrowserOnErrorListener>()
+  const internalPreviousOnError = window.onerror
+  const internalCurrentOnError: OnErrorEventHandler = (message, source, lineno, colno, error): boolean => {
+    let internalHandled = false
+
+    for (const internalListener of internalListeners) {
+      internalHandled = internalListener(message, source, lineno, colno, error) || internalHandled
+    }
+
+    if (typeof internalPreviousOnError === "function") {
+      internalHandled = internalPreviousOnError(message, source, lineno, colno, error) === true || internalHandled
+    }
+
+    return internalHandled
+  }
+
+  const internalState: InternalBrowserOnErrorState = {
+    previousOnError: internalPreviousOnError,
+    currentOnError: internalCurrentOnError,
+    listeners: internalListeners,
+  }
+
+  internalBrowserOnErrorStateMap.set(window, internalState)
+
+  // oxlint-disable-next-line prefer-add-event-listener
+  window.onerror = internalCurrentOnError
+
+  return internalState
+}
+/**
+ * 监听浏览器侧通过 `window.onerror` 暴露的全局异常。
+ */
+export const onBrowserWindowOnError = (
+  listener: BrowserExceptionListener,
+  options?: ObserveExceptionsOptions | undefined,
+): ExceptionListenerCleanup => {
+  return useBrowser(({ window }) => {
+    const internalOnErrorState = internalGetBrowserOnErrorState(window)
+    const internalListener: InternalBrowserOnErrorListener = (message, source, lineno, colno, error): boolean => {
+      listener(normalizeBrowserExceptionRecord({
+        source: "browser.window-onerror",
+        exception: error ?? message,
+        message: typeof message === "string" ? message : undefined,
+        timestamp: options?.captureTimestamp?.() ?? Date.now(),
+        originalEvent: { message, source, lineno, colno, error },
+        filename: source,
+        lineno,
+        colno,
+      }))
+
+      return false
+    }
+
+    internalOnErrorState.listeners.add(internalListener)
+
+    return () => {
+      internalOnErrorState.listeners.delete(internalListener)
+
+      if (internalOnErrorState.listeners.size !== 0) {
+        return
+      }
+
+      internalBrowserOnErrorStateMap.delete(window)
+
+      if (window.onerror === internalOnErrorState.currentOnError) {
+        // oxlint-disable-next-line prefer-add-event-listener
+        window.onerror = internalOnErrorState.previousOnError
+      }
+    }
+  }, () => {
+    return (): void => {
+      return undefined
+    }
+  })
+}
+
+/**
+ * 监听浏览器侧未处理 Promise 拒绝。
+ */
+export const onBrowserUnhandledRejection = (
+  listener: BrowserExceptionListener,
+  options?: ObserveExceptionsOptions | undefined,
+): ExceptionListenerCleanup => {
+  return useBrowser(({ window }) => {
+    const internalListener = (event: PromiseRejectionEvent): void => {
+      listener(normalizeBrowserExceptionRecord({
+        source: "browser.unhandled-rejection",
+        exception: event.reason,
+        timestamp: options?.captureTimestamp?.() ?? Date.now(),
+        originalEvent: event,
+      }))
+    }
+
+    window.addEventListener("unhandledrejection", internalListener)
+
+    return () => {
+      window.removeEventListener("unhandledrejection", internalListener)
+    }
+  }, () => {
+    return (): void => {
+      return undefined
+    }
+  })
+}
+
+/**
+ * 表示批量监听浏览器异常时可选的配置。
+ *
+ * 未显式传入时，三个浏览器入口默认都会启用；仅当对应选项为 `false` 时才跳过该入口。
+ */
+export interface ObserveBrowserExceptionsOptions extends ObserveExceptionsOptions {
+  includeGlobalError?: boolean | undefined
+  includeWindowOnError?: boolean | undefined
+  includeUnhandledRejection?: boolean | undefined
+}
+
+/**
+ * 批量监听浏览器侧全局异常入口。
+ *
+ * 默认会同时监听 `error`、`window.onerror` 和 `unhandledrejection`。
+ * 如需关闭某个入口，请将对应的 `include*` 选项显式设为 `false`。
+ */
+export const observeBrowserExceptions = (
+  listener: BrowserExceptionListener,
+  options?: ObserveBrowserExceptionsOptions | undefined,
+): ExceptionListenerCleanup => {
+  const {
+    includeGlobalError,
+    includeWindowOnError,
+    includeUnhandledRejection,
+  } = options ?? {}
+
+  const cleanups: ExceptionListenerCleanup[] = []
+
+  if (includeGlobalError !== false) {
+    cleanups.push(onBrowserGlobalError(listener, options))
+  }
+
+  if (includeWindowOnError !== false) {
+    cleanups.push(onBrowserWindowOnError(listener, options))
+  }
+
+  if (includeUnhandledRejection !== false) {
+    cleanups.push(onBrowserUnhandledRejection(listener, options))
+  }
+
+  return () => {
+    for (const cleanup of cleanups) {
+      cleanup()
+    }
+  }
+}

package/src/exception/index.ts

@@ -0,0 +1,4 @@
+export type * from "./types.ts"
+export * from "./normalize.ts"
+export * from "./browser.ts"
+export * from "./nodejs.ts"