@planet-matrix/mobius-model 0.6.0 → 0.10.1

package/src/drizzle/pagination.ts

@@ -0,0 +1,198 @@
+import { d } from "./drizzle.ts"
+import type { AnyPgTableWithColumns, InferModelFromPgTableWithColumns } from "./infer.ts"
+
+export type Cursor = string | null
+export interface WithCursorBasedPaginationOptions {
+  limit: number
+  cursor: Cursor
+}
+export interface WithCursorBasedPaginationResult {
+  nextCursor: Cursor
+  totalCount: number
+}
+
+interface OrderByItem<Key> {
+  key: Key
+  order: "asc" | "desc"
+}
+export interface EncodeCursorOptions<Model> {
+  model: Model
+  orderBy: Array<OrderByItem<keyof Model>>
+}
+export type EncodeCursorResult = string
+export const encodeCursor = <Model>(
+  options: EncodeCursorOptions<Model>,
+): EncodeCursorResult => {
+  const { model, orderBy } = options
+  const encoded = orderBy
+    .map((item) => {
+      const { key } = item
+      if (model[key] === undefined) {
+        throw new Error(`model[${String(key)}] is undefined`)
+      }
+      return model[key]
+    })
+    .map((value) => {
+      if (value instanceof Date) {
+        return `Date(${value.getTime()})`
+      }
+      return String(value)
+    })
+    .join(":")
+  return btoa(encoded)
+}
+
+export interface DecodeCursorOptions<Model, Key extends keyof Model = keyof Model> {
+  modelForType: Model
+  cursor: Cursor
+  orderBy: Array<OrderByItem<Key>>
+}
+export type DecodedCursor<Model, Key extends keyof Model = keyof Model> = {
+  [K in Key]: Model[K] extends Date ? Date : Model[K]
+}
+export type DecodeCursorResult<Model, Key extends keyof Model = keyof Model> = DecodedCursor<Model, Key> | null
+export const decodeCursor = <Model, Key extends keyof Model = keyof Model>(
+  options: DecodeCursorOptions<Model, Key>,
+): DecodeCursorResult<Model, Key> => {
+  const { cursor, orderBy } = options
+  if (cursor === null) {
+    return null
+  }
+  const decoded = atob(cursor)
+    .split(":")
+    .map((value) => {
+      if (value.startsWith("Date(")) {
+        return new Date(Number.parseInt(value.slice(5, -1), 10))
+      }
+      return value
+    })
+    .reduce((acc, value, index) => {
+      const key = orderBy[index]!.key
+      return { ...acc, [key]: value }
+    }, {})
+  return decoded as DecodedCursor<Model, Key>
+}
+
+export interface GetNextCursorOptions<Model> {
+  list: Model[]
+  limit: number
+  encodeOptions: Omit<EncodeCursorOptions<Model>, "model">
+}
+export const getNextCursor = <Model>(options: GetNextCursorOptions<Model>): Cursor => {
+  const { list, limit, encodeOptions } = options
+  if (list.length === 0) {
+    return null
+  }
+  if (list.length < limit) {
+    return null
+  }
+  const lastModel = list.at(-1)!
+  const cursor = encodeCursor({
+    model: lastModel,
+    ...encodeOptions,
+  })
+  return cursor
+}
+
+export interface BuildWhereSqlOptions<Table extends AnyPgTableWithColumns, Key extends keyof InferModelFromPgTableWithColumns<Table>> {
+  table: Table
+  orderBy: Array<OrderByItem<Key>>
+  decodeCursorResult: DecodeCursorResult<InferModelFromPgTableWithColumns<Table>, Key>
+}
+export const buildWhereSql = <Table extends AnyPgTableWithColumns, Key extends keyof InferModelFromPgTableWithColumns<Table>>(
+  options: BuildWhereSqlOptions<Table, Key>,
+): d.SQL | undefined => {
+  const { table, decodeCursorResult, orderBy } = options
+  if (decodeCursorResult === null) {
+    return undefined
+  }
+  if (orderBy.length === 0) {
+    return undefined
+  }
+  const conditionSqlList = orderBy.map((item) => {
+    const { key, order } = item
+    if (order === "asc") {
+      return d.gt(table[key], decodeCursorResult[key])
+    }
+    if (order === "desc") {
+      return d.lt(table[key], decodeCursorResult[key])
+    }
+    throw new Error(`Invalid order: ${String(order)}`)
+  })
+  return d.and(...conditionSqlList)
+}
+
+export interface BuildOrderBySql<Table extends AnyPgTableWithColumns, Key extends keyof InferModelFromPgTableWithColumns<Table>> {
+  table: Table
+  orderBy: Array<OrderByItem<Key>>
+}
+export const buildOrderBySql = <Table extends AnyPgTableWithColumns, Key extends keyof InferModelFromPgTableWithColumns<Table>>(
+  options: BuildOrderBySql<Table, Key>,
+): d.SQL[] => {
+  const { table, orderBy } = options
+  const sqlList = orderBy.map((item) => {
+    const { key, order } = item
+    if (order === "asc") {
+      return d.asc(table[key])
+    }
+    if (order === "desc") {
+      return d.desc(table[key])
+    }
+    throw new Error(`Invalid order: ${String(order)}`)
+  })
+  return sqlList
+}
+
+export interface BuildCursorBasedPaginationOptions<Table extends AnyPgTableWithColumns, Key extends keyof InferModelFromPgTableWithColumns<Table>> {
+  table: Table
+  orderBy: Array<OrderByItem<Key>>
+  cursor: Cursor
+  limit: number
+}
+export interface BuildCursorBasedPaginationResult<Table extends AnyPgTableWithColumns, Key extends keyof InferModelFromPgTableWithColumns<Table>> {
+  decodeCursorResult: DecodeCursorResult<InferModelFromPgTableWithColumns<Table>, Key>
+  whereSql: d.SQL | undefined
+  orderBySql: d.SQL[]
+  getNextCursor: (list: Array<InferModelFromPgTableWithColumns<Table>>) => Cursor
+}
+export const buildCursorBasedPagination = <Table extends AnyPgTableWithColumns, Key extends keyof InferModelFromPgTableWithColumns<Table>>(
+  options: BuildCursorBasedPaginationOptions<Table, Key>,
+): BuildCursorBasedPaginationResult<Table, Key> => {
+  const { table, orderBy, limit, cursor } = options
+
+  type Model = InferModelFromPgTableWithColumns<Table>
+
+  const decodeCursorResult = decodeCursor({
+    modelForType: {} as Model,
+    cursor,
+    orderBy,
+  })
+
+  const whereSql = buildWhereSql({
+    table,
+    decodeCursorResult,
+    orderBy,
+  })
+
+  const orderBySql = buildOrderBySql({
+    table,
+    orderBy,
+  })
+
+  const _getNextCursor = (list: Model[]): Cursor => {
+    return getNextCursor({
+      list,
+      limit,
+      encodeOptions: {
+        orderBy,
+      },
+    })
+  }
+
+  return {
+    decodeCursorResult,
+    whereSql,
+    orderBySql,
+    getNextCursor: _getNextCursor,
+  }
+}

