@wordrhyme/auto-crud-server 1.1.6 → 1.2.0

package/README.md

@@ -83,7 +83,7 @@ import { tasks } from '@/db/schema';
 // 🚀 零配置！一行代码生成完整 CRUD 路由
 export const tasksRouter = createCrudRouter({
   table: tasks,
-  // Schema 自动从 table 派生，排除 id, createdAt, updatedAt
+  // Schema 自动从 table 派生，排除平台托管字段
 });
 ```
 
@@ -169,6 +169,9 @@ export { handler as GET, handler as POST };
 }
 ```
 
+未传 `sort` 或传空数组时，如果表存在 `createdAt` 且未被 `sortableColumns`
+白名单排除，列表默认按 `createdAt` 降序返回。
+
 **输出**:
 
 ```typescript
@@ -491,18 +494,18 @@ interface CrudRouterConfig<TTable, TSelect, TInsert, TUpdate> {
   idField?: string; // ID 字段名，默认 "id"
   filterableColumns?: CrudColumnRef<TTable>[]; // 可过滤字段白名单
   sortableColumns?: CrudColumnRef<TTable>[]; // 可排序字段白名单
-  omitFields?: string[]; // 自动派生时排除的字段
-  // 默认 ["id", "createdAt", "updatedAt"]
+  omitFields?: string[]; // 自动派生时额外排除的业务字段
+  // 默认已排除 ["id", "createdAt", "updatedAt", "createdBy", "createdByType", "updatedBy", "updatedByType"]
 }
 ```
 
 #### Schema 派生规则
 
-| 配置              | 派生行为                                    |
-| ----------------- | ------------------------------------------- |
-| 无 `schema`       | 从 `table` 自动派生，排除 `omitFields`      |
-| 无 `updateSchema` | 从 `schema.partial().refine(nonEmpty)` 派生 |
-| 无 `selectSchema` | 若有 `schema` 则使用它，否则从 `table` 派生 |
+| 配置              | 派生行为                                             |
+| ----------------- | ---------------------------------------------------- |
+| 无 `schema`       | 从 `table` 自动派生，排除默认托管字段和 `omitFields` |
+| 无 `updateSchema` | 从 `schema.partial().refine(nonEmpty)` 派生          |
+| 无 `selectSchema` | 若有 `schema` 则使用它，否则从 `table` 派生          |
 
 #### 使用示例
 
