DEV Community: José Carlos García

Generalizing Transactions in NestJS: A Domain Port over TypeORM and MongoDB

José Carlos García — Thu, 10 Sep 2026 19:16:21 +0000

Transaction control usually starts out tied to whatever implements it. An executor — a concrete class that opens a transaction over the project's ORM — gets injected into the controller and wraps the body of the handler, so that everything a request writes either commits or is discarded as a block:

@Post()
create(@Body() body: CreateUserRequest) {
  return this.transactionExecutor.execute(async () =>
    new RegisterUser(this.ids, this.users, this.settings).execute(body),
  );
}

The approach is sound, and for most operations nothing more is needed. An HTTP request corresponds exactly to one unit of work, the use case has no idea it is inside a transaction, and repositories enlist themselves in whichever one is active through AsyncLocalStorage. That starting point is described in detail, along with the enlistment mechanism and its edge cases, in Transactions in NestJS and TypeORM without passing the EntityManager around.

This article is about a kind of operation that approach cannot handle — one where the use case has to wait on an external service before it writes — and about the generalization it takes when one shows up: extracting that executor's contract into a ten-line interface that lives in the domain.

What this buys is not only that the use case can decide its own scope without depending on the ORM. The interface is then put to the test with two implementations, one over PostgreSQL and one over MongoDB, running the same use cases and the same tests against both. That check is the only way to know whether the contract generalizes anything or is the same executor under a new name, and it is also what marks how far it reaches: there are differences between engines that no abstraction hides, and it is worth knowing which before trusting it.

The problem: waiting on a third party inside the transaction

An open transaction is not free. It holds a pooled connection and the locks on the rows already written, and it holds them for as long as the block it wraps takes to finish.

That does not matter when the block only talks to the database. It starts to matter the moment the use case calls an external service: a payment gateway, a file store, an AI model. The transaction stays alive while something that has nothing to do with the database is awaited, and that wait is measured in seconds or minutes.

@Post('reports')
generateReport(@Body() body: GenerateReportRequest) {
  return this.transactionExecutor.execute(async () =>
    new GenerateReport(this.ids, this.reports, this.content).execute(body),
  );
}

// ...and inside that use case:
async execute(props: GenerateReportProps): Promise<string> {
  const generated = await this.content.generate(props.prompt); // minutes

  const report = new Report({ id: this.ids.create(), userId: props.userId, content: generated });
  await this.reports.save(report);

  return report.id;
}

Neither file looks wrong on its own. The controller does what it does in every other endpoint, and the use case calls a service and saves the result. The problem exists only in the relationship between the two, and it is invisible from either.

The result is a system that carries far less load than it should, with connections busy waiting on third parties and requests blocked on rows nobody will release until some external service answers.

The fix is easy to state: only database operations belong inside the transaction. Applying it is what breaks the original approach, because the controller cannot carry it out. The controller knows the request is one unit of work, but not which part of the use case is the write and which is the wait. That knowledge lives one level down.

Moving the scope couples the application layer

If the use case decides the scope, it needs something to open the unit with. The immediate move is to inject the executor that already exists:

export class GenerateReport {
  constructor(private readonly executor: TypeOrmTransactionExecutor) {}
}

With that signature, the application layer now depends on the class that implements transactions over TypeORM, and through it on the whole ORM.

It is the same defect that shows up when a domain repository declares manager?: EntityManager on its methods, only one layer higher. A layer that should be reasonable, testable and instantiable without knowing how data is persisted no longer can be. And the use case is precisely where the logic worth keeping clean lives.

The move solves one problem and creates another, and the second is solved by generalizing the executor rather than injecting it as it is.

The solution: the UnitOfWork port

The use case does not need that particular class, but any collaborator able to run a block as a single unit. That description is the description of an interface, and since it is a need of the application layer, declaring it falls to the domain:

export interface UnitOfWorkProps<T> {
  work: () => Promise<T>;

  // Runs after the rollback, on a clean connection. Writing this inside the
  // failed unit would revert it along with the failure it records.
  onError?: (error: unknown) => Promise<void> | void;
}

export interface UnitOfWork {
  // Joins the unit already active in this async context, if there is one.
  run<T>(props: UnitOfWorkProps<T>): Promise<T>;
}

That is the whole contract, and work taking no arguments is what keeps a persistence type from reaching the application layer.

onError is not decoration. It is the seam for whatever must outlive the rollback, and it exists because of a trap worth naming: anything written in the catch on the failed unit's own connection is reverted along with the failure it was meant to record. The adapter invokes onError after rolling back and outside the unit's context, so repositories used there write on the normal connection.

The concrete executor becomes an implementation of that contract. It changes name, because it is no longer a standalone class but the adapter of a port, and execute becomes run to match the declared signature:

