@planet-matrix/mobius-model 0.5.0 → 0.9.0

package/src/identifier/README.md

@@ -0,0 +1,92 @@
+# Identifier
+
+## Description
+
+Identifier 模块用于提供围绕逻辑标识（logical identifier）进行生成、判断、断言、比较与序列化的基础能力，并统一收纳与通用唯一标识符（UUID, Universally Unique Identifier）相关的格式校验与生成语义。
+
+它关注的是“系统如何稳定表达身份与标识”，而不是某个业务系统的编号规则、数据库主键策略或外部协议字段约定。
+
+## For Understanding
+
+理解 Identifier 模块时，应先把逻辑身份与标识格式区分开。这里同时承载两类彼此相关、但层次不同的能力：
+
+- `Id` 用于表达库内部的逻辑身份，是一种不透明的运行时标识值。
+- `UUID` 用于表达广泛使用的通用标识字符串格式，适合在系统边界做校验、断言、版本读取和字符串生成。
+
+把这两类能力放在同一个模块中，核心原因不是它们实现方式相同，而是它们都服务于“谁是谁、一个标识是否合法、一个标识如何被稳定生成和传递”这一共同问题域。相对地，随机字符串本身更偏向随机输入生成，不再属于这个边界。
+
+这个模块不适合承载数据库自增键、雪花算法、业务编码规则、分布式全局编号体系或任何需要额外持久化与跨系统一致性承诺的标识模型。若未来出现这类需求，应按更明确的问题域继续建模，而不是直接膨胀当前模块。
+
+## For Using
+
+当你需要在系统中稳定表达身份语义，或在边界层处理 UUID 一类的通用标识字符串时，可以使用这个模块。它适合放在跨模块协作、基础设施边界、日志关联、资源索引和接口参数校验等场景中。
+
+当前公共能力大致可以按以下几类理解：
+
+- 逻辑身份生成：用于创建新的 `Id`，或基于同一种子复用同一个运行时标识实例。
+- 逻辑身份判断与比较：用于判断一个值是否为 `Id`，以及区分“同一个实例”和“同一个内部标识值”。
+- 逻辑身份序列化：用于把 `Id` 转换为适合日志、调试和展示的字符串形式。
+- UUID 校验与断言：用于在外部输入进入系统前确认其格式是否合法。
+- UUID 生成：用于生成 UUID v4 与 UUID v7 字符串，以满足常规唯一性和近似时间有序标识场景。
+
+更合理的接入方式，是在边界层尽早决定你需要的是“内部逻辑身份”还是“外部通用标识字符串”。两者虽然都属于 Identifier，但不应相互混用。
+
+## For Contributing
+
+贡献 Identifier 模块时，应优先判断新增能力是否真的在澄清标识语义，而不是借“编号”或“随机”名义引入其它问题域。这里应长期承载的是逻辑身份模型与通用标识格式模型，而不是各种临时编码技巧的集合。
+
+在扩展时，应优先遵守以下边界：
+
+- `Id` 应继续保持为不透明的逻辑身份值，不要让调用方依赖其内部结构。
+- UUID 相关能力应围绕格式判断、断言、版本提取和生成展开，不要混入业务编号规则。
+- 如果某个能力的重点已经变成“随机文本如何生成”，应优先考虑 Random 模块，而不是继续放入 Identifier。
+- 如果某个能力需要更强的持久化、安全性或跨系统一致性承诺，应在更具体的问题域中单独建模。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/identifier/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/identifier`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/identifier/<sub-module-name>`。
+- 测试应重点覆盖带种子与不带种子的 `Id` 生成语义、`Id` 的比较与序列化，以及 UUID 的格式校验、版本读取和不同生成路径的结果特征。

package/src/identifier/id.ts

