tcdona_unilib 1.0.11 → 1.0.14

package/staticMeta/enum.api.ts

@@ -2,37 +2,45 @@
  * 日志和错误处理 API：基于文件路径和事件 ID 生成统一的日志前缀
  */
 
+// ==================== 类型扩展 ====================
+
+declare global {
+  interface ErrorConstructor {
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void
+  }
+}
+
 // ==================== 日志配置 ====================
 
-const cons = console;
+const cons = console
 
 export enum LogLevel {
-    DEBUG = 0,
-    INFO = 1,
-    WARN = 2,
-    ERROR = 3,
-    FATAL = 4,
+  DEBUG = 0,
+  INFO = 1,
+  WARN = 2,
+  ERROR = 3,
+  FATAL = 4,
 }
 
-const logLevelUsed = LogLevel.INFO;
+const logLevelUsed = LogLevel.INFO
 
 const logFnMap: Record<LogLevel, (...args: unknown[]) => void> = {
-    [LogLevel.DEBUG]: cons.debug,
-    [LogLevel.INFO]: cons.log,
-    [LogLevel.WARN]: cons.warn,
-    [LogLevel.ERROR]: cons.error,
-    [LogLevel.FATAL]: cons.error,
-};
+  [LogLevel.DEBUG]: cons.debug,
+  [LogLevel.INFO]: cons.log,
+  [LogLevel.WARN]: cons.warn,
+  [LogLevel.ERROR]: cons.error,
+  [LogLevel.FATAL]: cons.error,
+}
 
 // ==================== 日志链类型 ====================
 
 export interface TcLog {
-    debug: (...args: unknown[]) => void;
-    info: (...args: unknown[]) => void;
-    log: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-    fatal: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void
+  info: (...args: unknown[]) => void
+  log: (...args: unknown[]) => void
+  warn: (...args: unknown[]) => void
+  error: (...args: unknown[]) => void
+  fatal: (...args: unknown[]) => void
 }
 
 // ==================== 新的 fileId 配置类型 ====================
