@nest-omni/core 4.1.3-2 → 4.1.3-20

package/cache/utils/dependency-manager.util.js

@@ -10,7 +10,17 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DependencyManager = void 0;
+/**
+ * Utility class for managing cache dependencies
+ */
 class DependencyManager {
+    /**
+     * Wrap a value with its dependencies
+     *
+     * @param value - The value to cache
+     * @param dependencies - Array of dependencies
+     * @returns Wrapped value with dependency data
+     */
     static wrapWithDependencies(value, dependencies) {
         return __awaiter(this, void 0, void 0, function* () {
             const wrapped = {
@@ -23,6 +33,12 @@ class DependencyManager {
             return wrapped;
         });
     }
+    /**
+     * Capture current state of all dependencies
+     *
+     * @param dependencies - Array of dependencies
+     * @returns Array of dependency data snapshots
+     */
     static captureDependencies(dependencies) {
         return __awaiter(this, void 0, void 0, function* () {
             const results = [];
@@ -36,6 +52,7 @@ class DependencyManager {
                     });
                 }
                 catch (error) {
+                    // Store error state
                     results.push({
                         key: dep.getKey(),
                         data: {
@@ -48,44 +65,67 @@ class DependencyManager {
             return results;
         });
     }
+    /**
+     * Check if any dependencies have changed
+     *
+     * @param dependencies - Current dependencies
+     * @param cachedDependencies - Previously captured dependency data
+     * @returns true if any dependency has changed
+     */
     static areDependenciesChanged(dependencies, cachedDependencies) {
         return __awaiter(this, void 0, void 0, function* () {
+            // No dependencies means never changed
             if (!dependencies || dependencies.length === 0) {
                 return false;
             }
+            // No cached dependency data means changed (first time)
             if (!cachedDependencies || cachedDependencies.length === 0) {
                 return true;
             }
+            // Different number of dependencies means changed
             if (dependencies.length !== cachedDependencies.length) {
                 return true;
             }
+            // Check each dependency
             for (let i = 0; i < dependencies.length; i++) {
                 const dep = dependencies[i];
                 const cached = cachedDependencies[i];
+                // Key mismatch means dependencies changed
                 if (dep.getKey() !== cached.key) {
                     return true;
                 }
                 try {
+                    // Check if this dependency has changed
                     const changed = yield dep.isChanged(cached.data);
                     if (changed) {
                         return true;
                     }
                 }
                 catch (_a) {
+                    // If check fails, consider it changed to be safe
                     return true;
                 }
             }
             return false;
         });
     }
+    /**
+     * Unwrap cached value and validate dependencies
+     *
+     * @param wrapped - Wrapped cached value
+     * @param dependencies - Current dependencies to check
+     * @returns Unwrapped value if valid, null if dependencies changed
+     */
     static unwrapAndValidate(wrapped, dependencies) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!wrapped) {
                 return null;
             }
+            // No dependencies to check, return value
             if (!dependencies || dependencies.length === 0) {
                 return wrapped.value;
             }
+            // Check if dependencies have changed
             const changed = yield this.areDependenciesChanged(dependencies, wrapped.dependencies);
             if (changed) {
                 return null;
@@ -93,6 +133,13 @@ class DependencyManager {
             return wrapped.value;
         });
     }
+    /**
+     * Get which dependencies have changed
+     *
+     * @param dependencies - Current dependencies
+     * @param cachedDependencies - Previously captured dependency data
+     * @returns Array of changed dependency keys
+     */
     static getChangedDependencies(dependencies, cachedDependencies) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!dependencies || dependencies.length === 0) {
@@ -121,6 +168,12 @@ class DependencyManager {
             return changed;
         });
     }
+    /**
+     * Serialize dependencies for storage
+     *
+     * @param dependencies - Dependency data
+     * @returns Serialized string
+     */
     static serializeDependencies(dependencies) {
         try {
             return JSON.stringify(dependencies);
@@ -129,6 +182,12 @@ class DependencyManager {
             return '[]';
         }
     }
+    /**
+     * Deserialize dependencies from storage
+     *
+     * @param serialized - Serialized string
+     * @returns Dependency data array
+     */
     static deserializeDependencies(serialized) {
         try {
             return JSON.parse(serialized);

package/cache/utils/key-generator.util.d.ts

@@ -1,10 +1,52 @@
 import type { CacheKeyOptions } from '../interfaces';
+/**
+ * Utility class for generating cache keys
+ */
 export declare class KeyGenerator {
+    /**
+     * Generate cache key from options and method arguments
+     *
+     * @param options - Cache key options
+     * @param args - Method arguments
+     * @returns Generated cache key
+     */
     static generate(options: CacheKeyOptions, args: any[]): string;
+    /**
+     * Generate key from method arguments
+     *
+     * @param args - Method arguments
+     * @returns Serialized key
+     */
     static generateFromArgs(args: any[]): string;
+    /**
+     * Normalize key (remove invalid characters, enforce length limits)
+     *
+     * @param key - Raw key
+     * @param maxLength - Maximum key length (default 250)
+     * @returns Normalized key
+     */
     static normalize(key: string, maxLength?: number): string;
+    /**
+     * Add namespace to key
+     *
+     * @param key - Original key
+     * @param namespace - Namespace
+     * @returns Namespaced key
+     */
     static addNamespace(key: string, namespace?: string): string;
+    /**
+     * Generate hash code for a string
+     *
+     * @param str - Input string
+     * @returns Hash code as string
+     */
     static hashCode(str: string): string;
+    /**
+     * Parse pattern into segments for matching
+     *
+     * @param pattern - Pattern with wildcards
+     * @returns Pattern segments
+     */
     static parsePattern(pattern: string): {
         prefix: string;
         suffix: string;

package/cache/utils/key-generator.util.js

@@ -1,60 +1,112 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KeyGenerator = void 0;
+/**
+ * Utility class for generating cache keys
+ */
 class KeyGenerator {
+    /**
+     * Generate cache key from options and method arguments
+     *
+     * @param options - Cache key options
+     * @param args - Method arguments
+     * @returns Generated cache key
+     */
     static generate(options, args) {
         let key;
         if (typeof options.key === 'function') {
+            // Dynamic key generation using function
             key = options.key(...args);
         }
         else if (typeof options.key === 'string') {
+            // Static key
             key = options.key;
         }
         else if (options.includeAllArgs) {
+            // Auto-generate key from all arguments
             key = this.generateFromArgs(args);
         }
         else {
+            // Default: use first argument as key
             key = args.length > 0 ? String(args[0]) : 'default';
         }
+        // Add prefix if specified
         if (options.prefix) {
             key = `${options.prefix}${key}`;
         }
         return key;
     }
+    /**
+     * Generate key from method arguments
+     *
+     * @param args - Method arguments
+     * @returns Serialized key
+     */
     static generateFromArgs(args) {
         if (args.length === 0) {
             return 'default';
         }
         try {
+            // Serialize arguments to JSON
             return JSON.stringify(args);
         }
         catch (_a) {
+            // Fallback to string concatenation
             return args.map((arg) => String(arg)).join(':');
         }
     }
+    /**
+     * Normalize key (remove invalid characters, enforce length limits)
+     *
+     * @param key - Raw key
+     * @param maxLength - Maximum key length (default 250)
+     * @returns Normalized key
+     */
     static normalize(key, maxLength = 250) {
+        // Remove or replace invalid characters
         let normalized = key.replace(/[\s\n\r\t]/g, '_');
+        // Enforce length limit
         if (normalized.length > maxLength) {
+            // Use hash for long keys
             const hash = this.hashCode(normalized);
             normalized = normalized.substring(0, maxLength - 10) + '_' + hash;
         }
         return normalized;
     }
+    /**
+     * Add namespace to key
+     *
+     * @param key - Original key
+     * @param namespace - Namespace
+     * @returns Namespaced key
+     */
     static addNamespace(key, namespace) {
         if (!namespace) {
             return key;
         }
         return `${namespace}:${key}`;
     }
+    /**
+     * Generate hash code for a string
+     *
+     * @param str - Input string
+     * @returns Hash code as string
+     */
     static hashCode(str) {
         let hash = 0;
         for (let i = 0; i < str.length; i++) {
             const char = str.charCodeAt(i);
             hash = (hash << 5) - hash + char;
-            hash = hash & hash;
+            hash = hash & hash; // Convert to 32bit integer
         }
         return Math.abs(hash).toString(36);
     }
+    /**
+     * Parse pattern into segments for matching
+     *
+     * @param pattern - Pattern with wildcards
+     * @returns Pattern segments
+     */
     static parsePattern(pattern) {
         const wildcardIndex = pattern.indexOf('*');
         if (wildcardIndex === -1) {

package/common/abstract.entity.d.ts

@@ -1,9 +1,23 @@
 import type { AbstractDto, AbstractTranslationDto } from './dto/abstract.dto';
 import { LanguageCode } from '../constants';
+/**
+ * Abstract DTO-able Entity
+ *
+ * @description Base class that provides toDto functionality without any database fields.
+ * Use this for view entities or other entities that don't need createdAt/updatedAt fields.
+ */
 export declare abstract class AbstractDtoEntity<DTO, O = never> {
     translations?: AbstractTranslationEntity[];
     toDto(options?: O): DTO;
 }
+/**
+ * Abstract Entity
+ *
+ * @description This class is an abstract class for all entities.
+ * It's experimental and recommended using it only in microservice architecture,
+ * otherwise just delete and use your own entity.
+ * Extends AbstractDtoEntity and adds createdAt/updatedAt timestamp fields.
+ */
 export declare abstract class AbstractBaseEntity<DTO, O> extends AbstractDtoEntity<DTO, O> {
     createdAt: Date;
     updatedAt: Date;

package/common/abstract.entity.js

@@ -14,6 +14,12 @@ const typeorm_1 = require("typeorm");
 const decorators_1 = require("../decorators");
 const constants_1 = require("../constants");
 const uuid_1 = require("uuid");
+/**
+ * Abstract DTO-able Entity
+ *
+ * @description Base class that provides toDto functionality without any database fields.
+ * Use this for view entities or other entities that don't need createdAt/updatedAt fields.
+ */
 class AbstractDtoEntity {
     toDto(options) {
         const dtoClass = Object.getPrototypeOf(this).dtoClass;
@@ -24,6 +30,14 @@ class AbstractDtoEntity {
     }
 }
 exports.AbstractDtoEntity = AbstractDtoEntity;
+/**
+ * Abstract Entity
+ *
+ * @description This class is an abstract class for all entities.
+ * It's experimental and recommended using it only in microservice architecture,
+ * otherwise just delete and use your own entity.
+ * Extends AbstractDtoEntity and adds createdAt/updatedAt timestamp fields.
+ */
 class AbstractBaseEntity extends AbstractDtoEntity {
 }
 exports.AbstractBaseEntity = AbstractBaseEntity;

package/common/boilerplate.polyfill.d.ts

@@ -25,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;
@@ -35,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

@@ -30,13 +30,16 @@ 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;
 };
@@ -49,7 +52,7 @@ typeorm_1.SelectQueryBuilder.prototype.searchByString = function (q, columnNames
     }
     this.andWhere(new typeorm_1.Brackets((qb) => {
         for (const item of columnNames) {
-            qb.orWhere(`${item} ILIKE :q`);
+            qb.orWhere(`${item} LIKE :q`);
         }
     }));
     if (options === null || options === void 0 ? void 0 : options.formStart) {
@@ -77,16 +80,22 @@ typeorm_1.SelectQueryBuilder.prototype.paginate = function (pageOptionsDto, opti
         return [entities, pageMetaDto];
     });
 };
+/**
+ * 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);
     });
 };
@@ -106,6 +115,9 @@ typeorm_1.SelectQueryBuilder.prototype.withTenant = function (tenantId, tenantFi
     }
     return this;
 };
+/**
+ * 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;
@@ -124,6 +136,9 @@ typeorm_1.SelectQueryBuilder.prototype.iterate = function (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;
@@ -134,11 +149,13 @@ typeorm_1.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;

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;
     }