@anjianshi/utils 3.0.0 → 3.0.1

package/src/env-service/env-reader.ts

@@ -1,141 +0,0 @@
-import * as dotenv from 'dotenv'
-import { safeParseJSON } from '../lang/string.js'
-
-type EnvValue = string | number | boolean | unknown[] | Record<string, unknown>
-
-type TypeDef = 'string' | 'number' | 'boolean' | unknown[] | Record<string, unknown>
-type TypeFrom<D extends TypeDef> = D extends 'string'
-  ? string
-  : D extends 'number'
-    ? number
-    : D extends 'boolean'
-      ? boolean
-      : D
-type ResultFrom<Defs extends Record<string, TypeDef>> = {
-  [K in keyof Defs]: TypeFrom<Defs[K]>
-}
-
-/**
- * 读取 .env 文件，并获取格式化后的数据
- * 注意：依赖 dotenv 包
- */
-export class EnvReader {
-  protected loadedEnvs: Record<string, string> = {}
-
-  constructor(options: dotenv.DotenvConfigOptions = {}) {
-    dotenv.config({
-      ...options,
-
-      // 把从 .env 文件读到的内容写入此变量，而不是 process.env，以避免污染 process.env。
-      processEnv: this.loadedEnvs,
-    })
-  }
-
-  protected toNumber(raw: string) {
-    const num = parseInt(raw, 10)
-    return isFinite(num) ? num : undefined
-  }
-  protected toBoolean(raw: string) {
-    const formatted = raw.toLowerCase().trim()
-    if (['1', 'true', 'on'].includes(formatted)) return true
-    if (['0', 'false', 'off'].includes(formatted)) return false
-    return undefined
-  }
-
-  getRaw(key: string) {
-    return this.loadedEnvs[key] ?? process.env[key]
-  }
-
-  /**
-   * 获取指定 env 的值，并转换成与 defaults 匹配的类型。
-   * 若值不存在，返回 defaults。
-   */
-  get(key: string, defaults: string): string
-  get(key: string, defaults: number): number
-  get(key: string, defaults: boolean): boolean
-  get<T extends unknown[] | Record<string, unknown>>(key: string, defaults: T): T
-  get(key: string, defaults: EnvValue) {
-    const raw = this.getRaw(key)
-    if (raw === undefined) return defaults
-
-    if (typeof defaults === 'number') return this.toNumber(raw) ?? defaults
-    else if (typeof defaults === 'boolean') return this.toBoolean(raw) ?? defaults
-    else if (Array.isArray(defaults) || typeof defaults === 'object') {
-      return safeParseJSON(raw) ?? defaults
-    }
-
-    return raw
-  }
-
-  /**
-   * 获取指定 env 的值，并转换成指定类型，无需提供默认值。
-   * 值不存在或转换失败时，返回 undefined。
-   */
-  getByType(key: string, type?: 'string'): string | undefined
-  getByType(key: string, type: 'number'): number | undefined
-  getByType(key: string, type: 'boolean'): boolean | undefined
-  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-  getByType<T extends unknown[] | Record<string, unknown>>(key: string, type: 'json'): T | undefined
-  getByType(key: string, type: 'string' | 'number' | 'boolean' | 'json' = 'string') {
-    const raw = this.getRaw(key)
-    if (raw === undefined) return raw
-    if (type === 'number') return this.toNumber(raw)
-    if (type === 'boolean') return this.toBoolean(raw)
-    if (type === 'json') return safeParseJSON(raw)
-    return raw
-  }
-
-  /**
-   * 同 envReader.get()，只不过是通过对象指定各 env 的默认值来批量获取
-   * envReader.batchGet({ port: 8000, debug: false, mobiles: ['123', '456'] }
-   */
-  batchGet<Defs extends Record<string, EnvValue>>(definitions: Defs) {
-    const result = {} as Record<string, unknown>
-    for (const [key, defaults] of Object.entries(definitions)) {
-      result[key] = this.get(key, defaults as string)
-    }
-
-    // 保证返回的值类型是“通用化”的，例如不是 `false` 而是 `boolean`
-    return result as {
-      [K in keyof Defs]: Defs[K] extends string
-        ? string
-        : Defs[K] extends number
-          ? number
-          : Defs[K] extends boolean
-            ? boolean
-            : Defs[K]
-    }
-  }
-
-  /**
-   * 同 envReader.getByType()，只不过是通过对象指定各 env 的类型来批量获取。
-   *
-   * - required=false（默认）时，不存在或值为 undefined 的 env 不会出现在返回对象里，以保证 { ...defaults, ...envReader.batchGetByType(...) } 的用法能正常保留默认值。
-   * - required=true 时要求所有 env 都必须有值，否则会抛出异常
-   *
-   * envReader.batchGetByType({
-   *   port: 'number',
-   *   debug: 'boolean',
-   *   mobiles: [] as string[],  // 用此格式定义内容是数组的 JSON 值
-   *   obj: {} as { a: number, b: string } // 用此格式定义内容是对象的 JSON 值
-   * })
-   */
-  batchGetByType<Defs extends Record<string, TypeDef>>(
-    definitions: Defs,
-    required?: false,
-  ): Partial<ResultFrom<Defs>>
-  batchGetByType<Defs extends Record<string, TypeDef>>(
-    definitions: Defs,
-    required: true,
-  ): ResultFrom<Defs>
-  batchGetByType<Defs extends Record<string, TypeDef>>(definitions: Defs, required = false) {
-    const result = {} as Record<string, unknown>
-    for (const [key, def] of Object.entries(definitions)) {
-      const value =
-        typeof def === 'string' ? this.getByType(key, def as 'string') : this.getByType(key, 'json')
-      if (value !== undefined) result[key] = value
-      else if (required) throw new Error(`env ${key} needs a value`)
-    }
-    return result
-  }
-}

