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

package/dist/transaction/data-source.util.js

@@ -0,0 +1,330 @@
+"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.addDataSources = exports.addDataSource = exports.withTransaction = exports.withDataSource = exports.isDataSourceAvailable = exports.getDefaultDataSource = exports.getDataSourceSafe = exports.getDataSource = exports.DataSourceUtil = void 0;
+const transaction_context_service_1 = require("./transaction-context.service");
+/**
+ * 全局数据源存储
+ * 用于在非请求上下文中存储和获取数据源
+ */
+class GlobalDataSourceStorage {
+    /**
+     * 注册数据源
+     */
+    static register(name, dataSource) {
+        this.dataSources.set(name, dataSource);
+    }
+    /**
+     * 批量注册数据源
+     */
+    static registerAll(dataSources) {
+        for (const [name, dataSource] of dataSources.entries()) {
+            this.register(name, dataSource);
+        }
+    }
+    /**
+     * 获取数据源
+     */
+    static get(name) {
+        return this.dataSources.get(name);
+    }
+    /**
+     * 获取默认数据源
+     */
+    static getDefault() {
+        return this.dataSources.get(this.defaultDataSourceName);
+    }
+    /**
+     * 设置默认数据源名称
+     */
+    static setDefaultName(name) {
+        this.defaultDataSourceName = name;
+    }
+    /**
+     * 检查数据源是否存在
+     */
+    static has(name) {
+        return this.dataSources.has(name);
+    }
+    /**
+     * 获取所有已注册的数据源名称
+     */
+    static getAllNames() {
+        return Array.from(this.dataSources.keys());
+    }
+    /**
+     * 移除数据源
+     */
+    static remove(name) {
+        this.dataSources.delete(name);
+    }
+    /**
+     * 清空所有数据源
+     */
+    static clear() {
+        this.dataSources.clear();
+    }
+}
+GlobalDataSourceStorage.dataSources = new Map();
+GlobalDataSourceStorage.defaultDataSourceName = 'default';
+/**
+ * 数据源工具类
+ * 提供静态方法在任意位置获取数据源
+ */
+class DataSourceUtil {
+    /**
+     * 获取数据源
+     * 按优先级从以下位置查找：
+     * 1. 当前请求上下文 (TransactionContextService)
+     * 2. 全局数据源存储 (GlobalDataSourceStorage)
+     *
+     * @param name 数据源名称，默认为 'default'
+     * @returns DataSource 实例
+     * @throws Error 如果数据源不存在
+     */
+    static getDataSource(name = 'default') {
+        // 1. 尝试从请求上下文获取
+        try {
+            return transaction_context_service_1.TransactionContextService.getDataSource(name);
+        }
+        catch (_a) {
+            // 忽略错误，继续尝试其他方式
+        }
+        // 2. 从全局存储获取
+        const dataSource = GlobalDataSourceStorage.get(name);
+        if (dataSource) {
+            return dataSource;
+        }
+        throw new Error(`DataSource '${name}' not found. ` +
+            `Please ensure it is registered via TransactionModule.registerDataSource() or TypeOrmModule.`);
+    }
+    /**
+     * 安全获取数据源，不存在时返回 null
+     *
+     * @param name 数据源名称
+     * @returns DataSource 实例或 null
+     */
+    static getDataSourceSafe(name = 'default') {
+        try {
+            return this.getDataSource(name);
+        }
+        catch (_a) {
+            return null;
+        }
+    }
+    /**
+     * 获取默认数据源
+     */
+    static getDefaultDataSource() {
+        return this.getDataSource('default');
+    }
+    /**
+     * 安全获取默认数据源
+     */
+    static getDefaultDataSourceSafe() {
+        return this.getDataSourceSafe('default');
+    }
+    /**
+     * 检查数据源是否可用
+     *
+     * @param name 数据源名称
+     * @returns 是否可用
+     */
+    static isAvailable(name = 'default') {
+        var _a;
+        try {
+            const ds = this.getDataSource(name);
+            return (_a = ds === null || ds === void 0 ? void 0 : ds.isInitialized) !== null && _a !== void 0 ? _a : false;
+        }
+        catch (_b) {
+            return false;
+        }
+    }
+    /**
+     * 获取所有可用数据源名称
+     */
+    static getAvailableDataSourceNames() {
+        const names = new Set();
+        // 从请求上下文获取
+        try {
+            const contextNames = transaction_context_service_1.TransactionContextService.getRegisteredDataSources();
+            contextNames.forEach((name) => names.add(name));
+        }
+        catch (_a) {
+            // 忽略错误
+        }
+        // 从全局存储获取
+        GlobalDataSourceStorage.getAllNames().forEach((name) => names.add(name));
+        return Array.from(names);
+    }
+    /**
+     * 批量获取数据源
+     *
+     * @param names 数据源名称数组
+     * @returns 数据源 Map
+     */
+    static getDataSources(names) {
+        const result = new Map();
+        for (const name of names) {
+            try {
+                const ds = this.getDataSource(name);
+                if (ds) {
+                    result.set(name, ds);
+                }
+            }
+            catch (_a) {
+                // 跳过不存在的数据源
+            }
+        }
+        return result;
+    }
+    /**
+     * 获取所有已注册的数据源
+     */
+    static getAllDataSources() {
+        const names = this.getAvailableDataSourceNames();
+        return this.getDataSources(names);
+    }
+    /**
+     * 手动注册数据源（用于非模块场景）
+     *
+     * @param name 数据源名称
+     * @param dataSource DataSource 实例
+     * @param isDefault 是否设为默认数据源
+     */
+    static registerDataSource(name, dataSource, isDefault = false) {
+        GlobalDataSourceStorage.register(name, dataSource);
+        if (isDefault) {
+            GlobalDataSourceStorage.setDefaultName(name);
+        }
+    }
+    /**
+     * 批量注册数据源
+     *
+     * @param dataSources 数据源 Map
+     * @param defaultName 默认数据源名称
+     */
+    static registerDataSources(dataSources, defaultName) {
+        GlobalDataSourceStorage.registerAll(dataSources);
+        if (defaultName) {
+            GlobalDataSourceStorage.setDefaultName(defaultName);
+        }
+    }
+    /**
+     * 使用数据源执行操作
+     *
+     * @param name 数据源名称
+     * @param operation 要执行的操作
+     * @returns 操作结果
+     */
+    static withDataSource(name, operation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const dataSource = this.getDataSource(name);
+            return operation(dataSource);
+        });
+    }
+    /**
+     * 使用默认数据源执行操作
+     *
+     * @param operation 要执行的操作
+     * @returns 操作结果
+     */
+    static withDefaultDataSource(operation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.withDataSource('default', operation);
+        });
+    }
+    /**
+     * 在事务中执行操作
+     *
+     * @param name 数据源名称
+     * @param operation 要执行的操作
+     * @returns 操作结果
+     */
+    static withTransaction(name, operation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const dataSource = this.getDataSource(name);
+            return dataSource.transaction((entityManager) => __awaiter(this, void 0, void 0, function* () {
+                // 通过 EntityManager 获取 DataSource
+                const ds = entityManager.connection;
+                return operation(ds);
+            }));
+        });
+    }
+    /**
+     * 在默认数据源的事务中执行操作
+     */
+    static withDefaultTransaction(operation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.withTransaction('default', operation);
+        });
+    }
+    /**
+     * 测试数据源连接
+     *
+     * @param name 数据源名称
+     * @returns 连接是否正常
+     */
+    static testConnection() {
+        return __awaiter(this, arguments, void 0, function* (name = 'default') {
+            try {
+                const dataSource = this.getDataSource(name);
+                if (dataSource.isInitialized) {
+                    yield dataSource.query('SELECT 1');
+                    return true;
+                }
+                return false;
+            }
+            catch (_a) {
+                return false;
+            }
+        });
+    }
+}
+exports.DataSourceUtil = DataSourceUtil;
+/**
+ * 便捷的别名
+ */
+exports.getDataSource = DataSourceUtil.getDataSource.bind(DataSourceUtil);
+exports.getDataSourceSafe = DataSourceUtil.getDataSourceSafe.bind(DataSourceUtil);
+exports.getDefaultDataSource = DataSourceUtil.getDefaultDataSource.bind(DataSourceUtil);
+exports.isDataSourceAvailable = DataSourceUtil.isAvailable.bind(DataSourceUtil);
+exports.withDataSource = DataSourceUtil.withDataSource.bind(DataSourceUtil);
+exports.withTransaction = DataSourceUtil.withTransaction.bind(DataSourceUtil);
+/**
+ * 添加数据源到全局注册表
+ * 用于在 TypeOrmModule.forRootAsync 的 useFactory 中手动注册数据源
+ *
+ * @param name 数据源名称
+ * @param dataSource DataSource 实例
+ * @param isDefault 是否设为默认数据源
+ *
+ * @example
+ * ```typescript
+ * TypeOrmModule.forRootAsync({
+ *   inject: [ApiConfigService],
+ *   useFactory: (config: ApiConfigService) => {
+ *     const dsConfig = config.typeormConfig;
+ *     // 在这里注册，确保数据源初始化后立即可用
+ *     addDataSource('default', dataSource, true);
+ *     return dsConfig;
+ *   },
+ * }),
+ * ```
+ */
+exports.addDataSource = DataSourceUtil.registerDataSource.bind(DataSourceUtil);
+/**
+ * 批量添加数据源
+ *
+ * @param dataSources 数据源 Map
+ * @param defaultName 默认数据源名称
+ */
+exports.addDataSources = DataSourceUtil.registerDataSources.bind(DataSourceUtil);