@@ -0,0 +1,119 @@
+import { generateUuidV7 } from "./uuid.ts"
+
+const INTERNAL_ID: unique symbol = Symbol("INTERNAL_ID")
+type IdentifierSeed = string | number | symbol
+
+/**
+ * Represent a logical identity value.
+ *
+ * @example
+ * ```
+ * const userId = generateId("user:1")
+ * const example1 = isId(userId)
+ * // Expect: true
+ *
+ * const example2 = String(userId)
+ * // Expect: starts with "Symbol-ID-"
+ * ```
+ */
+export interface Id {
+  [INTERNAL_ID]: string
+  [Symbol.toPrimitive]: (hint: string) => string
+}
+
+const internalIdPacket: Record<IdentifierSeed, Id> = {}
+
+/**
+ * 根据种子生成 `Id`，或在未提供种子时生成一个新的 `Id`。
+ *
+ * 当传入种子时，同一种子会复用同一个 `Id` 实例；未传入种子时，每次都会得到新的 `Id`。
+ *
+ * @example
+ * ```
+ * const stableA = generateId("user:1")
+ * const stableB = generateId("user:1")
+ * const example1 = Object.is(stableA, stableB)
+ * // Expect: true
+ *
+ * const freshA = generateId()
+ * const freshB = generateId()
+ * const example2 = Object.is(freshA, freshB)
+ * // Expect: false
+ * ```
+ */
+export const generateId = (seed?: IdentifierSeed | undefined): Id => {
+  if (seed === undefined) {
+    const id = {
+      [INTERNAL_ID]: generateUuidV7(),
+      [Symbol.toPrimitive]: (): string => {
+        return idToString(id)
+      },
+    }
+    return id
+  }
+
+  const id = internalIdPacket[seed] ?? {
+    [INTERNAL_ID]: generateUuidV7(),
+    [Symbol.toPrimitive]: (): string => {
+      return idToString(id)
+    },
+  }
+  internalIdPacket[seed] = id
+
+  return id
+}
+
+/**
+ * 判断一个值是否为 `Id`。
+ */
+export const isId = (target: unknown): target is Id => {
+  return typeof target === "object" && target !== null && INTERNAL_ID in target
+}
+
+type AssertId = (target: unknown) => asserts target is Id
+
+/**
+ * 断言一个值是 `Id`。
+ *
+ * @throws {TypeError} 当 target 不是 `Id` 时抛出
+ */
+export const assertId: AssertId = (target: unknown): void => {
+  if (isId(target) === false) {
+    throw new TypeError(`Expected Id, got: ${String(target)}`)
+  }
+}
+
+/**
+ * 按引用身份比较两个 `Id` 值是否为同一个实例。
+ */
+export const isSameId = (a: Id, b: Id): boolean => {
+  return Object.is(a, b)
+}
+
+/**
+ * 按内部标识值比较两个 `Id` 是否相等。
+ */
+export const isEqualId = (a: Id, b: Id): boolean => {
+  return a[INTERNAL_ID] === b[INTERNAL_ID]
+}
+
+/**
+ * 将 `Id` 转换为可读字符串。
+ *
+ * 返回值格式为 `Symbol-ID-<uuid>`。
+ *
+ * @example
+ * ```
+ * const userId = generateId("user:1")
+ * const example1 = idToString(userId)
+ * // Expect: starts with "Symbol-ID-"
+ *
+ * const anonymousId = generateId()
+ * const example2 = idToString(anonymousId)
+ * // Expect: matches the format "Symbol-ID-<uuid>"
+ * ```
+ */
+export const idToString = (id: Id): string => {
+  assertId(id)
+  return `Symbol-ID-${id[INTERNAL_ID]}`
+}

package/src/identifier/index.ts

@@ -0,0 +1,2 @@
+export * from "./id.ts"
+export * from "./uuid.ts"

package/src/identifier/uuid.ts

