!Banner

Transactional Decorators

A comprehensive TypeScript library providing transaction management capabilities through decorators, locks, and utilities. This library enables atomic operations, concurrency control, and error handling in your TypeScript applications, ensuring data integrity and thread safety.

> Release docs refreshed on 2025-11-26. See workdocs/reports/RELEASE_NOTES.md for ticket summaries.

$3

* @transactional: A method decorator that wraps a method in a transaction, ensuring that it is executed atomically.
* Transaction Class: The core class for managing transaction lifecycle, including creation, execution, and cleanup.
* Locks: The library provides different lock implementations to control concurrency.
* SynchronousLock: A simple lock that allows only one transaction to execute at a time.
* MultiLock: A more advanced lock that allows multiple transactions to execute concurrently, with a configurable limit.

!Licence
!GitHub language count
!GitHub top language


!Open Issues
!Closed Issues
!Pull Requests
!Maintained

!Forks
!Stars
!Watchers

!Node Version
!NPM Version

Documentation available here

$3

The Transactional Decorators library is a standalone module that provides a robust implementation for handling concurrency and transaction management in TypeScript applications. It offers a comprehensive set of tools for ensuring data integrity and thread safety in your code.

#### Core Components

- Transaction Class: The central class that manages the lifecycle of transactions, including creation, execution, and cleanup. It provides mechanisms for binding transactions to objects and methods, ensuring proper transaction context propagation.

- Lock System: A flexible locking mechanism for controlling access to shared resources:
- Lock: A base class providing fundamental locking capabilities with support for queuing and executing functions when the lock is available.
- TransactionLock: An interface defining the contract for transaction lock implementations that manage transaction execution order and concurrency.
- SyncronousLock: A default implementation of TransactionLock that processes transactions one at a time in the order they are submitted.

- Decorators:
- @transactional(): A method decorator that enables transactional behavior by wrapping the original method in a transaction context that handles transaction creation, binding, and error handling.
- transactionalSuperCall(): A utility function for handling super calls in transactional methods, ensuring transaction continuity through the inheritance chain.

#### Key Features

- Simple yet powerful locking: The library provides a flexible locking system that can be customized to suit your application's needs.
- Method decoration with @transactional(): Easily add transactional behavior to your methods with a simple decorator.
- Instance proxying: The Transaction class can bind to objects, creating proxies that maintain transaction context across method calls.
- Transaction chaining: Transactions can be linked together, allowing you to group multiple operations into a single atomic transaction.
- Customizable Transaction Lock: You can implement your own TransactionLock to customize how transactions are processed.
- Error handling: The library includes built-in error handling to ensure transactions are properly released even when errors occur.
- Seamless integration with db-decorators: The library works well with the db-decorators package for database operations.

This library is ideal for applications that need to ensure data consistency and handle concurrent operations safely, such as database applications, financial systems, or any application where atomic operations are important.

How to Use

This guide provides examples of how to use the main features of the @decaf-ts/transactional-decorators library.

Transactional Decorator

The @transactional decorator ensures that a method is executed within a transaction.

``typescript
import { transactional } from '@decaf-ts/transactional-decorators';

class MyService {
@transactional()
async myTransactionalMethod() {
// This method will be executed within a transaction.
}
}
`

Locks

The library provides different lock implementations to control concurrency.

$3

The SynchronousLock allows only one transaction to execute at a time. This is the default lock.

`typescript
import { Transaction, SynchronousLock } from '@decaf-ts/transactional-decorators';

Transaction.setLock(new SynchronousLock());
`

$3

The MultiLock allows multiple transactions to execute concurrently, with a configurable limit.

`typescript
import { Transaction, MultiLock } from '@decaf-ts/transactional-decorators';

// Allow up to 5 transactions to execute concurrently
Transaction.setLock(new MultiLock(5));
`

Manual Transaction Management

You can also manage transactions manually using the Transaction class.

`typescript
import { Transaction } from '@decaf-ts/transactional-decorators';

const myTransaction = new Transaction(
'MyManualTransaction',
'myAction',
async () => {
// Transaction logic here
}
);

Transaction.submit(myTransaction);
``

$3


$3


#### Languages

!TypeScript
!JavaScript
!NodeJS
!ShellScript

Getting help

If you have bug reports, questions or suggestions please create a new issue.

Contributing

I am grateful for any contributions made to this project. Please read this to get started.

Supporting

The first and easiest way you can support it is by Contributing. Even just finding a typo in the documentation is important.

Financial support is always welcome and helps keep both me and the project alive and healthy.

So if you can, if this project in any way. either by learning something or simply by helping you save precious time, please consider donating.

License

This project is released under the MIT License.

By developers, for developers...