package/src/env-service/index.ts

@@ -1,6 +0,0 @@
-/**
- * 开发后端服务能用到的工具库
- */
-export * from './env-reader.js'
-export * from './controllers.js'
-export * from './tasks.js'

package/src/env-service/prisma/adapt-logging.ts

@@ -1,39 +0,0 @@
-/**
- * 对接 Prisma 的日志记录
- *
- * 注意：Prisma 的 debugging 日志是直接输出到 console 的，没有提供处理渠道，所以无法记录进日志文件。
- * 理论上可以重写 console.log/debug... 等方法来实现捕获，但这牵扯面太广，暂不这样做。
- */
-import nodeUtil from 'node:util'
-import type { getPrismaClient, PrismaClientOptions } from '@prisma/client/runtime/library.js'
-import chalk from 'chalk'
-import { type Logger } from '../../logging/index.js'
-
-type PrismalClient = ReturnType<typeof getPrismaClient> extends new () => infer T ? T : never
-
-export function getPrismaLoggingOptions(debug: boolean) {
-  return {
-    errorFormat: 'pretty',
-    log: [
-      ...(debug ? [{ emit: 'event', level: 'query' } as const] : []),
-      { emit: 'event', level: 'info' },
-      { emit: 'event', level: 'warn' },
-      { emit: 'event', level: 'error' },
-    ],
-  } satisfies PrismaClientOptions
-}
-
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-export function adaptPrismaLogging<T extends Pick<PrismalClient, '$on'>>(
-  prisma: T,
-  baseLogger: Logger,
-) {
-  // 记录 Prisma 相关日志
-  const queryLogger = baseLogger.getChild('query')
-  prisma.$on('query', e => {
-    queryLogger.debug(e.query, chalk.green(nodeUtil.format(e.params) + ` +${e.duration}ms`))
-  })
-  prisma.$on('info', e => baseLogger.info(e.message))
-  prisma.$on('warn', e => baseLogger.warn(e.message))
-  prisma.$on('error', e => baseLogger.error(e.message))
-}

package/src/env-service/prisma/extensions/exist.ts