package/dist/transaction/database-adapter.d.ts

@@ -0,0 +1,44 @@
+import { DataSource, QueryRunner } from 'typeorm';
+/**
+ * 数据库类型
+ */
+export type DatabaseType = 'mysql' | 'mariadb' | 'postgres' | 'cockroachdb' | 'sqlite' | 'better-sqlite3' | 'mssql' | 'oracle' | 'mongodb' | 'cordova' | 'react-native' | 'nativescript' | 'sqljs' | 'expo' | 'capacitor';
+/**
+ * 数据库适配器
+ * 处理不同数据库的 SQL 语法差异
+ */
+export declare class DatabaseAdapter {
+    /**
+     * 获取数据库类型
+     */
+    static getDatabaseType(dataSource: DataSource): DatabaseType;
+    /**
+     * 检查数据库是否支持 SAVEPOINT
+     */
+    static supportsSavepoint(dataSource: DataSource): boolean;
+    /**
+     * 创建保存点
+     */
+    static createSavepoint(queryRunner: QueryRunner, savepointName: string): Promise<void>;
+    /**
+     * 回滚到保存点
+     */
+    static rollbackToSavepoint(queryRunner: QueryRunner, savepointName: string): Promise<void>;
+    /**
+     * 释放保存点
+     */
+    static releaseSavepoint(queryRunner: QueryRunner, savepointName: string): Promise<void>;
+    /**
+     * 执行健康检查查询
+     */
+    static healthCheck(dataSource: DataSource): Promise<boolean>;
+    /**
+     * 获取数据库特定的信息
+     */
+    static getDatabaseInfo(dataSource: DataSource): {
+        type: DatabaseType;
+        supportsSavepoint: boolean;
+        supportsNestedTransactions: boolean;
+        requiresReleaseSavepoint: boolean;
+    };
+}

