# sequelize-transactional-decorator

> A Transactional method decorator for Sequelize ORM

Latest version **1.0.1** (published 2024-05-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install sequelize-transactional-decorator
pnpm add sequelize-transactional-decorator
yarn add sequelize-transactional-decorator
bun add sequelize-transactional-decorator
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.1 |
| Published | 2024-05-17 |
| First published | 2023-08-07 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 15.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 8 |
| Author | happnz |
| Maintainers | happnz |
| Keywords | sequelize, transactional, transaction, method decorator, annotation |

## Links

- npm: https://www.npmjs.com/package/sequelize-transactional-decorator
- Repository: https://github.com/happnz/sequelize-transactional-decorator
- Homepage: https://github.com/happnz/sequelize-transactional-decorator#readme
- Issues: https://github.com/happnz/sequelize-transactional-decorator/issues
- npm.io page: https://npm.io/package/sequelize-transactional-decorator

## Dependencies (1)

- [cls-hooked](https://npm.io/package/cls-hooked.md) ^4.2.2

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 1.0.1 (latest) — 2024-05-17
- 1.0.0 — 2023-08-07

## README

# Sequelize Transactional decorator

[![Build status](https://github.com/happnz/sequelize-transactional-decorator/actions/workflows/node.js.yml/badge.svg?branch=main)](https://github.com/happnz/sequelize-transactional-decorator/actions/workflows/node.js.yml?query=branch%3Amain)
[![NPM](https://img.shields.io/npm/v/sequelize-transactional-decorator.svg)](https://www.npmjs.com/package/sequelize-transactional-decorator)
![Downloads](https://img.shields.io/npm/dm/sequelize-transactional-decorator)

A `@Transactional` method decorator for **Sequelize** inspired by Java Spring's `@Transactional` annotation. 

Simple integration with **NestJS**.

## Requirements

- [sequelize](https://github.com/sequelize/sequelize) v4-6

## Installation

```shell
# npm
npm install --save sequelize-transactional-decorator
# yarn
yarn add sequelize-transactional-decorator
```


## Usage

### Step 1

**Before establishing any connections** using Sequelize,
you need to enable Sequelize to use node CLS:
```typescript
import { initSequelizeCLS } from 'sequelize-transactional-decorator';


initSequelizeCLS();
```

### Step 2

### With NestJS:

Import `SequelizeTransactionalModule.register()` into your root application module.

Example:
```typescript
@Module({
  imports: [
    SequelizeModule.forRoot({
      ...
    }),
    SequelizeTransactionalModule.register(),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

If you specified custom connection name in `SequelizeModule`, pass `connectionName` into options:
```typescript
@Module({
  imports: [
    SequelizeModule.forRoot({
      ...
      name: 'my-connection-name',
    }),
    SequelizeTransactionalModule.register({ connectionName: 'my-connection-name' }),
  ],
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}
```

### Without NestJS:

Just call `initSequelizeTransactional` after establishing a connection:

```typescript
const sequelize = new Sequelize({ ... })

initSequelizeTransactional(sequelize) // pass your Sequelize conection here
```

### Step 3

Use `@Transactional` annotation on your class methods.

Example:

```typescript
@Injectable()
export class AppService {
  constructor(
    @InjectModel(Something)
    private readonly something: typeof Something,
    private readonly anotherService: AnotherService,
  ) {}

  @Transactional()
  async appMethod(): Promise<void> {
    await this.something.create({ message: 'hello' });
    await this.something.create({ message: 'world' });
    await this.anotherService.method(); // other service's method will use the same transaction
  }
}

```

`@Transactional` decorator accepts `options` object:
```typescript
{
  isolationLevel?: string; // Isolation Level of transaction. Default value depends on your Sequelize config or the database you use
  propagation?: string; // Default value is REQUIRED. Allowed options are described below
}
```

## Propagation options

- `REQUIRED` (default) - If exists, use current transaction, otherwise create a new one.
- `SUPPORTS` - If exists, use current transaction, otherwise execute without transaction.
- `MANDATORY` - If exists, use current transaction, otherwise throw an exception.  
- `NEVER` - Execute without transaction. If an active transaction exists, throw an exception. 
- `NOT_SUPPORTED` - Execute without transaction, suspend an active transaction if it exists. 
- `REQUIRES_NEW` - Always execute in a separate transaction, suspend an active transaction if it exists.


## Isolation Level Options

- `READ UNCOMMITTED`
- `READ COMMITTED`
- `REPEATABLE READ`
- `SERIALIZABLE`

For more info refer to your database documentation.


## Testing

### Mocking in unit tests

If you want to remove transactional logic from your unit tests, you can mock `@Transactional` decorator.

Example in Jest:

```typescript
jest.mock('sequelize-transactional-decorator', () => ({
  Transactional: () => () => ({}),
}));
```

### Testing with `@Transactional`
You can test your code with `@Transactional` as usual, if you configure it in tests following the same steps described above.

**NOTE**: you will have to run your tests sequentially (which may be slower) rather than in parallel.  
This is because only one simultaneous Sequelize connection is supported in order for decorator to work.  
For example, in jest you will need to use `--runInBand` option.

---
_Source: https://npm.io/package/sequelize-transactional-decorator · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._