export class TypeOrmUnitOfWork implements UnitOfWork {
  private static readonly storage = new AsyncLocalStorage<EntityManager>();

  constructor(private readonly dataSource: DataSource) {}

  getManagerIfActive(): EntityManager | null {
    return TypeOrmUnitOfWork.storage.getStore() ?? null;
  }

  async run<T>({ work, onError }: UnitOfWorkProps<T>): Promise<T> {
    if (TypeOrmUnitOfWork.storage.getStore()) return work();

    const queryRunner = this.dataSource.createQueryRunner();
    await queryRunner.connect();
    await queryRunner.startTransaction();

    try {
      return await TypeOrmUnitOfWork.storage.run(queryRunner.manager, async () => {
        const result = await work();
        await queryRunner.commitTransaction();
        return result;
      });
    } catch (error) {
      await queryRunner.rollbackTransaction();

      // Outside the run(): repositories used here write on the pooled
      // connection, so what they write survives the rollback. Best effort: a
      // failure while recording the failure must not replace it.
      if (onError) {
        try {
          await onError(error);
        } catch {}
      }

      throw error;
    } finally {
      await queryRunner.release();
    }
  }
}

On the repository side, enlisting means reading the unit the executor has just published. A base class settles the decision for all of them, so no concrete repository ever asks the question again:

protected get repository(): Repository<Model> {
  const manager: EntityManager | null =
    this.transactionExecutor.getManagerIfActive();

  return manager
    ? manager.getRepository(this.target)
    : this.dataSource.getRepository(this.target);
}

That is the mechanism by which a repository ends up inside the transaction without receiving anything. It is developed, with its edge cases, in Transactions in NestJS and TypeORM without passing the EntityManager around.

With that, the use case depends on the port and knows nothing about the implementation:

export class GenerateReport {
  constructor(
    private readonly uow: UnitOfWork,
    private readonly ids: IdGenerator,
    private readonly reports: ReportRepository,
    private readonly failures: FailureLogRepository,
    private readonly content: SlowContentService,
  ) {}

  async execute(props: { userId: string; prompt: string }): Promise<string> {
    // Outside the unit on purpose: a transaction held open across this wait
    // would pin a connection and its locks until it returned.
    const generated = await this.content.generate(props.prompt);

    const report = new Report({ id: this.ids.create(), userId: props.userId, content: generated });

    await this.uow.run({
      work: async () => {
        await this.reports.save(report);
      },
      onError: async (error) => {
        await this.failures.save(
          new FailureLog({
            id: this.ids.create(),
            operation: 'generate-report',
            message: error instanceof Error ? error.message : String(error),
          }),
        );
      },
    });

    return report.id;
  }
}

In the controller, that endpoint stops opening anything:

@Post('reports')
async generateReport(@Body() body: GenerateReportRequest) {
  const useCase = new GenerateReport(
    this.uow, this.ids, this.reports, this.failures, this.content,
  );

  return { id: await useCase.execute(body) };
}

Compared with the handler at the top of this article, the call that wrapped the body is gone. The boundary was not removed: it moved inward, to the only place that knows where to put it.

Use cases that do not need to decide their scope do not change at all. They still know nothing about the port, and the boundary is opened by whoever calls them, exactly as before:

export class RegisterUser {
  constructor(
    private readonly ids: IdGenerator,
    private readonly users: UserRepository,
    private readonly settings: UserSettingsRepository,
  ) {}

  async execute(props: { email: string; name: string }): Promise<string> {
    const existing = await this.users.findByEmail(props.email);
    if (existing) throw new UserAlreadyExistsError(props.email);

    const user = new User({ id: this.ids.create(), email: props.email, name: props.name });

    await this.users.save(user);
    await this.settings.save(
      new UserSettings({ id: this.ids.create(), userId: user.id, theme: 'light' }),
    );

    return user.id;
  }
}

Nested units: joining instead of opening another

Moving the scope into the use case has a consequence worth settling. From the moment a use case can open its own unit without knowing whether someone further up the stack already opened one, nesting stops being a rarity and becomes the expected case.

That is why the first line of run() returns work() when a unit is already active. Without that guard a second transaction would open, on a different connection, committing on its own and capable of blocking on a row its own caller is holding.

Checking that they do join admits a direct proof. An independent transaction cannot read another's uncommitted writes at any isolation level, so if the inner unit sees what the outer one wrote, there can only be one transaction:

await uow.run({
  work: async () => {
    await users.save(new User({ id: ids.create(), email, name: 'Outer' }));

    await uow.run({
      work: async () => {
        // Uncommitted: visible only from inside the same transaction.
        sawOuterWriteFromInside = (await users.findByEmail(email)) !== null;
      },
    });
  },
});

