@nest-omni/core 4.1.3-1 → 4.1.3-11

package/common/boilerplate.polyfill.d.ts

@@ -16,10 +16,6 @@ declare global {
     }
 }
 declare module 'typeorm' {
-    interface Repository<Entity extends ObjectLiteral> {
-        saveWithPk(this: Repository<Entity>, entity: Entity | Entity[]): Promise<Entity | Entity[]>;
-        getPrimaryKeyFields(this: Repository<Entity>): string[];
-    }
     interface SelectQueryBuilder<Entity> {
         searchByString(q: string, columnNames: string[], options?: {
             formStart: boolean;
@@ -29,6 +25,91 @@ declare module 'typeorm' {
             takeAll: boolean;
             skipCount: boolean;
         }>): Promise<[Entity[], PageMetaDto]>;
+        /**
+         * Paginate and automatically map entities to DTOs in a single call.
+         * This method combines paginate() and toPageDto() into one convenient method.
+         *
+         * @param pageOptionsDto Pagination options (page, pageSize, order, etc.)
+         * @param options Configuration options
+         * @param options.dtoOptions Options to pass to the toDto() method of each entity
+         * @param options.skipCount Skip counting total items (improves performance)
+         * @param options.takeAll Fetch all items without limit (ignores pageSize)
+         * @param options.transform Optional callback to transform items before mapping to DTOs (supports both sync and async)
+         *
+         * @example
+         * Basic usage - automatically maps entities to DTOs:
+         * ```typescript
+         * const queryBuilder = userRepository.createQueryBuilder('user');
+         * const pageDto = await queryBuilder.paginateAndMap(pageOptionsDto);
+         * return pageDto; // Returns PageDto<UserDto>
+         * ```
+         *
+         * @example
+         * With toDto options:
+         * ```typescript
+         * const queryBuilder = userRepository.createQueryBuilder('user');
+         * const pageDto = await queryBuilder.paginateAndMap(pageOptionsDto, {
+         *   dtoOptions: { includeRelations: true }
+         * });
+         * ```
+         *
+         * @example
+         * With synchronous transform callback:
+         * ```typescript
+         * const queryBuilder = orderRepository.createQueryBuilder('order');
+         * const pageDto = await queryBuilder.paginateAndMap(pageOptionsDto, {
+         *   transform: (items) => items.filter(order => order.status === 'active')
+         * });
+         * ```
+         *
+         * @example
+         * With async transform callback for complex operations:
+         * ```typescript
+         * const queryBuilder = orderRepository.createQueryBuilder('order');
+         * const pageDto = await queryBuilder.paginateAndMap(pageOptionsDto, {
+         *   transform: async (items) => {
+         *     // Perform async operations on items
+         *     const enrichedItems = await Promise.all(
+         *       items.map(async (order) => {
+         *         order.additionalData = await externalService.getData(order.id);
+         *         return order;
+         *       })
+         *     );
+         *     return enrichedItems.filter(order => order.isValid);
+         *   }
+         * });
+         * ```
+         *
+         * @example
+         * Complete example with all options:
+         * ```typescript
+         * const queryBuilder = productRepository
+         *   .createQueryBuilder('product')
+         *   .leftJoinAndSelect('product.category', 'category')
+         *   .where('product.isActive = :isActive', { isActive: true });
+         *
+         * const pageDto = await queryBuilder.paginateAndMap(pageOptionsDto, {
+         *   dtoOptions: { includeCategory: true },
+         *   skipCount: false,
+         *   transform: async (items) => {
+         *     // Enrich products with external data
+         *     const enrichedProducts = await Promise.all(
+         *       items.map(async (product) => {
+         *         product.reviews = await reviewService.getReviews(product.id);
+         *         return product;
+         *       })
+         *     );
+         *     // Filter out products with no stock
+         *     return enrichedProducts.filter(product => product.stock > 0);
+         *   }
+         * });
+         *
+         * // Returns PageDto<ProductDto> with enriched and filtered data
+         * return pageDto;
+         * ```
+         *
+         * @returns Promise resolving to PageDto with mapped DTOs
+         */
         paginateAndMap<Dto extends AbstractDto, DtoOptions = unknown>(this: SelectQueryBuilder<Entity>, pageOptionsDto: PageOptionsDto, options?: Partial<{
             dtoOptions: DtoOptions;
             skipCount: boolean;
@@ -39,9 +120,66 @@ declare module 'typeorm' {
         leftJoin<AliasEntity extends AbstractEntity, A extends string>(this: SelectQueryBuilder<Entity>, property: `${A}.${Exclude<KeyOfType<AliasEntity, AbstractEntity>, symbol>}`, alias: string, condition?: string, parameters?: ObjectLiteral): this;
         innerJoinAndSelect<AliasEntity extends AbstractEntity, A extends string>(this: SelectQueryBuilder<Entity>, property: `${A}.${Exclude<KeyOfType<AliasEntity, AbstractEntity>, symbol>}`, alias: string, condition?: string, parameters?: ObjectLiteral): this;
         innerJoin<AliasEntity extends AbstractEntity, A extends string>(this: SelectQueryBuilder<Entity>, property: `${A}.${Exclude<KeyOfType<AliasEntity, AbstractEntity>, symbol>}`, alias: string, condition?: string, parameters?: ObjectLiteral): this;
+        /**
+         * Iterate over entity results in batches using async iteration.
+         *
+         * @param options.batchSize Number of entities to retrieve per batch (default: 1000)
+         *
+         * @example
+         * ```typescript
+         * const queryBuilder = repository.createQueryBuilder('entity');
+         *
+         * for await (const batch of queryBuilder.iterate({ batchSize: 500 })) {
+         *   console.log(`Processing batch of ${batch.length} entities`);
+         *   // Process each batch of entities
+         *   await processEntities(batch);
+         * }
+         * ```
+         *
+         * @returns An async iterator that yields arrays of entities
+         */
         iterate(this: SelectQueryBuilder<Entity>, options?: {
             batchSize?: number;
         }): AsyncIterableIterator<Entity[]>;
+        /**
+         * Process entity results in batches by calling a callback function.
+         * The callback can accept either individual entities or batches of entities.
+         *
+         * @param callback Function to process each entity or batch of entities
+         * @param options
+         * @param options.batchSize Number of entities to retrieve per batch (default: 1000)
+         * @param options.mode Whether to pass entities individually or as batches to the callback (default: 'batch')
+         *
+         * @example
+         * Processing individual entities:
+         * ```typescript
+         * const queryBuilder = repository.createQueryBuilder('entity');
+         *
+         * await queryBuilder.eachBatch(
+         *   async (entity) => {
+         *     // Process each individual entity
+         *     console.log(`Processing entity: ${entity.id}`);
+         *     await processEntity(entity);
+         *   },
+         *   { batchSize: 100, mode: 'single' }
+         * );
+         * ```
+         *
+         * @example
+         * Processing batches of entities:
+         * ```typescript
+         * const queryBuilder = repository.createQueryBuilder('entity');
+         *
+         * await queryBuilder.eachBatch(
+         *   async (batch) => {
+         *     // Process each batch of entities
+         *     console.log(`Processing batch of ${batch.length} entities`);
+         *     await processEntities(batch);
+         *   },
+         *   { batchSize: 500, mode: 'batch' }
+         * );
+         * ```
+         */
         eachBatch(this: SelectQueryBuilder<Entity>, callback: (item: Entity) => Promise<void> | void, options?: {
             batchSize?: number;
             mode?: 'single';

package/common/boilerplate.polyfill.js

@@ -25,30 +25,32 @@ Object.defineProperty(exports, "__esModule", { value: true });
 require("source-map-support/register");
 const lodash_1 = require("lodash");
 const typeorm_1 = require("typeorm");
-const typeorm_2 = require("typeorm");
 const page_dto_1 = require("./dto/page.dto");
 const page_meta_dto_1 = require("./dto/page-meta.dto");
 const providers_1 = require("../providers");
 Array.prototype.toDtos = function (options) {
     return (0, lodash_1.compact)((0, lodash_1.map)(this, (item) => {
+        // Check if item exists and has toDto method
         if (item && typeof item.toDto === 'function') {
             return item.toDto(options);
         }
+        // Skip items that don't have toDto method
         return undefined;
     }));
 };
 Array.prototype.getByLanguage = function (languageCode) {
+    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
     return this.find((translation) => languageCode === translation.languageCode)
         .text;
 };
 Array.prototype.toPageDto = function (pageMetaDto, options) {
     return new page_dto_1.PageDto(this.toDtos(options), pageMetaDto);
 };
-typeorm_2.SelectQueryBuilder.prototype.searchByString = function (q, columnNames, options) {
+typeorm_1.SelectQueryBuilder.prototype.searchByString = function (q, columnNames, options) {
     if (!q) {
         return this;
     }
-    this.andWhere(new typeorm_2.Brackets((qb) => {
+    this.andWhere(new typeorm_1.Brackets((qb) => {
         for (const item of columnNames) {
             qb.orWhere(`${item} ILIKE :q`);
         }
@@ -61,7 +63,7 @@ typeorm_2.SelectQueryBuilder.prototype.searchByString = function (q, columnNames
     }
     return this;
 };
-typeorm_2.SelectQueryBuilder.prototype.paginate = function (pageOptionsDto, options) {
+typeorm_1.SelectQueryBuilder.prototype.paginate = function (pageOptionsDto, options) {
     return __awaiter(this, void 0, void 0, function* () {
         if (!(options === null || options === void 0 ? void 0 : options.takeAll)) {
             this.skip(pageOptionsDto.skip).take(pageOptionsDto.pageSize);
@@ -78,20 +80,26 @@ typeorm_2.SelectQueryBuilder.prototype.paginate = function (pageOptionsDto, opti
         return [entities, pageMetaDto];
     });
 };
-typeorm_2.SelectQueryBuilder.prototype.paginateAndMap = function (pageOptionsDto, options) {
+/**
+ * Implementation of paginateAndMap
+ */
+typeorm_1.SelectQueryBuilder.prototype.paginateAndMap = function (pageOptionsDto, options) {
     return __awaiter(this, void 0, void 0, function* () {
+        // Call paginate to get entities and meta
         const [entities, pageMetaDto] = yield this.paginate(pageOptionsDto, {
             skipCount: options === null || options === void 0 ? void 0 : options.skipCount,
             takeAll: options === null || options === void 0 ? void 0 : options.takeAll,
         });
+        // Apply transform if provided (support both sync and async)
         let transformedEntities = entities;
         if (options === null || options === void 0 ? void 0 : options.transform) {
             transformedEntities = yield options.transform(entities);
         }
+        // Convert to DTOs and return PageDto
         return transformedEntities.toPageDto(pageMetaDto, options === null || options === void 0 ? void 0 : options.dtoOptions);
     });
 };
-typeorm_2.SelectQueryBuilder.prototype.withTenant = function (tenantId, tenantFieldName = 'tenantId') {
+typeorm_1.SelectQueryBuilder.prototype.withTenant = function (tenantId, tenantFieldName = 'tenantId') {
     var _a;
     if (!tenantId) {
         tenantId = providers_1.ContextProvider.getTenantId();
@@ -107,7 +115,10 @@ typeorm_2.SelectQueryBuilder.prototype.withTenant = function (tenantId, tenantFi
     }
     return this;
 };
-typeorm_2.SelectQueryBuilder.prototype.iterate = function (options) {
+/**
+ * Implementation for the async iterator method
+ */
+typeorm_1.SelectQueryBuilder.prototype.iterate = function (options) {
     return __asyncGenerator(this, arguments, function* () {
         const batchSize = (options === null || options === void 0 ? void 0 : options.batchSize) || 100;
         let offset = 0;
@@ -125,7 +136,10 @@ typeorm_2.SelectQueryBuilder.prototype.iterate = function (options) {
         }
     });
 };
-typeorm_2.SelectQueryBuilder.prototype.eachBatch = function (callback, options) {
+/**
+ * Implementation for the callback-based iteration method
+ */
+typeorm_1.SelectQueryBuilder.prototype.eachBatch = function (callback, options) {
     return __awaiter(this, void 0, void 0, function* () {
         const batchSize = (options === null || options === void 0 ? void 0 : options.batchSize) || 100;
         const mode = (options === null || options === void 0 ? void 0 : options.mode) || 'batch';
@@ -135,11 +149,13 @@ typeorm_2.SelectQueryBuilder.prototype.eachBatch = function (callback, options)
             const batch = yield this.clone().skip(offset).take(batchSize).getMany();
             if (batch.length > 0) {
                 if (mode === 'single') {
+                    // Process each entity individually
                     for (const item of batch) {
                         yield callback(item);
                     }
                 }
                 else {
+                    // Process the entire batch
                     yield callback(batch);
                 }
                 offset += batchSize;
@@ -151,95 +167,3 @@ typeorm_2.SelectQueryBuilder.prototype.eachBatch = function (callback, options)
         }
     });
 };
-const insertWithPk = function (entity) {
-    return __awaiter(this, void 0, void 0, function* () {
-        if (!this.metadata) {
-            throw new Error('Repository metadata is not available. Make sure the repository is properly initialized.');
-        }
-        const tableName = this.metadata.tableName;
-        const columns = this.metadata.columns;
-        const columnNames = [];
-        const columnValues = [];
-        const valuePlaceholders = [];
-        for (const column of columns) {
-            const propertyName = column.propertyName;
-            const value = entity[propertyName];
-            if (value === undefined) {
-                continue;
-            }
-            const columnName = column.databaseName;
-            if (columnName) {
-                columnNames.push(columnName);
-                columnValues.push(value);
-                valuePlaceholders.push(`?`);
-            }
-        }
-        const sql = `INSERT INTO ${tableName} (${columnNames.join(', ')}) VALUES (${valuePlaceholders.join(', ')})`;
-        try {
-            const result = yield this.query(sql, columnValues);
-            return result[0];
-        }
-        catch (error) {
-            console.warn(`Native SQL insert failed for ${tableName}, falling back to regular save:`, error);
-            return yield this.save(entity);
-        }
-    });
-};
-typeorm_1.Repository.prototype.getPrimaryKeyFields = function () {
-    if (!this.metadata) {
-        throw new Error('Repository metadata is not available. Make sure the repository is properly initialized.');
-    }
-    const primaryKeys = this.metadata.primaryColumns;
-    if (!primaryKeys || primaryKeys.length === 0) {
-        throw new Error(`Entity ${this.metadata.targetName} does not have any primary key columns defined.`);
-    }
-    return primaryKeys.map(column => column.propertyName);
-};
-typeorm_1.Repository.prototype.saveWithPk = function (entity) {
-    return __awaiter(this, void 0, void 0, function* () {
-        const isArray = Array.isArray(entity);
-        const entities = isArray ? entity : [entity];
-        if (entities.length === 0) {
-            return isArray ? [] : null;
-        }
-        const pkFields = this.getPrimaryKeyFields();
-        const results = yield Promise.all(entities.map((singleEntity) => __awaiter(this, void 0, void 0, function* () {
-            const hasPkValues = pkFields.every(pkField => {
-                const value = singleEntity[pkField];
-                return value !== undefined && value !== null && value !== '';
-            });
-            if (hasPkValues) {
-                try {
-                    const existingEntity = yield this.findOne({
-                        where: pkFields.reduce((acc, pkField) => {
-                            acc[pkField] = singleEntity[pkField];
-                            return acc;
-                        }, {})
-                    });
-                    if (existingEntity) {
-                        yield this.update(pkFields.reduce((acc, pkField) => {
-                            acc[pkField] = singleEntity[pkField];
-                            return acc;
-                        }, {}), singleEntity);
-                        return yield this.findOne({
-                            where: pkFields.reduce((acc, pkField) => {
-                                acc[pkField] = singleEntity[pkField];
-                                return acc;
-                            }, {})
-                        });
-                    }
-                    else {
-                        return yield insertWithPk.call(this, singleEntity);
-                    }
-                }
-                catch (error) {
-                    return yield insertWithPk.call(this, singleEntity);
-                }
-            }
-            else {
-                return yield this.save(singleEntity);
-            }
-        })));
-        return isArray ? results : results[0];
-    });
-};

package/common/dto/dto-container.d.ts

@@ -1,9 +1,25 @@
+/**
+ * DTO容器 - 类似class-validator的useContainer机制
+ * 全局存储服务容器，供DTO转换时使用
+ */
 export declare class DtoContainer {
     private static instance;
     private container;
     static getInstance(): DtoContainer;
+    /**
+     * 设置容器 - 类似useContainer
+     */
     static useContainer(container: any): void;
+    /**
+     * 获取服务实例
+     */
     static get<T = any>(serviceToken: string | symbol | any): Promise<T | null>;
+    /**
+     * 检查容器是否已初始化
+     */
     static isInitialized(): boolean;
+    /**
+     * 重置容器 (主要用于测试)
+     */
     static reset(): void;
 }

package/common/dto/dto-container.js

@@ -10,6 +10,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DtoContainer = void 0;
+/**
+ * DTO容器 - 类似class-validator的useContainer机制
+ * 全局存储服务容器，供DTO转换时使用
+ */
 class DtoContainer {
     constructor() {
         this.container = null;
@@ -20,9 +24,15 @@ class DtoContainer {
         }
         return DtoContainer.instance;
     }
+    /**
+     * 设置容器 - 类似useContainer
+     */
     static useContainer(container) {
         DtoContainer.getInstance().container = container;
     }
+    /**
+     * 获取服务实例
+     */
     static get(serviceToken) {
         return __awaiter(this, void 0, void 0, function* () {
             const instance = DtoContainer.getInstance();
@@ -31,13 +41,17 @@ class DtoContainer {
                 return null;
             }
             try {
+                // 支持多种容器类型
                 if (typeof instance.container.get === 'function') {
+                    // NestJS容器
                     return yield instance.container.get(serviceToken);
                 }
                 else if (typeof instance.container.resolve === 'function') {
+                    // ModuleRef
                     return yield instance.container.resolve(serviceToken);
                 }
                 else if (typeof instance.container[serviceToken] === 'function') {
+                    // 直接的服务实例
                     return instance.container[serviceToken];
                 }
                 console.warn(`Unable to resolve service: ${String(serviceToken)}`);
@@ -49,9 +63,15 @@ class DtoContainer {
             }
         });
     }
+    /**
+     * 检查容器是否已初始化
+     */
     static isInitialized() {
         return DtoContainer.getInstance().container !== null;
     }
+    /**
+     * 重置容器 (主要用于测试)
+     */
     static reset() {
         DtoContainer.getInstance().container = null;
     }

package/common/dto/dto-decorators.d.ts

@@ -1,18 +1,36 @@
 import { Constructor } from '../types';
 import { TransformFnParams } from 'class-transformer';
+/**
+ * 扩展的TransformFnParams，包含context
+ */
 export interface ExtendedTransformFnParams extends TransformFnParams {
     context?: any;
 }
+/**
+ * DTO服务装饰器 - 标记可以在DTO中使用的服务
+ */
 export declare const DTO_SERVICE_KEY = "dto:service-name";
 export declare function DtoService(serviceName?: string): ClassDecorator;
+/**
+ * 使用服务装饰器 - 在DTO类中声明需要的服务
+ */
 export declare const DTO_REQUIRED_SERVICES_KEY = "dto:required-services";
 export declare function UseServices(...serviceTokens: Array<string | Constructor<any>>): ClassDecorator;
+/**
+ * DTO类装饰器 - 标记这是一个DTO类并关联到Entity
+ */
 export declare const DTO_ENTITY_KEY = "dto:entity";
 export declare function Dto(entityClass: Constructor<any>): ClassDecorator;
+/**
+ * DTO字段装饰器 - 类似@Column，用于DTO类
+ */
 export interface DtoFieldOptions {
     source?: string;
     transform?: (value: any) => any;
 }
 export declare function DtoField(source?: string, transform?: (value: any) => any): PropertyDecorator;
 export declare function DtoField(options?: DtoFieldOptions): PropertyDecorator;
+/**
+ * DTO计算字段装饰器 - 用于需要计算的复杂字段
+ */
 export declare function DtoComputed(computeFn: (entity: any, context?: any) => any): PropertyDecorator;

package/common/dto/dto-decorators.js

@@ -7,6 +7,9 @@ exports.Dto = Dto;
 exports.DtoField = DtoField;
 exports.DtoComputed = DtoComputed;
 const common_1 = require("@nestjs/common");
+/**
+ * DTO服务装饰器 - 标记可以在DTO中使用的服务
+ */
 exports.DTO_SERVICE_KEY = 'dto:service-name';
 function DtoService(serviceName) {
     return function (target) {
@@ -14,18 +17,26 @@ function DtoService(serviceName) {
         (0, common_1.SetMetadata)(exports.DTO_SERVICE_KEY, name)(target);
     };
 }
+/**
+ * 使用服务装饰器 - 在DTO类中声明需要的服务
+ */
 exports.DTO_REQUIRED_SERVICES_KEY = 'dto:required-services';
 function UseServices(...serviceTokens) {
     return function (target) {
+        // 将Constructor转换为服务名
         const tokens = serviceTokens.map(token => {
             if (typeof token === 'string') {
                 return token;
             }
+            // 假设服务名就是类名的小写版本
             return token.name.charAt(0).toLowerCase() + token.name.slice(1);
         });
         (0, common_1.SetMetadata)(exports.DTO_REQUIRED_SERVICES_KEY, tokens)(target);
     };
 }
+/**
+ * DTO类装饰器 - 标记这是一个DTO类并关联到Entity
+ */
 exports.DTO_ENTITY_KEY = 'dto:entity';
 function Dto(entityClass) {
     return function (target) {
@@ -46,6 +57,9 @@ function DtoField(sourceOrOptions, transform) {
         Reflect.defineMetadata('dto:fields', fields, target.constructor);
     };
 }
+/**
+ * DTO计算字段装饰器 - 用于需要计算的复杂字段
+ */
 function DtoComputed(computeFn) {
     return function (target, propertyKey) {
         const fields = Reflect.getMetadata('dto:fields', target.constructor) || [];

package/common/dto/dto-extensions.d.ts

@@ -1,11 +1,22 @@
 import { Constructor } from '../types';
 declare global {
     interface Array<T> {
+        /**
+         * 将实体数组转换为DTO数组
+         * @param dtoClass DTO类
+         * @param context 转换上下文
+         */
         toDto<DtoType>(dtoClass: Constructor<DtoType>, context?: any): Promise<DtoType[]>;
     }
 }
 declare module 'typeorm' {
     interface SelectQueryBuilder<Entity> {
+        /**
+         * 执行分页查询并转换为DTO页面
+         * @param pageOptionsDto 分页选项
+         * @param dtoClass DTO类
+         * @param context 转换上下文
+         */
         toDtoPage<DtoType>(pageOptionsDto: any, dtoClass: Constructor<DtoType>, context?: any): Promise<any>;
     }
 }

package/common/dto/dto-extensions.js

@@ -12,6 +12,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.transformEntityToDto = transformEntityToDto;
 const typeorm_1 = require("typeorm");
 const dto_transformer_1 = require("./dto-transformer");
+// 实现Array.toDto方法
 Array.prototype.toDto = function (dtoClass, context) {
     return __awaiter(this, void 0, void 0, function* () {
         if (!this || this.length === 0) {
@@ -20,6 +21,7 @@ Array.prototype.toDto = function (dtoClass, context) {
         return yield dto_transformer_1.DtoTransformer.transformArray(this, dtoClass, context);
     });
 };
+// 避免直接修改Object原型，改为使用独立的函数
 function transformEntityToDto(entity, dtoClass, context) {
     return __awaiter(this, void 0, void 0, function* () {
         if (!entity) {
@@ -28,21 +30,28 @@ function transformEntityToDto(entity, dtoClass, context) {
         return yield dto_transformer_1.DtoTransformer.transform(entity, dtoClass, context);
     });
 }
+// 实现QueryBuilder.toDtoPage方法
 typeorm_1.SelectQueryBuilder.prototype.toDtoPage = function (pageOptionsDto, dtoClass, context) {
     return __awaiter(this, void 0, void 0, function* () {
         const page = pageOptionsDto.page || 1;
         const pageSize = pageOptionsDto.pageSize || 10;
         const skip = (page - 1) * pageSize;
+        // 获取总数
         const total = yield this.getCount();
+        // 应用分页
         const entities = yield this.skip(skip).take(pageSize).getMany();
         const count = entities.length;
+        // 调试：输出原始实体数据
         if (count) {
             console.log('Raw entity sample:', JSON.stringify(entities[0], null, 2));
         }
+        // 转换为DTO
         const data = yield entities.toDto(dtoClass, context);
+        // 调试：输出转换后的DTO数据
         if (data.length > 0) {
             console.log('Converted DTO sample:', JSON.stringify(data[0], null, 2));
         }
+        // 计算分页信息
         const pageCount = Math.ceil(total / pageSize);
         const hasPreviousPage = page > 1;
         const hasNextPage = page < pageCount;

package/common/dto/dto-service-accessor.d.ts

@@ -1,7 +1,24 @@
 import { Constructor } from '../types';
+/**
+ * DTO服务访问器 - 使用全局容器获取服务
+ * 类似class-validator的useContainer机制
+ */
 export declare class DtoServiceAccessor {
+    /**
+     * 获取服务实例
+     */
     static getService<T = any>(serviceToken: string | symbol | Constructor<any>): Promise<T | null>;
+    /**
+     * 批量获取服务
+     */
     static getServices<T = any>(serviceTokens: Array<string | symbol | Constructor<any>>): Promise<Record<string, T>>;
+    /**
+     * 为特定DTO类获取所需服务
+     * 基于预定义的服务依赖列表
+     */
     static getServicesForDto(dtoClass: Constructor<any>): Promise<Record<string, any>>;
+    /**
+     * 检查是否已初始化
+     */
     static isInitialized(): boolean;
 }