tcdona_unilib 1.0.12 → 1.0.15

package/eff/aff.ts

@@ -0,0 +1,161 @@
+import { Result } from 'neverthrow'
+import { err, ok, ResultAsync } from 'neverthrow'
+import {
+  Actrl,
+  ABORT_REASON,
+  shortId,
+  type AffFn,
+  type NonEmptyArray,
+  type ExtractOk,
+  type ExtractErr,
+} from './aff.util'
+
+export class Aff {
+  /**
+   * 创建子任务（继承父 signal，支持取消传播）
+   */
+  static make<T, E>(
+    actrlSpanId: string,
+    executor: AffFn<T, E>,
+    parentActrl: Actrl,
+  ): ResultAsync<T, E> {
+    const actrl = new Actrl(actrlSpanId)
+    const unlink = parentActrl.link(actrl)
+
+    const executorResult = executor(actrl)
+    // 统一处理 PromiseLike 和 ResultAsync，转换为 Promise<Result<T, E>>
+    // ResultAsync 实现了 PromiseLike，Promise.resolve 可以处理它
+    const promise: Promise<Result<T, E>> = Promise.resolve(
+      executorResult as PromiseLike<Result<T, E>>,
+    )
+      .catch((e) => err(e as E))
+      .then((result) => {
+        actrl.resultStatus = result.isOk() ? 'ok' : 'err'
+        unlink()
+        actrl.cancel(ABORT_REASON.COMPLETED)
+        return result
+      })
+
+    return new ResultAsync(promise)
+  }
+
+  /**
+   * 创建根级任务（无父 signal）
+   */
+  static root<T, E>(executor: AffFn<T, E>): ResultAsync<T, E> {
+    return Aff.make('root', executor, new Actrl('$', true))
+  }
+
+  static all<T extends NonEmptyArray<AffFn<unknown, unknown>>>(
+    executors: T,
+    parentActrl: Actrl,
+  ): ResultAsync<
+    { -readonly [P in keyof T]: ExtractOk<T[P]> },
+    ExtractErr<T[number]>
+  > {
+    const actrl = new Actrl('all#' + shortId())
+    const unlink = parentActrl.link(actrl)
+
+    // Result -> Promise 语义转换：err 变成 reject，这样 Promise.all 遇到 err 会立即返回
+    const toPromise = (ra: ResultAsync<unknown, unknown>) =>
+      ra.then((r) => (r.isOk() ? r.value : Promise.reject(r.error)))
+
+    const promise = Promise.all(
+      executors.map((fn, i) => toPromise(Aff.make(`all-${i}`, fn, actrl))),
+    )
+      .then((values) => {
+        unlink()
+        actrl.cancel(ABORT_REASON.COMPLETED)
+        return ok(values) as Result<
+          { -readonly [P in keyof T]: ExtractOk<T[P]> },
+          ExtractErr<T[number]>
+        >
+      })
+      .catch((e) => {
+        unlink()
+        actrl.cancel(ABORT_REASON.SETTLED)
+        return err(e) as Result<
+          { -readonly [P in keyof T]: ExtractOk<T[P]> },
+          ExtractErr<T[number]>
+        >
+      })
+
+    return new ResultAsync(promise)
+  }
+
+  static any<T extends NonEmptyArray<AffFn<unknown, unknown>>>(
+    executors: T,
+    parentActrl: Actrl,
+  ): ResultAsync<ExtractOk<T[number]>, ExtractErr<T[number]>[]> {
+    const actrl = new Actrl('any#' + shortId())
+    const unlink = parentActrl.link(actrl)
+
+    // Result -> Promise 语义转换
+    const toPromise = (ra: ResultAsync<unknown, unknown>) =>
+      ra.then((r) => (r.isOk() ? r.value : Promise.reject(r.error)))
+
+    const promise = Promise.any(
+      executors.map((fn, i) => toPromise(Aff.make(`any-${i}`, fn, actrl))),
+    )
+      .then((value) => {
+        unlink()
+        actrl.cancel(ABORT_REASON.SETTLED)
+        return ok(value) as Result<
+          ExtractOk<T[number]>,
+          ExtractErr<T[number]>[]
+        >
+      })
+      .catch((e: AggregateError) => {
+        unlink()
+        actrl.cancel(ABORT_REASON.COMPLETED)
+        return err(e.errors) as Result<
+          ExtractOk<T[number]>,
+          ExtractErr<T[number]>[]
+        >
+      })
+
+    return new ResultAsync(promise)
+  }
+
+  static race<T extends NonEmptyArray<AffFn<unknown, unknown>>>(
+    executors: T,
+    parentActrl: Actrl,
+  ): ResultAsync<ExtractOk<T[number]>, ExtractErr<T[number]>> {
+    const actrl = new Actrl('race#' + shortId())
+    const unlink = parentActrl.link(actrl)
+
+    const promise = Promise.race(
+      executors.map((fn, i) => Aff.make(`race-${i}`, fn, actrl)),
+    ).then((firstResult) => {
+      unlink()
+      actrl.cancel(ABORT_REASON.SETTLED)
+      return firstResult as Result<ExtractOk<T[number]>, ExtractErr<T[number]>>
+    })
+
+    return new ResultAsync(promise)
+  }
+
+  static allSettled<T extends NonEmptyArray<AffFn<unknown, unknown>>>(
+    executors: T,
+    parentActrl: Actrl,
+  ): ResultAsync<
+    { -readonly [P in keyof T]: Result<ExtractOk<T[P]>, ExtractErr<T[P]>> },
+    never
+  > {
+    const actrl = new Actrl('settled#' + shortId())
+    const unlink = parentActrl.link(actrl)
+
+    const promise = Promise.all(
+      executors.map((fn, i) => Aff.make(`allSettled-${i}`, fn, actrl)),
+    ).then((results) => {
+      unlink()
+      actrl.cancel(ABORT_REASON.COMPLETED)
+      return ok(results) as Result<
+        { -readonly [P in keyof T]: Result<ExtractOk<T[P]>, ExtractErr<T[P]>> },
+        never
+      >
+    })
+
+    return new ResultAsync(promise)
+  }
+}

