prisma-flare 1.1.8 → 1.2.0

package/README.md

@@ -0,0 +1,162 @@
+# 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
+
+```bash
+npm install prisma-flare
+```
+
+### Compatibility
+
+| Prisma Version | Generator Provider | Support |
+|----------------|-------------------|---------|
+| 5.x - 7.x | `prisma-client-js` | ✅ |
+| 7.x+ | `prisma-client` | ✅ |
+
+## Quick Start
+
+### 1. Generate and Initialize
+
+```bash
+# Generate prisma-flare client (run after prisma generate)
+npx prisma-flare generate
+```
+
+```typescript
+// 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](docs/configuration.md).
+
+### 2. Generate Query Classes
+
+Query classes are auto-generated based on your Prisma schema:
+
+```bash
+npx prisma-flare generate
+```
+
+### 3. Use the Fluent API
+
+```typescript
+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. Define Callbacks
+
+```typescript
+// prisma/callbacks/user.ts
+import { beforeCreate, afterChange } from 'prisma-flare';
+
+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);
+  }
+});
+```
+
+## Documentation
+
+- **[API Reference](docs/api-reference.md)** - Complete FlareBuilder API documentation
+- **[Hooks & Callbacks](docs/hooks.md)** - Lifecycle hooks and column-level change tracking
+- **[Configuration](docs/configuration.md)** - Config options, custom paths, and CLI commands
+- **[How It Works](docs/how-it-works.md)** - Architecture and type generation internals
+- **[Development](docs/development.md)** - 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`:
+
+```prisma
+generator client {
+  provider = "prisma-client-js"
+  output   = "./generated/client"
+}
+```
+
+```typescript
+// 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`:
+
+```typescript
+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 });
+```
+
+See [Configuration](docs/configuration.md#new-provider-prisma-client---prisma-7) for full setup.
+
+## Transactions
+
+```typescript
+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

package/dist/cli/db-create.cjs

@@ -23,6 +23,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// src/cli/db-create.ts
+var import_dotenv = require("dotenv");
+
 // src/core/adapters/postgres.ts
 var PostgresAdapter = {
   name: "postgres",
@@ -30,26 +33,26 @@ var PostgresAdapter = {
     return url.startsWith("postgresql://") || url.startsWith("postgres://");
   },
   async create(url) {
-    const config = parseDatabaseUrl(url);
+    const config2 = parseDatabaseUrl(url);
     const { Client } = await import("pg");
     const client = new Client({
-      user: config.user,
-      password: config.password,
-      host: config.host,
-      port: config.port,
+      user: config2.user,
+      password: config2.password,
+      host: config2.host,
+      port: config2.port,
       database: "postgres"
     });
     try {
       await client.connect();
       const checkRes = await client.query(
         `SELECT 1 FROM pg_database WHERE datname = $1`,
-        [config.database]
+        [config2.database]
       );
       if (checkRes.rowCount === 0) {
-        await client.query(`CREATE DATABASE "${config.database}"`);
-        console.log(`\u2705 Database "${config.database}" created successfully.`);
+        await client.query(`CREATE DATABASE "${config2.database}"`);
+        console.log(`\u2705 Database "${config2.database}" created successfully.`);
       } else {
-        console.log(`\u26A0\uFE0F  Database "${config.database}" already exists.`);
+        console.log(`\u26A0\uFE0F  Database "${config2.database}" already exists.`);
       }
     } catch (error) {
       console.error("\u274C Error creating database:", error);
@@ -59,13 +62,13 @@ var PostgresAdapter = {
     }
   },
   async drop(url) {
-    const config = parseDatabaseUrl(url);
+    const config2 = parseDatabaseUrl(url);
     const { Client } = await import("pg");
     const client = new Client({
-      user: config.user,
-      password: config.password,
-      host: config.host,
-      port: config.port,
+      user: config2.user,
+      password: config2.password,
+      host: config2.host,
+      port: config2.port,
       database: "postgres"
     });
     try {
@@ -75,10 +78,10 @@ var PostgresAdapter = {
          FROM pg_stat_activity
          WHERE pg_stat_activity.datname = $1
          AND pid <> pg_backend_pid()`,
-        [config.database]
+        [config2.database]
       );