@@ -41,102 +49,123 @@ export interface TcLog {
  * fileId 的配置对象：包含事件 ID、源文件、标签
  */
 export interface FileIdConf {
-    id: string; // 事件标识 key
-    srcFile: string; // 源文件路径
-    tag: string[]; // 标签数组（必须）
+  id: string // 事件标识 key
+  srcFile: string // 源文件路径
+  tag: string[] // 标签数组（必须）
 }
 
 /**
  * fileId：包含配置和日志方法（info, warn, error, debug）
  */
 export interface FileId {
-    readonly conf: FileIdConf;
+  readonly conf: FileIdConf
 
-    // 日志方法
-    info: (...args: unknown[]) => void;
-    warn: (...args: unknown[]) => void;
-    error: (...args: unknown[]) => void;
-    debug: (...args: unknown[]) => void;
+  // 日志方法
+  info: (...args: unknown[]) => void
+  warn: (...args: unknown[]) => void
+  error: (...args: unknown[]) => void
+  debug: (...args: unknown[]) => void
 }
 
 /**
  * 生成格式为 YYMMDD-HHmmss 的时间戳
  */
 const getTimestamp = (): string => {
-    const now = new Date();
-    const yy = String(now.getFullYear()).slice(-2).padStart(2, '0');
-    const mm = String(now.getMonth() + 1).padStart(2, '0');
-    const dd = String(now.getDate()).padStart(2, '0');
-    const hh = String(now.getHours()).padStart(2, '0');
-    const min = String(now.getMinutes()).padStart(2, '0');
-    const ss = String(now.getSeconds()).padStart(2, '0');
-    return `${yy}${mm}${dd}-${hh}${min}${ss}`;
-};
+  const now = new Date()
+  const yy = String(now.getFullYear()).slice(-2).padStart(2, '0')
+  const mm = String(now.getMonth() + 1).padStart(2, '0')
+  const dd = String(now.getDate()).padStart(2, '0')
+  const hh = String(now.getHours()).padStart(2, '0')
+  const min = String(now.getMinutes()).padStart(2, '0')
+  const ss = String(now.getSeconds()).padStart(2, '0')
+  return `${yy}${mm}${dd}-${hh}${min}${ss}`
+}
 
 export class TcErr extends Error {
-    public fildId: FileId;
-    public ctx: Record<string, unknown>;
-    public cause?: Error; // 显式声明 cause 属性
-
-    constructor(
-        ctx: { fildId: FileId; cause?: unknown } & Record<string, unknown>,
-    ) {
-        const { fildId, cause, ...rest } = ctx;
-        super(fildId.conf?.id ?? 'TcErrId');
-        Object.setPrototypeOf(this, new.target.prototype);
-        this.name = 'TcErr';
-        this.fildId = fildId;
-        if (cause) {
-            this.cause = cause as Error;
-        }
-        this.ctx = rest;
-        if (Error.captureStackTrace) {
-            Error.captureStackTrace(this, TcErr);
-        }
-
-        cons.error(getTimestamp(), fildId, cause, rest);
+  public fileId: FileId
+  public ctx: Record<string, unknown>
+  public cause?: Error // 显式声明 cause 属性
+
+  constructor(
+    ctx: { fileId: FileId; cause?: unknown } & Record<string, unknown>,
+  ) {
+    const { fileId, cause, ...rest } = ctx
+    super(fileId.conf?.id ?? 'TcErrId')
+    Object.setPrototypeOf(this, new.target.prototype)
+    this.name = 'TcErr'
+    this.fileId = fileId
+    if (cause) {
+      this.cause = cause as Error
     }
+    this.ctx = rest
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, TcErr)
+    }
+
+    cons.error(
+      getTimestamp(),
+      `[${fileId.conf.srcFile}:${fileId.conf.id}]${fileId.conf.tag.length > 0 ? `[${fileId.conf.tag.join(', ')}]` : ''}`,
+      rest,
+    )
+    cons.log(cause)
+  }
+}
+
+export type TcErrObj = Record<string, unknown> & {
+  fileId: FileId
+  cause?: Error | unknown
+}
+
+export const tcerrobj = (errObj: TcErrObj): TcErrObj => {
+  const { fileId, cause, ...ctx } = errObj
+  // 将 Error 对象传递给 cons.error，Node.js 会自动格式化堆栈信息
+  cons.error(
+    `${getTimestamp()} [${fileId.conf.srcFile}:${fileId.conf.id}]${fileId.conf.tag.length > 0 ? `[${fileId.conf.tag.join(', ')}]` : ''}`,
+    { cause, ...ctx },
+  )
+
+  return errObj
 }
 
 // ==================== 内部日志函数工厂 ====================
 
 const createLogFn = (
-    level: LogLevel,
-    prefix: string,
+  level: LogLevel,
+  prefix: string,
 ): ((...args: unknown[]) => void) => {
-    if (level < logLevelUsed) return () => { };
+  if (level < logLevelUsed) return () => {}
 
-    const logFn = logFnMap[level] ?? (() => { });
-    return logFn.bind(null, `${getTimestamp()} ${prefix}`);
-};
+  const logFn = logFnMap[level] ?? (() => {})
+  return logFn.bind(null, `${getTimestamp()} ${prefix}`)
+}
 
 // ==================== 新的 fileInit API ====================
 
 /**
  * 工厂函数类型：接收事件 ID 和可选标签，返回 FileId
  */
-export type fileIdFactory = (id: string, ...tag: string[]) => FileId;
+export type fileIdFactory = (id: string, ...tag: string[]) => FileId
 
 /**
  * 为模块创建 fileId 工厂函数
  * @param modulePath 模块路径（相对路径字符串）
  */
 export function fileInit(modulePath: string): fileIdFactory {
-    return (id: string, ...tag: string[]): FileId => {
-        const prefix = `[${modulePath}:${id}]${tag.length > 0 ? `[${tag.join(', ')}]` : ''}`;
-
-        const conf: FileIdConf = {
-            id,
-            srcFile: modulePath,
-            tag,
-        };
-
-        return {
-            conf,
-            info: createLogFn(LogLevel.INFO, prefix),
-            warn: createLogFn(LogLevel.WARN, prefix),
-            error: createLogFn(LogLevel.ERROR, prefix),
-            debug: createLogFn(LogLevel.DEBUG, prefix),
-        };
-    };
+  return (id: string, ...tag: string[]): FileId => {
+    const prefix = `[${modulePath}:${id}]${tag.length > 0 ? `[${tag.join(', ')}]` : ''}`
+
+    const conf: FileIdConf = {
+      id,
+      srcFile: modulePath,
+      tag,
+    }
+
+    return {
+      conf,
+      info: createLogFn(LogLevel.INFO, prefix),
+      warn: createLogFn(LogLevel.WARN, prefix),
+      error: createLogFn(LogLevel.ERROR, prefix),
+      debug: createLogFn(LogLevel.DEBUG, prefix),
+    }
+  }
 }

