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

package/dist/transaction/transaction.errors.js

@@ -0,0 +1,206 @@
+"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.TransactionErrorHandler = exports.TransactionError = void 0;
+/**
+ * 事务相关错误类
+ * 提供统一的错误处理机制
+ */
+class TransactionError extends Error {
+    constructor(message, code, dataSource, transactionId, cause) {
+        super(message);
+        this.code = code;
+        this.dataSource = dataSource;
+        this.transactionId = transactionId;
+        this.cause = cause;
+        this.name = 'TransactionError';
+        // 保持堆栈跟踪
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, TransactionError);
+        }
+    }
+    /**
+     * 创建事务开始失败错误
+     */
+    static beginFailed(message, dataSource, cause) {
+        return new TransactionError(`Transaction begin failed: ${message}`, 'TRANSACTION_BEGIN_FAILED', dataSource, undefined, cause);
+    }
+    /**
+     * 创建事务提交失败错误
+     */
+    static commitFailed(message, dataSource, transactionId, cause) {
+        return new TransactionError(`Transaction commit failed: ${message}`, 'TRANSACTION_COMMIT_FAILED', dataSource, transactionId, cause);
+    }
+    /**
+     * 创建事务回滚失败错误
+     */
+    static rollbackFailed(message, dataSource, transactionId, cause) {
+        return new TransactionError(`Transaction rollback failed: ${message}`, 'TRANSACTION_ROLLBACK_FAILED', dataSource, transactionId, cause);
+    }
+    /**
+     * 创建事务超时错误
+     */
+    static timeout(message, dataSource, transactionId) {
+        return new TransactionError(`Transaction timeout: ${message}`, 'TRANSACTION_TIMEOUT', dataSource, transactionId);
+    }
+    /**
+     * 创建事务状态无效错误
+     */
+    static invalidState(message, dataSource, transactionId) {
+        return new TransactionError(`Invalid transaction state: ${message}`, 'TRANSACTION_INVALID_STATE', dataSource, transactionId);
+    }
+    /**
+     * 创建数据源连接错误
+     */
+    static dataSourceNotFound(dataSource) {
+        return new TransactionError(`DataSource not found: ${dataSource}`, 'DATA_SOURCE_NOT_FOUND', dataSource);
+    }
+    /**
+     * 创建传播行为不支持错误
+     */
+    static unsupportedPropagation(propagation) {
+        return new TransactionError(`Unsupported propagation: ${propagation}`, 'UNSUPPORTED_PROPAGATION');
+    }
+    /**
+     * 创建嵌套事务错误
+     */
+    static nestedTransactionFailed(message, dataSource, cause) {
+        return new TransactionError(`Nested transaction failed: ${message}`, 'NESTED_TRANSACTION_FAILED', dataSource, undefined, cause);
+    }
+    /**
+     * 转换为JSON
+     */
+    toJSON() {
+        var _a;
+        return {
+            name: this.name,
+            message: this.message,
+            code: this.code,
+            dataSource: this.dataSource,
+            transactionId: this.transactionId,
+            stack: this.stack,
+            cause: (_a = this.cause) === null || _a === void 0 ? void 0 : _a.message,
+        };
+    }
+    /**
+     * 检查是否为特定错误代码
+     */
+    isErrorCode(code) {
+        return this.code === code;
+    }
+    /**
+     * 检查是否为连接相关错误
+     */
+    isConnectionError() {
+        return [
+            'DATA_SOURCE_NOT_FOUND',
+            'TRANSACTION_BEGIN_FAILED',
+        ].includes(this.code);
+    }
+    /**
+     * 检查是否为可重试错误
+     */
+    isRetryable() {
+        return [
+            'TRANSACTION_BEGIN_FAILED',
+            'TRANSACTION_COMMIT_FAILED',
+            'TRANSACTION_ROLLBACK_FAILED',
+        ].includes(this.code);
+    }
+}
+exports.TransactionError = TransactionError;
+/**
+ * 事务错误处理工具类
+ */
+class TransactionErrorHandler {
+    /**
+     * 设置日志记录器
+     */
+    static setLogger(logger) {
+        this.logger = logger;
+    }
+    /**
+     * 安全地执行操作，捕获并转换错误
+     */
+    static safeExecute(operation, errorFactory, context) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                return yield operation();
+            }
+            catch (error) {
+                const transactionError = errorFactory(error);
+                // 记录错误上下文
+                if (context) {
+                    this.logger.error(`[TransactionErrorHandler] Error in context "${context}":`, transactionError.toJSON());
+                }
+                throw transactionError;
+            }
+        });
+    }
+    /**
+     * 处理事务超时
+     */
+    static handleTimeout(timeoutMs, dataSource, transactionId) {
+        return TransactionError.timeout(`Transaction exceeded timeout of ${timeoutMs}ms`, dataSource, transactionId);
+    }
+    /**
+     * 处理回滚失败
+     */
+    static safeRollback(rollbackFn, dataSource, transactionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                yield rollbackFn();
+            }
+            catch (error) {
+                const rollbackError = TransactionError.rollbackFailed(error.message, dataSource, transactionId, error);
+                // 记录回滚失败，但不抛出（避免掩盖原始错误）
+                this.logger.error('[TransactionErrorHandler] Rollback failed:', rollbackError.toJSON());
+            }
+        });
+    }
+    /**
+     * 格式化错误消息
+     */
+    static formatMessage(error) {
+        let message = `[${error.code}] ${error.message}`;
+        if (error.dataSource) {
+            message += ` (DataSource: ${error.dataSource})`;
+        }
+        if (error.transactionId) {
+            message += ` (TxId: ${error.transactionId})`;
+        }
+        return message;
+    }
+    /**
+     * 判断是否应该重试
+     */
+    static shouldRetry(error, attempt, maxAttempts = 3) {
+        if (attempt >= maxAttempts) {
+            return false;
+        }
+        // 只对 TransactionError 且可重试的错误进行重试
+        if (error instanceof TransactionError) {
+            return error.isRetryable();
+        }
+        // 对于其他错误，如果是网络相关或临时性错误，也可以重试
+        const retryablePatterns = [
+            /connection/i,
+            /timeout/i,
+            /temporary/i,
+            /network/i,
+            /ECONNRESET/,
+            /ETIMEDOUT/,
+        ];
+        return retryablePatterns.some(pattern => pattern.test(error.message) || pattern.test(error.name));
+    }
+}
+exports.TransactionErrorHandler = TransactionErrorHandler;
+TransactionErrorHandler.logger = console; // 在实际使用中应该注入 Logger