expect(sawOuterWriteFromInside).toBe(true);

Testing the generalization: the MongoDB adapter

So far there is an interface and a single implementation, which is not a generalization but a rename. The only way to know whether the port generalizes anything is to write a second implementation over a technology that does not resemble the first.

MongoDB meets that requirement, and it also presents the problem this article started from in a more severe form. A transaction there does not only hold resources: it has a lifetime, and the server aborts it once that runs out. The clock starts at its first operation, and a read counts. With the server's limit lowered to one second, this sequence opens a transaction, performs a read, waits and then tries to write:

const session = await connection.startSession();
session.startTransaction();

// First operation of the transaction: the clock starts here.
await users.countDocuments({}).session(session);

await sleep(5_000); // the server's limit is 1 second

// Fails: the transaction has already been aborted.
await users.create([{ _id: id, email: 'slow@example.com', name: 'Slow' }], { session });

The write fails. The same sequence without the wait commits without trouble, so the only thing that differs between them is how long is spent inside the transaction. Nothing had been written when the clock started running: the read was enough.

What degrades performance in PostgreSQL prevents the operation from completing here. The fix is not to raise the limit, which exists to protect the cluster, but to leave the wait outside the unit — which is precisely what the port lets the use case decide.

The adapter is then written against the same interface, and it is worth comparing it line by line with the TypeORM one:

export class MongoUnitOfWork implements UnitOfWork {
  private static readonly storage = new AsyncLocalStorage<ClientSession>();

  constructor(private readonly connection: Connection) {}

  async run<T>({ work, onError }: UnitOfWorkProps<T>): Promise<T> {
    if (MongoUnitOfWork.storage.getStore()) return work();

    const session = await this.connection.startSession();
    session.startTransaction();

    try {
      return await MongoUnitOfWork.storage.run(session, async () => {
        const result = await work();
        await session.commitTransaction();
        return result;
      });
    } catch (error) {
      // A transaction the server already aborted, by outliving its lifetime,
      // is no longer in progress, and aborting it again throws.
      if (session.inTransaction()) await session.abortTransaction();

      if (onError) {
        try {
          await onError(error);
        } catch {}
      }

      throw error;
    } finally {
      await session.endSession();
    }
  }
}

The session takes the place of the queryRunner and the rest is identical: the same join guard, the same storage.run publishing the unit, the same commit inside the callback and the same onError outside it. That both implementations take this shape was not the goal but the signal that the contract describes something both engines genuinely do.

The real difference shows up on the repository side. Mongoose offers no manager shortcut: the session has to ride on every operation, reads included, and omitting it on a single call leaves that call outside the transaction with no error. An equivalent base class absorbs that difference, so concrete repositories for either engine end up written the same way. Absorbing those asymmetries so the port can stay the same is exactly the adapter's job.

The same suite over PostgreSQL and MongoDB

With two implementations available, the check can be run against both from the same material. The tests below are tests of the use cases, not of the adapters: they describe what must happen on commit and on rollback, without mentioning at any point which engine is underneath.

describe.each(ALL_CONTEXTS)('UnitOfWork contract: %s', (_name, makeContext) => {
  it('commits both writes as a single unit', async () => {
    await ctx.uow.run({
      work: () => registerUser().execute({ email: 'ana@example.com', name: 'Ana' }),
    });

    expect(await ctx.users.countAll()).toBe(1);
    expect(await ctx.settings.countAll()).toBe(1);
  });

  it('runs onError after the rollback, so the record survives it', async () => {
    await expect(
      ctx.uow.run({
        work: async () => {
          await registerUser().execute({ email: 'ana@example.com', name: 'Ana' });
          throw new Error('boom');
        },
        onError: async () => {
          await ctx.failures.save(new FailureLog({ /* ... */ }));
        },
      }),
    ).rejects.toThrow('boom');

    expect(await ctx.users.countAll()).toBe(0); // the work was reverted
    expect(await ctx.failures.countAll()).toBe(1); // the record of it was not
  });
});

The same tests run against PostgreSQL and against MongoDB, and pass on both. Had the interface come out shaped like the TypeORM executor, the MongoDB adapter could not have implemented it without distorting it, and this would not be green.

The repository also includes a third implementation, in memory, which serves to run these same tests without infrastructure and for one additional check: both engines ship native transactions, so an adapter that satisfies the contract without having any rules out that the port is a transaction in disguise.

With any test of this kind it is worth breaking on purpose what it claims to check and confirming it goes red. Removing the join guard from the adapters makes the nesting tests fail on all of them. A green test that cannot fail proves nothing.

It is worth being precise about the scope of that check. The port unifies the API, not the guarantees: the two engines differ in isolation levels, in lock behaviour and in failure modes, and those differences survive the abstraction untouched. The transaction lifetime in MongoDB is one of them, and it is precisely the one that forced the scope down into the use case.