package/eff/aff.util.ts

@@ -0,0 +1,218 @@
+import { Result } from 'neverthrow'
+import { err, ok, ResultAsync } from 'neverthrow'
+import { tcNanoid } from '../staticMeta/string.nanoid'
+
+export type ActrlSpan = {
+  id: string
+  parent: string
+  status: 'init'
+  startTime: number
+  duration: number
+}
+
+export class Actrl {
+  readonly ac: AbortController
+  public traceid: string = ''
+  public span: ActrlSpan = {
+    id: '',
+    parent: '',
+    status: 'init',
+    startTime: 0,
+    duration: 0,
+  }
+  private isRoot = false
+  public depth = 0 // 基于父子关系的真实深度
+  public resultStatus: 'ok' | 'err' | null = null // 任务返回状态
+  public logs: string[] = [] // 日志数组，用于收集日志信息
+  private rootLogs: string[] | null = null // 指向根 Actrl 的 logs，用于统一收集所有日志
+
+  constructor(spanid: string, isRoot = false) {
+    this.ac = new AbortController()
+    this.span.id = spanid
+    this.isRoot = isRoot
+    this.depth = isRoot ? 0 : 0
+    if (isRoot) {
+      this.rootLogs = this.logs // 根 Actrl 的 rootLogs 指向自己的 logs
+    }
+  }
+
+  get aborted() {
+    return this.ac.signal.aborted
+  }
+  get reason(): unknown {
+    return this.ac.signal.reason
+  }
+
+  cancel(reason?: unknown) {
+    this.ac.abort(reason)
+  }
+  link(childActrl: Actrl) {
+    // 让子 Actrl 共享根 Actrl 的 logs
+    childActrl.rootLogs = this.rootLogs || this.logs
+    // 获取目标日志数组（根 Actrl 的 logs）
+    const getTargetLogs = () => this.rootLogs || this.logs
+
+    if (this.isRoot) {
+      this.traceid = tcNanoid()
+      childActrl.traceid = this.traceid
+      childActrl.depth = 1
+
+      const indent = formatIndent(childActrl.depth)
+      const displayId = childActrl.span.id
+      getTargetLogs().push(formatLogStart(indent, displayId))
+
+      if (this.ac.signal.aborted) {
+        childActrl.cancel(this.ac.signal.reason)
+        getTargetLogs().push(
+          formatLogCancel(indent, childActrl.span.id, 'parent aborted'),
+        )
+        return noop
+      }
+      const handler = () => {
+        childActrl.cancel(this.ac.signal.reason)
+        // 记录取消日志（当父任务因为 SETTLED 被取消时）
+        if (this.ac.signal.reason === ABORT_REASON.SETTLED) {
+          getTargetLogs().push(formatLogCancel(indent, childActrl.span.id))
+        }
+      }
+      this.ac.signal.addEventListener('abort', handler, { once: true })
+      return () => {
+        // 判断是否被外部取消（reason 是 'settled' 表示被其他任务抢先完成）
+        const isCancelled =
+          childActrl.aborted && childActrl.reason === ABORT_REASON.SETTLED
+        let status = ''
+        if (isCancelled) {
+          status = ' [cancelled]'
+        } else if (childActrl.resultStatus) {
+          status = ' [' + childActrl.resultStatus + ']'
+        }
+        getTargetLogs().push(formatLogEnd(indent, childActrl.span.id, status))
+        this.ac.signal.removeEventListener('abort', handler)
+      }
+    }
+    childActrl.traceid = this.traceid
+    childActrl.span.parent = this.span.id
+    childActrl.depth = this.depth + 1
+
+    const indent = formatIndent(childActrl.depth)
+    const displayId = formatDisplayId(this.span.id, childActrl.span.id)
+    childActrl.span.id = displayId
+    getTargetLogs().push(formatLogStart(indent, displayId))
+
+    if (this.ac.signal.aborted) {
+      childActrl.cancel(this.ac.signal.reason)
+      getTargetLogs().push(
+        formatLogCancel(indent, childActrl.span.id, 'parent aborted'),
+      )
+      return noop
+    }
+    const handler = () => {
+      childActrl.cancel(this.ac.signal.reason)
+      // 记录取消日志（当父任务因为 SETTLED 被取消时）
+      if (this.ac.signal.reason === ABORT_REASON.SETTLED) {
+        getTargetLogs().push(formatLogCancel(indent, childActrl.span.id))
+      }
+    }
+    this.ac.signal.addEventListener('abort', handler, { once: true })
+    return () => {
+      // 判断是否被外部取消（reason 是 'settled' 表示被其他任务抢先完成）
+      const isCancelled =
+        childActrl.aborted && childActrl.reason === ABORT_REASON.SETTLED
+      let status = ''
+      if (isCancelled) {
+        status = ' [cancelled]'
+      } else if (childActrl.resultStatus) {
+        status = ' [' + childActrl.resultStatus + ']'
+      }
+      getTargetLogs().push(formatLogEnd(indent, childActrl.span.id, status))
+      this.ac.signal.removeEventListener('abort', handler)
+    }
+  }
+  on(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | AddEventListenerOptions,
+  ) {
+    this.ac.signal.addEventListener(type, listener, options)
+  }
+  off(
+    type: string,
+    listener: EventListenerOrEventListenerObject,
+    options?: boolean | EventListenerOptions,
+  ) {
+    this.ac.signal.removeEventListener(type, listener, options)
+  }
+}
+
+export type AffFn<T, E> = (
+  actrl: Actrl,
+) => PromiseLike<Result<T, E>> | ResultAsync<T, E>
+export type NonEmptyArray<T> = readonly [T, ...T[]]
+export type ExtractOk<T> = T extends AffFn<infer U, unknown> ? U : never
+export type ExtractErr<T> = T extends AffFn<unknown, infer E> ? E : never
+
+export const ABORT_REASON = { SETTLED: 'settled', COMPLETED: 'completed' } as const
+export const noop = () => {}
+
+// ============================================================
+// 日志格式化函数
+// ============================================================
+
+/**
+ * 生成缩进字符串
+ */
+export const formatIndent = (depth: number): string => {
+  return '  '.repeat(depth)
+}
+
+/**
+ * 格式化显示 ID（取父级最后一段 + 当前 id）
+ */
+export const formatDisplayId = (parentId: string, childId: string): string => {
+  const parentShort = parentId.split('/').pop() || parentId
+  return parentShort + '/' + childId
+}
+
+/**
+ * 格式化开始日志
+ */
+export const formatLogStart = (indent: string, id: string): string => {
+  return indent + '→ ' + id
+}
+
+/**
+ * 格式化结束日志
+ */
+export const formatLogEnd = (indent: string, id: string, status?: string): string => {
+  return indent + '← ' + id + (status || '')
+}
+
+/**
+ * 格式化取消日志
+ */
+export const formatLogCancel = (
+  indent: string,
+  id: string,
+  reason?: string,
+): string => {
+  if (reason === 'parent aborted') {
+    return indent + '✗ ' + id + ' [cancelled: parent aborted]'
+  }
+  return indent + '✗ ' + id + ' [cancelled]'
+}
+
+/**
+ * 打印日志
+ */
+export const printLogs = (logs: string[], title?: string): void => {
+  if (logs.length > 0) {
+    if (title) {
+      console.log(`=== ${title} ===`)
+    }
+    console.log(logs.join('\n'))
+  }
+}
+
+// 简短 id 生成器
+let _idCounter = 0
+export const shortId = () => (++_idCounter).toString(36)

