@fluojs/prisma

Prisma lifecycle and ALS-backed transaction context for fluo applications. Connects a PrismaClient to the module system with automatic connection management and request-scoped transactions.

Table of Contents

• Installation
• When to Use
• Quick Start
• Common Patterns
  • PrismaService and current()
  • Named Registrations for Multiple Clients
  • Manual Transactions
  • Automatic Request Transactions
  • Async Configuration and Isolation
  • Manual Module Composition
• Public API Overview
• Related Packages
• Example Sources

Installation

pnpm add @fluojs/prisma
# Ensure @prisma/client is also installed
pnpm add @prisma/client

When to Use

• When using Prisma as your ORM and you want it integrated with fluo's dependency injection and lifecycle hooks.
• When you need a reliable way to share a transaction context across multiple services and repositories without passing a tx object everywhere.
• When you want automatic $connect on startup and $disconnect on shutdown.

Quick Start

Register the PrismaModule in your root module by providing a PrismaClient instance.

import { Module } from '@fluojs/core';
import { PrismaModule } from '@fluojs/prisma';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

@Module({
  imports: [
    PrismaModule.forRoot({ client: prisma }),
  ],
})
class AppModule {}

Common Patterns

PrismaService and current()

The PrismaService is the primary way to interact with Prisma. Its current() method automatically returns the active transaction client if inside a transaction scope, or the root client otherwise.

import { Inject } from '@fluojs/core';
import { PrismaService } from '@fluojs/prisma';
import { PrismaClient } from '@prisma/client';

@Inject(PrismaService)
export class UserRepository {
  constructor(private readonly prisma: PrismaService<PrismaClient>) {}

  async findById(id: string) {
    // current() preserves your generated Prisma types and autocomplete
    return this.prisma.current().user.findUnique({ where: { id } });
  }
}

Named Registrations for Multiple Clients

When one application container needs more than one Prisma client, register each client with an explicit name and inject the matching token with getPrismaServiceToken(name).

import { Inject } from '@fluojs/core';
import { PrismaModule, PrismaService, getPrismaServiceToken } from '@fluojs/prisma';

const usersPrismaModule = PrismaModule.forRoot({ name: 'users', client: usersPrisma });
const analyticsPrismaModule = PrismaModule.forRoot({ name: 'analytics', client: analyticsPrisma });

@Inject(getPrismaServiceToken('users'), getPrismaServiceToken('analytics'))
export class MultiDatabaseService {
  constructor(
    private readonly users: PrismaService<typeof usersPrisma>,
    private readonly analytics: PrismaService<typeof analyticsPrisma>,
  ) {}

  async loadDashboard(userId: string) {
    const user = await this.users.current().user.findUnique({ where: { id: userId } });
    const summary = await this.analytics.current().report.findMany();
    return { summary, user };
  }
}

Unnamed registration remains the default single-client path for PrismaService, PRISMA_CLIENT, PRISMA_OPTIONS, and PrismaTransactionInterceptor. When you register multiple Prisma clients in the same container, use names for every additional client so token resolution stays explicit.

Manual Transactions

Use prisma.transaction() to create an interactive transaction block. Any calls to current() inside the block will use the transaction-scoped client.

await this.prisma.transaction(async () => {
  const user = await this.prisma.current().user.create({ data });
  await this.prisma.current().profile.create({ data: { userId: user.id } });
});

When transaction() is called while a transaction context is already active, PrismaService reuses the active transaction client instead of opening a nested Prisma transaction. Nested calls must not pass transaction options such as isolation levels; providing options in an active context is rejected so the package does not silently drop caller intent while reusing the ambient transaction.

Automatic Request Transactions

Apply the PrismaTransactionInterceptor to a controller or method to wrap the entire request in a transaction automatically.

import { Post, UseInterceptors } from '@fluojs/http';
import { PrismaTransactionInterceptor } from '@fluojs/prisma';

@UseInterceptors(PrismaTransactionInterceptor)
class UserController {
  @Post()
  async create() {
    // All downstream repository calls via PrismaService.current() share this tx
  }
}

PrismaTransactionInterceptor targets the default unnamed PrismaService. For named multi-client registrations, inject the corresponding named PrismaService and open explicit transaction() / requestTransaction() boundaries where needed.

Async Configuration and Isolation

