@wordrhyme/auto-crud-server 0.4.0 → 0.6.1

package/README.md

@@ -136,7 +136,7 @@ export { handler as GET, handler as POST };
 
 ## 📖 自动生成的路由
 
-`createCrudRouter` 会自动生成以下 7 个路由：
+`createCrudRouter` 会自动生成以下 8 个路由：
 
 ### 1. `list` - 列表查询
 
@@ -299,6 +299,42 @@ await trpc.tasks.updateMany({
 });
 ```
 
+### 8. `upsert` - 存在则更新，不存在则创建
+
+**输入**:
+```typescript
+Omit<Task, "createdAt" | "updatedAt">  // 需要包含 id
+```
+
+**输出**:
+```typescript
+{
+  data: Task;       // 创建或更新后的记录
+  isNew: boolean;   // true = 新建, false = 更新
+}
+```
+
+**示例**:
+```typescript
+// 如果 id="123" 存在则更新，不存在则创建
+const { data, isNew } = await trpc.tasks.upsert({
+  id: "123",
+  title: "My Task",
+  status: "todo",
+});
+
+if (isNew) {
+  console.log("Created new task");
+} else {
+  console.log("Updated existing task");
+}
+```
+
+**适用场景**：
+- 同步外部数据
+- 幂等导入
+- 配置项更新
+
 ---
 
 ## 🎯 高级过滤
@@ -608,6 +644,110 @@ export const tasksRouter = router({
 
 ---
 
+## 🔄 生命周期中间件
+
+使用 `middleware` 配置在 CRUD 操作前后注入自定义逻辑，类似 tRPC middleware 模式。
+
+### 完整控制模式
+
+```typescript
+import { createCrudRouter } from "@wordrhyme/auto-crud-server";
+
+const tasksRouter = createCrudRouter({
+  table: tasks,
+  insertSchema: insertTaskSchema,
+  updateSchema: updateTaskSchema,
+
+  // 中间件：完全控制操作流程
+  middleware: {
+    // 创建：修改输入 + 执行副作用
+    create: async ({ ctx, input, next }) => {
+      // 1. 修改输入数据
+      const data = { ...input, slug: slugify(input.title), createdBy: ctx.user.id };
+
+      // 2. 执行核心操作
+      const result = await next(data);
+
+      // 3. 执行副作用
+      await sendNotification(result);
+      await logAudit(ctx.user, "create", result);
+
+      // 4. 返回结果（可修改）
+      return result;
+    },
+
+    // 更新：可访问原记录
+    update: async ({ ctx, id, data, existing, next }) => {
+      // 检查权限
+      if (existing.ownerId !== ctx.user.id) {
+        throw new Error("Forbidden");
+      }
+      return next(data);
+    },
+
+    // 删除：条件拦截
+    delete: async ({ ctx, id, existing, next }) => {
+      if (existing.status === "locked") {
+        throw new Error("Cannot delete locked resource");
+      }
+      return next();
+    },
+  },
+});
+```
+
+### 使用便捷工具函数
+
+对于简单场景，使用工具函数简化代码：
+
+```typescript
+import {
+  createCrudRouter,
+  afterMiddleware,
+  beforeMiddleware,
+  afterCreate,
+  beforeCreate,
+} from "@wordrhyme/auto-crud-server";
+
+const tasksRouter = createCrudRouter({
+  table: tasks,
+  insertSchema: insertTaskSchema,
+  updateSchema: updateTaskSchema,
+
+  middleware: {
+    // 简单副作用：只在操作后执行
+    create: afterMiddleware(async (ctx, result) => {
+      await sendEmail(result);
+      await logAudit(ctx.user, "create", result);
+    }),
+
+    // 修改输入：只在操作前执行
+    update: beforeMiddleware(async (ctx, data) => {
+      return { ...data, updatedAt: new Date(), updatedBy: ctx.user.id };
+    }),
+
+    // 类型安全的便捷函数
+    delete: afterDelete(async (ctx, deleted) => {
+      await cleanupRelatedData(deleted.id);
+    }),
+  },
+});
+```
+
+### 可用的工具函数
+
+| 函数 | 用途 | 示例 |
+|------|------|------|
+| `afterMiddleware(fn)` | 操作后执行副作用 | 日志、通知、审计 |
+| `afterMiddlewareTransform(fn)` | 操作后修改返回值 | 添加计算字段 |
+| `beforeMiddleware(fn)` | 操作前修改输入 | 注入用户ID、生成slug |
+| `composeMiddleware(...fns)` | 组合多个中间件 | 复杂场景 |
+| `afterList`, `beforeList` | list 操作专用 | 分页后处理 |
+| `afterCreate`, `beforeCreate` | create 操作专用 | 创建通知 |
+| `afterUpdate`, `afterDelete` | update/delete 专用 | 更新/删除通知 |
+
+---
+
 ## 🔌 与其他库集成
 
 ### 与 Drizzle ORM 集成
@@ -698,7 +838,26 @@ export const filterVariants = {
 ```typescript
 // 主要导出
 export { createCrudRouter } from "./routers/_factory";