package/dist/transaction/transaction.module.d.ts

@@ -0,0 +1,30 @@
+import { DynamicModule } from '@nestjs/common';
+import { DataSourceRegistryConfig } from './data-source-registry';
+/**
+ * 事务模块配置
+ */
+export interface TransactionModuleOptions {
+    defaultDataSource?: string;
+    globalTransactionOptions?: {
+        dataSources?: string[];
+        isolationLevel?: any;
+        rollbackOnError?: boolean;
+        timeout?: number;
+        logDetails?: boolean;
+    };
+    enableDynamicRegistration?: boolean;
+    logDataSourceRegistration?: boolean;
+    dataSourceRegistryConfig?: DataSourceRegistryConfig;
+    useLoggingInterceptor?: boolean;
+}
+/**
+ * 事务模块
+ */
+export declare class TransactionModule {
+    static forRoot(options?: TransactionModuleOptions): DynamicModule;
+    static forFeature(dataSourceName?: string, interceptorOptions?: {
+        dataSources?: string[];
+        isolationLevel?: any;
+        rollbackOnError?: boolean;
+    }): DynamicModule;
+}

package/dist/transaction/transaction.module.js

@@ -0,0 +1,98 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var TransactionModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TransactionModule = void 0;
+const common_1 = require("@nestjs/common");
+const transaction_context_service_1 = require("./transaction-context.service");
+const transactional_decorator_1 = require("./transactional.decorator");
+const transaction_manager_1 = require("./transaction-manager");
+const transaction_manager_2 = require("./transaction-manager");
+const data_source_registry_1 = require("./data-source-registry");
+const logging_transactional_interceptor_1 = require("./logging-transactional.interceptor");
+/**
+ * 事务模块
+ */
+let TransactionModule = TransactionModule_1 = class TransactionModule {
+    static forRoot(options) {
+        var _a, _b, _c, _d, _e;
+        const providers = [
+            transaction_context_service_1.TransactionContextService,
+            transaction_manager_2.TransactionContextManager,
+            transaction_manager_1.TransactionManager,
+            transactional_decorator_1.TransactionalInterceptor,
+            {
+                provide: 'TRANSACTION_CONFIG',
+                useValue: {
+                    defaultDataSource: (options === null || options === void 0 ? void 0 : options.defaultDataSource) || 'default',
+                    enableDynamicRegistration: (_a = options === null || options === void 0 ? void 0 : options.enableDynamicRegistration) !== null && _a !== void 0 ? _a : true,
+                    logDataSourceRegistration: (_b = options === null || options === void 0 ? void 0 : options.logDataSourceRegistration) !== null && _b !== void 0 ? _b : true,
+                    defaultTimeout: (_c = options === null || options === void 0 ? void 0 : options.globalTransactionOptions) === null || _c === void 0 ? void 0 : _c.timeout,
+                    logTransactionDetails: (_e = (_d = options === null || options === void 0 ? void 0 : options.globalTransactionOptions) === null || _d === void 0 ? void 0 : _d.logDetails) !== null && _e !== void 0 ? _e : false,
+                },
+            },
+            {
+                provide: 'DATA_SOURCE_NAME',
+                useValue: (options === null || options === void 0 ? void 0 : options.defaultDataSource) || 'default',
+            },
+            {
+                provide: 'TRANSACTION_OPTIONS',
+                useValue: (options === null || options === void 0 ? void 0 : options.globalTransactionOptions) || {},
+            },
+            data_source_registry_1.DataSourceRegistryService,
+            {
+                provide: 'DATA_SOURCE_REGISTRY_CONFIG',
+                useValue: (options === null || options === void 0 ? void 0 : options.dataSourceRegistryConfig) || {
+                    enableHealthCheck: false,
+                    logLifecycleEvents: true,
+                },
+            },
+        ];
+        // 添加日志增强拦截器
+        if (options === null || options === void 0 ? void 0 : options.useLoggingInterceptor) {
+            providers.push(logging_transactional_interceptor_1.LoggingTransactionalInterceptor);
+        }
+        const exports = [
+            transaction_context_service_1.TransactionContextService,
+            transaction_manager_2.TransactionContextManager,
+            transaction_manager_1.TransactionManager,
+            data_source_registry_1.DataSourceRegistryService,
+            transactional_decorator_1.TransactionalInterceptor,
+        ];
+        return {
+            module: TransactionModule_1,
+            providers,
+            exports,
+            global: true,
+        };
+    }
+    static forFeature(dataSourceName, interceptorOptions) {
+        const providers = [];
+        if (interceptorOptions) {
+            providers.push({
+                provide: 'TRANSACTION_OPTIONS',
+                useValue: interceptorOptions,
+            });
+        }
+        if (dataSourceName) {
+            providers.push({
+                provide: 'DATA_SOURCE_NAME',
+                useValue: dataSourceName,
+            });
+        }
+        return {
+            module: TransactionModule_1,
+            providers,
+            exports: [transaction_context_service_1.TransactionContextService],
+        };
+    }
+};
+exports.TransactionModule = TransactionModule;
+exports.TransactionModule = TransactionModule = TransactionModule_1 = __decorate([
+    (0, common_1.Module)({})
+], TransactionModule);

