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

package/transaction/transaction-synchronization.d.ts

@@ -0,0 +1,171 @@
+/**
+ * 事务同步管理器
+ * 对标 Spring TransactionSynchronizationManager
+ *
+ * 提供事务资源绑定、同步回调和事务状态管理
+ */
+/**
+ * 事务同步状态
+ */
+export declare enum TransactionSynchronizationStatus {
+    STATUS_COMMITTED = 0,
+    STATUS_ROLLED_BACK = 1,
+    STATUS_UNKNOWN = 2
+}
+/**
+ * 事务同步回调接口
+ * 对标 Spring TransactionSynchronization
+ */
+export interface TransactionSynchronization {
+    /**
+     * 事务挂起前调用
+     */
+    suspend?(): void;
+    /**
+     * 事务恢复时调用
+     */
+    resume?(): void;
+    /**
+     * 事务提交前调用（刷新前）
+     */
+    beforeCommit?(readOnly: boolean): Promise<void> | void;
+    /**
+     * 事务完成前调用（提交或回滚前）
+     */
+    beforeCompletion?(): Promise<void> | void;
+    /**
+     * 事务提交后调用
+     */
+    afterCommit?(): Promise<void> | void;
+    /**
+     * 事务完成后调用（提交或回滚后）
+     * @param status 事务完成状态
+     */
+    afterCompletion?(status: TransactionSynchronizationStatus): Promise<void> | void;
+    /**
+     * 获取同步顺序（值越小，优先级越高）
+     */
+    getOrder?(): number;
+}
+/**
+ * 事务同步管理器
+ * 对标 Spring TransactionSynchronizationManager
+ *
+ * 使用 AsyncLocalStorage 实现请求隔离，避免跨请求状态污染和内存泄漏
+ */
+export declare class TransactionSynchronizationManager {
+    private static readonly logger;
+    /**
+     * 获取当前请求的同步上下文
+     */
+    private static getContext;
+    /**
+     * 在 AsyncLocalStorage 上下文中运行代码
+     * 用于确保每个请求有独立的同步状态
+     */
+    static runInContext<T>(fn: () => T): T;
+    /**
+     * 初始化请求上下文（用于中间件）
+     */
+    static initRequestContext(): void;
+    /**
+     * 检查是否在上下文中
+     */
+    static hasContext(): boolean;
+    /**
+     * 获取当前事务的唯一标识
+     */
+    private static getCurrentTransactionKey;
+    /**
+     * 注册事务同步回调
+     */
+    static registerSynchronization(synchronization: TransactionSynchronization, dataSourceName?: string): void;
+    /**
+     * 检查事务同步是否活跃
+     */
+    static isSynchronizationActive(dataSourceName?: string): boolean;
+    /**
+     * 初始化事务同步
+     */
+    static initSynchronization(dataSourceName?: string): void;
+    /**
+     * 清理事务同步
+     */
+    static clearSynchronization(dataSourceName?: string): void;
+    /**
+     * 获取所有同步回调（按优先级排序）
+     */
+    static getSynchronizations(dataSourceName?: string): TransactionSynchronization[];
+    /**
+     * 触发 beforeCommit 回调
+     */
+    static triggerBeforeCommit(readOnly: boolean, dataSourceName?: string): Promise<void>;
+    /**
+     * 触发 beforeCompletion 回调
+     */
+    static triggerBeforeCompletion(dataSourceName?: string): Promise<void>;
+    /**
+     * 触发 afterCommit 回调
+     */
+    static triggerAfterCommit(dataSourceName?: string): Promise<void>;
+    /**
+     * 触发 afterCompletion 回调
+     */
+    static triggerAfterCompletion(status: TransactionSynchronizationStatus, dataSourceName?: string): Promise<void>;
+    /**
+     * 绑定资源到当前事务
+     */
+    static bindResource(key: string, value: any, dataSourceName?: string): void;
+    /**
+     * 解绑资源
+     */
+    static unbindResource(key: string, dataSourceName?: string): any;
+    /**
+     * 获取绑定的资源
+     */
+    static getResource(key: string, dataSourceName?: string): any;
+    /**
+     * 检查资源是否已绑定
+     */
+    static hasResource(key: string, dataSourceName?: string): boolean;
+    /**
+     * 设置当前事务是否活跃
+     */
+    static setActualTransactionActive(active: boolean, dataSourceName?: string): void;
+    /**
+     * 检查是否有实际的事务
+     */
+    static isActualTransactionActive(dataSourceName?: string): boolean;
+    /**
+     * 设置当前事务名称
+     */
+    static setCurrentTransactionName(name: string | null, dataSourceName?: string): void;
+    /**
+     * 获取当前事务名称
+     */
+    static getCurrentTransactionName(dataSourceName?: string): string | null;
+    /**
+     * 设置当前事务是否只读
+     */
+    static setCurrentTransactionReadOnly(readOnly: boolean, dataSourceName?: string): void;
+    /**
+     * 检查当前事务是否只读
+     */
+    static isCurrentTransactionReadOnly(dataSourceName?: string): boolean;
+    /**
+     * 设置当前事务隔离级别
+     */
+    static setCurrentTransactionIsolationLevel(level: number | null, dataSourceName?: string): void;
+    /**
+     * 获取当前事务隔离级别
+     */
+    static getCurrentTransactionIsolationLevel(dataSourceName?: string): number | null;
+    /**
+     * 清理所有事务同步状态
+     */
+    static clear(dataSourceName?: string): void;
+    /**
+     * 获取所有资源
+     */
+    static getAllResources(dataSourceName?: string): Map<string, any>;
+}

