@wordrhyme/auto-crud-server 1.0.4 → 1.0.6

package/dist/index.d.cts

@@ -1,8 +1,8 @@
+import { z } from "zod";
 import { PgTable } from "drizzle-orm/pg-core";
-import * as _trpc_server0 from "@trpc/server";
+import * as _trpc_server2 from "@trpc/server";
 import { PostgresJsDatabase } from "drizzle-orm/postgres-js";
-import { SQL } from "drizzle-orm";
-import { z } from "zod";
+import { AnyColumn, SQL } from "drizzle-orm";
 
 //#region src/trpc.d.ts
 /**
@@ -12,23 +12,48 @@ import { z } from "zod";
 interface Context {
   db: PostgresJsDatabase<Record<string, never>>;
 }
-declare const router: _trpc_server0.TRPCRouterBuilder<{
+declare const router: _trpc_server2.TRPCRouterBuilder<{
   ctx: Context;
   meta: object;
-  errorShape: _trpc_server0.TRPCDefaultErrorShape;
+  errorShape: _trpc_server2.TRPCDefaultErrorShape;
   transformer: true;
 }>;
-declare const publicProcedure: _trpc_server0.TRPCProcedureBuilder<Context, object, object, _trpc_server0.TRPCUnsetMarker, _trpc_server0.TRPCUnsetMarker, _trpc_server0.TRPCUnsetMarker, _trpc_server0.TRPCUnsetMarker, false>;
+declare const publicProcedure: _trpc_server2.TRPCProcedureBuilder<Context, object, object, _trpc_server2.TRPCUnsetMarker, _trpc_server2.TRPCUnsetMarker, _trpc_server2.TRPCUnsetMarker, _trpc_server2.TRPCUnsetMarker, false>;
 //#endregion
 //#region src/types/config.d.ts
-type CrudOperation = "list" | "get" | "create" | "update" | "delete" | "deleteMany" | "updateMany" | "upsert" | "export" | "import" | "createMany";
-type WriteOperation = "create" | "update";
+type CrudOperation = 'list' | 'get' | 'create' | 'update' | 'delete' | 'deleteMany' | 'updateMany' | 'upsert' | 'export' | 'import' | 'createMany';
+type WriteOperation = 'create' | 'update';
 /**
  * 表字段键类型提取
  * 用于 omitFields 的强类型支持
  */
-type TableColumnKeys<T extends PgTable> = keyof T["_"]["columns"];
+type TableColumnKeys<T extends PgTable> = keyof T['_']['columns'];
 type AnyProcedure = any;
+/**
+ * 过滤/排序字段的自定义 SQL expression。
+ *
+ * 普通字段无需配置 expression，直接使用字段名即可；jsonb、i18n、派生字段等
+ * 需要自定义查询目标时，可通过 expression 显式返回 Drizzle SQL 片段或列对象。
+ */
+type CrudColumnExpression<TTable extends PgTable = PgTable> = (params: {
+  table: TTable;
+}) => SQL | AnyColumn;
+/**
+ * 过滤/排序字段配置。
+ *
+ * - string: 普通表字段，继续使用 table[id]
+ * - object.jsonField: 从 jsonb 字段中提取一个或多个 key 作为文本查询目标
+ * - object.expression: 高级场景自定义 SQL expression
+ */
+interface CrudColumnConfig<TTable extends PgTable = PgTable> {
+  /** 前端传入的逻辑字段名，同时默认对应 table 上的列名 */
+  id: string;
+  /** jsonb 对象内部要读取的字段；数组按顺序 coalesce 作为 fallback */
+  jsonField?: string | string[];
+  /** 高级场景自定义查询目标，优先级高于 jsonField */
+  expression?: CrudColumnExpression<TTable>;
+}
+type CrudColumnRef<TTable extends PgTable = PgTable> = string | CrudColumnConfig<TTable>;
 interface SoftDeleteConfig {
   /** 软删除标记列名 */
   column: string;
@@ -63,7 +88,7 @@ interface ListInput {
     operator: string;
     filterId: string;
   }>;
-  joinOperator: "and" | "or";
+  joinOperator: 'and' | 'or';
 }
 /**
  * 列表查询结果类型
@@ -75,6 +100,14 @@ interface ListResult<TSelect> {
   perPage: number;
   pageCount: number;
 }
+/**
+ * 单条查询输入类型
+ * - string: 兼容旧的 get(id) 调用
+ * - object: 支持通过 getInputSchema 扩展 include 等控制参数
+ */
+type GetInput = string | {
+  id: string;
+};
 /**
  * 导出查询输入类型（复用 ListInput 的筛选/排序，无分页）
  */