@@ -0,0 +1,187 @@
+
+const internalUUID_REGEXP = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
+
+/**
+ * 判断输入值是否为合法的 UUID 字符串。
+ *
+ * @example
+ * ```
+ * // Expect: true
+ * const example1 = isUuid("550e8400-e29b-41d4-a716-446655440000")
+ * // Expect: false
+ * const example2 = isUuid("not-a-uuid")
+ * ```
+ */
+export const isUuid = (input: string): boolean => {
+  return internalUUID_REGEXP.test(input)
+}
+
+/**
+ * 断言输入值是合法的 UUID 字符串。
+ *
+ * 当输入值不满足 UUID 格式时，该函数会抛出 TypeError，适合在标识边界层做快速失败。
+ *
+ * @example
+ * ```
+ * // Expect: no throw
+ * const example1 = assertUuid("550e8400-e29b-41d4-a716-446655440000")
+ * // Expect: throws TypeError
+ * const example2 = () => assertUuid("not-a-uuid")
+ * ```
+ *
+ * @throws {TypeError} when input is not a valid UUID
+ */
+export const assertUuid = (input: string): void => {
+  if (isUuid(input) === false) {
+    throw new TypeError(`Expected a valid UUID string, got: ${input}`)
+  }
+}
+
+/**
+ * 读取合法 UUID 字符串中的版本号。
+ *
+ * 该函数会先校验输入格式；如果输入不是合法 UUID，则会抛出 TypeError。
+ *
+ * @example
+ * ```
+ * // Expect: 4
+ * const example1 = getUuidVersion("550e8400-e29b-41d4-a716-446655440000")
+ * // Expect: 1
+ * const example2 = getUuidVersion("123e4567-e89b-12d3-a456-426614174000")
+ * ```
+ *
+ * @throws {TypeError} when input is not a valid UUID
+ */
+export const getUuidVersion = (input: string): number => {
+  assertUuid(input)
+  return Number.parseInt(input[14]!, 16)
+}
+
+/**
+ * 生成 UUID v4 字符串。
+ *
+ * 当运行时提供 Web Crypto 能力时，优先使用安全随机源；否则回退到兼容性方案。
+ *
+ * @example
+ * ```
+ * const uuid = generateUuidV4()
+ * // Expect: true
+ * const example1 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(uuid)
+ * ```
+ */
+export const generateUuidV4 = (): string => {
+  if (globalThis.crypto !== undefined) {
+    const { crypto } = globalThis
+
+    if (typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID()
+    }
+
+    if (typeof crypto.getRandomValues === "function" && typeof Uint8Array === "function") {
+      const buffer = new Uint8Array(16)
+      crypto.getRandomValues(buffer)
+
+      buffer[6] = (buffer[6]! & 0x0F) | 0x40
+      buffer[8] = (buffer[8]! & 0x3F) | 0x80
+
+      const hex = [...buffer].map(value => value.toString(16).padStart(2, "0")).join("")
+      return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+    }
+  }
+
+  const fallbackUUID = (): string => {
+    const random = (value: number): string => {
+      return ((value ^ ((Math.random() * 16) >> (value / 4))) & 15).toString(16)
+    }
+
+    return "10000000-1000-4000-8000-100000000000".replaceAll(/[018]/g, (char: string) => random(Number(char)))
+  }
+
+  return fallbackUUID()
+}
+
+/**
+ * 通过 URL.createObjectURL 侧向取得一个 UUID v4 风格的字符串。
+ *
+ * 该函数依赖 Blob 与 URL API，适合浏览器等具备对象 URL 能力的环境。
+ * 如果只需要常规 UUID v4，优先使用 generateUuidV4。
+ *
+ * @example
+ * ```
+ * const uuid = generateUuidV4FromUrl()
+ * // Expect: true
+ * const example1 = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(uuid)
+ * // Expect: 36
+ * const example2 = uuid.length
+ * ```
+ */
+export const generateUuidV4FromUrl = (): string => {
+  const tempURL = URL.createObjectURL(new Blob())
+  const uuidInUrl = tempURL
+  URL.revokeObjectURL(tempURL)
+  const uuid = uuidInUrl.slice(uuidInUrl.lastIndexOf("/") + 1)
+  return uuid
+}
+
+const internalUUIDv7RandomMask74 = (1n << 74n) - 1n
+const internalUUIDv7RandomMask48 = (1n << 48n) - 1n
+let internalUUIDv7LastTimestamp = -1n
+let internalUUIDv7MonotonicValue = 0n
+
+const internalUUIDv7FillRandom = (buffer: Uint8Array): void => {
+  if (globalThis.crypto !== undefined) {
+    const { crypto } = globalThis
+    if (typeof crypto.getRandomValues === "function") {
+      crypto.getRandomValues(buffer)
+      return
+    }
+  }
+
+  console.warn("generateUuidV7 requires crypto.getRandomValues")
+  for (let i = 0; i < 10; i = i + 1) {
+    buffer[i] = Math.floor(Math.random() * 256)
+  }
+}
+
+const internalUUIDv7NextRandom74 = (timestamp: bigint): bigint => {
+  if (timestamp !== internalUUIDv7LastTimestamp) {
+    const randomValues = new Uint8Array(10)
+    internalUUIDv7FillRandom(randomValues)
+
+    const randomHex = Array.from(randomValues, value => value.toString(16).padStart(2, "0")).join("")
+    internalUUIDv7MonotonicValue = BigInt(`0x${randomHex}`) & internalUUIDv7RandomMask74
+    internalUUIDv7LastTimestamp = timestamp
+    return internalUUIDv7MonotonicValue
+  }
+
+  internalUUIDv7MonotonicValue = (internalUUIDv7MonotonicValue + 1n) & internalUUIDv7RandomMask74
+  return internalUUIDv7MonotonicValue
+}
+
+/**
+ * 生成 UUID v7 字符串。
+ *
+ * 结果以前导时间戳编码排序信息，适合需要近似按生成时间排序的标识场景。
+ *
+ * @example
+ * ```
+ * const uuid = generateUuidV7()
+ * // Expect: true
+ * const example1 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(uuid)
+ * ```
+ */
+export const generateUuidV7 = (): string => {
+  const timestamp = BigInt(Date.now())
+  const random74 = internalUUIDv7NextRandom74(timestamp)
+  const timeHex = timestamp.toString(16).padStart(12, "0")
+
+  const randAValue = Number((random74 >> 62n) & 0xFFFn)
+  const randBValue = Number((random74 >> 48n) & 0x3FFFn)
+  const trailingValue = random74 & internalUUIDv7RandomMask48
+
+  const randA = ((0x7 << 12) | randAValue) & 0xFFFF
+  const randB = ((0x2 << 14) | randBValue) & 0xFFFF
+  const trailingHex = trailingValue.toString(16).padStart(12, "0")
+
+  return `${timeHex.slice(0, 8)}-${timeHex.slice(8, 12)}-${randA.toString(16).padStart(4, "0")}-${randB.toString(16).padStart(4, "0")}-${trailingHex}`
+}