package/src/email/README.md

@@ -0,0 +1 @@
+# Email

package/src/email/index.ts

@@ -0,0 +1 @@
+export * from "./resend.ts"

package/src/email/resend.ts

@@ -0,0 +1,25 @@
+import { Resend } from "resend"
+
+export interface SendEmailOptions {
+  from: string
+  to: string
+  subject: string
+  html: string
+}
+export type SendEmailResult = ReturnType<typeof Resend.prototype.emails.send>
+
+export interface EmailOptions {
+  key: string
+}
+export class Email {
+  private sendClient: Resend
+
+  constructor(options: EmailOptions) {
+    const { key } = options
+    this.sendClient = new Resend(key)
+  }
+
+  async sendEmail(options: SendEmailOptions): Promise<SendEmailResult> {
+    return await this.sendClient.emails.send({ ...options })
+  }
+}

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

@@ -1,13 +1,13 @@
 import type { InternalProxySubscriberEntryMap } from "./internal.ts"
 import type {
-  BaseEvents,
+  EventsConstraint,
   SubscriberEntry,
 } from "./common.ts"
 
 /**
  * 表示 ClassEventProxy 用于接入目标实例及其事件系统的适配器。
  */
-export interface ClassEventProxyTargetAdapter<Target, Events extends BaseEvents> {
+export interface ClassEventProxyTargetAdapter<Target, Events extends EventsConstraint<Events>> {
   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
@@ -16,7 +16,7 @@ export interface ClassEventProxyTargetAdapter<Target, Events extends BaseEvents>
 /**
  * 表示 ClassEventProxy 的构造选项。
  */
-export interface ClassEventProxyOptions<Target, Events extends BaseEvents> {
+export interface ClassEventProxyOptions<Target, Events extends EventsConstraint<Events>> {
   targetAdapter: ClassEventProxyTargetAdapter<Target, Events>
   /**
    * 在代理管理的订阅者执行出错时接收错误与对应订阅项。
@@ -27,7 +27,7 @@ export interface ClassEventProxyOptions<Target, Events extends BaseEvents> {
 /**
  * 将一组目标实例的事件系统适配为统一的代理订阅模型。
  */
-export class ClassEventProxy<Target, Events extends BaseEvents> {
+export class ClassEventProxy<Target, Events extends EventsConstraint<Events>> {
   protected options: ClassEventProxyOptions<Target, Events>
   protected subscribers: Map<Target, InternalProxySubscriberEntryMap<Events>>
 
@@ -66,7 +66,6 @@ export class ClassEventProxy<Target, Events extends BaseEvents> {
 
     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) {
@@ -196,7 +195,7 @@ export class ClassEventProxy<Target, Events extends BaseEvents> {
 
     const events = Object.keys(proxySubscriberEntryMap)
     for (const event of events) {
-      this.removeSubscribersOfEvent(target, event)
+      this.removeSubscribersOfEvent(target, event as keyof Events)
     }
     this.subscribers.delete(target)
 

package/src/event/common.ts

@@ -4,14 +4,24 @@
 // oxlint-disable-next-line no-explicit-any
 export type BaseSubscriber = (...args: any[]) => void
 /**
- * 表示由事件名到订阅者函数类型构成的事件表。
+ * 表示事件表中允许的事件-订阅者关系的约束类型。
+ * 该类型要求事件表的每个事件都必须对应一个 BaseSubscriber 类型的订阅者函数。
+ * 通过该约束类型，EventManager 和相关组件能够在编译时确保事件表的正确性。
  */
-export type BaseEvents = Record<string, BaseSubscriber>
+export type EventsConstraint<Events extends EventsConstraint<Events>> = {
+  [K in keyof Events]: BaseSubscriber
+}
+export type BuildEvents<Events extends EventsConstraint<Events>> = {
+  [K in keyof Events]: Events[K]
+}
+export interface AnyEvents {
+  [event: string]: BaseSubscriber
+}
 
 /**
  * 表示一次订阅关系的标准化描述。
  */
-export interface SubscriberEntry<Events extends BaseEvents, K extends keyof Events> {
+export interface SubscriberEntry<Events extends EventsConstraint<Events>, K extends keyof Events> {
   event: K
   once: boolean
   subscriber: Events[K]

package/src/event/event-manager.ts

@@ -1,10 +1,10 @@
 import type { InternalSubscriberEntryMap } from "./internal.ts"
-import type { BaseEvents, SubscriberEntry } from "./common.ts"
+import type { EventsConstraint, SubscriberEntry } from "./common.ts"
 
 /**
  * 表示 EventManager 的构造选项。
  */
-export interface EventManagerOptions<Events extends BaseEvents> {
+export interface EventManagerOptions<Events extends EventsConstraint<Events>> {
   /**
    * 在订阅者执行出错时接收错误与对应订阅项。
    */
@@ -14,7 +14,7 @@ export interface EventManagerOptions<Events extends BaseEvents> {
 /**
  * 管理同一事件表下的订阅、取消订阅与事件派发。
  */
-export class EventManager<Events extends BaseEvents> {
+export class EventManager<Events extends EventsConstraint<Events>> {
   protected options: EventManagerOptions<Events>
   /**
    * 每一类事件对应一个内部订阅映射，映射中的 key 是订阅者函数，value 是 SubscriberEntry 对象。

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

@@ -1,13 +1,13 @@
 import type { InternalProxySubscriberEntryMap } from "./internal.ts"
 import type {
-  BaseEvents,
+  EventsConstraint,
   SubscriberEntry,
 } from "./common.ts"
 
 /**
  * 表示 InstanceEventProxy 用于接入底层事件目标的适配器。
  */
-export interface InstanceEventProxyTargetAdapter<Events extends BaseEvents> {
+export interface InstanceEventProxyTargetAdapter<Events extends EventsConstraint<Events>> {
   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
@@ -16,7 +16,7 @@ export interface InstanceEventProxyTargetAdapter<Events extends BaseEvents> {
 /**
  * 表示 InstanceEventProxy 的构造选项。
  */
-export interface InstanceEventProxyOptions<Events extends BaseEvents> {
+export interface InstanceEventProxyOptions<Events extends EventsConstraint<Events>> {
   targetAdapter: InstanceEventProxyTargetAdapter<Events>
   /**
    * 在代理管理的订阅者执行出错时接收错误与对应订阅项。
@@ -27,7 +27,7 @@ export interface InstanceEventProxyOptions<Events extends BaseEvents> {
 /**
  * 将单个事件目标适配为可管理下游订阅关系的代理。
  */
-export class InstanceEventProxy<Events extends BaseEvents> {
+export class InstanceEventProxy<Events extends EventsConstraint<Events>> {
   protected options: InstanceEventProxyOptions<Events>
   protected subscribers: InternalProxySubscriberEntryMap<Events>
 
@@ -58,7 +58,6 @@ export class InstanceEventProxy<Events extends BaseEvents> {
 
     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) {
@@ -168,7 +167,7 @@ export class InstanceEventProxy<Events extends BaseEvents> {
     const events = Object.keys(this.subscribers)
 
     for (const event of events) {
-      this.removeSubscribersOfEvent(event)
+      this.removeSubscribersOfEvent(event as keyof Events)
     }
     this.subscribers = {}
 

package/src/event/internal.ts

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

package/src/exception/README.md

@@ -2,49 +2,57 @@
 
 ## Description
 
-Exception 模块提供围绕宿主环境全局异常入口（global exception entry）的监听、标准化与组合能力，用于把浏览器和 Node.js 暴露出来的异常来源整理成稳定、可清理、可组合的公共异常模型。
+Exception 模块提供围绕异常（exception）的基础模型能力，用于承载宿主环境全局异常入口的监听与标准化，以及其中一类可判别、可匹配、可序列化的结构化错误建模。
 
-它关注的是“异常从哪里被捕获、如何被整理成稳定记录”，而不是“异常之后如何打印、上报、恢复、吞掉或终止进程”。
+它关注的是“异常从哪里进入系统、错误如何被稳定表达”，而不是“异常之后如何打印、上报、恢复、吞掉或终止进程”。
 
 ## For Understanding
 
-理解 Exception 模块时，应把它视为“异常来源层”，而不是“异常处理策略层”。这个模块的职责边界非常明确：
+理解 Exception 模块时，更合适的方式是把它视为“异常模型层”，而不是“异常处理策略层”。这个模块当前关注的是异常这一上位概念，其中既包括异常如何从宿主环境进入系统，也包括其中一类适合被稳定建模的异常形式，也就是结构化错误。
 
-- 它负责封装宿主提供的全局异常入口。
-- 它负责把宿主原始事件整理成更稳定的异常记录结构。
-- 它负责提供可清理的监听语义与批量组合入口。
-- 它不负责日志发送、监控上报、默认阻止、错误恢复或退出进程等策略决策。
+- 宿主异常入口：负责封装浏览器和 Node.js 暴露出来的全局异常入口，并把原始输入整理成稳定记录。
+- 结构化错误：负责把应用内部需要长期存在的某些异常表达成带判别信息的 Error 变体，以便进行分派、组合和序列化。
 
-当前模块主要覆盖两类宿主：
+之所以可以把它们放在同一模块内，不是因为它们的实现方式相似，而是因为它们都在回答同一类问题：系统中的异常应该以什么稳定模型进入后续流程。前者解决“异常从哪里来”，后者解决“某些异常在系统中应如何被表达与判别”。
+
+因此，这个模块并不承担日志发送、监控上报、错误恢复、默认阻止、重试编排或进程退出等策略职责。它只负责把异常整理成更稳定、更清楚、更可组合的输入模型，让上层的 logger、telemetry、workflow、Result/Either 或业务恢复逻辑在其之上继续工作。
+
+对于宿主异常入口部分，当前主要覆盖两类运行时：
 
 - 浏览器侧异常入口，例如 `error` 事件、`window.onerror` 与 `unhandledrejection`。
 - Node.js 侧异常入口，例如 `uncaughtExceptionMonitor`、`uncaughtException` 与 `unhandledRejection`。
 
-在建模上，这个模块采用“保留来源差异，同时提供标准化记录”的方式，而不是过早追求绝对统一。也就是说，浏览器与 Node.js 的来源种类、原始参数和补充字段可以不同，但它们都可以被整理成带有 runtime、source、exception、message、timestamp 等稳定字段的公共记录。这种分层有助于同时满足宿主特定处理与跨宿主消费。
+对于异常建模中的结构化错误部分，当前采用 Tagged Error 的思路：这类错误既保留原生 Error 的 name、message、stack 与 `cause` 语义，也额外拥有稳定的 `tag` 与 `data` 字段，便于在联合类型中进行穷举或部分匹配。
 
 ## For Using
 
-当应用需要在入口层、基础设施层、日志层或诊断层统一接入宿主全局异常时，可以使用这个模块，把分散在不同宿主 API 上的异常来源整理成更清楚的订阅接口。
+当应用需要从宿主环境统一接入全局异常，并把这些异常整理成稳定记录时，可以使用这个模块的异常入口能力，把分散在不同运行时 API 上的异常来源收敛成更清楚的订阅接口。
+
+当应用需要在模块边界、基础设施层、工作流编排、Result/Either 风格流程或跨层协议中表达一组稳定、可判别、可序列化的异常时，也可以使用这个模块中的结构化错误能力，把其中适合显式建模的一类异常从“临时字符串或松散对象”提升为更清楚的公共模型。
 
 当前公共能力大致可以按以下几类理解：
 
-- 单一入口监听：用于单独监听浏览器或 Node.js 的某一种异常来源。
-- 批量入口监听：用于按宿主一次性安装一组常见异常入口，并返回统一清理函数。
+- 单一入口监听：用于单独监听浏览器或 Node.js 的某一种全局异常来源。
+- 批量入口监听：用于按运行时一次性安装一组常见异常入口，并返回统一清理函数。
 - 异常记录标准化：用于把浏览器或 Node.js 的原始输入整理成稳定的异常记录结构。
-- 类型与清理语义：用于表达异常来源种类、记录形状以及取消监听的统一返回类型。
+- Tagged Error 建模：用于定义一类带 `tag`、`data`、`cause` 与序列化能力的结构化异常类型。
+- Tagged Error 匹配：用于按 tag 分派这一类结构化异常的处理逻辑，并在类型层保留分支信息。
+- 类型与清理语义：用于表达异常来源种类、异常记录形状、结构化异常实例能力以及取消监听的统一返回类型。
 
-使用时应把它接在 logger、遥测、监控、恢复策略或业务错误处理的上游，而不是期待它直接替代这些能力。它更适合作为异常输入层，而不是最终处理层。
+使用时应把它接在 logger、遥测、监控、恢复策略或业务错误处理的上游，而不是期待它直接替代这些能力。更准确地说，它适合作为异常输入与异常表达的基础层，而不是最终处理层。
 
 ## For Contributing
 
-贡献 Exception 模块时，应优先判断新增能力是否表达了稳定、可复用的宿主级异常来源，还是只是某个框架、某个应用内部错误流的便捷包装。只有前者才适合进入这个模块。
+贡献 Exception 模块时，应优先判断新增能力是否真正扩展了“异常模型”这个问题域，而不是只是在当前实现里顺手添加一个便捷函数。只有当某项能力表达了稳定、可复用、值得长期维护的异常来源语义，或表达了某类异常的稳定建模语义时，它才适合进入这个模块。
 
 在扩展时，应优先遵守以下边界：
 
-- 公共能力应围绕宿主异常入口、标准化记录与监听清理语义展开。
-- 不要在监听逻辑中默认执行日志输出、上报请求、`preventDefault`、`process.exit` 或其它强策略动作，除非 API 名称与文档已经明确承诺。
+- 公共能力应围绕宿主异常入口、异常记录标准化，以及其中可被稳定表达的结构化异常建模与匹配语义展开。
+- 若新增的是模块内稳定异常模型，且它适合以 Error 形式存在，应优先使用 Tagged Error 形式表达，而不是仅靠裸字符串或无判别字段的对象。
+- 不要在监听逻辑或异常模型中默认执行日志输出、上报请求、`preventDefault`、`process.exit`、重试、恢复或其它强策略动作，除非 API 名称与文档已经明确承诺。
 - 组合入口只负责批量安装监听器与汇总清理，不负责掩盖宿主差异或替调用方做策略决策。
-- 与 Environment 的关系应保持清楚：Environment 可以帮助判断和获取宿主上下文，Exception 则负责安装异常监听器。
+- Tagged Error 的职责是提供一类稳定异常表达、判别和匹配语义，而不是承载某个单一应用的临时上下文容器。
+- 与 Environment 的关系应保持清楚：Environment 可以帮助判断和获取宿主上下文，Exception 则负责异常入口与异常模型本身。
 
 ### JSDoc 注释格式要求
 
@@ -82,7 +90,7 @@ Exception 模块提供围绕宿主环境全局异常入口（global exception en
 - 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
 - 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
 - Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
-- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的异常入口语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的异常模型语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
 
 ### 测试要求
 
@@ -94,3 +102,4 @@ Exception 模块提供围绕宿主环境全局异常入口（global exception en
 - 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
 - 模块的单元测试文件目录是 `./tests/unit/exception`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/exception/<sub-module-name>`。
 - 测试应重点覆盖监听注册、清理行为、默认包含的入口集合、记录标准化结果，以及宿主不可用时的失败或空操作语义是否稳定。
+- 若新增 Tagged Error 能力，应重点覆盖 tag 判别、message 与 `cause` 推导、序列化结果，以及按 tag 进行穷举或部分匹配时的返回语义是否稳定。

package/src/exception/error/error.ts

@@ -0,0 +1,123 @@
+
+const isString = (value: unknown): value is string => {
+  return typeof value === "string"
+}
+const isObject = (value: unknown): value is object => {
+  return typeof value === "object" && value !== null
+}
+const extractMessage = (data: unknown): string | undefined => {
+  if (isString(data)) {
+    return data
+  } else if (isObject(data) && "message" in data && isString(data.message)) {
+    return data.message
+  } else {
+    return undefined
+  }
+}
+const extractCause = (data: unknown): unknown => {
+  if (isObject(data) && "cause" in data) {
+    return data.cause
+  } else {
+    return undefined
+  }
+}
+const formatCauseStack = (cause: unknown): string => {
+  if ((cause instanceof Error) === false || cause.stack === undefined) {
+    return ""
+  }
+  const indented = cause.stack.replaceAll("\n", "\n  ")
+  return `\nCaused by: ${indented}`
+}
+const serializeCause = (cause: unknown): unknown => {
+  if (cause instanceof Error) {
+    return { name: cause.name, message: cause.message, stack: cause.stack };
+  }
+  return cause
+}
+
+export interface SerializedTaggedError<Tag extends string, Data = unknown> {
+  version: "1" // for future compatibility
+  tag: Tag
+  data: Data
+  name: string
+  message: string
+  cause: unknown | undefined
+  stack: string | undefined
+  timestamp: number
+}
+export interface TaggedErrorAugments<Tag extends string, Data = unknown> {
+  readonly tag: Tag
+  readonly data: Data
+  toJSON(): SerializedTaggedError<Tag, Data>
+}
+export type TaggedErrorInstance<Tag extends string, Data = unknown> =
+  & Error
+  & TaggedErrorAugments<Tag, Data>
+export type TaggedErrorConstructor<Tag extends string, Data = unknown> = {
+  new(data: Data): TaggedErrorInstance<Tag, Data>
+  is(target: unknown): target is TaggedErrorInstance<Tag, Data>
+}
+export const createTaggedError = <const Tag extends string>(tag: Tag) => {
+  return <Data = unknown>(): TaggedErrorConstructor<Tag, Data> => {
+    return class Impl extends Error {
+      readonly tag: Tag
+      readonly data: Data
+
+      constructor(data: Data) {
+        const message = extractMessage(data)
+        const cause = extractCause(data)
+
+        super(message, cause !== undefined ? { cause } : undefined)
+        Object.setPrototypeOf(this, new.target.prototype)
+        this.name = tag
+        this.stack = `${this.stack}${formatCauseStack(cause)}`
+
+        this.tag = tag
+        this.data = data
+      }
+
+      static is(target: unknown): target is TaggedErrorInstance<Tag, Data> {
+        if (target instanceof Impl) {
+          return true
+        }
+        if (isTaggedError(target) && target.tag === tag) {
+          return true
+        }
+        return false
+      }
+
+      toJSON(): SerializedTaggedError<Tag, Data> {
+        return {
+          version: "1",
+          tag: this.tag,
+          data: this.data,
+          name: this.name,
+          message: this.message,
+          cause: serializeCause(this.cause),
+          stack: this.stack,
+          timestamp: Date.now(),
+        }
+      }
+    }
+  }
+}
+
+export type AnyTaggedError = TaggedErrorInstance<string, unknown>
+export const isTaggedError = (target: unknown): target is AnyTaggedError => {
+  if (typeof target !== "object" || target === null) {
+    return false
+  }
+  if (target instanceof Error === false) {
+    return false
+  }
+  if (!("tag" in target) || typeof target.tag !== "string") {
+    return false
+  }
+  if (!("data" in target)) {
+    return false
+  }
+  if (!("toJSON" in target) || typeof target.toJSON !== "function") {
+    return false
+  }
+  return true
+}

package/src/exception/error/index.ts

@@ -0,0 +1,2 @@
+export * from "./error.ts"
+export * from "./match.ts"

package/src/exception/error/match.ts

@@ -0,0 +1,38 @@
+import type { AnyTaggedError } from "./error.ts"
+
+export type MatchTaggedErrorHandlers<E extends AnyTaggedError, R> = {
+  [Tag in E["tag"]]: (error: Extract<E, { tag: Tag }>) => R
+}
+export const matchTaggedError = <E extends AnyTaggedError, R>(
+  taggedError: E,
+  handlers: MatchTaggedErrorHandlers<E, R>,
+): R => {
+  const handler = handlers[taggedError.tag as E["tag"]]
+  if (handler === undefined) {
+    throw new Error(`No handler for tag: ${taggedError.tag}`)
+  }
+  return handler(taggedError as Extract<E, { tag: E["tag"] }>)
+}
+
+export type MatchTaggedErrorPartialHandlers<E extends AnyTaggedError, R> = {
+  [Tag in E["tag"]]?: ((error: Extract<E, { tag: Tag }>) => R) | undefined
+}
+type UnhandledTaggedError<E extends AnyTaggedError, H> = Exclude<
+  E,
+  { tag: keyof H }
+>
+export const matchTaggedErrorPartial = <
+  E extends AnyTaggedError,
+  R,
+  const Handlers extends MatchTaggedErrorPartialHandlers<E, R> = MatchTaggedErrorPartialHandlers<E, R>
+>(
+  taggedError: E,
+  handlers: Handlers,
+  fallback: (error: UnhandledTaggedError<E, Handlers>) => R,
+): R => {
+  const handler = handlers[taggedError.tag as E["tag"]]
+  if (handler !== undefined) {
+    return handler(taggedError as Extract<E, { tag: E["tag"] }>)
+  }
+  return fallback(taggedError as UnhandledTaggedError<E, Handlers>)
+}