Proposal: Implicit Transaction Context in Drizzle ORM

[agcty]

Problem Statement

Currently, when working with transactions in Drizzle ORM, one we need to explicitly pass the transaction object to every function that needs to participate in the transaction. This leads to verbose code and makes it challenging to manage transactions across multiple function calls, especially in complex business logic.

Example of current approach:

async function inviteUserToOrganization(db, email, organizationId, roleName) {
  return db.transaction(async (trx) => {
    const organization = await findOrganization(trx, organizationId);
    if (!organization) throw new Error("Organization not found");

    const membership = await createPendingMembership(trx, email, organizationId);
    await addRoleToMembership(trx, membership.id, roleName);

    return membership;
  });
}

async function findOrganization(trx, organizationId) {
  return trx.query.organizations.findFirst({
    where: eq(schema.organizations.id, organizationId),
  });
}

async function createPendingMembership(trx, email, organizationId) {
  // Implementation using trx
}

async function addRoleToMembership(trx, membershipId, roleName) {
  // Implementation using trx
}

Proposed Solution

Implement an implicit transaction context using AsyncLocalStorage or a similar mechanism. This would allow functions to access the current transaction without explicitly passing it as an argument.

Example of proposed approach:

import { createTransactionContext } from 'drizzle-orm/transaction-context';

const { withTransaction, useTransaction } = createTransactionContext(db);

async function inviteUserToOrganization(email, organizationId, roleName) {
  return withTransaction(async () => {
    const organization = await findOrganization(organizationId);
    if (!organization) throw new Error("Organization not found");

    const membership = await createPendingMembership(email, organizationId);
    await addRoleToMembership(membership.id, roleName);

    return membership;
  });
}

async function findOrganization(organizationId) {
  const trx = useTransaction();
  return trx.query.organizations.findFirst({
    where: eq(schema.organizations.id, organizationId),
  });
}

async function createPendingMembership(email, organizationId) {
  const trx = useTransaction();
  // Implementation using trx
}

async function addRoleToMembership(membershipId, roleName) {
  const trx = useTransaction();
  // Implementation using trx
}

Benefits

1. Cleaner function signatures without the need to pass transaction objects explicitly.
2. Easier to manage transactions across multiple function calls and nested operations.
3. Improved readability and maintainability of business logic.
4. Flexibility to use transactions implicitly or explicitly as needed.

Implementation Considerations

1. Use AsyncLocalStorage or a similar mechanism to store the current transaction context.
2. Provide helper functions like withTransaction to create transaction contexts and useTransaction to access the current transaction.
3. Ensure proper error handling and transaction rollback in case of exceptions.
4. Consider providing options for transaction isolation levels and timeouts.

Questions for Discussion

1. Should this be implemented as a core feature of Drizzle ORM or as an optional plugin/extension?
2. How can we ensure this approach doesn't introduce significant performance overhead?
3. Are there any potential pitfalls or edge cases we should be aware of with this approach?
4. How can we make this feature TypeScript-friendly and provide good type inference?

Related Discussion

An old issue #1473 already brought up this idea and I think it has a valid point. It mentions https://www.baeldung.com/spring-transactional-propagation-isolation which could be taken as a reference for a drizzle implementation.

What are your thoughts on this? How are people rolling transaction context at the moment?