@zucker-framework/crud 1.0.1 → 1.0.2

package/README.md

@@ -0,0 +1,11 @@
+# CRUD
+
+## Services with custom dependency injection
+
+Extend `CrudService<T>` when your Nest service has a custom constructor. Inject the configured `DATABASE_ADAPTER` explicitly and pass it, `DynamicQueryService`, and the model name to `super`. `CrudService` has no inherited Nest parameter tokens, so product dependencies cannot accidentally resolve as a database adapter or event bus. `CrudEntity` requires an ID and permits optional timestamps; the host chooses the ordering field. Existing `BaseService<T>` retains its standard injected constructor and delegates to the same implementation.
+
+`BaseController(Entity, options)` accepts `only` (enabled methods), `routes` (method/path overrides and additional decorators), and `queryDto` (the runtime query DTO used by Nest validation). Defaults preserve the existing Framework HTTP surface; single-record `saveOrUpdate` must be explicitly enabled. Pass application policy as a configuration object instead of mutating generated prototypes in consumers. Controller factories are isolated, so configuring one resource does not change another.
+
+## Validated HTTP query DTO
+
+`QueryParamDto` supplies transformation and validation for filters, orderBy, page (default 1), pageSize (default 10, maximum 100), and comma-separated includes/excludes. Non-string projection inputs remain subject to validation instead of throwing inside the transform. `QueryParamEntity` remains the query-builder API; it is not replaced by the transport DTO.

package/dist/index.d.mts

@@ -479,10 +479,17 @@ declare class QueryParamEntity implements DynamicQueryParam {
     private cloneValue;
 }
 
