@nestplatform/transactional 1.0.0 → 1.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestplatform/transactional",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,15 +9,17 @@
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "dependencies": {
-    "@nestplatform/common": "^1.0.0"
+    "@nestplatform/common": "^1.0.1"
   },
   "peerDependencies": {
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0",
     "reflect-metadata": "^0.1.13 || ^0.2.0"
   },
-  "keywords": [],
-  "author": "",
+  "keywords": [
+    "transactional"
+  ],
+  "author": "Đường Trung Nguyên",
   "license": "ISC",
   "type": "commonjs"
-}
+}

package/src/decorators/index.ts

@@ -1 +0,0 @@
-export * from "./transactional.decorator";

package/src/decorators/transactional.decorator.ts

@@ -1,54 +0,0 @@
-import { applyDecorators, SetMetadata } from "@nestjs/common";
-
-import { NO_TRANSACTIONAL_METADATA, TRANSACTIONAL_METADATA } from "../transactional.constant";
-import { TransactionalOptions, TransactionPropagation } from "../types";
-
-const TRANSACTIONAL_DEFAULTS: Required<Omit<TransactionalOptions, "adapter" | "isolation">> = {
-  propagation: TransactionPropagation.REQUIRED,
-  logging: false,
-};
-
-/**
- * Marks a class or method as transactional.
- *
- * - **Method-level**: Wraps the decorated method in a database transaction.
- * - **Class-level**: Wraps all methods of the class in transactions.
- *   Use `@NoTransactional()` on specific methods to opt-out.
- *
- * @example
- * // Method-level
- * @Transactional()
- * async createOrder(dto: CreateOrderDto) { ... }
- *
- * // Method-level with options
- * @Transactional({ propagation: TransactionPropagation.REQUIRES_NEW })
- * async logAuditEvent(event: AuditEvent) { ... }
- *
- * // Class-level
- * @Transactional()
- * @Injectable()
- * export class PaymentService { ... }
- */
-export const Transactional = (options?: TransactionalOptions): ClassDecorator & MethodDecorator => {
-  const mergedOptions: TransactionalOptions = {
-    ...TRANSACTIONAL_DEFAULTS,
-    ...options,
-  };
-
-  return applyDecorators(SetMetadata(TRANSACTIONAL_METADATA, mergedOptions));
-};
-
-/**
- * Excludes a method from class-level `@Transactional()` wrapping.
- *
- * @example
- * @Transactional()
- * @Injectable()
- * export class PaymentService {
- *     @NoTransactional()
- *     async getPaymentStatus(id: string) { ... } // Not wrapped in transaction
- * }
- */
-export const NoTransactional = (): MethodDecorator => {
-  return applyDecorators(SetMetadata(NO_TRANSACTIONAL_METADATA, true));
-};

package/src/index.ts

@@ -1,6 +0,0 @@
-export * from "./interfaces";
-export * from "./decorators";
-export * from "./transactional.module";
-export * from "./transactional.constant";
-export * from "./transaction-context";
-export * from "./types";

package/src/interfaces/index.ts

@@ -1 +0,0 @@
-export * from "./transaction-adapter.interface";

package/src/interfaces/transaction-adapter.interface.ts

@@ -1,41 +0,0 @@
-import { TransactionExecuteOptions } from "../types";
-
-/**
- * Plugin interface for ORM transaction adapters.
- *
- * Each adapter is responsible for managing the lifecycle of transactions
- * for its specific ORM (TypeORM, Mongoose, MikroORM, etc.).
- *
- * The adapter handles:
- * 1. Creating/reusing transactions based on propagation behavior
- * 2. Committing on success, rolling back on error
- * 3. Managing savepoints for NESTED propagation
- * 4. Context propagation (storing/retrieving the active transaction)
- */
-export interface ITransactionAdapter {
-  /**
-   * Proxy an instance to inject transaction management logic.
-   *
-   * @param instance - The instance to proxy
-   * @returns The proxied instance
-   */
-  proxyInstance?<T extends object>(instance: T): T;
-
-  /**
-   * Execute callback within a transaction.
-   *
-   * @param callback - The function to execute within the transaction scope
-   * @param options  - Transaction execution options (propagation, isolation)
-   * @returns The result of the callback
-   */
-  execute<T>(callback: () => Promise<T>, options: TransactionExecuteOptions): Promise<T>;
-
-  /**
-   * Get the active transaction handle from the current context.
-   * Returns `undefined` if no transaction is active.
-   *
-   * This is useful for repositories or services that need to access
-   * the current transaction directly (e.g., TypeORM QueryRunner, Mongoose Session).
-   */
-  getActiveTransaction(): any | undefined;
-}

package/src/providers/index.ts

