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

package/shared/serviceRegistryModule.js

@@ -37,13 +37,18 @@ const nestjs_cls_1 = require("nestjs-cls");
 const redis_lock_1 = require("../redis-lock");
 const typeorm_2 = require("typeorm");
 const vault_1 = require("../vault");
+const validators_1 = require("../validators");
 const providers = [
     services_1.ApiConfigService,
     services_1.ValidatorService,
     services_1.GeneratorService,
     services_1.TranslationService,
+    validators_1.IsExistsValidator,
+    validators_1.IsUniqueValidator,
+    validators_1.CustomValidateValidator,
 ];
 if (!((_a = process === null || process === void 0 ? void 0 : process.env) === null || _a === void 0 ? void 0 : _a.ENV_FILE_PATH)) {
+    // 兼容单元测试，没有加载初始化文件，手动引入
     Promise.resolve().then(() => require('../setup/bootstrap.setup'));
 }
 services_1.ApiConfigService.rootPath = process.env.ROOT_PATH;
@@ -56,19 +61,6 @@ const modules = [
         expandVariables: false,
         envFilePath: [process.env.ENV_FILE_PATH, process.env.BASE_ENV_FILE_PATH],
     }),
-    nestjs_cls_1.ClsModule.forRoot({
-        global: true,
-        middleware: { mount: true, saveReq: true },
-        plugins: [
-            new transactional_1.ClsPluginTransactional({
-                imports: [typeorm_1.TypeOrmModule],
-                adapter: new transactional_adapter_typeorm_1.TransactionalAdapterTypeOrm({
-                    dataSourceToken: typeorm_2.DataSource,
-                }),
-                enableTransactionProxy: true,
-            }),
-        ],
-    }),
     nestjs_pino_1.LoggerModule.forRootAsync({
         inject: [services_1.ApiConfigService],
         useFactory: (config) => config.pinoConfig,
@@ -100,6 +92,24 @@ if (services_1.ApiConfigService.toBoolean(process.env.DB_ENABLED, true)) {
         inject: [services_1.ApiConfigService],
         useFactory: (config) => config.typeormConfig,
     }));
