tcdona_unilib 1.0.11 → 1.0.14

package/eff/eff.ts

@@ -0,0 +1,225 @@
+/**
+ * Eff 框架：基于 Result 的异步任务管理
+ * - root/create：创建异步任务
+ * - all/any/race/allSettled：并行或竞速执行多个任务
+ * - Signal 传播：支持任务取消和自动清理
+ * - 支持返回 Result AsyncResult 不支持直接返回值
+ */
+import type { Result } from 'neverthrow'
+import { err, ok, ResultAsync } from 'neverthrow'
+
+export interface EffContext {
+  signal: AbortSignal
+}
+
+/**
+ * 任务执行器类型
+ *
+ * 设计说明：
+ * - 只接受函数，不接受直接的 ResultAsync<T, E>
+ * - 原因：函数形式表示延迟执行（调用时才执行），而 ResultAsync 表示已开始执行
+ * - 与 Promise.all 设计一致：接受函数数组而非 Promise 数组
+ * - 保持类型简单，避免运行时 instanceof 检查
+ * - 未来不应修改为支持 ResultAsync，以保持语义清晰和性能最优
+ */
+type EffExecutor<T, E> = (ctx: EffContext) => PromiseLike<Result<T, E>>
+type NonEmptyArray<T> = readonly [T, ...T[]]
+
+const ABORT_REASON = { SETTLED: 'settled', COMPLETED: 'completed' } as const
+const noop = () => {}
+
+/**
+ * 将父 signal abort 传播到子 controller，返回解绑函数
+ */
+const link = (
+  parentSignal: AbortSignal,
+  childController: AbortController,
+): (() => void) => {
+  if (parentSignal.aborted) {
+    childController.abort(parentSignal.reason)
+    return noop
+  }
+  const handler = () => childController.abort(parentSignal.reason)
+  parentSignal.addEventListener('abort', handler, { once: true })
+  return () => parentSignal.removeEventListener('abort', handler)
+}
+
+/**
+ * 并行运行多个任务，通过回调函数允许调用方控制何时 settle
+ *
+ * 类型参数说明：
+ * - T: 各个任务的成功值类型
+ * - E: 各个任务的错误值类型
+ * - R: 最终返回的成功值类型（由 onResult 的 settle 决定）
+ * - ER: 最终返回的错误值类型（由 onResult 的 settle 决定）
+ */
+const runAll = <T, E, R, ER>(
+  executors: NonEmptyArray<EffExecutor<T, E>>,
+  parentSignal: AbortSignal,
+  onResult: (
+    result: Result<T, E>,
+    index: number,
+    settle: (r: Result<R, ER>) => void,
+    context: {
+      resultCount: number
+      okValues: T[]
+      errValues: E[]
+      allResults: Result<T, E>[]
+    },
+  ) => void,
+): ResultAsync<R, ER> =>
+  Eff.create(({ signal: parentSignal }) => {
+    const controller = new AbortController()
+    const unlink = link(parentSignal, controller)
+
+    return new Promise((resolve) => {
+      let done = false
+      const context = {
+        resultCount: 0,
+        okValues: [] as T[],
+        errValues: [] as E[],
+        allResults: [] as Result<T, E>[],
+      }
+
+      const settle = (r: Result<R, ER>) => {
+        if (done) return
+        done = true
+        unlink()
+        controller.abort(ABORT_REASON.SETTLED)
+        resolve(r)
+      }
+
+      if (parentSignal.aborted) {
+        settle(ok([] as R))
+        return
+      }
+
+      let remaining = executors.length
+
+      executors.forEach((executor, i) => {
+        Eff.create(executor, controller.signal).then((r) => {
+          if (done) return
+          remaining--
+          onResult(r, i, settle, context)
+          if (remaining === 0) settle(ok(context.allResults as R))
+        })
+      })
+    })
+  }, parentSignal)
+
+export class Eff {
+  /**
+   * 创建根级任务（无父 signal）
+   */
+  static root<T, E>(executor: EffExecutor<T, E>): ResultAsync<T, E> {
+    const controller = new AbortController()
+    const promise: Promise<Result<T, E>> = Promise.resolve()
+      .then(() => executor({ signal: controller.signal }))
+      .catch((e) => err(e as E))
+      .finally(() => controller.abort(ABORT_REASON.COMPLETED))
+    return new ResultAsync(promise)
+  }
+
+  /**
+   * 创建子任务（继承父 signal，支持取消传播）
+   */
+  static create<T, E>(
+    executor: EffExecutor<T, E>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<T, E> {
+    const controller = new AbortController()
+    const unlink = link(parentSignal, controller)
+
+    const promise: Promise<Result<T, E>> = Promise.resolve()
+      .then(() => executor({ signal: controller.signal }))
+      .catch((e) => err(e as E))
+      .finally(() => {
+        unlink()
+        controller.abort(ABORT_REASON.COMPLETED)
+      })
+
+    return new ResultAsync(promise)
+  }
+
+  /**
+   * 全部成功才成功，任一失败立即失败并 abort 其他
+   */
+  static all<T, E>(
+    executors: NonEmptyArray<EffExecutor<T, E>>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<T[], E> {
+    return runAll<T, E, T[], E>(
+      executors,
+      parentSignal,
+      (result, index, settle, context) => {
+        result.match(
+          (v) => {
+            context.okValues[index] = v
+            context.resultCount++
+            if (context.resultCount === executors.length) {
+              settle(ok(context.okValues))
+            }
+          },
+          (e) => settle(err(e)),
+        )
+      },
+    )
+  }
+
+  /**
+   * 任一成功立即成功并 abort 其他，全部失败才失败
+   */
+  static any<T, E>(
+    executors: NonEmptyArray<EffExecutor<T, E>>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<T, E[]> {
+    return runAll<T, E, T, E[]>(
+      executors,
+      parentSignal,
+      (result, index, settle, context) => {
+        result.match(
+          (v) => settle(ok(v)),
+          (e) => {
+            context.errValues[index] = e
+            context.resultCount++
+            if (context.resultCount === executors.length) {
+              settle(err(context.errValues))
+            }
+          },
+        )
+      },
+    )
+  }
+
+  /**
+   * 任一完成立即返回其结果并 abort 其他
+   */
+  static race<T, E>(
+    executors: NonEmptyArray<EffExecutor<T, E>>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<T, E> {
+    return runAll<T, E, T, E>(
+      executors,
+      parentSignal,
+      (result, _index, settle) => {
+        settle(result)
+      },
+    )
+  }
+
+  /**
+   * 等待全部完成，收集所有结果（不因某个失败而 abort）
+   */
+  static allSettled<T, E>(
+    executors: NonEmptyArray<EffExecutor<T, E>>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<Result<T, E>[], never> {
+    return runAll<T, E, Result<T, E>[], never>(
+      executors,
+      parentSignal,
+      (result, index, _settle, context) => {
+        context.allResults[index] = result
+      },
+    )
+  }
+}

package/eff/effcan.ts

@@ -0,0 +1,286 @@
+/**
+ * EffCan 框架：基于 ResultAsync 的异步任务管理
+ * 与 Eff 的区别：
+ * - Executor 返回 ResultAsync<T, E> 而非 PromiseLike<Result<T, E>>
+ * - 假设 executor 不会抛出错误（无 catch 处理）
+ * - 保持 signal 生成/传递的语义和无内存泄露风险
+ *
+ * 设计原则与注意事项：
+ * 1. 内存管理
+ *    - linkSignal 返回的解绑函数必须被调用（在 runAll 的 settle 中执行）
+ *    - cleanup 需要在 Ok/Err 都执行（通过 andTee + orTee 组合实现）
+ *    - 若修改清理逻辑，务必确保两个分支都能执行
+ *
+ * 2. Signal abort 阶段
+ *    - SETTLED: 标志多任务中至少一个已确定结果，触发其他任务中断
+ *    - COMPLETED: 标志单个任务完成，用于事后清理
+ *    - 注意顺序：settle() 先调用 unlink()，再 abort(SETTLED)，保证解绑后才中断
+ *
+ * 3. runAll 中的 done 标志
+ *    - 防止 settle 被多次调用（Promise resolve 只有一次效果，但可能重复执行副作用）
+ *    - 也防止已 settle 后的结果被重复处理
+ *
+ * 4. allSettled 的特殊性
+ *    - 不因任一失败而 abort，但仍需执行并发控制
+ *    - 返回类型 never 表示这个操作本身不会产生错误
+ */
+import type { Result } from 'neverthrow'
+import { err, ok, ResultAsync } from 'neverthrow'
+
+export interface EffContext {
+  signal: AbortSignal
+}
+
+/**
+ * 任务执行器类型
+ * - 返回 ResultAsync<T, E>，表示异步任务已开始执行
+ * - 假设不会抛出错误，错误应通过 Err 返回
+ */
+type EffCanExecutor<T, E> = (ctx: EffContext) => ResultAsync<T, E>
+type NonEmptyArray<T> = readonly [T, ...T[]]
+
+const ABORT_REASON = { SETTLED: 'settled', COMPLETED: 'completed' } as const
+const noop = () => {}
+
+/**
+ * 将父 signal abort 传播到子 controller，返回解绑函数
+ */
+const linkSignal = (
+  parentSignal: AbortSignal,
+  controller: AbortController,
+): (() => void) => {
+  if (parentSignal.aborted) {
+    controller.abort(parentSignal.reason)
+    return noop
+  }
+  const handler = () => controller.abort(parentSignal.reason)
+  parentSignal.addEventListener('abort', handler, { once: true })
+  return () => parentSignal.removeEventListener('abort', handler)
+}
+
+/**
+ * 并行运行多个任务，通过回调函数允许调用方控制何时 settle
+ *
+ * 类型参数说明：
+ * - T: 各个任务的成功值类型
+ * - E: 各个任务的错误值类型
+ * - R: 最终返回的成功值类型（由 onResult 的 settle 决定）
+ * - ER: 最终返回的错误值类型（由 onResult 的 settle 决定）
+ *
+ * 关键设计细节：
+ * - 使用 childSignal 而非 signal，确保所有子任务中断后再结束
+ * - settle 被调用时：
+ *   1. done 标志防止重复处理
+ *   2. unlink() 移除父子 signal 关联（防止内存泄露）
+ *   3. abort(SETTLED) 中断所有未完成的子任务
+ *   4. resolve(r) Promise 才真正完成
+ * - 若所有任务都完成但没被 settle，则在 remaining === 0 时调用
+ * - 初始 signal.aborted 检查处理已被中止的父任务场景
+ */
+const runAll = <T, E, R, ER>(
+  executors: NonEmptyArray<EffCanExecutor<T, E>>,
+  parentSignal: AbortSignal,
+  onResult: (
+    result: Result<T, E>,
+    index: number,
+    settle: (r: Result<R, ER>) => void,
+    context: {
+      resultCount: number
+      okValues: T[]
+      errValues: E[]
+      allResults: Result<T, E>[]
+    },
+  ) => void,
+): ResultAsync<R, ER> =>
+  EffCan.create(({ signal }) => {
+    const controller = new AbortController()
+    const childSignal = controller.signal
+    const unlink = linkSignal(signal, controller)
+
+    const promise = new Promise<Result<R, ER>>((resolve) => {
+      let done = false
+      const context = {
+        resultCount: 0,
+        okValues: [] as T[],
+        errValues: [] as E[],
+        allResults: [] as Result<T, E>[],
+      }
+
+      const settle = (r: Result<R, ER>) => {
+        if (done) return
+        done = true
+        unlink()
+        controller.abort(ABORT_REASON.SETTLED)
+        resolve(r)
+      }
+
+      if (signal.aborted) {
+        settle(ok([] as R))
+        return
+      }
+
+      let remaining = executors.length
+
+      executors.forEach((executor, i) => {
+        EffCan.create(executor, childSignal).then((r) => {
+          if (done) return
+          remaining--
+          onResult(r, i, settle, context)
+          if (remaining === 0) settle(ok(context.allResults as R))
+        })
+      })
+    })
+
+    return new ResultAsync(promise)
+  }, parentSignal)
+
+export class EffCan {
+  /**
+   * 创建根级任务（无父 signal）
+   *
+   * 关键细节：
+   * - resultAsync.andTee(cleanup) 在 Ok 分支执行清理
+   * - resultAsync.orTee(cleanup) 在 Err 分支执行清理
+   * - 类型断言 as ResultAsync<T, E> 是必要的，因为 orTee 返回的类型推导会变复杂
+   * - cleanup 在两个分支都调用确保 abort(COMPLETED) 被执行
+   *
+   * 为何用 andTee + orTee 而不是其他方式：
+   * - .map() 只在 Ok 时执行（Err 时内存未释放）
+   * - .then() 返回 PromiseLike 而 ResultAsync 需要 Promise（不兼容）
+   * - andTee + orTee 是 neverthrow 提供的原生方式，无副作用污染
+   */
+  static root<T, E>(executor: EffCanExecutor<T, E>): ResultAsync<T, E> {
+    const controller = new AbortController()
+    const resultAsync = executor({ signal: controller.signal })
+
+    const cleanup = () => {
+      controller.abort(ABORT_REASON.COMPLETED)
+    }
+
+    return resultAsync.andTee(cleanup).orTee(cleanup) as ResultAsync<T, E>
+  }
+
+  /**
+   * 创建子任务（继承父 signal，支持取消传播）
+   *
+   * 关键细节：
+   * - parentSignal 中止时会自动中止 controller（通过 linkSignal）
+   * - unlink() 必须在清理时调用，否则会形成 EventListener 泄露
+   * - unlink() 调用顺序很重要：先 unlink，再 abort，避免竞态条件
+   * - cleanup 需要在两个分支都执行（通过 andTee + orTee）
+   *
+   * 内存泄露风险点：
+   * 1. 若遗漏 unlink() 调用，parentSignal 的 abort 监听器永不移除 → 内存泄露
+   * 2. 若只用 .map() 而不用 .orTee()，Err 分支的 unlink 不执行 → 内存泄露
+   * 3. 若改为手动 Promise 包装，需确保 finally 块执行（当前 andTee+orTee 方式更安全）
+   */
+  static create<T, E>(
+    executor: EffCanExecutor<T, E>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<T, E> {
+    const controller = new AbortController()
+    const unlink = linkSignal(parentSignal, controller)
+
+    const resultAsync = executor({ signal: controller.signal })
+
+    const cleanup = () => {
+      unlink()
+      controller.abort(ABORT_REASON.COMPLETED)
+    }
+
+    return resultAsync.andTee(cleanup).orTee(cleanup) as ResultAsync<T, E>
+  }
+
+  /**
+   * 全部成功才成功，任一失败立即失败并 abort 其他
+   */
+  static all<T, E>(
+    executors: NonEmptyArray<EffCanExecutor<T, E>>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<T[], E> {
+    return runAll<T, E, T[], E>(
+      executors,
+      parentSignal,
+      (result, index, settle, context) => {
+        result.match(
+          (v) => {
+            context.okValues[index] = v
+            context.resultCount++
+            if (context.resultCount === executors.length) {
+              settle(ok(context.okValues))
+            }
+          },
+          (e) => settle(err(e)),
+        )
+      },
+    )
+  }
+
+  /**
+   * 任一成功立即成功并 abort 其他，全部失败才失败
+   */
+  static any<T, E>(
+    executors: NonEmptyArray<EffCanExecutor<T, E>>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<T, E[]> {
+    return runAll<T, E, T, E[]>(
+      executors,
+      parentSignal,
+      (result, index, settle, context) => {
+        result.match(
+          (v) => settle(ok(v)),
+          (e) => {
+            context.errValues[index] = e
+            context.resultCount++
+            if (context.resultCount === executors.length) {
+              settle(err(context.errValues))
+            }
+          },
+        )
+      },
+    )
+  }
+
+  /**
+   * 任一完成立即返回其结果并 abort 其他
+   */
+  static race<T, E>(
+    executors: NonEmptyArray<EffCanExecutor<T, E>>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<T, E> {
+    return runAll<T, E, T, E>(
+      executors,
+      parentSignal,
+      (result, _index, settle) => {
+        settle(result)
+      },
+    )
+  }
+
+  /**
+   * 等待全部完成，收集所有结果（不因某个失败而 abort）
+   *
+   * 关键特性：
+   * - 与 all/any/race 不同，allSettled 不提前 settle，总是等所有任务完成
+   * - onResult 中不调用 settle，只收集结果
+   * - 当 remaining === 0 时才调用 settle(ok(context.allResults))（在 runAll 中）
+   * - 返回类型 never 表示外层 Result 的 Err 永不出现（永远 Ok）
+   *
+   * 用途：
+   * 1. 需要所有结果而不关心单个失败时
+   * 2. 并发执行多个独立任务并收集所有状态
+   * 3. 无需因一个失败而中止其他任务的场景
+   */
+  static allSettled<T, E>(
+    executors: NonEmptyArray<EffCanExecutor<T, E>>,
+    parentSignal: AbortSignal,
+  ): ResultAsync<Result<T, E>[], never> {
+    return runAll<T, E, Result<T, E>[], never>(
+      executors,
+      parentSignal,
+      (result, index, _settle, context) => {
+        context.allResults[index] = result
+      },
+    )
+  }
+}

package/eff/throwable.ts

@@ -0,0 +1,11 @@
+import { fromThrowable } from 'neverthrow'
+import { TcErr, fileInit } from '../staticMeta/enum.api'
+
+const fileId = fileInit('eff/throwable.ts')
+
+export const jsonParse = fromThrowable(JSON.parse, (e) => {
+  new TcErr({
+    fileId: fileId('jsonParse'),
+    cause: e,
+  })
+})

package/effector.ts

@@ -1,2 +1,33 @@
-export { createEvent, createStore, createEffect, createDomain, sample, combine, attach, merge, split, forward, guard, restore, scopeBind, allSettled, fork, serialize, hydrate, clearNode, withRegion, launch, is } from 'effector';
-export type { Event, Store, Effect, Domain, Scope, Unit, EventCallable, StoreWritable } from 'effector';
+export {
+  createEvent,
+  createStore,
+  createEffect,
+  createDomain,
+  sample,
+  combine,
+  attach,
+  merge,
+  split,
+  forward,
+  guard,
+  restore,
+  scopeBind,
+  allSettled,
+  fork,
+  serialize,
+  hydrate,
+  clearNode,
+  withRegion,
+  launch,
+  is,
+} from 'effector'
+export type {
+  Event,
+  Store,
+  Effect,
+  Domain,
+  Scope,
+  Unit,
+  EventCallable,
+  StoreWritable,
+} from 'effector'

package/es-toolkit.ts

@@ -50,14 +50,12 @@ export {
   zip,
   zipObject,
   zipWith,
-
   debounce,
   throttle,
   once,
   noop,
   identity,
   range,
-
   clone,
   cloneDeep,
   isEqual,
@@ -70,7 +68,6 @@ export {
   invert,
   mapKeys,
   mapValues,
-
   camelCase,
   capitalize,
   kebabCase,
@@ -84,7 +81,6 @@ export {
   trimEnd,
   trimStart,
   pad,
-
   mean,
   meanBy,
   sum,
@@ -93,11 +89,9 @@ export {
   clamp,
   random,
   randomInt,
-
   delay,
   timeout,
   retry,
-
   isNil,
   isNull,
   isUndefined,
@@ -109,4 +103,4 @@ export {
   isSymbol,
   isLength,
   isTypedArray,
-} from 'es-toolkit';
+} from 'es-toolkit'

package/exome.ts

@@ -1,2 +1,10 @@
-export { Exome, addMiddleware, getExomeId, onAction, subscribe, update, runMiddleware } from 'exome';
-export type { Middleware } from 'exome';
+export {
+  Exome,
+  addMiddleware,
+  getExomeId,
+  onAction,
+  subscribe,
+  update,
+  runMiddleware,
+} from 'exome'
+export type { Middleware } from 'exome'

package/hono.ts

@@ -1,4 +1,20 @@
-export { Hono } from "hono"
+// 导入所有需要的模块
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import { logger } from 'hono/logger'
+import { timeout } from 'hono/timeout'
+
+// 导出 Hono 主类
+export { Hono }
+
+// 导出 hono 中间件为对象，避免命名冲突
+export const honoMiddleware = {
+  cors,
+  logger,
+  timeout,
+}
+
+// 导出类型
 export type {
   Env,
   ErrorHandler,
@@ -20,4 +36,4 @@ export type {
   InferRequestType,
   InferResponseType,
   ClientRequestOptions,
-} from "hono"
+} from 'hono'

package/hotkeys-js.ts

@@ -1,2 +1,3 @@
-export { default } from 'hotkeys-js';
-export type { HotkeysEvent, KeyHandler } from 'hotkeys-js';
+import { default as hotkey } from 'hotkeys-js'
+export { hotkey }
+export type { HotkeysEvent, KeyHandler } from 'hotkeys-js'

package/idmeta.json

@@ -0,0 +1,42 @@
+{
+  "generatedAt": "2026-01-02T15:48:35.553Z",
+  "projectRoot": "/Users/admin/Documents/tc/tcdona_unilib",
+  "totalFiles": 50,
+  "files": [
+    [
+      "/Users/admin/Documents/tc/tcdona_unilib/staticMeta/ast.scan.ts",
+      "staticMeta/ast.scan.ts",
+      true,
+      "fileId",
+      [[595, 629]],
+      []
+    ],
+    [
+      "/Users/admin/Documents/tc/tcdona_unilib/staticMeta/sync.ts",
+      "staticMeta/sync.ts",
+      true,
+      "fileId",
+      [[337, 371]],
+      [
+        "deleteFileFailed",
+        "cleanupFailed",
+        "syncEntryFailed",
+        "syncStart",
+        "syncDirectoryFailed",
+        "syncComplete",
+        "syncStatsCopied",
+        "syncStatsSkipped",
+        "syncStatsDeleted",
+        "syncStatsErrors"
+      ]
+    ],
+    [
+      "/Users/admin/Documents/tc/tcdona_unilib/eff/throwable.ts",
+      "eff/throwable.ts",
+      true,
+      "fileId",
+      [[116, 139]],
+      ["jsonParse"]
+    ]
+  ]
+}

package/inquirer.ts

@@ -10,4 +10,4 @@ export {
   password,
   search,
   select,
-} from "@inquirer/prompts"
+} from '@inquirer/prompts'