package/src/index.ts

@@ -1,5 +1,37 @@
 export * as Basic from "./basic/index.ts"
-export * as Type from "./type/index.ts"
+export type * as Type from "./type/index.ts"
+
+export * as Environment from "./environment/index.ts"
+export * as Exception from "./exception/index.ts"
+export * as Event from "./event/index.ts"
+export * as Singleton from "./singleton/index.ts"
+
+export * as Abort from "./abort/index.ts"
+export * as Log from "./log/index.ts"
 export * as Reactor from "./reactor/index.ts"
+export * as Result from "./result/index.ts"
+export * as Form from "./form/index.ts"
+export * as Request from "./request/index.ts"
+export * as Route from "./route/index.ts"
+export * as Timer from "./timer/index.ts"
+export * as Cron from "./cron/index.ts"
+export * as Orchestration from "./orchestration/index.ts"
+export * as Socket from "./socket/index.ts"
+export * as Http from "./http/index.ts"
+
+export * as Identifier from "./identifier/index.ts"
+export * as Credential from "./credential/index.ts"
 export * as Encoding from "./encoding/index.ts"
 export * as Random from "./random/index.ts"
+export * as Color from "./color/index.ts"
+export * as Json from "./json/index.ts"
+export * as Aio from "./aio/index.ts"
+
+export * as Web from "./web/index.ts"
+export * as CSS from "./css/index.ts"
+export * as Drizzle from "./drizzle/index.ts"
+export * as Email from "./email/index.ts"
+export * as Huawei from "./huawei/index.ts"
+export * as Openai from "./openai/index.ts"
+export * as Weixin from "./weixin/index.ts"
+export * as Ai from "./ai/index.ts"

