Feature: Add support to transactions by luanupe · Pull Request #2 · Uanela/prisma-smart-cache

luanupe · 2026-04-24T20:58:05Z

Summary

This PR improves transaction support in prisma-smart-cache, specifically addressing cache consistency issues when using Prisma transactions and compatibility issues with array-based transactions.

Problems addressed

Interactive transactions bypassed smart cache

Previously, when using:

await prisma.$transaction(async (tx) => {
  await tx.user.update(...)
})

the tx object was Prisma’s raw transaction client. Because of that:

reads inside the transaction did not go through the smart cache wrapper;
writes inside the transaction did not trigger cache invalidation;
cached data could remain stale after transactional writes.

Array transactions could fail with PrismaPromise validation

When using:

await prisma.$transaction([
  prisma.user.findMany(...),
  prisma.user.create(...),
])

proxied operations returned regular JavaScript promises instead of Prisma Client promises. Prisma requires all array transaction entries to be Prisma Client promises, which could lead to:

All elements of the array need to be Prisma Client promises

What changed

Interactive transaction support

$transaction is now handled explicitly by the proxy.

For interactive transactions, the transaction client passed to the callback is wrapped with smart cache by default:

await prisma.$transaction(async (tx) => {
  await tx.user.update({
    where: { id: 1 },
    data: { name: "Ada" },
  });
});

This allows transactional reads and writes to go through the same cache-aware behavior as the root client.

Deferred invalidation after transaction commit

Writes inside interactive transactions no longer invalidate cache immediately.

Instead, mutations are collected while the transaction callback runs, and invalidation is flushed only after the transaction commits successfully.

If the transaction rolls back or throws, no invalidation is performed.

This avoids invalidating cache before the database changes are actually committed.

Opt-out for raw transaction client

A transaction can explicitly opt out of smart cache wrapping:

await prisma.$transaction(
  async (tx) => {
    await tx.user.update({
      where: { id: 1 },
      data: { name: "Ada" },
    });
  },
  { smartCache: { enabled: false } }
);

In this case, the callback receives Prisma’s original transaction client.

The custom smartCache option is stripped before forwarding transaction options to Prisma.

`$raw` passthrough client

A $raw property was added to expose the original Prisma client behavior for cases where preserving Prisma Client promises is required.

This is especially useful for array transactions:

await prisma.$transaction([
  prisma.$raw.user.findMany({ where: { active: true } }),
  prisma.$raw.user.create({ data: { name: "Ada" } }),
]);

$raw bypasses caching but strips the custom cache option from arguments before forwarding calls to Prisma.

Public invalidation method

The internal invalidation method was made public so transaction invalidation can call it directly after commit.

When multiple transactional mutations are collected, invalidations are flushed with Promise.all after first checking that there are mutations to process.

Types moved to shared type file

Transaction-related cache mutation types were moved into src/types.ts and exported from the package entrypoint.

This keeps shared proxy/handler types in the same place as the rest of the public/internal type definitions.

Documentation

The README now includes a section explaining:

interactive transaction behavior;
how to opt out of smart cache inside transactions;
how to use $raw for array transactions;
why interactive transactions are preferred when automatic invalidation is needed.

Tests

Regression coverage was added for:

wrapping interactive transaction clients by default;
opting out with smartCache.enabled: false;
deferring invalidation until transaction success;
avoiding invalidation on rollback;
preserving array transaction behavior;
using $raw without smart cache interception;
direct invalidation behavior in the cache handler.

Implementation note

Some logic was intentionally kept inline and slightly duplicated in the proxy.

The goal was to minimize unnecessary abstraction in areas where small behavior differences matter, such as:

regular cached model operations;
raw passthrough operations;
interactive transactions;
array transactions.

Over-reusing the same helper paths here could introduce unnecessary risk, since these flows may need slightly different rules over time.

To avoid duplicating even more code, a small wrapClient function is still used internally to wrap both the root Prisma client and transaction clients consistently.

How to test

Run the test suite:

npm test

Run the package build:

npm run build

Manual scenarios worth validating in a consuming app:

Interactive transaction invalidation

await prisma.user.findMany({
  cache: { ttl: 60 },
});

await prisma.$transaction(async (tx) => {
  await tx.user.update({
    where: { id: 1 },
    data: { name: "Updated" },
  });
});

await prisma.user.findMany();

The final read should not return stale cached data.

Opt out of smart cache inside transaction

await prisma.$transaction(
  async (tx) => {
    await tx.user.findMany();
  },
  { smartCache: { enabled: false } }
);

The transaction callback should receive the raw Prisma transaction client.

Array transaction with `$raw`

await prisma.$transaction([
  prisma.$raw.user.findMany(),
  prisma.$raw.user.count(),
]);

This should preserve Prisma Client promises and avoid the array transaction validation error.

luanupe · 2026-04-24T21:00:18Z

Hey @Uanela, this is still a draft while I run some local tests, but I’d like to get your thoughts on these changes. The goal is to improve $transaction support. #1

Uanela · 2026-04-25T11:14:29Z

It was faster than I thought. I will get hands on this ASAP.

But for the code itself I was reading so far seems GREAT but I need to make a deep dive and test it.

Uanela

Great job @luanupe you went deeper into this codebase (even thought not that large, but somehow dealing with a kind complex scenario) and the job you did was exactly what was blind to me on the benchmark repo (I will migrate to this as monorepo instead) see https://github.com/Uanela/smart-cache-benchmark