package/dist/transaction/database-adapter.js

@@ -0,0 +1,240 @@
+"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.DatabaseAdapter = void 0;
+/**
+ * 数据库适配器
+ * 处理不同数据库的 SQL 语法差异
+ */
+class DatabaseAdapter {
+    /**
+     * 获取数据库类型
+     */
+    static getDatabaseType(dataSource) {
+        return dataSource.options.type;
+    }
+    /**
+     * 检查数据库是否支持 SAVEPOINT
+     */
+    static supportsSavepoint(dataSource) {
+        const type = this.getDatabaseType(dataSource);
+        // MongoDB 不支持传统事务和 SAVEPOINT
+        if (type === 'mongodb') {
+            return false;
+        }
+        // 其他关系型数据库都支持 SAVEPOINT
+        return true;
+    }
+    /**
+     * 创建保存点
+     */
+    static createSavepoint(queryRunner, savepointName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 检查 queryRunner.connection 是否存在
+            if (!queryRunner.connection) {
+                // 如果没有 connection，使用标准 SQL 语法（最常见的情况）
+                yield queryRunner.query(`SAVEPOINT ${savepointName}`);
+                return;
+            }
+            const type = this.getDatabaseType(queryRunner.connection);
+            switch (type) {
+                case 'mysql':
+                case 'mariadb':
+                case 'postgres':
+                case 'cockroachdb':
+                case 'sqlite':
+                case 'better-sqlite3':
+                case 'sqljs':
+                case 'cordova':
+                case 'react-native':
+                case 'nativescript':
+                case 'expo':
+                case 'capacitor':
+                    // 标准 SQL 语法
+                    yield queryRunner.query(`SAVEPOINT ${savepointName}`);
+                    break;
+                case 'mssql':
+                    // SQL Server 使用 SAVE TRANSACTION
+                    yield queryRunner.query(`SAVE TRANSACTION ${savepointName}`);
+                    break;
+                case 'oracle':
+                    // Oracle 使用标准 SAVEPOINT 语法
+                    yield queryRunner.query(`SAVEPOINT ${savepointName}`);
+                    break;
+                case 'mongodb':
+                    throw new Error('MongoDB does not support SAVEPOINT. Use transactions instead.');
+                default:
+                    // 对于未知的数据库类型，尝试使用标准 SQL 语法
+                    yield queryRunner.query(`SAVEPOINT ${savepointName}`);
+            }
+        });
+    }
+    /**
+     * 回滚到保存点
+     */
+    static rollbackToSavepoint(queryRunner, savepointName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 检查 queryRunner.connection 是否存在
+            if (!queryRunner.connection) {
+                // 如果没有 connection，使用标准 SQL 语法（最常见的情况）
+                yield queryRunner.query(`ROLLBACK TO SAVEPOINT ${savepointName}`);
+                return;
+            }
+            const type = this.getDatabaseType(queryRunner.connection);
+            switch (type) {
+                case 'mysql':
+                case 'mariadb':
+                case 'postgres':
+                case 'cockroachdb':
+                case 'sqlite':
+                case 'better-sqlite3':
+                case 'sqljs':
+                case 'cordova':
+                case 'react-native':
+                case 'nativescript':
+                case 'expo':
+                case 'capacitor':
+                case 'oracle':
+                    // 标准 SQL 语法
+                    yield queryRunner.query(`ROLLBACK TO SAVEPOINT ${savepointName}`);
+                    break;
+                case 'mssql':
+                    // SQL Server 使用 ROLLBACK TRANSACTION
+                    yield queryRunner.query(`ROLLBACK TRANSACTION ${savepointName}`);
+                    break;
+                case 'mongodb':
+                    throw new Error('MongoDB does not support SAVEPOINT. Use transactions instead.');
+                default:
+                    // 对于未知的数据库类型，尝试使用标准 SQL 语法
+                    yield queryRunner.query(`ROLLBACK TO SAVEPOINT ${savepointName}`);
+            }
+        });
+    }
+    /**
+     * 释放保存点
+     */
+    static releaseSavepoint(queryRunner, savepointName) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 检查 queryRunner.connection 是否存在
+            if (!queryRunner.connection) {
+                // 如果没有 connection，尝试使用标准 SQL 语法
+                try {
+                    yield queryRunner.query(`RELEASE SAVEPOINT ${savepointName}`);
+                }
+                catch (error) {
+                    // 静默失败，因为某些数据库不支持 RELEASE
+                }
+                return;
+            }
+            const type = this.getDatabaseType(queryRunner.connection);
+            switch (type) {
+                case 'mysql':
+                case 'mariadb':
+                case 'postgres':
+                case 'cockroachdb':
+                case 'sqlite':
+                case 'better-sqlite3':
+                case 'sqljs':
+                case 'cordova':
+                case 'react-native':
+                case 'nativescript':
+                case 'expo':
+                case 'capacitor':
+                    // 标准 SQL 语法
+                    yield queryRunner.query(`RELEASE SAVEPOINT ${savepointName}`);
+                    break;
+                case 'oracle':
+                    // Oracle 不支持 RELEASE SAVEPOINT，保存点会在提交时自动释放
+                    // 不执行任何操作
+                    break;
+                case 'mssql':
+                    // SQL Server 不支持 RELEASE，保存点会在提交或回滚时自动清理
+                    // 不执行任何操作
+                    break;
+                case 'mongodb':
+                    // MongoDB 不支持
+                    break;
+                default:
+                    // 对于未知的数据库类型，尝试使用标准 SQL 语法
+                    // 如果失败也不抛出错误，因为某些数据库不需要显式释放
+                    try {
+                        yield queryRunner.query(`RELEASE SAVEPOINT ${savepointName}`);
+                    }
+                    catch (error) {
+                        // 静默失败，因为某些数据库不支持 RELEASE
+                    }
+            }
+        });
+    }
+    /**
+     * 执行健康检查查询
+     */
+    static healthCheck(dataSource) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const type = this.getDatabaseType(dataSource);
+            try {
+                switch (type) {
+                    case 'mysql':
+                    case 'mariadb':
+                        yield dataSource.query('SELECT 1');
+                        break;
+                    case 'postgres':
+                    case 'cockroachdb':
+                        yield dataSource.query('SELECT 1');
+                        break;
+                    case 'mssql':
+                        yield dataSource.query('SELECT 1');
+                        break;
+                    case 'oracle':
+                        yield dataSource.query('SELECT 1 FROM DUAL');
+                        break;
+                    case 'sqlite':
+                    case 'better-sqlite3':
+                    case 'sqljs':
+                    case 'cordova':
+                    case 'react-native':
+                    case 'nativescript':
+                    case 'expo':
+                    case 'capacitor':
+                        yield dataSource.query('SELECT 1');
+                        break;
+                    case 'mongodb':
+                        // MongoDB 使用不同的健康检查方式
+                        yield dataSource.query('{ ping: 1 }');
+                        break;
+                    default:
+                        // 默认使用 SELECT 1
+                        yield dataSource.query('SELECT 1');
+                }
+                return true;
+            }
+            catch (error) {
+                return false;
+            }
+        });
+    }
+    /**
+     * 获取数据库特定的信息
+     */
+    static getDatabaseInfo(dataSource) {
+        const type = this.getDatabaseType(dataSource);
+        const supportsSavepoint = this.supportsSavepoint(dataSource);
+        // 检查是否需要显式释放 SAVEPOINT
+        const requiresReleaseSavepoint = !['oracle', 'mssql', 'mongodb'].includes(type);
+        return {
+            type,
+            supportsSavepoint,
+            supportsNestedTransactions: supportsSavepoint,
+            requiresReleaseSavepoint,
+        };
+    }
+}
+exports.DatabaseAdapter = DatabaseAdapter;