package/staticMeta/err.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod'
+import { Result, ok, err } from 'neverthrow'
+import { jsonParse } from '../eff/throwable'
+import { fileInit, TcErrObj, tcerrobj } from './enum.api'
+
+const fileId = fileInit('src/staticMeta/err.ts')
+
+/**
+ * Zod 错误消息解析后的格式
+ */
+export type ZodErrorMessage = {
+  code: string
+  message: string
+  path: string[]
+  value: string
+}[]
+
+/**
+ * Zod 解析错误类型（JSON 解析成功的情况）
+ */
+export type ZodParseError = TcErrObj & {
+  zodErrors: ZodErrorMessage
+}
+
+/**
+ * Zod 验证并返回 Result<T, ZodParseError>
+ *
+ * 验证成功时返回 ok(data)，失败时返回 err(ZodParseError)，
+ * 并自动将 Zod 的 validated.error 作为 TcErr 的 cause。
+ * 同时给 fileId 添加 tag "zodParseError" 标记。
+ *
+ * 返回的错误类型有两种情况：
+ * - ZodParseErrorJson: 当 error.message 可以解析为 JSON 时，包含 zodErrors 属性
+ * - ZodParseErrorString: 当 error.message 无法解析为 JSON 时，包含 message 属性
+ */
+export const zodParse = <T extends z.ZodType>(
+  schema: T,
+  data: unknown,
+  context: Record<string, unknown>,
+): Result<z.infer<T>, ZodParseError> => {
+  const validated = schema.safeParse(data)
+
+  if (validated.success) {
+    return ok(validated.data)
+  }
+
+  return err(
+    jsonParse(validated.error.message).match(
+      (message: ZodErrorMessage): ZodParseError =>
+        tcerrobj({
+          fileId: fileId('schemaValidationFailed', 'zodParseError-json'),
+          ...message,
+          schema,
+          data,
+          ...context,
+        }) as ZodParseError,
+      () =>
+        fileId('schemaValidationFailed', 'zodParseError-string').error(
+          validated.error.message,
+          context,
+        ) as unknown as ZodParseError,
+    ),
+  )
+}

package/staticMeta/file.yml.ts

@@ -1,18 +1,27 @@
-import { fs, YAML } from 'zx';
-
+import { fs, YAML } from 'zx'
 /**
  * YAML 文件读写：无 data 参数时读取，有 data 参数时写入
  */
 export function yml(path: string, data?: unknown): unknown {
-    if (typeof data !== 'undefined') {
-        fs.writeFileSync(
-            path,
-            // @ts-expect-error YAML.stringify 类型定义有误
-            YAML.stringify(data, { singleQuote: true, sortKeys: true }),
-            'utf-8',
-        );
-    } else {
-        const ymlContent = fs.readFileSync(path, 'utf-8');
-        return YAML.parse(ymlContent);
-    }
+  if (typeof data !== 'undefined') {
+    fs.writeFileSync(
+      path,
+      // @ts-expect-error YAML.stringify 类型定义有误
+      YAML.stringify(data, { singleQuote: true }),
+      'utf-8',
+    )
+  } else {
+    const ymlContent = fs.readFileSync(path, 'utf-8')
+    return YAML.parse(ymlContent)
+  }
+}
+
+import { default as jsYAML } from 'js-yaml'
+export const yml2 = (path: string, data?: unknown): unknown => {
+  if (typeof data !== 'undefined') {
+    fs.writeFileSync(path, jsYAML.dump(data, { sortKeys: true }), 'utf-8')
+  } else {
+    const ymlContent = fs.readFileSync(path, 'utf-8')
+    return jsYAML.load(ymlContent)
+  }
 }

package/staticMeta/md.html2md.ts

@@ -0,0 +1,38 @@
+import { type MdMapping } from './md.md2html.js'
+
+const ELEMENT_NODE = 1
+const TEXT_NODE = 3
+
+export const reconstructMarkdown = (
+  container: HTMLElement,
+  idMap: Record<string, MdMapping>,
+): string => {
+  const parts: string[] = []
+
+  const walk = (node: Node): void => {
+    if (node.nodeType === ELEMENT_NODE) {
+      const el = node as HTMLElement
+      const mdId = el.getAttribute('data-md-id')
+
+      if (mdId && idMap[mdId]) {
+        parts.push(idMap[mdId].originalMd)
+        return
+      }
+    }
+
+    if (node.nodeType === TEXT_NODE) {
+      const text = node.textContent || ''
+      if (text.trim()) {
+        parts.push(text)
+      }
+      return
+    }
+
+    for (const child of Array.from(node.childNodes)) {
+      walk(child)
+    }
+  }
+
+  walk(container)
+  return parts.join('')
+}