Two things are guaranteed. That the decision about scope is taken in the layer that knows it, without that layer depending on the engine. And that a change of engine stays confined to infrastructure — the adapters and the repositories for the new engine — without touching a single use case or a single use-case test.

When to generalize and when not to

The generalization pays for itself once there is at least one use case that needs to decide its own scope, and those cases have a recognizable shape: slow work that is not database work, interleaved with writes that are.

Charging and recording the charge. The use case calls the payment gateway and persists the result. The call takes seconds and cannot sit inside the transaction.
Uploading a file and saving its metadata. The upload to object storage goes outside; the row referencing it, inside.
Generating content with an external service and persisting it, which is the GenerateReport case in this article.

In all three the controller has no way to get it right: wrapping everything keeps the transaction open across the wait, and wrapping nothing leaves the writes without atomicity. The boundary sits in the middle of the use case, and only it knows where.

If no operation has that shape and all of them fit inside a transaction opened at the controller, the port adds nothing: injecting the concrete executor wherever it is needed is enough, and the interface would only add indirection nobody uses.

And even with the port in place, outside those cases the boundary should still be opened at the controller. That the use case can take the scope does not mean it should, and in the controllers the transactional shape of the system can be read at a glance.

Checklist

The port lives in the domain and imports nothing from the engine.
work takes no arguments: if it takes a manager or a session, it is not a port.
run() joins the active unit instead of opening a second one.
Whatever must outlive the rollback is written from onError, outside the unit.
Only database operations go inside the unit.
An interface with a single implementation does not generalize anything yet.
Use-case tests run against every adapter, not against one.
Every test is validated by deliberately breaking what it claims to check.

The complete code is in a runnable repository — the adapters, the use cases, the NestJS wiring and the shared suite, with Docker Compose to bring up PostgreSQL and MongoDB: https://github.com/JoseCarlosGarcia/unit-of-work-demo

Transactions in NestJS and TypeORM without passing the EntityManager around

José Carlos García — Tue, 18 Aug 2026 18:37:48 +0000

Transactions promise a simple guarantee: either everything commits, or nothing does. And yet, in a NestJS application with a repository layer, it is perfectly possible to run a rollback with no errors and then find a row still sitting in the database that should have disappeared with it.

This is not a TypeORM or PostgreSQL bug. One of the repositories involved was never inside the transaction, because the EntityManager stopped being passed down three layers up. There was no exception, no warning, and the tests passed because that repository was mocked.

This article describes how to make that class of failure impossible: the transaction opens at a single point — the controller handling the request — and repositories enlist themselves in the transaction in progress, without receiving anything as a parameter. It comes to about sixty lines built on AsyncLocalStorage.

The second part is the one rarely told: three consequences of the transaction boundary, each with its fix. A network call inside the transaction holds a pooled connection and its locks for the entire wait. A failure record written in the catch is rolled back along with the very failure it was meant to document. And nesting two execute calls does not open a nested transaction but two independent ones, with the self-deadlock that allows.

The problem: passing the EntityManager by hand

TypeORM offers a transaction like this:

await dataSource.transaction(async (manager) => {
  await manager.getRepository(UserModel).save(user);
  await manager.getRepository(UserSettingModel).save(settings);
});

For a small project this is the correct answer and nothing more is needed.

The problem shows up once a repository layer exists. The manager is the transaction: if a repository does not use that manager, its queries run on a different connection and end up outside the transaction. Silently, with no error and no warning. The rollback simply does not revert them.

So the manager has to reach the repository, and it only gets there by being passed by hand. An application-layer use case ends up like this:

async execute(props: CreateUserProps, manager?: EntityManager): Promise<void> {
  const user = await this.userRepository.findByEmail(props.email, manager);
  if (user) throw new UserAlreadyExistsError();

  await this.userRepository.create(newUser, manager);
  await this.settingRepository.create(defaultSettings, manager);
}

The effect on UserRepository, the interface that declares the port and lives in the domain layer, is the following:

export interface UserRepository {
  create(user: User, manager?: EntityManager): Promise<void>;
  findById(id: string, manager?: EntityManager): Promise<User | null>;
  findByEmail(email: string, manager?: EntityManager): Promise<User | null>;
  update(user: User, manager?: EntityManager): Promise<void>;
  delete(id: string, manager?: EntityManager): Promise<void>;
}

This interface lives in the domain layer. The reason for putting it there is that the domain declares what it needs without knowing how anything is persisted. And now it imports EntityManager from typeorm. With that, the port stops being one: it can no longer be implemented without dragging the ORM along, starting with the in-memory double you would use to test the application layer.