+    modules.push(nestjs_cls_1.ClsModule.forRootAsync({
+        imports: [typeorm_1.TypeOrmModule],
+        useFactory(args) {
+            return {
+                middleware: { mount: true, saveReq: true },
+            };
+        },
+        global: true,
+        plugins: [
+            new transactional_1.ClsPluginTransactional({
+                imports: [typeorm_1.TypeOrmModule],
+                adapter: new transactional_adapter_typeorm_1.TransactionalAdapterTypeOrm({
+                    dataSourceToken: (0, typeorm_1.getDataSourceToken)(),
+                }),
+                enableTransactionProxy: true,
+            }),
+        ]
+    }));
 }
 if (services_1.ApiConfigService.toBoolean(process.env.BULL_ENABLED)) {
     modules.push(bull_1.BullModule.forRootAsync({
@@ -113,6 +123,7 @@ if (services_1.ApiConfigService.toBoolean(process.env.CACHE_ENABLED)) {
         isGlobal: true,
         useFactory: (config, redisService, dataSource) => __awaiter(void 0, void 0, void 0, function* () {
             let redisClient = null;
+            // Try to get Redis client (use default client)
             try {
                 redisClient = redisService.getClient();
             }
@@ -131,6 +142,7 @@ if (services_1.ApiConfigService.toBoolean(process.env.CACHE_ENABLED)) {
         }),
     }));
 }
+// Add RedisLockModule if both Redis and Cache are enabled
 if (services_1.ApiConfigService.toBoolean(process.env.SCHEDULE_ENABLED) &&
     services_1.ApiConfigService.toBoolean(process.env.REDIS_LOCK_ENABLED, true)) {
     modules.push(redis_lock_1.RedisLockModule.forRootAsync({
@@ -138,6 +150,7 @@ if (services_1.ApiConfigService.toBoolean(process.env.SCHEDULE_ENABLED) &&
         isGlobal: true,
         useFactory: (config, redisService) => __awaiter(void 0, void 0, void 0, function* () {
             let redisClient = null;
+            // Try to get Redis client (use default client)
             try {
                 redisClient = redisService.getClient();
             }
@@ -146,7 +159,7 @@ if (services_1.ApiConfigService.toBoolean(process.env.SCHEDULE_ENABLED) &&
             }
             return {
                 redisClient,
-                defaultTtl: config.getNumber('REDIS_LOCK_TTL', 300000),
+                defaultTtl: config.getNumber('REDIS_LOCK_TTL', 300000), // 5 minutes
                 defaultKeyPrefix: config.getString('REDIS_LOCK_KEY_PREFIX', 'lock'),
                 defaultRetryCount: config.getNumber('REDIS_LOCK_RETRY_COUNT', 3),
                 defaultRetryDelay: config.getNumber('REDIS_LOCK_RETRY_DELAY', 200),

package/shared/services/api-config.service.d.ts

@@ -41,6 +41,9 @@ export declare class ApiConfigService {
         password: string;
         db: number;
     };
+    /**
+     * 是否使用Redis，用于health check
+     */
     get isRedisEnabled(): boolean;
     get bullConfig(): BullRootModuleOptions;
     get pinoConfig(): Params;

package/shared/services/api-config.service.js

@@ -99,15 +99,19 @@ let ApiConfigService = ApiConfigService_1 = class ApiConfigService {
                 if (!origin) {
                     return callback(null, true);
                 }
+                // 支持通配符匹配逻辑
                 const isAllowed = allowedDomains.some((domain) => {
+                    // 处理包含通配符的情况（如 *.example.com）
                     if (domain.includes('*')) {
+                        // 将通配符转换为正则表达式
                         const regexPattern = domain
                             .replace(/\./g, '\\.')
-                            .replace(':*', '(:\\d+)?')
+                            .replace(':*', '(:\\d+)?') // 处理端口通配符
                             .replace('*\\.', '(.*\\.)?');
                         const fullRegex = new RegExp(`^https?:\/\/${regexPattern}$`, 'i');
                         return fullRegex.test(origin);
                     }
+                    // 完全匹配（包含端口匹配）
                     return origin === domain || origin.startsWith(`${domain}:`);
                 });
                 isAllowed
@@ -160,6 +164,9 @@ let ApiConfigService = ApiConfigService_1 = class ApiConfigService {
             db: this.getNumber('REDIS_DB'),
         };
     }
+    /**
+     * 是否使用Redis，用于health check
+     */
     get isRedisEnabled() {
         return (this.getBoolean('BULL_ENABLED') ||
             this.getBoolean('CACHE_ENABLED') ||
@@ -168,7 +175,9 @@ let ApiConfigService = ApiConfigService_1 = class ApiConfigService {
     }
     get bullConfig() {
         return {
-            redis: Object.assign(Object.assign({}, this.ioRedisConfig), { retryStrategy: (times) => Math.min(times * 1000, 5000) }),
+            redis: Object.assign(Object.assign({}, this.ioRedisConfig), { 
+                // 增加重连策略
+                retryStrategy: (times) => Math.min(times * 1000, 5000) }),
             prefix: this.getString('BULL_PREFIX'),
             defaultJobOptions: {
                 removeOnComplete: true,
@@ -178,16 +187,18 @@ let ApiConfigService = ApiConfigService_1 = class ApiConfigService {
                     type: 'exponential',
                     delay: this.getNumber('BULL_JOB_BACKOFF_DELAY_MS', 5000),
                 },
-                timeout: this.getNumber('BULL_JOB_TIMEOUT_MS', 30 * 1000),
+                timeout: this.getNumber('BULL_JOB_TIMEOUT_MS', 30 * 1000), // 默认30秒超时
             },
             settings: {
-                maxStalledCount: 2,
-                guardInterval: 5000,
-                retryProcessDelay: 1000,
+                // 增强稳定性配置
+                maxStalledCount: 2, // 最大卡住重试次数
+                guardInterval: 5000, // 检查卡住任务间隔
+                retryProcessDelay: 1000, // 进程重启后的重试延迟
             },
+            // 增加队列级限流配置
             limiter: {
-                max: this.getNumber('BULL_MAX_CONCURRENT_JOBS', 100),
-                duration: 1000,
+                max: this.getNumber('BULL_MAX_CONCURRENT_JOBS', 100), // 最大并发任务数
+                duration: 1000, // 时间窗口
             },
         };
     }
@@ -275,7 +286,7 @@ let ApiConfigService = ApiConfigService_1 = class ApiConfigService {
             if (defaultValue !== undefined) {
                 return defaultValue;
             }
-            throw new Error(`key:'${key}' - environment does not set`);
+            throw new Error(`key:'${key}' - environment does not set`); // probably we should call process.exit() too to avoid locking the service
         }
         return value;
     }

package/validator-json/decorators.d.ts

@@ -1,6 +1,23 @@
 import { ReferenceObject, SchemaObject } from '@nestjs/swagger/dist/interfaces/open-api-spec.interface';
 import 'reflect-metadata';
 import { IOptions } from './options';
+/**
+ * Either a plain JSON Schema object that gets merged into the existing schema,
+ * or a function that receives as parameters the existing schema and global
+ * options, returning an updated schema.
+ */
 export type DecoratorSchema = ReferenceObject | SchemaObject | ((source: SchemaObject, options: IOptions) => ReferenceObject | SchemaObject);
+/**
+ * Supplement class or property with additional JSON Schema keywords.
+ *
+ * @param schema JSON Schema object that is merged into the schema derived from
+ * class-validator decorators. In case of conflicts, keywords defined here
+ * overwrite the existing ones. Alternatively you can supply a function that
+ * receives as parameters the existing schema and global options, returning an
+ * updated schema.
+ */
 export declare function JSONSchema(schema: DecoratorSchema): (target: object | Function, key?: string) => void;
+/**
+ * Get the JSON Schema stored in given target's metadata.
+ */
 export declare function getMetadataSchema(target: object | Function, key: string): DecoratorSchema;

package/validator-json/decorators.js

@@ -4,19 +4,34 @@ exports.JSONSchema = JSONSchema;
 exports.getMetadataSchema = getMetadataSchema;
 require("reflect-metadata");
 const SCHEMA_KEY = Symbol('class-validator-jsonschema:JSONSchema');
+/**
+ * Supplement class or property with additional JSON Schema keywords.
+ *
+ * @param schema JSON Schema object that is merged into the schema derived from
+ * class-validator decorators. In case of conflicts, keywords defined here
+ * overwrite the existing ones. Alternatively you can supply a function that
+ * receives as parameters the existing schema and global options, returning an
+ * updated schema.
+ */
 function JSONSchema(schema) {
     return (target, key) => {
         if (key) {
-            setMetadataSchema(schema, target.constructor, key);
+            setMetadataSchema(schema, target.constructor, key); // Property metadata
         }
         else {
-            setMetadataSchema(schema, target, target.name);
+            setMetadataSchema(schema, target, target.name); // Class metadata
         }
     };
 }
+/**
+ * Get the JSON Schema stored in given target's metadata.
+ */
 function getMetadataSchema(target, key) {
     return Reflect.getMetadata(SCHEMA_KEY, target.constructor, key) || {};
 }
+/**
+ * Store given JSON Schema into target object's metadata.
+ */
 function setMetadataSchema(value, target, key) {
     return Reflect.defineMetadata(SCHEMA_KEY, value, target, key);
 }

package/validator-json/default.d.ts

@@ -2,5 +2,11 @@ import { ValidationMetadata } from 'class-validator/types/metadata/ValidationMet
 import { IOptions } from './options';
 import { I18nService } from 'nestjs-i18n';
 export { JSONSchema } from './decorators';
+/**
+ * Convert an array of class-validator metadata into JSON Schema definitions.
+ */
 export declare function validationMetadataArrayToSchemas(metadatas: ValidationMetadata[], i18n: any, userOptions?: Partial<IOptions>): any;
+/**
+ * Generate JSON Schema definitions from the target object constructor.
+ */
 export declare function targetConstructorToSchema(targetConstructor: Function, i18n: I18nService, userOptions?: Partial<IOptions>): any;

package/validator-json/default.js

@@ -9,6 +9,9 @@ const defaultConverters_1 = require("./defaultConverters");
 const options_1 = require("./options");
 var decorators_1 = require("./decorators");
 Object.defineProperty(exports, "JSONSchema", { enumerable: true, get: function () { return decorators_1.JSONSchema; } });
+/**
+ * Convert an array of class-validator metadata into JSON Schema definitions.
+ */
 function validationMetadataArrayToSchemas(metadatas, i18n, userOptions) {
     const options = Object.assign(Object.assign({}, options_1.defaultOptions), userOptions);
     const rules = [];
@@ -46,6 +49,9 @@ function getFirstNonNullDataType(data) {
     }
     return undefined;
 }
+/**
+ * Generate JSON Schema definitions from the target object constructor.
+ */
 function targetConstructorToSchema(targetConstructor, i18n, userOptions) {
     const options = Object.assign(Object.assign({}, options_1.defaultOptions), userOptions);
     const storage = options.classValidatorMetadataStorage;
@@ -64,6 +70,15 @@ function populateMetadatasWithConstraints(storage, metadatas) {
         return Object.assign({}, meta);
     });
 }
+/**
+ * Return target class' inherited validation metadatas, with original metadatas
+ * given precedence over inherited ones in case of duplicates.
+ *
+ * Adapted from `class-validator` source.
+ *
+ * @param target Target child class.
+ * @param metadatas All class-validator metadata objects.
+ */
 function getInheritedMetadatas(target, metadatas) {
     return metadatas.filter((d) => d.target instanceof Function &&
         target.prototype instanceof d.target &&
@@ -71,6 +86,9 @@ function getInheritedMetadatas(target, metadatas) {
             m.target === target &&
             m.type === d.type));
 }
+/**
+ * Convert a property's class-validator metadata into a JSON Schema property.
+ */
 function applyConverters(propertyMetadatas, options, i18n) {
     const converters = Object.assign(Object.assign({}, defaultConverters_1.defaultConverters), options.additionalConverters);
     const convert = (meta) => {
@@ -83,12 +101,13 @@ function applyConverters(propertyMetadatas, options, i18n) {
         const converterResult = typeof converter === 'function' ? converter(meta, options) : converter;
         const items = {};
         let message = '';
+        // @ts-ignore
         const originMessage = typeof meta.message === 'function'
             ? meta.message({
-                value: undefined,
+                value: undefined, // We don't have the actual value in this context
                 constraints: meta.constraints,
                 targetName: meta.target.name || '',
-                object: {},
+                object: {}, // We don't have the actual object in this context
                 property: meta.propertyName,
             })
             : meta.message;
@@ -109,15 +128,23 @@ function applyConverters(propertyMetadatas, options, i18n) {
         }
         return meta.each ? { items, type: 'array' } : items;
     };
+    // const constraints = [];
     const constraints = propertyMetadatas.map((meta) => {
         return convert(meta);
     });
     return (0, lodash_1.reject)(constraints, (item) => (0, lodash_1.isEmpty)(item));
 }
+/** Check whether property is excluded with class-transformer `@Exclude` decorator. */
 function isExcluded(propertyMetadata, options) {
     var _a;
     return !!((_a = options.classTransformerMetadataStorage) === null || _a === void 0 ? void 0 : _a.findExcludeMetadata(propertyMetadata.target, propertyMetadata.propertyName));
 }
+/**
+ * Get the required property names of a validated class.
+ * @param target Validation target class.
+ * @param metadatas Validation metadata objects of the validated class.
+ * @param options Global class-validator options.
+ */
 function getRequiredPropNames(target, metadatas, options) {
     function isDefined(metas) {
         return (metas && metas.some(({ type }) => type === cv.ValidationTypes.IS_DEFINED));
@@ -127,6 +154,7 @@ function getRequiredPropNames(target, metadatas, options) {
             metas.some(({ type }) => [cv.ValidationTypes.CONDITIONAL_VALIDATION, cv.IS_EMPTY].includes(type)));
     }
     return (Object.entries((0, lodash_1.groupBy)(metadatas, (m) => m.propertyName))
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
         .filter(([_, metas]) => {
         const own = metas.filter((m) => m.target === target);
         const inherited = metas.filter((m) => m.target !== target);

package/validator-json/defaultConverters.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultConverters = void 0;
+// tslint:disable:no-submodule-imports
 const cv = require("class-validator");
 require("reflect-metadata");
 exports.defaultConverters = {

package/validator-json/options.d.ts

@@ -2,10 +2,33 @@ import type { MetadataStorage as ClassTransformerMetadataStorage } from 'class-t
 import { MetadataStorage, ValidatorOptions } from 'class-validator';
 import { ISchemaConverters } from './defaultConverters';
 export interface IOptions extends ValidatorOptions {
+    /**
+     * A map of additional metadata-to-schema converters that can be used to
+     * supplement or override the default ones. The key should correspond to the
+     * 'type' property of a ValidationMetadata object.
+     */
     additionalConverters: ISchemaConverters;
+    /**
+     * Metadata storage instance of class-transformer. This value can be
+     * optionally defined in order for class-transformer's @Type decorators to
+     * have effect in JSON Schema generation.
+     */
     classTransformerMetadataStorage?: ClassTransformerMetadataStorage;
+    /**
+     * Metadata storage instance of class-validator. This value can be
+     * optionally defined in order to override the default storage used
+     * to parse decorator metadata.
+     */
     classValidatorMetadataStorage: MetadataStorage;
+    /**
+     * A prefix added to all `$ref` JSON pointers referencing other schemas.
+     * Defaults to '#/definitions/'.
+     */
     refPointerPrefix: string;
+    /**
+     * Property used to group schemas.
+     * Defaults to `name`, i.e., class name.
+     */
     schemaNameField: string;
 }
 export declare const defaultOptions: IOptions;

package/validators/common-validators.d.ts

@@ -0,0 +1,143 @@
+import type { ValidationOptions } from 'class-validator';
+import { IsPhoneNumber as isPhoneNumber, ValidationArguments, ValidatorConstraintInterface } from 'class-validator';
+/**
+ * 验证密码格式（只允许字母、数字和特定特殊字符）
+ *
+ * @param validationOptions 验证选项
+ *
+ * @example
+ * ```typescript
+ * class UserDto {
+ *   @IsPassword({ message: 'Invalid password format' })
+ *   password: string;
+ * }
+ * ```
+ */
+export declare function IsPassword(validationOptions?: ValidationOptions): PropertyDecorator;
+/**
+ * 验证手机号码（支持指定国家/地区）
+ *
+ * @param validationOptions 验证选项，可以指定 region
+ *
+ * @example
+ * ```typescript
+ * class ContactDto {
+ *   @IsPhoneNumber({ region: 'CN' })
+ *   phone: string;
+ * }
+ * ```
+ */
+export declare function IsPhoneNumber(validationOptions?: ValidationOptions & {
+    region?: Parameters<typeof isPhoneNumber>[0];
+}): PropertyDecorator;
+/**
+ * 验证临时文件路径（必须以 tmp/ 开头）
+ *
+ * @param validationOptions 验证选项
+ *
+ * @example
+ * ```typescript
+ * class FileDto {
+ *   @IsTmpKey()
+ *   filePath: string; // 必须是 'tmp/...'
+ * }
+ * ```
+ */
+export declare function IsTmpKey(validationOptions?: ValidationOptions): PropertyDecorator;
+/**
+ * 允许字段为 undefined，如果不是 undefined 才执行其他验证
+ *
+ * @param options 验证选项
+ *
+ * @example
+ * ```typescript
+ * class UserDto {
+ *   @IsUndefinable()
+ *   @IsString()
+ *   nickname?: string; // undefined 或字符串
+ * }
+ * ```
+ */
+export declare function IsUndefinable(options?: ValidationOptions): PropertyDecorator;
+/**
+ * 允许字段为空值（null、undefined 或空字符串），如果不为空才执行其他验证
+ *
+ * @param options 验证选项
+ *
+ * @example
+ * ```typescript
+ * class UserDto {
+ *   @IsEmptyable()
+ *   @IsEmail()
+ *   email?: string; // 可以为空，或者必须是有效邮箱
+ * }
+ * ```
+ */
+export declare function IsEmptyable(options?: ValidationOptions): PropertyDecorator;
+/**
+ * 允许字段为 null，如果不是 null 才执行其他验证
+ *
+ * @param options 验证选项
+ *
+ * @example
+ * ```typescript
+ * class UserDto {
+ *   @IsNullable()
+ *   @IsNumber()
+ *   age?: number | null; // null 或数字
+ * }
+ * ```
+ */
+export declare function IsNullable(options?: ValidationOptions): PropertyDecorator;
+/**
+ * 验证 HTTP/HTTPS URL
+ *
+ * @param validationOptions 验证选项
+ *
+ * @example
+ * ```typescript
+ * class WebsiteDto {
+ *   @IsHttpUrl({ message: 'Invalid URL' })
+ *   url: string;
+ * }
+ * ```
+ */
+export declare function IsHttpUrl(validationOptions?: ValidationOptions): (object: any, propertyName: string) => void;
+/**
+ * Validator constraint for AtLeastOneField decorator
+ */
+export declare class AtLeastOneFieldConstraint implements ValidatorConstraintInterface {
+    validate(value: any, args: ValidationArguments): boolean;
+    defaultMessage(args: ValidationArguments): string;
+}
+/**
+ * 验证至少提供指定字段中的一个
+ *
+ * @param properties 要检查的属性名数组
+ * @param validationOptions 验证选项
+ *
+ * @example
+ * ```typescript
+ * class ContactDto {
+ *   @AtLeastOneField(['email', 'phone'], {
+ *     message: 'Either email or phone must be provided'
+ *   })
+ *   email?: string;
+ *
+ *   phone?: string;
+ * }
+ * ```
+ *
+ * @example
+ * 使用虚拟字段（推荐用于类级别验证）：
+ * ```typescript
+ * class ContactDto {
+ *   @AtLeastOneField(['email', 'phone'])
+ *   _atLeastOne: any; // 虚拟字段用于验证
+ *
+ *   email?: string;
+ *   phone?: string;
+ * }
+ * ```
+ */
+export declare function AtLeastOneField(properties: string[], validationOptions?: ValidationOptions): PropertyDecorator;