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

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-11",
   "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/comprehensive-lock-cleanup.service.d.ts

@@ -0,0 +1,94 @@
+import { OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
+import { RedisLockService } from './redis-lock.service';
+import { LockHeartbeatService } from './lock-heartbeat.service';
+/**
+ * Comprehensive lock cleanup service
+ *
+ * Provides safe and comprehensive lock cleanup mechanism for distributed environments.
+ * Combines instance-based precise cleanup with heartbeat-based dead instance detection.
+ *
+ * **Cleanup Strategy:**
+ * 1. **Immediate Precise Cleanup (0s):**
+ *    - Only cleans locks from the current instance
+ *    - Safe during rolling updates - won't affect other running instances
+ *
+ * 2. **Delayed Conservative Cleanup (60s):**
+ *    - Checks heartbeat of other instances
+ *    - Only cleans locks from dead instances (no heartbeat)
+ *    - Gives enough time for rolling updates to complete
+ *
+ * 3. **Graceful Shutdown Cleanup:**
+ *    - On SIGTERM/SIGINT, immediately cleans own locks
+ *    - Ensures locks are released before process exits
+ *    - Works with PM2 reload and Kubernetes rolling updates
+ *
+ * @example
+ * ```typescript
+ * // In your module
+ * @Module({
+ *   providers: [
+ *     RedisLockService,
+ *     LockHeartbeatService,
+ *     ComprehensiveLockCleanupService,
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ */
+export declare class ComprehensiveLockCleanupService implements OnModuleInit, OnApplicationShutdown {
+    private readonly lockService;
+    private readonly heartbeatService;
+    private readonly logger;
+    private readonly instanceId;
+    /**
+     * Grace period before cleaning other instances' locks (milliseconds)
+     * @default 60000 (60 seconds)
+     */
+    private readonly gracePeriod;
+    constructor(lockService: RedisLockService, heartbeatService: LockHeartbeatService);
+    onModuleInit(): Promise<void>;
+    /**
+     * Clean up locks from the current instance
+     * Safe to run immediately - only affects locks created by this instance
+     */
+    private cleanupOwnLocks;
+    /**
+     * Clean up locks from dead instances
+     * Only runs after grace period to avoid cleaning locks during rolling updates
+     */
+    private cleanupDeadInstanceLocks;
+    /**
+     * Check if a lock belongs to the current instance
+     *
+     * @param lockValue - Lock value to check
+     * @returns True if lock belongs to current instance
+     */
+    private isOwnLock;
+    /**
+     * Extract instance ID from lock value
+     * Lock value format: instanceId:timestamp:random:pid
+     *
+     * @param lockValue - Lock value
+     * @returns Instance ID or null if cannot be extracted
+     */
+    private extractInstanceId;
+    /**
+     * Get instance identifier
+     */
+    private getInstanceId;
+    /**
+     * Manually trigger cleanup of all stale locks
+     * Use with caution - this will clean both own and dead instance locks
+     */
+    manualCleanup(): Promise<{
+        ownLocks: number;
+        deadLocks: number;
+    }>;
+    private cleanupOwnLocksCount;
+    private cleanupDeadInstanceLocksCount;
+    /**
+     * Cleanup own locks on application shutdown
+     * Called when receiving SIGTERM/SIGINT (graceful shutdown)
+     */
+    onApplicationShutdown(signal?: string): Promise<void>;
+}