@nest-omni/core 4.1.3-3 → 4.1.3-31

package/common/boilerplate.polyfill.js

@@ -52,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) {
@@ -167,3 +167,20 @@ typeorm_1.SelectQueryBuilder.prototype.eachBatch = function (callback, options)
         }
     });
 };
+typeorm_1.SelectQueryBuilder.prototype.findField = function (field) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const alias = this.alias;
+        const fieldName = String(field);
+        const results = yield this.clone()
+            .select(`${alias}.${fieldName}`, fieldName)
+            .getRawMany();
+        if (results.length === 0) {
+            return null;
+        }
+        const values = results.map((result) => result[fieldName]);
+        if (values.length === 1) {
+            return values[0];
+        }
+        return values;
+    });
+};

package/common/helpers/validation-metadata-helper.d.ts

@@ -0,0 +1,112 @@
+import type { Constructor } from '../types';
+/**
+ * 字段元数据接口（简化版）
+ * 用于在验证错误时生成友好的错误消息
+ */
+export interface ValidationMetadata {
+    /** 字段名称 */
+    fieldName?: string;
+    /** i18n 翻译键 */
+    i18nKey?: string;
+    /** 字段标签（多语言）- 使用 fieldLabel 避免命名冲突 */
+    label?: string | {
+        zh?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    /** 字段描述（多语言）- 使用 fieldDescription 避免命名冲突 */
+    description?: string | {
+        zh?: string;
+        en?: string;
+        [lang: string]: string | undefined;
+    };
+    /** 是否为数组 */
+    each?: boolean;
+}
+/**
+ * i18n 翻译函数类型
+ */
+type I18nTranslateFunction = (key: string, options?: any) => string | Promise<string>;
+/**
+ * 设置全局 i18n 翻译函数
+ *
+ * @example
+ * // 在 app.module.ts 或 main.ts 中设置
+ * import { setI18nTranslate } from './common/helpers/validation-metadata-helper';
+ * import { I18nService } from 'nestjs-i18n';
+ *
+ * setI18nTranslate((key, options) => i18nService.translate(key, options));
+ */
+export declare function setI18nTranslate(fn: I18nTranslateFunction): void;
+/**
+ * 获取全局 i18n 翻译函数
+ */
+export declare function getI18nTranslate(): I18nTranslateFunction | null;
+/**
+ * 解析字段标签
+ * 支持以下格式：
+ * 1. i18n key 字符串: "user.username"
+ * 2. 多语言对象: { zh: '用户名', en: 'Username' }
+ * 3. 普通字符串: "Username"
+ *
+ * @param label - 字段标签
+ * @param i18nKey - i18n 翻译键（优先使用）
+ * @param lang - 语言代码 (zh, en, 等)
+ * @returns 解析后的标签文本
+ */
+export declare function resolveFieldLabel(label: string | {
+    zh?: string;
+    en?: string;
+    [lang: string]: string | undefined;
+} | undefined, i18nKey?: string, lang?: string): string | {
+    zh?: string;
+    en?: string;
+    [lang: string]: string | undefined;
+};
+/**
+ * 翻译字段标签
+ * 将 i18n key 或多语言对象解析为最终文本
+ *
+ * @param labelOrKey - 标签、i18n key 或多语言对象
+ * @param lang - 语言代码
+ * @returns 翻译后的文本
+ */
+export declare function translateFieldLabel(labelOrKey: string | {
+    zh?: string;
+    en?: string;
+    [lang: string]: string | undefined;
+}, lang?: string): Promise<string>;
+/**
+ * 存储验证元数据到装饰器
+ *
+ * @param target - 目标类
+ * @param propertyKey - 属性名
+ * @param metadata - 验证元数据
+ */
+export declare function setValidationMetadata(target: Constructor<any>, propertyKey: string, metadata: ValidationMetadata): void;
+/**
+ * 获取验证元数据
+ *
+ * @param target - 目标类
+ * @param propertyKey - 属性名
+ * @returns 验证元数据
+ */
+export declare function getValidationMetadata(target: Constructor<any>, propertyKey: string): ValidationMetadata | undefined;
+/**
+ * 获取所有验证元数据
+ *
+ * @param target - 目标类
+ * @returns 所有验证元数据
+ */
+export declare function getAllValidationMetadata(target: Constructor<any>): Record<string, ValidationMetadata>;
+/**
+ * 获取字段的友好标签
+ * 根据语言环境返回对应的标签
+ * 支持优先级：fieldLabel > i18nKey > fieldName
+ *
+ * @param metadata - 验证元数据
+ * @param lang - 语言 (zh, en, 等)
+ * @returns 字段标签
+ */
+export declare function getFieldLabelForValidation(metadata: ValidationMetadata, lang?: string): string;
+export {};

package/common/helpers/validation-metadata-helper.js

@@ -0,0 +1,164 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setI18nTranslate = setI18nTranslate;
+exports.getI18nTranslate = getI18nTranslate;
+exports.resolveFieldLabel = resolveFieldLabel;
+exports.translateFieldLabel = translateFieldLabel;
+exports.setValidationMetadata = setValidationMetadata;
+exports.getValidationMetadata = getValidationMetadata;
+exports.getAllValidationMetadata = getAllValidationMetadata;
+exports.getFieldLabelForValidation = getFieldLabelForValidation;
+/**
+ * 全局 i18n 翻译函数（由应用设置）
+ */
+let globalI18nTranslate = null;
+/**
+ * 设置全局 i18n 翻译函数
+ *
+ * @example
+ * // 在 app.module.ts 或 main.ts 中设置
+ * import { setI18nTranslate } from './common/helpers/validation-metadata-helper';
+ * import { I18nService } from 'nestjs-i18n';
+ *
+ * setI18nTranslate((key, options) => i18nService.translate(key, options));
+ */
+function setI18nTranslate(fn) {
+    globalI18nTranslate = fn;
+}
+/**
+ * 获取全局 i18n 翻译函数
+ */
+function getI18nTranslate() {
+    return globalI18nTranslate;
+}
+/**
+ * 解析字段标签
+ * 支持以下格式：
+ * 1. i18n key 字符串: "user.username"
+ * 2. 多语言对象: { zh: '用户名', en: 'Username' }
+ * 3. 普通字符串: "Username"
+ *
+ * @param label - 字段标签
+ * @param i18nKey - i18n 翻译键（优先使用）
+ * @param lang - 语言代码 (zh, en, 等)
+ * @returns 解析后的标签文本
+ */
+function resolveFieldLabel(label, i18nKey, lang = 'zh') {
+    // 如果有 i18n key，返回 i18n key 对象（延迟解析）
+    if (i18nKey) {
+        return i18nKey;
+    }
+    // 如果有直接提供的 label
+    if (label) {
+        return label;
+    }
+    // 默认返回空字符串
+    return '';
+}
+/**
+ * 翻译字段标签
+ * 将 i18n key 或多语言对象解析为最终文本
+ *
+ * @param labelOrKey - 标签、i18n key 或多语言对象
+ * @param lang - 语言代码
+ * @returns 翻译后的文本
+ */
+function translateFieldLabel(labelOrKey_1) {
+    return __awaiter(this, arguments, void 0, function* (labelOrKey, lang = 'zh') {
+        // 如果是普通字符串，直接返回
+        if (typeof labelOrKey === 'string') {
+            // 尝试作为 i18n key 翻译
+            if (globalI18nTranslate && labelOrKey.includes('.')) {
+                try {
+                    const translated = yield globalI18nTranslate(labelOrKey, { lang });
+                    if (translated && translated !== labelOrKey) {
+                        return translated;
+                    }
+                }
+                catch (_a) {
+                    // 翻译失败，返回原始 key
+                }
+            }
+            return labelOrKey;
+        }
+        // 如果是多语言对象，返回对应语言的文本
+        if (typeof labelOrKey === 'object' && labelOrKey !== null) {
+            return (labelOrKey[lang] ||
+                labelOrKey.zh ||
+                labelOrKey.en ||
+                Object.values(labelOrKey).find((v) => v) ||
+                '');
+        }
+        return '';
+    });
+}
+/**
+ * 验证元数据存储键
+ */
+const VALIDATION_METADATA_KEY = 'VALIDATION_METADATA_OPTIONS';
+/**
+ * 存储验证元数据到装饰器
+ *
+ * @param target - 目标类
+ * @param propertyKey - 属性名
+ * @param metadata - 验证元数据
+ */
+function setValidationMetadata(target, propertyKey, metadata) {
+    const existingMetadata = Reflect.getMetadata(VALIDATION_METADATA_KEY, target) || {};
+    existingMetadata[propertyKey] = metadata;
+    Reflect.defineMetadata(VALIDATION_METADATA_KEY, existingMetadata, target);
+}
+/**
+ * 获取验证元数据
+ *
+ * @param target - 目标类
+ * @param propertyKey - 属性名
+ * @returns 验证元数据
+ */
+function getValidationMetadata(target, propertyKey) {
+    const allMetadata = Reflect.getMetadata(VALIDATION_METADATA_KEY, target);
+    const metadata = allMetadata === null || allMetadata === void 0 ? void 0 : allMetadata[propertyKey];
+    return metadata;
+}
+/**
+ * 获取所有验证元数据
+ *
+ * @param target - 目标类
+ * @returns 所有验证元数据
+ */
+function getAllValidationMetadata(target) {
+    return Reflect.getMetadata(VALIDATION_METADATA_KEY, target) || {};
+}
+/**
+ * 获取字段的友好标签
+ * 根据语言环境返回对应的标签
+ * 支持优先级：fieldLabel > i18nKey > fieldName
+ *
+ * @param metadata - 验证元数据
+ * @param lang - 语言 (zh, en, 等)
+ * @returns 字段标签
+ */
+function getFieldLabelForValidation(metadata, lang = 'zh') {
+    // 如果有 fieldLabel，直接使用
+    if (metadata.label) {
+        if (typeof metadata.label === 'string') {
+            return metadata.label;
+        }
+        return metadata.label[lang] || metadata.label.zh || metadata.label.en || '';
+    }
+    // 如果有 i18nKey，返回 i18nKey（会在运行时翻译）
+    if (metadata.i18nKey) {
+        return metadata.i18nKey;
+    }
+    // 默认返回字段名
+    return metadata.fieldName || '';
+}

package/common/index.d.ts

@@ -4,3 +4,4 @@ export * from './dto';
 export * from './types';
 export * from './snake-naming.strategy';
 export * from './boilerplate.polyfill';
+export * from './helpers/validation-metadata-helper';

package/common/index.js

@@ -20,3 +20,7 @@ __exportStar(require("./dto"), exports);
 __exportStar(require("./types"), exports);
 __exportStar(require("./snake-naming.strategy"), exports);
 __exportStar(require("./boilerplate.polyfill"), exports);
+// ========================================
+// Validation Metadata Helper
+// ========================================
+__exportStar(require("./helpers/validation-metadata-helper"), exports);

package/decorators/examples/field-i18n.example.d.ts

@@ -0,0 +1,294 @@
+/**
+ * 字段装饰器 i18n 翻译使用示例
+ *
+ * 本示例演示如何使用 fieldI18n 选项通过 i18n key 进行多语言转换
+ *
+ * 注意：此示例文件仅供参考，展示如何使用 fieldI18n 选项。
+ * 如果使用 TypeScript 5+ 的新装饰器语法，需要确保 tsconfig.json 中
+ * "experimentalDecorators" 设置为 true。
+ */
+/**
+ * 在应用启动时（如 app.module.ts 或 main.ts）配置 i18n 翻译函数
+ *
+ * @example
+ * // app.module.ts
+ * import { setI18nTranslate } from '@your-lib/core';
+ *
+ *@Module({
+ *   imports: [
+ *     ConfigModule.forRoot(),
+ *     I18nModule.forRoot({
+ *       fallbackLanguage: 'en',
+ *       loader: TranslationsLoader({
+ *         config: {
+ *           defaultLanguage: 'zh',
+ *           languages: ['zh', 'en'],
+ *           types: ['validation', 'field'],
+ *         },
+ *       }),
+ *     }),
+ *   ],
+ *   providers: [AppService],
+ * })
+ * export class AppModule implements OnModuleInit {
+ *   constructor(private readonly i18n: I18nService) {}
+ *
+ *   async onModuleInit() {
+ *     // 设置全局 i18n 翻译函数
+ *     setI18nTranslate((key, options) => this.i18n.translate(key, options));
+ *   }
+ * }
+ */
+/**
+ * 翻译文件结构示例 (src/i18n/zh.json):
+ *
+ * {
+ *   "field": {
+ *     "user": {
+ *       "username": "用户名",
+ *       "email": "邮箱",
+ *       "phone": "手机号",
+ *       "role": "角色",
+ *       "status": "状态",
+ *       "description": "个人简介"
+ *     },
+ *     "product": {
+ *       "name": "产品名称",
+ *       "price": "价格",
+ *       "stock": "库存",
+ *       "status": "产品状态"
+ *     }
+ *   },
+ *   "field.value": {
+ *     "user.role": {
+ *       "user": "普通用户",
+ *       "admin": "管理员",
+ *       "vip": "VIP用户"
+ *     },
+ *     "user.status": {
+ *       "active": "正常",
+ *       "inactive": "未激活",
+ *       "suspended": "已暂停"
+ *     }
+ *   }
+ * }
+ *
+ * 翻译文件结构示例 (src/i18n/en.json):
+ *
+ * {
+ *   "field": {
+ *     "user": {
+ *       "username": "Username",
+ *       "email": "Email",
+ *       "phone": "Phone Number",
+ *       "role": "Role",
+ *       "status": "Status",
+ *       "description": "Bio"
+ *     },
+ *     "product": {
+ *       "name": "Product Name",
+ *       "price": "Price",
+ *       "stock": "Stock",
+ *       "status": "Product Status"
+ *     }
+ *   },
+ *   "field.value": {
+ *     "user.role": {
+ *       "user": "User",
+ *       "admin": "Administrator",
+ *       "vip": "VIP User"
+ *     },
+ *     "user.status": {
+ *       "active": "Active",
+ *       "inactive": "Inactive",
+ *       "suspended": "Suspended"
+ *     }
+ *   }
+ * }
+ */
+/**
+ * 用户 DTO - 使用 i18n key
+ */
+export declare class CreateUserDto {
+    username: string;
+    email: string;
+    phone?: string;
+    description?: string;
+    emailVerified?: boolean;
+}
+/**
+ * 产品 DTO - 使用 i18n key
+ */
+export declare class CreateProductDto {
+    name: string;
+    price: number;
+    stock: number;
+}
+declare enum UserRole {
+    USER = "user",
+    ADMIN = "admin",
+    VIP = "vip"
+}
+declare enum UserStatus {
+    ACTIVE = "active",
+    INACTIVE = "inactive",
+    SUSPENDED = "suspended"
+}
+/**
+ * 用户更新 DTO - 枚举字段使用 i18n
+ */
+export declare class UpdateUserDto {
+    role: UserRole;
+    status: UserStatus;
+}
+/**
+ * 验证错误过滤器示例
+ *
+ * @example
+ * import { getValidationMetadata, getFieldLabelForValidation } from '@your-lib/core';
+ *
+ * @Catch(ValidationError)
+ * export class ValidationErrorFilter implements ExceptionFilter {
+ *   catch(exception: ValidationError, host: ArgumentsHost) {
+ *     const ctx = host.switchToHttp();
+ *     const response = ctx.getResponse<Response>();
+ *     const request = ctx.getRequest<Request>();
+ *     const language = request.headers['accept-language'] || 'zh';
+ *
+ *     const errors = exception.errors.map(error => {
+ *       const metadata = getValidationMetadata(error.target.constructor, error.property);
+ *       const fieldLabel = getFieldLabelForValidation(metadata, language);
+ *
+ *       // 如果 fieldLabel 是 i18n key，需要翻译
+ *       const displayLabel = fieldLabel.includes('.')
+ *         ? this.i18n.translate(fieldLabel, { lang: language })
+ *         : fieldLabel;
+ *
+ *       return {
+ *         field: error.property,
+ *         fieldLabel: displayLabel,
+ *         constraints: error.constraints,
+ *       };
+ *     });
+ *
+ *     response.status(400).json({
+ *       statusCode: 400,
+ *       message: 'Validation failed',
+ *       errors,
+ *     });
+ *   }
+ * }
+ */
+/**
+ * 审计日志服务示例
+ *
+ * @example
+ * import { getAuditMetadata } from '@your-lib/core';
+ *
+ * @Injectable()
+ * export class AuditService {
+ *   constructor(private readonly i18n: I18nService) {}
+ *
+ *   async logFieldChange(
+ *     entity: any,
+ *     field: string,
+ *     oldValue: any,
+ *     newValue: any,
+ *     language: string = 'zh',
+ *   ) {
+ *     const metadata = getAuditMetadata(entity.constructor, field);
+ *
+ *     // 翻译字段标签
+ *     let fieldLabel = metadata?.label || field;
+ *     if (typeof fieldLabel === 'string' && fieldLabel.includes('.')) {
+ *       fieldLabel = await this.i18n.translate(fieldLabel, { lang: language });
+ *     } else if (typeof fieldLabel === 'object') {
+ *       fieldLabel = fieldLabel[language] || fieldLabel.zh || fieldLabel.en;
+ *     }
+ *
+ *     // 翻译枚举值
+ *     const valueLabels = metadata?.valueLabels;
+ *     const displayOldValue = valueLabels?.[oldValue]
+ *       ? await this.translateValueLabel(valueLabels[oldValue], language)
+ *       : oldValue;
+ *     const displayNewValue = valueLabels?.[newValue]
+ *       ? await this.translateValueLabel(valueLabels[newValue], language)
+ *       : newValue;
+ *
+ *     return {
+ *       fieldLabel,
+ *       oldValue,
+ *       newValue,
+ *       displayOldValue,
+ *       displayNewValue,
+ *     };
+ *   }
+ *
+ *   private async translateValueLabel(
+ *     label: string | { [lang: string]: string },
+ *     language: string,
+ *   ): Promise<string> {
+ *     if (typeof label === 'string' && label.includes('.')) {
+ *       return await this.i18n.translate(label, { lang: language });
+ *     }
+ *     if (typeof label === 'object') {
+ *       return label[language] || label.zh || label.en || '';
+ *     }
+ *     return label;
+ *   }
+ * }
+ */
+/**
+ * 场景 1: 纯 i18n key 方式（推荐）
+ *
+ * 优点:
+ * - 翻译集中管理，易于维护
+ * - 支持动态切换语言
+ * - 翻译可以复用
+ * - 适合大型项目和国际化需求
+ *
+ * 缺点:
+ * - 需要额外的翻译文件配置
+ * - 增加了一定的复杂度
+ */
+export declare class PureI18nDto {
+    username: string;
+}
+/**
+ * 场景 2: 纯多语言对象方式
+ *
+ * 优点:
+ * - 简单直接，无需额外配置
+ * - 适合小型项目或固定语言场景
+ * - 翻译就在代码中，查看方便
+ *
+ * 缺点:
+ * - 翻译分散在各个 DTO 中，难以统一管理
+ * - 不易于动态切换语言
+ * - 翻译无法复用
+ */
+export declare class PureLabelDto {
+    username: string;
+}
+/**
+ * 场景 3: 混合方式（fieldLabel 优先）
+ *
+ * 优点:
+ * - 灵活性最高
+ * - 可以为特定字段覆盖 i18n 翻译
+ *
+ * 缺点:
+ * - 可能造成混淆
+ * - 建议统一使用一种方式
+ */
+export declare class MixedDto {
+    username: string;
+}
+export declare class RegisterUserDto {
+    username: string;
+    email: string;
+    password: string;
+    phone?: string;
+    agreeTerms?: boolean;
+}
+export {};