The underlying problem is not aesthetic. That ? carries the correctness of the system and is invisible: failing to pass manager through one call, inside one branch, of one service is enough for that write to fall outside the transaction. It passes code review. It passes the tests that mock the repository. And it surfaces in production with symptoms like this one, by way of example: a half-failed operation that leaves a user row without its matching settings row.

The second alternative — doing without transactions — resolves nothing. It only postpones the problem to the moment two related writes diverge.

The goal, then:

The domain port with no TypeORM types.
The transaction boundary declared once, at the entry point.
Repositories that enlist themselves in the active transaction, and behave identically when there is none.
"Forgetting to pass something" no longer a possible mistake, because nothing is passed.

AsyncLocalStorage

Node has shipped AsyncLocalStorage since v12. It is storage local to the asynchronous call chain: a value is set at the root, and any function below it — at any depth, across every await — can read it without receiving it as an argument.

Applied to the problem above, the shape is this:

const storage = new AsyncLocalStorage<EntityManager>();

// At the root of the operation, once:
await storage.run(queryRunner.manager, async () => {
  await createUserService.execute(props); // does not receive the manager
});

// Several layers down, inside any repository:
const manager = storage.getStore(); // the same queryRunner.manager from above

The store is scoped to the asynchronous context, not to a global variable. Two concurrent HTTP requests each hold their own, with no interference, and outside a run() the read returns undefined. That property is what makes the pattern safe.

An EntityManager fits that description exactly: it is needed throughout the call chain and belongs to none of the intermediate layers.

The solution: TransactionExecutor

TransactionExecutor lives in the project's shared infrastructure. It is forty-five lines, with no dependencies beyond TypeORM and Node.

import { Injectable } from '@nestjs/common';
import { AsyncLocalStorage } from 'async_hooks';
import { DataSource, EntityManager } from 'typeorm';

@Injectable()
export class TransactionExecutor {
  private static readonly entityManagerStorage =
    new AsyncLocalStorage<EntityManager>();

  constructor(private readonly dataSource: DataSource) {}

  /**
   * Runs `work` inside a transaction. Commits if it completes,
   * rolls back if it throws, and always releases the queryRunner.
   */
  async execute<T>(work: (manager: EntityManager) => Promise<T>): Promise<T> {
    const queryRunner = this.dataSource.createQueryRunner();
    await queryRunner.connect();
    await queryRunner.startTransaction();

    try {
      return await TransactionExecutor.entityManagerStorage.run(
        queryRunner.manager,
        async () => {
          const result = await work(queryRunner.manager);
          await queryRunner.commitTransaction();
          return result;
        },
      );
    } catch (err) {
      await queryRunner.rollbackTransaction();
      throw err;
    } finally {
      await queryRunner.release();
    }
  }

  /**
   * EntityManager of the active transaction, or null if there is none.
   * Repositories use it to enlist in the transaction in progress.
   */
  getManagerIfActive(): EntityManager | null {
    return TransactionExecutor.entityManagerStorage.getStore() || null;
  }
}

Four decisions in the code above are deliberate, and each one produces a bug if resolved differently:

The storage is static. A single store must exist for the whole process: with two distinct AsyncLocalStorage objects, a repository reading from the second would not see the transaction opened with the first. Sharing it does not compromise isolation, because run() takes care of that: it scopes the value to its callback's asynchronous chain and restores the previous one on return, so two concurrent requests never see each other's manager.

The commit happens inside the run() callback, not after it. With the commit outside, any code sitting between the end of work() and the commit observes a store that has already been torn down.

The release happens in finally. A QueryRunner holds a real connection from the pool. Omitting this on the error path leaks one connection per failed request, until the pool is exhausted and the application stops responding. It is the most common way to get this pattern wrong.

getManagerIfActive() returns null instead of throwing. That is what allows the same repository to work outside a transaction too.

The abstraction: BaseTypeOrmRepository

Every repository needs to resolve the same decision: if a transaction is active, obtain the repository from its manager; otherwise use the one from the DataSource. Repeating that check in every file is exactly the kind of duplication that ends up failing in a single place, silently. That decision belongs in a base class, sitting next to the executor in the shared infrastructure:

import {
  DataSource,
  EntityManager,
  EntityTarget,
  ObjectLiteral,
  Repository,
} from 'typeorm';
import { TransactionExecutor } from './typeorm-transaction.executor';

export abstract class BaseTypeOrmRepository<Model extends ObjectLiteral> {
  protected constructor(
    private readonly dataSource: DataSource,
    private readonly transactionExecutor: TransactionExecutor,
    private readonly target: EntityTarget<Model>,
  ) {}

