@wordrhyme/auto-crud-server 0.8.0 → 0.10.0

package/README.md

@@ -75,27 +75,32 @@ export const tasks = pgTable("tasks", {
 // src/server/routers/tasks.ts
 import { createCrudRouter } from "@wordrhyme/auto-crud-server";
 import { tasks } from "@/db/schema";
+
+// 🚀 零配置！一行代码生成完整 CRUD 路由
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // Schema 自动从 table 派生，排除 id, createdAt, updatedAt
+});
+```
+
+**或者，显式传入 Schema：**
+
+```typescript
+import { createCrudRouter } from "@wordrhyme/auto-crud-server";
+import { tasks } from "@/db/schema";
 import { createSelectSchema } from "drizzle-zod";
 
 // 从 Drizzle Schema 自动生成 Zod Schema
-const selectTaskSchema = createSelectSchema(tasks);
-
-// 创建输入 Schema
-const insertTaskSchema = selectTaskSchema.omit({
+const taskSchema = createSelectSchema(tasks).omit({
   id: true,
   createdAt: true,
   updatedAt: true,
 });
 
-const updateTaskSchema = insertTaskSchema.partial();
-
-// 🚀 一行代码生成完整 CRUD 路由
 export const tasksRouter = createCrudRouter({
   table: tasks,
-  selectSchema: selectTaskSchema,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
-  idField: "id",  // 可选，默认为 "id"
+  schema: taskSchema,  // 主 Schema（用于 create/upsert）
+  // updateSchema 自动派生为 schema.partial()
 });
 ```
 
@@ -440,14 +445,57 @@ await trpc.tasks.list({
 
 ```typescript
 interface CrudRouterConfig<TTable, TSelect, TInsert, TUpdate> {
+  // ========== 必填 ==========
   table: TTable;                    // Drizzle 表定义
-  selectSchema: z.ZodType<TSelect>; // 查询返回 Schema
-  insertSchema: z.ZodType<TInsert>; // 创建输入 Schema
-  updateSchema: z.ZodType<TUpdate>; // 更新输入 Schema
+
+  // ========== Schema 配置（可选） ==========
+  schema?: z.ZodType<TInsert>;      // 主 Schema（用于 create/upsert）
+  updateSchema?: z.ZodType<TUpdate>;// 更新 Schema（覆盖自动派生）
+  selectSchema?: z.ZodType<TSelect>;// 查询返回 Schema
+
+  // ========== 其他配置 ==========
   idField?: string;                 // ID 字段名，默认 "id"
+  omitFields?: string[];            // 自动派生时排除的字段
+                                    // 默认 ["id", "createdAt", "updatedAt"]
 }
 ```
 
+#### Schema 派生规则
+
+| 配置 | 派生行为 |
+|-----|---------|
+| 无 `schema` | 从 `table` 自动派生，排除 `omitFields` |
+| 无 `updateSchema` | 从 `schema.partial().refine(nonEmpty)` 派生 |
+| 无 `selectSchema` | 若有 `schema` 则使用它，否则从 `table` 派生 |
+
+#### 使用示例
+
+```typescript
+// 1. 零配置 - 全部自动派生
+const tasksRouter = createCrudRouter({
+  table: tasks,
+});
+
+// 2. 传入 schema，updateSchema 自动派生
+const postsRouter = createCrudRouter({
+  table: posts,
+  schema: postSchema,
+});
+
+// 3. 传入 schema + 自定义 updateSchema
+const usersRouter = createCrudRouter({
+  table: users,
+  schema: userSchema,
+  updateSchema: customUpdateSchema,
+});
+
+// 4. 自定义排除字段
+const ordersRouter = createCrudRouter({
+  table: orders,
+  omitFields: ["id", "createdAt", "updatedAt", "internalCode"],
+});
+```
+
 #### 返回值
 
 ```typescript
@@ -459,95 +507,94 @@ interface CrudRouterConfig<TTable, TSelect, TInsert, TUpdate> {
   // 可 spread 的 procedures 对象（用于扩展自定义路由）
   procedures: {
     list: Procedure<ListInput, ListOutput>,
-    getById: Procedure<string, TSelect>,
+    get: Procedure<string, TSelect>,
     create: Procedure<TInsert, TSelect>,
     update: Procedure<{ id: string, data: TUpdate }, TSelect>,
     delete: Procedure<string, TSelect>,
     deleteMany: Procedure<string[], { deleted: number }>,
     updateMany: Procedure<{ ids: string[], data: TUpdate }, { updated: number }>,
+    upsert: Procedure<TInsert, { data: TSelect, isNew: boolean }>,
   }
 }
 ```
 
-#### 完整示例
+---
+
+## 🔐 权限控制
+
+### 使用 procedure 配置
 
 ```typescript
 import { createCrudRouter } from "@wordrhyme/auto-crud-server";
-import { users } from "@/db/schema";
-import { createSelectSchema } from "drizzle-zod";
-import { z } from "zod";
+import { protectedProcedure, adminProcedure, publicProcedure } from "../trpc";
 
-const selectUserSchema = createSelectSchema(users);
-
-const insertUserSchema = selectUserSchema.omit({
-  id: true,
-  createdAt: true,
-  updatedAt: true,
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // 按操作指定不同的 procedure
+  procedure: {
+    list: publicProcedure,      // 公开读
+    get: publicProcedure,
+    create: protectedProcedure, // 需要登录
+    update: protectedProcedure,
+    delete: adminProcedure,     // 需要管理员
+    default: protectedProcedure,
+  },
 });
+```
 
-const updateUserSchema = insertUserSchema.partial();
+### 使用 guard（操作级守卫）
 
-export const usersRouter = createCrudRouter({
-  table: users,
-  selectSchema: selectUserSchema,
-  insertSchema: insertUserSchema,
-  updateSchema: updateUserSchema,
-  idField: "id",
+```typescript
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  guard: (ctx, operation) => {
+    // 删除操作需要管理员权限
+    if (operation === "delete") {
+      return ctx.user.role === "admin";
+    }
+    // 其他操作需要登录
+    return !!ctx.user;
+  },
 });
 ```
 
----
-
-## 🔐 权限控制
-
-### 使用 tRPC Middleware
+### 使用 scope（行级过滤 RLS）
 
 ```typescript
