tcdona_unilib 1.0.11 → 1.0.12

package/.prettierrc.json

@@ -0,0 +1,6 @@
+{
+  "singleQuote": true,
+  "tabWidth": 2,
+  "semi": false,
+  "arrowParens": "always"
+}

package/animejs.ts

@@ -1 +1,13 @@
-export { animate, createTimeline, createTimer, createScope, createSpring, createDraggable, stagger, eases, utils, svg, engine } from 'animejs';
+export {
+  animate,
+  createTimeline,
+  createTimer,
+  createScope,
+  createSpring,
+  createDraggable,
+  stagger,
+  eases,
+  utils,
+  svg,
+  engine,
+} from 'animejs'

package/ast-grep.ts

@@ -0,0 +1,42 @@
+// -----Type Only Export!-----//
+export type {
+  FileOption,
+  FindConfig,
+  NapiConfig,
+  DynamicLangRegistrations,
+  Edit,
+  Pos,
+  Range,
+  Rule,
+  Lang,
+  SgNode,
+} from '@ast-grep/napi'
+
+// -----Runtime Value Export!-----//
+// 导入所有需要的模块
+import {
+  findInFiles,
+  kind,
+  parse,
+  parseAsync,
+  parseFiles,
+  pattern,
+  registerDynamicLanguage,
+  Lang,
+  SgNode,
+  SgRoot,
+} from '@ast-grep/napi'
+
+// 导出为对象，避免命名冲突
+export const astgrep = {
+  findInFiles,
+  kind,
+  parse,
+  parseAsync,
+  parseFiles,
+  pattern,
+  registerDynamicLanguage,
+  Lang,
+  SgNode,
+  SgRoot,
+}

package/big.ts

@@ -1,2 +1,2 @@
-export { default as Big } from 'big.js';
-export type { Big as BigType, BigSource } from 'big.js';
+export { default as Big } from 'big.js'
+export type { Big as BigType, BigSource } from 'big.js'

package/clipboardy.ts

@@ -1 +1 @@
-export { default as clipboard } from 'clipboardy';
+export { default as clipboard } from 'clipboardy'

package/dayjs.ts

@@ -1,2 +1,2 @@
-export { default as dayjs } from 'dayjs';
-export type { Dayjs, ConfigType, OptionType } from 'dayjs';
+export { default as dayjs } from 'dayjs'
+export type { Dayjs, ConfigType, OptionType } from 'dayjs'

package/dotenvx.ts

@@ -1,4 +1,17 @@
-export { config, parse, set, get, ls, genexample } from "@dotenvx/dotenvx"
+// 导入所有需要的模块
+import { config, parse, set, get, ls, genexample } from '@dotenvx/dotenvx'
+
+// 导出为对象，避免命名冲突
+export const dotenvx = {
+  config,
+  parse,
+  set,
+  get,
+  ls,
+  genexample,
+}
+
+// 导出类型
 export type {
   DotenvConfigOptions,
   DotenvConfigOutput,
@@ -10,4 +23,4 @@ export type {
   SetOutput,
   GetOptions,
   GenExampleOutput,
-} from "@dotenvx/dotenvx"
+} from '@dotenvx/dotenvx'

package/eff/eff.delay.ts

@@ -0,0 +1,21 @@
+import { ok } from 'neverthrow'
+import { Eff } from './eff'
+
+/**
+ * 异步延迟函数：返回延迟是否完成（true）或被取消（false）
+ */
+export const delayEff = (time: number, parentSignal: AbortSignal) => {
+  return Eff.create<boolean, never>(({ signal }) => {
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => resolve(ok(true)), time)
+      signal.addEventListener(
+        'abort',
+        () => {
+          clearTimeout(timer)
+          resolve(ok(false))
+        },
+        { once: true },
+      )
+    })
+  }, parentSignal)
+}

package/eff/eff.ts

@@ -0,0 +1,226 @@
+/**
+ * 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 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 决定）
+ */
+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 }) => {
+    const controller = new AbortController()
+    const childSignal = controller.signal
+    const unlink = linkSignal(signal, 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 (signal.aborted) {
+        settle(ok([] as R))
+        return
+      }
+
+      let remaining = executors.length
+
+      executors.forEach((executor, i) => {
+        Eff.create(executor, childSignal).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 = linkSignal(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'