@@ -1,21 +0,0 @@
-import { Prisma } from '@prisma/client/extension'
-
-/**
- * 快速检查指定条件的数据是否存在
- * const exists = await prisma.xxx.exists({ id: '1' })
- */
-export const exists = Prisma.defineExtension({
-  name: 'exists',
-  model: {
-    $allModels: {
-      async exists<T>(
-        this: T,
-        where: Prisma.Args<T, 'count'>['where'],
-        withDeleted = false,
-      ): Promise<boolean> {
-        const context = Prisma.getExtensionContext(this)
-        return !!(await (context as any).count({ where, withDeleted }))
-      },
-    },
-  },
-})

package/src/env-service/prisma/extensions/find-and-count.ts

@@ -1,24 +0,0 @@
-import { Prisma } from '@prisma/client/extension'
-import { type SoftDeleteQueryArgs } from './soft-delete.js'
-
-export const findAndCount = Prisma.defineExtension({
-  name: 'findAndCount',
-  model: {
-    $allModels: {
-      findAndCount<T, A>(
-        this: T,
-        rawArgs: Prisma.Exact<A, Prisma.Args<T, 'findMany'> & SoftDeleteQueryArgs>,
-      ) {
-        const context = Prisma.getExtensionContext(this)
-        const args = rawArgs as Prisma.Args<T, 'findMany'> & SoftDeleteQueryArgs
-        return Promise.all([
-          (context as any).findMany(args) as Promise<Prisma.Result<T, A, 'findMany'>>,
-          (context as any).count({
-            where: args.where,
-            withDeleted: args.withDeleted,
-          }) as Promise<Prisma.Result<T, A, 'count'>>,
-        ])
-      },
-    },
-  },
-})

package/src/env-service/prisma/extensions/soft-delete.ts

