Prisma Flare

A powerful TypeScript utilities package for Prisma ORM that provides a callback system and a query builder for chained operations.

Features

• Plug & Play: Works with any existing Prisma project
• Flare Builder: Elegant chainable query API for Prisma models
• Auto-Generated Queries: Automatically generates query classes based on your schema
• Callback System: Hooks for before/after operations (create, update, delete) and column-level changes
• Type-Safe: Full IntelliSense and compile-time type checking
• Zero Overhead: ~0.1-0.4% overhead per query (~0.001ms)

Installation

npm install prisma-flare

Compatibility

Prisma Version	Generator Provider	Support
5.x - 7.x	prisma-client-js	✅
7.x+	prisma-client	✅
7.x+	Multi-file schema	✅

Quick Start

1. Generate and Initialize

# Generate prisma-flare client (run after prisma generate)
npx prisma-flare generate

// prisma/db.ts
import './callbacks';
import { FlareClient } from 'prisma-flare/client';

export const db = new FlareClient();

Note: For advanced setups (custom Prisma output, monorepos), see Configuration.

2. Generate Query Classes

Query classes are auto-generated based on your Prisma schema:

npx prisma-flare generate

3. Use the Fluent API

import { DB } from 'prisma-flare/generated';

// Chainable queries with full type safety
const posts = await DB.posts
  .where({ published: true })
  .order({ createdAt: 'desc' })
  .limit(10)
  .include('author')
  .findMany();

// Pagination
const { data, meta } = await DB.users.paginate(1, 15);

// Conditional queries
const users = await DB.users
  .when(!!search, (q) => q.where({ name: { contains: search } }))
  .findMany();

4. Chain Raw SQL Without Breaking the Chain

defer() queues async work until execution, so a scope backed by raw SQL stays chainable like any other:

class User extends FlareBuilder<'user'> {
  random(n = 1) {
    return this.defer('id', () => db.$queryRaw`
      SELECT id FROM "User" ORDER BY RANDOM() LIMIT ${n}`);
  }
}

await DB.users.random(4).active().order({ name: 'asc' }).findMany();

For anything that isn't a simple in on one field, return a where filter or refine the builder directly. See API Reference for the full semantics.

5. Define Callbacks

// prisma/callbacks/user.ts
import { beforeCreate, afterChange } from 'prisma-flare-generated';

beforeCreate('user', async (args) => {
  if (!args.data.email.includes('@')) {
    throw new Error('Invalid email');
  }
});

afterChange('post', 'published', async (oldValue, newValue, record) => {
  if (!oldValue && newValue) {
    await notifySubscribers(record);
  }
});

Note: Always import hooks from prisma-flare-generated for proper type inference. This module is created by npx prisma-flare generate and provides types specific to your Prisma schema.

Documentation

• API Reference - Complete FlareBuilder API documentation
• Hooks & Callbacks - Lifecycle hooks and column-level change tracking
• Configuration - Config options, custom paths, and CLI commands
• How It Works - Architecture and type generation internals
• Development - Testing, contributing, and project structure

Custom Prisma Output

prisma-flare fully supports custom Prisma output paths. Just run npx prisma-flare generate and import from prisma-flare/client:

generator client {
  provider = "prisma-client-js"
  output   = "./generated/client"
}

// The recommended import - works with any Prisma configuration
import { FlareClient, FlareBuilder } from 'prisma-flare/client';

export const db = new FlareClient();

For the new prisma-client provider (Prisma 7+), you can also import from the generated flare.ts:

import { FlareClient } from './generated/flare';
import { PrismaPg } from '@prisma/adapter-pg';

const adapter = new PrismaPg({ connectionString: process.env.DATABASE_URL });
export const db = new FlareClient({ adapter });

Multi-File Schema (Prisma 7+)

prisma-flare automatically supports multi-file schemas. Just run npx prisma-flare generate:

prisma/schema/
├── _base.prisma    # generator & datasource (can be in any file)
├── user.prisma
├── post.prisma
└── ...

See Configuration for details.

Transactions

await DB.instance.transaction(async (tx) => {
  const user = await tx.from('user').create({
    email: 'new@example.com',
    name: 'New User',
  });

  await tx.from('post').create({
    title: 'First Post',
    authorId: user.id,
  });
});

Performance

Query Type	Overhead
findFirst by ID	+0.25%
findFirst + include	+0.23%
COUNT with WHERE	+0.34%
Complex query	+0.38%

Median overhead: 0.1-0.4% (~0.001ms per query)

License

ISC