package/dist/transaction/decorators/entity-datasource.decorator.d.ts

@@ -0,0 +1,62 @@
+import 'reflect-metadata';
+/**
+ * Entity 数据源装饰器
+ * 用于指定 Entity 应该使用哪个数据源
+ */
+export declare const ENTITY_DATASOURCE_METADATA_KEY = "entity:datasource";
+/**
+ * 数据源装饰器 - 为 Entity 指定数据源
+ *
+ * @param dataSourceName 数据源名称
+ *
+ * 使用示例：
+ * ```typescript
+ * @Entity('users')
+ * @DataSource('user_db')
+ * export class User {
+ *   @PrimaryGeneratedColumn()
+ *   id: number;
+ *
+ *   @Column()
+ *   name: string;
+ * }
+ * ```
+ */
+export declare function DataSource(dataSourceName: string): ClassDecorator;
+/**
+ * 获取 Entity 的数据源名称
+ * @param entityClass Entity 类或构造函数
+ * @returns 数据源名称，如果未指定则返回 null
+ */
+export declare function getEntityDataSource(entityClass: any): string | null;
+/**
+ * 检查 Entity 是否指定了数据源
+ * @param entityClass Entity 类或构造函数
+ * @returns 是否指定了数据源
+ */
+export declare function hasEntityDataSource(entityClass: any): boolean;
+/**
+ * 带数据源的 Entity 基类
+ * 继承这个基类的 Entity 可以通过实现 useDataSource 方法动态指定数据源
+ */
+export declare abstract class BaseEntityWithDataSource {
+    /**
+     * 子类可以重写此方法来动态指定数据源
+     * @returns 数据源名称
+     */
+    static useDataSource?(): string;
+    /**
+     * 实例方法版本，用于动态获取数据源
+     * @returns 数据源名称
+     */
+    getDataSource?(): string;
+}
+/**
+ * 动态数据源装饰器
+ * 标记 Entity 使用动态数据源（通过 useDataSource 方法指定）
+ */
+export declare function DynamicDataSource(): ClassDecorator;
+/**
+ * 检查 Entity 是否使用动态数据源
+ */
+export declare function isDynamicDataSourceEntity(entityClass: any): boolean;