@@ -1,162 +0,0 @@
-/**
- * 扩展 Prisma 实现软删除
- *
- * 1. 有 deleteTime 字段的 model 支持软删除。
- * 2. 执行 delete() 和 deleteMany() 时默认是进行软删除；可指定 soft 为 false 来彻底删除；执行软删除时可指定要额外更新的 data。
- * 2. 查询时会忽略被软删除的记录；可指定 withDeleted 为 true 来包含它们。
- * 4. 可通过 restore() 和 restoreMany() 恢复软删除的记录。
- *
- * 扩展实现方式参考：
- * https://www.prisma.io/docs/orm/prisma-client/client-extensions/type-utilities#add-a-custom-property-to-a-method
- * https://www.npmjs.com/package/@prisma/extension-accelerate?activeTab=code  =>  @prisma/extension-accelerate/dist/esm/extension.js
- *
- * 此扩展修改了 Prisma 的原生方法。
- * 为保证其他扩展也应用到修改过的这些方法，此扩展应尽可能放在最前面。
- */
-import { Prisma } from '@prisma/client/extension'
-import type { Operation } from '@prisma/client/runtime/library.js'
-import { type OptionalFields } from '../../../index.js'
-
-type ExampleModel = any
-
-type DeleteArgs<T> = Prisma.Args<T, 'delete'> & {
-  soft?: boolean
-  data?: Prisma.Args<T, 'update'>['data'] // 软删除时支持额外更新其他字段
-}
-type DeleteReturn<T, A> = Promise<Prisma.Result<T, A, 'delete'>>
-
-type DeleteManyArgs<T> = Prisma.Args<T, 'deleteMany'> & {
-  soft?: boolean
-  data?: Prisma.Args<T, 'updateMany'>['data']
-}
-type DeleteManyReturn<T, A> = Promise<Prisma.Result<T, A, 'deleteMany'>>
-
-type RestoreArgs<T> = OptionalFields<Prisma.Args<T, 'update'>, 'data'>
-type RestoreManyArgs<T> = OptionalFields<Prisma.Args<T, 'updateMany'>, 'data'>
-
-interface QueryExtraArgs {
-  withDeleted?: boolean
-}
-export type { QueryExtraArgs as SoftDeleteQueryArgs }
-type QueryInputArgs<T, A, K extends Operation> = Prisma.Exact<A, Prisma.Args<T, K> & QueryExtraArgs>
-
-// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
-function getModel<T>(that: T) {
-  const context = Prisma.getExtensionContext(that as ExampleModel)
-
-  // 1. 此扩展修改了 Prisma 原生的方法，所以要通过 context.$parent[context.$name] 获取上一层的 model，不然会自己调用自己导致死循环。
-  // 2. 如果此扩展后面还应用了其他扩展，那么仅仅一层 $parent 取得的 model 还是这个扩展修改过的版本而不是原生的。
-  //    此时需要递归向上，直到取得未经此扩展修改过的 model。不然此扩展的业务逻辑会被重复执行，
-  //    而因为第一次执行时已经把定制参数消解掉了，第二次执行时会误以为没有传入定制参数，最终导致定制参数失效。
-  let model = context
-  do {
-    model = (model as unknown as { $parent: Record<string, ExampleModel> }).$parent[context.$name!]!
-  } while ('withSoftDeleteExtension' in model)
-
-  const supportSoftDelete = 'deleteTime' in model.fields
-  return { model, supportSoftDelete }
-}
-
-function query<T, A, K extends Operation>(
-  that: T,
-  inputArgs: Prisma.Exact<A, Prisma.Args<T, K>>,
-  method: K,
-) {
-  const { model, supportSoftDelete } = getModel(that)
-  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents
-  const { withDeleted = false, ...args } = inputArgs as Prisma.Args<ExampleModel, 'findFirst'> &
-    QueryExtraArgs
-
-  return model[method]({
-    ...args,
-    where: !supportSoftDelete || withDeleted ? args.where : { ...args.where, deleteTime: null },
-  }) as Promise<Prisma.Result<T, A, K>>
-}
-
-export const softDelete = Prisma.defineExtension({
-  name: 'softDeleted',
-  model: {
-    $allModels: {
-      withSoftDeleteExtension: true,
-
-      // -----------------------------
-      // 操作
-      // -----------------------------
-
-      delete<T, A>(this: T, rawArgs: Prisma.Exact<A, DeleteArgs<T>>) {
-        const { model, supportSoftDelete } = getModel(this)
-        const { soft = true, data, ...args } = rawArgs as DeleteArgs<ExampleModel>
-        if (supportSoftDelete && soft) {
-          return model.update({
-            ...args, // .delete() 的参数 .update() 也都支持
-            data: { ...(data ?? {}), deleteTime: new Date() },
-          }) as unknown as DeleteReturn<T, A> // .update() 的返回值和 .delete() 一样
-        } else {
-          return model.delete(args) as unknown as DeleteReturn<T, A>
-        }
-      },
-
-      deleteMany<T, A>(this: T, rawArgs: Prisma.Exact<A, DeleteManyArgs<T>>) {
-        const { model, supportSoftDelete } = getModel(this)
-        const { soft = true, data, ...args } = rawArgs as DeleteManyArgs<ExampleModel>
-        if (supportSoftDelete && soft) {
-          return model.updateMany({
-            ...args, // .deleteMany() 的参数 .updateMany() 也都支持
-            data: { ...(data ?? {}), deleteTime: new Date() },
-          }) as DeleteManyReturn<T, A> // .updateMany() 的返回值和 .deleteMany() 一样
-        } else {
-          return model.deleteMany(args) as DeleteManyReturn<T, A>
-        }
-      },
-
-      restore<T, A>(this: T, rawArgs: Prisma.Exact<A, RestoreArgs<T>>) {
-        const { data, ...args } = rawArgs as RestoreArgs<ExampleModel>
-        const { model, supportSoftDelete } = getModel(this)
-        if (!supportSoftDelete) throw new Error('当前模型不支持软删除，不能执行恢复')
-        return model.update({
-          ...(args as Prisma.Args<ExampleModel, 'update'>),
-          data: { ...(data ?? {}), deleteTime: null },
-        }) as unknown as Promise<Prisma.Result<T, A, 'update'>>
-      },
-
-      restoreMany<T, A>(this: T, rawArgs: Prisma.Exact<A, RestoreManyArgs<T>>) {
-        const { data, ...args } = rawArgs as RestoreArgs<ExampleModel>
-        const { model, supportSoftDelete } = getModel(this)
-        if (!supportSoftDelete) throw new Error('当前模型不支持软删除，不能执行恢复')
-        return model.updateMany({
-          ...(args as Prisma.Args<ExampleModel, 'updateMany'>),
-          data: { ...(data ?? {}), deleteTime: new Date() },
-        }) as Promise<Prisma.Result<T, A, 'updateMany'>>
-      },
-
-      // -----------------------------
-      // 查询
-      // -----------------------------
-
-      aggregate<T, A>(this: T, inputArgs: QueryInputArgs<T, A, 'aggregate'>) {
-        return query(this, inputArgs, 'aggregate')
-      },
-      count<T, A>(this: T, inputArgs: QueryInputArgs<T, A, 'count'>) {
-        return query(this, inputArgs, 'count')
-      },
-      findFirst<T, A>(this: T, inputArgs: QueryInputArgs<T, A, 'findFirst'>) {
-        return query(this, inputArgs, 'findFirst')
-      },
-      findFirstOrThrow<T, A>(this: T, inputArgs: QueryInputArgs<T, A, 'findFirstOrThrow'>) {
-        return query(this, inputArgs, 'findFirstOrThrow')
-      },
-      findMany<T, A>(this: T, inputArgs: QueryInputArgs<T, A, 'findMany'>) {
-        return query(this, inputArgs, 'findMany')
-      },
-      findUnique<T, A>(this: T, inputArgs: QueryInputArgs<T, A, 'findUnique'>) {
-        return query(this, inputArgs, 'findUnique')
-      },
-      findUniqueOrThrow<T, A>(this: T, inputArgs: QueryInputArgs<T, A, 'findUniqueOrThrow'>) {
-        return query(this, inputArgs, 'findUniqueOrThrow')
-      },
-      groupBy<T, A>(this: T, inputArgs: QueryInputArgs<T, A, 'groupBy'>) {
-        return query(this, inputArgs, 'groupBy')
-      },
-    },
-  },
-})

