@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/src/exception/nodejs.ts

@@ -0,0 +1,169 @@
+import { useNodejs } from "#Source/environment/index.ts"
+
+import { normalizeNodejsExceptionRecord } from "./normalize.ts"
+import type {
+  ExceptionListenerCleanup,
+  NodejsExceptionRecord,
+  ObserveExceptionsOptions,
+} from "./types.ts"
+
+/**
+ * 表示 Nodejs 侧异常监听回调。
+ */
+export type NodejsExceptionListener = (record: NodejsExceptionRecord) => void
+
+/**
+ * 监听 Node.js 的 `uncaughtExceptionMonitor` 事件。
+ */
+export const onNodejsUncaughtExceptionMonitor = (
+  listener: NodejsExceptionListener,
+  options?: ObserveExceptionsOptions | undefined,
+): ExceptionListenerCleanup => {
+  return useNodejs((context) => {
+    const currentProcess = context.globalThis.process
+    const internalListener = (exception: unknown, origin: unknown): void => {
+      listener(normalizeNodejsExceptionRecord({
+        source: "nodejs.uncaught-exception-monitor",
+        exception,
+        timestamp: options?.captureTimestamp?.() ?? Date.now(),
+        originalEvent: { exception, origin },
+        origin: typeof origin === "string" ? origin : undefined,
+      }))
+    }
+
+    currentProcess.on("uncaughtExceptionMonitor", internalListener)
+
+    return () => {
+      if (typeof currentProcess.off === "function") {
+        currentProcess.off("uncaughtExceptionMonitor", internalListener)
+        return
+      }
+
+      currentProcess.removeListener?.("uncaughtExceptionMonitor", internalListener)
+    }
+  }, () => {
+    return (): void => {
+      return undefined
+    }
+  })
+}
+
+/**
+ * 监听 Node.js 的 `uncaughtException` 事件。
+ */
+export const onNodejsUncaughtException = (
+  listener: NodejsExceptionListener,
+  options?: ObserveExceptionsOptions | undefined,
+): ExceptionListenerCleanup => {
+  return useNodejs((context) => {
+    const currentProcess = context.globalThis.process
+    const internalListener = (exception: unknown, origin: unknown): void => {
+      listener(normalizeNodejsExceptionRecord({
+        source: "nodejs.uncaught-exception",
+        exception,
+        timestamp: options?.captureTimestamp?.() ?? Date.now(),
+        originalEvent: { exception, origin },
+        origin: typeof origin === "string" ? origin : undefined,
+      }))
+    }
+
+    currentProcess.on("uncaughtException", internalListener)
+
+    return () => {
+      if (typeof currentProcess.off === "function") {
+        currentProcess.off("uncaughtException", internalListener)
+        return
+      }
+
+      currentProcess.removeListener?.("uncaughtException", internalListener)
+    }
+  }, () => {
+    return (): void => {
+      return undefined
+    }
+  })
+}
+
+/**
+ * 监听 Node.js 的 `unhandledRejection` 事件。
+ */
+export const onNodejsUnhandledRejection = (
+  listener: NodejsExceptionListener,
+  options?: ObserveExceptionsOptions | undefined,
+): ExceptionListenerCleanup => {
+  return useNodejs((context) => {
+    const currentProcess = context.globalThis.process
+    const internalListener = (reason: unknown, promise: unknown): void => {
+      listener(normalizeNodejsExceptionRecord({
+        source: "nodejs.unhandled-rejection",
+        exception: reason,
+        timestamp: options?.captureTimestamp?.() ?? Date.now(),
+        originalEvent: { reason, promise },
+        promise: promise instanceof Promise ? promise : undefined,
+      }))
+    }
+
+    currentProcess.on("unhandledRejection", internalListener)
+
+    return () => {
+      if (typeof currentProcess.off === "function") {
+        currentProcess.off("unhandledRejection", internalListener)
+        return
+      }
+
+      currentProcess.removeListener?.("unhandledRejection", internalListener)
+    }
+  }, () => {
+    return (): void => {
+      return undefined
+    }
+  })
+}
+
+/**
+ * 表示批量监听 Nodejs 异常时可选的配置。
+ *
+ * 未显式传入时，三个 Node.js 入口默认都会启用；仅当对应选项为 `false` 时才跳过该入口。
+ */
+export interface ObserveNodejsExceptionsOptions extends ObserveExceptionsOptions {
+  includeUncaughtExceptionMonitor?: boolean | undefined
+  includeUncaughtException?: boolean | undefined
+  includeUnhandledRejection?: boolean | undefined
+}
+
+/**
+ * 批量监听 Nodejs 侧全局异常入口。
+ *
+ * 默认会同时监听 `uncaughtExceptionMonitor`、`uncaughtException` 和 `unhandledRejection`。
+ * 如需关闭某个入口，请将对应的 `include*` 选项显式设为 `false`。
+ */
+export const observeNodejsExceptions = (
+  listener: NodejsExceptionListener,
+  options?: ObserveNodejsExceptionsOptions | undefined,
+): ExceptionListenerCleanup => {
+  const {
+    includeUncaughtExceptionMonitor,
+    includeUncaughtException,
+    includeUnhandledRejection
+  } = options ?? {}
+
+  const cleanups: ExceptionListenerCleanup[] = []
+
+  if (includeUncaughtExceptionMonitor !== false) {
+    cleanups.push(onNodejsUncaughtExceptionMonitor(listener, options))
+  }
+
+  if (includeUncaughtException !== false) {
+    cleanups.push(onNodejsUncaughtException(listener, options))
+  }
+
+  if (includeUnhandledRejection !== false) {
+    cleanups.push(onNodejsUnhandledRejection(listener, options))
+  }
+
+  return () => {
+    for (const cleanup of cleanups) {
+      cleanup()
+    }
+  }
+}

