typeorm-transactional
Advanced tools
A Transactional Method Decorator for typeorm that uses cls-hooked to handle and propagate transactions between different repositories and service methods. Inpired by Spring Trasnactional Annotation and Sequelize CLS
A Transactional Method Decorator for typeorm that uses ALS or cls-hooked to handle and propagate transactions between different repositories and service methods.
See Changelog
## npm
npm install --save typeorm-transactional
## Needed dependencies
npm install --save typeorm reflect-metadata
Or
yarn add typeorm-transactional
## Needed dependencies
yarn add typeorm reflect-metadata
Note: You will need to import
reflect-metadatasomewhere in the global place of your app - https://github.com/typeorm/typeorm#installation
In order to use it, you will first need to initialize the transactional context before your application is started
import { initializeTransactionalContext } from 'typeorm-transactional';
initializeTransactionalContext()
...
app = express()
...
IMPORTANT NOTE
Calling initializeTransactionalContext must happen BEFORE any application context is initialized!
New versions of TypeORM use DataSource instead of Connection, so most of the API has been changed and the old API has become deprecated.
To be able to use TypeORM entities in transactions, you must first add a DataSource using the addTransactionalDataSource function:
import { DataSource } from 'typeorm';
import { initializeTransactionalContext, addTransactionalDataSource, StorageDriver } from 'typeorm-transactional';
...
const dataSource = new DataSource({
type: 'postgres',
host: 'localhost',
port: 5435,
username: 'postgres',
password: 'postgres'
});
...
initializeTransactionalContext({ storageDriver: StorageDriver.ASYNC_LOCAL_STORAGE });
addTransactionalDataSource(dataSource);
...
Example for Nest.js:
// main.ts
import { NestFactory } from '@nestjs/core';
import { initializeTransactionalContext } from 'typeorm-transactional';
import { AppModule } from './app';
const bootstrap = async () => {
initializeTransactionalContext();
const app = await NestFactory.create(AppModule, {
abortOnError: true,
});
await app.listen(3000);
};
bootstrap();
// app.module.ts
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { DataSource } from 'typeorm';
import { addTransactionalDataSource } from 'typeorm-transactional';
@Module({
imports: [
TypeOrmModule.forRootAsync({
useFactory() {
return {
type: 'postgres',
host: 'localhost',
port: 5435,
username: 'postgres',
password: 'postgres',
synchronize: true,
logging: false,
};
},
async dataSourceFactory(options) {
if (!options) {
throw new Error('Invalid options passed');
}
return addTransactionalDataSource(new DataSource(options));
},
}),
...
],
providers: [...],
exports: [...],
})
class AppModule {}
Unlike typeorm-transactional-cls-hooked, you do not need to use BaseRepositoryor otherwise define repositories.
You can also use this library with custom TypeORM repositories. You can read more about them here and here.
NOTE: You can add multiple DataSource if you need it
@Transactional() decoratorconnectionName as argument (by default it is default) to specify the data source to be userpropagation as argument to define the propagation behaviourisolationLevel as argument to define the isolation level (by default it will use your database driver's default isolation level)export class PostService {
constructor(readonly repository: PostRepository)
@Transactional() // Will open a transaction if one doesn't already exist
async createPost(id, message): Promise<Post> {
const post = this.repository.create({ id, message })
return this.repository.save(post)
}
}
You can also use DataSource/EntityManager objects together with repositories in transactions:
export class PostService {
constructor(readonly repository: PostRepository, readonly dataSource: DataSource)
@Transactional() // Will open a transaction if one doesn't already exist
async createAndGetPost(id, message): Promise<Post> {
const post = this.repository.create({ id, message })
await this.repository.save(post)
return dataSource.createQueryBuilder(Post, 'p').where('id = :id', id).getOne();
}
}
In new versions of TypeORM the name property in Connection / DataSource is deprecated, so to work conveniently with multiple DataSource the function addTransactionalDataSource allows you to specify custom the name:
addTransactionalDataSource({
name: 'second-data-source',
dataSource: new DataSource(...)
});
If you don't specify a name, it defaults to default.
Now, you can use this name in API by passing the connectionName property as options to explicitly define which Data Source you want to use:
@Transactional({ connectionName: 'second-data-source' })
async fn() { ... }
OR
runInTransaction(() => {
// ...
}, { connectionName: 'second-data-source' })
The following propagation options can be specified:
MANDATORY - Support a current transaction, throw an exception if none exists.NESTED - Execute within a nested transaction if a current transaction exists, behave like REQUIRED else.NEVER - Execute non-transactionally, throw an exception if a transaction exists.NOT_SUPPORTED - Execute non-transactionally, suspend the current transaction if one exists.REQUIRED (default behaviour) - Support a current transaction, create a new one if none exists.REQUIRES_NEW - Create a new transaction, and suspend the current transaction if one exists.SUPPORTS - Support a current transaction, execute non-transactionally if none exists.The following isolation level options can be specified:
READ_UNCOMMITTED - A constant indicating that dirty reads, non-repeatable reads and phantom reads can occur.READ_COMMITTED - A constant indicating that dirty reads are prevented; non-repeatable reads and phantom reads can occur.REPEATABLE_READ - A constant indicating that dirty reads and non-repeatable reads are prevented; phantom reads can occur.SERIALIZABLE = A constant indicating that dirty reads, non-repeatable reads and phantom reads are prevented.NOTE: If a transaction already exist and a method is decorated with @Transactional and propagation does not equal to REQUIRES_NEW, then the declared isolationLevel value will not be taken into account.
Because you hand over control of the transaction creation to this library, there is no way for you to know whether or not the current transaction was successfully persisted to the database.
To circumvent that, we expose three helper methods that allow you to hook into the transaction lifecycle and take appropriate action after a commit/rollback.
runOnTransactionCommit(cb) takes a callback to be executed after the current transaction was successfully committedrunOnTransactionRollback(cb) takes a callback to be executed after the current transaction rolls back. The callback gets the error that initiated the rollback as a parameter.runOnTransactionComplete(cb) takes a callback to be executed at the completion of the current transactional context. If there was an error, it gets passed as an argument.export class PostService {
constructor(readonly repository: PostRepository, readonly events: EventService) {}
@Transactional()
async createPost(id, message): Promise<Post> {
const post = this.repository.create({ id, message });
const result = await this.repository.save(post);
runOnTransactionCommit(() => this.events.emit('post created'));
return result;
}
}
@Transactional can be mocked to prevent running any of the transactional code in unit tests.
This can be accomplished in Jest with:
jest.mock('typeorm-transactional', () => ({
Transactional: () => () => ({}),
}));
Repositories, services, etc. can be mocked as usual.
{
storageDriver?: StorageDriver,
maxHookHandlers?: number
}
storageDriver - Determines which underlying mechanism (like Async Local Storage or cls-hooked) the library should use for handling and propagating transactions. By default, it's StorageDriver.CLS_HOOKED.maxHookHandlers - Controls how many hooks (commit, rollback, complete) can be used simultaneously. If you exceed the number of hooks of same type, you get a warning. This is a useful to find possible memory leaks. You can set this options to 0 or Infinity to indicate an unlimited number of listeners. By default, it's 10.{
connectionName?: string;
isolationLevel?: IsolationLevel;
propagation?: Propagation;
}
connectionName- DataSource name to use for this transactional context (the data sources)isolationLevel- isolation level for transactional context (isolation levels )propagation- propagation behaviors for nest transactional contexts (propagation behaviors)Option that determines which underlying mechanism the library should use for handling and propagating transactions.
The possible variants:
AUTO - Automatically selects the appropriate storage mechanism based on the Node.js version, using AsyncLocalStorage for Node.js versions 16 and above, and defaulting to cls-hooked for earlier versions.CLS_HOOKED - Utilizes the cls-hooked package to provide context storage, supporting both legacy Node.js versions with AsyncWrap for versions below 8.2.1, and using async_hooks for later versions.ASYNC_LOCAL_STORAGE - Uses the built-in AsyncLocalStorage feature, available from Node.js version 16 onwards,⚠️ WARNING: Currently, we use
CLS_HOOKEDby default for backward compatibility. However, in the next major release, this default will be switched toAUTO.
import { StorageDriver } from 'typeorm-transactional'
initializeTransactionalContext({ storageDriver: StorageDriver.AUTO });
Initialize transactional context.
initializeTransactionalContext(options?: TypeormTransactionalOptions);
Optionally, you can set some options.
Add TypeORM DataSource to transactional context.
addTransactionalDataSource(new DataSource(...));
addTransactionalDataSource({ name: 'default', dataSource: new DataSource(...), patch: true });
Run code in transactional context.
...
runInTransaction(() => {
...
const user = this.usersRepo.update({ id: 1000 }, { state: action });
...
}, { propagation: Propagation.REQUIRES_NEW });
...
Wrap function in transactional context
...
const updateUser = wrapInTransaction(() => {
...
const user = this.usersRepo.update({ id: 1000 }, { state: action });
...
}, { propagation: Propagation.NEVER });
...
await updateUser();
...
Takes a callback to be executed after the current transaction was successfully committed
@Transactional()
async createPost(id, message): Promise<Post> {
const post = this.repository.create({ id, message });
const result = await this.repository.save(post);
runOnTransactionCommit(() => this.events.emit('post created'));
return result;
}
Takes a callback to be executed after the current transaction rolls back. The callback gets the error that initiated the rollback as a parameter.
@Transactional()
async createPost(id, message): Promise<Post> {
const post = this.repository.create({ id, message });
const result = await this.repository.save(post);
runOnTransactionRollback((e) => this.events.emit(e));
return result;
}
Takes a callback to be executed at the completion of the current transactional context. If there was an error, it gets passed as an argument.
@Transactional()
async createPost(id, message): Promise<Post> {
const post = this.repository.create({ id, message });
const result = await this.repository.save(post);
runOnTransactionComplete((e) => this.events.emit(e ? e : 'post created'));
return result;
}
FAQs
A Transactional Method Decorator for typeorm that uses cls-hooked to handle and propagate transactions between different repositories and service methods. Inpired by Spring Trasnactional Annotation and Sequelize CLS
The npm package typeorm-transactional receives a total of 45,719 weekly downloads. As such, typeorm-transactional popularity was classified as popular.
We found that typeorm-transactional demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.