package/src/env-service/prisma/extensions/with-transaction.ts

@@ -1,65 +0,0 @@
-/**
- * 在事务中执行回调。与 $transaction 有几点不同：
- * 1. 回调必须返回 Result 值
- * 2. 回调返回 Failed 值或抛出异常都会触发回滚。
- *    如果是返回 Failed，会作为此方法的返回值；如果是抛出异常，则异常会继续向上传递，直到被捕获或触发请求失败。
- * 3. 如果已经处于事务中，会沿用上层事务，且回调返回 Failed 或抛出异常会触发上层事务的回滚。
- *
- * const result: Result = await db.$withTransaction(
- *   async (dbInTransaction) => {
- *     // do something
- *     return success()
- *   }
- * )
- */
-import { Prisma } from '@prisma/client/extension.js'
-import { type ITXClientDenyList } from '@prisma/client/runtime/library.js'
-import type { Result, Failed } from '../../../index.js'
-
-export const withTransaction = Prisma.defineExtension({
-  name: 'withTransaction',
-  client: {
-    $withTransaction,
-  },
-})
-
-// ----------------------------------
-
-export type GetPrismaClientInTransaction<PrismaClient> = Omit<PrismaClient, ITXClientDenyList>
-export type WithTransactionMethod = typeof $withTransaction
-
-type OpenTransaction<R = unknown> = (cb: (dbInTransaction: unknown) => Promise<R>) => Promise<R>
-
-class FailedInTransaction<T = void> extends Error {
-  constructor(readonly failed: Failed<T>) {
-    super(failed.message)
-  }
-}
-
-// 注意：此函数的返回值为 `R | Failed<any>`，例如实际可能为 `Result<xxx, xxx> | Failed<any>`，这是有意为之的，`Failed<any>` 并不多余。
-// 因为有时 callback() 只会返回 success 结果，此时 R=Success<xxx>，但是 $withTransaction 整体的返回值仍有可能有 Failed<any>，所以不能用 R 作为整体返回值。
-async function $withTransaction<That extends object, R extends Result<unknown, unknown>>(
-  this: That,
-  callback: (dbInTransaction: GetPrismaClientInTransaction<That>) => Promise<R>,
-) {
-  const executeCallback = async (dbInTransaction: unknown) => {
-    const result = await callback(dbInTransaction as GetPrismaClientInTransaction<That>)
-    if (result.success) return result
-    else throw new FailedInTransaction(result)
-  }
-
-  if ('$transaction' in this && this.$transaction) {
-    // 如果当前不在事务中，开启新事务并执行回调
-    try {
-      return await (this.$transaction as OpenTransaction<R>)(async dbInTransaction =>
-        executeCallback(dbInTransaction),
-      )
-    } catch (e) {
-      if (e instanceof FailedInTransaction) return e.failed
-      throw e
-    }
-  } else {
-    // 已经在事务中，直接执行回调（如果有异常，上层开启事务的代码会捕获）
-    return executeCallback(this)
-  }
-}

