@anjianshi/utils 2.5.0 → 2.7.0

package/src/env-node/safe-request.ts

@@ -0,0 +1,66 @@
+import { success, failed, type MaySuccess, type Failed } from '../lang/may-success.js'
+
+interface BaseOptions {
+  url: string
+  method?: 'GET' | 'POST'
+  headers?: Record<string, string>
+  body?: string | null
+
+  /** 若请求未成功发起，会触发此函数来生成失败信息 */
+  handleRequestError?: (error: Error) => Failed<unknown>
+  /** 请求成功发起，但服务端返回失败结果（如 500），会触发此函数来生成失败信息 */
+  handleResponseError?: (response: Response) => Failed<unknown> | Promise<Failed<unknown>>
+  /** 服务端返回内容解析失败时，会触发此函数来生成失败信息 */
+  handleParseFailed?: (error: Error, response: Response) => Failed<unknown>
+}
+
+function defaultHandleRequestError(error: Error) {
+  return failed('Request Error', undefined, error)
+}
+async function defaultHandleResponseError(response: Response) {
+  return failed(`Response Error:${response.status}`, undefined, await response.text())
+}
+function defaultHandleParseFailed(error: Error) {
+  return failed('Response Parse Failed', undefined, error)
+}
+
+/**
+ * 发起请求并妥善处理返回值，可用于与外部服务对接
+ */
+function safeRequest<T>(
+  options: BaseOptions & { responseType?: 'json' }
+): Promise<MaySuccess<T, Error | string>>
+function safeRequest(
+  options: BaseOptions & { responseType: 'binary' }
+): Promise<MaySuccess<Buffer, Error | string>>
+function safeRequest(
+  options: BaseOptions & { responseType: 'text' }
+): Promise<MaySuccess<string, Error | string>>
+async function safeRequest<T>(
+  options: BaseOptions & { responseType?: 'json' | 'binary' | 'text' }
+) {
+  const { url, method = 'GET', headers = {}, body = null, responseType = 'json' } = options
+  try {
+    const response = await fetch(url, {
+      method,
+      headers,
+      body,
+    })
+    try {
+      if (response.status !== 200 && (response.status !== 204 || responseType !== 'text')) {
+        return await (options.handleResponseError ?? defaultHandleResponseError)(response)
+      }
+
+      let responseBody: unknown
+      if (responseType === 'json') responseBody = await response.json()
+      else if (responseType === 'binary') responseBody = Buffer.from(await response.arrayBuffer())
+      else responseBody = await response.text()
+      return success(responseBody as T)
+    } catch (e) {
+      return (options.handleParseFailed ?? defaultHandleParseFailed)(e as Error, response)
+    }
+  } catch (e) {
+    return (options.handleRequestError ?? defaultHandleRequestError)(e as Error)
+  }
+}
+export { safeRequest }

package/src/env-react/emotion.tsx

@@ -0,0 +1,42 @@
+/**
+ * 通过 React Hook 把 emotion css 转换成 className
+ * （不再需要 <ClassName>）
+ *
+ * 使用前提：
+ * 1. 只支持浏览器渲染
+ * 2. 用 EmotionCacheProvider 包裹 App 根元素
+ *
+ * 来自：
+ * https://github.com/emotion-js/emotion/issues/1853#issuecomment-623349622
+ */
+import { type EmotionCache, withEmotionCache } from '@emotion/react'
+import { type CSSInterpolation, serializeStyles } from '@emotion/serialize'
+import { insertStyles } from '@emotion/utils'
+import { createContext, useContext, useCallback } from 'react'
+
+const CacheContext = createContext<EmotionCache | undefined>(undefined)
+export const useEmotionCache = () => useContext(CacheContext)
+
+export const EmotionCacheProvider = withEmotionCache(
+  ({ children }: { children: React.ReactNode }, cache: EmotionCache) => {
+    return <CacheContext.Provider value={cache}>{children}</CacheContext.Provider>
+  },
+)
+
+export function useEmotionClassName(): (...args: CSSInterpolation[]) => string {
+  const cache = useEmotionCache()
+  return useCallback(
+    (...args) => {
+      if (!cache) {
+        if (process.env.NODE_ENV === 'production') {
+          return 'emotion-cache-missing'
+        }
+        throw new Error('No emotion cache found!')
+      }
+      const serialized = serializeStyles(args, cache.registered)
+      insertStyles(cache, serialized, false)
+      return cache.key + '-' + serialized.name
+    },
+    [cache],
+  )
+}

package/src/env-service/controllers.ts