package/dist/transaction/transactional.decorator.d.ts

@@ -0,0 +1,82 @@
+import { CallHandler, ExecutionContext, NestInterceptor } from '@nestjs/common';
+import { Observable } from 'rxjs';
+import { TransactionManager, Propagation, IsolationLevel, TransactionTimeoutCallback } from './transaction-manager';
+/**
+ * 事务元数据键
+ */
+export declare const TRANSACTION_METADATA_KEY = "transactional";
+/**
+ * 事务配置选项
+ */
+export interface TransactionalOptions {
+    propagation?: Propagation;
+    isolation?: IsolationLevel;
+    readOnly?: boolean;
+    timeout?: number;
+    name?: string;
+    dataSource?: string;
+    onTimeout?: TransactionTimeoutCallback;
+    isolationLevel?: IsolationLevel;
+}
+/**
+ * @Transactional 装饰器
+ * 统一的事务装饰器，自动处理嵌套和数据源
+ */
+export declare function Transactional(options?: TransactionalOptions): MethodDecorator;
+/**
+ * 类级别事务装饰器
+ */
+export declare function ClassTransactional(options?: TransactionalOptions): ClassDecorator;
+/**
+ * 事务拦截器
+ * 支持类级别和方法级别的事务管理
+ */
+export declare class TransactionalInterceptor implements NestInterceptor {
+    private readonly transactionManager;
+    private readonly logger;
+    constructor(transactionManager: TransactionManager);
+    intercept(context: ExecutionContext, next: CallHandler): Promise<Observable<any>>;
+    private executeWithTransaction;
+    private getTransactionOptions;
+}
+/**
+ * 便捷装饰器工厂
+ */
+export declare const Tx: {
+    /**
+     * 必须在事务中执行（默认）
+     */
+    Required: (dataSource?: string) => MethodDecorator;
+    /**
+     * 支持当前事务，非事务执行也行
+     */
+    Supports: (dataSource?: string) => MethodDecorator;
+    /**
+     * 必须在事务中执行，否则抛异常
+     */
+    Mandatory: (dataSource?: string) => MethodDecorator;
+    /**
+     * 创建新事务
+     */
+    RequiresNew: (dataSource?: string) => MethodDecorator;
+    /**
+     * 不支持事务，挂起当前事务
+     */
+    NotSupported: (dataSource?: string) => MethodDecorator;
+    /**
+     * 永不使用事务
+     */
+    Never: (dataSource?: string) => MethodDecorator;
+    /**
+     * 嵌套事务
+     */
+    Nested: (dataSource?: string) => MethodDecorator;
+    /**
+     * 只读事务
+     */
+    ReadOnly: (dataSource?: string) => MethodDecorator;
+};
+/**
+ * 组合装饰器：使用拦截器
+ */
+export declare function UseTransactional(options?: TransactionalOptions): ClassDecorator & MethodDecorator;