@@ -90,7 +123,7 @@ interface ExportInput {
     operator: string;
     filterId: string;
   }>;
-  joinOperator?: "and" | "or";
+  joinOperator?: 'and' | 'or';
   /** 导出数量限制，会被 clamp 到 [1, maxExportSize] */
   limit?: number;
 }
@@ -137,17 +170,18 @@ interface ImportInput {
    * - "upsert": 存在则更新，不存在则新建
    * - "error": 冲突行计入失败
    */
-  onConflict?: "skip" | "upsert" | "error";
+  onConflict?: 'skip' | 'upsert' | 'error';
 }
-interface ListMiddlewareParams<TContext, TSelect> {
+interface ListMiddlewareParams<TContext, TSelect, TListInput extends ListInput = ListInput> {
   ctx: TContext;
-  input: ListInput;
-  next: (input?: ListInput) => Promise<ListResult<TSelect>>;
+  input: TListInput;
+  next: (input?: TListInput) => Promise<ListResult<TSelect>>;
 }
-interface GetMiddlewareParams<TContext, TSelect> {
+interface GetMiddlewareParams<TContext, TSelect, TGetInput extends GetInput = GetInput> {
   ctx: TContext;
   id: string;
-  next: () => Promise<TSelect | null>;
+  input: TGetInput;
+  next: (input?: TGetInput) => Promise<TSelect | null>;
 }
 interface CreateMiddlewareParams<TContext, TSelect, TInsert> {
   ctx: TContext;
@@ -190,10 +224,10 @@ interface UpsertMiddlewareParams<TContext, TSelect, TInsert> {
     isNew: boolean;
   }>;
 }
-interface ExportMiddlewareParams<TContext, TSelect> {
+interface ExportMiddlewareParams<TContext, TSelect, TExportInput extends ExportInput = ExportInput> {
   ctx: TContext;
-  input: ExportInput;
-  next: (input?: ExportInput) => Promise<ExportResult<TSelect>>;
+  input: TExportInput;
+  next: (input?: TExportInput) => Promise<ExportResult<TSelect>>;
 }
 interface ImportMiddlewareParams<TContext> {
   ctx: TContext;
@@ -234,15 +268,15 @@ interface CreateManyMiddlewareParams<TContext, TSelect, TInsert> {
  *   },
  * }
  */
-interface CrudMiddleware<TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown> {
+interface CrudMiddleware<TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown, TListInput extends ListInput = ListInput, TGetInput extends GetInput = GetInput, TExportInput extends ExportInput = ExportInput> {
   /**
    * 列表查询包装器
    */
-  list?: (params: ListMiddlewareParams<TContext, TSelect>) => Promise<ListResult<TSelect>>;
+  list?: (params: ListMiddlewareParams<TContext, TSelect, TListInput>) => Promise<ListResult<TSelect>>;
   /**
    * 单条查询包装器
    */
-  get?: (params: GetMiddlewareParams<TContext, TSelect>) => Promise<TSelect | null>;
+  get?: (params: GetMiddlewareParams<TContext, TSelect, TGetInput>) => Promise<TSelect | null>;
   /**
    * 创建包装器
    */
@@ -281,7 +315,7 @@ interface CrudMiddleware<TContext = unknown, TSelect = unknown, TInsert = unknow
    * 导出包装器
    * 可用于审计日志、限流、异步队列调度
    */
-  export?: (params: ExportMiddlewareParams<TContext, TSelect>) => Promise<ExportResult<TSelect>>;
+  export?: (params: ExportMiddlewareParams<TContext, TSelect, TExportInput>) => Promise<ExportResult<TSelect>>;
   /**
    * 导入包装器
    * 可用于审计日志、限流、异步队列调度
@@ -377,7 +411,7 @@ type ProcedureConfig = AnyProcedure | ProcedureMap | ProcedureFactory;
  *   authorize: (ctx, resource) => resource.ownerId === ctx.user.id,
  * })
  */
-interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown> {
+interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown, TListInput extends ListInput = ListInput, TGetInput extends GetInput = GetInput, TExportInput extends ExportInput = ExportInput> {
   /** Drizzle 表定义 */
   table: TTable;
   /**
@@ -408,6 +442,35 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   updateSchema?: z.ZodType<TUpdate>;
   /** 查询返回 Schema */
   selectSchema?: z.ZodType<TSelect>;
+  /**
+   * 列表查询输入 Schema（可选）
+   * - 默认使用内置基础列表输入：page、perPage、sort、filters、joinOperator
+   * - 业务侧可以基于 baseListInputSchema.extend(...) 增加自定义参数
+   * - 默认查询逻辑只读取基础字段，额外字段会保留给 middleware.list 使用
+   *
+   * @example
+   * listInputSchema: baseListInputSchema.extend({
+   *   include: z.object({ skus: z.boolean().optional() }).optional(),
+   * })
+   */
+  listInputSchema?: z.ZodType<TListInput>;
+  /**
+   * 单条查询输入 Schema（可选）
+   * - 默认兼容 get(id) 和 get({ id })
+   * - 业务侧可以基于 baseGetInputSchema.extend(...) 增加 include 等控制参数
+   * - 配置后仍保留 get(id) 字符串调用兼容性
+   * - 默认查询逻辑只读取 id，额外字段会保留给 middleware.get 使用
+   */
+  getInputSchema?: z.ZodType<Extract<TGetInput, {
+    id: string;
+  }>>;
+  /**
+   * 导出查询输入 Schema（可选）
+   * - 默认使用内置基础导出输入：sort、filters、joinOperator、limit
+   * - 业务侧可以基于 baseExportInputSchema.extend(...) 增加自定义参数
+   * - 默认查询逻辑只读取基础字段，额外字段会保留给 middleware.export 使用
+   */
+  exportInputSchema?: z.ZodType<TExportInput>;
   /**
    * Procedure 配置（统一字段）
    *
@@ -458,10 +521,25 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
   omitFields?: TableColumnKeys<TTable>[];
   /** ID 字段名，默认 "id" */
   idField?: string;
-  /** 可过滤的列白名单 */
-  filterableColumns?: string[];
-  /** 可排序的列白名单 */
-  sortableColumns?: string[];
+  /**
+   * 可过滤的列白名单。
+   *
+   * 普通字段使用字符串；jsonb/i18n 字段可用对象配置 jsonField，
+   * 由服务端显式生成 text expression，前端仍然传 id。
+   *
+   * @example
+   * filterableColumns: [
+   *   'status',
+   *   { id: 'name', jsonField: ['zh-CN', 'en-US', 'en', 'zh'] },
+   * ]
+   */
+  filterableColumns?: CrudColumnRef<TTable>[];
+  /**
+   * 可排序的列白名单。
+   *
+   * 与 filterableColumns 相同，普通字段使用字符串，jsonb/i18n 字段可配置 jsonField。
+   */
+  sortableColumns?: CrudColumnRef<TTable>[];
   /** 批量操作的最大数量限制，默认 100 */
   maxBatchSize?: number;
   /**
@@ -516,7 +594,7 @@ interface CrudRouterConfig<TTable extends PgTable = PgTable, TContext = unknown,
    *   }),
    * }
    */
-  middleware?: CrudMiddleware<TContext, TSelect, TInsert, TUpdate>;
+  middleware?: CrudMiddleware<TContext, TSelect, TInsert, TUpdate, TListInput, TGetInput, TExportInput>;
 }
 interface CrudProcedures {
   list: AnyProcedure;
@@ -540,6 +618,94 @@ interface CrudProcedures {
 type CrudRouterReturn = ReturnType<typeof router> & {
   procedures: CrudProcedures;
 };
+declare const baseListInputSchema: z.ZodObject<{
+  page: z.ZodDefault<z.ZodNumber>;
+  perPage: z.ZodDefault<z.ZodNumber>;
+  sort: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    desc: z.ZodBoolean;
+  }, z.core.$strip>>>;
+  filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    variant: z.ZodEnum<{
+      number: "number";
+      boolean: "boolean";
+      date: "date";
+      text: "text";
+      range: "range";
+      dateRange: "dateRange";
+      select: "select";
+      multiSelect: "multiSelect";
+    }>;
+    operator: z.ZodEnum<{
+      iLike: "iLike";
+      notILike: "notILike";
+      eq: "eq";
+      ne: "ne";
+      isEmpty: "isEmpty";
+      isNotEmpty: "isNotEmpty";
+      lt: "lt";
+      lte: "lte";
+      gt: "gt";
+      gte: "gte";
+      isBetween: "isBetween";
+      isRelativeToToday: "isRelativeToToday";
+      inArray: "inArray";
+      notInArray: "notInArray";
+    }>;
+    filterId: z.ZodString;
+  }, z.core.$strip>>>;
+  joinOperator: z.ZodDefault<z.ZodEnum<{
+    and: "and";
+    or: "or";
+  }>>;
+}, z.core.$strip>;
+declare const baseGetInputSchema: z.ZodObject<{
+  id: z.ZodString;
+}, z.core.$strip>;
+declare const baseExportInputSchema: z.ZodObject<{
+  sort: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    desc: z.ZodBoolean;
+  }, z.core.$strip>>>;
+  filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>;
+    variant: z.ZodEnum<{
+      number: "number";
+      boolean: "boolean";
+      date: "date";
+      text: "text";
+      range: "range";
+      dateRange: "dateRange";
+      select: "select";
+      multiSelect: "multiSelect";
+    }>;
+    operator: z.ZodEnum<{
+      iLike: "iLike";
+      notILike: "notILike";
+      eq: "eq";
+      ne: "ne";
+      isEmpty: "isEmpty";
+      isNotEmpty: "isNotEmpty";
+      lt: "lt";
+      lte: "lte";
+      gt: "gt";
+      gte: "gte";
+      isBetween: "isBetween";
+      isRelativeToToday: "isRelativeToToday";
+      inArray: "inArray";
+      notInArray: "notInArray";
+    }>;
+    filterId: z.ZodString;
+  }, z.core.$strip>>>;
+  joinOperator: z.ZodDefault<z.ZodEnum<{
+    and: "and";
+    or: "or";
+  }>>;
+  limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /**
  * 创建 CRUD Router
  *
@@ -552,7 +718,7 @@ type CrudRouterReturn = ReturnType<typeof router> & {
  * @typeParam TInsert - 创建输入类型
  * @typeParam TUpdate - 更新输入类型
  */
-declare function createCrudRouter<TTable extends PgTable = PgTable, TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown>(config: CrudRouterConfig<TTable, TContext, TSelect, TInsert, TUpdate>): CrudRouterReturn;
+declare function createCrudRouter<TTable extends PgTable = PgTable, TContext = unknown, TSelect = unknown, TInsert = unknown, TUpdate = unknown, TListInput extends ListInput = ListInput, TGetInput extends GetInput = GetInput, TExportInput extends ExportInput = ExportInput>(config: CrudRouterConfig<TTable, TContext, TSelect, TInsert, TUpdate, TListInput, TGetInput, TExportInput>): CrudRouterReturn;
 //#endregion
 //#region src/lib/middleware-helpers.d.ts
 /**
@@ -612,34 +778,6 @@ type AnyMiddlewareParams<TContext> = {
 declare function composeMiddleware<TContext, TResult>(...middlewares: Array<(params: AnyMiddlewareParams<TContext>) => Promise<any>>): (params: AnyMiddlewareParams<TContext>) => Promise<TResult>;
 //#endregion
 //#region src/types/hook-types.d.ts
-/**
- * Hook 系统类型工具
- *
- * 提供 CrudHookEventMap 类型——从 Zod Schema / Drizzle Table 推导出
- * auto-crud 相关的所有 Hook 事件类型。
- *
- * 下游插件通过 module augmentation 合并到全局 HookEventMap：
- *
- * @example
- * ```typescript
- * import type { CrudHookEventMap } from "@wordrhyme/auto-crud-server";
- * import type { z } from "zod";
- * import type { InferSelectModel } from "drizzle-orm";
- *
- * declare module "@wordrhyme/plugin" {
- *   interface HookEventMap extends CrudHookEventMap<
- *     "crm",
- *     "customers",
- *     z.infer<typeof createCustomerSchema>,
- *     z.infer<typeof updateCustomerSchema>,
- *     InferSelectModel<typeof customerTable>
- *   > {}
- * }
- *
- * // 使用效果：
- * // ctx.hooks.emit('crm.customers.  ← IDE 自动补全所有 hook 名和 payload
- * ```
- */
 /**
  * 从 CRUD Schema 类型自动推导 Hook 事件映射
  *
@@ -652,8 +790,11 @@ declare function composeMiddleware<TContext, TResult>(...middlewares: Array<(par
  * @typeParam TCreate     - 创建输入类型（z.infer<typeof createSchema>）
  * @typeParam TUpdate     - 更新输入类型（z.infer<typeof updateSchema>）
  * @typeParam TSelect     - 查询返回类型（InferSelectModel<typeof table>）
+ * @typeParam TListInput  - list procedure 输入类型
+ * @typeParam TGetInput   - get procedure 输入类型
+ * @typeParam TExportInput - export procedure 输入类型
  */
-type CrudHookEventMap<PluginId extends string, ResourceName extends string, TCreate, TUpdate, TSelect> = { [K in `${PluginId}.${ResourceName}.beforeCreate`]: TCreate } & { [K in `${PluginId}.${ResourceName}.afterCreate`]: TSelect } & { [K in `${PluginId}.${ResourceName}.beforeUpdate`]: {
+type CrudHookEventMap<PluginId extends string, ResourceName extends string, TCreate, TUpdate, TSelect, TListInput extends ListInput = ListInput, TGetInput extends GetInput = string, TExportInput extends ExportInput = ExportInput> = { [K in `${PluginId}.${ResourceName}.beforeCreate`]: TCreate } & { [K in `${PluginId}.${ResourceName}.afterCreate`]: TSelect } & { [K in `${PluginId}.${ResourceName}.beforeUpdate`]: {
   id: string;
   data: TUpdate;
 } } & { [K in `${PluginId}.${ResourceName}.afterUpdate`]: TSelect } & { [K in `${PluginId}.${ResourceName}.beforeDelete`]: {
@@ -664,47 +805,18 @@ type CrudHookEventMap<PluginId extends string, ResourceName extends string, TCre
 } } & { [K in `${PluginId}.${ResourceName}.delete`]: string } & { [K in `${PluginId}.${ResourceName}.deleteMany`]: string[] } & { [K in `${PluginId}.${ResourceName}.updateMany`]: {
   ids: string[];
   data: TUpdate;
-} } & { [K in `${PluginId}.${ResourceName}.upsert`]: TCreate } & { [K in `${PluginId}.${ResourceName}.get`]: string } & { [K in `${PluginId}.${ResourceName}.list`]: {
-  page: number;
-  perPage: number;
-  sort?: Array<{
-    id: string;
-    desc: boolean;
-  }>;
-  filters?: Array<{
-    id: string;
-    value: string | string[];
-    variant: string;
-    operator: string;
-    filterId: string;
-  }>;
-  joinOperator: "and" | "or";
-} } & { [K in `${PluginId}.${ResourceName}.export`]: {
-  sort?: Array<{
-    id: string;
-    desc: boolean;
-  }>;
-  filters?: Array<{
-    id: string;
-    value: string | string[];
-    variant: string;
-    operator: string;
-    filterId: string;
-  }>;
-  joinOperator?: "and" | "or";
-  limit?: number;
-} } & { [K in `${PluginId}.${ResourceName}.import`]: {
+} } & { [K in `${PluginId}.${ResourceName}.upsert`]: TCreate } & { [K in `${PluginId}.${ResourceName}.get`]: TGetInput } & { [K in `${PluginId}.${ResourceName}.list`]: TListInput } & { [K in `${PluginId}.${ResourceName}.export`]: TExportInput } & { [K in `${PluginId}.${ResourceName}.import`]: {
   rows: unknown[];
-  onConflict?: "skip" | "upsert" | "error";
+  onConflict?: 'skip' | 'upsert' | 'error';
 } } & { [K in `${PluginId}.${ResourceName}.createMany`]: TCreate[] };
 //#endregion
 //#region src/routers/index.d.ts
-declare const appRouter: _trpc_server0.TRPCBuiltRouter<{
+declare const appRouter: _trpc_server2.TRPCBuiltRouter<{
   ctx: Context;
   meta: object;
-  errorShape: _trpc_server0.TRPCDefaultErrorShape;
+  errorShape: _trpc_server2.TRPCDefaultErrorShape;
   transformer: true;
-}, _trpc_server0.TRPCDecorateCreateRouterOptions<{}>>;
+}, _trpc_server2.TRPCDecorateCreateRouterOptions<{}>>;
 type AppRouter = typeof appRouter;
 //#endregion
-export { type AnyProcedure, type AppRouter, type CreateManyMiddlewareParams, type CreateMiddlewareParams, type CrudHookEventMap, type CrudMiddleware, type CrudOperation, type CrudProcedures, type CrudRouterConfig, type DeleteManyMiddlewareParams, type DeleteMiddlewareParams, type ExportInput, type ExportMiddlewareParams, type ExportResult, 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, beforeMiddleware, composeMiddleware, createCrudRouter, publicProcedure, router };
+export { type AnyProcedure, type AppRouter, type CreateManyMiddlewareParams, type CreateMiddlewareParams, type CrudColumnConfig, type CrudColumnExpression, type CrudColumnRef, 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 };