prisma-flare 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,237 @@
+import * as _prisma_client from '@prisma/client';
+import { PrismaClient } from '@prisma/client';
+import * as _prisma_client_runtime_library from '@prisma/client/runtime/library';
+import { PrismaClientOptions } from '@prisma/client/runtime/library';
+import FlareBuilder from './core/flareBuilder.cjs';
+export { RelationModelMap } from './core/flareBuilder.cjs';
+import { M as ModelName, l as PrismaOperation, m as HookTiming, B as BeforeHookCallback, j as AfterHookCallback, k as ColumnChangeCallback } from './prisma.types-nGNe1CG8.cjs';
+export { r as AggregateResult, o as CreateArgs, C as CreateData, p as CreateManyArgs, b as CreateManyData, c as DeleteArgs, n as FindFirstArgs, F as FindManyArgs, a as ModelDelegate, R as RecordType, q as UpdateArgs, f as UpsertArgs } from './prisma.types-nGNe1CG8.cjs';
+export { afterChange, afterCreate, afterDelete, afterUpdate, afterUpsert, beforeCreate, beforeDelete, beforeUpdate } from './core/hooks.cjs';
+
+declare class FlareClient extends PrismaClient {
+    constructor(options?: PrismaClientOptions);
+    /**
+     * Creates a new FlareBuilder instance for the specified model.
+     * @param modelName - The name of the model.
+     * @returns FlareBuilder instance
+     */
+    from<T extends ModelName>(modelName: T): FlareBuilder<T>;
+    /**
+     * Executes a transaction with the FlareClient capabilities.
+     * @param fn - The transaction function.
+     * @param options - Transaction options.
+     * @returns The result of the transaction.
+     */
+    transaction<R>(fn: (tx: FlareClient) => Promise<R>, options?: {
+        maxWait?: number;
+        timeout?: number;
+        isolationLevel?: any;
+    }): Promise<R>;
+}
+/**
+ * @deprecated Use `FlareClient` instead. This alias will be removed in a future version.
+ */
+declare const ExtendedPrismaClient: typeof FlareClient;
+
+type ModelClass<T extends ModelName = any> = new () => FlareBuilder<T, any>;
+/**
+ * Registry for custom model classes that extend FlareBuilder.
+ * This allows the include() method to instantiate the correct custom model class
+ * for related models, preserving custom methods like `.valid()`, `.published()`, etc.
+ */
+declare class ModelRegistry {
+    private models;
+    /**
+     * Register a custom model class for a given model name.
+     * The model name should match the Prisma model name (e.g., 'user', 'post', 'enrollment')
+     * @param modelName - The lowercase model name (matching Prisma delegate name)
+     * @param modelClass - The custom class that extends FlareBuilder
+     */
+    register<T extends ModelName>(modelName: T, modelClass: ModelClass<T>): void;
+    /**
+     * Register multiple models at once
+     * @param models - Object mapping model names to their classes
+     */
+    registerMany(models: Record<string, ModelClass>): void;
+    /**
+     * Get a custom model class by name
+     * @param modelName - The model name to look up
+     * @returns The model class or undefined if not registered
+     */
+    get<T extends ModelName>(modelName: string): ModelClass<T> | undefined;
+    /**
+     * Check if a model is registered
+     * @param modelName - The model name to check
+     */
+    has(modelName: string): boolean;
+    /**
+     * Create an instance of a registered model
+     * @param modelName - The model name to instantiate
+     * @returns A new instance of the custom model class, or undefined if not registered
+     */
+    create<T extends ModelName>(modelName: string): FlareBuilder<T, any> | undefined;
+    /**
+     * Clear all registered models (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get all registered model names
+     */
+    getRegisteredModels(): string[];
+}
+declare const modelRegistry: ModelRegistry;
+
+/**
+ * Configuration options for the hook system.
+ */
+interface HookConfig {
+    /**
+     * Whether column-level hooks (afterChange) are enabled.
+     * Set to false to disable all column hooks globally.
+     * @default true
+     */
+    enableColumnHooks: boolean;
+    /**
+     * Maximum number of records to re-fetch for column hooks on updateMany.
+     * If an updateMany affects more records than this limit, column hooks
+     * will be skipped and a warning logged.
+     * Set to 0 or Infinity to disable the limit.
+     * @default 1000
+     */
+    maxRefetch: number;
+    /**
+     * Whether to log warnings when hooks are skipped.
+     * @default true
+     */
+    warnOnSkip: boolean;
+}
+declare class HookRegistry {
+    private hooks;
+    private columnHooks;
+    private fieldCache;
+    private modelsWithColumnHooks;
+    private config;
+    constructor();
+    /**
+     * Configure the hook system.
+     * @param config - Partial configuration to merge with defaults
+     *
+     * @example
+     * // Disable column hooks globally for performance
+     * hookRegistry.configure({ enableColumnHooks: false });
+     *
+     * @example
+     * // Increase maxRefetch limit
+     * hookRegistry.configure({ maxRefetch: 5000 });
+     *
+     * @example
+     * // Disable limit entirely (use with caution)
+     * hookRegistry.configure({ maxRefetch: Infinity });
+     */
+    configure(config: Partial<HookConfig>): void;
+    /**
+     * Get current configuration.
+     */
+    getConfig(): Readonly<HookConfig>;
+    addHook(model: ModelName, action: PrismaOperation, timing: HookTiming, fn: BeforeHookCallback | AfterHookCallback): void;
+    addColumnHook(model: ModelName, column: string, fn: ColumnChangeCallback<any>): void;
+    runHooks(timing: HookTiming, model: ModelName, action: PrismaOperation, args: any[], prisma: any): Promise<void>;
+    runColumnHooks(model: ModelName, newData: any, prevData: any, prisma: any): Promise<void>;
+    hasColumnHooks(model: ModelName): boolean;
+    /**
+     * Check if column hooks should run for an operation.
+     * Takes into account global config, record count limits, and per-call options.
+     *
+     * @param model - The model name
+     * @param recordCount - Number of records affected (for maxRefetch check)
+     * @param args - The operation args (to check for __flare skip option)
+     * @returns Whether column hooks should execute
+     */
+    shouldRunColumnHooks(model: ModelName, recordCount: number, args?: any): boolean;
+    getRelevantFields(model: ModelName): Record<string, true>;
+    /**
+     * Clear all registered hooks (useful for testing)
+     */
+    clearAll(): void;
+}
+declare const hookRegistry: HookRegistry;
+
+/**
+ * Loads callback files from a specified directory.
+ * Users can create a 'callbacks' directory in their project and call this function.
+ *
+ * IMPORTANT: This function is async - you MUST await it before querying to ensure
+ * all hooks are registered.
+ *
+ * In production Node.js environments, only .js files are loaded.
+ * TypeScript files (.ts) are only loaded when running under ts-node, tsx, Bun, or Vitest.
+ * Make sure to compile your TypeScript callbacks to JavaScript for production.
+ *
+ * @param callbacksDir - Path to the callbacks directory
+ * @returns Promise that resolves when all callbacks are loaded
+ *
+ * @example
+ * // In your app initialization:
+ * await loadCallbacks();
+ * // Now safe to query - all hooks are registered
+ */
+declare function loadCallbacks(callbacksDir?: string): Promise<void>;
+/**
+ * Creates a Prisma 7+ client extension for hooks
+ */
+declare function createHooksExtension(basePrisma: PrismaClient): (client: any) => _prisma_client.PrismaClientExtends<_prisma_client_runtime_library.InternalArgs<{}, {}, {}, {}>>;
+/**
+ * Registers hooks using the legacy $use middleware API (Prisma ≤6)
+ * @deprecated Use createHooksExtension for Prisma 7+
+ */
+declare function registerHooksLegacy(prisma: PrismaClient): void;
+/**
+ * Registers hooks on the Prisma client and automatically loads callbacks.
+ * Automatically detects Prisma version and uses the appropriate API:
+ * - Prisma ≤6: Uses $use middleware
+ * - Prisma 7+: Returns extended client with hooks extension
+ *
+ * Callbacks are loaded from the path specified in prisma-flare.config.json
+ * (defaults to 'prisma/callbacks'). Set `callbacksPath` in config to customize.
+ *
+ * @param prisma - The Prisma client instance
+ * @returns Promise resolving to the Prisma client (possibly extended for Prisma 7+)
+ *
+ * @example
+ * // In your db setup file:
+ * export const db = await registerHooks(new FlareClient());
+ */
+declare function registerHooks<T extends PrismaClient>(prisma: T): Promise<T>;
+
+/**
+ * Database Adapter Interface
+ */
+interface DatabaseAdapter {
+    /**
+     * Adapter name (e.g., 'postgres', 'sqlite')
+     */
+    name: string;
+    /**
+     * Check if this adapter handles the given connection URL
+     */
+    matches(url: string): boolean;
+    /**
+     * Create the database
+     */
+    create(url: string): Promise<void>;
+    /**
+     * Drop the database
+     */
+    drop(url: string): Promise<void>;
+}
+/**
+ * Adapter Registry
+ */
+declare class AdapterRegistry {
+    private adapters;
+    register(adapter: DatabaseAdapter): void;
+    getAdapter(url: string): DatabaseAdapter;
+}
+declare const registry: AdapterRegistry;
+
+export { AfterHookCallback, BeforeHookCallback, ColumnChangeCallback, type DatabaseAdapter, ExtendedPrismaClient, FlareBuilder, FlareClient, type HookConfig, HookTiming, ModelName, PrismaOperation, createHooksExtension, registry as dbAdapterRegistry, hookRegistry, loadCallbacks, modelRegistry, registerHooks, registerHooksLegacy };

