Repository Prisma Pattern

This repository demonstrates an Implicit Transaction Pattern for Prisma in Node.js, inspired by "Repository Pattern + SQLAlchemy" in Python.

It solves the common problem of "Prop-Drilling" transaction objects (tx) through your service layers.

📖 Read the Full Design Document for architecture details.

The Problem: Explicit Transactions (Standard Pattern)

In standard Prisma, you must pass the transaction client explicitly:

``typescript
// Standard Prisma
await prisma.$transaction(async (tx) => {
await tx.user.create(...); // MUST use 'tx', not 'prisma'
await tx.post.create(...); // MUST use 'tx', not 'prisma'
})
`

If you forget to use tx and use the global prisma instead, your query runs OUTSIDE the transaction. This is error-prone.

The Solution: Implicit Transactions

We use Node.js AsyncLocalStorage to store the transaction context globally for the request.

We provide Two Patterns to use this.

$3

Best if you like clean, declarative code and are using TypeScript with experimentalDecorators.

`typescript
import { Transactional } from 'repository_prisma';

class UserService {
@Transactional()
async createUserAndPost() {
// Works automatically! no 'tx' argument needed.
await this.userRepo.create(...)
await this.postRepo.create(...)
}
}
`

$3

Best if you prefer explicit scoping and want to avoid experimental decorators.

`typescript
import { runInTransaction } from 'repository_prisma';

class UserService {
async createUserAndPost() {
// Explicit wrapper
await runInTransaction(async () => {
await this.userRepo.create(...)
await this.postRepo.create(...)
});
}
}
`

$3

If you want to skip repositories for a quick script or advanced Prisma queries, use the exported
prisma proxy. It automatically uses the transaction client if one is active.

`typescript
import { prisma, runInTransaction } from 'repository_prisma';

await runInTransaction(async () => {
await prisma.user.create({ data: { email: 'safe@example.com' } });
});
`

Initialization (Optional)

If you want to eagerly connect or enable SQLite WAL mode, call:

`typescript
import { initializePrisma } from 'repository_prisma';

await initializePrisma({ enableWAL: true });
`

Advanced: Root Client Access (Use Carefully)

The exported rootPrismaClient is intended for app-level tasks (migrations, health checks, cleanup scripts).
Avoid using it inside transactional flows, or you will bypass ALS and lose the implicit transaction behavior.

Example

See examples/implicit-transaction-demo.ts for a runnable demo.

Optional: No-Quote Repository Helper

If you prefer to avoid string literals like 'User', you can use BaseRepository.forModel:

`typescript
import { BaseRepository, Models } from 'repository_prisma';

export class UserRepository extends BaseRepository.forModel(Models.User) {}
export class PostRepository extends BaseRepository.forModel(Models.Post) {}
`

defineRepository is still available as a short alias if you prefer it.

Case-Insensitive Filters (SQLite-Safe)

SQLite does not support Prisma's mode: "insensitive" string filters. Use the helpers below
to avoid runtime errors and optionally apply a fallback in memory.

`typescript
import { buildContainsFilter, filterContainsCaseInsensitive, supportsCaseInsensitiveMode } from 'repository_prisma';

const where = { name: buildContainsFilter("Alice", { caseInsensitive: true }) };
const rows = await repo.findMany({ where });

// If you need true case-insensitive behavior on SQLite, apply in-memory fallback:
const filtered = supportsCaseInsensitiveMode()
? rows
: filterContainsCaseInsensitive(rows, "Alice", (row) => row.name);
`

If you want explicit provider selection, set PRISMA_DATASOURCE_PROVIDER=sqlite|postgresql|mysql|...
to override auto-detection (which uses DATABASE_URL).

Testing

npm test automatically syncs the Prisma schema to a dedicated SQLite file (test.db).
You can override it by setting DATABASE_URL_TEST.

Release (Tag-Based)

We use a tag-based release flow. Create a version tag and push it:

`bash
npm version patch -m "1.0.6" # or minor/major
git push origin main --follow-tags
`

If you prefer to tag manually (or via a Git UI), create an annotated tag:

`bash
git tag -a v1.0.6 -m "1.0.6"
git push origin main --tags
`

Pushing a tag like v1.2.3 triggers GitHub Actions to build and publish.
Trusted Publishing is enabled for this package.

How it Works

1. src/lib/context.ts: Holds the AsyncLocalStorage.
2. src/lib/prisma-manager.ts: The getPrismaClient() function checks the storage. If a transaction is active, it returns the transaction client. If not, it returns the global client.
3. src/lib/base-repository.ts: Uses getPrismaClient()` internally, so every query automatically uses the correct state.