@@ -1,2 +0,0 @@
-export * from "./transaction-adapter.provider";
-export * from "./transaction-adapter-async.provider";

package/src/providers/transaction-adapter-async.provider.ts

@@ -1,17 +0,0 @@
-import { FactoryProvider } from "@nestjs/common";
-
-import { DEFAULT_TRANSACTION_ADAPTER, TRANSACTION_ADAPTERS } from "../transactional.constant";
-import { TransactionalModuleConfigAsync } from "../types";
-
-export const TransactionAdapterAsyncProvider = (config: TransactionalModuleConfigAsync): FactoryProvider => {
-  return {
-    provide: TRANSACTION_ADAPTERS,
-    inject: config.inject,
-    useFactory: async (...args) => {
-      const { adapters } = await config.useFactory(...args);
-
-      // If single adapter (has `execute` method), wrap in default key
-      return !!adapters["execute"] ? { [DEFAULT_TRANSACTION_ADAPTER]: adapters } : adapters;
-    },
-  };
-};

package/src/providers/transaction-adapter.provider.ts

@@ -1,16 +0,0 @@
-import { FactoryProvider } from "@nestjs/common";
-
-import { DEFAULT_TRANSACTION_ADAPTER, TRANSACTION_ADAPTERS } from "../transactional.constant";
-import { TransactionalModuleConfigSync } from "../types";
-
-export const TransactionAdapterProvider = (config: TransactionalModuleConfigSync): FactoryProvider => {
-  return {
-    provide: TRANSACTION_ADAPTERS,
-    useFactory: async () => {
-      const adapters = config.adapters;
-
-      // If single adapter (has `execute` method), wrap in default key
-      return !!adapters["execute"] ? { [DEFAULT_TRANSACTION_ADAPTER]: adapters } : adapters;
-    },
-  };
-};

package/src/transaction-context.ts

@@ -1,47 +0,0 @@
-import { AsyncLocalStorage } from "node:async_hooks";
-
-/**
- * Transaction store containing the active transaction handle and its adapter.
- * Propagated through the async call stack via AsyncLocalStorage (Node.js CLS).
- */
-export type TransactionStore = {
-  /** The active transaction handle (e.g., TypeORM QueryRunner, Mongoose Session, MikroORM EntityManager) */
-  transaction: any;
-
-  /** The adapter key that owns this transaction */
-  adapterKey: string;
-};
-
-/**
- * AsyncLocalStorage-based transaction context propagation.
- *
- * Mirrors how Spring uses ThreadLocal to propagate transaction context.
- * In Node.js, AsyncLocalStorage achieves the same effect across the async call stack.
- */
-export class TransactionContext {
-  private static readonly storage = new AsyncLocalStorage<TransactionStore>();
-
-  /**
-   * Run a callback within a transaction context.
-   * The store will be available to all async operations within the callback scope.
-   */
-  static run<T>(store: TransactionStore, fn: () => Promise<T>): Promise<T> {
-    return this.storage.run(store, fn);
-  }
-
-  /**
-   * Get the current transaction store from the async context.
-   * Returns `undefined` if no transaction is active in the current scope.
-   */
-  static getStore(): TransactionStore | undefined {
-    return this.storage.getStore();
-  }
-
-  /**
-   * Get the current transaction from the async context.
-   * Returns `undefined` if no transaction is active in the current scope.
-   */
-  static getTransaction<T = any>(): T | undefined {
-    return this.storage.getStore()?.transaction;
-  }
-}

package/src/transactional-feature.decoration.ts

