@wordrhyme/auto-crud-server 0.3.0 → 0.6.0

package/dist/index.d.cts

@@ -42,7 +42,139 @@ interface SoftDeleteConfig {
  * - SoftDeleteConfig: 完整配置
  */
 type SoftDeleteOption = string | boolean | SoftDeleteConfig;
-interface CrudRouterConfigBase {
+/**
+ * 列表查询输入类型
+ */
+interface ListInput {
+  page: number;
+  perPage: number;
+  sort?: Array<{
+    id: string;
+    desc: boolean;
+  }>;
+  filters?: Array<{
+    id: string;
+    value: string | string[];
+    variant: string;
+    operator: string;
+    filterId: string;
+  }>;
+  joinOperator: "and" | "or";
+}
+/**
+ * 列表查询结果类型
+ */
+interface ListResult<TSelect> {
+  data: TSelect[];
+  total: number;
+  page: number;
+  perPage: number;
+  pageCount: number;
+}
+/**
+ * 操作包装器 - 类似 tRPC middleware 的 next 模式
+ *
+ * 功能：
+ * - 修改输入数据（传参给 next）
+ * - 修改返回值（处理 next 的结果）
+ * - 执行副作用（日志、通知、审计）
+ * - 条件拦截（不调用 next 直接返回/抛错）
+ * - 包装事务（try/catch 包裹 next）
+ *
+ * @example
+ * // 修改输入 + 执行副作用
+ * middleware: {
+ *   create: async ({ ctx, input, next }) => {
+ *     const data = { ...input, slug: slugify(input.title) };
+ *     const result = await next(data);
+ *     await sendNotification(result);
+ *     return result;
+ *   },
+ * }
+ *
+ * @example
+ * // 简单副作用 - 使用工具函数
+ * import { afterMiddleware } from "@wordrhyme/auto-crud-server";
+ *
+ * middleware: {
+ *   create: afterMiddleware(async (ctx, result) => {
+ *     await sendEmail(result);
+ *   }),
+ * }
+ */
+interface CrudMiddleware<TContext = unknown> {
+  /**
+   * 列表查询包装器
+   */
+  list?: (params: {
+    ctx: TContext;
+    input: ListInput;
+    next: (input?: ListInput) => Promise<ListResult<unknown>>;
+  }) => Promise<ListResult<unknown>>;
+  /**
+   * 单条查询包装器
+   */
+  get?: (params: {
+    ctx: TContext;
+    id: string;
+    next: () => Promise<unknown | null>;
+  }) => Promise<unknown | null>;
+  /**
+   * 创建包装器
+   */
+  create?: (params: {
+    ctx: TContext;
+    input: unknown;
+    next: (input?: unknown) => Promise<unknown>;
+  }) => Promise<unknown>;
+  /**
+   * 更新包装器
+   * existing: 更新前的记录
+   */
+  update?: (params: {
+    ctx: TContext;
+    id: string;
+    data: unknown;
+    existing: unknown;
+    next: (data?: unknown) => Promise<unknown>;
+  }) => Promise<unknown>;
+  /**
+   * 删除包装器
+   * existing: 删除前的记录
+   */
+  delete?: (params: {
+    ctx: TContext;
+    id: string;
+    existing: unknown;
+    next: () => Promise<unknown>;
+  }) => Promise<unknown>;
+  /**
+   * 批量删除包装器
+   */
+  deleteMany?: (params: {
+    ctx: TContext;
+    ids: string[];
+    next: () => Promise<{
+      deleted: number;
+    }>;
+  }) => Promise<{
+    deleted: number;
+  }>;
+  /**
+   * 批量更新包装器
+   */
+  updateMany?: (params: {
+    ctx: TContext;
+    ids: string[];
+    data: unknown;
+    next: (data?: unknown) => Promise<{
+      updated: number;
+    }>;
+  }) => Promise<{
+    updated: number;
+  }>;
+}
+interface CrudRouterConfigBase<TContext = unknown> {
   /** Drizzle 表定义 */
   table: PgTable;
   /** 查询返回 Schema */
@@ -77,8 +209,37 @@ interface CrudRouterConfigBase {
    * softDelete: { column: 'isDeleted', value: () => true }
    */
   softDelete?: SoftDeleteOption;
+  /**
+   * 操作中间件
+   * 类似 tRPC middleware 的 next 模式，完全控制操作流程
+   *
+   * @example
+   * // 完整控制
+   * middleware: {
+   *   create: async ({ ctx, input, next }) => {
+   *     const data = { ...input, slug: slugify(input.title) };
+   *     const result = await next(data);
+   *     await sendNotification(result);
+   *     return result;
+   *   },
+   * }
+   *
+   * @example
+   * // 使用工具函数简化
+   * import { afterMiddleware, beforeMiddleware } from "@wordrhyme/auto-crud-server";
+   *
+   * middleware: {
+   *   create: afterMiddleware(async (ctx, result) => {
+   *     await sendEmail(result);
+   *   }),
+   *   update: beforeMiddleware(async (ctx, data) => {
+   *     return { ...data, updatedAt: new Date() };
+   *   }),
+   * }
+   */
+  middleware?: CrudMiddleware<TContext>;
 }
-interface DeclarativeConfig<TContext = unknown> extends CrudRouterConfigBase {
+interface DeclarativeConfig<TContext = unknown> extends CrudRouterConfigBase<TContext> {
   mode?: "declarative";
   /**
    * 基础 procedure（认证）
@@ -118,7 +279,7 @@ interface DeclarativeConfig<TContext = unknown> extends CrudRouterConfigBase {
    */
   authorize?: (ctx: TContext, resource: Record<string, unknown>, operation: CrudOperation) => boolean | Promise<boolean>;
 }
-interface FactoryConfig<TContext = unknown> extends CrudRouterConfigBase {
+interface FactoryConfig<TContext = unknown> extends CrudRouterConfigBase<TContext> {
   mode: "factory";
   /**
    * Procedure 工厂函数
@@ -137,7 +298,7 @@ interface FactoryConfig<TContext = unknown> extends CrudRouterConfigBase {
    */
   inject?: (ctx: TContext, operation: WriteOperation) => Record<string, unknown>;
 }
-interface ProceduresConfig<TContext = unknown> extends CrudRouterConfigBase {
+interface ProceduresConfig<TContext = unknown> extends CrudRouterConfigBase<TContext> {
   mode: "procedures";
   /**
    * 按操作指定不同的 procedure
@@ -197,6 +358,134 @@ declare function createCrudRouter<TContext = unknown>(config: CrudRouterConfig<T
   };
 };
 //#endregion
+//#region src/lib/middleware-helpers.d.ts
+type NextFn<TInput, TResult> = (input?: TInput) => Promise<TResult>;
+interface MiddlewareParams<TContext, TInput, TResult> {
+  ctx: TContext;
+  input?: TInput;
+  next: NextFn<TInput, TResult>;
+}
+/**
+ * 创建 after-only 的 middleware（最常见场景）
+ * 在操作完成后执行副作用，不修改返回值
+ *
+ * @example
+ * middleware: {
+ *   create: afterMiddleware(async (ctx, result) => {
+ *     await sendEmail(result);
+ *     await logAudit(ctx.user, 'create', result);
+ *   }),
+ * }
+ */
+declare function afterMiddleware<TContext, TResult>(fn: (ctx: TContext, result: TResult) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TResult>;
+}) => Promise<TResult>;
+/**
+ * 创建 after-only 的 middleware，可修改返回值
+ *
+ * @example
+ * middleware: {
+ *   get: afterMiddlewareTransform(async (ctx, result) => {
+ *     return { ...result, computed: calculateSomething(result) };
+ *   }),
+ * }
+ */
+declare function afterMiddlewareTransform<TContext, TResult>(fn: (ctx: TContext, result: TResult) => TResult | Promise<TResult>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TResult>;
+}) => Promise<TResult>;
+/**
+ * 创建 before-only 的 middleware
+ * 在操作执行前修改输入数据
+ *
+ * @example
+ * middleware: {
+ *   create: beforeMiddleware(async (ctx, input) => {
+ *     return { ...input, slug: slugify(input.title), createdBy: ctx.user.id };
+ *   }),
+ * }
+ */
+declare function beforeMiddleware<TContext, TInput>(fn: (ctx: TContext, input: TInput) => TInput | Promise<TInput>): <TResult>({
+  ctx,
+  input,
+  next
+}: MiddlewareParams<TContext, TInput, TResult>) => Promise<TResult>;
+/**
+ * 组合多个 middleware 为一个
+ *
+ * @example
+ * middleware: {
+ *   create: composeMiddleware(
+ *     beforeMiddleware((ctx, input) => ({ ...input, slug: slugify(input.title) })),
+ *     afterMiddleware((ctx, result) => sendEmail(result)),
+ *   ),
+ * }
+ */
+declare function composeMiddleware<TContext, TInput, TResult>(...middlewares: Array<(params: MiddlewareParams<TContext, TInput, TResult>) => Promise<TResult>>): (params: MiddlewareParams<TContext, TInput, TResult>) => Promise<TResult>;
+/**
+ * 创建 list 操作的 after middleware
+ */
+declare function afterList<TContext, TSelect>(fn: (ctx: TContext, result: ListResult<TSelect>) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<ListResult<TSelect>>;
+}) => Promise<ListResult<TSelect>>;
+/**
+ * 创建 list 操作的 before middleware
+ */
+declare function beforeList<TContext>(fn: (ctx: TContext, input: ListInput) => ListInput | Promise<ListInput>): <TResult>({
+  ctx,
+  input,
+  next
+}: MiddlewareParams<TContext, ListInput, TResult>) => Promise<TResult>;
+/**
+ * 创建 create 操作的 after middleware
+ */
+declare function afterCreate<TContext, TSelect>(fn: (ctx: TContext, created: TSelect) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TSelect>;
+}) => Promise<TSelect>;
+/**
+ * 创建 create 操作的 before middleware
+ */
+declare function beforeCreate<TContext, TInsert>(fn: (ctx: TContext, input: TInsert) => TInsert | Promise<TInsert>): <TResult>({
+  ctx,
+  input,
+  next
+}: MiddlewareParams<TContext, TInsert, TResult>) => Promise<TResult>;
+/**
+ * 创建 update 操作的 after middleware
+ */
+declare function afterUpdate<TContext, TSelect>(fn: (ctx: TContext, updated: TSelect) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TSelect>;
+}) => Promise<TSelect>;
+/**
+ * 创建 delete 操作的 after middleware
+ */
+declare function afterDelete<TContext, TSelect>(fn: (ctx: TContext, deleted: TSelect) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TSelect>;
+}) => Promise<TSelect>;
+//#endregion
 //#region src/routers/index.d.ts
 declare const appRouter: _trpc_server5.TRPCBuiltRouter<{
   ctx: Context;
@@ -206,4 +495,4 @@ declare const appRouter: _trpc_server5.TRPCBuiltRouter<{
 }, _trpc_server5.TRPCDecorateCreateRouterOptions<{}>>;
 type AppRouter = typeof appRouter;
 //#endregion
-export { type AnyProcedure, type AppRouter, type CrudOperation, type CrudRouterConfig, type DeclarativeConfig, type FactoryConfig, type ProceduresConfig, type SoftDeleteConfig, type SoftDeleteOption, type WriteOperation, appRouter, createCrudRouter, publicProcedure, router };
+export { type AnyProcedure, type AppRouter, type CrudMiddleware, type CrudOperation, type CrudRouterConfig, type DeclarativeConfig, type FactoryConfig, type ListInput, type ListResult, type ProceduresConfig, type SoftDeleteConfig, type SoftDeleteOption, type WriteOperation, afterCreate, afterDelete, afterList, afterMiddleware, afterMiddlewareTransform, afterUpdate, appRouter, beforeCreate, beforeList, beforeMiddleware, composeMiddleware, createCrudRouter, publicProcedure, router };

package/dist/index.d.ts

@@ -43,7 +43,139 @@ interface SoftDeleteConfig {
  * - SoftDeleteConfig: 完整配置
  */
 type SoftDeleteOption = string | boolean | SoftDeleteConfig;
-interface CrudRouterConfigBase {
+/**
+ * 列表查询输入类型
+ */
+interface ListInput {
+  page: number;
+  perPage: number;
+  sort?: Array<{
+    id: string;
+    desc: boolean;
+  }>;
+  filters?: Array<{
+    id: string;
+    value: string | string[];
+    variant: string;
+    operator: string;
+    filterId: string;
+  }>;
+  joinOperator: "and" | "or";
+}
+/**
+ * 列表查询结果类型
+ */
+interface ListResult<TSelect> {
+  data: TSelect[];
+  total: number;
+  page: number;
+  perPage: number;
+  pageCount: number;
+}
+/**
+ * 操作包装器 - 类似 tRPC middleware 的 next 模式
+ *
+ * 功能：
+ * - 修改输入数据（传参给 next）
+ * - 修改返回值（处理 next 的结果）
+ * - 执行副作用（日志、通知、审计）
+ * - 条件拦截（不调用 next 直接返回/抛错）
+ * - 包装事务（try/catch 包裹 next）
+ *
+ * @example
+ * // 修改输入 + 执行副作用
+ * middleware: {
+ *   create: async ({ ctx, input, next }) => {
+ *     const data = { ...input, slug: slugify(input.title) };
+ *     const result = await next(data);
+ *     await sendNotification(result);
+ *     return result;
+ *   },
+ * }
+ *
+ * @example
+ * // 简单副作用 - 使用工具函数
+ * import { afterMiddleware } from "@wordrhyme/auto-crud-server";
+ *
+ * middleware: {
+ *   create: afterMiddleware(async (ctx, result) => {
+ *     await sendEmail(result);
+ *   }),
+ * }
+ */
+interface CrudMiddleware<TContext = unknown> {
+  /**
+   * 列表查询包装器
+   */
+  list?: (params: {
+    ctx: TContext;
+    input: ListInput;
+    next: (input?: ListInput) => Promise<ListResult<unknown>>;
+  }) => Promise<ListResult<unknown>>;
+  /**
+   * 单条查询包装器
+   */
+  get?: (params: {
+    ctx: TContext;
+    id: string;
+    next: () => Promise<unknown | null>;
+  }) => Promise<unknown | null>;
+  /**
+   * 创建包装器
+   */
+  create?: (params: {
+    ctx: TContext;
+    input: unknown;
+    next: (input?: unknown) => Promise<unknown>;
+  }) => Promise<unknown>;
+  /**
+   * 更新包装器
+   * existing: 更新前的记录
+   */
+  update?: (params: {
+    ctx: TContext;
+    id: string;
+    data: unknown;
+    existing: unknown;
+    next: (data?: unknown) => Promise<unknown>;
+  }) => Promise<unknown>;
+  /**
+   * 删除包装器
+   * existing: 删除前的记录
+   */
+  delete?: (params: {
+    ctx: TContext;
+    id: string;
+    existing: unknown;
+    next: () => Promise<unknown>;
+  }) => Promise<unknown>;
+  /**
+   * 批量删除包装器
+   */
+  deleteMany?: (params: {
+    ctx: TContext;
+    ids: string[];
+    next: () => Promise<{
+      deleted: number;
+    }>;
+  }) => Promise<{
+    deleted: number;
+  }>;
+  /**
+   * 批量更新包装器
+   */
+  updateMany?: (params: {
+    ctx: TContext;
+    ids: string[];
+    data: unknown;
+    next: (data?: unknown) => Promise<{
+      updated: number;
+    }>;
+  }) => Promise<{
+    updated: number;
+  }>;
+}
+interface CrudRouterConfigBase<TContext = unknown> {
   /** Drizzle 表定义 */
   table: PgTable;
   /** 查询返回 Schema */
@@ -78,8 +210,37 @@ interface CrudRouterConfigBase {
    * softDelete: { column: 'isDeleted', value: () => true }
    */
   softDelete?: SoftDeleteOption;
+  /**
+   * 操作中间件
+   * 类似 tRPC middleware 的 next 模式，完全控制操作流程
+   *
+   * @example
+   * // 完整控制
+   * middleware: {
+   *   create: async ({ ctx, input, next }) => {
+   *     const data = { ...input, slug: slugify(input.title) };
+   *     const result = await next(data);
+   *     await sendNotification(result);
+   *     return result;
+   *   },
+   * }
+   *
+   * @example
+   * // 使用工具函数简化
+   * import { afterMiddleware, beforeMiddleware } from "@wordrhyme/auto-crud-server";
+   *
+   * middleware: {
+   *   create: afterMiddleware(async (ctx, result) => {
+   *     await sendEmail(result);
+   *   }),
+   *   update: beforeMiddleware(async (ctx, data) => {
+   *     return { ...data, updatedAt: new Date() };
+   *   }),
+   * }
+   */
+  middleware?: CrudMiddleware<TContext>;
 }
-interface DeclarativeConfig<TContext = unknown> extends CrudRouterConfigBase {
+interface DeclarativeConfig<TContext = unknown> extends CrudRouterConfigBase<TContext> {
   mode?: "declarative";
   /**
    * 基础 procedure（认证）
@@ -119,7 +280,7 @@ interface DeclarativeConfig<TContext = unknown> extends CrudRouterConfigBase {
    */
   authorize?: (ctx: TContext, resource: Record<string, unknown>, operation: CrudOperation) => boolean | Promise<boolean>;
 }
-interface FactoryConfig<TContext = unknown> extends CrudRouterConfigBase {
+interface FactoryConfig<TContext = unknown> extends CrudRouterConfigBase<TContext> {
   mode: "factory";
   /**
    * Procedure 工厂函数
@@ -138,7 +299,7 @@ interface FactoryConfig<TContext = unknown> extends CrudRouterConfigBase {
    */
   inject?: (ctx: TContext, operation: WriteOperation) => Record<string, unknown>;
 }
-interface ProceduresConfig<TContext = unknown> extends CrudRouterConfigBase {
+interface ProceduresConfig<TContext = unknown> extends CrudRouterConfigBase<TContext> {
   mode: "procedures";
   /**
    * 按操作指定不同的 procedure
@@ -198,6 +359,134 @@ declare function createCrudRouter<TContext = unknown>(config: CrudRouterConfig<T
   };
 };
 //#endregion
+//#region src/lib/middleware-helpers.d.ts
+type NextFn<TInput, TResult> = (input?: TInput) => Promise<TResult>;
+interface MiddlewareParams<TContext, TInput, TResult> {
+  ctx: TContext;
+  input?: TInput;
+  next: NextFn<TInput, TResult>;
+}
+/**
+ * 创建 after-only 的 middleware（最常见场景）
+ * 在操作完成后执行副作用，不修改返回值
+ *
+ * @example
+ * middleware: {
+ *   create: afterMiddleware(async (ctx, result) => {
+ *     await sendEmail(result);
+ *     await logAudit(ctx.user, 'create', result);
+ *   }),
+ * }
+ */
+declare function afterMiddleware<TContext, TResult>(fn: (ctx: TContext, result: TResult) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TResult>;
+}) => Promise<TResult>;
+/**
+ * 创建 after-only 的 middleware，可修改返回值
+ *
+ * @example
+ * middleware: {
+ *   get: afterMiddlewareTransform(async (ctx, result) => {
+ *     return { ...result, computed: calculateSomething(result) };
+ *   }),
+ * }
+ */
+declare function afterMiddlewareTransform<TContext, TResult>(fn: (ctx: TContext, result: TResult) => TResult | Promise<TResult>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TResult>;
+}) => Promise<TResult>;
+/**
+ * 创建 before-only 的 middleware
+ * 在操作执行前修改输入数据
+ *
+ * @example
+ * middleware: {
+ *   create: beforeMiddleware(async (ctx, input) => {
+ *     return { ...input, slug: slugify(input.title), createdBy: ctx.user.id };
+ *   }),
+ * }
+ */
+declare function beforeMiddleware<TContext, TInput>(fn: (ctx: TContext, input: TInput) => TInput | Promise<TInput>): <TResult>({
+  ctx,
+  input,
+  next
+}: MiddlewareParams<TContext, TInput, TResult>) => Promise<TResult>;
+/**
+ * 组合多个 middleware 为一个
+ *
+ * @example
+ * middleware: {
+ *   create: composeMiddleware(
+ *     beforeMiddleware((ctx, input) => ({ ...input, slug: slugify(input.title) })),
+ *     afterMiddleware((ctx, result) => sendEmail(result)),
+ *   ),
+ * }
+ */
+declare function composeMiddleware<TContext, TInput, TResult>(...middlewares: Array<(params: MiddlewareParams<TContext, TInput, TResult>) => Promise<TResult>>): (params: MiddlewareParams<TContext, TInput, TResult>) => Promise<TResult>;
+/**
+ * 创建 list 操作的 after middleware
+ */
+declare function afterList<TContext, TSelect>(fn: (ctx: TContext, result: ListResult<TSelect>) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<ListResult<TSelect>>;
+}) => Promise<ListResult<TSelect>>;
+/**
+ * 创建 list 操作的 before middleware
+ */
+declare function beforeList<TContext>(fn: (ctx: TContext, input: ListInput) => ListInput | Promise<ListInput>): <TResult>({
+  ctx,
+  input,
+  next
+}: MiddlewareParams<TContext, ListInput, TResult>) => Promise<TResult>;
+/**
+ * 创建 create 操作的 after middleware
+ */
+declare function afterCreate<TContext, TSelect>(fn: (ctx: TContext, created: TSelect) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TSelect>;
+}) => Promise<TSelect>;
+/**
+ * 创建 create 操作的 before middleware
+ */
+declare function beforeCreate<TContext, TInsert>(fn: (ctx: TContext, input: TInsert) => TInsert | Promise<TInsert>): <TResult>({
+  ctx,
+  input,
+  next
+}: MiddlewareParams<TContext, TInsert, TResult>) => Promise<TResult>;
+/**
+ * 创建 update 操作的 after middleware
+ */
+declare function afterUpdate<TContext, TSelect>(fn: (ctx: TContext, updated: TSelect) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TSelect>;
+}) => Promise<TSelect>;
+/**
+ * 创建 delete 操作的 after middleware
+ */
+declare function afterDelete<TContext, TSelect>(fn: (ctx: TContext, deleted: TSelect) => void | Promise<void>): ({
+  ctx,
+  next
+}: {
+  ctx: TContext;
+  next: () => Promise<TSelect>;
+}) => Promise<TSelect>;
+//#endregion
 //#region src/routers/index.d.ts
 declare const appRouter: _trpc_server5.TRPCBuiltRouter<{
   ctx: Context;
@@ -207,4 +496,4 @@ declare const appRouter: _trpc_server5.TRPCBuiltRouter<{
 }, _trpc_server5.TRPCDecorateCreateRouterOptions<{}>>;
 type AppRouter = typeof appRouter;
 //#endregion
-export { type AnyProcedure, type AppRouter, type CrudOperation, type CrudRouterConfig, type DeclarativeConfig, type FactoryConfig, type ProceduresConfig, type SoftDeleteConfig, type SoftDeleteOption, type WriteOperation, appRouter, createCrudRouter, publicProcedure, router };
+export { type AnyProcedure, type AppRouter, type CrudMiddleware, type CrudOperation, type CrudRouterConfig, type DeclarativeConfig, type FactoryConfig, type ListInput, type ListResult, type ProceduresConfig, type SoftDeleteConfig, type SoftDeleteOption, type WriteOperation, afterCreate, afterDelete, afterList, afterMiddleware, afterMiddlewareTransform, afterUpdate, appRouter, beforeCreate, beforeList, beforeMiddleware, composeMiddleware, createCrudRouter, publicProcedure, router };