prisma-flare 1.0.0

package/dist/core/flareBuilder.js

@@ -0,0 +1,658 @@
+// src/core/modelRegistry.ts
+var ModelRegistry = class {
+  constructor() {
+    this.models = /* @__PURE__ */ new Map();
+  }
+  /**
+   * 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(modelName, modelClass) {
+    this.models.set(modelName.toLowerCase(), modelClass);
+  }
+  /**
+   * Register multiple models at once
+   * @param models - Object mapping model names to their classes
+   */
+  registerMany(models) {
+    for (const [name, modelClass] of Object.entries(models)) {
+      this.register(name, modelClass);
+    }
+  }
+  /**
+   * 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(modelName) {
+    return this.models.get(modelName.toLowerCase());
+  }
+  /**
+   * Check if a model is registered
+   * @param modelName - The model name to check
+   */
+  has(modelName) {
+    return this.models.has(modelName.toLowerCase());
+  }
+  /**
+   * 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(modelName) {
+    const ModelClass = this.get(modelName);
+    if (ModelClass) {
+      return new ModelClass();
+    }
+    return void 0;
+  }
+  /**
+   * Clear all registered models (useful for testing)
+   */
+  clear() {
+    this.models.clear();
+  }
+  /**
+   * Get all registered model names
+   */
+  getRegisteredModels() {
+    return Array.from(this.models.keys());
+  }
+};
+var modelRegistry = new ModelRegistry();
+
+// src/core/flareBuilder.ts
+function deepClone(obj) {
+  if (obj === null || typeof obj !== "object") {
+    return obj;
+  }
+  if (typeof obj === "bigint") {
+    return obj;
+  }
+  if (typeof structuredClone === "function") {
+    try {
+      return structuredClone(obj);
+    } catch {
+    }
+  }
+  if (obj instanceof Date) {
+    return new Date(obj.getTime());
+  }
+  if (obj instanceof RegExp) {
+    return new RegExp(obj.source, obj.flags);
+  }
+  if (typeof Buffer !== "undefined" && Buffer.isBuffer(obj)) {
+    return Buffer.from(obj);
+  }
+  if (obj instanceof ArrayBuffer) {
+    return obj.slice(0);
+  }
+  if (ArrayBuffer.isView(obj) && !(obj instanceof DataView)) {
+    const TypedArrayConstructor = obj.constructor;
+    const buffer = obj.buffer instanceof ArrayBuffer ? obj.buffer.slice(0) : obj.buffer;
+    return new TypedArrayConstructor(buffer);
+  }
+  if (obj instanceof Map) {
+    const clonedMap = /* @__PURE__ */ new Map();
+    obj.forEach((value, key) => {
+      clonedMap.set(deepClone(key), deepClone(value));
+    });
+    return clonedMap;
+  }
+  if (obj instanceof Set) {
+    const clonedSet = /* @__PURE__ */ new Set();
+    obj.forEach((value) => {
+      clonedSet.add(deepClone(value));
+    });
+    return clonedSet;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => deepClone(item));
+  }
+  if (typeof obj.toDecimalPlaces === "function") {
+    return obj;
+  }
+  const prototype = Object.getPrototypeOf(obj);
+  const cloned = Object.create(prototype);
+  for (const key in obj) {
+    if (Object.prototype.hasOwnProperty.call(obj, key)) {
+      cloned[key] = deepClone(obj[key]);
+    }
+  }
+  return cloned;
+}
+var FlareBuilder = class _FlareBuilder {
+  constructor(model, query = {}) {
+    this.model = model;
+    this.query = query;
+  }
+  /**
+   * 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) {
+    if (!this.query.where || Object.keys(this.query.where).length === 0) {
+      this.query.where = condition;
+    } else {
+      const prevWhere = this.query.where;
+      this.query.where = { AND: [prevWhere, condition] };
+    }
+    return this;
+  }
+  /**
+   * 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) {
+    return this.where(condition);
+  }
+  /**
+   * 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) {
+    if (!this.query.where || Object.keys(this.query.where).length === 0) {
+      this.query.where = condition;
+    } else {
+      const prevWhere = this.query.where;
+      this.query.where = { OR: [prevWhere, condition] };
+    }
+    return this;
+  }
+  /**
+   * 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, mode = "AND") {
+    const groupBuilder = new _FlareBuilder(this.model, {});
+    callback(groupBuilder);
+    const groupWhere = groupBuilder.getQuery().where;
+    if (!groupWhere || Object.keys(groupWhere).length === 0) {
+      return this;
+    }
+    if (!this.query.where || Object.keys(this.query.where).length === 0) {
+      this.query.where = groupWhere;
+    } else {
+      const prevWhere = this.query.where;
+      this.query.where = { [mode]: [prevWhere, groupWhere] };
+    }
+    return this;
+  }
+  /**
+   * 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) {
+    return this.whereGroup(callback, "OR");
+  }
+  /**
+   * 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) {
+    if (!id) {
+      throw new Error("Id is required");
+    }
+    if (!this.query.where || Object.keys(this.query.where).length === 0) {
+      this.query.where = { id };
+    } else {
+      const prevWhere = this.query.where;
+      this.query.where = { AND: [prevWhere, { id }] };
+    }
+    return this;
+  }
+  /**
+   * Adds an order by condition to the query
+   * @param orderBy - OrderBy object matching your Prisma model
+   */
+  order(orderBy) {
+    this.query.orderBy = orderBy;
+    return this;
+  }
+  /**
+   * Gets the last record sorted by the specified field
+   * @param key - Field to sort by (defaults to 'createdAt')
+   */
+  last(key = "createdAt") {
+    return this.order({ [key]: "desc" }).limit(1);
+  }
+  /**
+   * Gets the first record sorted by the specified field
+   * @param key - Field to sort by (defaults to 'createdAt')
+   */
+  first(key = "createdAt") {
+    return this.order({ [key]: "asc" }).limit(1);
+  }
+  /**
+   * Sets a limit on the number of records to retrieve
+   * @param limit - Maximum number of records
+   */
+  limit(limit) {
+    this.query.take = limit;
+    return this;
+  }
+  /**
+   * Sets distinct fields for the query
+   * @param distinct - Fields to be distinct
+   */
+  distinct(distinct) {
+    this.query.distinct = distinct;
+    return this;
+  }
+  /**
+   * Selects specific fields to retrieve
+   * @param fields - Select object matching your Prisma model
+   */
+  select(fields) {
+    this.query.select = fields;
+    return this;
+  }
+  /**
+   * Selects only the specified field and returns its value
+   * @param field - Field name to retrieve
+   */
+  async only(field) {
+    this.query.select = { [field]: true };
+    const result = await this.model.findFirst(this.query);
+    if (!result) {
+      return null;
+    }
+    return result[field];
+  }
+  /**
+   * Returns the current query object
+   */
+  getQuery() {
+    return this.query;
+  }
+  include(relation, callback) {
+    let relationQuery = true;
+    if (callback) {
+      const builder = modelRegistry.create(relation) ?? new _FlareBuilder(null);
+      callback(builder);
+      relationQuery = builder.getQuery();
+      if (Object.keys(relationQuery).length === 0) {
+        relationQuery = true;
+      }
+    }
+    this.query.include = {
+      ...this.query.include,
+      [relation]: relationQuery
+    };
+    return this;
+  }
+  /**
+   * Groups results by specified fields
+   * @param groupBy - Fields to group by
+   */
+  groupBy(groupBy) {
+    this.query.by = groupBy;
+    return this;
+  }
+  /**
+   * Adds a having condition to the query
+   * @param condition - Having condition
+   */
+  having(condition) {
+    this.query.having = condition;
+    return this;
+  }
+  /**
+   * Skips the specified number of records
+   * @param offset - Number of records to skip
+   */
+  skip(offset) {
+    this.query.skip = offset;
+    return this;
+  }
+  /**
+   * Checks if any record exists matching the current query
+   * @param existenceKey - Key to check for existence (defaults to 'id')
+   */
+  async exists(existenceKey = "id") {
+    const result = await this.model.findFirst({
+      where: this.query.where,
+      select: { [existenceKey]: true }
+    });
+    return Boolean(result);
+  }
+  /**
+   * Paginates the results
+   * @param page - Page number (1-based)
+   * @param perPage - Number of records per page
+   */
+  async paginate(page = 1, perPage = 15) {
+    const skip = (page - 1) * perPage;
+    const take = perPage;
+    this.query.skip = skip;
+    this.query.take = take;
+    const [data, total] = await Promise.all([
+      this.model.findMany(this.query),
+      this.model.count({ where: this.query.where })
+    ]);
+    const lastPage = Math.ceil(total / perPage);
+    return {
+      data,
+      meta: {
+        total,
+        lastPage,
+        currentPage: page,
+        perPage,
+        prev: page > 1 ? page - 1 : null,
+        next: page < lastPage ? page + 1 : null
+      }
+    };
+  }
+  /**
+   * 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, callback) {
+    const isTrue = typeof condition === "function" ? condition() : condition;
+    if (isTrue) {
+      callback(this);
+    }
+    return this;
+  }
+  /**
+   * Processes results in chunks to avoid memory issues
+   * @param size - Size of each chunk
+   * @param callback - Function to process each chunk
+   */
+  async chunk(size, callback) {
+    let page = 1;
+    let hasMore = true;
+    const originalSkip = this.query.skip;
+    const originalTake = this.query.take;
+    while (hasMore) {
+      this.query.skip = (page - 1) * size;
+      this.query.take = size;
+      const results = await this.model.findMany(this.query);
+      if (results.length > 0) {
+        await callback(results);
+        page++;
+        if (results.length < size) {
+          hasMore = false;
+        }
+      } else {
+        hasMore = false;
+      }
+    }
+    this.query.skip = originalSkip;
+    this.query.take = originalTake;
+  }
+  /**
+   * Clones the current query builder instance.
+   * Uses structuredClone for proper handling of Date, BigInt, etc.
+   */
+  clone() {
+    const queryCopy = deepClone(this.query);
+    return new _FlareBuilder(this.model, queryCopy);
+  }
+  /**
+   * 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
+   */
+  async findFirstOrThrow() {
+    return this.model.findFirstOrThrow(this.query);
+  }
+  /**
+   * 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
+   */
+  async findUniqueOrThrow() {
+    return this.model.findUniqueOrThrow(this.query);
+  }
+  /**
+   * 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
+   */
+  async findMany() {
+    return this.model.findMany(this.query);
+  }
+  /**
+   * 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
+   */
+  async findFirst() {
+    return this.model.findFirst(this.query);
+  }
+  /**
+   * 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
+   */
+  async findUnique() {
+    return this.model.findUnique(this.query);
+  }
+  /**
+   * 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
+   */
+  async create(data) {
+    const query = { ...this.query, data };
+    return this.model.create(query);
+  }
+  /**
+   * 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
+   */
+  async createMany(data) {
+    const query = { ...this.query, data };
+    return this.model.createMany(query);
+  }
+  /**
+   * 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
+   */
+  async delete(args) {
+    const query = args ? { ...this.query, ...args } : this.query;
+    return this.model.delete(query);
+  }
+  /**
+   * 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
+   */
+  async deleteMany(args) {
+    const query = args ? { ...this.query, ...args } : this.query;
+    return this.model.deleteMany(query);
+  }
+  /**
+   * 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
+   */
+  async update(data) {
+    const query = { ...this.query, data };
+    return this.model.update(query);
+  }
+  /**
+   * 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
+   */
+  async updateMany(data) {
+    const query = { ...this.query, data };
+    return this.model.updateMany(query);
+  }
+  /**
+   * 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
+   */
+  async upsert(args) {
+    const query = args ? { ...this.query, ...args } : this.query;
+    return this.model.upsert(query);
+  }
+  /**
+   * Counts the number of records matching the query
+   */
+  async count() {
+    return this.model.count(this.query);
+  }
+  /**
+   * Sums the specified numeric field
+   * @param field - Field name to sum
+   */
+  async sum(field) {
+    const result = await this.model.aggregate({
+      _sum: { [field]: true },
+      where: this.query.where
+    });
+    return result._sum[field];
+  }
+  /**
+   * Calculates the average of the specified numeric field
+   * @param field - Field name to average
+   */
+  async avg(field) {
+    const result = await this.model.aggregate({
+      _avg: { [field]: true },
+      where: this.query.where
+    });
+    return result._avg[field];
+  }
+  /**
+   * Finds the minimum value of the specified field
+   * @param field - Field name to find minimum
+   */
+  async min(field) {
+    const result = await this.model.aggregate({
+      _min: { [field]: true },
+      where: this.query.where
+    });
+    return result._min[field];
+  }
+  /**
+   * Finds the maximum value of the specified field
+   * @param field - Field name to find maximum
+   */
+  async max(field) {
+    const result = await this.model.aggregate({
+      _max: { [field]: true },
+      where: this.query.where
+    });
+    return result._max[field];
+  }
+  /**
+   * Plucks the specified field from all results
+   * @param field - Field name to pluck
+   */
+  async pluck(field) {
+    this.query.select = { [field]: true };
+    const results = await this.model.findMany(this.query);
+    return results.map((result) => result[field]);
+  }
+};
+export {
+  FlareBuilder as default
+};