+/** Minimum CRUD record shape; timestamp names/presence belong to the host model. */
+interface CrudEntity {
+    id: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
 /**
  * 链式查询构建器接口
  */
-interface IQueryBuilder<T extends GenericEntity> {
+interface IQueryBuilder<T extends CrudEntity> {
     where<K extends string & keyof T>(field: K, op: string, value: unknown): IQueryBuilder<T>;
     whereEq<K extends string & keyof T>(field: K, value: T[K]): IQueryBuilder<T>;
     in<K extends string & keyof T>(field: K, values: unknown[]): IQueryBuilder<T>;
@@ -531,14 +538,14 @@ interface GroupByQueryArgs {
     _max?: Record<string, boolean>;
 }
 /** JOIN 子句接口 */
-interface IJoinClause<T extends GenericEntity> {
+interface IJoinClause<T extends CrudEntity> {
     on(localField: string, foreignField: string): IQueryBuilder<T>;
 }
 /**
  * 链式查询构建器实现
  * 通过 DatabaseAdapter 执行查询，将链式 API 转换为 Prisma 兼容的查询参数
  */
-declare class QueryBuilder<T extends GenericEntity> implements IQueryBuilder<T> {
+declare class QueryBuilder<T extends CrudEntity> implements IQueryBuilder<T> {
     private readonly db;
     private readonly modelName;
     private _conditions;
@@ -612,9 +619,9 @@ declare class QueryBuilder<T extends GenericEntity> implements IQueryBuilder<T>
  *
  * Subclasses should provide the model name and optionally customize the default order field.
  *
- * @template T - The entity type, must extend GenericEntity
+ * @template T - The entity type, must extend CrudEntity
  */
-declare abstract class BaseService<T extends GenericEntity> {
+declare abstract class CrudService<T extends CrudEntity> {
     protected readonly db: DatabaseAdapter;
     protected readonly dynamicQuery: DynamicQueryService;
     protected readonly eventBus?: TopicEventBus | undefined;
@@ -791,9 +798,16 @@ declare abstract class BaseService<T extends GenericEntity> {
      */
     protected emitEventWithCancelCheck(type: EntityEventType, entity: unknown): Promise<void>;
 }
+/** Nest-injected base retained for consumers whose constructor follows this signature.
+ * Custom constructor layouts should extend CrudService and inject their own dependencies. */
+declare abstract class BaseService<T extends CrudEntity> extends CrudService<T> {
+    constructor(db: DatabaseAdapter, dynamicQuery: DynamicQueryService, modelName: string, eventBus?: TopicEventBus, options?: {
+        defaultOrderField?: string;
+    });
+}
 
-declare class BaseControllerHost<T extends GenericEntity> {
-    protected readonly service: BaseService<T>;
+declare class BaseControllerHost<T extends CrudEntity> {
+    protected readonly service: CrudService<T>;
     create(..._args: unknown[]): Promise<T>;
     findOne(..._args: unknown[]): Promise<T>;
     findAll(..._args: unknown[]): Promise<unknown>;
@@ -831,7 +845,20 @@ declare class BaseControllerHost<T extends GenericEntity> {
         exists: boolean;
     }>;
 }
-declare function BaseController<T extends GenericEntity>(EntityClass: Type<T>): Type<BaseControllerHost<T>>;
+type BaseControllerMethod = Exclude<keyof BaseControllerHost<CrudEntity>, 'service'>;
+interface BaseControllerRouteOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path?: string;
+    decorators?: MethodDecorator[];
+}
+interface BaseControllerOptions {
+    /** Restrict the generated HTTP surface to these operations. Defaults to existing standard routes. */
+    only?: readonly BaseControllerMethod[];
+    routes?: Partial<Record<BaseControllerMethod, BaseControllerRouteOptions | false>>;
+    /** Runtime query DTO for the host's validation/defaults policy. */
+    queryDto?: Type<DynamicQueryParam>;
+}
+declare function BaseController<T extends CrudEntity>(EntityClass: Type<T>, options?: BaseControllerOptions): Type<BaseControllerHost<T>>;
 
 interface CacheEnabledServiceOptions {
     /** 缓存 TTL（毫秒） */
@@ -1331,4 +1358,13 @@ interface CrudOptions {
  */
 declare function CrudControllerFactory<T>(serviceToken: new (...args: unknown[]) => T, options?: CrudOptions): new (...args: unknown[]) => object;
 
-export { ALL_OPERATORS, type AggregateQueryArgs, BaseController, BaseControllerHost, BaseService, BetweenOperator, CRUD_METADATA, CURRENT_USER_PROVIDER, CacheEnabledService, type CacheEnabledServiceOptions, Cacheable, ContainsOperator, CreatorEventListener, CrudControllerFactory, type CrudModuleAsyncOptions, type CrudOptions, type CrudRouteConfig, type CurrentUserProvider, type DynamicQueryParam, DynamicQueryParamService, DynamicQueryService, ENTITY_VALIDATION_REGISTRY, EmptyOperator, EndsWithOperator, type EntityValidationRegistry, EqualsOperator, FILTER_OPERATORS, FilterOperatorFactory, type FilterOperatorType, type GroupByQueryArgs, GtOperator, GteOperator, HasOperator, HasSomeOperator, type IFilterOperator, type IJoinClause, type IQueryBuilder, InMemoryAdapter, InOperator, IsNotNullOperator, IsNullOperator, LikeOperator, LtOperator, LteOperator, NotEmptyOperator, NotEqualsOperator, NotInOperator, NotLikeOperator, type OptimizedQuery, type PaginatedResult, PrismaAdapter, type PrismaAdapterOptions, PrismaDatabaseAdapterModule, type PrismaDatabaseAdapterModuleOptions, QueryAnalyzer, QueryBuilder, QueryParamEntity as QueryParam, QueryParamEntity, type SaveResult, SimpleEntityValidationRegistry, type SoftDeletableEntity, type SoftDeleteQueryOptions, SoftDeleteService, StartsWithOperator, TermExpressionParser, TreeController, TreeControllerHost, TreeService, ValidateEventListener, ZuckerCrudModule, calculateTotalPages, emptyPagerResult, isPaged, mergeSaveResult, noPaging, parseExpression, parseFilterMap, rePaging, toPaginatedResult };
+declare class QueryParamDto {
+    filters?: string;
+    orderBy?: string;
+    page: number;
+    pageSize: number;
+    includes?: string[];
+    excludes?: string[];
+}
+
+export { ALL_OPERATORS, type AggregateQueryArgs, BaseController, BaseControllerHost, type BaseControllerMethod, type BaseControllerOptions, type BaseControllerRouteOptions, BaseService, BetweenOperator, CRUD_METADATA, CURRENT_USER_PROVIDER, CacheEnabledService, type CacheEnabledServiceOptions, Cacheable, ContainsOperator, CreatorEventListener, CrudControllerFactory, type CrudEntity, type CrudModuleAsyncOptions, type CrudOptions, type CrudRouteConfig, CrudService, type CurrentUserProvider, type DynamicQueryParam, DynamicQueryParamService, DynamicQueryService, ENTITY_VALIDATION_REGISTRY, EmptyOperator, EndsWithOperator, type EntityValidationRegistry, EqualsOperator, FILTER_OPERATORS, FilterOperatorFactory, type FilterOperatorType, type GroupByQueryArgs, GtOperator, GteOperator, HasOperator, HasSomeOperator, type IFilterOperator, type IJoinClause, type IQueryBuilder, InMemoryAdapter, InOperator, IsNotNullOperator, IsNullOperator, LikeOperator, LtOperator, LteOperator, NotEmptyOperator, NotEqualsOperator, NotInOperator, NotLikeOperator, type OptimizedQuery, type PaginatedResult, PrismaAdapter, type PrismaAdapterOptions, PrismaDatabaseAdapterModule, type PrismaDatabaseAdapterModuleOptions, QueryAnalyzer, QueryBuilder, QueryParamEntity as QueryParam, QueryParamDto, QueryParamEntity, type SaveResult, SimpleEntityValidationRegistry, type SoftDeletableEntity, type SoftDeleteQueryOptions, SoftDeleteService, StartsWithOperator, TermExpressionParser, TreeController, TreeControllerHost, TreeService, ValidateEventListener, ZuckerCrudModule, calculateTotalPages, emptyPagerResult, isPaged, mergeSaveResult, noPaging, parseExpression, parseFilterMap, rePaging, toPaginatedResult };

package/dist/index.d.ts

@@ -479,10 +479,17 @@ declare class QueryParamEntity implements DynamicQueryParam {
     private cloneValue;
 }
 
+/** Minimum CRUD record shape; timestamp names/presence belong to the host model. */
+interface CrudEntity {
+    id: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+
 /**
  * 链式查询构建器接口
  */
-interface IQueryBuilder<T extends GenericEntity> {
+interface IQueryBuilder<T extends CrudEntity> {
     where<K extends string & keyof T>(field: K, op: string, value: unknown): IQueryBuilder<T>;
     whereEq<K extends string & keyof T>(field: K, value: T[K]): IQueryBuilder<T>;
     in<K extends string & keyof T>(field: K, values: unknown[]): IQueryBuilder<T>;
@@ -531,14 +538,14 @@ interface GroupByQueryArgs {
     _max?: Record<string, boolean>;
 }
 /** JOIN 子句接口 */
-interface IJoinClause<T extends GenericEntity> {
+interface IJoinClause<T extends CrudEntity> {
     on(localField: string, foreignField: string): IQueryBuilder<T>;
 }
 /**
  * 链式查询构建器实现
  * 通过 DatabaseAdapter 执行查询，将链式 API 转换为 Prisma 兼容的查询参数
  */
-declare class QueryBuilder<T extends GenericEntity> implements IQueryBuilder<T> {
+declare class QueryBuilder<T extends CrudEntity> implements IQueryBuilder<T> {
     private readonly db;
     private readonly modelName;
     private _conditions;
@@ -612,9 +619,9 @@ declare class QueryBuilder<T extends GenericEntity> implements IQueryBuilder<T>
  *
  * Subclasses should provide the model name and optionally customize the default order field.
  *
- * @template T - The entity type, must extend GenericEntity
+ * @template T - The entity type, must extend CrudEntity
  */
-declare abstract class BaseService<T extends GenericEntity> {
+declare abstract class CrudService<T extends CrudEntity> {
     protected readonly db: DatabaseAdapter;
     protected readonly dynamicQuery: DynamicQueryService;
     protected readonly eventBus?: TopicEventBus | undefined;
@@ -791,9 +798,16 @@ declare abstract class BaseService<T extends GenericEntity> {
      */
     protected emitEventWithCancelCheck(type: EntityEventType, entity: unknown): Promise<void>;
 }
+/** Nest-injected base retained for consumers whose constructor follows this signature.
+ * Custom constructor layouts should extend CrudService and inject their own dependencies. */
+declare abstract class BaseService<T extends CrudEntity> extends CrudService<T> {
+    constructor(db: DatabaseAdapter, dynamicQuery: DynamicQueryService, modelName: string, eventBus?: TopicEventBus, options?: {
+        defaultOrderField?: string;
+    });
+}
 
-declare class BaseControllerHost<T extends GenericEntity> {
-    protected readonly service: BaseService<T>;
+declare class BaseControllerHost<T extends CrudEntity> {
+    protected readonly service: CrudService<T>;
     create(..._args: unknown[]): Promise<T>;
     findOne(..._args: unknown[]): Promise<T>;
     findAll(..._args: unknown[]): Promise<unknown>;
@@ -831,7 +845,20 @@ declare class BaseControllerHost<T extends GenericEntity> {
         exists: boolean;
     }>;
 }
-declare function BaseController<T extends GenericEntity>(EntityClass: Type<T>): Type<BaseControllerHost<T>>;
+type BaseControllerMethod = Exclude<keyof BaseControllerHost<CrudEntity>, 'service'>;
+interface BaseControllerRouteOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path?: string;
+    decorators?: MethodDecorator[];
+}
+interface BaseControllerOptions {
+    /** Restrict the generated HTTP surface to these operations. Defaults to existing standard routes. */
+    only?: readonly BaseControllerMethod[];
+    routes?: Partial<Record<BaseControllerMethod, BaseControllerRouteOptions | false>>;
+    /** Runtime query DTO for the host's validation/defaults policy. */
+    queryDto?: Type<DynamicQueryParam>;
+}
+declare function BaseController<T extends CrudEntity>(EntityClass: Type<T>, options?: BaseControllerOptions): Type<BaseControllerHost<T>>;
 
 interface CacheEnabledServiceOptions {
     /** 缓存 TTL（毫秒） */
@@ -1331,4 +1358,13 @@ interface CrudOptions {
  */
 declare function CrudControllerFactory<T>(serviceToken: new (...args: unknown[]) => T, options?: CrudOptions): new (...args: unknown[]) => object;
 
-export { ALL_OPERATORS, type AggregateQueryArgs, BaseController, BaseControllerHost, BaseService, BetweenOperator, CRUD_METADATA, CURRENT_USER_PROVIDER, CacheEnabledService, type CacheEnabledServiceOptions, Cacheable, ContainsOperator, CreatorEventListener, CrudControllerFactory, type CrudModuleAsyncOptions, type CrudOptions, type CrudRouteConfig, type CurrentUserProvider, type DynamicQueryParam, DynamicQueryParamService, DynamicQueryService, ENTITY_VALIDATION_REGISTRY, EmptyOperator, EndsWithOperator, type EntityValidationRegistry, EqualsOperator, FILTER_OPERATORS, FilterOperatorFactory, type FilterOperatorType, type GroupByQueryArgs, GtOperator, GteOperator, HasOperator, HasSomeOperator, type IFilterOperator, type IJoinClause, type IQueryBuilder, InMemoryAdapter, InOperator, IsNotNullOperator, IsNullOperator, LikeOperator, LtOperator, LteOperator, NotEmptyOperator, NotEqualsOperator, NotInOperator, NotLikeOperator, type OptimizedQuery, type PaginatedResult, PrismaAdapter, type PrismaAdapterOptions, PrismaDatabaseAdapterModule, type PrismaDatabaseAdapterModuleOptions, QueryAnalyzer, QueryBuilder, QueryParamEntity as QueryParam, QueryParamEntity, type SaveResult, SimpleEntityValidationRegistry, type SoftDeletableEntity, type SoftDeleteQueryOptions, SoftDeleteService, StartsWithOperator, TermExpressionParser, TreeController, TreeControllerHost, TreeService, ValidateEventListener, ZuckerCrudModule, calculateTotalPages, emptyPagerResult, isPaged, mergeSaveResult, noPaging, parseExpression, parseFilterMap, rePaging, toPaginatedResult };
+declare class QueryParamDto {
+    filters?: string;
+    orderBy?: string;
+    page: number;
+    pageSize: number;
+    includes?: string[];
+    excludes?: string[];
+}
+
+export { ALL_OPERATORS, type AggregateQueryArgs, BaseController, BaseControllerHost, type BaseControllerMethod, type BaseControllerOptions, type BaseControllerRouteOptions, BaseService, BetweenOperator, CRUD_METADATA, CURRENT_USER_PROVIDER, CacheEnabledService, type CacheEnabledServiceOptions, Cacheable, ContainsOperator, CreatorEventListener, CrudControllerFactory, type CrudEntity, type CrudModuleAsyncOptions, type CrudOptions, type CrudRouteConfig, CrudService, type CurrentUserProvider, type DynamicQueryParam, DynamicQueryParamService, DynamicQueryService, ENTITY_VALIDATION_REGISTRY, EmptyOperator, EndsWithOperator, type EntityValidationRegistry, EqualsOperator, FILTER_OPERATORS, FilterOperatorFactory, type FilterOperatorType, type GroupByQueryArgs, GtOperator, GteOperator, HasOperator, HasSomeOperator, type IFilterOperator, type IJoinClause, type IQueryBuilder, InMemoryAdapter, InOperator, IsNotNullOperator, IsNullOperator, LikeOperator, LtOperator, LteOperator, NotEmptyOperator, NotEqualsOperator, NotInOperator, NotLikeOperator, type OptimizedQuery, type PaginatedResult, PrismaAdapter, type PrismaAdapterOptions, PrismaDatabaseAdapterModule, type PrismaDatabaseAdapterModuleOptions, QueryAnalyzer, QueryBuilder, QueryParamEntity as QueryParam, QueryParamDto, QueryParamEntity, type SaveResult, SimpleEntityValidationRegistry, type SoftDeletableEntity, type SoftDeleteQueryOptions, SoftDeleteService, StartsWithOperator, TermExpressionParser, TreeController, TreeControllerHost, TreeService, ValidateEventListener, ZuckerCrudModule, calculateTotalPages, emptyPagerResult, isPaged, mergeSaveResult, noPaging, parseExpression, parseFilterMap, rePaging, toPaginatedResult };

package/dist/index.js

@@ -33,6 +33,7 @@ __export(index_exports, {
   ContainsOperator: () => ContainsOperator,
   CreatorEventListener: () => CreatorEventListener,
   CrudControllerFactory: () => CrudControllerFactory,
+  CrudService: () => CrudService,
   DATABASE_ADAPTER: () => import_core2.DATABASE_ADAPTER,
   DynamicQueryParamService: () => DynamicQueryParamService,
   DynamicQueryService: () => DynamicQueryService,
@@ -62,6 +63,7 @@ __export(index_exports, {
   QueryAnalyzer: () => QueryAnalyzer,
   QueryBuilder: () => QueryBuilder,
   QueryParam: () => QueryParamEntity,
+  QueryParamDto: () => QueryParamDto,
   QueryParamEntity: () => QueryParamEntity,
   SimpleEntityValidationRegistry: () => SimpleEntityValidationRegistry,
   SoftDeleteService: () => SoftDeleteService,
@@ -2563,9 +2565,9 @@ function hasErrorCode(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 __name(hasErrorCode, "hasErrorCode");
-var BaseService = class {
+var CrudService = class {
   static {
-    __name(this, "BaseService");
+    __name(this, "CrudService");
   }
   db;
   dynamicQuery;
@@ -3109,6 +3111,14 @@ var BaseService = class {
     }
   }
 };
+var BaseService = class extends CrudService {
+  static {
+    __name(this, "BaseService");
+  }
+  constructor(db, dynamicQuery, modelName, eventBus, options) {
+    super(db, dynamicQuery, modelName, eventBus, options);
+  }
+};
 BaseService = _ts_decorate4([
   (0, import_common4.Injectable)(),
   _ts_param3(0, (0, import_common4.Inject)(import_core2.DATABASE_ADAPTER)),
@@ -3212,7 +3222,7 @@ var BaseControllerHost = class {
     throw new Error("Not implemented");
   }
 };
-function BaseController(EntityClass) {
+function BaseController(EntityClass, options = {}) {
   let BaseControllerHostImpl = class BaseControllerHostImpl {
     static {
       __name(this, "BaseControllerHostImpl");
@@ -3304,6 +3314,10 @@ function BaseController(EntityClass) {
     async findAll(query) {
       return this.service.findAll(query);
     }
+    /** Explicitly opt into single-record upsert through routes/only. */
+    async saveOrUpdate(data) {
+      return this.service.saveOrUpdate(data);
+    }
     // ===================== Save Routes  =====================
     /**
     * 新增单个数据,并返回新增后的数据
@@ -3515,6 +3529,15 @@ function BaseController(EntityClass) {
     ]),
     _ts_metadata4("design:returntype", Promise)
   ], BaseControllerHostImpl.prototype, "findAll", null);
+  _ts_decorate5([
+    (0, import_common5.Patch)("save"),
+    _ts_param4(0, (0, import_common5.Body)()),
+    _ts_metadata4("design:type", Function),
+    _ts_metadata4("design:paramtypes", [
+      typeof Partial === "undefined" ? Object : Partial
+    ]),
+    _ts_metadata4("design:returntype", Promise)
+  ], BaseControllerHostImpl.prototype, "saveOrUpdate", null);
   _ts_decorate5([
     (0, import_common5.Post)(),
     (0, import_swagger.ApiOperation)({
@@ -3628,6 +3651,35 @@ function BaseController(EntityClass) {
     ]),
     _ts_metadata4("design:returntype", Promise)
   ], BaseControllerHostImpl.prototype, "deleteMany", null);
+  const prototype = BaseControllerHostImpl.prototype;
+  const verbs = {
+    GET: import_common5.Get,
+    POST: import_common5.Post,
+    PUT: import_common5.Put,
+    PATCH: import_common5.Patch,
+    DELETE: import_common5.Delete
+  };
+  for (const name of Object.getOwnPropertyNames(prototype)) {
+    if (name === "constructor") continue;
+    const key = name;
+    const route = options.routes?.[key];
+    const enabled = options.only ? options.only.includes(key) : key !== "saveOrUpdate" || route !== void 0;
+    if (!enabled || route === false) {
+      Reflect.deleteProperty(prototype, key);
+      continue;
+    }
+    if (route) {
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+      if (route.method) verbs[route.method](route.path ?? "")(prototype, key, descriptor);
+      else if (route.path !== void 0) throw new Error("A route path override requires an HTTP method");
+      for (const decorator of route.decorators ?? []) decorator(prototype, key, descriptor);
+    }
+  }
+  if (options.queryDto && Object.hasOwn(prototype, "findAll")) {
+    Reflect.defineMetadata("design:paramtypes", [
+      options.queryDto
+    ], prototype, "findAll");
+  }
   return BaseControllerHostImpl;
 }
 __name(BaseController, "BaseController");
@@ -5880,6 +5932,122 @@ function CrudControllerFactory(serviceToken, options = {}) {
   return CrudController;
 }
 __name(CrudControllerFactory, "CrudControllerFactory");
+
+// src/query/query-param.dto.ts
+var import_class_validator = require("class-validator");
+var import_class_transformer = require("class-transformer");
+var import_swagger3 = require("@nestjs/swagger");
+function _ts_decorate13(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate13, "_ts_decorate");
+function _ts_metadata10(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata10, "_ts_metadata");
+var QueryParamDto = class {
+  static {
+    __name(this, "QueryParamDto");
+  }
+  filters;
+  orderBy;
+  page = 1;
+  pageSize = 10;
+  includes;
+  excludes;
+};
+_ts_decorate13([
+  (0, import_swagger3.ApiProperty)({
+    required: false,
+    description: 'JSON\u683C\u5F0F\u7684\u67E5\u8BE2\u6761\u4EF6\uFF0C\u4F8B\u5982: {"name$like":"example","age$gte":18}'
+  }),
+  (0, import_class_validator.IsOptional)(),
+  (0, import_class_validator.IsString)(),
+  _ts_metadata10("design:type", String)
+], QueryParamDto.prototype, "filters", void 0);
+_ts_decorate13([
+  (0, import_swagger3.ApiProperty)({
+    required: false,
+    description: '\u6392\u5E8F\u5B57\u6BB5\uFF0C\u4F8B\u5982: "age desc, createdAt asc"'
+  }),
+  (0, import_class_validator.IsOptional)(),
+  (0, import_class_validator.IsString)(),
+  _ts_metadata10("design:type", String)
+], QueryParamDto.prototype, "orderBy", void 0);
+_ts_decorate13([
+  (0, import_swagger3.ApiProperty)({
+    required: false,
+    default: 1,
+    minimum: 1,
+    description: "\u9875\u7801"
+  }),
+  (0, import_class_validator.IsOptional)(),
+  (0, import_class_transformer.Type)(() => Number),
+  (0, import_class_validator.IsNumber)(),
+  (0, import_class_validator.Min)(1),
+  _ts_metadata10("design:type", Number)
+], QueryParamDto.prototype, "page", void 0);
+_ts_decorate13([
+  (0, import_swagger3.ApiProperty)({
+    required: false,
+    default: 10,
+    minimum: 1,
+    maximum: 100,
+    description: "\u6BCF\u9875\u6761\u6570"
+  }),
+  (0, import_class_validator.IsOptional)(),
+  (0, import_class_transformer.Type)(() => Number),
+  (0, import_class_validator.IsNumber)(),
+  (0, import_class_validator.Min)(1),
+  (0, import_class_validator.Max)(100),
+  _ts_metadata10("design:type", Number)
+], QueryParamDto.prototype, "pageSize", void 0);
+_ts_decorate13([
+  (0, import_swagger3.ApiProperty)({
+    required: false,
+    type: [
+      String
+    ],
+    description: "\u6307\u5B9A\u8FD4\u56DE\u7684\u5B57\u6BB5\uFF0C\u591A\u4E2A\u5B57\u6BB5\u7528\u9017\u53F7\u5206\u9694"
+  }),
+  (0, import_class_validator.IsOptional)(),
+  (0, import_class_transformer.Transform)(({ value }) => {
+    if (!value) return void 0;
+    if (Array.isArray(value) || typeof value !== "string") return value;
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }),
+  (0, import_class_validator.IsArray)(),
+  _ts_metadata10("design:type", Array)
+], QueryParamDto.prototype, "includes", void 0);
+_ts_decorate13([
+  (0, import_swagger3.ApiProperty)({
+    required: false,
+    type: [
+      String
+    ],
+    description: "\u6307\u5B9A\u6392\u9664\u7684\u5B57\u6BB5\uFF0C\u591A\u4E2A\u5B57\u6BB5\u7528\u9017\u53F7\u5206\u9694"
+  }),
+  (0, import_class_validator.IsOptional)(),
+  (0, import_class_transformer.Transform)(({ value }) => {
+    if (!value) return void 0;
+    if (Array.isArray(value) || typeof value !== "string") return value;
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }),
+  (0, import_class_validator.IsArray)(),
+  _ts_metadata10("design:type", Array)
+], QueryParamDto.prototype, "excludes", void 0);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ALL_OPERATORS,
@@ -5894,6 +6062,7 @@ __name(CrudControllerFactory, "CrudControllerFactory");
   ContainsOperator,
   CreatorEventListener,
   CrudControllerFactory,
+  CrudService,
   DATABASE_ADAPTER,
   DynamicQueryParamService,
   DynamicQueryService,
@@ -5923,6 +6092,7 @@ __name(CrudControllerFactory, "CrudControllerFactory");
   QueryAnalyzer,
   QueryBuilder,
   QueryParam,
+  QueryParamDto,
   QueryParamEntity,
   SimpleEntityValidationRegistry,
   SoftDeleteService,

package/dist/index.mjs

@@ -2480,9 +2480,9 @@ function hasErrorCode(error, code) {
   return typeof error === "object" && error !== null && "code" in error && error.code === code;
 }
 __name(hasErrorCode, "hasErrorCode");
-var BaseService = class {
+var CrudService = class {
   static {
-    __name(this, "BaseService");
+    __name(this, "CrudService");
   }
   db;
   dynamicQuery;
@@ -3026,6 +3026,14 @@ var BaseService = class {
     }
   }
 };
+var BaseService = class extends CrudService {
+  static {
+    __name(this, "BaseService");
+  }
+  constructor(db, dynamicQuery, modelName, eventBus, options) {
+    super(db, dynamicQuery, modelName, eventBus, options);
+  }
+};
 BaseService = _ts_decorate4([
   Injectable3(),
   _ts_param3(0, Inject3(DATABASE_ADAPTER2)),
@@ -3129,7 +3137,7 @@ var BaseControllerHost = class {
     throw new Error("Not implemented");
   }
 };
-function BaseController(EntityClass) {
+function BaseController(EntityClass, options = {}) {
   let BaseControllerHostImpl = class BaseControllerHostImpl {
     static {
       __name(this, "BaseControllerHostImpl");
@@ -3221,6 +3229,10 @@ function BaseController(EntityClass) {
     async findAll(query) {
       return this.service.findAll(query);
     }
+    /** Explicitly opt into single-record upsert through routes/only. */
+    async saveOrUpdate(data) {
+      return this.service.saveOrUpdate(data);
+    }
     // ===================== Save Routes  =====================
     /**
     * 新增单个数据,并返回新增后的数据
@@ -3432,6 +3444,15 @@ function BaseController(EntityClass) {
     ]),
     _ts_metadata4("design:returntype", Promise)
   ], BaseControllerHostImpl.prototype, "findAll", null);
+  _ts_decorate5([
+    Patch("save"),
+    _ts_param4(0, Body()),
+    _ts_metadata4("design:type", Function),
+    _ts_metadata4("design:paramtypes", [
+      typeof Partial === "undefined" ? Object : Partial
+    ]),
+    _ts_metadata4("design:returntype", Promise)
+  ], BaseControllerHostImpl.prototype, "saveOrUpdate", null);
   _ts_decorate5([
     Post(),
     ApiOperation({
@@ -3545,6 +3566,35 @@ function BaseController(EntityClass) {
     ]),
     _ts_metadata4("design:returntype", Promise)
   ], BaseControllerHostImpl.prototype, "deleteMany", null);
+  const prototype = BaseControllerHostImpl.prototype;
+  const verbs = {
+    GET: Get,
+    POST: Post,
+    PUT: Put,
+    PATCH: Patch,
+    DELETE: Delete
+  };
+  for (const name of Object.getOwnPropertyNames(prototype)) {
+    if (name === "constructor") continue;
+    const key = name;
+    const route = options.routes?.[key];
+    const enabled = options.only ? options.only.includes(key) : key !== "saveOrUpdate" || route !== void 0;
+    if (!enabled || route === false) {
+      Reflect.deleteProperty(prototype, key);
+      continue;
+    }
+    if (route) {
+      const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+      if (route.method) verbs[route.method](route.path ?? "")(prototype, key, descriptor);
+      else if (route.path !== void 0) throw new Error("A route path override requires an HTTP method");
+      for (const decorator of route.decorators ?? []) decorator(prototype, key, descriptor);
+    }
+  }
+  if (options.queryDto && Object.hasOwn(prototype, "findAll")) {
+    Reflect.defineMetadata("design:paramtypes", [
+      options.queryDto
+    ], prototype, "findAll");
+  }
   return BaseControllerHostImpl;
 }
 __name(BaseController, "BaseController");
@@ -5797,6 +5847,122 @@ function CrudControllerFactory(serviceToken, options = {}) {
   return CrudController;
 }
 __name(CrudControllerFactory, "CrudControllerFactory");
+
+// src/query/query-param.dto.ts
+import { IsOptional, IsString, IsNumber, Min, Max, IsArray } from "class-validator";
+import { Transform, Type } from "class-transformer";
+import { ApiProperty } from "@nestjs/swagger";
+function _ts_decorate13(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
+    r = Reflect.decorate(decorators, target, key, desc);
+  } else {
+    for (var i = decorators.length - 1; i >= 0; i--) {
+      if (d = decorators[i]) {
+        r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+      }
+    }
+  }
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate13, "_ts_decorate");
+function _ts_metadata10(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") {
+    return Reflect.metadata(metadataKey, metadataValue);
+  }
+}
+__name(_ts_metadata10, "_ts_metadata");
+var QueryParamDto = class {
+  static {
+    __name(this, "QueryParamDto");
+  }
+  filters;
+  orderBy;
+  page = 1;
+  pageSize = 10;
+  includes;
+  excludes;
+};
+_ts_decorate13([
+  ApiProperty({
+    required: false,
+    description: 'JSON\u683C\u5F0F\u7684\u67E5\u8BE2\u6761\u4EF6\uFF0C\u4F8B\u5982: {"name$like":"example","age$gte":18}'
+  }),
+  IsOptional(),
+  IsString(),
+  _ts_metadata10("design:type", String)
+], QueryParamDto.prototype, "filters", void 0);
+_ts_decorate13([
+  ApiProperty({
+    required: false,
+    description: '\u6392\u5E8F\u5B57\u6BB5\uFF0C\u4F8B\u5982: "age desc, createdAt asc"'
+  }),
+  IsOptional(),
+  IsString(),
+  _ts_metadata10("design:type", String)
+], QueryParamDto.prototype, "orderBy", void 0);
+_ts_decorate13([
+  ApiProperty({
+    required: false,
+    default: 1,
+    minimum: 1,
+    description: "\u9875\u7801"
+  }),
+  IsOptional(),
+  Type(() => Number),
+  IsNumber(),
+  Min(1),
+  _ts_metadata10("design:type", Number)
+], QueryParamDto.prototype, "page", void 0);
+_ts_decorate13([
+  ApiProperty({
+    required: false,
+    default: 10,
+    minimum: 1,
+    maximum: 100,
+    description: "\u6BCF\u9875\u6761\u6570"
+  }),
+  IsOptional(),
+  Type(() => Number),
+  IsNumber(),
+  Min(1),
+  Max(100),
+  _ts_metadata10("design:type", Number)
+], QueryParamDto.prototype, "pageSize", void 0);
+_ts_decorate13([
+  ApiProperty({
+    required: false,
+    type: [
+      String
+    ],
+    description: "\u6307\u5B9A\u8FD4\u56DE\u7684\u5B57\u6BB5\uFF0C\u591A\u4E2A\u5B57\u6BB5\u7528\u9017\u53F7\u5206\u9694"
+  }),
+  IsOptional(),
+  Transform(({ value }) => {
+    if (!value) return void 0;
+    if (Array.isArray(value) || typeof value !== "string") return value;
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }),
+  IsArray(),
+  _ts_metadata10("design:type", Array)
+], QueryParamDto.prototype, "includes", void 0);
+_ts_decorate13([
+  ApiProperty({
+    required: false,
+    type: [
+      String
+    ],
+    description: "\u6307\u5B9A\u6392\u9664\u7684\u5B57\u6BB5\uFF0C\u591A\u4E2A\u5B57\u6BB5\u7528\u9017\u53F7\u5206\u9694"
+  }),
+  IsOptional(),
+  Transform(({ value }) => {
+    if (!value) return void 0;
+    if (Array.isArray(value) || typeof value !== "string") return value;
+    return value.split(",").map((item) => item.trim()).filter(Boolean);
+  }),
+  IsArray(),
+  _ts_metadata10("design:type", Array)
+], QueryParamDto.prototype, "excludes", void 0);
 export {
   ALL_OPERATORS,
   BaseController,
@@ -5810,6 +5976,7 @@ export {
   ContainsOperator,
   CreatorEventListener,
   CrudControllerFactory,
+  CrudService,
   DATABASE_ADAPTER2 as DATABASE_ADAPTER,
   DynamicQueryParamService,
   DynamicQueryService,
@@ -5839,6 +6006,7 @@ export {
   QueryAnalyzer,
   QueryBuilder,
   QueryParamEntity as QueryParam,
+  QueryParamDto,
   QueryParamEntity,
   SimpleEntityValidationRegistry,
   SoftDeleteService,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zucker-framework/crud",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -23,20 +23,24 @@
     "THIRD_PARTY_NOTICES"
   ],
   "dependencies": {
-    "@zucker-framework/core": "1.0.0"
+    "@zucker-framework/core": "1.0.2"
   },
   "peerDependencies": {
     "@nestjs/common": "^12.0.0",
     "@nestjs/core": "^12.0.0",
     "@nestjs/swagger": "^12.0.0",
-    "@zucker-framework/cache": "1.0.0",
-    "@zucker-framework/event": "1.0.0"
+    "@zucker-framework/cache": "1.0.2",
+    "@zucker-framework/event": "1.0.2",
+    "class-transformer": "^0.5.0",
+    "class-validator": "^0.14.0 || ^0.15.0"
   },
   "devDependencies": {
     "@nestjs/swagger": "^12.0.1",
-    "@zucker-framework/cache": "1.0.0",
-    "@zucker-framework/event": "1.0.0",
-    "@types/node": "^20.19.43"
+    "@zucker-framework/cache": "1.0.2",
+    "@zucker-framework/event": "1.0.2",
+    "@types/node": "^20.19.43",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1"
   },
   "license": "Apache-2.0",
   "author": "Lind",
@@ -50,7 +54,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --external @nestjs/common --external @nestjs/core --external @nestjs/swagger --external @zucker-framework/core --external @zucker-framework/event --external @zucker-framework/cache --external eventemitter2",
+    "build": "tsup src/index.ts --format cjs,esm --dts --external @nestjs/common --external @nestjs/core --external @nestjs/swagger --external @zucker-framework/core --external @zucker-framework/event --external @zucker-framework/cache --external eventemitter2 --external class-transformer --external class-validator",
     "clean": "rm -rf dist",
     "lint": "eslint src/"
   }