package/src/env-service/prisma/index.ts

@@ -1,6 +0,0 @@
-export * from './extensions/exist.js'
-export * from './extensions/find-and-count.js'
-export * from './extensions/soft-delete.js'
-export * from './extensions/with-transaction.js'
-export * from './transaction-contexted.js'
-export * from './adapt-logging.js'

package/src/env-service/prisma/transaction-contexted.ts

@@ -1,80 +0,0 @@
-import { type Result } from '../../index.js'
-import type {
-  GetPrismaClientInTransaction,
-  WithTransactionMethod,
-} from './extensions/with-transaction.js'
-
-/**
- * 返回一个可以在事务内和事务外通用的 PrismaClient 代理对象。
- * 当前在事务内时，调用它是调用事务内的 client；当前不在事务内时，调用它是调用全局 client。
- * 这样当一个事务涉及多个函数调用时，就不用把事务内 client 传递来传递去了。
- * 注意：应给每个线性流程（例如一个请求）单独生成一个此对象，不能作为全局对象使用，不然可能出现事务冲突。
- */
-export function getTransactionContextedPrismaClient<
-  AppPrismaClient extends {
-    $transaction: (...args: any[]) => Promise<unknown>
-    $withTransaction: WithTransactionMethod
-  },
->(prisma: AppPrismaClient): AppPrismaClient {
-  type PrismaClientInTransaction = GetPrismaClientInTransaction<AppPrismaClient>
-
-  /** 虽然这里还是会把事务中的 client 传给 callback，但实际并不需要了，始终使用 contexted client 即可 */
-  type TransactionCallback<R = unknown> = (client: PrismaClientInTransaction) => Promise<R>
-
-  let client: AppPrismaClient | PrismaClientInTransaction = prisma
-
-  async function callCallbackInTransaction<R = unknown>(
-    callback: TransactionCallback<R>,
-    clientInTransaction: PrismaClientInTransaction,
-  ) {
-    const prevClient = client
-    const currentClient = clientInTransaction
-    client = currentClient
-    function restoreClient() {
-      if (client !== currentClient)
-        throw new Error('事务冲突，必须等一个事务结束后再开启另一个事务')
-      client = prevClient
-    }
-
-    try {
-      const res = await callback(client)
-      restoreClient()
-      return res
-    } catch (e) {
-      restoreClient()
-      throw e
-    }
-  }
-
-  async function $transaction(arg: unknown, ...restArgs: unknown[]) {
-    interface GeneralClient {
-      $transaction: (...args: unknown[]) => Promise<unknown>
-    }
-    if (typeof arg === 'function') {
-      const wrappedCallback = callCallbackInTransaction.bind(null, arg as TransactionCallback)
-      return (client as GeneralClient).$transaction(wrappedCallback, ...restArgs)
-    } else {
-      return (client as GeneralClient).$transaction(arg, ...restArgs)
-    }
-  }
-
-  async function $withTransaction(callback: TransactionCallback<Result>) {
-    return client.$withTransaction(async clientInTransaction =>
-      callCallbackInTransaction(callback, clientInTransaction as PrismaClientInTransaction),
-    )
-  }
-
-  return new Proxy(
-    {},
-    {
-      has(_, prop) {
-        return prop in client
-      },
-      get(_, prop) {
-        if (prop === '$transaction') return $transaction
-        if (prop === '$withTransaction') return $withTransaction
-        return (client as Record<string | symbol, unknown>)[prop]
-      },
-    },
-  ) as AppPrismaClient
-}