@wordrhyme/auto-crud-server 1.1.8 → 1.3.0

package/README.md

@@ -939,6 +939,40 @@ export const db = drizzle(client, { schema });
 export const createContext = () => ({ db });
 ```
 
+### 使用业务时区解析日期过滤
+
+AutoCrud 默认保留历史行为：使用服务器本地时区解析日期过滤。如果宿主已经有用户或租户的业务时区，可在 tRPC context 中提供 `resolveDateRange`，将日历日期转换为 UTC 半开区间：
+
+```typescript
+import type { DateRangeResolver } from '@wordrhyme/auto-crud-server';
+
+const resolveDateRange: DateRangeResolver = (filter) => {
+  // 由宿主根据 filter.value、filter.operator 和当前业务时区进行转换。
+  // resolveCalendarFilterToUtc 应返回 UTC Date 对象。
+  return resolveCalendarFilterToUtc(filter, getBusinessTimeZone());
+};
+
+export const createContext = () => ({
+  db,
+  resolveDateRange,
+});
+```
+
+Resolver 返回值遵循以下契约：
+
+```typescript
+interface DateFilterRange {
+  start?: Date; // 日历范围的 UTC 起点，包含
+  endExclusive?: Date; // UTC 终点，不包含
+}
+```
+
+- 返回 `undefined`：使用原有服务器本地时区逻辑。
+- 返回非空范围：该结果是权威结果，不再回退到本地时区。
+- `lt` / `gte` 需要 `start`；`lte` / `gt` 需要 `endExclusive`。
+- `eq`、`ne`、`isBetween`、`isRelativeToToday` 可使用单边或双边范围。
+- 无效日期、空范围、反向范围或缺少操作符所需边界会抛出 `RangeError`，避免过滤条件意外扩大。
+
 ### 与 Next.js 集成
 
 ```typescript

package/dist/index.cjs

@@ -75,12 +75,73 @@ function safeParseNumber(value) {
 	const num = Number(value);
 	return Number.isNaN(num) ? null : num;
 }