Use PrismaModule.forRootAsync(...) when the Prisma client must be created from injected configuration or another async source. The async factory is resolved once per application container and is not shared across separate bootstraps, even when the same module definition is reused in tests or multi-app processes.

import { PrismaClient } from '@prisma/client';
import { PrismaModule } from '@fluojs/prisma';

PrismaModule.forRootAsync({
  inject: [DatabaseConfig],
  useFactory: (config: DatabaseConfig) => ({
    client: new PrismaClient({ datasources: { db: { url: config.url } } }),
    strictTransactions: true,
  }),
});

Within one compiled application, downstream providers share the same resolved PrismaService, ALS transaction context, and lifecycle-managed client. Separate application containers receive independent factory results, so $connect / $disconnect ownership and request transaction state remain isolated.

Manual Module Composition

Use PrismaModule.forRoot(...) / forRootAsync(...) to register Prisma. When you need to compose Prisma support inside a custom defineModule(...) registration, import the module entrypoint there as well.

import { defineModule } from '@fluojs/runtime';
import { PrismaModule, PrismaService, PrismaTransactionInterceptor } from '@fluojs/prisma';
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

class ManualPrismaModule {}

defineModule(ManualPrismaModule, {
  exports: [PrismaService, PrismaTransactionInterceptor],
  imports: [PrismaModule.forRoot({ client: prisma })],
});

Public API Overview

PrismaModule

• PrismaModule.forRoot(options) / PrismaModule.forRootAsync(options)
• forRoot(...) and forRootAsync(...) also accept name for named/scoped registrations.
• forRootAsync(...) accepts DI-aware Prisma options whose factory returns the client and transaction settings; pass name or global on the top-level async registration so module identity and visibility are decided before the factory runs.
• forRootAsync(...) resolves options once per application container, preserving client lifecycle and request transaction isolation across separate bootstraps.
• Supports strictTransactions: true to throw if transaction support is missing.
• When strictTransactions is false, PrismaService falls back to direct execution if the client does not expose interactive $transaction.
• Names are trimmed for named registrations, and blank names are rejected.

PrismaService<TClient>

• current(): TClient | PrismaTransactionClient<TClient>
  • Returns the ambient transaction client or the root client.
• transaction(fn, options?): Promise<T>
  • Runs a function within an interactive transaction. If a transaction context is already active, the callback reuses that context; nested transaction options are rejected because no new Prisma transaction boundary is opened.
• requestTransaction(fn, signal?, options?): Promise<T>
  • Specialized transaction boundary for HTTP request lifecycles. It is abort-aware, drains during shutdown before disconnect, and retries without signal when a Prisma client rejects that option. Like transaction(), nested calls reuse the active transaction context and reject nested options to avoid silently ignoring transaction settings.

PRISMA_CLIENT (Token)

Injectable token for the raw PrismaClient instance.

PRISMA_OPTIONS (Token)

Injectable token for the public runtime options consumed by PrismaService, currently { strictTransactions: boolean }. This is intentionally narrower than the package's internal normalized module-options token, which also carries registration identity, client ownership, and visibility metadata and is not part of the public API.

Platform status

• createPrismaPlatformStatusSnapshot(input): Creates a persistence platform status snapshot that reports Prisma readiness, health, ownership, and ALS-backed transaction context.

Named Prisma token helpers

• getPrismaClientToken(name?)
• getPrismaOptionsToken(name?)
• getPrismaServiceToken(name?)

These helpers return the default unnamed token when name is omitted and a registration-specific token when name is provided. They are the public way to target named registrations; internal implementation tokens such as the normalized module-options token are deliberately not exported.

Related exported types

• PrismaModuleOptions
• PrismaClientLike
• PrismaHandleProvider
• PrismaTransactionClient<TClient>
• InferPrismaTransactionClient<TClient>
• InferPrismaTransactionOptions<TClient>

Related Packages

• @fluojs/runtime: Manages the application lifecycle hooks.
• @fluojs/http: Provides the interceptor system.
• @fluojs/terminus: Provides a health indicator for Prisma.

Example Sources

• packages/prisma/src/vertical-slice.test.ts: DTO → Service → Repository → Prisma flow.
• packages/prisma/src/module.test.ts: Module lifecycle, named clients, async factories, strict transaction behavior, and status snapshots.