-export type { CrudRouterConfig } from "./routers/_factory";
+export type {
+  CrudRouterConfig,
+  CrudMiddleware,
+  ListInput,
+  ListResult,
+} from "./types/config";
+
+// Middleware 工具函数
+export {
+  afterMiddleware,
+  afterMiddlewareTransform,
+  beforeMiddleware,
+  composeMiddleware,
+  afterList,
+  beforeList,
+  afterCreate,
+  beforeCreate,
+  afterUpdate,
+  afterDelete,
+} from "./lib/middleware-helpers";
 
 // tRPC 工具
 export { router, publicProcedure } from "./trpc";

package/dist/index.cjs

@@ -474,11 +474,19 @@ 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, hooks = {} } = config;
+	const { table, insertSchema, updateSchema, idField = "id", filterableColumns, sortableColumns, maxBatchSize = 100, softDelete: softDeleteOption, middleware = {} } = config;
 	const resolved = resolveConfig(config);
 	const softDelete = resolveSoftDelete(softDeleteOption);
-	const h = hooks;
+	const m = middleware;
 	const getIdColumn = () => table[idField];
 	const getSoftDeleteColumn = () => softDelete ? table[softDelete.column] : null;
 	const buildWhere = (ctx, operation, additionalCondition) => {
@@ -496,6 +504,12 @@ function createCrudRouter(config) {
 	};
 	const withGuard = async (ctx, operation) => {
 		if (resolved.guard) {
+			if (operation === "upsert") {
+				const canCreate = await resolved.guard(ctx, "create");
+				const canUpdate = await resolved.guard(ctx, "update");
+				if (!canCreate || !canUpdate) throw new Error("Forbidden: upsert requires both create and update permissions");
+				return;
+			}
 			if (!await resolved.guard(ctx, operation)) throw new Error(`Forbidden: ${operation} not allowed`);
 		}
 	};
@@ -506,72 +520,75 @@ function createCrudRouter(config) {
 	const procedures = {
 		list: resolved.procedureFactory("list").input(listInputSchema).query(async ({ ctx, input }) => {
 			await withGuard(ctx, "list");
-			let processedInput = input;
-			if (h.beforeList) {
-				const result = await h.beforeList(ctx, processedInput);
-				if (result) processedInput = result;
-			}
-			const offset = (processedInput.page - 1) * processedInput.perPage;
-			const validatedFilters = processedInput.filters?.filter((filter) => validateColumn(filter.id, filterableColumns));
-			const where = buildWhere(ctx, "list", validatedFilters?.length ? filterColumns({
-				table,
-				filters: validatedFilters,
-				joinOperator: processedInput.joinOperator
-			}) : void 0);
-			let query = ctx.db.select().from(table).$dynamic();
-			if (where) query = query.where(where);
-			if (processedInput.sort?.length) {
-				const sortField = processedInput.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 doList = async (listInput$1) => {
+				const offset = (listInput$1.page - 1) * listInput$1.perPage;
+				const validatedFilters = listInput$1.filters?.filter((filter) => validateColumn(filter.id, filterableColumns));
+				const where = buildWhere(ctx, "list", validatedFilters?.length ? filterColumns({
+					table,
+					filters: validatedFilters,
+					joinOperator: listInput$1.joinOperator
+				}) : void 0);
+				let query = ctx.db.select().from(table).$dynamic();
+				if (where) query = query.where(where);
+				if (listInput$1.sort?.length) {
+					const sortField = listInput$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(processedInput.perPage).offset(offset);
-			let countQuery = ctx.db.select({ count: drizzle_orm.sql`count(*)::int` }).from(table).$dynamic();
-			if (where) countQuery = countQuery.where(where);
-			const count = (await countQuery)[0]?.count ?? 0;
-			let listResult = {
-				data,
-				total: count,
-				page: processedInput.page,
-				perPage: processedInput.perPage,
-				pageCount: Math.ceil(count / processedInput.perPage)
+				const data = await query.limit(listInput$1.perPage).offset(offset);
+				let countQuery = ctx.db.select({ count: drizzle_orm.sql`count(*)::int` }).from(table).$dynamic();
+				if (where) countQuery = countQuery.where(where);
+				const count = (await countQuery)[0]?.count ?? 0;
+				return {
+					data,
+					total: count,
+					page: listInput$1.page,
+					perPage: listInput$1.perPage,
+					pageCount: Math.ceil(count / listInput$1.perPage)
+				};
 			};
-			if (h.afterList) {
-				const result = await h.afterList(ctx, listResult);
-				if (result) listResult = result;
-			}
-			return listResult;
+			const listInput = input;
+			if (m.list) return m.list({
+				ctx,
+				input: listInput,
+				next: async (modifiedInput) => doList(modifiedInput ?? listInput)
+			});
+			return doList(listInput);
 		}),
-		getById: resolved.procedureFactory("get").input(zod.z.string()).query(async ({ ctx, input }) => {
+		get: resolved.procedureFactory("get").input(zod.z.string()).query(async ({ ctx, input }) => {
 			await withGuard(ctx, "get");
-			if (h.beforeGet) await h.beforeGet(ctx, input);
-			const where = buildWhere(ctx, "get", (0, drizzle_orm.eq)(getIdColumn(), input));
-			const [item] = await ctx.db.select().from(table).where(where);
-			await withAuthorize(ctx, item, "get");
-			let result = item ?? null;
-			if (h.afterGet) {
-				const hookResult = await h.afterGet(ctx, result);
-				if (hookResult !== void 0) result = hookResult;
-			}
-			return result;
+			const doGet = async () => {
+				const where = buildWhere(ctx, "get", (0, drizzle_orm.eq)(getIdColumn(), input));
+				const [item] = await ctx.db.select().from(table).where(where);
+				await withAuthorize(ctx, item, "get");
+				return item ?? null;
+			};
+			if (m.get) return m.get({
+				ctx,
+				id: input,
+				next: doGet
+			});
+			return doGet();
 		}),
 		create: resolved.procedureFactory("create").input(insertSchema).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "create");
-			let processedData = input;
-			if (h.beforeCreate) {
-				const result = await h.beforeCreate(ctx, processedData);
-				if (result) processedData = result;
-			}
-			const injectData = resolved.getInject(ctx, "create");
-			const data = {
-				...processedData,
-				...injectData
+			const doCreate = async (inputData) => {
+				const injectData = resolved.getInject(ctx, "create");
+				const data = {
+					...inputData,
+					...injectData
+				};
+				const [created] = await ctx.db.insert(table).values(data).returning();
+				return created;
 			};
-			const [created] = await ctx.db.insert(table).values(data).returning();
-			if (h.afterCreate) await h.afterCreate(ctx, created);
-			return created;
+			if (m.create) return m.create({
+				ctx,
+				input,
+				next: async (modifiedInput) => doCreate(modifiedInput ?? input)
+			});
+			return doCreate(input);
 		}),
 		update: resolved.procedureFactory("update").input(zod.z.object({
 			id: zod.z.string(),
@@ -582,19 +599,23 @@ function createCrudRouter(config) {
 			const [existing] = await ctx.db.select().from(table).where(where);
 			await withAuthorize(ctx, existing, "update");
 			if (!existing) throw new Error("Resource not found or access denied");
-			let processedData = input.data;
-			if (h.beforeUpdate) {
-				const result = await h.beforeUpdate(ctx, input.id, processedData, existing);
-				if (result) processedData = result;
-			}
-			const injectData = resolved.getInject(ctx, "update");
-			const data = {
-				...processedData,
-				...injectData
+			const doUpdate = async (updateData) => {
+				const injectData = resolved.getInject(ctx, "update");
+				const data = {
+					...updateData,
+					...injectData
+				};
+				const [updated] = await ctx.db.update(table).set(data).where(where).returning();
+				return updated;
 			};
-			const [updated] = await ctx.db.update(table).set(data).where(where).returning();
-			if (h.afterUpdate) await h.afterUpdate(ctx, updated);
-			return updated;
+			if (m.update) return m.update({
+				ctx,
+				id: input.id,
+				data: input.data,
+				existing,
+				next: async (modifiedData) => doUpdate(modifiedData ?? input.data)
+			});
+			return doUpdate(input.data);
 		}),
 		delete: resolved.procedureFactory("delete").input(zod.z.string()).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "delete");
@@ -602,54 +623,169 @@ function createCrudRouter(config) {
 			const [existing] = await ctx.db.select().from(table).where(where);
 			await withAuthorize(ctx, existing, "delete");
 			if (!existing) throw new Error("Resource not found or access denied");
-			if (h.beforeDelete) await h.beforeDelete(ctx, input, existing);
-			let deleted;
-			if (softDelete) [deleted] = await ctx.db.update(table).set({ [softDelete.column]: softDelete.getValue() }).where(where).returning();
-			else [deleted] = await ctx.db.delete(table).where(where).returning();
-			if (h.afterDelete) await h.afterDelete(ctx, deleted);
-			return deleted;
+			const doDelete = async () => {
+				let deleted;
+				if (softDelete) [deleted] = await ctx.db.update(table).set({ [softDelete.column]: softDelete.getValue() }).where(where).returning();
+				else [deleted] = await ctx.db.delete(table).where(where).returning();
+				return deleted;
+			};
+			if (m.delete) return m.delete({
+				ctx,
+				id: input,
+				existing,
+				next: doDelete
+			});
+			return doDelete();
 		}),
 		deleteMany: resolved.procedureFactory("deleteMany").input(zod.z.array(zod.z.string()).max(maxBatchSize)).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "deleteMany");
-			if (h.beforeDeleteMany) await h.beforeDeleteMany(ctx, input);
 			const where = buildWhere(ctx, "deleteMany", (0, drizzle_orm.inArray)(getIdColumn(), input));
-			let result;
-			if (softDelete) result = { deleted: (await ctx.db.update(table).set({ [softDelete.column]: softDelete.getValue() }).where(where).returning()).length };
-			else result = { deleted: (await ctx.db.delete(table).where(where).returning()).length };
-			if (h.afterDeleteMany) await h.afterDeleteMany(ctx, result);
-			return result;
+			const doDeleteMany = async () => {
+				if (softDelete) return { deleted: (await ctx.db.update(table).set({ [softDelete.column]: softDelete.getValue() }).where(where).returning()).length };
+				else return { deleted: (await ctx.db.delete(table).where(where).returning()).length };
+			};
+			if (m.deleteMany) return m.deleteMany({
+				ctx,
+				ids: input,
+				next: doDeleteMany
+			});
+			return doDeleteMany();
 		}),
 		updateMany: resolved.procedureFactory("updateMany").input(zod.z.object({
 			ids: zod.z.array(zod.z.string()).max(maxBatchSize),
 			data: updateSchema
 		})).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "updateMany");
-			let processedData = input.data;
-			if (h.beforeUpdateMany) {
-				const result$1 = await h.beforeUpdateMany(ctx, input.ids, processedData);
-				if (result$1) processedData = result$1;
-			}
 			const where = buildWhere(ctx, "updateMany", (0, drizzle_orm.inArray)(getIdColumn(), input.ids));
-			const injectData = resolved.getInject(ctx, "update");
-			const data = {
-				...processedData,
-				...injectData
+			const doUpdateMany = async (updateData) => {
+				const injectData = resolved.getInject(ctx, "update");
+				const data = {
+					...updateData,
+					...injectData
+				};
+				return { updated: (await ctx.db.update(table).set(data).where(where).returning()).length };
+			};
+			if (m.updateMany) return m.updateMany({
+				ctx,
+				ids: input.ids,
+				data: input.data,
+				next: async (modifiedData) => doUpdateMany(modifiedData ?? input.data)
+			});
+			return doUpdateMany(input.data);
+		}),
+		upsert: resolved.procedureFactory("upsert").input(insertSchema).mutation(async ({ ctx, input }) => {
+			await withGuard(ctx, "upsert");
+			const doUpsert = async (inputData) => {
+				const injectData = resolved.getInject(ctx, "create");
+				const data = {
+					...inputData,
+					...injectData
+				};
+				const inputId = inputData[idField];
+				let isNew = true;
+				if (inputId) {
+					const where = buildWhere(ctx, "get", (0, drizzle_orm.eq)(getIdColumn(), inputId));
+					const [existing] = await ctx.db.select().from(table).where(where);
+					isNew = !existing;
+				}
+				const [result] = await ctx.db.insert(table).values(data).onConflictDoUpdate({
+					target: getIdColumn(),
+					set: data
+				}).returning();
+				return {
+					data: result,
+					isNew
+				};
 			};
-			const result = { updated: (await ctx.db.update(table).set(data).where(where).returning()).length };
-			if (h.afterUpdateMany) await h.afterUpdateMany(ctx, result);
-			return result;
+			if (m.upsert) return m.upsert({
+				ctx,
+				input,
+				next: async (modifiedInput) => doUpsert(modifiedInput ?? input)
+			});
+			return doUpsert(input);
 		})
 	};
 	const crudRouter = router(procedures);
 	return Object.assign(crudRouter, { procedures });
 }
 