package/src/json/README.md

@@ -0,0 +1,92 @@
+# JSON
+
+## Description
+
+JSON 模块提供围绕 JSON（JavaScript Object Notation）这一数据表示格式的相关基础能力，用于承载与 JSON 本身直接相关、且值得长期稳定维护的公共语义。
+
+当前模块公开能力还很少，暂时只有 `repair` 这一项文本修复入口；但这不意味着模块边界仅限于修复本身，而是说明 JSON 相关能力仍在逐步沉淀中。
+
+## For Understanding
+
+理解 JSON 模块时，应把它看作一个围绕 JSON 本身建立的问题域模块，而不是一个泛化的数据清洗工具箱，也不是任意对象处理逻辑的收纳处。判断某项能力是否应进入这里，关键不在于它“碰巧输入或输出了 JSON”，而在于它是否直接服务于 JSON 这一表示格式本身的稳定语义。
+
+这类能力通常可能包括 JSON 文本修复、序列化与反序列化辅助、稳定格式化、合法性判断、边界明确的表示转换，或其它直接围绕 JSON 文本与 JSON 语义展开的基础能力。当前仓库里之所以只有 `repair`，只是因为模块还处在较早阶段，而不是因为其它 JSON 相关能力天然不属于这里。
+
+当前边界可以概括为：
+
+- 它可以承载与 JSON 本身直接相关的公共能力，而不局限于当前已经存在的 `repair`。
+- 它关注的是 JSON 作为表示格式时的稳定语义，而不是解析后对象在业务上的含义。
+- 它可以处理文本层问题，也可以在未来扩展到仍然属于 JSON 语义边界内的其它能力。
+- 它不应因为名称宽泛就退化成杂项对象工具箱或通用数据清洗工具箱。
+
+因此，这个模块不应承载对象结构校验、字段语义补全、领域模型迁移、容错合并或业务级默认值推导。那些问题可能发生在 JSON 之前或之后，也可能依赖 JSON 作为载体，但并不因此自动属于 JSON 模块。
+
+## For Using
+
+当你需要复用一类与 JSON 本身直接相关的基础能力，而不是在业务代码里零散处理 JSON 文本、解析入口或表示细节时，可以使用这个模块。当前最直接的使用场景，是在解析之前先修复接近 JSON、但带有轻微格式噪声的文本，例如人工编辑配置、LLM 输出、宽松的第三方接口返回、日志片段复制结果，或历史遗留系统吐出的近似 JSON 文本。
+
+当前公共能力可以从使用意图上理解为一类入口：
+
+- 文本修复入口：把接近 JSON 的字符串整理成可继续交给标准解析器处理的 JSON 文本。
+
+随着模块扩展，未来也可以继续容纳其它直接服务于 JSON 语义的公共入口。但即便如此，使用时仍应区分“JSON 本身的问题”和“业务对象的问题”：如果你的问题已经变成对象级校验、字段默认值注入、结构迁移或业务容错，那么应在其它模块或上层流程中继续分层，而不要把这些职责压回 JSON 模块。
+
+## For Contributing
+
+贡献 JSON 模块时，应优先判断新增能力是否直接表达 JSON 本身的稳定语义，而不是借着 JSON 的名字引入对象级处理、业务级清洗或协议级解释逻辑。这个模块可以继续增长，但增长方向应围绕 JSON 自身的问题域展开，而不是因为名字宽泛就无限吸纳一切与对象或文本有关的工具。
+
+在扩展时，应优先遵守以下边界：
+
+- 公共能力应直接围绕 JSON 本身展开，例如表示修复、合法性处理、稳定序列化或其它明确属于 JSON 语义的能力。
+- 不要把 schema 校验、字段补全、结构迁移、业务默认值或容错合并直接写成 JSON 模块的公共职责。
+- 若新增能力只是“使用了 JSON”但核心问题并不属于 JSON 本身，则应放在更合适的模块，而不是为了归类方便塞进这里。
+- 对于像 `repair` 这类带有容错性质的能力，应保持失败语义清楚；当输入不能被稳定处理时，抛错通常比返回含糊结果更符合模块边界。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/json/internal.ts`；若当前模块仍然很小，则不必为了形式拆出没有稳定价值的共享文件。
+- 模块内可以包含子模块。只有当某个子目录表达一个稳定、可单独理解、且可能被父模块重导出的子问题域时，才应将其视为子模块。
+- 子模块包含多个文件时，应该为其单独创建子文件夹，并为其创建单独的 Barrel 文件；父模块的 Barrel 文件再重导出子模块的 Barrel 文件。
+- 子模块不需要有自己的 `README.md`。
+- 子模块可以有自己的 `internal.ts` 文件，多个子模块共享的辅助元素应该放在父模块的 `internal.ts` 文件中，单个子模块共享的辅助元素应该放在该子模块的 `internal.ts` 文件中。
+- 对模块依赖关系的要求（通常是不循环依赖或不反向依赖）与对 DRY 的要求可能产生冲突。此时，若复用的代码数量不大，可以适当牺牲 DRY，复制粘贴并保留必要的注释说明；若复用的代码数量较大，则可以将其抽象到新的文件或子模块中，如 `common.ts`，并在需要的地方导入使用。
+- 实现时应优先保持输入、输出与失败条件的语义清楚；若某项能力具有容错或修复性质，不应为了支持更多特例不断堆叠难以解释的隐式规则。
+
+### 导出策略要求
+
+- 保持内部辅助项和内部符号为私有，不要让外部接入依赖临时性的内部结构。
+- 每个模块都应有一个用于重导出所有公共 API 的 Barrel 文件。
+- Barrel 文件应命名为 `index.ts`，放在模块目录根部，并且所有公共 API 都应从该文件导出。
+- 新增公共能力时，应优先检查它是否表达稳定、清楚且值得长期维护的 JSON 模块语义，而不是某段实现细节的便捷暴露；仅在确认需要长期对外承诺时再加入 Barrel 导出。
+
+### 测试要求
+
+- 若程序元素是函数，则只为该函数编写一个测试，如果该函数需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，则至少要为该类的每一个方法编写一个测试，如果该方法需要测试多个用例，应放在同一个测试中。
+- 若程序元素是类，除了为该类的每一个方法编写至少一个测试之外，还可以为该类编写任意多个测试，以覆盖该类的不同使用场景或边界情况。
+- 若编写测试时需要用到辅助元素（Mock 或 Spy 等），可以在测试文件中直接定义这些辅助元素。若辅助元素较为简单，则可以直接放在每一个测试内部，优先保证每个测试的独立性，而不是追求极致 DRY；若辅助元素较为复杂或需要在多个测试中复用，则可以放在测试文件顶部，供该测试文件中的所有测试使用。
+- 测试顺序应与源文件中被测试目标的原始顺序保持一致。
+- 若该模块不需要测试，必须在说明文件中明确说明该模块不需要测试，并说明理由。一般来说，只有在该模块没有可执行的公共函数、只承载类型层表达，或其语义已被上层模块的测试完整覆盖且重复测试几乎不再带来额外价值时，才适合这样处理。
+- 模块的单元测试文件目录是 `./tests/unit/json`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/json/<sub-module-name>`。
+- 测试应覆盖各公共能力各自的稳定语义。对于当前已有的 `repair`，重点覆盖可稳定修复的常见格式问题，以及超出修复边界时是否以明确失败结束，而不是返回含糊结果。

