prisma-flare 1.0.0

package/dist/core/flareBuilder.d.ts

@@ -0,0 +1,402 @@
+import { Prisma } from '@prisma/client';
+import { M as ModelName, a as ModelDelegate, Q as QueryArgs, W as WhereInput, O as OrderByInput, R as RecordType, D as DistinctInput, S as SelectInput, I as IncludeKey, G as GroupByInput, H as HavingInput, P as PaginatedResult, C as CreateData, b as CreateManyData, c as DeleteArgs, d as DeleteManyArgs, U as UpdateData, e as UpdateManyData, f as UpsertArgs, g as SumFields, A as AvgFields, h as MinFields, i as MaxFields } from '../prisma.types-nGNe1CG8.js';
+
+/**
+ * Global interface for relation-to-model mapping.
+ * This is augmented by prisma-flare/generated to provide type-safe includes.
+ *
+ * @example
+ * // In your project, prisma-flare generate creates:
+ * declare module 'prisma-flare' {
+ *   interface RelationModelMap {
+ *     posts: Post;
+ *     author: User;
+ *   }
+ * }
+ */
+interface RelationModelMap {
+    [key: string]: FlareBuilder<any, any>;
+}
+/**
+ * Helper type to get the model class for a relation name
+ */
+type GetRelationModel<K extends string> = K extends keyof RelationModelMap ? RelationModelMap[K] : FlareBuilder<any, {}>;
+/**
+ * FlareBuilder for chainable Prisma queries with full type safety
+ * The type safety is enforced through the ModelDelegate parameter
+ */
+declare class FlareBuilder<T extends ModelName, Args extends Record<string, any> = {}> {
+    protected model: ModelDelegate<T>;
+    protected query: QueryArgs;
+    constructor(model: ModelDelegate<T>, query?: QueryArgs);
+    /**
+     * Adds a where condition to the query with type safety from Prisma.
+     * Multiple where() calls are composed using AND logic to avoid silent overwrites.
+     * @param condition - Where filter matching your Prisma model
+     *
+     * @example
+     * // These conditions are AND-ed together:
+     * DB.posts
+     *   .where({ published: true })
+     *   .where({ authorId: 1 })
+     *   .findMany()
+     * // Equivalent to: { AND: [{ published: true }, { authorId: 1 }] }
+     */
+    where(condition: WhereInput<T>): FlareBuilder<T, Args & {
+        where: WhereInput<T>;
+    }>;
+    /**
+     * Adds a where condition using AND logic (explicit alias for where())
+     * @param condition - Where filter matching your Prisma model
+     *
+     * @example
+     * DB.posts
+     *   .where({ published: true })
+     *   .andWhere({ createdAt: { gte: new Date('2024-01-01') } })
+     *   .findMany()
+     */
+    andWhere(condition: WhereInput<T>): FlareBuilder<T, Args & {
+        where: WhereInput<T>;
+    }>;
+    /**
+     * Adds a where condition using OR logic.
+     *
+     * ⚠️ **IMPORTANT**: `orWhere()` wraps the *entire* accumulated where clause:
+     * `OR([prevWhere, condition])`. This means:
+     *
+     * ```ts
+     * .where(A).orWhere(B).where(C)  // becomes: (A OR B) AND C
+     * ```
+     *
+     * For complex boolean logic, prefer `whereGroup()` / `orWhereGroup()` for explicit control.
+     *
+     * @param condition - Where filter matching your Prisma model
+     *
+     * @example
+     * // Simple case - OK:
+     * DB.posts
+     *   .where({ published: true })
+     *   .orWhere({ featured: true })
+     *   .findMany()
+     * // Result: published OR featured
+     *
+     * @example
+     * // For complex logic, use whereGroup instead:
+     * DB.posts
+     *   .where({ published: true })
+     *   .whereGroup(qb => qb
+     *     .where({ category: 'news' })
+     *     .orWhere({ category: 'tech' })
+     *   )
+     *   .findMany()
+     * // Result: published AND (category='news' OR category='tech')
+     */
+    orWhere(condition: WhereInput<T>): FlareBuilder<T, Args & {
+        where: WhereInput<T>;
+    }>;
+    /**
+     * Creates a grouped where condition using a callback.
+     * Use this for explicit control over boolean logic grouping.
+     * The callback receives a fresh builder - its accumulated where becomes a single group.
+     *
+     * @param callback - Function that builds the grouped condition
+     * @param mode - How to combine with existing where: 'AND' (default) or 'OR'
+     *
+     * @example
+     * // (status = 'active') AND (name LIKE 'A%' OR name LIKE 'B%')
+     * DB.users
+     *   .where({ status: 'active' })
+     *   .whereGroup(qb => qb
+     *     .where({ name: { startsWith: 'A' } })
+     *     .orWhere({ name: { startsWith: 'B' } })
+     *   )
+     *   .findMany()
+     *
+     * @example
+     * // (status = 'active') OR (role = 'admin' AND verified = true)
+     * DB.users
+     *   .where({ status: 'active' })
+     *   .whereGroup(qb => qb
+     *     .where({ role: 'admin' })
+     *     .where({ verified: true })
+     *   , 'OR')
+     *   .findMany()
+     */
+    whereGroup(callback: (builder: FlareBuilder<T, {}>) => FlareBuilder<T, any>, mode?: 'AND' | 'OR'): FlareBuilder<T, Args & {
+        where: WhereInput<T>;
+    }>;
+    /**
+     * Alias for whereGroup with OR mode.
+     * Creates a grouped condition that's OR-ed with existing where.
+     *
+     * @param callback - Function that builds the grouped condition
+     *
+     * @example
+     * // (published = true) OR (authorId = 1 AND draft = true)
+     * DB.posts
+     *   .where({ published: true })
+     *   .orWhereGroup(qb => qb
+     *     .where({ authorId: 1 })
+     *     .where({ draft: true })
+     *   )
+     *   .findMany()
+     */
+    orWhereGroup(callback: (builder: FlareBuilder<T, {}>) => FlareBuilder<T, any>): FlareBuilder<T, Args & {
+        where: WhereInput<T>;
+    }>;
+    /**
+     * Adds a where condition to the query for the specified id.
+     * Uses the same AND composition as where() for consistency.
+     * @param id - The id to search for
+     */
+    withId(id: number | string): FlareBuilder<T, Args & {
+        where: {
+            id: number | string;
+        };
+    }>;
+    /**
+     * Adds an order by condition to the query
+     * @param orderBy - OrderBy object matching your Prisma model
+     */
+    order(orderBy: OrderByInput<T>): FlareBuilder<T, Args & {
+        orderBy: OrderByInput<T>;
+    }>;
+    /**
+     * Gets the last record sorted by the specified field
+     * @param key - Field to sort by (defaults to 'createdAt')
+     */
+    last(key?: keyof RecordType<T> | string): FlareBuilder<T, Args & {
+        orderBy: any;
+        take: number;
+    }>;
+    /**
+     * Gets the first record sorted by the specified field
+     * @param key - Field to sort by (defaults to 'createdAt')
+     */
+    first(key?: keyof RecordType<T> | string): FlareBuilder<T, Args & {
+        orderBy: any;
+        take: number;
+    }>;
+    /**
+     * Sets a limit on the number of records to retrieve
+     * @param limit - Maximum number of records
+     */
+    limit(limit: number): FlareBuilder<T, Args & {
+        take: number;
+    }>;
+    /**
+     * Sets distinct fields for the query
+     * @param distinct - Fields to be distinct
+     */
+    distinct(distinct: DistinctInput<T>): FlareBuilder<T, Args & {
+        distinct: DistinctInput<T>;
+    }>;
+    /**
+     * Selects specific fields to retrieve
+     * @param fields - Select object matching your Prisma model
+     */
+    select<S extends SelectInput<T>>(fields: S): FlareBuilder<T, Args & {
+        select: S;
+    }>;
+    /**
+     * Selects only the specified field and returns its value
+     * @param field - Field name to retrieve
+     */
+    only<K extends keyof RecordType<T>>(field: K): Promise<RecordType<T>[K] | null>;
+    /**
+     * Returns the current query object
+     */
+    getQuery(): QueryArgs;
+    /**
+   * Includes a relation (typed from Prisma's `include` args)
+   */
+    include<K extends IncludeKey<T>>(relation: K): FlareBuilder<T, Args & {
+        include: {
+            [P in K]: true;
+        };
+    }>;
+    /**
+     * Includes a relation with query customization using a builder.
+     * The callback receives the custom model class if registered via prisma-flare generate.
+     * Type inference is automatic when RelationModelMap is properly augmented.
+     *
+     * @example
+     * // Type-safe includes with custom methods (automatic after prisma-flare generate):
+     * .include("posts", (posts) => posts.published().recent(5))
+     * .include("author", (author) => author.withEmail("test@example.com"))
+     */
+    include<K extends IncludeKey<T>, R extends FlareBuilder<any, any>>(relation: K, callback: (builder: GetRelationModel<K & string>) => R): FlareBuilder<T, Args & {
+        include: {
+            [P in K]: R extends FlareBuilder<any, infer RA> ? RA : true;
+        };
+    }>;
+    /**
+     * Groups results by specified fields
+     * @param groupBy - Fields to group by
+     */
+    groupBy(groupBy: GroupByInput<T>): FlareBuilder<T, Args & {
+        by: GroupByInput<T>;
+    }>;
+    /**
+     * Adds a having condition to the query
+     * @param condition - Having condition
+     */
+    having(condition: HavingInput<T>): FlareBuilder<T, Args & {
+        having: HavingInput<T>;
+    }>;
+    /**
+     * Skips the specified number of records
+     * @param offset - Number of records to skip
+     */
+    skip(offset: number): FlareBuilder<T, Args & {
+        skip: number;
+    }>;
+    /**
+     * Checks if any record exists matching the current query
+     * @param existenceKey - Key to check for existence (defaults to 'id')
+     */
+    exists(existenceKey?: string): Promise<boolean>;
+    /**
+     * Paginates the results
+     * @param page - Page number (1-based)
+     * @param perPage - Number of records per page
+     */
+    paginate(page?: number, perPage?: number): Promise<PaginatedResult<RecordType<T>>>;
+    /**
+     * Conditionally executes a callback on the query builder
+     * @param condition - Boolean or function returning boolean
+     * @param callback - Function to execute if condition is true
+     */
+    when(condition: boolean | (() => boolean), callback: (qb: this) => void): this;
+    /**
+     * Processes results in chunks to avoid memory issues
+     * @param size - Size of each chunk
+     * @param callback - Function to process each chunk
+     */
+    chunk(size: number, callback: (results: RecordType<T>[]) => Promise<void> | void): Promise<void>;
+    /**
+     * Clones the current query builder instance.
+     * Uses structuredClone for proper handling of Date, BigInt, etc.
+     */
+    clone(): FlareBuilder<T, Args>;
+    /**
+     * Finds the first record matching the query or throws an error if none found
+     * Throws a Prisma NotFoundError if no record matches the query
+     * @throws {Prisma.NotFoundError} When no record matches the query
+     * @returns Promise resolving to the found record
+     */
+    findFirstOrThrow(): Promise<NonNullable<RecordType<T>>>;
+    /**
+     * Finds a unique record by primary key or throws an error if not found
+     * Requires a unique constraint (typically the id field)
+     * Throws a Prisma NotFoundError if no record matches
+     * @throws {Prisma.NotFoundError} When no record is found
+     * @returns Promise resolving to the found record
+     */
+    findUniqueOrThrow(): Promise<NonNullable<RecordType<T>>>;
+    /**
+     * Finds all records matching the query
+     * Respects all previously set query conditions (where, orderBy, take, skip, include, select, distinct)
+     * @returns Promise resolving to an array of records matching the query
+     */
+    findMany(): Promise<Prisma.Result<ModelDelegate<T>, Args, 'findMany'>>;
+    /**
+     * Finds the first record matching the query
+     * Returns null if no record matches. To throw an error instead, use findFirstOrThrow()
+     * @returns Promise resolving to the first matching record or null
+     */
+    findFirst(): Promise<Prisma.Result<ModelDelegate<T>, Args, 'findFirst'>>;
+    /**
+     * Finds a unique record by primary key
+     * Returns null if no record is found. To throw an error instead, use findUniqueOrThrow()
+     * Requires a unique constraint in the where condition (typically the id field)
+     * @returns Promise resolving to the found record or null
+     */
+    findUnique(): Promise<Prisma.Result<ModelDelegate<T>, Args, 'findUnique'>>;
+    /**
+     * Creates a new record with the provided data
+     * Any hooks registered for 'create' operations will be triggered
+     * @param data - Data matching your Prisma model's create input
+     * @returns Promise resolving to the newly created record
+     */
+    create(data: CreateData<T>): Promise<Prisma.Result<ModelDelegate<T>, Args, 'create'>>;
+    /**
+     * Creates multiple records in a single operation
+     * More efficient than creating records individually
+     * Any hooks registered for 'create' operations will be triggered for each record
+     * @param data - Array of data objects matching your Prisma model's create input
+     * @returns Promise resolving to the count of created records
+     */
+    createMany(data: CreateManyData<T>): Promise<Prisma.Result<ModelDelegate<T>, Args, 'createMany'>>;
+    /**
+     * Deletes a single record matching the current query conditions
+     * Requires at least one unique constraint in the where condition (typically id)
+     * Any hooks registered for 'delete' operations will be triggered
+     * @param args - Optional additional delete arguments to override query conditions
+     * @returns Promise resolving to the deleted record
+     */
+    delete(args?: DeleteArgs<T>): Promise<Prisma.Result<ModelDelegate<T>, Args, 'delete'>>;
+    /**
+     * Deletes multiple records matching the current query conditions
+     * More efficient than deleting records individually
+     * Any hooks registered for 'delete' operations will be triggered for each record
+     * @param args - Optional additional delete arguments to override query conditions
+     * @returns Promise resolving to the count of deleted records
+     */
+    deleteMany(args?: DeleteManyArgs<T>): Promise<Prisma.Result<ModelDelegate<T>, Args, 'deleteMany'>>;
+    /**
+     * Updates a single record matching the current query conditions
+     * Requires at least one unique constraint in the where condition (typically id)
+     * Any hooks registered for 'update' operations will be triggered
+     * @param data - Data to update, matching your Prisma model's update input
+     * @returns Promise resolving to the updated record
+     */
+    update(data: UpdateData<T>): Promise<Prisma.Result<ModelDelegate<T>, Args, 'update'>>;
+    /**
+     * Updates multiple records matching the current query conditions
+     * More efficient than updating records individually
+     * Any hooks registered for 'update' operations will be triggered for each record
+     * @param data - Data to update, matching your Prisma model's update input
+     * @returns Promise resolving to the count of updated records
+     */
+    updateMany(data: UpdateManyData<T>): Promise<Prisma.Result<ModelDelegate<T>, Args, 'updateMany'>>;
+    /**
+     * Updates a record if it exists, otherwise creates a new record
+     * The record is uniquely identified by the where condition (typically id)
+     * Any hooks registered for 'update' or 'create' operations will be triggered accordingly
+     * @param args - Optional upsert arguments including where, update, and create data
+     * @returns Promise resolving to the upserted record
+     */
+    upsert(args?: UpsertArgs<T>): Promise<Prisma.Result<ModelDelegate<T>, Args, 'upsert'>>;
+    /**
+     * Counts the number of records matching the query
+     */
+    count(): Promise<number>;
+    /**
+     * Sums the specified numeric field
+     * @param field - Field name to sum
+     */
+    sum(field: SumFields<T> & string): Promise<number | null>;
+    /**
+     * Calculates the average of the specified numeric field
+     * @param field - Field name to average
+     */
+    avg(field: AvgFields<T> & string): Promise<number | null>;
+    /**
+     * Finds the minimum value of the specified field
+     * @param field - Field name to find minimum
+     */
+    min(field: MinFields<T> & string): Promise<any>;
+    /**
+     * Finds the maximum value of the specified field
+     * @param field - Field name to find maximum
+     */
+    max(field: MaxFields<T> & string): Promise<any>;
+    /**
+     * Plucks the specified field from all results
+     * @param field - Field name to pluck
+     */
+    pluck<K extends keyof RecordType<T>>(field: K): Promise<RecordType<T>[K][]>;
+}
+
+export { type RelationModelMap, FlareBuilder as default };