@@ -528,7 +531,7 @@ const usersRouter = createCrudRouter({
 // 4. 自定义排除字段
 const ordersRouter = createCrudRouter({
   table: orders,
-  omitFields: ['id', 'createdAt', 'updatedAt', 'internalCode'],
+  omitFields: ['internalCode'],
 });
 ```
 
@@ -992,8 +995,8 @@ export const usersRouter = createCrudRouter({
 ```typescript
 export const ordersRouter = createCrudRouter({
   table: orders,
-  // 自动派生 schema 时排除这些字段
-  omitFields: ['id', 'createdAt', 'updatedAt', 'internalCode'],
+  // 自动派生 schema 时额外排除这些字段；默认托管字段无需重复写
+  omitFields: ['internalCode'],
 });
 ```
 

package/dist/index.cjs

@@ -562,7 +562,11 @@ const importInputSchema = zod.z.object({
 const DEFAULT_OMIT_FIELDS = [
 	"id",
 	"createdAt",
-	"updatedAt"
+	"updatedAt",
+	"createdBy",
+	"createdByType",
+	"updatedBy",
+	"updatedByType"
 ];
 function shouldEnableCrudExtensionSchema(config) {
 	return Boolean(config.id) && config.extensions !== false;
@@ -576,19 +580,30 @@ function withCrudExtensionInput(schema, config) {
 * - 优先使用显式传入的 Schema
 * - 否则从 Drizzle table 自动派生
 */
-function resolveSchemas(config) {
-	const { table, omitFields = DEFAULT_OMIT_FIELDS } = config;
+function resolveSchemas(config, idField = "id") {
+	const { table } = config;
+	const omitFields = [...new Set([...DEFAULT_OMIT_FIELDS, ...config.omitFields ?? []])];
 	let schema;
+	let upsertSchema;
+	let importSchema;
 	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;
+		upsertSchema = schema;
+		importSchema = 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]));
+		const omitConfig = Object.fromEntries(omitFields.filter((field) => field in rawSchema.shape).map((field) => [field, true]));
 		schema = rawSchema.omit(omitConfig);
+		const idSchema = rawSchema.shape[idField];
+		const schemaWithOptionalId = idSchema && !(idField in schema.shape) ? schema.extend({ [idField]: idSchema.optional() }) : schema;
+		upsertSchema = schemaWithOptionalId;
+		importSchema = schemaWithOptionalId;
 	}
 	schema = withCrudExtensionInput(schema, config);
+	upsertSchema = withCrudExtensionInput(upsertSchema, config);
+	importSchema = withCrudExtensionInput(importSchema, config);
 	let selectSchema;
 	if (config.selectSchema) selectSchema = config.selectSchema;
 	else if (config.schema) selectSchema = schema;
@@ -597,6 +612,8 @@ function resolveSchemas(config) {
 	return {
 		selectSchema,
 		schema,
+		upsertSchema,
+		importSchema,
 		updateSchema
 	};
 }
@@ -604,12 +621,87 @@ function getColumnRefId(columnRef) {
 	return typeof columnRef === "string" ? columnRef : columnRef.id;
 }
 function findColumnRef(columnId, allowedColumns) {
+	if (!Array.isArray(allowedColumns)) return void 0;
 	return allowedColumns?.find((columnRef) => getColumnRefId(columnRef) === columnId);
 }
 function validateColumn(columnId, allowedColumns) {
-	if (!allowedColumns || allowedColumns.length === 0) return true;
+	if (allowedColumns === false) return false;
+	if (allowedColumns === void 0) return true;
 	return findColumnRef(columnId, allowedColumns) !== void 0;
 }
+function resolveColumnCapability(config, nextKey, legacyKey) {
+	const nextValue = config[nextKey];
+	const legacyValue = config[legacyKey];
+	if (nextValue !== void 0 && legacyValue !== void 0) throw new Error(`[createCrudRouter] "${nextKey}" and "${legacyKey}" cannot be used together.`);
+	const value = nextValue !== void 0 ? nextValue : legacyValue;
+	if (value === void 0) return void 0;
+	if (value === false) return false;
+	if (Array.isArray(value)) return value;
+	throw new Error(`[createCrudRouter] "${nextKey}" must be an array of column refs or false.`);
+}
+function readCapabilityFields(columns) {
+	if (columns === false) return [];
+	if (Array.isArray(columns)) return columns.map(getColumnRefId);
+	return null;
+}
+function buildCrudCapabilities(searchColumns, filterableColumns, sortableColumns) {
+	const searchFields = readCapabilityFields(searchColumns) ?? [];
+	return {
+		search: {
+			enabled: searchFields.length > 0,
+			fields: searchFields
+		},
+		filters: {
+			enabled: filterableColumns !== false,
+			fields: readCapabilityFields(filterableColumns)
+		},
+		sort: {
+			enabled: sortableColumns !== false,
+			fields: readCapabilityFields(sortableColumns)
+		}
+	};
+}
+function uniqueCapabilityFields(...fields) {
+	return Array.from(new Set(fields.flatMap((fieldList) => fieldList ?? [])));
+}
+function mergeSearchCapability(base, extension, disabled) {
+	if (disabled) return {
+		enabled: false,
+		fields: []
+	};
+	const fields = uniqueCapabilityFields(base.fields, extension?.fields);
+	return {
+		enabled: base.enabled || extension?.enabled === true || fields.length > 0,
+		fields
+	};
+}
+function mergeFieldCapability(base, extension, disabled) {
+	if (disabled) return {
+		enabled: false,
+		fields: []
+	};
+	if (!(base.enabled || extension?.enabled === true)) return {
+		enabled: false,
+		fields: []
+	};
+	return {
+		enabled: true,
+		fields: base.fields === null || extension?.fields === null ? null : uniqueCapabilityFields(base.fields, extension?.fields)
+	};
+}
+function mergeCrudCapabilities(base, extension, disabled) {
+	return {
+		search: mergeSearchCapability(base.search, extension?.search, disabled.search),
+		filters: mergeFieldCapability(base.filters, extension?.filters, disabled.filters),
+		sort: mergeFieldCapability(base.sort, extension?.sort, disabled.sort)
+	};
+}
+function withCrudCapabilities(metadata, capabilities, disabled) {
+	return {
+		...metadata ?? {},
+		capabilities: mergeCrudCapabilities(capabilities, metadata?.capabilities, disabled)
+	};
+}
 function getTableColumn(table, columnId) {
 	return table[columnId];
 }
@@ -628,7 +720,8 @@ function buildJsonFieldTextExpression(column, jsonField) {
 }
 function resolveColumnTarget({ table, columnId, allowedColumns }) {
 	const columnRef = findColumnRef(columnId, allowedColumns);
-	if ((allowedColumns?.length ?? 0) > 0 && columnRef === void 0) return;
+	if (allowedColumns === false) return;
+	if (Array.isArray(allowedColumns) && columnRef === void 0) return;
 	if (columnRef && typeof columnRef !== "string") {
 		if (columnRef.expression) return columnRef.expression({ table });
 		const column = getTableColumn(table, columnRef.id);
@@ -824,7 +917,8 @@ async function enrichCrudRows(ctx, config, idField, rows) {
 	});
 }
 function isAllowedBaseCrudColumn(table, columnId, allowedColumns) {
-	if (allowedColumns && allowedColumns.length > 0) return resolveColumnTarget({
+	if (allowedColumns === false) return false;
+	if (Array.isArray(allowedColumns)) return resolveColumnTarget({
 		table,
 		columnId,
 		allowedColumns
@@ -839,11 +933,16 @@ async function applyCrudExtensionFilters(ctx, config, table, idField, filterable
 	const filters = input.filters ?? [];
 	const search = typeof input.search === "string" ? input.search.trim() : "";
 	if (!target || filters.length === 0 && !search) return input;
+	const filtersDisabled = filterableColumns === false;
+	const searchDisabled = searchColumns === false;
 	const baseFilters = [];
 	const extensionFilters = [];
-	for (const filter of filters) if (isAllowedBaseCrudColumn(table, filter.id, filterableColumns)) baseFilters.push(filter);
-	else if (isKnownBaseCrudColumn(table, filter.id, filterableColumns)) continue;
-	else extensionFilters.push(filter);
+	for (const filter of filters) {
+		if (filtersDisabled) continue;
+		if (isAllowedBaseCrudColumn(table, filter.id, filterableColumns)) baseFilters.push(filter);
+		else if (isKnownBaseCrudColumn(table, filter.id, filterableColumns)) continue;
+		else extensionFilters.push(filter);
+	}
 	if (extensionFilters.length === 0 && !search) return {
 		...input,
 		filters: baseFilters
@@ -863,14 +962,14 @@ async function applyCrudExtensionFilters(ctx, config, table, idField, filterable
 		});
 		matchedSets.push(new Set(matchedIds$1));
 	}
-	if (search && provider?.searchEntityIds) {
+	if (search && !searchDisabled && provider?.searchEntityIds) {
 		const matchedIds$1 = await provider.searchEntityIds({
 			id: target.id,
 			search,
 			limit: 5e3
 		});
 		matchedSets.push(new Set(matchedIds$1));
-	} else if (search && !buildCrudSearchCondition({
+	} else if (search && !searchDisabled && !buildCrudSearchCondition({
 		table,
 		search,
 		searchColumns
@@ -897,7 +996,7 @@ async function applyCrudExtensionFilters(ctx, config, table, idField, filterable
 }
 function buildCrudSearchCondition({ table, search, searchColumns }) {
 	const term = typeof search === "string" ? search.trim() : "";
-	if (!term || !searchColumns || searchColumns.length === 0) return void 0;
+	if (!term || !Array.isArray(searchColumns) || searchColumns.length === 0) return;
 	const conditions = searchColumns.map((columnRef) => resolveColumnTarget({
 		table,
 		columnId: getColumnRefId(columnRef),
@@ -926,8 +1025,17 @@ function combineConditions(...conditions) {
 * @typeParam TUpdate - 更新输入类型
 */
 function createCrudRouter(config) {
-	const { table, idField = "id", filterableColumns, searchColumns, sortableColumns, maxBatchSize = 100, maxExportSize = 5e3, softDelete: softDeleteOption, middleware = {} } = config;
-	const { selectSchema, schema, updateSchema } = resolveSchemas(config);
+	const { table, idField = "id", maxBatchSize = 100, maxExportSize = 5e3, softDelete: softDeleteOption, middleware = {} } = config;
+	const searchColumns = resolveColumnCapability(config, "search", "searchColumns");
+	const filterableColumns = resolveColumnCapability(config, "filters", "filterableColumns");
+	const sortableColumns = resolveColumnCapability(config, "sort", "sortableColumns");
+	const capabilities = buildCrudCapabilities(searchColumns, filterableColumns, sortableColumns);
+	const disabledCapabilities = {
+		search: searchColumns === false,
+		filters: filterableColumns === false,
+		sort: sortableColumns === false
+	};
+	const { selectSchema, schema, upsertSchema, importSchema, updateSchema } = resolveSchemas(config, idField);
 	const entityOutputSchema = withCrudExtensionInput(selectSchema, config);
 	const listOutputSchema = zod.z.object({
 		data: zod.z.array(entityOutputSchema),
@@ -939,7 +1047,21 @@ function createCrudRouter(config) {
 	const metadataOutputSchema = zod.z.object({
 		schema: zod.z.unknown().optional(),
 		fields: zod.z.record(zod.z.string(), zod.z.unknown()).optional(),
-		errors: zod.z.array(zod.z.string()).optional()
+		errors: zod.z.array(zod.z.string()).optional(),
+		capabilities: zod.z.object({
+			search: zod.z.object({
+				enabled: zod.z.boolean(),
+				fields: zod.z.array(zod.z.string())
+			}),
+			filters: zod.z.object({
+				enabled: zod.z.boolean(),
+				fields: zod.z.array(zod.z.string()).nullable()
+			}),
+			sort: zod.z.object({
+				enabled: zod.z.boolean(),
+				fields: zod.z.array(zod.z.string()).nullable()
+			})
+		})
 	});
 	const deleteManyOutputSchema = zod.z.object({ deleted: zod.z.number() });
 	const updateManyOutputSchema = zod.z.object({ updated: zod.z.number() });
@@ -1016,10 +1138,10 @@ function createCrudRouter(config) {
 		meta: metaProcedure.output(metadataOutputSchema).query(async ({ ctx }) => {
 			await withGuard(ctx, "list");
 			const target = readCrudTarget(config);
-			if (!target) return {};
+			if (!target) return withCrudCapabilities({}, capabilities, disabledCapabilities);
 			const provider = resolveCrudExtensions(ctx, config);
-			if (!provider?.getMetadata) return {};
-			return provider.getMetadata({ id: target.id });
+			if (!provider?.getMetadata) return withCrudCapabilities({}, capabilities, disabledCapabilities);
+			return withCrudCapabilities(await provider.getMetadata({ id: target.id }), capabilities, disabledCapabilities);
 		}),
 		list: resolved.procedureFactory("list").input(resolvedListInputSchema).output(listOutputSchema).query(async ({ ctx, input }) => {
 			await withGuard(ctx, "list");
@@ -1047,9 +1169,12 @@ function createCrudRouter(config) {
 				})));
 				let query = ctx.db.select().from(table).$dynamic();
 				if (where) query = query.where(where);
-				if (effectiveInput.sort?.length) {
-					const sortField = effectiveInput.sort[0];
-					if (sortField && validateColumn(sortField.id, sortableColumns)) {
+				const sortField = effectiveInput.sort?.[0] ?? (getTableColumn(table, "createdAt") ? {
+					id: "createdAt",
+					desc: true
+				} : void 0);
+				if (sortField) {
+					if (validateColumn(sortField.id, sortableColumns)) {
 						const column = resolveColumnTarget({
 							table,
 							columnId: sortField.id,
@@ -1255,7 +1380,7 @@ function createCrudRouter(config) {
 			});
 			return doUpdateMany(input.data);
 		}),
-		upsert: resolved.procedureFactory("upsert").input(schema).output(upsertOutputSchema).mutation(async ({ ctx, input }) => {
+		upsert: resolved.procedureFactory("upsert").input(upsertSchema).output(upsertOutputSchema).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "upsert");
 			const doUpsert = async (inputData) => {
 				const splitInput = splitCrudExtensionWriteInput(inputData, tableColumnNames);
@@ -1400,7 +1525,7 @@ function createCrudRouter(config) {
 				const failed = [];
 				for (let i = 0; i < importData$1.rows.length; i++) {
 					const row = importData$1.rows[i];
-					const result = schema.safeParse(row);
+					const result = importSchema.safeParse(row);
 					if (result.success) {
 						const splitRow = splitCrudExtensionWriteInput(result.data, tableColumnNames);
 						validRows.push(splitRow);

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { PgTable } from "drizzle-orm/pg-core";
-import * as _trpc_server2 from "@trpc/server";
+import * as _trpc_server0 from "@trpc/server";
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import { AnyColumn, SQL } from "drizzle-orm";
 
@@ -12,13 +12,13 @@ import { AnyColumn, SQL } from "drizzle-orm";
 interface Context {
   db: PostgresJsDatabase<Record<string, never>>;
 }
-declare const router: _trpc_server2.TRPCRouterBuilder<{
+declare const router: _trpc_server0.TRPCRouterBuilder<{
   ctx: Context;
   meta: object;
-  errorShape: _trpc_server2.TRPCDefaultErrorShape;
+  errorShape: _trpc_server0.TRPCDefaultErrorShape;
   transformer: true;
 }>;
-declare const publicProcedure: _trpc_server2.TRPCProcedureBuilder<Context, object, object, _trpc_server2.TRPCUnsetMarker, _trpc_server2.TRPCUnsetMarker, _trpc_server2.TRPCUnsetMarker, _trpc_server2.TRPCUnsetMarker, false>;
+declare const publicProcedure: _trpc_server0.TRPCProcedureBuilder<Context, object, object, _trpc_server0.TRPCUnsetMarker, _trpc_server0.TRPCUnsetMarker, _trpc_server0.TRPCUnsetMarker, _trpc_server0.TRPCUnsetMarker, false>;
 //#endregion
 //#region src/types/config.d.ts
 type CrudOperation = 'list' | 'get' | 'create' | 'update' | 'delete' | 'deleteMany' | 'updateMany' | 'upsert' | 'export' | 'import' | 'createMany';
@@ -54,6 +54,21 @@ interface CrudColumnConfig<TTable extends PgTable = PgTable> {
   expression?: CrudColumnExpression<TTable>;
 }
 type CrudColumnRef<TTable extends PgTable = PgTable> = string | CrudColumnConfig<TTable>;
+type CrudColumnCapability<TTable extends PgTable = PgTable> = false | CrudColumnRef<TTable>[];
+interface CrudCapabilityMetadata {
+  search: {
+    enabled: boolean;
+    fields: string[];
+  };
+  filters: {
+    enabled: boolean;
+    fields: string[] | null;
+  };
+  sort: {
+    enabled: boolean;
+    fields: string[] | null;
+  };
+}
 interface SoftDeleteConfig {
   /** 软删除标记列名 */
   column: string;
@@ -133,6 +148,8 @@ interface CrudExtensionMetadata {
   schema?: unknown;
   fields?: Record<string, unknown>;
   errors?: string[];
+  /** 扩展提供的查询能力，会与 router 基础能力合并。 */
+  capabilities?: CrudCapabilityMetadata;
 }
 interface CrudExtensionFilter {
   id: string;
@@ -581,14 +598,39 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   authorize?: (ctx: TContext, resource: TSelect, operation: CrudOperation) => boolean | Promise<boolean>;
   /**
    * 要从 schema 排除的字段（自动派生时使用）
-   * @default ["id", "createdAt", "updatedAt"]
+   * @default ["id", "createdAt", "updatedAt", "createdBy", "createdByType", "updatedBy", "updatedByType"]
    */
   omitFields?: TableColumnKeys<TTable>[];
   /** ID 字段名，默认 "id" */
   idField?: string;
+  /**
+   * 全局搜索列白名单。
+   *
+   * 不配置时不启用全局搜索；传数组时启用并只搜索指定字段；传 false 显式禁用。
+   *
+   * @example
+   * search: ['title', { id: 'name', jsonField: ['zh-CN', 'en-US'] }]
+   */
+  search?: CrudColumnCapability<TTable>;
+  /**
+   * 可过滤列白名单。
+   *
+   * 不配置时保持兼容行为：所有真实表字段可过滤；传数组时只允许指定字段；
+   * 传 false 显式禁用过滤。
+   */
+  filters?: CrudColumnCapability<TTable>;
+  /**
+   * 可排序列白名单。
+   *
+   * 不配置时保持兼容行为：所有真实表字段可排序；传数组时只允许指定字段；
+   * 传 false 显式禁用排序。
+   */
+  sort?: CrudColumnCapability<TTable>;
   /**
    * 可过滤的列白名单。
    *
+   * @deprecated Use `filters` instead.
+   *
    * 普通字段使用字符串；jsonb/i18n 字段可用对象配置 jsonField，
    * 由服务端显式生成 text expression，前端仍然传 id。
    *
@@ -602,6 +644,8 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   /**
    * 全局搜索列白名单。
    *
+   * @deprecated Use `search` instead.
+   *
    * 当列表/导出输入包含 `search` 时，默认查询会对这些列做文本化 ILIKE
    * 搜索，并与其他筛选条件按 AND 组合。扩展字段搜索仍由
    * `CrudExtensionsProvider.searchEntityIds` 处理。
@@ -613,6 +657,8 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   /**
    * 可排序的列白名单。
    *
+   * @deprecated Use `sort` instead.
+   *
    * 与 filterableColumns 相同，普通字段使用字符串，jsonb/i18n 字段可配置 jsonField。
    */
   sortableColumns?: CrudColumnRef<TTable>[];
@@ -890,12 +936,12 @@ type CrudHookEventMap<PluginId extends string, ResourceName extends string, TCre
 } } & { [K in `${PluginId}.${ResourceName}.createMany`]: TCreate[] };
 //#endregion
 //#region src/routers/index.d.ts
-declare const appRouter: _trpc_server2.TRPCBuiltRouter<{
+declare const appRouter: _trpc_server0.TRPCBuiltRouter<{
   ctx: Context;
   meta: object;
-  errorShape: _trpc_server2.TRPCDefaultErrorShape;
+  errorShape: _trpc_server0.TRPCDefaultErrorShape;
   transformer: true;
-}, _trpc_server2.TRPCDecorateCreateRouterOptions<{}>>;
+}, _trpc_server0.TRPCDecorateCreateRouterOptions<{}>>;
 type AppRouter = typeof appRouter;
 //#endregion
-export { type AnyProcedure, type AppRouter, type CreateManyMiddlewareParams, type CreateMiddlewareParams, type CrudColumnConfig, type CrudColumnExpression, type CrudColumnRef, type CrudExtensionFilter, type CrudExtensionMetadata, type CrudExtensionsConfig, type CrudExtensionsProvider, type CrudHookEventMap, type CrudMiddleware, type CrudOperation, type CrudProcedures, type CrudRouterConfig, type DeleteManyMiddlewareParams, type DeleteMiddlewareParams, type ExportInput, type ExportMiddlewareParams, type ExportResult, type GetInput, type GetMiddlewareParams, type ImportFailedRow, type ImportInput, type ImportMiddlewareParams, type ImportResult, type ListInput, type ListMiddlewareParams, type ListResult, type ProcedureConfig, type ProcedureFactory, type ProcedureMap, type SoftDeleteConfig, type SoftDeleteOption, type UpdateManyMiddlewareParams, type UpdateMiddlewareParams, type UpsertMiddlewareParams, type WriteOperation, afterMiddleware, appRouter, baseExportInputSchema, baseGetInputSchema, baseListInputSchema, beforeMiddleware, composeMiddleware, createCrudRouter, publicProcedure, router };
+export { type AnyProcedure, type AppRouter, type CreateManyMiddlewareParams, type CreateMiddlewareParams, type CrudCapabilityMetadata, type CrudColumnCapability, type CrudColumnConfig, type CrudColumnExpression, type CrudColumnRef, type CrudExtensionFilter, type CrudExtensionMetadata, type CrudExtensionsConfig, type CrudExtensionsProvider, type CrudHookEventMap, type CrudMiddleware, type CrudOperation, type CrudProcedures, type CrudRouterConfig, type DeleteManyMiddlewareParams, type DeleteMiddlewareParams, type ExportInput, type ExportMiddlewareParams, type ExportResult, type GetInput, type GetMiddlewareParams, type ImportFailedRow, type ImportInput, type ImportMiddlewareParams, type ImportResult, type ListInput, type ListMiddlewareParams, type ListResult, type ProcedureConfig, type ProcedureFactory, type ProcedureMap, type SoftDeleteConfig, type SoftDeleteOption, type UpdateManyMiddlewareParams, type UpdateMiddlewareParams, type UpsertMiddlewareParams, type WriteOperation, afterMiddleware, appRouter, baseExportInputSchema, baseGetInputSchema, baseListInputSchema, beforeMiddleware, composeMiddleware, createCrudRouter, publicProcedure, router };

package/dist/index.d.ts

@@ -55,6 +55,21 @@ interface CrudColumnConfig<TTable extends PgTable = PgTable> {
   expression?: CrudColumnExpression<TTable>;
 }
 type CrudColumnRef<TTable extends PgTable = PgTable> = string | CrudColumnConfig<TTable>;
+type CrudColumnCapability<TTable extends PgTable = PgTable> = false | CrudColumnRef<TTable>[];
+interface CrudCapabilityMetadata {
+  search: {
+    enabled: boolean;
+    fields: string[];
+  };
+  filters: {
+    enabled: boolean;
+    fields: string[] | null;
+  };
+  sort: {
+    enabled: boolean;
+    fields: string[] | null;
+  };
+}
 interface SoftDeleteConfig {
   /** 软删除标记列名 */
   column: string;
@@ -134,6 +149,8 @@ interface CrudExtensionMetadata {
   schema?: unknown;
   fields?: Record<string, unknown>;
   errors?: string[];
+  /** 扩展提供的查询能力，会与 router 基础能力合并。 */
+  capabilities?: CrudCapabilityMetadata;
 }
 interface CrudExtensionFilter {
   id: string;
@@ -582,14 +599,39 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   authorize?: (ctx: TContext, resource: TSelect, operation: CrudOperation) => boolean | Promise<boolean>;
   /**
    * 要从 schema 排除的字段（自动派生时使用）
-   * @default ["id", "createdAt", "updatedAt"]
+   * @default ["id", "createdAt", "updatedAt", "createdBy", "createdByType", "updatedBy", "updatedByType"]
    */
   omitFields?: TableColumnKeys<TTable>[];
   /** ID 字段名，默认 "id" */
   idField?: string;
+  /**
+   * 全局搜索列白名单。
+   *
+   * 不配置时不启用全局搜索；传数组时启用并只搜索指定字段；传 false 显式禁用。
+   *
+   * @example
+   * search: ['title', { id: 'name', jsonField: ['zh-CN', 'en-US'] }]
+   */
+  search?: CrudColumnCapability<TTable>;
+  /**
+   * 可过滤列白名单。
+   *
+   * 不配置时保持兼容行为：所有真实表字段可过滤；传数组时只允许指定字段；
+   * 传 false 显式禁用过滤。
+   */
+  filters?: CrudColumnCapability<TTable>;
+  /**
+   * 可排序列白名单。
+   *
+   * 不配置时保持兼容行为：所有真实表字段可排序；传数组时只允许指定字段；
+   * 传 false 显式禁用排序。
+   */
+  sort?: CrudColumnCapability<TTable>;
   /**
    * 可过滤的列白名单。
    *
+   * @deprecated Use `filters` instead.
+   *
    * 普通字段使用字符串；jsonb/i18n 字段可用对象配置 jsonField，
    * 由服务端显式生成 text expression，前端仍然传 id。
    *
@@ -603,6 +645,8 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   /**
    * 全局搜索列白名单。
    *
+   * @deprecated Use `search` instead.
+   *
    * 当列表/导出输入包含 `search` 时，默认查询会对这些列做文本化 ILIKE
    * 搜索，并与其他筛选条件按 AND 组合。扩展字段搜索仍由
    * `CrudExtensionsProvider.searchEntityIds` 处理。
@@ -614,6 +658,8 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   /**
    * 可排序的列白名单。
    *
+   * @deprecated Use `sort` instead.
+   *
    * 与 filterableColumns 相同，普通字段使用字符串，jsonb/i18n 字段可配置 jsonField。
    */
   sortableColumns?: CrudColumnRef<TTable>[];
@@ -899,4 +945,4 @@ declare const appRouter: _trpc_server0.TRPCBuiltRouter<{
 }, _trpc_server0.TRPCDecorateCreateRouterOptions<{}>>;
 type AppRouter = typeof appRouter;
 //#endregion
-export { type AnyProcedure, type AppRouter, type CreateManyMiddlewareParams, type CreateMiddlewareParams, type CrudColumnConfig, type CrudColumnExpression, type CrudColumnRef, type CrudExtensionFilter, type CrudExtensionMetadata, type CrudExtensionsConfig, type CrudExtensionsProvider, type CrudHookEventMap, type CrudMiddleware, type CrudOperation, type CrudProcedures, type CrudRouterConfig, type DeleteManyMiddlewareParams, type DeleteMiddlewareParams, type ExportInput, type ExportMiddlewareParams, type ExportResult, type GetInput, type GetMiddlewareParams, type ImportFailedRow, type ImportInput, type ImportMiddlewareParams, type ImportResult, type ListInput, type ListMiddlewareParams, type ListResult, type ProcedureConfig, type ProcedureFactory, type ProcedureMap, type SoftDeleteConfig, type SoftDeleteOption, type UpdateManyMiddlewareParams, type UpdateMiddlewareParams, type UpsertMiddlewareParams, type WriteOperation, afterMiddleware, appRouter, baseExportInputSchema, baseGetInputSchema, baseListInputSchema, beforeMiddleware, composeMiddleware, createCrudRouter, publicProcedure, router };
+export { type AnyProcedure, type AppRouter, type CreateManyMiddlewareParams, type CreateMiddlewareParams, type CrudCapabilityMetadata, type CrudColumnCapability, type CrudColumnConfig, type CrudColumnExpression, type CrudColumnRef, type CrudExtensionFilter, type CrudExtensionMetadata, type CrudExtensionsConfig, type CrudExtensionsProvider, type CrudHookEventMap, type CrudMiddleware, type CrudOperation, type CrudProcedures, type CrudRouterConfig, type DeleteManyMiddlewareParams, type DeleteMiddlewareParams, type ExportInput, type ExportMiddlewareParams, type ExportResult, type GetInput, type GetMiddlewareParams, type ImportFailedRow, type ImportInput, type ImportMiddlewareParams, type ImportResult, type ListInput, type ListMiddlewareParams, type ListResult, type ProcedureConfig, type ProcedureFactory, type ProcedureMap, type SoftDeleteConfig, type SoftDeleteOption, type UpdateManyMiddlewareParams, type UpdateMiddlewareParams, type UpsertMiddlewareParams, type WriteOperation, afterMiddleware, appRouter, baseExportInputSchema, baseGetInputSchema, baseListInputSchema, beforeMiddleware, composeMiddleware, createCrudRouter, publicProcedure, router };

package/dist/index.js

@@ -533,7 +533,11 @@ const importInputSchema = z.object({
 const DEFAULT_OMIT_FIELDS = [
 	"id",
 	"createdAt",
-	"updatedAt"
+	"updatedAt",
+	"createdBy",
+	"createdByType",
+	"updatedBy",
+	"updatedByType"
 ];
 function shouldEnableCrudExtensionSchema(config) {
 	return Boolean(config.id) && config.extensions !== false;
@@ -547,19 +551,30 @@ function withCrudExtensionInput(schema, config) {
 * - 优先使用显式传入的 Schema
 * - 否则从 Drizzle table 自动派生
 */
-function resolveSchemas(config) {
-	const { table, omitFields = DEFAULT_OMIT_FIELDS } = config;
+function resolveSchemas(config, idField = "id") {
+	const { table } = config;
+	const omitFields = [...new Set([...DEFAULT_OMIT_FIELDS, ...config.omitFields ?? []])];
 	let schema;
+	let upsertSchema;
+	let importSchema;
 	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;
+		upsertSchema = schema;
+		importSchema = schema;
 	} else {
 		const rawSchema = 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]));
+		const omitConfig = Object.fromEntries(omitFields.filter((field) => field in rawSchema.shape).map((field) => [field, true]));
 		schema = rawSchema.omit(omitConfig);
+		const idSchema = rawSchema.shape[idField];
+		const schemaWithOptionalId = idSchema && !(idField in schema.shape) ? schema.extend({ [idField]: idSchema.optional() }) : schema;
+		upsertSchema = schemaWithOptionalId;
+		importSchema = schemaWithOptionalId;
 	}
 	schema = withCrudExtensionInput(schema, config);
+	upsertSchema = withCrudExtensionInput(upsertSchema, config);
+	importSchema = withCrudExtensionInput(importSchema, config);
 	let selectSchema;
 	if (config.selectSchema) selectSchema = config.selectSchema;
 	else if (config.schema) selectSchema = schema;
@@ -568,6 +583,8 @@ function resolveSchemas(config) {
 	return {
 		selectSchema,
 		schema,
+		upsertSchema,
+		importSchema,
 		updateSchema
 	};
 }
@@ -575,12 +592,87 @@ function getColumnRefId(columnRef) {
 	return typeof columnRef === "string" ? columnRef : columnRef.id;
 }
 function findColumnRef(columnId, allowedColumns) {
+	if (!Array.isArray(allowedColumns)) return void 0;
 	return allowedColumns?.find((columnRef) => getColumnRefId(columnRef) === columnId);
 }
 function validateColumn(columnId, allowedColumns) {
-	if (!allowedColumns || allowedColumns.length === 0) return true;
+	if (allowedColumns === false) return false;
+	if (allowedColumns === void 0) return true;
 	return findColumnRef(columnId, allowedColumns) !== void 0;
 }
+function resolveColumnCapability(config, nextKey, legacyKey) {
+	const nextValue = config[nextKey];
+	const legacyValue = config[legacyKey];
+	if (nextValue !== void 0 && legacyValue !== void 0) throw new Error(`[createCrudRouter] "${nextKey}" and "${legacyKey}" cannot be used together.`);
+	const value = nextValue !== void 0 ? nextValue : legacyValue;
+	if (value === void 0) return void 0;
+	if (value === false) return false;
+	if (Array.isArray(value)) return value;
+	throw new Error(`[createCrudRouter] "${nextKey}" must be an array of column refs or false.`);
+}
+function readCapabilityFields(columns) {
+	if (columns === false) return [];
+	if (Array.isArray(columns)) return columns.map(getColumnRefId);
+	return null;
+}
+function buildCrudCapabilities(searchColumns, filterableColumns, sortableColumns) {
+	const searchFields = readCapabilityFields(searchColumns) ?? [];
+	return {
+		search: {
+			enabled: searchFields.length > 0,
+			fields: searchFields
+		},
+		filters: {
+			enabled: filterableColumns !== false,
+			fields: readCapabilityFields(filterableColumns)
+		},
+		sort: {
+			enabled: sortableColumns !== false,
+			fields: readCapabilityFields(sortableColumns)
+		}
+	};
+}
+function uniqueCapabilityFields(...fields) {
+	return Array.from(new Set(fields.flatMap((fieldList) => fieldList ?? [])));
+}
+function mergeSearchCapability(base, extension, disabled) {
+	if (disabled) return {
+		enabled: false,
+		fields: []
+	};
+	const fields = uniqueCapabilityFields(base.fields, extension?.fields);
+	return {
+		enabled: base.enabled || extension?.enabled === true || fields.length > 0,
+		fields
+	};
+}
+function mergeFieldCapability(base, extension, disabled) {
+	if (disabled) return {
+		enabled: false,
+		fields: []
+	};
+	if (!(base.enabled || extension?.enabled === true)) return {
+		enabled: false,
+		fields: []
+	};
+	return {
+		enabled: true,
+		fields: base.fields === null || extension?.fields === null ? null : uniqueCapabilityFields(base.fields, extension?.fields)
+	};
+}
+function mergeCrudCapabilities(base, extension, disabled) {
+	return {
+		search: mergeSearchCapability(base.search, extension?.search, disabled.search),
+		filters: mergeFieldCapability(base.filters, extension?.filters, disabled.filters),
+		sort: mergeFieldCapability(base.sort, extension?.sort, disabled.sort)
+	};
+}
+function withCrudCapabilities(metadata, capabilities, disabled) {
+	return {
+		...metadata ?? {},
+		capabilities: mergeCrudCapabilities(capabilities, metadata?.capabilities, disabled)
+	};
+}
 function getTableColumn(table, columnId) {
 	return table[columnId];
 }
@@ -599,7 +691,8 @@ function buildJsonFieldTextExpression(column, jsonField) {
 }
 function resolveColumnTarget({ table, columnId, allowedColumns }) {
 	const columnRef = findColumnRef(columnId, allowedColumns);
-	if ((allowedColumns?.length ?? 0) > 0 && columnRef === void 0) return;
+	if (allowedColumns === false) return;
+	if (Array.isArray(allowedColumns) && columnRef === void 0) return;
 	if (columnRef && typeof columnRef !== "string") {
 		if (columnRef.expression) return columnRef.expression({ table });
 		const column = getTableColumn(table, columnRef.id);
@@ -795,7 +888,8 @@ async function enrichCrudRows(ctx, config, idField, rows) {
 	});
 }
 function isAllowedBaseCrudColumn(table, columnId, allowedColumns) {
-	if (allowedColumns && allowedColumns.length > 0) return resolveColumnTarget({
+	if (allowedColumns === false) return false;
+	if (Array.isArray(allowedColumns)) return resolveColumnTarget({
 		table,
 		columnId,
 		allowedColumns
@@ -810,11 +904,16 @@ async function applyCrudExtensionFilters(ctx, config, table, idField, filterable
 	const filters = input.filters ?? [];
 	const search = typeof input.search === "string" ? input.search.trim() : "";
 	if (!target || filters.length === 0 && !search) return input;
+	const filtersDisabled = filterableColumns === false;
+	const searchDisabled = searchColumns === false;
 	const baseFilters = [];
 	const extensionFilters = [];
-	for (const filter of filters) if (isAllowedBaseCrudColumn(table, filter.id, filterableColumns)) baseFilters.push(filter);
-	else if (isKnownBaseCrudColumn(table, filter.id, filterableColumns)) continue;
-	else extensionFilters.push(filter);
+	for (const filter of filters) {
+		if (filtersDisabled) continue;
+		if (isAllowedBaseCrudColumn(table, filter.id, filterableColumns)) baseFilters.push(filter);
+		else if (isKnownBaseCrudColumn(table, filter.id, filterableColumns)) continue;
+		else extensionFilters.push(filter);
+	}
 	if (extensionFilters.length === 0 && !search) return {
 		...input,
 		filters: baseFilters
@@ -834,14 +933,14 @@ async function applyCrudExtensionFilters(ctx, config, table, idField, filterable
 		});
 		matchedSets.push(new Set(matchedIds$1));
 	}
-	if (search && provider?.searchEntityIds) {
+	if (search && !searchDisabled && provider?.searchEntityIds) {
 		const matchedIds$1 = await provider.searchEntityIds({
 			id: target.id,
 			search,
 			limit: 5e3
 		});
 		matchedSets.push(new Set(matchedIds$1));
-	} else if (search && !buildCrudSearchCondition({
+	} else if (search && !searchDisabled && !buildCrudSearchCondition({
 		table,
 		search,
 		searchColumns
@@ -868,7 +967,7 @@ async function applyCrudExtensionFilters(ctx, config, table, idField, filterable
 }
 function buildCrudSearchCondition({ table, search, searchColumns }) {
 	const term = typeof search === "string" ? search.trim() : "";
-	if (!term || !searchColumns || searchColumns.length === 0) return void 0;
+	if (!term || !Array.isArray(searchColumns) || searchColumns.length === 0) return;
 	const conditions = searchColumns.map((columnRef) => resolveColumnTarget({
 		table,
 		columnId: getColumnRefId(columnRef),
@@ -897,8 +996,17 @@ function combineConditions(...conditions) {
 * @typeParam TUpdate - 更新输入类型
 */
 function createCrudRouter(config) {
-	const { table, idField = "id", filterableColumns, searchColumns, sortableColumns, maxBatchSize = 100, maxExportSize = 5e3, softDelete: softDeleteOption, middleware = {} } = config;
-	const { selectSchema, schema, updateSchema } = resolveSchemas(config);
+	const { table, idField = "id", maxBatchSize = 100, maxExportSize = 5e3, softDelete: softDeleteOption, middleware = {} } = config;
+	const searchColumns = resolveColumnCapability(config, "search", "searchColumns");
+	const filterableColumns = resolveColumnCapability(config, "filters", "filterableColumns");
+	const sortableColumns = resolveColumnCapability(config, "sort", "sortableColumns");
+	const capabilities = buildCrudCapabilities(searchColumns, filterableColumns, sortableColumns);
+	const disabledCapabilities = {
+		search: searchColumns === false,
+		filters: filterableColumns === false,
+		sort: sortableColumns === false
+	};
+	const { selectSchema, schema, upsertSchema, importSchema, updateSchema } = resolveSchemas(config, idField);
 	const entityOutputSchema = withCrudExtensionInput(selectSchema, config);
 	const listOutputSchema = z.object({
 		data: z.array(entityOutputSchema),
@@ -910,7 +1018,21 @@ function createCrudRouter(config) {
 	const metadataOutputSchema = z.object({
 		schema: z.unknown().optional(),
 		fields: z.record(z.string(), z.unknown()).optional(),
-		errors: z.array(z.string()).optional()
+		errors: z.array(z.string()).optional(),
+		capabilities: z.object({
+			search: z.object({
+				enabled: z.boolean(),
+				fields: z.array(z.string())
+			}),
+			filters: z.object({
+				enabled: z.boolean(),
+				fields: z.array(z.string()).nullable()
+			}),
+			sort: z.object({
+				enabled: z.boolean(),
+				fields: z.array(z.string()).nullable()
+			})
+		})
 	});
 	const deleteManyOutputSchema = z.object({ deleted: z.number() });
 	const updateManyOutputSchema = z.object({ updated: z.number() });
@@ -987,10 +1109,10 @@ function createCrudRouter(config) {
 		meta: metaProcedure.output(metadataOutputSchema).query(async ({ ctx }) => {
 			await withGuard(ctx, "list");
 			const target = readCrudTarget(config);
-			if (!target) return {};
+			if (!target) return withCrudCapabilities({}, capabilities, disabledCapabilities);
 			const provider = resolveCrudExtensions(ctx, config);
-			if (!provider?.getMetadata) return {};
-			return provider.getMetadata({ id: target.id });
+			if (!provider?.getMetadata) return withCrudCapabilities({}, capabilities, disabledCapabilities);
+			return withCrudCapabilities(await provider.getMetadata({ id: target.id }), capabilities, disabledCapabilities);
 		}),
 		list: resolved.procedureFactory("list").input(resolvedListInputSchema).output(listOutputSchema).query(async ({ ctx, input }) => {
 			await withGuard(ctx, "list");
@@ -1018,9 +1140,12 @@ function createCrudRouter(config) {
 				})));
 				let query = ctx.db.select().from(table).$dynamic();
 				if (where) query = query.where(where);
-				if (effectiveInput.sort?.length) {
-					const sortField = effectiveInput.sort[0];
-					if (sortField && validateColumn(sortField.id, sortableColumns)) {
+				const sortField = effectiveInput.sort?.[0] ?? (getTableColumn(table, "createdAt") ? {
+					id: "createdAt",
+					desc: true
+				} : void 0);
+				if (sortField) {
+					if (validateColumn(sortField.id, sortableColumns)) {
 						const column = resolveColumnTarget({
 							table,
 							columnId: sortField.id,
@@ -1226,7 +1351,7 @@ function createCrudRouter(config) {
 			});
 			return doUpdateMany(input.data);
 		}),
-		upsert: resolved.procedureFactory("upsert").input(schema).output(upsertOutputSchema).mutation(async ({ ctx, input }) => {
+		upsert: resolved.procedureFactory("upsert").input(upsertSchema).output(upsertOutputSchema).mutation(async ({ ctx, input }) => {
 			await withGuard(ctx, "upsert");
 			const doUpsert = async (inputData) => {
 				const splitInput = splitCrudExtensionWriteInput(inputData, tableColumnNames);
@@ -1371,7 +1496,7 @@ function createCrudRouter(config) {
 				const failed = [];
 				for (let i = 0; i < importData$1.rows.length; i++) {
 					const row = importData$1.rows[i];
-					const result = schema.safeParse(row);
+					const result = importSchema.safeParse(row);
 					if (result.success) {
 						const splitRow = splitCrudExtensionWriteInput(result.data, tableColumnNames);
 						validRows.push(splitRow);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@wordrhyme/auto-crud-server",
   "type": "module",
-  "version": "1.1.6",
+  "version": "1.2.0",
   "description": "tRPC server utilities for auto-crud - automatic CRUD routers for Drizzle ORM",
   "author": "wordrhyme",
   "license": "MIT",
@@ -48,10 +48,10 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18",
     "zod": "^4.3.6",
+    "@internal/eslint-config": "0.3.0",
+    "@internal/prettier-config": "0.0.1",
     "@internal/tsconfig": "0.1.0",
     "@internal/tsdown-config": "0.1.0",
-    "@internal/prettier-config": "0.0.1",
-    "@internal/eslint-config": "0.3.0",
     "@internal/vitest-config": "0.1.0"
   },
   "prettier": "@internal/prettier-config",