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

package/http-client/utils/curl-generator.util.js

@@ -1,14 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CurlGenerator = void 0;
+/**
+ * HTTP请求curl命令生成器
+ */
 class CurlGenerator {
+    /**
+     * 生成curl命令
+     */
     static generateCurlCommand(config, response) {
         const parts = ['curl'];
+        // 添加方法
         if (config.method && config.method.toLowerCase() !== 'get') {
             parts.push(`-X ${config.method.toUpperCase()}`);
         }
+        // 添加URL
         const url = this.buildUrl(config);
         parts.push(`'${url}'`);
+        // 添加头信息
         if (config.headers) {
             Object.entries(config.headers).forEach(([key, value]) => {
                 if (value !== undefined && value !== null) {
@@ -16,12 +25,14 @@ class CurlGenerator {
                 }
             });
         }
+        // 添加数据
         if (config.data) {
             const data = typeof config.data === 'string'
                 ? config.data
                 : JSON.stringify(config.data, null, 2);
             parts.push(`-d '${data}'`);
         }
+        // 添加表单数据
         if (config.data instanceof FormData) {
             const formDataParts = [];
             config.data.forEach((value, key) => {
@@ -34,26 +45,35 @@ class CurlGenerator {
             });
             parts.push(...formDataParts);
         }
+        // 添加查询参数（如果不在URL中）
         if (config.params && !url.includes('?')) {
             const params = new URLSearchParams(config.params).toString();
             if (params) {
                 parts[parts.length - 1] = parts[parts.length - 1].replace(/'/, `?${params}'`);
             }
         }
-        parts.push('-i');
-        parts.push('-s');
-        parts.push('-L');
+        // 添加其他选项
+        parts.push('-i'); // 包含头信息
+        parts.push('-s'); // 静默模式
+        parts.push('-L'); // 跟随重定向
+        // 添加响应状态码注释
         if (response) {
             parts.push(`# Response: ${response.status} ${response.statusText}`);
         }
         return parts.join(' \\\n  ');
     }
+    /**
+     * 生成简化的curl命令（用于日志记录）
+     */
     static generateSimplifiedCurl(config) {
         const parts = ['curl'];
+        // 添加方法
         if (config.method && config.method.toLowerCase() !== 'get') {
             parts.push(`-X ${config.method.toUpperCase()}`);
         }
+        // 添加URL
         parts.push(`'${this.buildUrl(config)}'`);
+        // 只添加重要的头信息
         const importantHeaders = [
             'content-type',
             'accept',
@@ -65,11 +85,13 @@ class CurlGenerator {
                 .filter(([key]) => importantHeaders.includes(key.toLowerCase()))
                 .forEach(([key, value]) => {
                 if (value !== undefined && value !== null) {
+                    // 过滤敏感信息
                     const sanitizedValue = this.sanitizeHeaderValue(key, String(value));
                     parts.push(`-H '${key}: ${sanitizedValue}'`);
                 }
             });
         }
+        // 添加数据（简化版）
         if (config.data) {
             const data = typeof config.data === 'string'
                 ? config.data.substring(0, 200) +
@@ -79,9 +101,13 @@ class CurlGenerator {
         }
         return parts.join(' ');
     }
+    /**
+     * 生成用于调试的详细curl命令
+     */
     static generateDebugCurl(config, response) {
         var _a, _b, _c;
         const curl = this.generateCurlCommand(config, response);
+        // 添加调试信息注释
         const debugInfo = [
             '# Debug Information:',
             `# Timestamp: ${new Date().toISOString()}`,
@@ -94,17 +120,23 @@ class CurlGenerator {
         }
         return debugInfo.join('\n') + '\n' + curl;
     }
+    /**
+     * 从curl命令解析请求配置
+     */
     static parseCurlCommand(curlCommand) {
         const config = {};
         try {
+            // 提取方法
             const methodMatch = curlCommand.match(/-X\s+(\w+)/);
             if (methodMatch) {
                 config.method = methodMatch[1].toLowerCase();
             }
+            // 提取URL
             const urlMatch = curlCommand.match(/curl[^']*'([^']+)'/);
             if (urlMatch) {
                 config.url = urlMatch[1];
             }
+            // 提取头信息
             const headerMatches = curlCommand.match(/-H\s+'([^:]+):\s*([^']+)'/g) || [];
             config.headers = {};
             headerMatches.forEach((header) => {
@@ -113,6 +145,7 @@ class CurlGenerator {
                     config.headers[headerMatch[1]] = headerMatch[2];
                 }
             });
+            // 提取数据
             const dataMatch = curlCommand.match(/-d\s+'([^']+)'/);
             if (dataMatch) {
                 try {
@@ -128,11 +161,16 @@ class CurlGenerator {
         }
         return config;
     }
+    /**
+     * 构建完整URL
+     */
     static buildUrl(config) {
         let url = config.url || '';
+        // 处理相对URL
         if (config.baseURL && !url.startsWith('http')) {
             url = config.baseURL.replace(/\/$/, '') + '/' + url.replace(/^\//, '');
         }
+        // 添加查询参数
         if (config.params) {
             const searchParams = new URLSearchParams();
             Object.entries(config.params).forEach(([key, value]) => {
@@ -147,6 +185,9 @@ class CurlGenerator {
         }
         return url;
     }
+    /**
+     * 过滤敏感头信息
+     */
     static sanitizeHeaderValue(key, value) {
         const sensitiveKeys = [
             'authorization',

package/http-client/utils/request-id.util.d.ts

@@ -1,4 +1,22 @@
+/**
+ * 生成请求ID
+ * @returns 唯一的请求ID
+ */
 export declare function generateRequestId(): string;
+/**
+ * 生成短请求ID（用于日志）
+ * @returns 短格的请求ID
+ */
 export declare function generateShortRequestId(): string;
+/**
+ * 验证请求ID格式
+ * @param requestId 请求ID
+ * @returns 是否为有效的请求ID
+ */
 export declare function isValidRequestId(requestId: string): boolean;
+/**
+ * 从请求头中提取请求ID
+ * @param headers 请求头
+ * @returns 请求ID或null
+ */
 export declare function extractRequestId(headers: Record<string, string>): string | null;

package/http-client/utils/request-id.util.js

@@ -5,17 +5,37 @@ exports.generateShortRequestId = generateShortRequestId;
 exports.isValidRequestId = isValidRequestId;
 exports.extractRequestId = extractRequestId;
 const crypto_1 = require("crypto");
+/**
+ * 生成请求ID
+ * @returns 唯一的请求ID
+ */
 function generateRequestId() {
     return (0, crypto_1.randomUUID)();
 }
+/**
+ * 生成短请求ID（用于日志）
+ * @returns 短格的请求ID
+ */
 function generateShortRequestId() {
     return Math.random().toString(36).substring(2, 15);
 }
+/**
+ * 验证请求ID格式
+ * @param requestId 请求ID
+ * @returns 是否为有效的请求ID
+ */
 function isValidRequestId(requestId) {
+    // UUID格式验证
     const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
     return uuidRegex.test(requestId);
 }
+/**
+ * 从请求头中提取请求ID
+ * @param headers 请求头
+ * @returns 请求ID或null
+ */
 function extractRequestId(headers) {
+    // 常见的请求ID头名称
     const requestIdHeaders = [
         'x-request-id',
         'x-trace-id',

package/http-client/utils/retry-recorder.util.d.ts

@@ -1,14 +1,41 @@
 import { AxiosError, AxiosRequestConfig } from 'axios';
 import { RetryRecord } from '../entities/http-log.entity';
+/**
+ * 请求重试记录器
+ */
 export declare class RetryRecorder {
     private records;
+    /**
+     * 记录重试尝试
+     */
     static recordRetry(attempt: number, error: AxiosError | any, config: AxiosRequestConfig, delay: number): RetryRecord;
+    /**
+     * 创建重试记录器实例
+     */
     static create(): RetryRecorder;
+    /**
+     * 格式化错误信息
+     */
     private static formatError;
+    /**
+     * 获取重试原因
+     */
     private static getRetryReason;
+    /**
+     * 过滤敏感头信息
+     */
     private static sanitizeHeaders;
+    /**
+     * 添加重试记录
+     */
     addRecord(record: RetryRecord): void;
+    /**
+     * 获取所有重试记录
+     */
     getRecords(): RetryRecord[];
+    /**
+     * 获取重试统计
+     */
     getStats(): {
         totalRetries: number;
         maxAttempts: number;
@@ -16,10 +43,25 @@ export declare class RetryRecorder {
         averageDelay: number;
         reasons: Record<string, number>;
     };
+    /**
+     * 重置记录
+     */
     reset(): void;
+    /**
+     * 获取最后一次重试记录
+     */
     getLastRecord(): RetryRecord | null;
+    /**
+     * 检查是否有重试记录
+     */
     hasRetries(): boolean;
+    /**
+     * 获取指定尝试次数的记录
+     */
     getRecordByAttempt(attempt: number): RetryRecord | null;
+    /**
+     * 获取重试时间线
+     */
     getTimeline(): Array<{
         attempt: number;
         timestamp: Date;

package/http-client/utils/retry-recorder.util.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RetryRecorder = void 0;
+/**
+ * 请求重试记录器
+ */
 class RetryRecorder {
     constructor() {
         this.records = [];
     }
+    /**
+     * 记录重试尝试
+     */
     static recordRetry(attempt, error, config, delay) {
         var _a;
         return {
@@ -20,9 +26,15 @@ class RetryRecorder {
             },
         };
     }
+    /**
+     * 创建重试记录器实例
+     */
     static create() {
         return new RetryRecorder();
     }
+    /**
+     * 格式化错误信息
+     */
     static formatError(error) {
         var _a;
         if (!error)
@@ -38,8 +50,12 @@ class RetryRecorder {
         }
         return formatted;
     }
+    /**
+     * 获取重试原因
+     */
     static getRetryReason(error) {
         if (!error.response) {
+            // 网络错误
             if (error.code === 'ECONNRESET') {
                 return 'Connection reset';
             }
@@ -54,6 +70,7 @@ class RetryRecorder {
             }
             return 'Network error';
         }
+        // HTTP错误
         const status = error.response.status;
         if (status >= 500) {
             return `Server error: ${status}`;
@@ -66,6 +83,9 @@ class RetryRecorder {
         }
         return `HTTP error: ${status}`;
     }
+    /**
+     * 过滤敏感头信息
+     */
     static sanitizeHeaders(headers) {
         const sanitized = {};
         const sensitiveKeys = [
@@ -89,12 +109,21 @@ class RetryRecorder {
         });
         return sanitized;
     }
+    /**
+     * 添加重试记录
+     */
     addRecord(record) {
         this.records.push(record);
     }
+    /**
+     * 获取所有重试记录
+     */
     getRecords() {
         return [...this.records];
     }
+    /**
+     * 获取重试统计
+     */
     getStats() {
         const totalRetries = this.records.length;
         const maxAttempts = Math.max(...this.records.map((r) => r.attempt), 0);
@@ -112,20 +141,35 @@ class RetryRecorder {
             reasons,
         };
     }
+    /**
+     * 重置记录
+     */
     reset() {
         this.records = [];
     }
+    /**
+     * 获取最后一次重试记录
+     */
     getLastRecord() {
         return this.records.length > 0
             ? this.records[this.records.length - 1]
             : null;
     }
+    /**
+     * 检查是否有重试记录
+     */
     hasRetries() {
         return this.records.length > 0;
     }
+    /**
+     * 获取指定尝试次数的记录
+     */
     getRecordByAttempt(attempt) {
         return this.records.find((r) => r.attempt === attempt) || null;
     }
+    /**
+     * 获取重试时间线
+     */
     getTimeline() {
         let cumulativeDelay = 0;
         return this.records.map((record) => {

package/i18n/en_US/validation.json

@@ -40,5 +40,6 @@
     "IS_LOCALE": "{property} value `{value}` must be a valid locale",
     "AT_LEAST_ONE_FIELD": "At least one of the following fields must be provided: {properties}",
     "CUSTOM_VALIDATION": "Custom validation failed for {property}",
-    "CUSTOM_VALIDATION_METHOD": "Validation failed for {property}"
+    "CUSTOM_VALIDATION_METHOD": "Validation failed for {property}",
+    "CUSTOM_VALIDATE": "Validation failed for {property}"
 }

package/i18n/zh_CN/validation.json

@@ -40,5 +40,6 @@
     "IS_LOCALE": "{property} 值 `{value}` 必须是有效语言",
     "AT_LEAST_ONE_FIELD": "以下字段中至少必须提供一个：{properties}",
     "CUSTOM_VALIDATION": "{property}自定义验证失败",
-    "CUSTOM_VALIDATION_METHOD": "{property}验证失败"
+    "CUSTOM_VALIDATION_METHOD": "{property}验证失败",
+    "CUSTOM_VALIDATE": "{property}验证失败"
 }

package/index.js

@@ -14,6 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+// Core modules
 __exportStar(require("./constants"), exports);
 __exportStar(require("./decorators"), exports);
 __exportStar(require("./exceptions"), exports);
@@ -27,10 +28,17 @@ __exportStar(require("./common"), exports);
 __exportStar(require("./validator-json"), exports);
 __exportStar(require("./helpers"), exports);
 __exportStar(require("./providers"), exports);
+// Lock module
 __exportStar(require("./redis-lock"), exports);
+// Cache module
 __exportStar(require("./cache"), exports);
+// HTTP Client module
 __exportStar(require("./http-client"), exports);
+// Vault module
 __exportStar(require("./vault"), exports);
+// Setup and bootstrap
 __exportStar(require("./setup"), exports);
+// Health checker
 __exportStar(require("./health-checker"), exports);
+// Audit module
 __exportStar(require("./audit"), exports);

package/interceptors/translation-interceptor.service.js

@@ -9,12 +9,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.TranslationInterceptor = void 0;
 const common_1 = require("@nestjs/common");
 const operators_1 = require("rxjs/operators");
+// import { TranslationService } from '../shared/services/translation.service';
+// FIXME: add implementation
 let TranslationInterceptor = class TranslationInterceptor {
+    // constructor(private readonly translationService: TranslationService) {}
     intercept(context, next) {
         const ctx = context.switchToHttp();
         const req = ctx.getRequest();
         const res = ctx.getResponse();
         return next.handle().pipe((0, operators_1.map)((data) => {
+            // const newData = this.translationService.translateNecessaryKeys(data);
+            // status 201 => 200
             if (res.statusCode === common_1.HttpStatus.CREATED) {
                 res.status(common_1.HttpStatus.OK);
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nest-omni/core",
-  "version": "4.1.3-1",
+  "version": "4.1.3-3",
   "description": "A comprehensive NestJS framework for building enterprise-grade applications with best practices",
   "main": "index.js",
   "types": "index.d.ts",

package/providers/context.provider.js

@@ -8,6 +8,7 @@ class ContextProvider {
         const store = nestjs_cls_1.ClsServiceManager.getClsService();
         return store.get(ContextProvider.getKeyWithNamespace(key));
     }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     static set(key, value) {
         const store = nestjs_cls_1.ClsServiceManager.getClsService();
         store.set(ContextProvider.getKeyWithNamespace(key), value);
@@ -24,6 +25,7 @@ class ContextProvider {
     static getRouter() {
         const value = ContextProvider.get(ContextProvider.routerKey);
         if (value) {
+            // @ts-ignore
             return value;
         }
         return {

package/providers/generator.provider.d.ts

@@ -5,5 +5,9 @@ export declare class GeneratorProvider {
     static getS3Key(publicUrl: string): string;
     static generateVerificationCode(): string;
     static generatePassword(): string;
+    /**
+     * generate random string
+     * @param length
+     */
     static generateRandomString(length: number): string;
 }

package/providers/generator.provider.js

@@ -40,6 +40,10 @@ class GeneratorProvider {
         }
         return text;
     }
+    /**
+     * generate random string
+     * @param length
+     */
     static generateRandomString(length) {
         return Math.random()
             .toString(36)

package/redis-lock/examples/lock-strategy.examples.d.ts

@@ -1,9 +1,25 @@
+/**
+ * Lock Strategy Examples
+ *
+ * This file demonstrates the different lock acquisition strategies available in Redis Lock module.
+ */
 import { RedisLockService } from '../index';
+/**
+ * SKIP strategy - Skip execution if lock cannot be acquired
+ * This is the default behavior and is useful for scheduled tasks where you don't
+ * want to queue up requests if a previous execution is still running.
+ */
 export declare class SkipStrategyExample {
     private readonly lockService;
     private readonly logger;
     constructor(lockService: RedisLockService);
+    /**
+     * Example 1: Using decorator with SKIP strategy (default)
+     */
     scheduledTask(): Promise<void>;
+    /**
+     * Example 2: Using service directly with SKIP strategy
+     */
     processWithSkip(): Promise<{
         skipped: boolean;
         success?: undefined;
@@ -11,6 +27,9 @@ export declare class SkipStrategyExample {
         success: boolean;
         skipped?: undefined;
     }>;
+    /**
+     * Example 3: SKIP with retries
+     */
     processWithRetries(): Promise<{
         skipped: boolean;
         success?: undefined;
@@ -20,14 +39,28 @@ export declare class SkipStrategyExample {
     }>;
     private simulateLongRunning;
 }
+/**
+ * THROW strategy - Throw an error if lock cannot be acquired
+ * Use this for critical operations that must have exclusive access.
+ * If the lock cannot be acquired, an exception will be thrown.
+ */
 export declare class ThrowStrategyExample {
     private readonly lockService;
     private readonly logger;
     constructor(lockService: RedisLockService);
+    /**
+     * Example 1: Using decorator with THROW strategy
+     */
     criticalOperation(): Promise<void>;
+    /**
+     * Example 2: Using service with error handling
+     */
     processWithThrow(): Promise<{
         success: boolean;
     }>;
+    /**
+     * Example 3: Critical payment processing
+     */
     processPayment(orderId: string, amount: number): Promise<{
         success: boolean;
     }>;
@@ -35,11 +68,22 @@ export declare class ThrowStrategyExample {
     private chargePayment;
     private updateOrderStatus;
 }
+/**
+ * WAIT strategy - Block/wait until lock can be acquired
+ * Use this when you want to queue execution and ensure the operation eventually runs.
+ * The function will wait indefinitely (or until waitTimeout) for the lock to become available.
+ */
 export declare class WaitStrategyExample {
     private readonly lockService;
     private readonly logger;
     constructor(lockService: RedisLockService);
+    /**
+     * Example 1: Using decorator with WAIT strategy
+     */
     sequentialTask(): Promise<void>;
+    /**
+     * Example 2: WAIT with timeout
+     */
     processWithWaitTimeout(): Promise<{
         timeout: boolean;
         success?: undefined;
@@ -47,12 +91,24 @@ export declare class WaitStrategyExample {
         success: boolean;
         timeout?: undefined;
     }>;
+    /**
+     * Example 3: Sequential data processing
+     * Perfect for operations that must be processed in order
+     */
     processDataSequentially(userId: string, data: any): Promise<{
         success: boolean;
     }>;
+    /**
+     * Example 4: Queue-like behavior
+     * Multiple requests will queue and execute one by one
+     */
     processQueue(queueName: string, item: any): Promise<{
         success: boolean;
     }>;
+    /**
+     * Example 5: Database migration with WAIT
+     * Ensures migrations run sequentially across all instances
+     */
     runMigration(migrationName: string): Promise<{
         success: boolean;
     }>;
@@ -63,11 +119,44 @@ export declare class WaitStrategyExample {
     private processQueueItem;
     private executeMigration;
 }
+/**
+ * USE SKIP WHEN:
+ * - Running scheduled tasks where you don't want overlapping executions
+ * - Cron jobs that should skip if previous run is still in progress
+ * - Non-critical background tasks
+ * - Operations where it's okay to skip if busy
+ *
+ * USE THROW WHEN:
+ * - Critical operations that require exclusive access
+ * - Financial transactions
+ * - Operations where failure to acquire lock is an error
+ * - When you want to alert/fail fast if resource is busy
+ *
+ * USE WAIT WHEN:
+ * - Operations that must execute eventually
+ * - Sequential processing requirements
+ * - Queue-like behavior needed
+ * - Database migrations
+ * - Operations where order matters
+ * - When you want to ensure the operation runs (with optional timeout)
+ */
+/**
+ * Example: Combining strategies in a single service
+ */
 export declare class CombinedStrategiesExample {
     private readonly lockService;
     private readonly logger;
     constructor(lockService: RedisLockService);
+    /**
+     * Background cleanup - SKIP if already running
+     */
     cleanupOldData(): Promise<void>;
+    /**
+     * Payment processing - THROW if cannot get exclusive access
+     */
     processPayment(orderId: string): Promise<void>;
+    /**
+     * Report generation - WAIT to ensure it runs eventually
+     */
     generateReport(reportId: string): Promise<void>;
 }