package/eff/eff.ts

@@ -31,15 +31,15 @@ const noop = () => {}
 /**
  * 将父 signal abort 传播到子 controller，返回解绑函数
  */
-const linkSignal = (
+const link = (
   parentSignal: AbortSignal,
-  controller: AbortController,
+  childController: AbortController,
 ): (() => void) => {
   if (parentSignal.aborted) {
-    controller.abort(parentSignal.reason)
+    childController.abort(parentSignal.reason)
     return noop
   }
-  const handler = () => controller.abort(parentSignal.reason)
+  const handler = () => childController.abort(parentSignal.reason)
   parentSignal.addEventListener('abort', handler, { once: true })
   return () => parentSignal.removeEventListener('abort', handler)
 }
@@ -68,10 +68,9 @@ const runAll = <T, E, R, ER>(
     },
   ) => void,
 ): ResultAsync<R, ER> =>
-  Eff.create(({ signal }) => {
+  Eff.create(({ signal: parentSignal }) => {
     const controller = new AbortController()
-    const childSignal = controller.signal
-    const unlink = linkSignal(signal, controller)
+    const unlink = link(parentSignal, controller)
 
     return new Promise((resolve) => {
       let done = false
@@ -90,7 +89,7 @@ const runAll = <T, E, R, ER>(
         resolve(r)
       }
 
-      if (signal.aborted) {
+      if (parentSignal.aborted) {
         settle(ok([] as R))
         return
       }
@@ -98,7 +97,7 @@ const runAll = <T, E, R, ER>(
       let remaining = executors.length
 
       executors.forEach((executor, i) => {
-        Eff.create(executor, childSignal).then((r) => {
+        Eff.create(executor, controller.signal).then((r) => {
           if (done) return
           remaining--
           onResult(r, i, settle, context)
@@ -129,7 +128,7 @@ export class Eff {
     parentSignal: AbortSignal,
   ): ResultAsync<T, E> {
     const controller = new AbortController()
-    const unlink = linkSignal(parentSignal, controller)
+    const unlink = link(parentSignal, controller)
 
     const promise: Promise<Result<T, E>> = Promise.resolve()
       .then(() => executor({ signal: controller.signal }))

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "tcdona_unilib",
-  "version": "1.0.12",
+  "version": "1.0.15",
   "description": "Unified dependency aggregation layer for shared libraries",
   "type": "module",
   "sideEffects": false,
   "exports": {
     "./astgrep": "./ast-grep.ts",
+    "./eff/aff": "./eff/aff.ts",
+    "./eff/aff.util": "./eff/aff.util.ts",
     "./eff/eff": "./eff/eff.ts",
     "./eff/effcan": "./eff/effcan.ts",
     "./eff/throwable": "./eff/throwable.ts",
@@ -46,32 +48,33 @@
     "./viteplugin/*.ts": "./viteplugin/*.ts"
   },
   "scripts": {
-    "viteplugin": "vite build -c viteplugin/vite.config.ts",
-    "pub": "bun run ./tc.pub.ts"
+    "test": "vitest",
+    "viteplugin": "vite build -c viteplugin/vite.config.ts"
   },
   "keywords": [],
   "author": "",
   "license": "ISC",
   "devDependencies": {
     "@types/bun": "^1.3.5",
-    "@types/node": "^20.10.6",
-    "vitest": "^4.0.16"
+    "@types/node": "^20.19.28"
   },
   "dependencies": {
-    "@ast-grep/napi": "^0.40.3",
-    "@dotenvx/dotenvx": "^1.51.2",
-    "@inquirer/prompts": "^8.1.0",
+    "@ast-grep/napi": "^0.40.5",
+    "@dotenvx/dotenvx": "^1.51.4",
+    "@inquirer/prompts": "^8.2.0",
     "@types/big.js": "^6.2.2",
+    "@types/js-yaml": "^4.0.9",
     "@types/turndown": "^5.0.6",
-    "animejs": "^4.1.3",
+    "animejs": "^4.2.2",
     "big.js": "^7.0.1",
     "clipboardy": "^5.0.2",
     "dayjs": "^1.11.19",
     "effector": "^23.4.4",
     "es-toolkit": "^1.43.0",
-    "exome": "^2.8.0",
+    "exome": "^2.8.1",
     "hono": "^4.11.3",
     "hotkeys-js": "^4.0.0",
+    "js-yaml": "^4.1.1",
     "koka": "^1.0.9",
     "koka-domain": "^1.0.0",
     "magic-regexp": "^0.10.0",
@@ -82,11 +85,12 @@
     "pathe": "^2.0.3",
     "pinyin-pro": "^3.27.0",
     "prettier": "^3.7.4",
-    "tinypool": "^2.0.0",
+    "tinypool": "^2.1.0",
     "turndown": "^7.2.2",
-    "vite": "^7.3.0",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.17",
     "vue": "^3.5.26",
-    "zod": "^4.2.1",
+    "zod": "^4.3.5",
     "zx": "^8.8.5"
   }
 }

package/staticMeta/enum.api.ts

@@ -105,9 +105,9 @@ export class TcErr extends Error {
     cons.error(
       getTimestamp(),
       `[${fileId.conf.srcFile}:${fileId.conf.id}]${fileId.conf.tag.length > 0 ? `[${fileId.conf.tag.join(', ')}]` : ''}`,
-      cause,
       rest,
     )
+    cons.log(cause)
   }
 }
 

package/staticMeta/file.yml.ts

@@ -1,5 +1,4 @@
 import { fs, YAML } from 'zx'
-
 /**
  * YAML 文件读写：无 data 参数时读取，有 data 参数时写入
  */
@@ -8,7 +7,7 @@ export function yml(path: string, data?: unknown): unknown {
     fs.writeFileSync(
       path,
       // @ts-expect-error YAML.stringify 类型定义有误
-      YAML.stringify(data, { singleQuote: true, sortKeys: true }),
+      YAML.stringify(data, { singleQuote: true }),
       'utf-8',
     )
   } else {
@@ -16,3 +15,13 @@ export function yml(path: string, data?: unknown): unknown {
     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)
+  }
+}