-function filterColumns({ table, filters, joinOperator, resolveColumn }) {
+function isValidDate(value) {
+	return value instanceof Date && !Number.isNaN(value.getTime());
+}
+function isDateRangeOperator(operator) {
+	switch (operator) {
+		case "eq":
+		case "ne":
+		case "lt":
+		case "lte":
+		case "gt":
+		case "gte":
+		case "isBetween":
+		case "isRelativeToToday": return true;
+		case "iLike":
+		case "notILike":
+		case "inArray":
+		case "notInArray":
+		case "isEmpty":
+		case "isNotEmpty": return false;
+	}
+	return false;
+}
+function normalizeDateRange(range) {
+	if (range.start !== void 0 && !isValidDate(range.start)) throw new RangeError("resolveDateRange returned an invalid start boundary");
+	if (range.endExclusive !== void 0 && !isValidDate(range.endExclusive)) throw new RangeError("resolveDateRange returned an invalid endExclusive boundary");
+	const { start, endExclusive } = range;
+	if (!start && !endExclusive) throw new RangeError("resolveDateRange must return at least one date boundary");
+	if (start && endExclusive && start >= endExclusive) throw new RangeError("resolveDateRange requires start to be before endExclusive");
+	return {
+		start,
+		endExclusive
+	};
+}
+function requireDateBoundary(boundary, name, operator) {
+	if (!boundary) throw new RangeError(`resolveDateRange must return ${name} for operator ${operator}`);
+	return boundary;
+}
+function resolvedDateCondition(expr, operator, range) {
+	const { start, endExclusive } = range;
+	switch (operator) {
+		case "eq":
+		case "isBetween":
+		case "isRelativeToToday":
+			if (start && endExclusive) return (0, drizzle_orm.and)((0, drizzle_orm.gte)(expr, start), (0, drizzle_orm.lt)(expr, endExclusive));
+			if (start) return (0, drizzle_orm.gte)(expr, start);
+			return (0, drizzle_orm.lt)(expr, requireDateBoundary(endExclusive, "endExclusive", operator));
+		case "ne":
+			if (start && endExclusive) return (0, drizzle_orm.or)((0, drizzle_orm.lt)(expr, start), (0, drizzle_orm.gte)(expr, endExclusive));
+			if (start) return (0, drizzle_orm.lt)(expr, start);
+			return (0, drizzle_orm.gte)(expr, requireDateBoundary(endExclusive, "endExclusive", operator));
+		case "lt": return (0, drizzle_orm.lt)(expr, requireDateBoundary(start, "start", operator));
+		case "lte": return (0, drizzle_orm.lt)(expr, requireDateBoundary(endExclusive, "endExclusive", operator));
+		case "gt": return (0, drizzle_orm.gte)(expr, requireDateBoundary(endExclusive, "endExclusive", operator));
+		case "gte": return (0, drizzle_orm.gte)(expr, requireDateBoundary(start, "start", operator));
+	}
+	throw new Error("Unsupported resolved date operator");
+}
+function filterColumns({ table, filters, joinOperator, resolveColumn, resolveDateRange }) {
 	const joinFn = joinOperator === "and" ? drizzle_orm.and : drizzle_orm.or;
 	const validConditions = filters.map((filter) => {
 		const column = resolveColumn ? resolveColumn(filter.id) : getColumn(table, filter.id);
 		if (!column) return void 0;
 		const expr = toSqlTarget(column);
+		if ((filter.variant === "date" || filter.variant === "dateRange") && isDateRangeOperator(filter.operator)) {
+			const resolvedRange = resolveDateRange?.(filter);
+			if (resolvedRange !== void 0) return resolvedDateCondition(expr, filter.operator, normalizeDateRange(resolvedRange));
+		}
 		switch (filter.operator) {
 			case "iLike": return filter.variant === "text" && typeof filter.value === "string" ? (0, drizzle_orm.ilike)(expr, `%${filter.value}%`) : void 0;
 			case "notILike": return filter.variant === "text" && typeof filter.value === "string" ? (0, drizzle_orm.notIlike)(expr, `%${filter.value}%`) : void 0;
@@ -621,12 +682,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];
 }
@@ -645,7 +781,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);
@@ -841,7 +978,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
@@ -856,11 +994,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
@@ -880,14 +1023,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
@@ -914,7 +1057,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),
@@ -943,7 +1086,16 @@ function combineConditions(...conditions) {
 * @typeParam TUpdate - 更新输入类型
 */
 function createCrudRouter(config) {
-	const { table, idField = "id", filterableColumns, searchColumns, sortableColumns, maxBatchSize = 100, maxExportSize = 5e3, softDelete: softDeleteOption, middleware = {} } = 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({
@@ -956,7 +1108,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() });
@@ -1033,10 +1199,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");
@@ -1056,7 +1222,8 @@ function createCrudRouter(config) {
 							columnId: id,
 							allowedColumns: filterableColumns
 						});
-					}
+					},
+					resolveDateRange: ctx.resolveDateRange
 				}) : void 0, buildCrudSearchCondition({
 					table,
 					search: effectiveInput.search,
@@ -1350,7 +1517,8 @@ function createCrudRouter(config) {
 							columnId: id,
 							allowedColumns: filterableColumns
 						});
-					}
+					},
+					resolveDateRange: ctx.resolveDateRange
 				}) : void 0, buildCrudSearchCondition({
 					table,
 					search: effectiveInput.search,

package/dist/index.d.cts

@@ -1,9 +1,36 @@
+import { AnyColumn, SQL, Table } from "drizzle-orm";
 import { z } from "zod";
 import { PgTable } from "drizzle-orm/pg-core";
 import * as _trpc_server2 from "@trpc/server";
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import { AnyColumn, SQL } from "drizzle-orm";
 
+//#region src/lib/filter-columns.d.ts
+/** 过滤器变体类型 */
+type FilterVariant = 'text' | 'number' | 'range' | 'date' | 'dateRange' | 'boolean' | 'select' | 'multiSelect';
+/** 过滤器操作符 */
+type FilterOperator = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'iLike' | 'notILike' | 'inArray' | 'notInArray' | 'isBetween' | 'isRelativeToToday' | 'isEmpty' | 'isNotEmpty';
+/** 扩展的列过滤器 */
+interface ExtendedColumnFilter<T extends Table = Table> {
+  id: keyof T | string;
+  value: unknown;
+  variant: FilterVariant;
+  operator: FilterOperator;
+}
+/** Host-resolved UTC boundaries for a calendar-date filter. */
+interface DateFilterRange {
+  start?: Date;
+  endExclusive?: Date;
+}
+/**
+ * Optional host adapter for date filters.
+ *
+ * AutoCrud intentionally does not choose a time zone. A host that has business
+ * time-zone context can resolve the filter to UTC boundaries. Returning
+ * undefined preserves the legacy server-local parsing behavior. A non-empty
+ * result is authoritative and must contain valid boundaries for the operator.
+ */
+type DateRangeResolver<T extends Table = Table> = (filter: ExtendedColumnFilter<T>) => DateFilterRange | undefined;
+//#endregion
 //#region src/trpc.d.ts
 /**
  * tRPC Context 类型
@@ -11,6 +38,7 @@ import { AnyColumn, SQL } from "drizzle-orm";
  */
 interface Context {
   db: PostgresJsDatabase<Record<string, never>>;
+  resolveDateRange?: DateRangeResolver;
 }
 declare const router: _trpc_server2.TRPCRouterBuilder<{
   ctx: Context;
@@ -54,6 +82,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 +176,8 @@ interface CrudExtensionMetadata {
   schema?: unknown;
   fields?: Record<string, unknown>;
   errors?: string[];
+  /** 扩展提供的查询能力，会与 router 基础能力合并。 */
+  capabilities?: CrudCapabilityMetadata;
 }
 interface CrudExtensionFilter {
   id: string;
@@ -586,9 +631,34 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   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 +672,8 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   /**
    * 全局搜索列白名单。
    *
+   * @deprecated Use `search` instead.
+   *
    * 当列表/导出输入包含 `search` 时，默认查询会对这些列做文本化 ILIKE
    * 搜索，并与其他筛选条件按 AND 组合。扩展字段搜索仍由
    * `CrudExtensionsProvider.searchEntityIds` 处理。
@@ -613,6 +685,8 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   /**
    * 可排序的列白名单。
    *
+   * @deprecated Use `sort` instead.
+   *
    * 与 filterableColumns 相同，普通字段使用字符串，jsonb/i18n 字段可配置 jsonField。
    */
   sortableColumns?: CrudColumnRef<TTable>[];
@@ -898,4 +972,4 @@ declare const appRouter: _trpc_server2.TRPCBuiltRouter<{
 }, _trpc_server2.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 DateFilterRange, type DateRangeResolver, type DeleteManyMiddlewareParams, type DeleteMiddlewareParams, type ExportInput, type ExportMiddlewareParams, type ExportResult, type ExtendedColumnFilter, type FilterOperator, type FilterVariant, 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

@@ -1,10 +1,37 @@
 import { z } from "zod";
-import { AnyColumn, SQL } from "drizzle-orm";
+import { AnyColumn, SQL, Table } from "drizzle-orm";
 import * as _trpc_server2 from "@trpc/server";
 import superjson from "superjson";
 import { PgTable } from "drizzle-orm/pg-core";
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 
+//#region src/lib/filter-columns.d.ts
+/** 过滤器变体类型 */
+type FilterVariant = 'text' | 'number' | 'range' | 'date' | 'dateRange' | 'boolean' | 'select' | 'multiSelect';
+/** 过滤器操作符 */
+type FilterOperator = 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte' | 'iLike' | 'notILike' | 'inArray' | 'notInArray' | 'isBetween' | 'isRelativeToToday' | 'isEmpty' | 'isNotEmpty';
+/** 扩展的列过滤器 */
+interface ExtendedColumnFilter<T extends Table = Table> {
+  id: keyof T | string;
+  value: unknown;
+  variant: FilterVariant;
+  operator: FilterOperator;
+}
+/** Host-resolved UTC boundaries for a calendar-date filter. */
+interface DateFilterRange {
+  start?: Date;
+  endExclusive?: Date;
+}
+/**
+ * Optional host adapter for date filters.
+ *
+ * AutoCrud intentionally does not choose a time zone. A host that has business
+ * time-zone context can resolve the filter to UTC boundaries. Returning
+ * undefined preserves the legacy server-local parsing behavior. A non-empty
+ * result is authoritative and must contain valid boundaries for the operator.
+ */
+type DateRangeResolver<T extends Table = Table> = (filter: ExtendedColumnFilter<T>) => DateFilterRange | undefined;
+//#endregion
 //#region src/trpc.d.ts
 /**
  * tRPC Context 类型
@@ -12,6 +39,7 @@ import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
  */
 interface Context {
   db: PostgresJsDatabase<Record<string, never>>;
+  resolveDateRange?: DateRangeResolver;
 }
 declare const router: _trpc_server2.TRPCRouterBuilder<{
   ctx: Context;
@@ -55,6 +83,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 +177,8 @@ interface CrudExtensionMetadata {
   schema?: unknown;
   fields?: Record<string, unknown>;
   errors?: string[];
+  /** 扩展提供的查询能力，会与 router 基础能力合并。 */
+  capabilities?: CrudCapabilityMetadata;
 }
 interface CrudExtensionFilter {
   id: string;
@@ -587,9 +632,34 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   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 +673,8 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   /**
    * 全局搜索列白名单。
    *
+   * @deprecated Use `search` instead.
+   *
    * 当列表/导出输入包含 `search` 时，默认查询会对这些列做文本化 ILIKE
    * 搜索，并与其他筛选条件按 AND 组合。扩展字段搜索仍由
    * `CrudExtensionsProvider.searchEntityIds` 处理。
@@ -614,6 +686,8 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   /**
    * 可排序的列白名单。
    *
+   * @deprecated Use `sort` instead.
+   *
    * 与 filterableColumns 相同，普通字段使用字符串，jsonb/i18n 字段可配置 jsonField。
    */
   sortableColumns?: CrudColumnRef<TTable>[];
@@ -899,4 +973,4 @@ declare const appRouter: _trpc_server2.TRPCBuiltRouter<{
 }, _trpc_server2.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 DateFilterRange, type DateRangeResolver, type DeleteManyMiddlewareParams, type DeleteMiddlewareParams, type ExportInput, type ExportMiddlewareParams, type ExportResult, type ExtendedColumnFilter, type FilterOperator, type FilterVariant, 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

@@ -46,12 +46,73 @@ function safeParseNumber(value) {
 	const num = Number(value);
 	return Number.isNaN(num) ? null : num;
 }
-function filterColumns({ table, filters, joinOperator, resolveColumn }) {
+function isValidDate(value) {
+	return value instanceof Date && !Number.isNaN(value.getTime());
+}
+function isDateRangeOperator(operator) {
+	switch (operator) {
+		case "eq":
+		case "ne":
+		case "lt":
+		case "lte":
+		case "gt":
+		case "gte":
+		case "isBetween":
+		case "isRelativeToToday": return true;
+		case "iLike":
+		case "notILike":
+		case "inArray":
+		case "notInArray":
+		case "isEmpty":
+		case "isNotEmpty": return false;
+	}
+	return false;
+}
+function normalizeDateRange(range) {
+	if (range.start !== void 0 && !isValidDate(range.start)) throw new RangeError("resolveDateRange returned an invalid start boundary");
+	if (range.endExclusive !== void 0 && !isValidDate(range.endExclusive)) throw new RangeError("resolveDateRange returned an invalid endExclusive boundary");
+	const { start, endExclusive } = range;
+	if (!start && !endExclusive) throw new RangeError("resolveDateRange must return at least one date boundary");
+	if (start && endExclusive && start >= endExclusive) throw new RangeError("resolveDateRange requires start to be before endExclusive");
+	return {
+		start,
+		endExclusive
+	};
+}
+function requireDateBoundary(boundary, name, operator) {
+	if (!boundary) throw new RangeError(`resolveDateRange must return ${name} for operator ${operator}`);
+	return boundary;
+}
+function resolvedDateCondition(expr, operator, range) {
+	const { start, endExclusive } = range;
+	switch (operator) {
+		case "eq":
+		case "isBetween":
+		case "isRelativeToToday":
+			if (start && endExclusive) return and(gte(expr, start), lt(expr, endExclusive));
+			if (start) return gte(expr, start);
+			return lt(expr, requireDateBoundary(endExclusive, "endExclusive", operator));
+		case "ne":
+			if (start && endExclusive) return or(lt(expr, start), gte(expr, endExclusive));
+			if (start) return lt(expr, start);
+			return gte(expr, requireDateBoundary(endExclusive, "endExclusive", operator));
+		case "lt": return lt(expr, requireDateBoundary(start, "start", operator));
+		case "lte": return lt(expr, requireDateBoundary(endExclusive, "endExclusive", operator));
+		case "gt": return gte(expr, requireDateBoundary(endExclusive, "endExclusive", operator));
+		case "gte": return gte(expr, requireDateBoundary(start, "start", operator));
+	}
+	throw new Error("Unsupported resolved date operator");
+}
+function filterColumns({ table, filters, joinOperator, resolveColumn, resolveDateRange }) {
 	const joinFn = joinOperator === "and" ? and : or;
 	const validConditions = filters.map((filter) => {
 		const column = resolveColumn ? resolveColumn(filter.id) : getColumn(table, filter.id);
 		if (!column) return void 0;
 		const expr = toSqlTarget(column);
+		if ((filter.variant === "date" || filter.variant === "dateRange") && isDateRangeOperator(filter.operator)) {
+			const resolvedRange = resolveDateRange?.(filter);
+			if (resolvedRange !== void 0) return resolvedDateCondition(expr, filter.operator, normalizeDateRange(resolvedRange));
+		}
 		switch (filter.operator) {
 			case "iLike": return filter.variant === "text" && typeof filter.value === "string" ? ilike(expr, `%${filter.value}%`) : void 0;
 			case "notILike": return filter.variant === "text" && typeof filter.value === "string" ? notIlike(expr, `%${filter.value}%`) : void 0;
@@ -592,12 +653,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];
 }
@@ -616,7 +752,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);
@@ -812,7 +949,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
@@ -827,11 +965,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
@@ -851,14 +994,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
@@ -885,7 +1028,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),
@@ -914,7 +1057,16 @@ function combineConditions(...conditions) {
 * @typeParam TUpdate - 更新输入类型
 */
 function createCrudRouter(config) {
-	const { table, idField = "id", filterableColumns, searchColumns, sortableColumns, maxBatchSize = 100, maxExportSize = 5e3, softDelete: softDeleteOption, middleware = {} } = 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({
@@ -927,7 +1079,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() });
@@ -1004,10 +1170,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");
@@ -1027,7 +1193,8 @@ function createCrudRouter(config) {
 							columnId: id,
 							allowedColumns: filterableColumns
 						});
-					}
+					},
+					resolveDateRange: ctx.resolveDateRange
 				}) : void 0, buildCrudSearchCondition({
 					table,
 					search: effectiveInput.search,
@@ -1321,7 +1488,8 @@ function createCrudRouter(config) {
 							columnId: id,
 							allowedColumns: filterableColumns
 						});
-					}
+					},
+					resolveDateRange: ctx.resolveDateRange
 				}) : void 0, buildCrudSearchCondition({
 					table,
 					search: effectiveInput.search,

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@wordrhyme/auto-crud-server",
   "type": "module",
-  "version": "1.1.8",
+  "version": "1.3.0",
   "description": "tRPC server utilities for auto-crud - automatic CRUD routers for Drizzle ORM",
   "author": "wordrhyme",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pixpilot/shadcn-components.git",
+    "url": "https://github.com/denvey/wordrhyme-components",
     "directory": "packages/auto-crud-server"
   },
   "main": "./dist/index.cjs",
@@ -49,10 +49,10 @@
     "vitest": "^4.0.18",
     "zod": "^4.3.6",
     "@internal/eslint-config": "0.3.0",
-    "@internal/tsconfig": "0.1.0",
-    "@internal/vitest-config": "0.1.0",
     "@internal/tsdown-config": "0.1.0",
-    "@internal/prettier-config": "0.0.1"
+    "@internal/tsconfig": "0.1.0",
+    "@internal/prettier-config": "0.0.1",
+    "@internal/vitest-config": "0.1.0"
   },
   "prettier": "@internal/prettier-config",
   "scripts": {