typeorm-transactional

Before using the library, you must call initializeTransactionalContext to set up the storage driver and patch TypeORM components (like EntityManager and Repository) to support transactional propagation. You can optionally provide configuration options to customize the library's behavior.

Supported options:

• maxHookHandlers (number): Controls how many hooks (commit, rollback, complete) can be used simultaneously. Default is 10. Setting this to 0 or Infinity allows unlimited listeners.
• storageDriver (StorageDriverEnum): Controls the storage driver used for persistence during async request timespans. By default, AsyncLocalStorage is preferred if supported by the runtime.

import { initializeTransactionalContext } from 'typeorm-transactional';

initializeTransactionalContext({
  maxHookHandlers: 20,
  // storageDriver: StorageDriverEnum.ASYNC_LOCAL_STORAGE
});

You can register callbacks to run at specific stages of a transaction's lifecycle:

• runOnTransactionCommit(cb): Executes cb after the transaction is successfully committed.
• runOnTransactionRollback(cb): Executes cb after a rollback occurs. The callback receives the error that triggered the rollback as an argument.
• runOnTransactionComplete(cb): Executes cb when the transactional context is finished (either commit or rollback). The callback receives the error (if any) as an argument.

import { 
  Transactional, 
  runOnTransactionCommit, 
  runOnTransactionRollback, 
  runOnTransactionComplete 
} from 'typeorm-transactional';

class PostService {
  @Transactional()
  async createPost(id: string, message: string) {
    const post = this.repository.create({ id, message });
    const result = await this.repository.save(post);

    // Runs after successful commit
    runOnTransactionCommit(() => this.events.emit('post created'));

    // Runs after rollback, receives error
    runOnTransactionRollback((err) => this.events.emit('post failed', err));

    // Runs at the very end, receives error or null
    runOnTransactionComplete((err) => this.events.emit(err ? 'error' : 'success'));

    return result;
  }
}

Apply the @Transactional() decorator to service methods to ensure they run within a transaction.

• If a transaction already exists, the method will join it (default behavior).
• You can specify a connectionName to target a specific DataSource.
• You can specify propagation to control how the transaction behaves relative to existing ones.
• You can specify isolationLevel to set the database isolation level.

import { Transactional } from 'typeorm-transactional';

export class PostService {
  constructor(readonly repository: PostRepository) 

  @Transactional() // Joins existing transaction or creates a new one
  async createPost(id, message): Promise<Post> {
    const post = this.repository.create({ id, message });
    return this.repository.save(post);
  }

  @Transactional({ connectionName: 'second-data-source' })
  async useOtherDataSource() {
    // ...
  }
}

Since the library manages the transaction lifecycle, use these helper functions to execute logic based on the transaction outcome:

• runOnTransactionCommit(cb): Executes cb after the transaction is successfully committed.
• runOnTransactionRollback(cb): Executes cb after a rollback. The callback receives the error that caused the rollback.
• runOnTransactionComplete(cb): Executes cb when the transactional context completes. If an error occurred, it is passed to the callback.

import { Transactional, runOnTransactionCommit } from 'typeorm-transactional';

export class PostService {
    @Transactional()
    async createPost(id, message): Promise<Post> {
        const result = await this.repository.save(this.repository.create({ id, message }));

        runOnTransactionCommit(() => {
            console.log('Post was successfully saved to the database!');
        });

        return result;
    }
}