@wordrhyme/auto-crud-server 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -1,7 +1,9 @@
 import { z } from "zod";
+import { SQL } from "drizzle-orm";
 import * as _trpc_server2 from "@trpc/server";
 import superjson from "superjson";
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
+import * as node_modules__trpc_server_dist_unstable_core_do_not_import_d_CjQPvBRI_mjs0 from "node_modules/@trpc/server/dist/unstable-core-do-not-import.d-CjQPvBRI.mjs";
 import { PgTable } from "drizzle-orm/pg-core";
 
 //#region src/trpc.d.ts
@@ -12,14 +14,6 @@ import { PgTable } from "drizzle-orm/pg-core";
 interface Context {
   db: PostgresJsDatabase<Record<string, never>>;
 }
-declare const t: _trpc_server2.TRPCRootObject<Context, object, {
-  transformer: typeof superjson;
-}, {
-  ctx: Context;
-  meta: object;
-  errorShape: _trpc_server2.TRPCDefaultErrorShape;
-  transformer: true;
-}>;
 declare const router: _trpc_server2.TRPCRouterBuilder<{
   ctx: Context;
   meta: object;
@@ -27,138 +21,311 @@ declare const router: _trpc_server2.TRPCRouterBuilder<{
   transformer: true;
 }>;
 declare const publicProcedure: _trpc_server2.TRPCProcedureBuilder<Context, object, object, _trpc_server2.TRPCUnsetMarker, _trpc_server2.TRPCUnsetMarker, _trpc_server2.TRPCUnsetMarker, _trpc_server2.TRPCUnsetMarker, false>;
-type AnyProcedure = typeof t.procedure;
 //#endregion
-//#region src/routers/_factory.d.ts
+//#region src/types/config.d.ts
+type CrudOperation = "list" | "get" | "create" | "update" | "delete" | "deleteMany" | "updateMany";
+type WriteOperation = "create" | "update";
+type AnyProcedure = any;
+interface SoftDeleteConfig {
+  /** 软删除标记列名 */
+  column: string;
+  /**
+   * 删除时设置的值
+   * - 默认: () => new Date()
+   * - 可自定义为其他值，如 true（用于 isDeleted 布尔字段）
+   */
+  value?: () => unknown;
+}
 /**
- * 授权回调类型
- * 返回 true 允许操作，返回 false 或抛出错误拒绝操作
+ * 软删除配置类型
+ * - string: 列名（使用默认值 new Date()）
+ * - boolean: true 表示使用默认列名 'deletedAt'
+ * - SoftDeleteConfig: 完整配置
  */
-type AuthorizeCallback = (ctx: {
-  operation: "list" | "get" | "create" | "update" | "delete" | "deleteMany" | "updateMany";
-  input?: unknown;
-}) => boolean | Promise<boolean>;
+type SoftDeleteOption = string | boolean | SoftDeleteConfig;
 /**
- * CRUD Router 配置
+ * 列表查询输入类型
  */
-interface CrudRouterConfig {
+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;
+}
+/**
+ * CRUD 生命周期钩子
+ *
+ * @example
+ * hooks: {
+ *   beforeCreate: async (ctx, data) => {
+ *     // 修改数据
+ *     return { ...data, slug: slugify(data.title) };
+ *   },
+ *   afterCreate: async (ctx, created) => {
+ *     // 发送通知
+ *     await sendNotification(created);
+ *   },
+ * }
+ */
+interface CrudHooks<TContext = unknown> {
+  /**
+   * 列表查询前
+   * 可修改查询参数
+   */
+  beforeList?: (ctx: TContext, input: ListInput) => ListInput | void | Promise<ListInput | void>;
+  /**
+   * 列表查询后
+   * 可修改返回结果
+   */
+  afterList?: <TSelect>(ctx: TContext, result: ListResult<TSelect>) => ListResult<TSelect> | void | Promise<ListResult<TSelect> | void>;
+  /**
+   * 单条查询前
+   */
+  beforeGet?: (ctx: TContext, id: string) => void | Promise<void>;
+  /**
+   * 单条查询后
+   * 可修改返回结果
+   */
+  afterGet?: <TSelect>(ctx: TContext, result: TSelect | null) => TSelect | null | void | Promise<TSelect | null | void>;
+  /**
+   * 创建前
+   * 可修改输入数据，返回新数据或抛出错误阻止创建
+   */
+  beforeCreate?: <TInsert>(ctx: TContext, data: TInsert) => TInsert | void | Promise<TInsert | void>;
+  /**
+   * 创建后
+   * 用于副作用（日志、通知、同步等）
+   */
+  afterCreate?: <TSelect>(ctx: TContext, created: TSelect) => void | Promise<void>;
+  /**
+   * 更新前
+   * 可修改输入数据，existing 为更新前的记录
+   */
+  beforeUpdate?: <TUpdate, TSelect>(ctx: TContext, id: string, data: TUpdate, existing: TSelect) => TUpdate | void | Promise<TUpdate | void>;
+  /**
+   * 更新后
+   */
+  afterUpdate?: <TSelect>(ctx: TContext, updated: TSelect) => void | Promise<void>;
+  /**
+   * 删除前
+   * existing 为删除前的记录，可抛出错误阻止删除
+   */
+  beforeDelete?: <TSelect>(ctx: TContext, id: string, existing: TSelect) => void | Promise<void>;
+  /**
+   * 删除后
+   */
+  afterDelete?: <TSelect>(ctx: TContext, deleted: TSelect) => void | Promise<void>;
+  /**
+   * 批量删除前
+   */
+  beforeDeleteMany?: (ctx: TContext, ids: string[]) => void | Promise<void>;
+  /**
+   * 批量删除后
+   */
+  afterDeleteMany?: (ctx: TContext, result: {
+    deleted: number;
+  }) => void | Promise<void>;
+  /**
+   * 批量更新前
+   * 可修改输入数据
+   */
+  beforeUpdateMany?: <TUpdate>(ctx: TContext, ids: string[], data: TUpdate) => TUpdate | void | Promise<TUpdate | void>;
+  /**
+   * 批量更新后
+   */
+  afterUpdateMany?: (ctx: TContext, result: {
+    updated: number;
+  }) => void | Promise<void>;
+}
+interface CrudRouterConfigBase<TContext = unknown> {
+  /** Drizzle 表定义 */
   table: PgTable;
-  selectSchema: z.ZodType;
+  /** 查询返回 Schema */
+  selectSchema?: z.ZodType;
+  /** 创建输入 Schema */
   insertSchema: z.ZodType;
+  /** 更新输入 Schema */
   updateSchema: z.ZodType;
+  /** ID 字段名，默认 "id" */
   idField?: string;
-  /**
-   * 可过滤的列白名单
-   * 未指定时默认允许所有列（不安全，仅用于开发）
-   */
+  /** 可过滤的列白名单 */
   filterableColumns?: string[];
+  /** 可排序的列白名单 */
+  sortableColumns?: string[];
+  /** 批量操作的最大数量限制，默认 100 */
+  maxBatchSize?: number;
   /**
-   * 可排序的列白名单
-   * 未指定时默认允许所有列（不安全，仅用于开发）
+   * 软删除配置
+   * 开启后：
+   * - delete 操作 → UPDATE ... SET {column} = {value}
+   * - deleteMany 操作 → UPDATE ... SET {column} = {value} WHERE id IN (...)
+   * - list/get 操作 → 自动添加 WHERE {column} IS NULL
+   *
+   * @example
+   * // 使用默认列名 'deletedAt'
+   * softDelete: true
+   *
+   * // 指定列名
+   * softDelete: 'deletedAt'
+   *
+   * // 完整配置（用于布尔字段）
+   * softDelete: { column: 'isDeleted', value: () => true }
    */
-  sortableColumns?: string[];
+  softDelete?: SoftDeleteOption;
   /**
-   * 批量操作的最大数量限制
-   * 默认: 100
+   * 生命周期钩子
+   * 在 CRUD 操作前后注入自定义逻辑
+   *
+   * @example
+   * hooks: {
+   *   beforeCreate: async (ctx, data) => {
+   *     return { ...data, slug: slugify(data.title) };
+   *   },
+   *   afterCreate: async (ctx, created) => {
+   *     await sendNotification(created);
+   *   },
+   * }
    */
-  maxBatchSize?: number;
+  hooks?: CrudHooks<TContext>;
+}
+interface DeclarativeConfig<TContext = unknown> extends CrudRouterConfigBase<TContext> {
+  mode?: "declarative";
   /**
-   * 自定义 procedure（用于注入授权中间件）
-   * 默认使用 publicProcedure
+   * 基础 procedure（认证）
+   * 所有操作共用，除非被 guard 拦截
    */
   procedure?: AnyProcedure;
   /**
-   * 授权回调（简单场景下的快捷授权方式）
-   * 如果需要更复杂的授权逻辑，建议使用 procedure 注入中间件
+   * 操作级守卫（RBAC）
+   * 在 scope 之前执行，快速拒绝无权限请求
+   *
+   * @example
+   * guard: (ctx, op) => op === 'delete' ? ctx.user.role === 'admin' : true
+   */
+  guard?: (ctx: TContext, operation: CrudOperation) => boolean | Promise<boolean>;
+  /**
+   * 行级过滤（RLS）
+   * 返回 SQL 条件，自动注入到 WHERE 子句
+   *
+   * @example
+   * scope: (ctx, table) => eq(table.tenantId, ctx.user.tenantId)
+   */
+  scope?: (ctx: TContext, table: PgTable, operation: CrudOperation) => SQL | undefined;
+  /**
+   * 强制注入字段（写入时）
+   * 返回的字段会强制覆盖用户输入（防止伪造）
+   *
+   * @example
+   * inject: (ctx) => ({ tenantId: ctx.user.tenantId, createdBy: ctx.user.id })
    */
-  authorize?: AuthorizeCallback;
+  inject?: (ctx: TContext, operation: WriteOperation) => Record<string, unknown>;
+  /**
+   * 资源级检查（ABAC）
+   * 在 get/update/delete 时，预取资源后调用
+   *
+   * @example
+   * authorize: (ctx, resource, op) => resource.ownerId === ctx.user.id
+   */
+  authorize?: (ctx: TContext, resource: Record<string, unknown>, operation: CrudOperation) => boolean | Promise<boolean>;
 }
-/**
- * 创建通用 CRUD Router
- */
-declare function createCrudRouter(config: CrudRouterConfig): _trpc_server2.TRPCBuiltRouter<{
+interface FactoryConfig<TContext = unknown> extends CrudRouterConfigBase<TContext> {
+  mode: "factory";
+  /**
+   * Procedure 工厂函数
+   * 根据操作类型返回对应的 procedure
+   *
+   * @example
+   * procedureFactory: (op) => {
+   *   if (['list', 'get'].includes(op)) return publicProcedure;
+   *   return protectedProcedure.meta({ permission: { action: op, subject: 'Task' } });
+   * }
+   */
+  procedureFactory: (operation: CrudOperation) => AnyProcedure;
+  /**
+   * 强制注入字段（可选）
+   * 如果 DB 层已处理则不需要
+   */
+  inject?: (ctx: TContext, operation: WriteOperation) => Record<string, unknown>;
+}
+interface ProceduresConfig<TContext = unknown> extends CrudRouterConfigBase<TContext> {
+  mode: "procedures";
+  /**
+   * 按操作指定不同的 procedure
+   *
+   * @example
+   * procedures: {
+   *   list: publicProcedure,
+   *   get: publicProcedure,
+   *   create: editorProcedure,
+   *   update: editorProcedure,
+   *   delete: adminProcedure,
+   * }
+   */
+  procedures: Partial<Record<CrudOperation, AnyProcedure>>;
+  /**
+   * 默认 procedure（未指定操作时使用）
+   */
+  defaultProcedure?: AnyProcedure;
+  /**
+   * 强制注入字段（可选）
+   */
+  inject?: (ctx: TContext, operation: WriteOperation) => Record<string, unknown>;
+}
+type CrudRouterConfig<TContext = unknown> = DeclarativeConfig<TContext> | FactoryConfig<TContext> | ProceduresConfig<TContext>;
+//#endregion
+//#region src/routers/_factory.d.ts
+declare function createCrudRouter<TContext = unknown>(config: CrudRouterConfig<TContext>): node_modules__trpc_server_dist_unstable_core_do_not_import_d_CjQPvBRI_mjs0.Router<{
   ctx: Context;
   meta: object;
   errorShape: _trpc_server2.TRPCDefaultErrorShape;
   transformer: true;
 }, _trpc_server2.TRPCDecorateCreateRouterOptions<{
-  list: _trpc_server2.TRPCQueryProcedure<{
-    input: {
-      page?: number | undefined;
-      perPage?: number | undefined;
-      sort?: {
-        id: string;
-        desc: boolean;
-      }[] | undefined;
-      filters?: {
-        id: string;
-        value: string | string[];
-        variant: "number" | "boolean" | "date" | "text" | "range" | "dateRange" | "select" | "multiSelect";
-        operator: "iLike" | "notILike" | "eq" | "ne" | "isEmpty" | "isNotEmpty" | "lt" | "lte" | "gt" | "gte" | "isBetween" | "isRelativeToToday" | "inArray" | "notInArray";
-        filterId: string;
-      }[] | undefined;
-      joinOperator?: "and" | "or" | undefined;
-    };
-    output: {
-      data: {
-        [x: string]: unknown;
-      }[];
-      total: number;
-      page: number;
-      perPage: number;
-      pageCount: number;
-    };
-    meta: object;
-  }>;
-  getById: _trpc_server2.TRPCQueryProcedure<{
-    input: string;
-    output: {
-      [x: string]: unknown;
-    } | null;
-    meta: object;
-  }>;
-  create: _trpc_server2.TRPCMutationProcedure<{
-    input: unknown;
-    output: {
-      [x: string]: unknown;
-    } | undefined;
-    meta: object;
-  }>;
-  update: _trpc_server2.TRPCMutationProcedure<{
-    input: {
-      id: string;
-      data: unknown;
-    };
-    output: {
-      [x: string]: unknown;
-    } | undefined;
-    meta: object;
-  }>;
-  delete: _trpc_server2.TRPCMutationProcedure<{
-    input: string;
-    output: {
-      [x: string]: unknown;
-    } | undefined;
-    meta: object;
-  }>;
-  deleteMany: _trpc_server2.TRPCMutationProcedure<{
-    input: string[];
-    output: {
-      deleted: number;
-    };
-    meta: object;
-  }>;
-  updateMany: _trpc_server2.TRPCMutationProcedure<{
-    input: {
-      ids: string[];
-      data: unknown;
-    };
-    output: {
-      updated: number;
-    };
-    meta: object;
-  }>;
-}>>;
+  list: any;
+  getById: any;
+  create: any;
+  update: any;
+  delete: any;
+  deleteMany: any;
+  updateMany: any;
+}>> & _trpc_server2.TRPCDecorateCreateRouterOptions<{
+  list: any;
+  getById: any;
+  create: any;
+  update: any;
+  delete: any;
+  deleteMany: any;
+  updateMany: any;
+}> & {
+  procedures: {
+    list: any;
+    getById: any;
+    create: any;
+    update: any;
+    delete: any;
+    deleteMany: any;
+    updateMany: any;
+  };
+};
 //#endregion
 //#region src/routers/index.d.ts
 declare const appRouter: _trpc_server2.TRPCBuiltRouter<{
@@ -169,4 +336,4 @@ declare const appRouter: _trpc_server2.TRPCBuiltRouter<{
 }, _trpc_server2.TRPCDecorateCreateRouterOptions<{}>>;
 type AppRouter = typeof appRouter;
 //#endregion
-export { type AnyProcedure, type AppRouter, type AuthorizeCallback, type CrudRouterConfig, appRouter, createCrudRouter, publicProcedure, router };
+export { type AnyProcedure, type AppRouter, type CrudHooks, type CrudOperation, type CrudRouterConfig, type DeclarativeConfig, type FactoryConfig, type ListInput, type ListResult, type ProceduresConfig, type SoftDeleteConfig, type SoftDeleteOption, type WriteOperation, appRouter, createCrudRouter, publicProcedure, router };