@@ -1,64 +0,0 @@
-import { Inject, Injectable, Logger } from "@nestjs/common";
-
-import { FeatureDecoration, stringifyMethod } from "@nestplatform/common";
-
-import { DEFAULT_TRANSACTION_ADAPTER, TRANSACTION_ADAPTERS } from "./transactional.constant";
-import { ITransactionAdapter } from "./interfaces";
-import { TransactionalOptions, TransactionAdapters, TransactionPropagation } from "./types";
-
-const LOGGING_CONTEXT = "TransactionalModule";
-
-@Injectable()
-export class TransactionalFeatureDecoration extends FeatureDecoration {
-  constructor(@Inject(TRANSACTION_ADAPTERS) private readonly adapters: TransactionAdapters) {
-    super();
-  }
-
-  /**
-   * Wrap a method with transaction management logic.
-   * Resolves the correct adapter and delegates execution.
-   */
-  // eslint-disable-next-line @typescript-eslint/ban-types
-  public wrapMethodWithTransaction(instance: any, methodName: string, originalMethod: Function, options: TransactionalOptions): void {
-    const adapterKey: string = options.adapter || DEFAULT_TRANSACTION_ADAPTER;
-    const fallbackAdapter: ITransactionAdapter | undefined = Object.values(this.adapters)[0];
-
-    const adapter: ITransactionAdapter | undefined = this.adapters[adapterKey] || fallbackAdapter;
-
-    if (!adapter) {
-      if (options.logging) {
-        Logger.warn(`Transaction adapter "${adapterKey}" not found. Skip wrapping for method ${methodName}.`, LOGGING_CONTEXT);
-      }
-
-      return;
-    }
-
-    instance[methodName] = async (...args: any[]): Promise<any> => {
-      const methodString: string = stringifyMethod(methodName, ...args);
-
-      if (options.logging) {
-        Logger.log(`Starting transaction for \`${methodString}\` [${options.propagation || TransactionPropagation.REQUIRED}]`, LOGGING_CONTEXT);
-      }
-
-      try {
-        const proxiedInstance = adapter.proxyInstance?.(instance);
-        const result = await adapter.execute(() => originalMethod.apply(proxiedInstance || instance, args), {
-          propagation: options.propagation || TransactionPropagation.REQUIRED,
-          isolation: options.isolation,
-        });
-
-        if (options.logging) {
-          Logger.log(`Transaction committed for \`${methodString}\``, LOGGING_CONTEXT);
-        }
-
-        return result;
-      } catch (error) {
-        if (options.logging) {
-          Logger.error(`Transaction rolled back for \`${methodString}\`: ${error}`, LOGGING_CONTEXT);
-        }
-
-        throw error;
-      }
-    };
-  }
-}

package/src/transactional-metadata.accessor.ts

@@ -1,30 +0,0 @@
-import { Injectable } from "@nestjs/common";
-import { Reflector } from "@nestjs/core";
-
-import { MetadataAccessor } from "@nestplatform/common";
-
-import { NO_TRANSACTIONAL_METADATA, TRANSACTIONAL_METADATA } from "./transactional.constant";
-import { TransactionalOptions } from "./types";
-
-@Injectable()
-export class TransactionalMetadataAccessor extends MetadataAccessor {
-  constructor(protected readonly reflector: Reflector) {
-    super();
-  }
-
-  /**
-   * Get @Transactional() metadata from a class or method.
-   */
-  // eslint-disable-next-line @typescript-eslint/ban-types
-  public getTransactionalMetadata(target: Function): TransactionalOptions | undefined {
-    return this.getMetadata<TransactionalOptions>(TRANSACTIONAL_METADATA, target);
-  }
-
-  /**
-   * Get @NoTransactional() metadata from a method.
-   */
-  // eslint-disable-next-line @typescript-eslint/ban-types
-  public getNoTransactionalMetadata(target: Function): boolean | undefined {
-    return this.getMetadata<boolean>(NO_TRANSACTIONAL_METADATA, target);
-  }
-}

package/src/transactional-metadata.explorer.ts

@@ -1,62 +0,0 @@
-import { Injectable } from "@nestjs/common";
-
-import { IFeatureExplorer, FeatureExplorer, MethodContext, ProviderContext } from "@nestplatform/common";
-
-import { TransactionalFeatureDecoration } from "./transactional-feature.decoration";
-import { TransactionalMetadataAccessor } from "./transactional-metadata.accessor";
-import { TransactionalOptions } from "./types";
-
-@Injectable()
-@FeatureExplorer()
-export class TransactionalMetadataExplorer implements IFeatureExplorer {
-  /**
-   * Stores class-level @Transactional() options, keyed by class constructor.
-   * Used to apply class-level defaults to all methods of the class.
-   */
-  // eslint-disable-next-line @typescript-eslint/ban-types
-  private readonly classLevelOptions = new Map<Function, TransactionalOptions>();
-
-  constructor(
-    private readonly metadataAccessor: TransactionalMetadataAccessor,
-    private readonly featureDecoration: TransactionalFeatureDecoration,
-  ) {}
-
-  /**
-   * Scan each provider for class-level @Transactional() metadata.
-   */
-  onProvider(ctx: ProviderContext): void {
-    const { metatype } = ctx;
-
-    const classOptions: TransactionalOptions | undefined = this.metadataAccessor.getTransactionalMetadata(metatype);
-
-    if (classOptions) {
-      this.classLevelOptions.set(metatype, classOptions);
-    }
-  }
-
-  /**
-   * Scan each method for @Transactional()/@NoTransactional() metadata.
-   * Class-level options serve as defaults; method-level options override them.
-   */
-  onMethod(ctx: MethodContext): void {
-    const { instance, methodName, methodRef, metatype } = ctx;
-
-    // Check if method is explicitly excluded
-    const isExcluded: boolean | undefined = this.metadataAccessor.getNoTransactionalMetadata(methodRef);
-
-    if (isExcluded) return;
-
-    // Method-level options take highest priority
-    const methodOptions: TransactionalOptions | undefined = this.metadataAccessor.getTransactionalMetadata(methodRef);
-
-    // Class-level options as fallback
-    const classOptions: TransactionalOptions | undefined = this.classLevelOptions.get(metatype);
-
-    // Merge: method-level overrides class-level
-    const resolvedOptions: TransactionalOptions | undefined = methodOptions ? { ...classOptions, ...methodOptions } : classOptions;
-
-    if (!resolvedOptions) return;
-
-    this.featureDecoration.wrapMethodWithTransaction(instance, methodName, methodRef, resolvedOptions);
-  }
-}