-import { initTRPC, TRPCError } from "@trpc/server";
-
-const t = initTRPC.context<Context>().create();
+import { eq } from "drizzle-orm";
 
-// 创建受保护的 procedure
-const protectedProcedure = t.procedure.use(async ({ ctx, next }) => {
-  if (!ctx.user) {
-    throw new TRPCError({ code: "UNAUTHORIZED" });
-  }
-  return next({ ctx: { ...ctx, user: ctx.user } });
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // 自动注入到所有查询的 WHERE 子句
+  scope: (ctx, table, operation) => {
+    return eq(table.tenantId, ctx.user.tenantId);
+  },
 });
+```
+
+### 使用 authorize（资源级检查 ABAC）
 
-// 在 createCrudRouter 中使用
+```typescript
 export const tasksRouter = createCrudRouter({
   table: tasks,
-  selectSchema: selectTaskSchema,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
-  // 注意：当前版本不支持直接传入 procedure
-  // 需要在路由层面添加权限控制
+  // 在 get/update/delete 时，预取资源后调用
+  authorize: (ctx, resource, operation) => {
+    return resource.ownerId === ctx.user.id;
+  },
 });
-
-// 包装路由添加权限
-export const protectedTasksRouter = {
-  list: protectedProcedure.query(async ({ input, ctx }) => {
-    return tasksRouter.list(input, ctx);
-  }),
-  // ... 其他路由
-};
 ```
 
-### 行级权限控制
+### 使用 inject（强制注入字段）
 
 ```typescript
-// 在 createContext 中添加用户信息
-export const createContext = async ({ req }: { req: Request }) => {
-  const user = await getUserFromRequest(req);
-  return { db, user };
-};
-
-// 在查询中添加过滤条件
-const result = await db
-  .select()
-  .from(tasks)
-  .where(eq(tasks.userId, ctx.user.id));  // 只查询当前用户的任务
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // 写入时强制覆盖字段（防止伪造）
+  inject: (ctx, operation) => ({
+    tenantId: ctx.user.tenantId,
+    ...(operation === "create" ? { createdBy: ctx.user.id } : { updatedBy: ctx.user.id }),
+  }),
+});
 ```
 
 ---
@@ -566,9 +613,6 @@ import { z } from "zod";
 // 创建基础 CRUD
 const tasksCrud = createCrudRouter({
   table: tasks,
-  selectSchema: selectTaskSchema,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
 });
 
 // 使用 .procedures spread 并添加自定义路由
@@ -604,9 +648,6 @@ export const tasksRouter = router({
 ```typescript
 const tasksCrud = createCrudRouter({
   table: tasks,
-  selectSchema: selectTaskSchema,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
 });
 
 // 直接嵌套到 appRouter