  protected get repository(): Repository<Model> {
    const manager: EntityManager | null =
      this.transactionExecutor.getManagerIfActive();

    return manager
      ? manager.getRepository(this.target)
      : this.dataSource.getRepository(this.target);
  }
}

That is the entire abstraction, in fifteen lines, and it is worth pausing on what it does and what it deliberately does not do.

It is not a generic CRUD base class. It implements no save, no find, no other operation. It exposes one single thing — the repository already enlisted in the right transaction — and steps aside. Each concrete repository goes on writing whatever queries it needs with the usual TypeORM API, with no intermediate layer to translate and no new limitations.

It is a get, not a method. Subclasses write this.repository, which reads exactly like the injected repository it replaces. There is no new convention to learn and nothing to remember on each query, and that detail is what makes the abstraction impossible to misuse by accident.

The decision lives in one place in the project. The question "is there an active transaction?" is answered once, in fifteen lines, and no repository ever asks it again. Adding a new repository means extending the class and passing the model to super: from then on it takes part in transactions without a single extra line of code.

A complete example, the user repository in the infrastructure layer:

@Injectable()
export class TypeOrmUserRepository
  extends BaseTypeOrmRepository<UserModel>
  implements IUserRepository
{
  constructor(
    dataSource: DataSource,
    transactionExecutor: TransactionExecutor,
  ) {
    super(dataSource, transactionExecutor, UserModel);
  }

  async save(user: User): Promise<void> {
    const model = UserMapper.toModel(user);
    await this.repository.save(model);
  }

  async findByEmail(email: string): Promise<User | null> {
    const found = await this.repository.findOne({ where: { email } });
    return found ? UserMapper.toDomain(found) : null;
  }

  async findByEmailWithPassword(email: string): Promise<User | null> {
    const found = await this.repository
      .createQueryBuilder('user')
      .addSelect('user.password')
      .where('user.email = :email', { email })
      .getOne();

    return found ? UserMapper.toDomain(found) : null;
  }

  async updatePassword(user: User): Promise<void> {
    await this.repository.update(
      { id: user.getId() },
      { password: user.password },
    );
  }
}

The createQueryBuilder case deserves separate attention. Query builders are where manual manager propagation usually breaks, because createQueryBuilder is a method on a repository: a repository holding the wrong one builds the query on the wrong connection. Here the call is this.repository.createQueryBuilder(...) and it lands inside the transaction like everything else.

The matching port, back in the domain layer, stays clean:

export interface IUserRepository {
  save(user: User): Promise<void>;
  findById(id: string): Promise<User | null>;
  findByEmail(email: string): Promise<User | null>;
  findByEmailWithPassword(email: string): Promise<User | null>;
  update(user: User): Promise<void>;
  updatePassword(user: User): Promise<void>;
  delete(id: string): Promise<void>;
}

No typeorm import. Nothing to pass down, nothing to forget.

Opening a transaction

The transaction opens at the entry point of the operation, because that is where an HTTP request corresponds exactly to one unit of work: everything that happens from that point on must be committed together or discarded together. In a NestJS backend that point is the controller; in a scheduled job or a queue consumer, the corresponding handler.

Injecting the executor into the controller and wrapping the body of the method is enough:

@Patch('change-password')
async changePassword(
  @Body() request: ChangePasswordRequest,
  @CurrentUser() user: User,
): Promise<void> {
  return this.transactionExecutor.execute(async () => {
    const service = new UserChangePassword(
      this.repository,
      new BcryptPasswordHasher(),
    );
    const command = new UserChangePasswordCommand(service);
    return command.execute({ request, user });
  });
}

The callback declares no arguments. execute does hand over the EntityManager, and occasionally that is useful for a raw query, but in normal use it is ignored, which is precisely the point. UserChangePasswordCommand has no idea it is inside a transaction. Neither does UserChangePassword. Neither does the repository. From there down everything is business logic, and the writes inside that callback either land together or none of them land.

With several repositories the approach is identical, with no coordination and no unit-of-work object to assemble:

@Post()
create(@Body() body: CreateUserRequest, @CurrentUser() user: User) {
  return this.transactionExecutor.execute(async () => {
    const createUserService = new CreateUser(
      this.idGenerator,
      this.passwordHasher,
      this.userRepository,
      this.userSettingRepository,
    );
    const command = new CreateUserCommand(createUserService);
    return command.execute({ body, user });
  });
}

Both repositories were injected long before any transaction existed. They pick it up at call time, from the ambient context.

Reads are not wrapped:

@Get(':id')
async getById(@Param('id') id: string): Promise<UserResponse> {
  const service = new UserGetById(this.repository);
  const query = new UserGetByIdQuery(service);
  return query.execute({ id }); // no transaction, same repository
}