package/src/transactional.constant.ts

@@ -1,8 +0,0 @@
-export const TRANSACTIONAL_METADATA = Symbol.for("metadata:transactional");
-export const NO_TRANSACTIONAL_METADATA = Symbol.for("metadata:no_transactional");
-
-export const TRANSACTION_ADAPTERS = Symbol.for("token:TRANSACTION_ADAPTERS");
-
-/* constants */
-
-export const DEFAULT_TRANSACTION_ADAPTER = "default";

package/src/transactional.module.ts

@@ -1,35 +0,0 @@
-import { DynamicModule, Module } from "@nestjs/common";
-
-import { FeatureExplorerModule, ConfigurableModule } from "@nestplatform/common";
-
-import { TransactionAdapterAsyncProvider, TransactionAdapterProvider } from "./providers";
-import { TransactionalModuleConfigAsync, TransactionalModuleConfigSync } from "./types";
-import { TransactionalMetadataExplorer } from "./transactional-metadata.explorer";
-import { TransactionalFeatureDecoration } from "./transactional-feature.decoration";
-import { TransactionalMetadataAccessor } from "./transactional-metadata.accessor";
-
-@Module({})
-export class TransactionalModule extends ConfigurableModule {
-  static register(config: TransactionalModuleConfigSync): DynamicModule {
-    return super.config(config, {
-      global: true,
-      module: TransactionalModule,
-      imports: [FeatureExplorerModule],
-      providers: [TransactionAdapterProvider(config), TransactionalMetadataExplorer, TransactionalMetadataAccessor, TransactionalFeatureDecoration],
-    });
-  }
-
-  static registerAsync(config: TransactionalModuleConfigAsync): DynamicModule {
-    return super.config(config, {
-      global: true,
-      module: TransactionalModule,
-      imports: [FeatureExplorerModule],
-      providers: [
-        TransactionAdapterAsyncProvider(config),
-        TransactionalMetadataExplorer,
-        TransactionalMetadataAccessor,
-        TransactionalFeatureDecoration,
-      ],
-    });
-  }
-}

package/src/types/index.ts

@@ -1,2 +0,0 @@
-export * from "./transactional.type";
-export * from "./transactional-module.type";

package/src/types/transactional-module.type.ts

@@ -1,10 +0,0 @@
-import { ModuleConfigAsync, ModuleConfigBase } from "@nestplatform/common";
-import { ITransactionAdapter } from "../interfaces";
-
-export type TransactionalModuleConfig = {
-  adapters: ITransactionAdapter | Record<string, ITransactionAdapter>;
-};
-
-export type TransactionalModuleConfigSync = Omit<ModuleConfigBase, "global"> & TransactionalModuleConfig;
-
-export type TransactionalModuleConfigAsync = Omit<ModuleConfigBase, "global"> & ModuleConfigAsync<TransactionalModuleConfig>;

package/src/types/transactional.type.ts

@@ -1,33 +0,0 @@
-import { ITransactionAdapter } from "../interfaces";
-
-export enum TransactionPropagation {
-  /** Join existing transaction or create a new one (default) */
-  REQUIRED = "REQUIRED",
-
-  /** Always create a new transaction, suspending the current one */
-  REQUIRES_NEW = "REQUIRES_NEW",
-
-  /** Create a savepoint within the existing transaction */
-  NESTED = "NESTED",
-}
-
-export enum TransactionIsolation {
-  READ_UNCOMMITTED = "READ UNCOMMITTED",
-  READ_COMMITTED = "READ COMMITTED",
-  REPEATABLE_READ = "REPEATABLE READ",
-  SERIALIZABLE = "SERIALIZABLE",
-}
-
-export type TransactionalOptions = {
-  propagation?: TransactionPropagation;
-  isolation?: TransactionIsolation;
-  adapter?: string;
-  logging?: boolean;
-};
-
-export type TransactionExecuteOptions = {
-  propagation: TransactionPropagation;
-  isolation?: TransactionIsolation;
-};
-
-export type TransactionAdapters = Record<string, ITransactionAdapter>;