Uanela · 2026-04-27T02:43:20Z

  });

  test("should intercept write operations and call handleWrite", async () => {
+    mockHandlerInstance.isReadOperation.mockReturnValue(false);


This is not needed and does nothing you can remove

Uanela · 2026-04-27T02:53:16Z

+      data: { name: "Ada" },
+    });
+  },
+  { smartCache: { enabled: false } }


See https://github.com/Uanela/prisma-smart-cache/pull/2/changes#r3144714942 before tackling those 2

Let's rename smartCache -> cache

Allow pass cache: false as shorthand and keep the current behavior also because it allows expansion

Uanela · 2026-04-27T02:55:19Z

+
+```ts
+await prisma.$transaction([
+  prisma.$raw.user.findMany({ where: { active: true } }),


Loved this one

Uanela · 2026-04-27T03:12:21Z

+  ? ((...args: A) => R) &
+      (<TResult>(
+        fn: (tx: PrismaWithCache<any>) => Promise<TResult>,
+        options?: SmartCacheTransactionOptions & Record<string, any>


options must be strictly typed

Regarding SmartCacheTransactionOptions I think we should stick to CacheQueryOptions it will stay consistent with the current API, and using it would be a clear sign of meaning apply those CacheQueryOptions to the global transaction. e.g:

await prisma.$transaction( async (tx) => { await tx.user.update({ where: { id: 1 }, data: { name: "Ada" }, }); }, { cache: ... } // CacheQueryOptions | false

Uanela · 2026-04-27T03:15:27Z

+}
+
+interface ProxyRuntimeOptions {
+  deferInvalidation?: (mutation: CacheMutation) => void;


What you think about renaming deferInvalidation to simply defer

Uanela · 2026-04-27T03:23:17Z

+
+        // wrap interactive transactions so tx can use smart cache and defer invalidation
+        if (modelName === "$transaction" && typeof modelDelegate === "function") {
+          return (firstArg: any, transactionOptions?: any) => {


Let's add the types that we already have here I guess will make it much clear for future readers

Uanela · 2026-04-27T03:25:55Z

+              smartCache: _smartCache,
+              ...prismaTransactionOptions
+            } = (transactionOptions ?? {}) as SmartCacheTransactionOptions &
+              Record<string, any>;


As we already casted to SmartCacheTransactionOptions maybe Record<string, any> is unneeded what you think?

Uanela · 2026-04-27T03:27:42Z

+              )
+              .then(async (result: unknown) => {
+                // flush transaction invalidations only after commit succeeds
+                if (useSmartCache && mutations?.length) {


Been loving your work @luanupe

Uanela · 2026-04-27T03:47:25Z

+);
+```
+
+For array transactions, Prisma requires every array element to be a Prisma Client promise. Cached operations return regular promises, so use `$raw` when building the array:


The correct name is sequential transactions I just saw now on their website you could put sequential transactions (array transactions).

I think also for this one would be great if we added a https://www.prisma.io/docs/orm/prisma-client/queries/transactions#sequential-operations so that users can quickly grasp why the $raw. I am trying to check if would could go without $raw but up until now shows impossible, and for now the solution you brought is the GREATEST

Uanela · 2026-04-27T03:51:07Z

+    mockPrisma.user.findMany.mockReturnValue(prismaPromise);
+
+    const proxy = smartCache(mockPrisma, mockBento);
+    const result = proxy.$raw.user.findMany({ cache: { ttl: 100 } } as any);


is the cache object need on this situation, I think not at all. what are you thoughts on this one?

luanupe · 2026-04-28T00:23:54Z

Hey @Uanela ,
Thank you for your review. I will address the points you mentioned next Friday (May 1st is a holiday here in Brazil).

I believe your points are indeed valid. 🙂

Uanela · 2026-04-28T06:00:03Z

Glad you got those, in Mozambique May 1st is also an holiday.

Uanela · 2026-05-02T08:58:18Z

Any update?

luanupe · 2026-05-02T13:28:02Z

Any update?

Hey @Uanela I haven't forgotten about this PR, but I ended up finding a huge bug in one of my projects, requiring data migration and some other major changes that are taking up a lot of my time. But I'll get back to fixing it ASAP.

luanupe added 4 commits April 24, 2026 17:38

chore: ignore lock and pack files

d83d347

feat: adds support to transactions

1aacf25

test: new behaviour for transactions

49c1348

chore: add docs for transactions support

3b25ab3

luanupe marked this pull request as draft April 24, 2026 20:58

Uanela requested changes Apr 27, 2026

View reviewed changes

Conversation

luanupe commented Apr 24, 2026

Summary

Problems addressed

Interactive transactions bypassed smart cache

Array transactions could fail with PrismaPromise validation

What changed

Interactive transaction support

Deferred invalidation after transaction commit

Opt-out for raw transaction client

$raw passthrough client

Public invalidation method

Types moved to shared type file

Documentation

Tests

Implementation note

How to test

Interactive transaction invalidation

Opt out of smart cache inside transaction

Array transaction with $raw

Uh oh!

luanupe commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uanela commented Apr 25, 2026

Uh oh!

Uanela left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

luanupe commented Apr 28, 2026

Uh oh!

Uanela commented Apr 28, 2026

Uh oh!

Uanela commented May 2, 2026

Uh oh!

luanupe commented May 2, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

`$raw` passthrough client

Array transaction with `$raw`

luanupe commented Apr 24, 2026 •

edited

Loading