package/staticMeta/md.md2html.ts

@@ -0,0 +1,203 @@
+import { Lexer, type Token, type Tokens } from 'marked'
+
+export interface MdMapping {
+  originalMd: string
+}
+
+export interface ParseResult {
+  html: string
+  idMap: Record<string, MdMapping>
+}
+
+// const resetIdCounter = (): void => {
+//   idCounter = 0
+// }
+
+const escapeHtml = (text: string): string => {
+  return text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+export const parseMarkdownWithIds = (markdown: string): ParseResult => {
+  let idCounter = 0
+  const generateId = (prefix: string): string => `${prefix}-${idCounter++}`
+  // resetIdCounter()
+  const idMap: Record<string, MdMapping> = {}
+  const tokens = Lexer.lex(markdown)
+
+  const processToken = (token: Token): string => {
+    switch (token.type) {
+      case 'heading': {
+        const t = token as Tokens.Heading
+        const id = generateId('h')
+        idMap[id] = { originalMd: t.raw }
+        const content = t.tokens ? t.tokens.map(processToken).join('') : t.text
+        return `<h${t.depth} data-md-id="${id}">${content}</h${t.depth}>\n`
+      }
+
+      case 'paragraph': {
+        const t = token as Tokens.Paragraph
+        const id = generateId('p')
+        idMap[id] = { originalMd: t.raw }
+        const content = t.tokens ? t.tokens.map(processToken).join('') : t.text
+        return `<p data-md-id="${id}">${content}</p>\n`
+      }
+
+      case 'code': {
+        const t = token as Tokens.Code
+        const id = generateId('pre')
+        idMap[id] = { originalMd: t.raw }
+        const langClass = t.lang
+          ? ` class="language-${escapeHtml(t.lang)}"`
+          : ''
+        return `<pre data-md-id="${id}"><code${langClass}>${escapeHtml(t.text)}</code></pre>\n`
+      }
+
+      case 'codespan': {
+        const t = token as Tokens.Codespan
+        const id = generateId('code')
+        idMap[id] = { originalMd: t.raw }
+        return `<code data-md-id="${id}">${escapeHtml(t.text)}</code>`
+      }
+
+      case 'blockquote': {
+        const t = token as Tokens.Blockquote
+        const id = generateId('blockquote')
+        idMap[id] = { originalMd: t.raw }
+        const content = t.tokens ? t.tokens.map(processToken).join('') : t.text
+        return `<blockquote data-md-id="${id}">\n${content}</blockquote>\n`
+      }
+
+      case 'list': {
+        const t = token as Tokens.List
+        const id = generateId('list')
+        idMap[id] = { originalMd: t.raw }
+        const tag = t.ordered ? 'ol' : 'ul'
+        const items = t.items.map((item) => processToken(item)).join('')
+        return `<${tag} data-md-id="${id}">\n${items}</${tag}>\n`
+      }
+
+      case 'list_item': {
+        const t = token as Tokens.ListItem
+        const id = generateId('li')
+        idMap[id] = { originalMd: t.raw }
+        const content = t.tokens ? t.tokens.map(processToken).join('') : t.text
+        return `<li data-md-id="${id}">${content}</li>\n`
+      }
+
+      case 'strong': {
+        const t = token as Tokens.Strong
+        const id = generateId('strong')
+        idMap[id] = { originalMd: t.raw }
+        const content = t.tokens ? t.tokens.map(processToken).join('') : t.text
+        return `<strong data-md-id="${id}">${content}</strong>`
+      }
+
+      case 'em': {
+        const t = token as Tokens.Em
+        const id = generateId('em')
+        idMap[id] = { originalMd: t.raw }
+        const content = t.tokens ? t.tokens.map(processToken).join('') : t.text
+        return `<em data-md-id="${id}">${content}</em>`
+      }
+
+      case 'link': {
+        const t = token as Tokens.Link
+        const id = generateId('a')
+        idMap[id] = { originalMd: t.raw }
+        const content = t.tokens ? t.tokens.map(processToken).join('') : t.text
+        const title = t.title ? ` title="${escapeHtml(t.title)}"` : ''
+        return `<a data-md-id="${id}" href="${escapeHtml(t.href)}"${title}>${content}</a>`
+      }
+
+      case 'image': {
+        const t = token as Tokens.Image
+        const id = generateId('img')
+        idMap[id] = { originalMd: t.raw }
+        const title = t.title ? ` title="${escapeHtml(t.title)}"` : ''
+        return `<img data-md-id="${id}" src="${escapeHtml(t.href)}" alt="${escapeHtml(t.text)}"${title}>`
+      }
+
+      case 'text': {
+        const t = token as Tokens.Text
+        if ('tokens' in t && t.tokens) {
+          return t.tokens.map(processToken).join('')
+        }
+        return t.text
+      }
+
+      case 'space':
+        return '\n'
+
+      case 'hr': {
+        const t = token as Tokens.Hr
+        const id = generateId('hr')
+        idMap[id] = { originalMd: t.raw }
+        return `<hr data-md-id="${id}">\n`
+      }
+
+      case 'br':
+        return '<br>'
+
+      case 'del': {
+        const t = token as Tokens.Del
+        const id = generateId('del')
+        idMap[id] = { originalMd: t.raw }
+        const content = t.tokens ? t.tokens.map(processToken).join('') : t.text
+        return `<del data-md-id="${id}">${content}</del>`
+      }
+
+      case 'html': {
+        const t = token as Tokens.HTML
+        return t.raw
+      }
+
+      case 'table': {
+        const t = token as Tokens.Table
+        const id = generateId('table')
+        idMap[id] = { originalMd: t.raw }
+
+        const headerCells = t.header
+          .map((cell, i) => {
+            const align = t.align[i] ? ` style="text-align:${t.align[i]}"` : ''
+            const content = cell.tokens
+              ? cell.tokens.map(processToken).join('')
+              : cell.text
+            return `<th${align}>${content}</th>`
+          })
+          .join('')
+
+        const bodyRows = t.rows
+          .map((row) => {
+            const cells = row
+              .map((cell, i) => {
+                const align = t.align[i]
+                  ? ` style="text-align:${t.align[i]}"`
+                  : ''
+                const content = cell.tokens
+                  ? cell.tokens.map(processToken).join('')
+                  : cell.text
+                return `<td${align}>${content}</td>`
+              })
+              .join('')
+            return `<tr>${cells}</tr>`
+          })
+          .join('\n')
+
+        return `<table data-md-id="${id}">
+<thead><tr>${headerCells}</tr></thead>
+<tbody>${bodyRows}</tbody>
+</table>\n`
+      }
+
+      default:
+        return ''
+    }
+  }
+
+  const html = tokens.map(processToken).join('')
+  return { html, idMap }
+}

package/staticMeta/path.init.ts

@@ -1,5 +1,5 @@
-import { dirname, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { dirname, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
 /**
  * 初始化模块的路径元信息（__filename, __dirname, __relative, resolve）
@@ -7,15 +7,15 @@ import { fileURLToPath } from 'node:url';
  * @param root 根目录路径
  */
 export function pathMeta(metaUrl: string, root: string) {
-    const __filename = fileURLToPath(metaUrl);
-    const __dirname = dirname(__filename);
-    const __rootname = resolve(root);
+  const __filename = fileURLToPath(metaUrl)
+  const __dirname = dirname(__filename)
+  const __rootname = resolve(__dirname, root)
 
-    return {
-        __rootname,
-        __dirname,
-        __filename,
-        resolve: resolve.bind(null, __dirname),
-        __relative: relative(__rootname, __filename),
-    } as const;
+  return {
+    __rootname,
+    __dirname,
+    __filename,
+    resolve: resolve.bind(null, __dirname),
+    __relative: relative(__rootname, __filename),
+  } as const
 }

package/staticMeta/string.nanoid.ts

@@ -1,14 +1,14 @@
-import { customAlphabet } from 'nanoid';
+import { customAlphabet } from 'nanoid'
 
 /**
  * 生成 18 字符的唯一 ID（使用自定义字符集，排除易混淆字符）
  */
 export const tcNanoid = customAlphabet(
-    'useandom26T198340PX75pxJACKVERYMINDBUSHWOLFGQZbfghjklqvwyzrict',
-    18,
-);
+  'useandom26T198340PX75pxJACKVERYMINDBUSHWOLFGQZbfghjklqvwyzrict',
+  18,
+)
 
 export const lowerNanoid = customAlphabet(
-    'useandom2619834075pxbfghjklqvwyzrict',
-    18,
-);
+  'useandom2619834075pxbfghjklqvwyzrict',
+  18,
+)