The same TypeOrmUserRepository, the same findById. getManagerIfActive() returns null, the base class falls back to dataSource.getRepository(...), and the read runs on a pooled connection without the cost of a transaction. No second read-only repository class is needed, and no read has to be wrapped in an unnecessary transaction to satisfy an API.

That symmetry is the property worth protecting: a repository method that behaves identically in both contexts can be called from anywhere with no prior checks.

What it buys

The domain port holds no infrastructure types. IUserRepository is implementable by an in-memory double in four lines, which makes application-layer tests fast and faithful.
No write can end up outside the transaction. The failure mode was "someone forgot to pass manager", and there is nothing left to pass.
One boundary, declared in plain sight. A grep for transactionExecutor.execute enumerates every unit of work in the project.
Adding a repository to an existing operation costs nothing. No signature changes rippling up through the service and the command.
It composes with everything. Query builders, raw SQL through the manager, subscribers, several repositories at once.
Fifteen lines of shared code, with no additional dependencies.

Three consequences of the transaction boundary, and how to fix them

The above is the clean version. The three sections that follow are what shows up once the pattern is carrying a real system, and all three come down to the same thing: the transaction begins or ends somewhere other than the code suggests.

An open transaction holds a connection from the pool

Placing the boundary at the controller has a second-order effect: it invites wrapping the entire handler. And the moment the handler calls an external service — a payment gateway, a file store, an email provider — that network call ends up inside the transaction.

@Post('payments')
create(@Body() body: CreatePaymentRequest) {
  return this.transactionExecutor.execute(async () => {
    const charge = await this.paymentGateway.charge(body); // 800 ms of network
    await this.paymentRepository.save(Payment.from(charge));
  });
}

While that response is awaited, the QueryRunner holds a pooled connection and the locks on the rows already written. With a pool of ten connections and an 800 ms call, the ceiling lands at around twelve requests per second no matter how much CPU is idle, and any request touching one of those rows waits on a third party it has no relationship with. In Postgres the session shows as idle in transaction, which is the signal the problem is recognised by.

The fix is to move the network call outside the transaction boundary. When the third party's result is what has to be persisted, it splits into two transactions with an idempotent record in between: write the intent, call outside a transaction, confirm the result.

@Post('payments')
async create(@Body() body: CreatePaymentRequest) {
  const pending = await this.transactionExecutor.execute(async () =>
    this.paymentRepository.save(Payment.pending(body)),
  );

  const charge = await this.paymentGateway.charge(body); // outside a transaction

  return this.transactionExecutor.execute(async () =>
    this.paymentRepository.confirm(pending.id, charge),
  );
}

Atomicity between the two halves is lost, and that is the real trade: in exchange, no connection sits waiting on a third party. The intermediate row in a pending state is what makes it possible to reconcile later if the second half never runs, which is exactly what idempotent webhook processing exists for.

The practical rule is short: only database operations go inside execute.

Failure records must be written outside the rollback

A system that records the execution of automated tasks also needs to persist the ones that fail. The natural approach is to write the failure row in the catch, using the same manager. But by then the transaction has already rolled back, and everything written with that manager is reverted along with it: the record of the failure disappears together with the failure.

The fix comes from recognising that success and failure need different managers:

} catch (err) {
  await queryRunner.rollbackTransaction();

  if (taskRun) {
    await this.persistTaskRun(
      this.dataSource.manager, // not queryRunner.manager: that transaction is gone
      taskRun,
      TaskRunStatus.FAILED,
      err,
    );
  }

  throw err;
}

Success rows go through queryRunner.manager and commit alongside the work. Failure rows go through this.dataSource.manager, on a separate connection, and survive the rollback. Recording outcomes requires both routes.

Nesting opens a second transaction, not a nested one

execute calls createQueryRunner() unconditionally and never checks whether a transaction is already active. As a result, this code:

await this.transactionExecutor.execute(async () => {
  await this.repository.save(order);
  await someService.doSomething(); // which internally calls execute() again
});

produces two independent transactions on two different connections. The inner run() shadows the outer manager for its duration, so the writes inside belong to the inner transaction and commit on their own. If the outer one later throws and rolls back, the inner work stays committed. Atomicity is lost with no warning at all.

The scenario has a second consequence: the inner transaction cannot see the outer's uncommitted writes, and if it touches a row the outer holds locked, it ends up waiting on a lock held by its own caller, which in turn is waiting on it. The result is a self-deadlock that only shows up under the exact interleaving that triggers it.

If nested calls are possible in the project, execute should join the active transaction instead of starting a new one:

async execute<T>(work: (manager: EntityManager) => Promise<T>): Promise<T> {
  const active = TransactionExecutor.entityManagerStorage.getStore();
  if (active) return work(active); // joins the caller's transaction

  // otherwise, open a new one
}