-      await client.query(`DROP DATABASE IF EXISTS "${config.database}"`);
-      console.log(`\u2705 Database "${config.database}" dropped successfully.`);
+      await client.query(`DROP DATABASE IF EXISTS "${config2.database}"`);
+      console.log(`\u2705 Database "${config2.database}" dropped successfully.`);
     } catch (error) {
       console.error("\u274C Error dropping database:", error);
       throw error;
@@ -181,10 +184,12 @@ registry.register(PostgresAdapter);
 registry.register(SqliteAdapter);
 
 // src/cli/db-create.ts
+(0, import_dotenv.config)();
 async function createDatabase() {
   const databaseUrl = process.env.DATABASE_URL;
   if (!databaseUrl) {
     console.error("\u274C DATABASE_URL environment variable is not set");
+    console.error("   Make sure DATABASE_URL is set in your .env file or environment");
     process.exit(1);
   }
   try {

package/dist/cli/db-create.d.cts

@@ -1 +1,2 @@
 #!/usr/bin/env node
+import 'prisma-flare-generated';

package/dist/cli/db-create.d.ts

@@ -1 +1,2 @@
 #!/usr/bin/env node
+import 'prisma-flare-generated';

package/dist/cli/db-create.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 
+// src/cli/db-create.ts
+import { config } from "dotenv";
+
 // src/core/adapters/postgres.ts
 var PostgresAdapter = {
   name: "postgres",
@@ -7,26 +10,26 @@ var PostgresAdapter = {
     return url.startsWith("postgresql://") || url.startsWith("postgres://");
   },
   async create(url) {
-    const config = parseDatabaseUrl(url);
+    const config2 = parseDatabaseUrl(url);
     const { Client } = await import("pg");
     const client = new Client({
-      user: config.user,
-      password: config.password,
-      host: config.host,
-      port: config.port,
+      user: config2.user,
+      password: config2.password,
+      host: config2.host,
+      port: config2.port,
       database: "postgres"
     });
     try {
       await client.connect();
       const checkRes = await client.query(
         `SELECT 1 FROM pg_database WHERE datname = $1`,
-        [config.database]
+        [config2.database]
       );
       if (checkRes.rowCount === 0) {
-        await client.query(`CREATE DATABASE "${config.database}"`);
-        console.log(`\u2705 Database "${config.database}" created successfully.`);
+        await client.query(`CREATE DATABASE "${config2.database}"`);
+        console.log(`\u2705 Database "${config2.database}" created successfully.`);
       } else {
-        console.log(`\u26A0\uFE0F  Database "${config.database}" already exists.`);
+        console.log(`\u26A0\uFE0F  Database "${config2.database}" already exists.`);
       }
     } catch (error) {
       console.error("\u274C Error creating database:", error);
@@ -36,13 +39,13 @@ var PostgresAdapter = {
     }
   },
   async drop(url) {
-    const config = parseDatabaseUrl(url);
+    const config2 = parseDatabaseUrl(url);
     const { Client } = await import("pg");
     const client = new Client({
-      user: config.user,
-      password: config.password,
-      host: config.host,
-      port: config.port,
+      user: config2.user,
+      password: config2.password,
+      host: config2.host,
+      port: config2.port,
       database: "postgres"
     });
     try {
@@ -52,10 +55,10 @@ var PostgresAdapter = {
          FROM pg_stat_activity
          WHERE pg_stat_activity.datname = $1
          AND pid <> pg_backend_pid()`,
-        [config.database]
+        [config2.database]
       );
-      await client.query(`DROP DATABASE IF EXISTS "${config.database}"`);
-      console.log(`\u2705 Database "${config.database}" dropped successfully.`);
+      await client.query(`DROP DATABASE IF EXISTS "${config2.database}"`);
+      console.log(`\u2705 Database "${config2.database}" dropped successfully.`);
     } catch (error) {
       console.error("\u274C Error dropping database:", error);
       throw error;
@@ -158,10 +161,12 @@ registry.register(PostgresAdapter);
 registry.register(SqliteAdapter);
 
 // src/cli/db-create.ts
+config();
 async function createDatabase() {
   const databaseUrl = process.env.DATABASE_URL;
   if (!databaseUrl) {
     console.error("\u274C DATABASE_URL environment variable is not set");
+    console.error("   Make sure DATABASE_URL is set in your .env file or environment");
     process.exit(1);
   }
   try {

package/dist/cli/db-drop.cjs

@@ -24,6 +24,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/cli/db-drop.ts
+var import_dotenv = require("dotenv");
 var readline = __toESM(require("readline"), 1);
 
 // src/core/adapters/postgres.ts
@@ -33,26 +34,26 @@ var PostgresAdapter = {
     return url.startsWith("postgresql://") || url.startsWith("postgres://");
   },
   async create(url) {
-    const config = parseDatabaseUrl(url);
+    const config2 = parseDatabaseUrl(url);
     const { Client } = await import("pg");
     const client = new Client({
-      user: config.user,
-      password: config.password,
-      host: config.host,
-      port: config.port,
+      user: config2.user,
+      password: config2.password,
+      host: config2.host,
+      port: config2.port,
       database: "postgres"
     });
     try {
       await client.connect();
       const checkRes = await client.query(
         `SELECT 1 FROM pg_database WHERE datname = $1`,
-        [config.database]
+        [config2.database]
       );
       if (checkRes.rowCount === 0) {
-        await client.query(`CREATE DATABASE "${config.database}"`);
-        console.log(`\u2705 Database "${config.database}" created successfully.`);
+        await client.query(`CREATE DATABASE "${config2.database}"`);
+        console.log(`\u2705 Database "${config2.database}" created successfully.`);
       } else {
-        console.log(`\u26A0\uFE0F  Database "${config.database}" already exists.`);
+        console.log(`\u26A0\uFE0F  Database "${config2.database}" already exists.`);
       }
     } catch (error) {
       console.error("\u274C Error creating database:", error);
@@ -62,13 +63,13 @@ var PostgresAdapter = {
     }
   },
   async drop(url) {
-    const config = parseDatabaseUrl(url);
+    const config2 = parseDatabaseUrl(url);
     const { Client } = await import("pg");
     const client = new Client({
-      user: config.user,
-      password: config.password,
-      host: config.host,
-      port: config.port,
+      user: config2.user,
+      password: config2.password,
+      host: config2.host,
+      port: config2.port,
       database: "postgres"
     });
     try {
@@ -78,10 +79,10 @@ var PostgresAdapter = {
          FROM pg_stat_activity
          WHERE pg_stat_activity.datname = $1
          AND pid <> pg_backend_pid()`,
-        [config.database]
+        [config2.database]
       );
-      await client.query(`DROP DATABASE IF EXISTS "${config.database}"`);
-      console.log(`\u2705 Database "${config.database}" dropped successfully.`);
+      await client.query(`DROP DATABASE IF EXISTS "${config2.database}"`);
+      console.log(`\u2705 Database "${config2.database}" dropped successfully.`);
     } catch (error) {
       console.error("\u274C Error dropping database:", error);
       throw error;
@@ -184,6 +185,7 @@ registry.register(PostgresAdapter);
 registry.register(SqliteAdapter);
 
 // src/cli/db-drop.ts
+(0, import_dotenv.config)();
 function confirm(question) {
   const rl = readline.createInterface({
     input: process.stdin,
@@ -201,6 +203,7 @@ async function dropDatabase() {
   const skipConfirmation = process.argv.includes("--force") || process.argv.includes("-f");
   if (!databaseUrl) {
     console.error("\u274C DATABASE_URL environment variable is not set");
+    console.error("   Make sure DATABASE_URL is set in your .env file or environment");
     process.exit(1);
   }
   try {

package/dist/cli/db-drop.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli/db-drop.ts
+import { config } from "dotenv";
 import * as readline from "readline";
 
 // src/core/adapters/postgres.ts
@@ -10,26 +11,26 @@ var PostgresAdapter = {
     return url.startsWith("postgresql://") || url.startsWith("postgres://");
   },
   async create(url) {
-    const config = parseDatabaseUrl(url);
+    const config2 = parseDatabaseUrl(url);
     const { Client } = await import("pg");
     const client = new Client({
-      user: config.user,
-      password: config.password,
-      host: config.host,
-      port: config.port,
+      user: config2.user,
+      password: config2.password,
+      host: config2.host,
+      port: config2.port,
       database: "postgres"
     });
     try {
       await client.connect();
       const checkRes = await client.query(
         `SELECT 1 FROM pg_database WHERE datname = $1`,
-        [config.database]
+        [config2.database]
       );
       if (checkRes.rowCount === 0) {
-        await client.query(`CREATE DATABASE "${config.database}"`);
-        console.log(`\u2705 Database "${config.database}" created successfully.`);
+        await client.query(`CREATE DATABASE "${config2.database}"`);
+        console.log(`\u2705 Database "${config2.database}" created successfully.`);
       } else {
-        console.log(`\u26A0\uFE0F  Database "${config.database}" already exists.`);
+        console.log(`\u26A0\uFE0F  Database "${config2.database}" already exists.`);
       }
     } catch (error) {
       console.error("\u274C Error creating database:", error);
@@ -39,13 +40,13 @@ var PostgresAdapter = {
     }
   },
   async drop(url) {
-    const config = parseDatabaseUrl(url);
+    const config2 = parseDatabaseUrl(url);
     const { Client } = await import("pg");
     const client = new Client({
-      user: config.user,
-      password: config.password,
-      host: config.host,
-      port: config.port,
+      user: config2.user,
+      password: config2.password,
+      host: config2.host,
+      port: config2.port,
       database: "postgres"
     });
     try {
@@ -55,10 +56,10 @@ var PostgresAdapter = {
          FROM pg_stat_activity
          WHERE pg_stat_activity.datname = $1
          AND pid <> pg_backend_pid()`,
-        [config.database]
+        [config2.database]
       );
-      await client.query(`DROP DATABASE IF EXISTS "${config.database}"`);
-      console.log(`\u2705 Database "${config.database}" dropped successfully.`);
+      await client.query(`DROP DATABASE IF EXISTS "${config2.database}"`);
+      console.log(`\u2705 Database "${config2.database}" dropped successfully.`);
     } catch (error) {
       console.error("\u274C Error dropping database:", error);
       throw error;
@@ -161,6 +162,7 @@ registry.register(PostgresAdapter);
 registry.register(SqliteAdapter);
 
 // src/cli/db-drop.ts
+config();
 function confirm(question) {
   const rl = readline.createInterface({
     input: process.stdin,
@@ -178,6 +180,7 @@ async function dropDatabase() {
   const skipConfirmation = process.argv.includes("--force") || process.argv.includes("-f");
   if (!databaseUrl) {
     console.error("\u274C DATABASE_URL environment variable is not set");
+    console.error("   Make sure DATABASE_URL is set in your .env file or environment");
     process.exit(1);
   }
   try {