@planet-matrix/mobius-model 0.4.0 → 0.6.0

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,3 +1,20 @@
 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 Log from "./log/index.ts"
+export * as Abort from "./abort/index.ts"
 export * as Reactor from "./reactor/index.ts"
+export * as Timer from "./timer/index.ts"
+export * as Orchestration from "./orchestration/index.ts"
+
+export * as Identifier from "./identifier/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 Web from "./web/index.ts"
+export * as CSS from "./css/index.ts"

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"

package/src/log/log-emitter.ts

@@ -0,0 +1,72 @@
+import type { LogRecord } from "./log-record.ts"
+
+/**
+ * Describe options consumed by log emitters.
+ */
+export interface LogEmitterOptions extends Omit<LogRecord, "type"> {
+}
+/**
+ * Define the base emitter contract for dispatching formatted logs.
+ */
+export abstract class LogEmitter {
+  readonly tags: string[]
+  readonly messages: unknown[]
+
+  readonly formattedMessages: string[]
+
+  constructor(options: LogEmitterOptions) {
+    this.tags = options.tags ?? []
+    this.messages = options.messages ?? []
+
+    this.formattedMessages = []
+    this.formattedMessages.push(this.tags.map(tag => `[${tag}]`).join(""))
+    this.formattedMessages.push(this.messages.map(message => String(message)).join(" "))
+  }
+
+  abstract emit(): void
+}
+
+/**
+ * Emit `log` records via `console.log`.
+ */
+export class ConsoleLogLogEmitter extends LogEmitter {
+  emit(): void {
+    console.log(this.formattedMessages.join(" "))
+  }
+}
+
+/**
+ * Emit `info` records via `console.info`.
+ */
+export class ConsoleInfoLogEmitter extends LogEmitter {
+  emit(): void {
+    console.info(this.formattedMessages.join(" "))
+  }
+}
+
+/**
+ * Emit `warn` records via `console.warn`.
+ */
+export class ConsoleWarnLogEmitter extends LogEmitter {
+  emit(): void {
+    console.warn(this.formattedMessages.join(" "))
+  }
+}
+
+/**
+ * Emit `error` records via `console.error`.
+ */
+export class ConsoleErrorLogEmitter extends LogEmitter {
+  emit(): void {
+    console.error(this.formattedMessages.join(" "))
+  }
+}
+
+/**
+ * Emit `debug` records via `console.debug`.
+ */
+export class ConsoleDebugLogEmitter extends LogEmitter {
+  emit(): void {
+    console.debug(this.formattedMessages.join(" "))
+  }
+}

package/src/log/log-record.ts

@@ -0,0 +1,10 @@
+import type { LogType } from "./log-type.ts"
+
+/**
+ * Describe a normalized log payload before emitter dispatch.
+ */
+export interface LogRecord {
+  type?: LogType | undefined
+  tags?: string[] | undefined
+  messages?: unknown[] | undefined
+}

package/src/log/log-scheduler.ts

@@ -0,0 +1,74 @@
+import type { LogRecord } from "./log-record.ts"
+
+/**
+ * Describe a schedulable log emission task.
+ */
+export interface LogTask {
+  record: LogRecord
+  emit: () => void
+}
+/**
+ * Represent supported scheduling strategies.
+ */
+export type LogSchedulerStrategy = "immediate"
+/**
+ * Describe options used to configure a log scheduler.
+ */
+export interface LogSchedulerOptions {
+  strategy: LogSchedulerStrategy
+}
+/**
+ * Queue and dispatch log tasks based on scheduling strategy.
+ */
+export class LogScheduler {
+  protected strategy: LogSchedulerStrategy
+
+  protected taskQueue: LogTask[][]
+
+  constructor(options: LogSchedulerOptions) {
+    this.strategy = options.strategy
+
+    this.taskQueue = []
+  }
+
+  /**
+   * Check if there are any tasks in the queue.
+   */
+  hasTasks(): boolean {
+    return this.taskQueue.length !== 0
+  }
+
+  /**
+   * Enqueue tasks and run immediately when strategy requires.
+   */
+  enqueue(task: LogTask[]): void {
+    this.taskQueue.push(task)
+    if (this.strategy === "immediate") {
+      this.run()
+    }
+  }
+
+  /**
+   * Flush queued tasks in insertion order.
+   */
+  run(): void {
+    const tasksToRun = [...this.taskQueue].flat()
+    this.taskQueue = []
+    for (const task of tasksToRun) {
+      task.emit()
+    }
+  }
+}
+
+/**
+ * Get the singleton global `LogScheduler` instance.
+ */
+export const getGlobalLogScheduler: () => LogScheduler = (
+  () => {
+    let instance: LogScheduler | undefined = undefined
+    return (): LogScheduler => {
+      instance = instance ?? new LogScheduler({ strategy: "immediate" })
+      return instance
+    }
+  }
+)()

package/src/log/log-type.ts

@@ -0,0 +1,8 @@
+/**
+ * Define supported log level identifiers.
+ */
+export const LOG_TYPES = ["log", "info", "warn", "error", "debug"] as const
+/**
+ * Represent the union type of all supported log levels.
+ */
+export type LogType = typeof LOG_TYPES[number]