@planet-matrix/mobius-model 0.5.0 → 0.9.0

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]

package/src/log/logger.ts

@@ -0,0 +1,554 @@
+import { generateUuidV4FromUrl } from "#Source/identifier/index.ts"
+import { getGlobalLogScheduler } from "./log-scheduler.ts"
+
+import type { LogRecord } from "./log-record.ts"
+import type { LogTask } from "./log-scheduler.ts"
+import type { LogType } from "./log-type.ts"
+import {
+  ConsoleDebugLogEmitter,
+  ConsoleErrorLogEmitter,
+  ConsoleInfoLogEmitter,
+  ConsoleLogLogEmitter,
+  ConsoleWarnLogEmitter,
+} from "./log-emitter.ts"
+import type { LogEmitter, LogEmitterOptions } from "./log-emitter.ts"
+
+const globalLogScheduler = getGlobalLogScheduler()
+
+/**
+ * Describe an object that exposes a `Logger` instance.
+ */
+export interface LoggerFriendly {
+  logger: Logger
+}
+/**
+ * Describe options that may provide an existing `Logger`.
+ */
+export interface LoggerFriendlyOptions {
+  logger?: Logger | undefined
+}
+
+/**
+ * Describe an emitter registration for a specific log type.
+ */
+export interface LogEmitterItem {
+  logType: LogType
+  // oxlint-disable-next-line no-explicit-any
+  LogEmitter: new (...args: any[]) => LogEmitter
+  injectOptions?: ((options: LogEmitterOptions) => LogEmitterOptions) | undefined
+}
+/**
+ * Define the default console-based emitters.
+ */
+const DEFAULT_CONSOLE_LOG_EMITTER_ITEMS: LogEmitterItem[] = [
+  {
+    logType: "log",
+    LogEmitter: ConsoleLogLogEmitter,
+  },
+  {
+    logType: "info",
+    LogEmitter: ConsoleInfoLogEmitter,
+  },
+  {
+    logType: "warn",
+    LogEmitter: ConsoleWarnLogEmitter,
+  },
+  {
+    logType: "error",
+    LogEmitter: ConsoleErrorLogEmitter,
+  },
+  {
+    logType: "debug",
+    LogEmitter: ConsoleDebugLogEmitter,
+  },
+]
+
+/**
+ * Describe runtime logger configuration values.
+ */
+export interface LoggerConfigs {
+  enabled: boolean
+  autoSend: boolean
+  filter: ((logRecord: LogRecord) => boolean)
+  emitters: LogEmitterItem[]
+}
+/**
+ * Describe options used to construct a `Logger`.
+ */
+export interface LoggerOptions {
+  name?: string | undefined
+  parent?: Logger | undefined
+  configs?: Partial<LoggerConfigs> | undefined
+}
+/**
+ * 表示支持层级继承、标签管理与延迟发送的日志记录器。
+ *
+ * 规范：
+ * - 初始配置的优先级为 parentConfigs -> configs -> 默认值。
+ * - 当 parent 为 undefined 时，parentConfigs 也应该是 undefined。
+ * - 更新 parent 时，parentConfigs 也应该同步更新。
+ * - 作为 parent 修改自己的 configs 时，不会影响 child 的 configs。
+ * - 作为 child 可以独立修改自己的 configs，也可以将 parentConfigs 应用到自己的 configs。
+ */
+export class Logger implements Disposable {
+  /**
+   * 从选项中解析 logger；如果未提供，则基于全局 logger 派生一个新 logger。
+   *
+   * @example
+   * ```
+   * // Expect: example1 === customLogger
+   * const customLogger = new Logger({ name: "Custom" })
+   * const example1 = Logger.fromOptions({ logger: customLogger })
+   *
+   * // Expect: example2 !== globalLogger
+   * // Expect: example2.hasParent() === true
+   * const globalLogger = getGlobalLogger()
+   * const example2 = Logger.fromOptions({})
+   *
+   * class CustomClass implements LoggerFriendly {
+   *   logger: Logger
+   *
+   *   constructor(options: LoggerFriendlyOptions) {
+   *     this.logger = Logger.fromOptions(options)
+   *   }
+   * }
+   *
+   * // Expect: example3.logger instanceof Logger
+   * const example3 = new CustomClass({ logger: customLogger })
+   * ```
+   */
+  static fromOptions(options: LoggerFriendlyOptions): Logger {
+    if (options.logger !== undefined) {
+      return options.logger
+    }
+
+    const parent = getGlobalLogger()
+    const logger = Logger.derive(parent)
+    return logger
+  }
+
+  /**
+   * Create a child logger from a parent logger.
+   */
+  static derive(parentLogger: Logger): Logger {
+    const logger = new Logger({ parent: parentLogger })
+    return logger
+  }
+
+  protected defaultName: string
+  protected name?: string | undefined
+  protected parent?: Logger | undefined
+  protected childs: Logger[]
+  protected parentConfigs?: LoggerConfigs | undefined
+  protected configs: LoggerConfigs
+
+  protected instanceTags: string[]
+  protected sessionTags: string[]
+  protected onceTags: string[]
+
+  private logTasks: LogTask[]
+  private cachedLogMethodMap: Map<string, (...messages: unknown[]) => this>
+
+  constructor(options: LoggerOptions) {
+    this.defaultName = "Unnamed"
+    this.name = options.name
+    this.parent = options.parent
+    this.childs = []
+    const parentConfigs = options.parent?.getConfigs()
+    const configs = options.configs
+    this.parentConfigs = parentConfigs
+    this.configs = {
+      enabled: parentConfigs?.enabled ?? configs?.enabled ?? true,
+      autoSend: parentConfigs?.autoSend ?? configs?.autoSend ?? true,
+      filter: parentConfigs?.filter ?? configs?.filter ?? ((): boolean => true),
+      emitters: parentConfigs?.emitters ?? configs?.emitters ?? DEFAULT_CONSOLE_LOG_EMITTER_ITEMS
+    }
+
+    this.instanceTags = []
+    this.sessionTags = []
+    this.onceTags = []
+
+    this.logTasks = []
+    this.cachedLogMethodMap = new Map()
+  }
+
+  /**
+   * Set the default name if the current name is empty,
+   * and return the logger for chaining.
+   */
+  setDefaultName(name: string): this {
+    this.defaultName = name
+    return this
+  }
+
+  /**
+   * Get the logger display name.
+   */
+  getName(): string {
+    return this.name ?? this.defaultName
+  }
+
+  /**
+   * Set the logger display name.
+   */
+  setName(name: string | undefined): this {
+    this.name = name
+    return this
+  }
+
+  /**
+   * Check whether the logger currently has a parent.
+   */
+  hasParent(): boolean {
+    return this.parent !== undefined
+  }
+
+  /**
+   * Set or clear the parent logger.
+   */
+  setParent(parentLogger?: Logger | undefined): this {
+    this.parent = parentLogger
+    this.parentConfigs = parentLogger?.getConfigs()
+    return this
+  }
+
+  /**
+   * Get merged effective configs from parent and local overrides.
+   */
+  getConfigs(): LoggerConfigs {
+    return { ...this.parentConfigs, ...this.configs }
+  }
+
+  /**
+   * Update local configs and refresh inherited configs on child loggers.
+   */
+  setConfigs(configs: Partial<LoggerConfigs>): this {
+    this.configs = { ...this.getConfigs(), ...configs }
+    for (const child of this.childs) {
+      child.setParent(this)
+    }
+    return this
+  }
+
+  /**
+   * Apply current parent configs onto local configs.
+   */
+  useParentConfigs(): this {
+    if (this.parentConfigs !== undefined) {
+      this.setConfigs(this.parentConfigs)
+    }
+    return this
+  }
+
+  /**
+   * Get all configured emitter registrations.
+   */
+  getAllLogEmitters(): LogEmitterItem[] {
+    const emitters = this.getConfigs().emitters
+    return emitters
+  }
+
+  /**
+   * Get emitter registrations for a specific log type.
+   */
+  getLogEmitters(logType: LogType): LogEmitterItem[] {
+    const emitters = this.getConfigs().emitters
+    const filteredEmitters = emitters.filter(item => item.logType === logType)
+    return filteredEmitters
+  }
+
+  /**
+   * 支持为同一类型的 Log 添加多个 LogEmitter。
+   */
+  addLogEmitters(logEmitters: LogEmitterItem[]): this {
+    const newEmitters = [...this.getConfigs().emitters]
+    for (const item of logEmitters) {
+      if (!newEmitters.some((e) => e.logType === item.logType && e.LogEmitter === item.LogEmitter)) {
+        newEmitters.push(item)
+      }
+    }
+    this.setConfigs({
+      emitters: newEmitters
+    })
+    return this
+  }
+
+  /**
+   * Remove matched emitter registrations.
+   */
+  removeLogEmitters(logEmitters: LogEmitterItem[]): this {
+    const emitters = this.getConfigs().emitters
+    const remainingEmitters = emitters.filter((item) => {
+      return !logEmitters.some((e) => e.logType === item.logType && e.LogEmitter === item.LogEmitter)
+    })
+    this.setConfigs({
+      emitters: remainingEmitters
+    })
+    return this
+  }
+
+  /**
+   * Invoke all emitters that match the record log type.
+   */
+  invokeLogEmitter(record: LogRecord): void {
+    const { type } = record
+    if (type === undefined) {
+      return
+    }
+    const logEmitterList = this.getLogEmitters(type)
+    if (logEmitterList.length === 0) {
+      return
+    }
+    logEmitterList.forEach((item) => {
+      const injectOptions = item.injectOptions ?? (<T>(v: T): T => v)
+      const LogEmitter = item.LogEmitter
+      const logEmitter = new LogEmitter(injectOptions(record))
+      logEmitter.emit()
+    })
+  }
+
+  /**
+   * Get full hierarchical name tags from root to current logger.
+   */
+  getNameTags(): string[] {
+    const names = [...this.parent?.getNameTags() ?? [], this.getName()]
+    return names
+  }
+
+  /**
+   * Add persistent instance tags.
+   */
+  addInstanceTags(tags: string[]): this {
+    this.instanceTags.push(...tags)
+    return this
+  }
+
+  /**
+   * Remove matched instance tags.
+   */
+  removeInstanceTags(tags: string[]): this {
+    this.instanceTags = this.instanceTags.filter(tag => !tags.includes(tag))
+    return this
+  }
+
+  /**
+   * Get current instance tags.
+   */
+  getInstanceTags(): string[] {
+    return this.instanceTags
+  }
+
+  /**
+   * Clear all instance tags.
+   */
+  clearInstanceTags(): this {
+    this.instanceTags = []
+    return this
+  }
+
+  /**
+   * Add session tags used until `tagEnd` is called.
+   */
+  addSessionTags(tags: string[]): this {
+    this.sessionTags.push(...tags)
+    return this
+  }
+
+  /**
+   * Remove matched session tags.
+   */
+  removeSessionTags(tags: string[]): this {
+    this.sessionTags = this.sessionTags.filter(tag => !tags.includes(tag))
+    return this
+  }
+
+  /**
+   * Get current session tags.
+   */
+  getSessionTags(): string[] {
+    return this.sessionTags
+  }
+
+  /**
+   * Clear all session tags.
+   */
+  clearSessionTags(): this {
+    this.sessionTags = []
+    return this
+  }
+
+  /**
+   * Start and automatically end a session tag scope on dispose.
+   */
+  autoTag(tags: string[]): Disposable {
+    this.tagStart(tags)
+    return {
+      [Symbol.dispose]: (): void => {
+        this.tagEnd()
+      },
+    }
+  }
+
+  /**
+   * Start a session tag scope.
+   */
+  tagStart(tags: string[]): this {
+    this.addSessionTags(tags)
+    return this
+  }
+
+  /**
+   * End the current session tag scope.
+   */
+  tagEnd(): this {
+    this.clearSessionTags()
+    return this
+  }
+
+  /**
+   * Add one-shot tags consumed by the next log call.
+   */
+  addOnceTags(tags: string[]): this {
+    this.onceTags.push(...tags)
+    return this
+  }
+
+  /**
+   * Get current one-shot tags.
+   */
+  getOnceTags(): string[] {
+    return this.onceTags
+  }
+
+  /**
+   * Clear all one-shot tags.
+   */
+  clearOnceTags(): this {
+    this.onceTags = []
+    return this
+  }
+
+  /**
+   * Build and cache a log method bound to type and prefix.
+   */
+  private makeLogMethod(logType: LogType, prefix: string): ((...args: unknown[]) => this) {
+    const cachedLogMethodKey = `${logType}-${prefix}`
+    const cachedLogMethod = this.cachedLogMethodMap.get(cachedLogMethodKey)
+    if (cachedLogMethod !== undefined) {
+      return cachedLogMethod
+    }
+
+    const newMethod = (...messages: unknown[]): this => {
+      const configs = this.getConfigs()
+      if (configs.enabled === false) {
+        return this
+      }
+
+      const tags = [
+        prefix,
+        ...this.getNameTags(),
+        ...this.getInstanceTags(),
+        ...this.getSessionTags(),
+        ...this.getOnceTags()
+      ]
+      const logRecord: LogRecord = {
+        type: logType,
+        tags: tags,
+        messages,
+      }
+
+      // oxlint-disable-next-line no-array-callback-reference
+      if (configs.filter(logRecord) === false) {
+        return this
+      }
+
+      this.logTasks.push({
+        record: logRecord,
+        emit: () => {
+          this.invokeLogEmitter(logRecord)
+        }
+      })
+      if (configs.autoSend === true) {
+        this.send()
+      }
+      this.clearOnceTags()
+      return this
+    }
+    this.cachedLogMethodMap.set(cachedLogMethodKey, newMethod)
+
+    return newMethod
+  }
+
+  /**
+   * Queue a `log` level record.
+   */
+  log(...messages: unknown[]): this {
+    return this.makeLogMethod("log", "🟢")(...messages)
+  }
+
+  /**
+   * Queue an `info` level record.
+   */
+  info(...messages: unknown[]): this {
+    return this.makeLogMethod("info", "🔵")(...messages)
+  }
+
+  /**
+   * Queue a `warn` level record.
+   */
+  warn(...messages: unknown[]): this {
+    return this.makeLogMethod("warn", "🟡")(...messages)
+  }
+
+  /**
+   * Queue an `error` level record.
+   */
+  error(...messages: unknown[]): this {
+    return this.makeLogMethod("error", "🔴")(...messages)
+  }
+
+  /**
+   * Queue a `debug` level record.
+   */
+  debug(...messages: unknown[]): this {
+    return this.makeLogMethod("debug", "🟤")(...messages)
+  }
+
+  /**
+   * Create a child logger configured for manual batched sending.
+   */
+  batch(id?: string | undefined): Logger {
+    const logger = Logger.derive(this)
+    logger.setConfigs({ autoSend: false })
+    logger.addInstanceTags([id ?? generateUuidV4FromUrl()])
+    return logger
+  }
+
+  /**
+   * Flush queued records to the global scheduler.
+   */
+  send(): void {
+    globalLogScheduler.enqueue(this.logTasks)
+    this.logTasks = []
+  }
+
+  /**
+   * Flush queued records when used with `using` disposal.
+   */
+  [Symbol.dispose](): void {
+    this.send()
+  }
+}
+
+/**
+ * Get the singleton global `Logger` instance.
+ */
+export const getGlobalLogger: () => Logger = (
+  () => {
+    let instance: Logger | undefined = undefined
+    return (): Logger => {
+      instance = instance ?? new Logger({ name: "GlobalLogger" })
+      return instance
+    }
+  }
+)()

package/src/openai/README.md

@@ -0,0 +1 @@
+# Openai

package/src/openai/index.ts

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