@@ -0,0 +1,93 @@
+/**
+ * 把业务功能整理成各个 Controller，
+ * 并整合成一个 controllers 对象方便外部引用和 Controller 之间互相引用。
+ *
+ * 支持自定义 Controller 类，例如把 context 中的内容定义成属性。
+ */
+
+/*
+【使用范例】
+
+// 定制 Context 和 Controller
+interface MyContext {
+  prop1: number
+  prop2: string
+}
+class MyController<
+  AllControllers extends Record<string, AnyController<MyContext>>,
+> extends Controller<MyContext, AllControllers> {
+  get prop1() {
+    return this.context.prop1
+  }
+  get prop2() {
+    return this.context.prop2
+  }
+}
+
+// 实现 Controller 内容
+class C1 extends MyController<Controllers> {
+  someMethod() {
+    console.log(this.prop1)
+    console.log(this.controllers.c2.prop2)
+  }
+}
+class C2 extends MyController<Controllers> {}
+class C3 extends MyController<Controllers> {}
+
+// 生成 controllers 类型和对象
+export const controllerClasses = { c1: C1, c2: C2, c3: C3 }
+export type Controllers = ControllersFrom<MyContext, typeof controllerClasses>
+initializeControllers({ c1: C1, c2: C2, c3: C3 }, { prop1: 1, prop2: 2 })
+*/
+
+export type AnyObject = Record<string, unknown>
+export type AnyController<Context> = Controller<Context, any> // eslint-disable-line @typescript-eslint/no-explicit-any
+type AnyControllerClass<Context> = typeof Controller<Context, any> // eslint-disable-line @typescript-eslint/no-explicit-any
+type ControllerClassesFrom<Context, T extends AnyObject> = {
+  [K in keyof T]: T[K] extends AnyControllerClass<Context> ? T[K] : never
+}
+export type ControllersFrom<Context, T extends AnyObject> = {
+  [K in keyof T]: T[K] extends AnyControllerClass<Context> ? InstanceType<T[K]> : never
+}
+
+/**
+ * Controller 基类
+ */
+export class Controller<Context, AllControllers extends Record<string, AnyController<Context>>> {
+  constructor(
+    /** 调用其他 controllers */
+    protected readonly controllers: AllControllers,
+
+    protected readonly context: Context,
+
+    protected readonly name: string = this.constructor.name,
+  ) {}
+}
+
+/**
+ * 传入 Controller 类列表，返回 controller 实例集合。
+ * 为优化性能，每个 controller 只有在被使用到时才会实例化。
+ */
+export function initializeControllers<Context, T extends AnyObject>(
+  controllerClasses: T,
+  context: Context,
+) {
+  type Classes = ControllerClassesFrom<Context, T>
+  type Controllers = ControllersFrom<Context, T>
+  const proxy = new Proxy({} as Controllers, {
+    get(controllers, prop) {
+      if (typeof prop !== 'string') return
+      if (prop in controllers) return controllers[prop]
+      if (prop in controllerClasses) {
+        const Class = controllerClasses[prop]! as typeof Controller<Context, Controllers>
+        controllers[prop as keyof Classes] = new Class(
+          proxy,
+          context,
+          prop,
+        ) as Controllers[keyof Classes]
+        return controllers[prop]
+      }
+    },
+  })
+  return proxy
+}

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

@@ -0,0 +1,141 @@
+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

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

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

@@ -0,0 +1,39 @@
+/**
+ * 对接 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

@@ -0,0 +1,21 @@
+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

@@ -0,0 +1,24 @@
+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

@@ -0,0 +1,162 @@
+/**
+ * 扩展 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

@@ -0,0 +1,65 @@
+/**
+ * 在事务中执行回调。与 $transaction 有几点不同：
+ * 1. 回调必须返回 MaySuccess 值
+ * 2. 回调返回 Failed 值或抛出异常都会触发回滚。
+ *    如果是返回 Failed，会作为此方法的返回值；如果是抛出异常，则异常会继续向上传递，直到被捕获或触发请求失败。
+ * 3. 如果已经处于事务中，会沿用上层事务，且回调返回 Failed 或抛出异常会触发上层事务的回滚。
+ *
+ * const result: MaySuccess = 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 { MaySuccess, 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>`，例如实际可能为 `MaySuccess<xxx, xxx> | Failed<any>`，这是有意为之的，`Failed<any>` 并不多余。
+// 因为有时 callback() 只会返回 success 结果，此时 R=Success<xxx>，但是 $withTransaction 整体的返回值仍有可能有 Failed<any>，所以不能用 R 作为整体返回值。
+async function $withTransaction<That extends object, R extends MaySuccess<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

@@ -0,0 +1,6 @@
+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'