package/dist/index.d.ts

@@ -0,0 +1,237 @@
+import * as _prisma_client from '@prisma/client';
+import { PrismaClient } from '@prisma/client';
+import * as _prisma_client_runtime_library from '@prisma/client/runtime/library';
+import { PrismaClientOptions } from '@prisma/client/runtime/library';
+import FlareBuilder from './core/flareBuilder.js';
+export { RelationModelMap } from './core/flareBuilder.js';
+import { M as ModelName, l as PrismaOperation, m as HookTiming, B as BeforeHookCallback, j as AfterHookCallback, k as ColumnChangeCallback } from './prisma.types-nGNe1CG8.js';
+export { r as AggregateResult, o as CreateArgs, C as CreateData, p as CreateManyArgs, b as CreateManyData, c as DeleteArgs, n as FindFirstArgs, F as FindManyArgs, a as ModelDelegate, R as RecordType, q as UpdateArgs, f as UpsertArgs } from './prisma.types-nGNe1CG8.js';
+export { afterChange, afterCreate, afterDelete, afterUpdate, afterUpsert, beforeCreate, beforeDelete, beforeUpdate } from './core/hooks.js';
+
+declare class FlareClient extends PrismaClient {
+    constructor(options?: PrismaClientOptions);
+    /**
+     * Creates a new FlareBuilder instance for the specified model.
+     * @param modelName - The name of the model.
+     * @returns FlareBuilder instance
+     */
+    from<T extends ModelName>(modelName: T): FlareBuilder<T>;
+    /**
+     * Executes a transaction with the FlareClient capabilities.
+     * @param fn - The transaction function.
+     * @param options - Transaction options.
+     * @returns The result of the transaction.
+     */
+    transaction<R>(fn: (tx: FlareClient) => Promise<R>, options?: {
+        maxWait?: number;
+        timeout?: number;
+        isolationLevel?: any;
+    }): Promise<R>;
+}
+/**
+ * @deprecated Use `FlareClient` instead. This alias will be removed in a future version.
+ */
+declare const ExtendedPrismaClient: typeof FlareClient;
+
+type ModelClass<T extends ModelName = any> = new () => FlareBuilder<T, any>;
+/**
+ * Registry for custom model classes that extend FlareBuilder.
+ * This allows the include() method to instantiate the correct custom model class
+ * for related models, preserving custom methods like `.valid()`, `.published()`, etc.
+ */
+declare class ModelRegistry {
+    private models;
+    /**
+     * Register a custom model class for a given model name.
+     * The model name should match the Prisma model name (e.g., 'user', 'post', 'enrollment')
+     * @param modelName - The lowercase model name (matching Prisma delegate name)
+     * @param modelClass - The custom class that extends FlareBuilder
+     */
+    register<T extends ModelName>(modelName: T, modelClass: ModelClass<T>): void;
+    /**
+     * Register multiple models at once
+     * @param models - Object mapping model names to their classes
+     */
+    registerMany(models: Record<string, ModelClass>): void;
+    /**
+     * Get a custom model class by name
+     * @param modelName - The model name to look up
+     * @returns The model class or undefined if not registered
+     */
+    get<T extends ModelName>(modelName: string): ModelClass<T> | undefined;
+    /**
+     * Check if a model is registered
+     * @param modelName - The model name to check
+     */
+    has(modelName: string): boolean;
+    /**
+     * Create an instance of a registered model
+     * @param modelName - The model name to instantiate
+     * @returns A new instance of the custom model class, or undefined if not registered
+     */
+    create<T extends ModelName>(modelName: string): FlareBuilder<T, any> | undefined;
+    /**
+     * Clear all registered models (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get all registered model names
+     */
+    getRegisteredModels(): string[];
+}
+declare const modelRegistry: ModelRegistry;
+
+/**
+ * Configuration options for the hook system.
+ */
+interface HookConfig {
+    /**
+     * Whether column-level hooks (afterChange) are enabled.
+     * Set to false to disable all column hooks globally.
+     * @default true
+     */
+    enableColumnHooks: boolean;
+    /**
+     * Maximum number of records to re-fetch for column hooks on updateMany.
+     * If an updateMany affects more records than this limit, column hooks
+     * will be skipped and a warning logged.
+     * Set to 0 or Infinity to disable the limit.
+     * @default 1000
+     */
+    maxRefetch: number;
+    /**
+     * Whether to log warnings when hooks are skipped.
+     * @default true
+     */
+    warnOnSkip: boolean;
+}
+declare class HookRegistry {
+    private hooks;
+    private columnHooks;
+    private fieldCache;
+    private modelsWithColumnHooks;
+    private config;
+    constructor();
+    /**
+     * Configure the hook system.
+     * @param config - Partial configuration to merge with defaults
+     *
+     * @example
+     * // Disable column hooks globally for performance
+     * hookRegistry.configure({ enableColumnHooks: false });
+     *
+     * @example
+     * // Increase maxRefetch limit
+     * hookRegistry.configure({ maxRefetch: 5000 });
+     *
+     * @example
+     * // Disable limit entirely (use with caution)
+     * hookRegistry.configure({ maxRefetch: Infinity });
+     */
+    configure(config: Partial<HookConfig>): void;
+    /**
+     * Get current configuration.
+     */
+    getConfig(): Readonly<HookConfig>;
+    addHook(model: ModelName, action: PrismaOperation, timing: HookTiming, fn: BeforeHookCallback | AfterHookCallback): void;
+    addColumnHook(model: ModelName, column: string, fn: ColumnChangeCallback<any>): void;
+    runHooks(timing: HookTiming, model: ModelName, action: PrismaOperation, args: any[], prisma: any): Promise<void>;
+    runColumnHooks(model: ModelName, newData: any, prevData: any, prisma: any): Promise<void>;
+    hasColumnHooks(model: ModelName): boolean;
+    /**
+     * Check if column hooks should run for an operation.
+     * Takes into account global config, record count limits, and per-call options.
+     *
+     * @param model - The model name
+     * @param recordCount - Number of records affected (for maxRefetch check)
+     * @param args - The operation args (to check for __flare skip option)
+     * @returns Whether column hooks should execute
+     */
+    shouldRunColumnHooks(model: ModelName, recordCount: number, args?: any): boolean;
+    getRelevantFields(model: ModelName): Record<string, true>;
+    /**
+     * Clear all registered hooks (useful for testing)
+     */
+    clearAll(): void;
+}
+declare const hookRegistry: HookRegistry;
+
+/**
+ * Loads callback files from a specified directory.
+ * Users can create a 'callbacks' directory in their project and call this function.
+ *
+ * IMPORTANT: This function is async - you MUST await it before querying to ensure
+ * all hooks are registered.
+ *
+ * In production Node.js environments, only .js files are loaded.
+ * TypeScript files (.ts) are only loaded when running under ts-node, tsx, Bun, or Vitest.
+ * Make sure to compile your TypeScript callbacks to JavaScript for production.
+ *
+ * @param callbacksDir - Path to the callbacks directory
+ * @returns Promise that resolves when all callbacks are loaded
+ *
+ * @example
+ * // In your app initialization:
+ * await loadCallbacks();
+ * // Now safe to query - all hooks are registered
+ */
+declare function loadCallbacks(callbacksDir?: string): Promise<void>;
+/**
+ * Creates a Prisma 7+ client extension for hooks
+ */
+declare function createHooksExtension(basePrisma: PrismaClient): (client: any) => _prisma_client.PrismaClientExtends<_prisma_client_runtime_library.InternalArgs<{}, {}, {}, {}>>;
+/**
+ * Registers hooks using the legacy $use middleware API (Prisma ≤6)
+ * @deprecated Use createHooksExtension for Prisma 7+
+ */
+declare function registerHooksLegacy(prisma: PrismaClient): void;
+/**
+ * Registers hooks on the Prisma client and automatically loads callbacks.
+ * Automatically detects Prisma version and uses the appropriate API:
+ * - Prisma ≤6: Uses $use middleware
+ * - Prisma 7+: Returns extended client with hooks extension
+ *
+ * Callbacks are loaded from the path specified in prisma-flare.config.json
+ * (defaults to 'prisma/callbacks'). Set `callbacksPath` in config to customize.
+ *
+ * @param prisma - The Prisma client instance
+ * @returns Promise resolving to the Prisma client (possibly extended for Prisma 7+)
+ *
+ * @example
+ * // In your db setup file:
+ * export const db = await registerHooks(new FlareClient());
+ */
+declare function registerHooks<T extends PrismaClient>(prisma: T): Promise<T>;
+
+/**
+ * Database Adapter Interface
+ */
+interface DatabaseAdapter {
+    /**
+     * Adapter name (e.g., 'postgres', 'sqlite')
+     */
+    name: string;
+    /**
+     * Check if this adapter handles the given connection URL
+     */
+    matches(url: string): boolean;
+    /**
+     * Create the database
+     */
+    create(url: string): Promise<void>;
+    /**
+     * Drop the database
+     */
+    drop(url: string): Promise<void>;
+}
+/**
+ * Adapter Registry
+ */
+declare class AdapterRegistry {
+    private adapters;
+    register(adapter: DatabaseAdapter): void;
+    getAdapter(url: string): DatabaseAdapter;
+}
+declare const registry: AdapterRegistry;
+
+export { AfterHookCallback, BeforeHookCallback, ColumnChangeCallback, type DatabaseAdapter, ExtendedPrismaClient, FlareBuilder, FlareClient, type HookConfig, HookTiming, ModelName, PrismaOperation, createHooksExtension, registry as dbAdapterRegistry, hookRegistry, loadCallbacks, modelRegistry, registerHooks, registerHooksLegacy };