package/transaction/transaction-synchronization.js

@@ -0,0 +1,380 @@
+"use strict";
+/**
+ * 事务同步管理器
+ * 对标 Spring TransactionSynchronizationManager
+ *
+ * 提供事务资源绑定、同步回调和事务状态管理
+ */
+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.TransactionSynchronizationManager = exports.TransactionSynchronizationStatus = void 0;
+const common_1 = require("@nestjs/common");
+const async_hooks_1 = require("async_hooks");
+/**
+ * 事务同步状态
+ */
+var TransactionSynchronizationStatus;
+(function (TransactionSynchronizationStatus) {
+    TransactionSynchronizationStatus[TransactionSynchronizationStatus["STATUS_COMMITTED"] = 0] = "STATUS_COMMITTED";
+    TransactionSynchronizationStatus[TransactionSynchronizationStatus["STATUS_ROLLED_BACK"] = 1] = "STATUS_ROLLED_BACK";
+    TransactionSynchronizationStatus[TransactionSynchronizationStatus["STATUS_UNKNOWN"] = 2] = "STATUS_UNKNOWN";
+})(TransactionSynchronizationStatus || (exports.TransactionSynchronizationStatus = TransactionSynchronizationStatus = {}));
+/**
+ * 创建新的同步上下文
+ */
+function createSyncContext() {
+    return {
+        synchronizations: new Map(),
+        resources: new Map(),
+        actualTransactionActive: new Map(),
+        currentTransactionName: new Map(),
+        currentTransactionReadOnly: new Map(),
+        currentTransactionIsolationLevel: new Map(),
+    };
+}
+// AsyncLocalStorage for request-scoped synchronization state
+const syncContextStorage = new async_hooks_1.AsyncLocalStorage();
+// Fallback context for non-HTTP scenarios (e.g., unit tests, CLI)
+let fallbackContext = null;
+/**
+ * 事务同步管理器
+ * 对标 Spring TransactionSynchronizationManager
+ *
+ * 使用 AsyncLocalStorage 实现请求隔离，避免跨请求状态污染和内存泄漏
+ */
+class TransactionSynchronizationManager {
+    /**
+     * 获取当前请求的同步上下文
+     */
+    static getContext() {
+        let context = syncContextStorage.getStore();
+        if (!context) {
+            // 如果在 AsyncLocalStorage 上下文外调用，使用 fallback 上下文
+            // 主要用于单元测试和非 HTTP 请求场景
+            if (!fallbackContext) {
+                fallbackContext = createSyncContext();
+            }
+            context = fallbackContext;
+        }
+        return context;
+    }
+    /**
+     * 在 AsyncLocalStorage 上下文中运行代码
+     * 用于确保每个请求有独立的同步状态
+     */
+    static runInContext(fn) {
+        const context = createSyncContext();
+        return syncContextStorage.run(context, fn);
+    }
+    /**
+     * 初始化请求上下文（用于中间件）
+     */
+    static initRequestContext() {
+        const context = createSyncContext();
+        syncContextStorage.enterWith(context);
+        // 同时设置 fallback，用于单元测试
+        fallbackContext = context;
+    }
+    /**
+     * 检查是否在上下文中
+     */
+    static hasContext() {
+        return syncContextStorage.getStore() !== undefined;
+    }
+    /**
+     * 获取当前事务的唯一标识
+     */
+    static getCurrentTransactionKey(dataSourceName = 'default') {
+        return `tx_${dataSourceName}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    /**
+     * 注册事务同步回调
+     */
+    static registerSynchronization(synchronization, dataSourceName = 'default') {
+        if (!this.isSynchronizationActive(dataSourceName)) {
+            throw new Error('Transaction synchronization is not active');
+        }
+        const context = this.getContext();
+        if (!context.synchronizations.has(dataSourceName)) {
+            context.synchronizations.set(dataSourceName, []);
+        }
+        context.synchronizations.get(dataSourceName).push(synchronization);
+    }
+    /**
+     * 检查事务同步是否活跃
+     */
+    static isSynchronizationActive(dataSourceName = 'default') {
+        const context = this.getContext();
+        return context.synchronizations.has(dataSourceName);
+    }
+    /**
+     * 初始化事务同步
+     */
+    static initSynchronization(dataSourceName = 'default') {
+        if (this.isSynchronizationActive(dataSourceName)) {
+            throw new Error('Transaction synchronization already active');
+        }
+        const context = this.getContext();
+        context.synchronizations.set(dataSourceName, []);
+    }
+    /**
+     * 清理事务同步
+     */
+    static clearSynchronization(dataSourceName = 'default') {
+        const context = this.getContext();
+        context.synchronizations.delete(dataSourceName);
+    }
+    /**
+     * 获取所有同步回调（按优先级排序）
+     */
+    static getSynchronizations(dataSourceName = 'default') {
+        const context = this.getContext();
+        const syncs = context.synchronizations.get(dataSourceName) || [];
+        return syncs.sort((a, b) => {
+            var _a, _b, _c, _d;
+            const orderA = (_b = (_a = a.getOrder) === null || _a === void 0 ? void 0 : _a.call(a)) !== null && _b !== void 0 ? _b : Number.MAX_SAFE_INTEGER;
+            const orderB = (_d = (_c = b.getOrder) === null || _c === void 0 ? void 0 : _c.call(b)) !== null && _d !== void 0 ? _d : Number.MAX_SAFE_INTEGER;
+            return orderA - orderB;
+        });
+    }
+    /**
+     * 触发 beforeCommit 回调
+     */
+    static triggerBeforeCommit(readOnly_1) {
+        return __awaiter(this, arguments, void 0, function* (readOnly, dataSourceName = 'default') {
+            const syncs = this.getSynchronizations(dataSourceName);
+            for (const sync of syncs) {
+                if (sync.beforeCommit) {
+                    try {
+                        yield sync.beforeCommit(readOnly);
+                    }
+                    catch (error) {
+                        this.logger.error(`Error in beforeCommit callback:`, error);
+                        throw error;
+                    }
+                }
+            }
+        });
+    }
+    /**
+     * 触发 beforeCompletion 回调
+     */
+    static triggerBeforeCompletion() {
+        return __awaiter(this, arguments, void 0, function* (dataSourceName = 'default') {
+            const syncs = this.getSynchronizations(dataSourceName);
+            for (const sync of syncs) {
+                if (sync.beforeCompletion) {
+                    try {
+                        yield sync.beforeCompletion();
+                    }
+                    catch (error) {
+                        this.logger.error(`Error in beforeCompletion callback:`, error);
+                        // 不抛出错误，继续执行其他回调
+                    }
+                }
+            }
+        });
+    }
+    /**
+     * 触发 afterCommit 回调
+     */
+    static triggerAfterCommit() {
+        return __awaiter(this, arguments, void 0, function* (dataSourceName = 'default') {
+            const syncs = this.getSynchronizations(dataSourceName);
+            for (const sync of syncs) {
+                if (sync.afterCommit) {
+                    try {
+                        yield sync.afterCommit();
+                    }
+                    catch (error) {
+                        this.logger.error(`Error in afterCommit callback:`, error);
+                        // 不抛出错误，继续执行其他回调
+                    }
+                }
+            }
+        });
+    }
+    /**
+     * 触发 afterCompletion 回调
+     */
+    static triggerAfterCompletion(status_1) {
+        return __awaiter(this, arguments, void 0, function* (status, dataSourceName = 'default') {
+            const syncs = this.getSynchronizations(dataSourceName);
+            for (const sync of syncs) {
+                if (sync.afterCompletion) {
+                    try {
+                        yield sync.afterCompletion(status);
+                    }
+                    catch (error) {
+                        this.logger.error(`Error in afterCompletion callback:`, error);
+                        // 不抛出错误，继续执行其他回调
+                    }
+                }
+            }
+        });
+    }
+    /**
+     * 绑定资源到当前事务
+     */
+    static bindResource(key, value, dataSourceName = 'default') {
+        const context = this.getContext();
+        if (!context.resources.has(dataSourceName)) {
+            context.resources.set(dataSourceName, new Map());
+        }
+        const resourceMap = context.resources.get(dataSourceName);
+        if (resourceMap.has(key)) {
+            throw new Error(`Resource with key '${key}' already bound to transaction`);
+        }
+        resourceMap.set(key, { key, value });
+    }
+    /**
+     * 解绑资源
+     */
+    static unbindResource(key, dataSourceName = 'default') {
+        const context = this.getContext();
+        const resourceMap = context.resources.get(dataSourceName);
+        if (!resourceMap) {
+            return null;
+        }
+        const resource = resourceMap.get(key);
+        if (resource) {
+            resourceMap.delete(key);
+            return resource.value;
+        }
+        return null;
+    }
+    /**
+     * 获取绑定的资源
+     */
+    static getResource(key, dataSourceName = 'default') {
+        var _a;
+        const context = this.getContext();
+        const resourceMap = context.resources.get(dataSourceName);
+        return ((_a = resourceMap === null || resourceMap === void 0 ? void 0 : resourceMap.get(key)) === null || _a === void 0 ? void 0 : _a.value) || null;
+    }
+    /**
+     * 检查资源是否已绑定
+     */
+    static hasResource(key, dataSourceName = 'default') {
+        const context = this.getContext();
+        const resourceMap = context.resources.get(dataSourceName);
+        return (resourceMap === null || resourceMap === void 0 ? void 0 : resourceMap.has(key)) || false;
+    }
+    /**
+     * 设置当前事务是否活跃
+     */
+    static setActualTransactionActive(active, dataSourceName = 'default') {
+        const context = this.getContext();
+        context.actualTransactionActive.set(dataSourceName, active);
+    }
+    /**
+     * 检查是否有实际的事务
+     */
+    static isActualTransactionActive(dataSourceName = 'default') {
+        const context = this.getContext();
+        return context.actualTransactionActive.get(dataSourceName) || false;
+    }
+    /**
+     * 设置当前事务名称
+     */
+    static setCurrentTransactionName(name, dataSourceName = 'default') {
+        const context = this.getContext();
+        if (name) {
+            context.currentTransactionName.set(dataSourceName, name);
+        }
+        else {
+            context.currentTransactionName.delete(dataSourceName);
+        }
+    }
+    /**
+     * 获取当前事务名称
+     */
+    static getCurrentTransactionName(dataSourceName = 'default') {
+        const context = this.getContext();
+        return context.currentTransactionName.get(dataSourceName) || null;
+    }
+    /**
+     * 设置当前事务是否只读
+     */
+    static setCurrentTransactionReadOnly(readOnly, dataSourceName = 'default') {
+        const context = this.getContext();
+        context.currentTransactionReadOnly.set(dataSourceName, readOnly);
+    }
+    /**
+     * 检查当前事务是否只读
+     */
+    static isCurrentTransactionReadOnly(dataSourceName = 'default') {
+        const context = this.getContext();
+        return context.currentTransactionReadOnly.get(dataSourceName) || false;
+    }
+    /**
+     * 设置当前事务隔离级别
+     */
+    static setCurrentTransactionIsolationLevel(level, dataSourceName = 'default') {
+        const context = this.getContext();
+        if (level !== null) {
+            context.currentTransactionIsolationLevel.set(dataSourceName, level);
+        }
+        else {
+            context.currentTransactionIsolationLevel.delete(dataSourceName);
+        }
+    }
+    /**
+     * 获取当前事务隔离级别
+     */
+    static getCurrentTransactionIsolationLevel(dataSourceName = 'default') {
+        const context = this.getContext();
+        return context.currentTransactionIsolationLevel.get(dataSourceName) || null;
+    }
+    /**
+     * 清理所有事务同步状态
+     */
+    static clear(dataSourceName) {
+        const context = this.getContext();
+        if (dataSourceName) {
+            context.synchronizations.delete(dataSourceName);
+            context.resources.delete(dataSourceName);
+            context.actualTransactionActive.delete(dataSourceName);
+            context.currentTransactionName.delete(dataSourceName);
+            context.currentTransactionReadOnly.delete(dataSourceName);
+            context.currentTransactionIsolationLevel.delete(dataSourceName);
+        }
+        else {
+            // 清理所有
+            context.synchronizations.clear();
+            context.resources.clear();
+            context.actualTransactionActive.clear();
+            context.currentTransactionName.clear();
+            context.currentTransactionReadOnly.clear();
+            context.currentTransactionIsolationLevel.clear();
+            // 重置 fallback 上下文
+            if (fallbackContext === context) {
+                fallbackContext = null;
+            }
+        }
+    }
+    /**
+     * 获取所有资源
+     */
+    static getAllResources(dataSourceName = 'default') {
+        const context = this.getContext();
+        const resourceMap = context.resources.get(dataSourceName);
+        const result = new Map();
+        if (resourceMap) {
+            resourceMap.forEach((resource, key) => {
+                result.set(key, resource.value);
+            });
+        }
+        return result;
+    }
+}
+exports.TransactionSynchronizationManager = TransactionSynchronizationManager;
+TransactionSynchronizationManager.logger = new common_1.Logger(TransactionSynchronizationManager.name);

package/transaction/transaction.errors.d.ts

@@ -0,0 +1,91 @@
+/**
+ * 事务相关错误类
+ * 提供统一的错误处理机制
+ */
+export declare class TransactionError extends Error {
+    readonly code: string;
+    readonly dataSource?: string;
+    readonly transactionId?: string;
+    readonly cause?: Error;
+    constructor(message: string, code: string, dataSource?: string, transactionId?: string, cause?: Error);
+    /**
+     * 创建事务开始失败错误
+     */
+    static beginFailed(message: string, dataSource?: string, cause?: Error): TransactionError;
+    /**
+     * 创建事务提交失败错误
+     */
+    static commitFailed(message: string, dataSource?: string, transactionId?: string, cause?: Error): TransactionError;
+    /**
+     * 创建事务回滚失败错误
+     */
+    static rollbackFailed(message: string, dataSource?: string, transactionId?: string, cause?: Error): TransactionError;
+    /**
+     * 创建事务超时错误
+     */
+    static timeout(message: string, dataSource?: string, transactionId?: string): TransactionError;
+    /**
+     * 创建事务状态无效错误
+     */
+    static invalidState(message: string, dataSource?: string, transactionId?: string): TransactionError;
+    /**
+     * 创建数据源连接错误
+     */
+    static dataSourceNotFound(dataSource: string): TransactionError;
+    /**
+     * 创建传播行为不支持错误
+     */
+    static unsupportedPropagation(propagation: number): TransactionError;
+    /**
+     * 创建嵌套事务错误
+     */
+    static nestedTransactionFailed(message: string, dataSource?: string, cause?: Error): TransactionError;
+    /**
+     * 转换为JSON
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * 检查是否为特定错误代码
+     */
+    isErrorCode(code: string): boolean;
+    /**
+     * 检查是否为连接相关错误
+     */
+    isConnectionError(): boolean;
+    /**
+     * 检查是否为可重试错误
+     */
+    isRetryable(): boolean;
+}
+/**
+ * 事务错误处理工具类
+ */
+export declare class TransactionErrorHandler {
+    private static logger;
+    /**
+     * 设置日志记录器
+     */
+    static setLogger(logger: Console | {
+        error: (message?: any, ...optionalParams: any[]) => void;
+    }): void;
+    /**
+     * 安全地执行操作，捕获并转换错误
+     */
+    static safeExecute<T>(operation: () => Promise<T>, errorFactory: (error: Error) => TransactionError, context?: string): Promise<T>;
+    /**
+     * 处理事务超时
+     */
+    static handleTimeout(timeoutMs: number, dataSource?: string, transactionId?: string): TransactionError;
+    /**
+     * 处理回滚失败
+     */
+    static safeRollback(rollbackFn: () => Promise<void>, dataSource?: string, transactionId?: string): Promise<void>;
+    /**
+     * 格式化错误消息
+     */
+    static formatMessage(error: TransactionError): string;
+    /**
+     * 判断是否应该重试
+     */
+    static shouldRetry(error: Error, attempt: number, maxAttempts?: number): boolean;
+}