That produces flat participation: the outermost execute owns the commit and inner calls run inside it. It is the correct default for most applications. If independent inner transactions are genuinely needed somewhere, they are better offered as an explicit opt-in — executeInNewTransaction() — so it is a decision someone made rather than a shape the code fell into by omission.

Keeping the boundary at the controller prevents nesting from arising, but that is a convention, and conventions are one refactor away from being broken. The guard is preferable.

Keeping the pattern from breaking

The pattern has a weakness that is not technical: it depends on every repository following it. A repository that injects Repository<UserModel> on its own and uses it directly still compiles, still passes its tests and still returns the right data. The only thing it does wrong is stay outside transactions, silently. It is the same failure mode as at the start, back through a different door.

Two tests close it. The first proves the enlistment actually works, against a real database:

it('rolls back writes made through the repository', async () => {
  const email = 'ana@example.com';
  const userRepository = app.get(TypeOrmUserRepository);
  const transactionExecutor = app.get(TransactionExecutor);

  let visibleInside = false;

  await expect(
    transactionExecutor.execute(async () => {
      await userRepository.save(aUser({ email }));
      visibleInside = (await userRepository.findByEmail(email)) !== null;
      throw new Error('forced rollback');
    }),
  ).rejects.toThrow('forced rollback');

  expect(visibleInside).toBe(true); // the write did happen
  expect(await userRepository.findByEmail(email)).toBeNull(); // and the rollback reverted it
});

That test fails if someone breaks the enlistment, but only for the repository it covers. The second one is the one that scales: it walks the source code and checks that no repository skips the base class.

import { readdirSync, readFileSync } from 'node:fs';
import { join } from 'node:path';
import * as ts from 'typescript';

const SRC = join(process.cwd(), 'src');

function repositoryFiles(): string[] {
  return readdirSync(SRC, { recursive: true })
    .map(String)
    .map((file) => file.replaceAll('\\', '/'))
    .filter((file) => file.includes('infrastructure/typeorm/'))
    .filter((file) => file.endsWith('.repository.ts'));
}

it('every TypeORM repository extends BaseTypeOrmRepository', () => {
  const files = repositoryFiles();
  expect(files.length).toBeGreaterThan(0); // if it stops finding files, the test says so

  const offenders: string[] = [];

  for (const file of files) {
    const source = ts.createSourceFile(
      file,
      readFileSync(join(SRC, file), 'utf8'),
      ts.ScriptTarget.Latest,
    );

    source.forEachChild((node) => {
      if (!ts.isClassDeclaration(node) || !node.name) return;

      const isAbstract = node.modifiers?.some(
        (modifier) => modifier.kind === ts.SyntaxKind.AbstractKeyword,
      );
      if (isAbstract) return; // BaseTypeOrmRepository itself

      const extendsBase = node.heritageClauses?.some(
        (clause) =>
          clause.token === ts.SyntaxKind.ExtendsKeyword &&
          clause.types.some(
            (type) =>
              ts.isIdentifier(type.expression) &&
              type.expression.text === 'BaseTypeOrmRepository',
          ),
      );

      if (!extendsBase) offenders.push(`${node.name.text} (${file})`);
    });
  }

  expect(offenders).toEqual([]);
});

It is parsed with the TypeScript compiler rather than with regular expressions, because what is being looked for is an extends clause on a class declaration, and a regex confuses that with a comment or a string at the first opportunity.

With that test, the failure stops depending on someone catching it in review: the build catches it.

When not to apply it

If dataSource.transaction() is used directly in a handful of services and is causing no trouble, there is no reason to change it. This pattern pays for itself when a repository layer exists, a domain that should not know about the ORM, and enough repositories that replicating the enlistment logic is a real cost.

There are also libraries that wrap this same idea in a @Transactional() method decorator. The explicit version has two advantages: the boundary is visible at the call site instead of hidden in a decorator on a service three layers down, and extending the transaction lifecycle — to record outcomes, for instance — is a few lines in a file you own.

Checklist

The pattern is simple; the time goes into the details.

queryRunner.release() in finally, always, or connections leak on the error path.
The commit inside the run() callback, not after it.
getManagerIfActive() returns null instead of throwing, so repositories work outside transactions.
The AsyncLocalStorage field must be static: the store has to be unique for the whole process.
Only database operations go inside execute: a network call holds a pooled connection and the locks while it waits.
Failure records are written with dataSource.manager, not the already-rolled-back queryRunner.manager.
Behaviour under nesting is decided explicitly and enforced inside execute, not by convention.
An architecture test keeps a new repository from skipping the base class.

The best possible outcome is that nobody on the team ever has to think about any of this. They write repositories that look like ordinary repositories, use cases that look like ordinary use cases, and no signature mentions an EntityManager because there is no longer one to pass around.