package/src/json/index.ts

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

package/src/json/repair.ts

@@ -0,0 +1,18 @@
+import { jsonrepair } from "jsonrepair"
+
+/**
+ * 修复常见格式问题后的 JSON 文本字符串。
+ *
+ * 该函数面向“文本表示修复”这一问题：当输入接近 JSON、但包含单引号、未加引号的键名、尾随逗号等常见格式问题时，可以先把它整理成合法 JSON 文本，再交给后续解析流程。
+ *
+ * @example
+ * ```
+ * // Expect: "{\"foo\":1}"
+ * const example1 = repairJson("{foo:1,}")
+ * // Expect: "{\"name\":\"mobius\"}"
+ * const example2 = repairJson("{'name':'mobius',}")
+ * ```
+ */
+export const repairJson = (text: string): string => {
+  return jsonrepair(text)
+}

package/src/log/README.md

@@ -0,0 +1,79 @@
+# Log
+
+## Description
+
+Log 模块用于提供结构化日志（structured logging）能力，主要承载日志记录、日志上下文组织、日志发送以及日志调度等稳定语义。
+
+它面向的是“如何把日志当作一类可长期维护的数据模型”这一问题，而不是若干零散的输出函数。模块内的公共能力应帮助调用方稳定地表达日志类型、日志记录、日志发送端和日志调度过程，而不是把日志格式拼接、上下文透传和输出策略分散到业务代码里临时处理。
+
+## For Understanding
+
+理解 Log 模块时，首先应把它看作日志生命周期的建模层，而不是异常捕获入口的集合。它解决的是“如何描述一条日志、如何附加上下文、如何把日志发往不同输出端、如何协调这些输出过程”这一类问题，因此适合放在应用、服务、组件或基础设施边界之间，作为统一的日志语义层。
+
+这个模块的边界重点在于“组织和消费日志”，而不是“发现错误来源”。像浏览器全局异常监听、Node.js 进程级未处理异常监听、框架级错误边界之类的能力，虽然最终经常会把结果送入 logger，但它们表达的是上游事件来源，不应直接并入 Log 模块本身。否则模块会同时承担异常捕获、日志建模和日志分发三类职责，边界会迅速变得模糊。
+
+因此，适合进入本模块的能力，应当围绕以下几类稳定语义展开：日志级别与日志记录本身的表达、logger 的上下文继承与派生、日志发送端的抽象、以及对发送过程的统一调度。若新增能力主要是在监听某个宿主环境的异常入口，通常应优先放到更靠近环境或异常语义的模块中，再由上层决定是否接入 Log 模块。
+
+## For Using
+
+当你希望在系统内维持一致的日志结构，而不是在每次输出时手工拼接字符串、标签和上下文时，可以使用这个模块。它适合那些需要长期保留日志语义、希望在多个输出端之间复用同一份日志记录结构的场景。
+
+从使用角度看，这个模块大致可以理解为几类能力的组合。第一类是日志记录本身，用来表达日志类型、消息和附加数据，让日志作为结构化对象被传递与消费。第二类是 logger 入口，用来在局部范围中派生带上下文的日志能力，使业务层不必重复附加相同的标签、作用域或元信息。第三类是发送与调度能力，用来把日志记录发往控制台或其它输出端，并把输出时机与策略统一收敛到日志系统内部。
+
+更合适的接入方式，是在业务边界尽早把日志上下文组织清楚，再将记录交给 logger、emitter 或 scheduler 处理，而不是在底层输出瞬间才临时补齐信息。这样做能够让日志在演进过程中保持稳定结构，也便于后续替换输出端、追加上下文或统一调整日志策略。
+
+## For Contributing
+
+贡献 Log 模块时，首要任务不是补一个“能打印出来”的便捷函数，而是确认新增能力是否确实表达了稳定的日志语义。这个模块应长期围绕日志记录、上下文组织、输出抽象和调度协作展开；任何新增公共能力，都应说明它解决的是哪一段日志生命周期问题，以及它为什么值得成为长期承诺的一部分。
+
+在扩展时，应持续守住以下边界：不要把宿主环境特有的异常捕获入口直接塞进来；不要把只对某个特定日志平台或某个业务日志格式成立的细节公开承诺出去；不要让 logger 退化为简单字符串打印器。对外语义应优先是“日志模型”和“日志协作方式”，而不是某一次实现中的输出技巧。
+
+### JSDoc 注释格式要求
+
+- 每个公开导出的目标（类型、函数、变量、类等）都应包含 JSDoc 注释，让人在不跳转实现的情况下就能理解用途。
+- JSDoc 注释第一行应为清晰且简洁的描述，该描述优先使用中文（英文也可以）。
+- 如果描述后还有其他内容，应在描述后加一个空行。
+- 如果有示例，应使用 `@example` 标签，后接三重反引号代码块（不带语言标识）。
+- 如果有示例，应包含多个场景，展示不同用法，尤其要覆盖常见组合方式或边界输入。
+- 如果有示例，应使用注释格式说明每个场景：`// Expect: <result>`。
+- 如果有示例，应将结果赋值给 `example1`、`example2` 之类的变量，以保持示例易读。
+- 如果有示例，`// Expect: <result>` 应该位于 `example1`、`example2` 之前，以保持示例的逻辑清晰。
+- 如果有示例，应优先使用确定性示例；避免断言精确的随机输出。
+- 如果函数返回结构化字符串，应展示其预期格式特征。
+- 如果有参考资料，应将 `@see` 放在 `@example` 代码块之后，并用一个空行分隔。
+
+### 实现规范要求
+
+- 不同程序元素之间使用一个空行分隔，保持结构清楚。这里的程序元素，通常指函数、类型、常量，以及直接服务于它们的辅助元素。
+- 某程序元素独占的辅助元素与该程序元素本身视为一个整体，不要在它们之间添加空行。
+- 程序元素的辅助元素应该放置在该程序元素的上方，以保持阅读时的逻辑顺序。
+- 若辅助元素被多个程序元素共享，则应将其视为独立的程序元素，放在这些程序元素中第一个相关目标的上方，并与后续程序元素之间保留一个空行。
+- 辅助元素也应该像其它程序元素一样，保持清晰的命名和适当的注释，以便在需要阅读实现细节时能够快速理解它们的作用和使用方式。
+- 辅助元素的命名必须以前缀 `internal` 开头（或 `Internal`，大小写不敏感）。
+- 辅助元素永远不要公开导出。
+- 被模块内多个不同文件中的程序元素共享的辅助元素，应该放在一个单独的文件中，例如 `./src/log/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/log`，若模块包含子模块，则子模块的单元测试文件目录为 `./tests/unit/log/<sub-module-name>`。
+- 对 logger、emitter、scheduler 这一类能力，应优先覆盖上下文继承、发送顺序、失败传播、默认行为与资源清理等关键场景。

package/src/log/index.ts

@@ -0,0 +1,5 @@
+export * from "./log-type.ts"
+export type * from "./log-record.ts"
+export * from "./log-emitter.ts"
+export * from "./log-scheduler.ts"
+export * from "./logger.ts"