@@ -619,7 +660,7 @@ export const appRouter = router({
 
 ```typescript
 // 覆盖 list 路由，添加自定义过滤逻辑
-const tasksCrud = createCrudRouter({ ... });
+const tasksCrud = createCrudRouter({ table: tasks });
 
 export const tasksRouter = router({
   ...tasksCrud.procedures,
@@ -655,8 +696,6 @@ import { createCrudRouter } from "@wordrhyme/auto-crud-server";
 
 const tasksRouter = createCrudRouter({
   table: tasks,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
 
   // 中间件：完全控制操作流程
   middleware: {
@@ -711,8 +750,6 @@ import {
 
 const tasksRouter = createCrudRouter({
   table: tasks,
-  insertSchema: insertTaskSchema,
-  updateSchema: updateTaskSchema,
 
   middleware: {
     // 简单副作用：只在操作后执行
@@ -811,24 +848,53 @@ app.listen(3000);
 ```typescript
 export const usersRouter = createCrudRouter({
   table: users,
-  selectSchema: selectUserSchema,
-  insertSchema: insertUserSchema,
-  updateSchema: updateUserSchema,
   idField: "userId",  // 使用自定义 ID 字段
 });
 ```
 
-### 自定义过滤器配置
+### 自定义排除字段
 
 ```typescript
-// src/config/data-table.ts
-export const filterVariants = {
-  text: ["eq", "ne", "like", "notLike"],
-  number: ["eq", "ne", "gt", "gte", "lt", "lte", "between"],
-  select: ["eq", "ne", "in", "notIn"],
-  date: ["eq", "ne", "gt", "gte", "lt", "lte", "between"],
-  boolean: ["eq"],
-};
+export const ordersRouter = createCrudRouter({
+  table: orders,
+  // 自动派生 schema 时排除这些字段
+  omitFields: ["id", "createdAt", "updatedAt", "internalCode"],
+});
+```
+
+### 软删除
+
+```typescript
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  // 方式 1：使用默认列名 'deletedAt'
+  softDelete: true,
+
+  // 方式 2：指定列名
+  softDelete: "deletedAt",
+
+  // 方式 3：完整配置（用于布尔字段）
+  softDelete: { column: "isDeleted", value: () => true },
+});
+```
+
+### 批量操作限制
+
+```typescript
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  maxBatchSize: 50,  // 默认 100
+});
+```
+
+### 列白名单
+
+```typescript
+export const tasksRouter = createCrudRouter({
+  table: tasks,
+  filterableColumns: ["title", "status", "priority"],  // 只允许这些列过滤
+  sortableColumns: ["title", "createdAt", "priority"], // 只允许这些列排序
+});
 ```
 
 ---

package/dist/index.cjs

@@ -25,6 +25,8 @@ let zod = require("zod");
 zod = __toESM(zod);
 let drizzle_orm = require("drizzle-orm");
 drizzle_orm = __toESM(drizzle_orm);
+let drizzle_zod = require("drizzle-zod");
+drizzle_zod = __toESM(drizzle_zod);
 let __trpc_server = require("@trpc/server");
 __trpc_server = __toESM(__trpc_server);
 let superjson = require("superjson");
@@ -399,6 +401,26 @@ const dataTableConfig = {
 	joinOperators: ["and", "or"]
 };
 
+//#endregion
+//#region src/lib/schema-utils.ts
+/**
+* 检查是否为 ZodObject 类型
+* 兼容 Zod v3 和 v4
+*
+* 实现策略：检查 schema 是否具有 ZodObject 特有的 .shape 属性
+* 这种方式比检查内部 _def 属性更稳定，因为不依赖 Zod 的内部实现细节
+*/
+function isZodObject(schema) {
+	return schema !== null && typeof schema === "object" && "shape" in schema && typeof schema.shape === "object" && schema.shape !== null;
+}
+/**
+* 非空对象验证器
+* 用于 updateSchema 的 refine，防止空更新
+*/
+function nonEmpty(value) {
+	return Object.keys(value).length > 0;
+}
+
 //#endregion
 //#region src/routers/_factory.ts
 function resolveSoftDelete(option) {
@@ -434,6 +456,9 @@ function isProcedureMap(config) {
 			"deleteMany",
 			"updateMany",
 			"upsert",
+			"export",
+			"import",
+			"createMany",
 			"default"
 		];
 		return keys.some((k) => validKeys.includes(k));
@@ -485,20 +510,63 @@ const listInputSchema = zod.z.object({
 	filters: zod.z.array(filterItemSchema).optional(),
 	joinOperator: zod.z.enum(["and", "or"]).default("and")
 });
+const exportInputSchema = zod.z.object({
+	sort: zod.z.array(zod.z.object({
+		id: zod.z.string(),
+		desc: zod.z.boolean()
+	})).optional(),
+	filters: zod.z.array(filterItemSchema).optional(),
+	joinOperator: zod.z.enum(["and", "or"]).default("and"),
+	limit: zod.z.number().min(1).optional()
+});
+const importInputSchema = zod.z.object({
+	rows: zod.z.array(zod.z.unknown()).min(1).max(1e3),
+	onConflict: zod.z.enum([
+		"skip",
+		"upsert",
+		"error"
+	]).default("skip")
+});
+const DEFAULT_OMIT_FIELDS = [
+	"id",
+	"createdAt",
+	"updatedAt"
+];
+/**
+* 解析并派生 Schema
+* - 优先使用显式传入的 Schema
+* - 否则从 Drizzle table 自动派生
+*/
+function resolveSchemas(config) {
+	const { table, omitFields = DEFAULT_OMIT_FIELDS } = config;
+	let schema;
+	if (config.schema) {
+		if (!isZodObject(config.schema)) throw new Error("[createCrudRouter] schema must be a ZodObject (not ZodEffects or other types). If you're using .refine() or .transform(), please remove them from schema.");
+		schema = config.schema;
+	} else {
+		const rawSchema = (0, drizzle_zod.createInsertSchema)(table);
+		if (!isZodObject(rawSchema)) throw new Error("[createCrudRouter] drizzle-zod returned non-ZodObject schema. This may be due to table refinements. Please provide schema explicitly.");
+		const omitConfig = Object.fromEntries(omitFields.map((f) => [f, true]));
+		schema = rawSchema.omit(omitConfig);
+	}
+	let selectSchema;
+	if (config.selectSchema) selectSchema = config.selectSchema;
+	else if (config.schema) selectSchema = schema;
+	else selectSchema = (0, drizzle_zod.createSelectSchema)(table);
+	const updateSchema = config.updateSchema ?? schema.partial().refine(nonEmpty, { message: "Update payload cannot be empty. At least one field is required." });
+	return {
+		selectSchema,
+		schema,
+		updateSchema
+	};
+}
 function validateColumn(columnId, allowedColumns) {
 	if (!allowedColumns || allowedColumns.length === 0) return true;
 	return allowedColumns.includes(columnId);
 }
-/**
-* 创建 CRUD Router
-*
-* @typeParam TContext - 上下文类型（包含 db）
-* @typeParam TSelect - 查询返回类型（从 selectSchema 或 insertSchema 推断）
-* @typeParam TInsert - 创建输入类型（从 insertSchema 推断）
-* @typeParam TUpdate - 更新输入类型（从 updateSchema 推断）
-*/
 function createCrudRouter(config) {
-	const { table, insertSchema, updateSchema, idField = "id", filterableColumns, sortableColumns, maxBatchSize = 100, softDelete: softDeleteOption, middleware = {} } = config;
+	const { table, idField = "id", filterableColumns, sortableColumns, maxBatchSize = 100, maxExportSize = 5e3, softDelete: softDeleteOption, middleware = {} } = config;
+	const { schema, updateSchema } = resolveSchemas(config);
 	const resolved = resolveConfig(config);
 	const softDelete = resolveSoftDelete(softDeleteOption);
 	const m = middleware;
@@ -596,7 +664,7 @@ function createCrudRouter(config) {
 			});
 			return doGet();
 		}),
-		create: resolved.procedureFactory("create").input(insertSchema).mutation(async ({ ctx, input }) => {
+		create: resolved.procedureFactory("create").input(schema).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "create");
 			const doCreate = async (inputData) => {
 				const injectData = resolved.getInject(ctx, "create");
@@ -703,7 +771,7 @@ function createCrudRouter(config) {
 			});
 			return doUpdateMany(input.data);
 		}),
-		upsert: resolved.procedureFactory("upsert").input(insertSchema).mutation(async ({ ctx, input }) => {
+		upsert: resolved.procedureFactory("upsert").input(schema).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "upsert");
 			const doUpsert = async (inputData) => {
 				const inputId = inputData[idField];
@@ -739,6 +807,131 @@ function createCrudRouter(config) {
 				next: async (modifiedInput) => doUpsert(modifiedInput ?? input)
 			});
 			return doUpsert(input);
+		}),
+		export: resolved.procedureFactory("export").input(exportInputSchema).query(async ({ ctx, input }) => {
+			await withGuard(ctx, "export");
+			const doExport = async (exportInput$1) => {
+				const effectiveLimit = Math.min(Math.max(exportInput$1.limit ?? maxExportSize, 1), maxExportSize);
+				const validatedFilters = exportInput$1.filters?.filter((filter) => validateColumn(filter.id, filterableColumns));
+				const where = buildWhere(ctx, "export", validatedFilters?.length ? filterColumns({
+					table,
+					filters: validatedFilters,
+					joinOperator: exportInput$1.joinOperator ?? "and"
+				}) : void 0);
+				let query = ctx.db.select().from(table).$dynamic();
+				if (where) query = query.where(where);
+				if (exportInput$1.sort?.length) {
+					const sortField = exportInput$1.sort[0];
+					if (sortField && validateColumn(sortField.id, sortableColumns)) {
+						const column = table[sortField.id];
+						if (column) query = query.orderBy(sortField.desc ? (0, drizzle_orm.desc)(column) : (0, drizzle_orm.asc)(column));
+					}
+				}
+				const data = await query.limit(effectiveLimit);
+				let countQuery = ctx.db.select({ count: drizzle_orm.sql`count(*)::int` }).from(table).$dynamic();
+				if (where) countQuery = countQuery.where(where);
+				const total = (await countQuery)[0]?.count ?? 0;
+				return {
+					data,
+					total,
+					hasMore: total > data.length
+				};
+			};
+			const exportInput = input;
+			if (m.export) return m.export({
+				ctx,
+				input: exportInput,
+				next: async (modifiedInput) => doExport(modifiedInput ?? exportInput)
+			});
+			return doExport(exportInput);
+		}),
+		createMany: resolved.procedureFactory("createMany").input(zod.z.array(schema).min(1).max(maxBatchSize)).mutation(async ({ ctx, input }) => {
+			await withGuard(ctx, "createMany");
+			const doCreateMany = async (items) => {
+				const injectData = resolved.getInject(ctx, "create");
+				const values = items.map((item) => ({
+					...item,
+					...injectData
+				}));
+				const created = await ctx.db.insert(table).values(values).onConflictDoNothing().returning();
+				return {
+					created,
+					count: created.length
+				};
+			};
+			if (m.createMany) return m.createMany({
+				ctx,
+				input,
+				next: async (modifiedInput) => doCreateMany(modifiedInput ?? input)
+			});
+			return doCreateMany(input);
+		}),
+		import: resolved.procedureFactory("import").input(importInputSchema).mutation(async ({ ctx, input }) => {
+			await withGuard(ctx, "import");
+			const doImport = async (importData$1) => {
+				const validRows = [];
+				const failed = [];
+				for (let i = 0; i < importData$1.rows.length; i++) {
+					const row = importData$1.rows[i];
+					const result = schema.safeParse(row);
+					if (result.success) validRows.push(result.data);
+					else {
+						const errors = result.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`);
+						failed.push({
+							row: i,
+							errors
+						});
+						if (importData$1.onConflict === "error") return {
+							success: 0,
+							updated: 0,
+							skipped: 0,
+							failed
+						};
+					}
+				}
+				if (validRows.length === 0) return {
+					success: 0,
+					updated: 0,
+					skipped: 0,
+					failed
+				};
+				const injectData = resolved.getInject(ctx, "create");
+				const values = validRows.map((row) => ({
+					...row,
+					...injectData
+				}));
+				let insertedCount = 0;
+				let updatedCount = 0;
+				if (importData$1.onConflict === "upsert") {
+					const existingCount = (await ctx.db.select({ id: getIdColumn() }).from(table).where((0, drizzle_orm.inArray)(getIdColumn(), values.map((v) => v[idField]).filter(Boolean)))).length;
+					const updateFields = Object.keys(validRows[0]);
+					const setClause = { ...resolved.getInject(ctx, "update") };
+					for (const key of updateFields) setClause[key] = drizzle_orm.sql.raw(`excluded."${key}"`);
+					const results = await ctx.db.insert(table).values(values).onConflictDoUpdate({
+						target: getIdColumn(),
+						set: setClause
+					}).returning({ id: getIdColumn() });
+					updatedCount = Math.min(existingCount, results.length);
+					insertedCount = results.length - updatedCount;
+				} else {
+					insertedCount = (await ctx.db.insert(table).values(values).onConflictDoNothing().returning({ id: getIdColumn() })).length;
+					updatedCount = 0;
+				}
+				const skipped = validRows.length - insertedCount - updatedCount;
+				return {
+					success: insertedCount,
+					updated: updatedCount,
+					skipped,
+					failed
+				};
+			};
+			const importData = input;
+			if (m.import) return m.import({
+				ctx,
+				input: importData,
+				next: async (modifiedInput) => doImport(modifiedInput ?? importData)
+			});
+			return doImport(importData);
 		})
 	};
 	const crudRouter = router(procedures);