package/src/exception/normalize.ts

@@ -0,0 +1,106 @@
+import type {
+  BrowserExceptionRecord,
+  BrowserExceptionRecordInput,
+  ExceptionRecord,
+  ExceptionRecordInput,
+  NodejsExceptionRecord,
+  NodejsExceptionRecordInput,
+} from "./types.ts"
+
+const internalIsErrorLike = (exception: unknown): exception is { message: string } => {
+  if (exception instanceof Error) {
+    return true
+  }
+
+  if (typeof exception !== "object" || exception === null) {
+    return false
+  }
+
+  if (("message" in exception) === false) {
+    return false
+  }
+
+  const { message } = exception as { message?: unknown }
+  return typeof message === "string"
+}
+
+const internalGetExceptionMessage = (exception: unknown): string | undefined => {
+  if (internalIsErrorLike(exception)) {
+    return exception.message
+  }
+
+  if (typeof exception === "string") {
+    return exception
+  }
+
+  return undefined
+}
+
+/**
+ * 将异常输入标准化为共享异常记录。
+ */
+export const normalizeExceptionRecord = (input: ExceptionRecordInput): ExceptionRecord => {
+  const {
+    runtime,
+    source,
+    exception,
+    message,
+    timestamp,
+    originalEvent,
+  }: ExceptionRecordInput = input
+
+  return {
+    runtime,
+    source,
+    exception,
+    message: message ?? internalGetExceptionMessage(exception),
+    timestamp: timestamp ?? Date.now(),
+    originalEvent,
+  }
+}
+
+/**
+ * 将浏览器异常输入标准化为浏览器异常记录。
+ */
+export const normalizeBrowserExceptionRecord = (input: BrowserExceptionRecordInput): BrowserExceptionRecord => {
+  const {
+    source,
+    filename,
+    lineno,
+    colno,
+  } = input
+
+  return {
+    ...normalizeExceptionRecord({
+      ...input,
+      runtime: "browser",
+    }),
+    runtime: "browser",
+    source,
+    filename,
+    lineno,
+    colno,
+  }
+}
+
+/**
+ * 将 Nodejs 异常输入标准化为 Nodejs 异常记录。
+ */
+export const normalizeNodejsExceptionRecord = (input: NodejsExceptionRecordInput): NodejsExceptionRecord => {
+  const {
+    source,
+    origin,
+    promise,
+  } = input
+
+  return {
+    ...normalizeExceptionRecord({
+      ...input,
+      runtime: "nodejs",
+    }),
+    runtime: "nodejs",
+    source,
+    origin,
+    promise,
+  }
+}

package/src/exception/types.ts