+//#endregion
+//#region src/lib/middleware-helpers.ts
+/**
+* Middleware 便捷工具函数
+* 简化常见场景的 middleware 创建
+*/
+/**
+* 创建 after-only 的 middleware（最常见场景）
+* 在操作完成后执行副作用，不修改返回值
+*
+* @example
+* middleware: {
+*   create: afterMiddleware(async (ctx, result) => {
+*     await sendEmail(result);
+*     await logAudit(ctx.user, 'create', result);
+*   }),
+* }
+*/
+function afterMiddleware(fn) {
+	return async (params) => {
+		const result = await params.next();
+		await fn(params.ctx, result);
+		return result;
+	};
+}
+/**
+* 创建 before-only 的 middleware
+* 在操作执行前修改输入数据
+*
+* @example
+* middleware: {
+*   create: beforeMiddleware(async (ctx, input) => {
+*     return { ...input, slug: slugify(input.title), createdBy: ctx.user.id };
+*   }),
+* }
+*/
+function beforeMiddleware(fn) {
+	return async (params) => {
+		const modifiedInput = await fn(params.ctx, params.input);
+		return params.next(modifiedInput);
+	};
+}
+/**
+* 组合多个 middleware 为一个
+*
+* @example
+* middleware: {
+*   create: composeMiddleware(
+*     beforeMiddleware((ctx, input) => ({ ...input, slug: slugify(input.title) })),
+*     afterMiddleware((ctx, result) => sendEmail(result)),
+*   ),
+* }
+*/
+function composeMiddleware(...middlewares) {
+	return async (params) => {
+		let index = 0;
+		const executeNext = async (...args) => {
+			if (index >= middlewares.length) return params.next(...args);
+			const currentMiddleware = middlewares[index++];
+			return currentMiddleware({
+				...params,
+				next: executeNext
+			});
+		};
+		return executeNext();
+	};
+}
+
 //#endregion
 //#region src/routers/index.ts
 const appRouter = router({});
 
 //#endregion
+exports.afterMiddleware = afterMiddleware;
 exports.appRouter = appRouter;
+exports.beforeMiddleware = beforeMiddleware;
+exports.composeMiddleware = composeMiddleware;
 exports.createCrudRouter = createCrudRouter;
 exports.publicProcedure = publicProcedure;
 exports.router = router;