@@ -0,0 +1,99 @@
+/**
+ * 表示异常来源所属的运行时类型。
+ */
+export type ExceptionRuntime =
+  | "browser"
+  | "nodejs"
+  | "unknown"
+
+/**
+ * 表示取消异常监听的清理函数。
+ */
+export type ExceptionListenerCleanup = () => void
+
+/**
+ * 表示一条标准化异常记录中的共享字段。
+ */
+export interface ExceptionRecord {
+  runtime: ExceptionRuntime
+  source: string
+  exception: unknown
+  message?: string | undefined
+  timestamp: number
+  originalEvent?: unknown | undefined
+}
+
+/**
+ * 表示标准化异常记录时所需的共享输入。
+ */
+export interface ExceptionRecordInput {
+  runtime: ExceptionRuntime
+  source: string
+  exception: unknown
+  message?: string | undefined
+  timestamp?: number | undefined
+  originalEvent?: unknown | undefined
+}
+
+/**
+ * 表示浏览器侧全局异常来源。
+ */
+export type BrowserExceptionSource =
+  | "browser.global-error"
+  | "browser.window-onerror"
+  | "browser.unhandled-rejection"
+
+/**
+ * 表示浏览器侧标准化异常记录。
+ */
+export interface BrowserExceptionRecord extends ExceptionRecord {
+  runtime: "browser"
+  source: BrowserExceptionSource
+  filename?: string | undefined
+  lineno?: number | undefined
+  colno?: number | undefined
+}
+
+/**
+ * 表示标准化浏览器异常记录时所需的输入。
+ */
+export interface BrowserExceptionRecordInput extends Omit<ExceptionRecordInput, "runtime" | "source"> {
+  source: BrowserExceptionSource
+  filename?: string | undefined
+  lineno?: number | undefined
+  colno?: number | undefined
+}
+
+/**
+ * 表示 Nodejs 侧全局异常来源。
+ */
+export type NodejsExceptionSource =
+  | "nodejs.uncaught-exception-monitor"
+  | "nodejs.uncaught-exception"
+  | "nodejs.unhandled-rejection"
+
+/**
+ * 表示 Nodejs 侧标准化异常记录。
+ */
+export interface NodejsExceptionRecord extends ExceptionRecord {
+  runtime: "nodejs"
+  source: NodejsExceptionSource
+  origin?: string | undefined
+  promise?: Promise<unknown> | undefined
+}
+
+/**
+ * 表示标准化 Nodejs 异常记录时所需的输入。
+ */
+export interface NodejsExceptionRecordInput extends Omit<ExceptionRecordInput, "runtime" | "source"> {
+  source: NodejsExceptionSource
+  origin?: string | undefined
+  promise?: Promise<unknown> | undefined
+}
+
+/**
+ * 表示批量安装异常监听器时可选的通用配置。
+ */
+export interface ObserveExceptionsOptions {
+  captureTimestamp?: (() => number) | undefined
+}

package/src/form/README.md

@@ -0,0 +1,25 @@
+# Form
+
+## Description
+
+Form 模块提供围绕类表单输入项（form-like input）及其组合关系的通用建模能力，用于表达输入状态、值转换与聚合边界。
+
+它关注的不是某个组件库的渲染细节，也不是某个框架各自的表单接入方式，而是“一个输入项应如何被视为可独立管理的输入原子、多个输入项如何组合成更高层的类表单数据管理器、以及输入值与聚合值如何保持清楚且可维护的对应关系”这一类基础问题。它之所以被命名为 Form，不是因为它只服务于页面表单，而是因为表单场景最自然、最直观地体现了这类模型的价值。
+
+## For Understanding
+
+理解 Form 模块时，首先应把它看成“类表单数据管理模型”，而不是“页面表单组件集合”或“校验规则工具箱”。它要解决的问题，不是把某个现成表单 API 重新包装一遍，而是为输入项本身建立稳定语义：一个输入项有哪些核心状态，输入过程与最终值如何区分，多个输入项如何组合，以及组合之后的整体值应如何被表达。
+
+这个模块更适合放在以下边界中：
+
+- 你希望把输入逻辑从具体接入层中抽离出来，让输入状态、值更新和聚合关系可以在不同 UI、服务端流程或其它非界面场景之间复用。
+- 你需要先把输入项视为一组可独立管理的输入原子，再把它们组合成更高层的类表单数据管理器，而不是一开始就把所有逻辑揉成单个大对象。
+- 你需要明确区分“输入过程中的值”和“对外稳定表达的值”，并希望这种区分能够成为长期可维护的公共语义。
+
+理解这个模块时，还应守住几条边界原则：
+
+- Form 模块表达的是输入项状态、输入项组合与值映射语义，不负责页面布局、样式、校验文案或具体提交流程。
+- 它可以服务于具体输入组件，但不应因为适配某个框架或某种表单交互习惯，而把这些宿主细节直接上升为模块公共语义。
+- 它关注的是“输入项如何被建模、如何更新、如何聚合”，而不是所有表单相关问题的总容器；像复杂校验编排、错误展示策略、网络提交流程或业务字段规范，通常应由更上层模块承担。
+
+因此，更合适的理解方式是：Form 模块提供的是一套围绕输入原子与类表单聚合的数据管理基础模型能力。表单只是它最典型的落点之一，而不是它的唯一归宿。只有当某个能力确实在澄清这条边界时，它才适合作为该模块的组成部分；如果某个能力只是某类页面表单的临时便利封装，那么它通常不应直接进入这个模块。

package/src/form/index.ts

@@ -0,0 +1 @@
+export * from "./inputor-controller/index.ts"