stabilize-orm 1.1.3 → 1.1.4

package/repository.ts

@@ -1,14 +1,18 @@
+/**
+ * @file repository.ts
+ * @description Provides a data access layer for a specific model, handling all CRUD operations.
+ * @author ElectronSz
+ */
+
 import { Cache } from "./cache";
 import { DBClient } from "./client";
 import { ConsoleLogger, type Logger } from "./logger";
 import { QueryBuilder } from "./query-builder";
-// DBConfig added to the type imports
 import {
   DBType,
   RelationType,
   StabilizeError,
   type CacheConfig,
-  type DBConfig,
 } from "./types";
 import {
   ModelKey,
@@ -18,8 +22,13 @@ import {
   SoftDeleteKey,
 } from "./decorators";
 
+/**
+ * Provides a generic repository for a model `T`.
+ * This class abstracts the database interactions for a specific model,
+ * offering methods for creating, reading, updating, and deleting records.
+ * @template T The model entity type.
+ */
 export class Repository<T> {
-  // Client remains DBClient type
   private client: DBClient;
   private cache: Cache | null;
   private table: string;
@@ -38,6 +47,13 @@ export class Repository<T> {
   private softDeleteField: string | null;
   private logger: Logger;
 
+  /**
+   * Creates an instance of Repository.
+   * @param client The database client instance for executing queries.
+   * @param model The model class constructor, decorated with `@Model`.
+   * @param cacheConfig Optional configuration for caching.
+   * @param logger A logger instance for logging messages.
+   */
   constructor(
     client: DBClient,
     model: new (...args: any[]) => T,
@@ -55,10 +71,22 @@ export class Repository<T> {
     this.logger = logger;
   }
 
-  private getDBType(): DBType {
-    return (this.client as any).config.type;
+  /**
+   * @internal
+   * Gets the database type from the client's configuration.
+   * @param _client An optional client instance (used in transactions).
+   * @returns The `DBType` enum for the current database.
+   */
+  private getDBType(_client?: DBClient): DBType {
+    const client = _client || this.client;
+    return client.config.type;
   }
 
+  /**
+   * @internal
+   * Validates an entity against the 'required' constraints defined in decorators.
+   * @param entity The partial entity to validate.
+   */
   private validate(entity: Partial<T>) {
     for (const [key, rules] of Object.entries(this.validators)) {
       const value = (entity as any)[key];
@@ -71,12 +99,18 @@ export class Repository<T> {
           "VALIDATION_ERROR",
         );
       }
-      if (rules.includes("unique")) {
-        // Defer unique check to DB
-      }
     }
   }
 
+  /**
+   * Creates a new `QueryBuilder` instance for the repository's table.
+   * Automatically adds a `WHERE` clause to exclude soft-deleted records if applicable.
+   * @returns A `QueryBuilder` instance for constructing a query.
+   * @example
+   * ```
+   * const activeUsersQuery = userRepository.find().where('status = ?', 'active');
+   * ```
+   */
   find(): QueryBuilder<T> {
     const qb = new QueryBuilder<T>(this.table);
     if (this.softDeleteField) {
@@ -85,10 +119,23 @@ export class Repository<T> {
     return qb;
   }
 
+  /**
+   * Finds a single record by its primary key (id).
+   * @param id The ID of the record to find.
+   * @param options Optional: Specify relations to load.
+   * @param _client Optional: An internal client for transactions.
+   * @returns A promise that resolves to the entity or `null` if not found.
+   * @example
+   * ```
+   * const user = await userRepository.findOne(1);
+   * ```
+   */
   async findOne(
     id: number | string,
     options: { relations?: string[] } = {},
+    _client?: DBClient,
   ): Promise<T | null> {
+    const client = _client || this.client;
     const start = performance.now();
     this.logger.logDebug(`Finding one ${this.table} with ID ${id}`);
     const queryBuilder = this.find().where("id = ?", id).limit(1);
@@ -97,357 +144,410 @@ export class Repository<T> {
         await this.loadRelation(queryBuilder, rel);
       }
     }
-    const cacheKey = options.relations
-      ? `findOne:${this.table}:${id}:${options.relations.join(",")}`
-      : `findOne:${this.table}:${id}`;
-    const results = await queryBuilder.execute(
-      this.client,
-      this.cache!,
-      cacheKey,
-    );
+    const cacheKey = `findOne:${this.table}:${id}:${options.relations?.join(",")}`;
+    const results = await queryBuilder.execute(client, this.cache!, cacheKey);
     this.logger.logDebug(
       `Found ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
     );
     return results[0] || null;
   }
 
+  /**
+   * Creates a new record in the database within a transaction.
+   * @param entity The data for the new record.
+   * @param options Optional: Specify relations to load on the returned entity.
+   * @returns A promise that resolves to the newly created entity.
+   * @example
+   * ```
+   * const newUser = await userRepository.create({ name: 'Ciniso Dlamini', email: 'lwazicd@icloud.com' });
+   * ```
+   */
   async create(
     entity: Partial<T>,
     options: { relations?: string[] } = {},
+  ): Promise<T> {
+    return this.client.transaction((txClient) =>
+      this._create(entity, options, txClient),
+    );
+  }
+
+  /**
+   * @internal
+   * The private implementation for creating a record, executed within a transaction.
+   */
+  private async _create(
+    entity: Partial<T>,
+    options: { relations?: string[] },
+    client: DBClient,
   ): Promise<T> {
     const start = performance.now();
     this.logger.logDebug(
       `Creating ${this.table} with data: ${JSON.stringify(entity)}`,
     );
     this.validate(entity);
-    return await this.client.transaction(async () => {
-      const keys = Object.keys(entity).filter((k) => this.columns[k]);
-      const columnNames = keys.map((k) => this.columns[k]?.name).join(", ");
-      const placeholders = keys.map(() => "?").join(", ");
-      const params = keys.map((k) => (entity as any)[k]);
 
-      let query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders})`;
-      let insertedResult: T[] | undefined;
-      let id: number | string | undefined;
+    const keys = Object.keys(entity).filter((k) => this.columns[k]);
+    const columnNames = keys.map((k) => this.columns[k]?.name).join(", ");
+    const placeholders = keys.map(() => "?").join(", ");
+    const params = keys.map((k) => (entity as any)[k]);
+    let query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders})`;
 
-      const dbType = this.getDBType();
+    let insertedResult: T[] | undefined;
+    let id: number | string | undefined;
+    const dbType = this.getDBType(client);
 
-      if (dbType === DBType.Postgres) {
-        query += " RETURNING *";
-        insertedResult = await this.client.query<T>(query, params);
-        id = (insertedResult?.[0] as any)?.id;
-      } else {
-        await this.client.query(query, params);
-
-        if (dbType === DBType.SQLite) {
-          id = (
-            await this.client.query<{ id: number }>(
-              "SELECT last_insert_rowid() as id",
-              [],
-            )
-          )[0]?.id;
-        } else if (dbType === DBType.MySQL) {
-          id = (
-            await this.client.query<{ id: number }>(
-              "SELECT LAST_INSERT_ID() as id",
-              [],
-            )
-          )[0]?.id;
-        }
+    if (dbType === DBType.Postgres) {
+      query += " RETURNING *";
+      insertedResult = await client.query<T>(query, params);
+      id = (insertedResult?.[0] as any)?.id;
+    } else {
+      await client.query(query, params);
+      if (dbType === DBType.SQLite) {
+        id = (await client.query<{ id: number }>("SELECT last_insert_rowid() as id"))[0]?.id;
+      } else if (dbType === DBType.MySQL) {
+        const result = await client.query<{ "LAST_INSERT_ID()": number }>("SELECT LAST_INSERT_ID()");
+        id = result[0]?.["LAST_INSERT_ID()"];
       }
+    }
 
-      if (!id)
-        throw new StabilizeError(
-          "Failed to retrieve inserted ID",
-          "INSERT_ERROR",
-        );
-
-      const cacheKeys = [`find:${this.table}`, `findOne:${this.table}:${id}`];
+    if (!id) throw new StabilizeError("Failed to retrieve inserted ID", "INSERT_ERROR");
 
-      const queryBuilder = this.find().where("id = ?", id);
-      if (options.relations) {
-        for (const rel of options.relations) {
-          await this.loadRelation(queryBuilder, rel);
-        }
-      }
+    const result = insertedResult?.[0] ?? ((await this.findOne(id, options, client)) as T);
 
-      // If we are using write-through cache, we fetch the result now and cache it.
-      if (this.cache) {
-        await this.cache.invalidate(cacheKeys);
-        if (this.cache.getStrategy() === "write-through") {
-          // Fetch the full result for write-through cache, explicitly casting to T.
-          const result = (insertedResult?.[0] ||
-            (await queryBuilder.execute(this.client))[0]) as T;
-          await this.cache.set(`findOne:${this.table}:${id}`, [result], 60);
-          this.logger.logDebug(
-            `Created ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
-          );
-          return result;
-        }
+    if (this.cache) {
+      const cacheKeys = [`find:${this.table}`, `findOne:${this.table}:${id}`];
+      await this.cache.invalidate(cacheKeys);
+      if (this.cache.getStrategy() === "write-through") {
+        await this.cache.set(`findOne:${this.table}:${id}`, [result], 60);
       }
+    }
 
-      const result = (insertedResult?.[0] ||
-        (await queryBuilder.execute(this.client))[0]) as T;
-      this.logger.logDebug(
-        `Created ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
-      );
-      return result;
-    });
+    this.logger.logDebug(
+      `Created ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
+    );
+    return result;
   }
-
+  
+  /**
+   * Creates multiple records in the database in batches.
+   * @param entities An array of entities to create.
+   * @param options Optional: Specify relations or batch size.
+   * @returns A promise that resolves to an array of the newly created entities.
+   * @example
+   * ```
+   * const newUsers = await userRepository.bulkCreate([
+   *   { name: 'Ciniso' },
+   *   { name: 'Lwazi' }
+   * ]);
+   * ```
+   */
   async bulkCreate(
     entities: Partial<T>[],
     options: { relations?: string[]; batchSize?: number } = {},
+  ): Promise<T[]> {
+    return this.client.transaction((txClient) =>
+      this._bulkCreate(entities, options, txClient),
+    );
+  }
+
+  /**
+   * @internal
+   * The private implementation for bulk creating records, executed within a transaction.
+   */
+  private async _bulkCreate(
+    entities: Partial<T>[],
+    options: { relations?: string[]; batchSize?: number },
+    client: DBClient,
   ): Promise<T[]> {
     const start = performance.now();
     this.logger.logDebug(
       `Bulk creating ${entities.length} ${this.table} entities`,
     );
     if (!entities.length) return [];
+
     const batchSize = options.batchSize || 1000;
     entities.forEach((entity) => this.validate(entity));
 
-    const dbType = this.getDBType();
+    const dbType = this.getDBType(client);
     const results: T[] = [];
 
     for (let i = 0; i < entities.length; i += batchSize) {
       const batch = entities.slice(i, i + batchSize);
-      await this.client.transaction(async () => {
-        const keys = Object.keys(batch[0]!).filter((k) => this.columns[k]);
-        const columnNames = keys.map((k) => this.columns[k]?.name).join(", ");
-        const placeholders = `(${keys.map(() => "?").join(", ")})`;
-        let query = `INSERT INTO ${this.table} (${columnNames}) VALUES ${batch.map(() => placeholders).join(", ")}`;
-        const params = batch.flatMap((entity) =>
-          keys.map((k) => (entity as any)[k]),
-        );
+      const keys = Object.keys(batch[0]!).filter((k) => this.columns[k]);
+      const columnNames = keys.map((k) => this.columns[k]?.name).join(", ");
+      const placeholders = `(${keys.map(() => "?").join(", ")})`;
+      let query = `INSERT INTO ${this.table} (${columnNames}) VALUES ${batch.map(() => placeholders).join(", ")}`;
+      const params = batch.flatMap((entity) =>
+        keys.map((k) => (entity as any)[k]),
+      );
 
-        let batchResults: T[] = [];
-        let ids: (number | string)[] = [];
-
-        if (dbType === DBType.Postgres) {
-          // PostgreSQL supports RETURNING * for multiple inserts
-          query += " RETURNING *";
-          batchResults = await this.client.query<T>(query, params);
-          ids = batchResults.map((r) => (r as any).id);
-        } else {
-          // SQLite/MySQL batch insert. ID retrieval remains complex.
-          await this.client.query(query, params);
-
-          // Unreliable ID retrieval kept for consistency, but should be reviewed for concurrency
-          ids = (
-            await this.client.query<{ id: number }>(
-              `SELECT id FROM ${this.table} ORDER BY id DESC LIMIT ?`,
-              [batch.length],
-            )
-          ).map((row) => row.id);
-        }
+      let batchResults: T[] = [];
+      let ids: (number | string)[] = [];
 
-        const cacheKeys = ids
-          .map((id) => `findOne:${this.table}:${id}`)
-          .concat(`find:${this.table}`);
-
-        // If batchResults is empty (non-PostgreSQL), we need to fetch the full records.
-        if (ids.length > 0 && batchResults.length === 0) {
-          const queryBuilder = this.find().where(
-            `id IN (${ids.map(() => "?").join(", ")})`,
-            ...ids,
-          );
-          if (options.relations) {
-            for (const rel of options.relations) {
-              await this.loadRelation(queryBuilder, rel);
-            }
-          }
-          batchResults = await queryBuilder.execute(this.client);
-        }
+      if (dbType === DBType.Postgres) {
+        query += " RETURNING *";
+        batchResults = await client.query<T>(query, params);
+        ids = batchResults.map((r) => (r as any).id);
+      } else {
+        await client.query(query, params);
+        ids = (
+          await client.query<{ id: number }>(
+            `SELECT id FROM ${this.table} ORDER BY id DESC LIMIT ?`,
+            [batch.length],
+          )
+        ).map((row) => row.id);
+      }
 
-        if (this.cache) {
-          await this.cache.invalidate(cacheKeys);
-          if (this.cache.getStrategy() === "write-through") {
-            await this.cache.set(
-              `bulkCreate:${this.table}:${ids.join(",")}`,
-              batchResults,
-              60,
-            );
+      if (ids.length > 0 && batchResults.length === 0) {
+        const queryBuilder = this.find().where(
+          `id IN (${ids.map(() => "?").join(", ")})`,
+          ...ids,
+        );
+        if (options.relations) {
+          for (const rel of options.relations) {
+            await this.loadRelation(queryBuilder, rel);
           }
         }
-        results.push(...batchResults);
-      });
+        batchResults = await queryBuilder.execute(client);
+      }
+
+      results.push(...batchResults);
     }
+    
+    if (this.cache) await this.cache.invalidatePattern(`find:${this.table}:*`);
+    
     this.logger.logDebug(
       `Bulk created ${results.length} ${this.table} entities in ${(performance.now() - start).toFixed(2)}ms`,
     );
     return results;
   }
 
+  /**
+   * Updates a record by its ID within a transaction.
+   * @param id The ID of the record to update.
+   * @param entity An object containing the fields to update.
+   * @returns A promise that resolves to the updated entity.
+   * @example
+   * ```
+   * const updatedUser = await userRepository.update(1, { name: 'Ciniso Dlamini' });
+   * ```
+   */
   async update(id: number | string, entity: Partial<T>): Promise<T> {
+    return this.client.transaction((txClient) =>
+      this._update(id, entity, txClient),
+    );
+  }
+
+  /**
+   * @internal
+   * The private implementation for updating a record, executed within a transaction.
+   */
+  private async _update(
+    id: number | string,
+    entity: Partial<T>,
+    client: DBClient,
+  ): Promise<T> {
     const start = performance.now();
     this.logger.logDebug(`Updating ${this.table} with ID ${id}`);
     this.validate(entity);
-    return await this.client.transaction(async () => {
-      const keys = Object.keys(entity).filter((k) => this.columns[k]);
-      const setClause = keys
-        .map((k) => `${this.columns[k]?.name} = ?`)
-        .join(", ");
-      const query = `UPDATE ${this.table} SET ${setClause} WHERE id = ?${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
-      const params = [...keys.map((k) => (entity as any)[k]), id];
-      await this.client.query(query, params);
 
-      let result: T;
+    const keys = Object.keys(entity).filter((k) => this.columns[k]);
+    const setClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(", ");
+    const query = `UPDATE ${this.table} SET ${setClause} WHERE id = ?${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
+    const params = [...keys.map((k) => (entity as any)[k]), id];
+    await client.query(query, params);
 
+    const result = await this.findOne(id, {}, client);
+    if (!result) throw new StabilizeError("Failed to find updated record.", "UPDATE_ERROR");
+
+    if (this.cache) {
       const cacheKeys = [`find:${this.table}`, `findOne:${this.table}:${id}`];
-      if (this.cache) {
-        await this.cache.invalidate(cacheKeys);
-        if (this.cache.getStrategy() === "write-through") {
-          const queryBuilder = this.find().where("id = ?", id);
-          // Fetch the result and explicitly cast to T to satisfy the return type.
-          result = (await queryBuilder.execute(this.client))[0] as T;
-          await this.cache.set(`findOne:${this.table}:${id}`, [result], 60);
-          this.logger.logDebug(
-            `Updated ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
-          );
-          return result;
-        }
+      await this.cache.invalidate(cacheKeys);
+      if (this.cache.getStrategy() === "write-through") {
+        await this.cache.set(`findOne:${this.table}:${id}`, [result], 60);
       }
+    }
 
-      // Fetch the result and explicitly cast to T. Logically, since we just updated the record, it must exist.
-      result = (await this.findOne(id)) as T;
-      this.logger.logDebug(
-        `Updated ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
-      );
-      return result;
-    });
+    this.logger.logDebug(
+      `Updated ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
+    );
+    return result;
   }
 
+  /**
+   * Updates multiple records based on different conditions.
+   * @param updates An array of update operations, each with a `where` and `set` clause.
+   * @param options Optional: Specify batch size.
+   * @returns A promise that resolves when the operation is complete.
+   * @example
+   * ```
+   * await userRepository.bulkUpdate([
+   *   { where: { condition: 'id = ?', params: [1] }, set: { status: 'inactive' } },
+   *   { where: { condition: 'id = ?', params: [2] }, set: { status: 'inactive' } }
+   * ]);
+   * ```
+   */
   async bulkUpdate(
     updates: { where: { condition: string; params: any[] }; set: Partial<T> }[],
     options: { batchSize?: number } = {},
+  ): Promise<void> {
+    return this.client.transaction((txClient) =>
+      this._bulkUpdate(updates, options, txClient),
+    );
+  }
+
+  /**
+   * @internal
+   * The private implementation for bulk updating records, executed within a transaction.
+   */
+  private async _bulkUpdate(
+    updates: { where: { condition: string; params: any[] }; set: Partial<T> }[],
+    options: { batchSize?: number },
+    client: DBClient,
   ): Promise<void> {
     const start = performance.now();
     this.logger.logDebug(
       `Bulk updating ${updates.length} ${this.table} entities`,
     );
     if (!updates.length) return;
+
     const batchSize = options.batchSize || 1000;
     updates.forEach((update) => this.validate(update.set));
 
     for (let i = 0; i < updates.length; i += batchSize) {
       const batch = updates.slice(i, i + batchSize);
-      await this.client.transaction(async () => {
-        for (const update of batch) {
-          const keys = Object.keys(update.set).filter((k) => this.columns[k]);
-          const setClause = keys
-            .map((k) => `${this.columns[k]?.name} = ?`)
-            .join(", ");
-          const query = `UPDATE ${this.table} SET ${setClause} WHERE ${update.where.condition}${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
-          const params = [
-            ...keys.map((k) => (update.set as any)[k]),
-            ...update.where.params,
-          ];
-          await this.client.query(query, params);
-        }
-        if (this.cache) {
-          await this.cache.invalidatePattern(`find:${this.table}:*`);
-        }
-      });
+      for (const update of batch) {
+        const keys = Object.keys(update.set).filter((k) => this.columns[k]);
+        const setClause = keys.map((k) => `${this.columns[k]?.name} = ?`).join(", ");
+        const query = `UPDATE ${this.table} SET ${setClause} WHERE ${update.where.condition}${this.softDeleteField ? ` AND ${this.softDeleteField} IS NULL` : ""}`;
+        const params = [
+          ...keys.map((k) => (update.set as any)[k]),
+          ...update.where.params,
+        ];
+        await client.query(query, params);
+      }
     }
+
+    if (this.cache) await this.cache.invalidatePattern(`find:${this.table}:*`);
+
     this.logger.logDebug(
       `Bulk updated ${updates.length} ${this.table} entities in ${(performance.now() - start).toFixed(2)}ms`,
     );
   }
 
+  /**
+   * Performs an "update or insert" operation based on a set of unique keys.
+   * @param entity The entity to upsert.
+   * @param keys The list of key names that uniquely identify a record.
+   * @returns A promise that resolves to the upserted entity.
+   * @example
+   * ```
+   * const user = await userRepository.upsert({ email: 'lwazicd@icloud.com', name: 'Lwazi' }, ['email']);
+   * ```
+   */
   async upsert(entity: Partial<T>, keys: string[]): Promise<T> {
+    return this.client.transaction((txClient) =>
+      this._upsert(entity, keys, txClient),
+    );
+  }
+
+  /**
+   * @internal
+   * The private implementation for an upsert operation, executed within a transaction.
+   */
+  private async _upsert(
+    entity: Partial<T>,
+    keys: string[],
+    client: DBClient,
+  ): Promise<T> {
     const start = performance.now();
     this.logger.logDebug(
       `Upserting ${this.table} with keys: ${keys.join(", ")}`,
     );
     this.validate(entity);
-    return await this.client.transaction(async () => {
-      const dbType = this.getDBType();
-      const columns = Object.keys(entity).filter((k) => this.columns[k]);
-      const columnNames = columns.map((k) => this.columns[k]?.name).join(", ");
-      const placeholders = columns.map(() => "?").join(", ");
-      const updateClause = columns
+
+    const dbType = this.getDBType(client);
+    const columns = Object.keys(entity).filter((k) => this.columns[k]);
+    const columnNames = columns.map((k) => this.columns[k]?.name).join(", ");
+    const placeholders = columns.map(() => "?").join(", ");
+    const updateClause = columns
+      .filter((c) => !keys.includes(c))
+      .map((c) => `${this.columns[c]?.name} = ?`).join(", ");
+
+    let query: string;
+    const updateParams = columns.filter((c) => !keys.includes(c)).map((k) => (entity as any)[k]);
+    const insertParams = columns.map((k) => (entity as any)[k]);
+    let params = [...insertParams, ...updateParams];
+
+    if (dbType === DBType.SQLite) {
+      query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders}) ON CONFLICT(${keys.map((k) => this.columns[k]!.name).join(", ")}) DO UPDATE SET ${updateClause}`;
+    } else if (dbType === DBType.MySQL) {
+      query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders}) ON DUPLICATE KEY UPDATE ${updateClause}`;
+    } else { // PostgreSQL
+      const pgUpdateClause = columns
         .filter((c) => !keys.includes(c))
-        .map((c) => `${this.columns[c]?.name} = ?`)
-        .join(", ");
+        .map((c) => `${this.columns[c]?.name} = EXCLUDED.${this.columns[c]?.name}`).join(", ");
+      query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders}) ON CONFLICT (${keys.map((k) => this.columns[k]!.name).join(", ")}) DO UPDATE SET ${pgUpdateClause} RETURNING *`;
+      params = insertParams;
+    }
 
-      let query: string;
+    const results = await client.query<T>(query, params);
+    let id: number | string | undefined = (results[0] as any)?.id || (entity as any).id;
 
-      if (dbType === DBType.SQLite) {
-        query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders}) ON CONFLICT(${keys.map((k) => this.columns[k]!.name).join(", ")}) DO UPDATE SET ${updateClause}`;
+    if (!id && dbType !== DBType.Postgres) {
+       if (dbType === DBType.SQLite) {
+        id = (await client.query<{ id: number }>("SELECT last_insert_rowid() as id"))[0]?.id;
       } else if (dbType === DBType.MySQL) {
-        query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders}) ON DUPLICATE KEY UPDATE ${updateClause}`;
-      } else {
-        // PostgreSQL and default
-        query = `INSERT INTO ${this.table} (${columnNames}) VALUES (${placeholders}) ON CONFLICT (${keys.map((k) => this.columns[k]!.name).join(", ")}) DO UPDATE SET ${updateClause} RETURNING *`;
+        const result = await client.query<{ "LAST_INSERT_ID()": number }>("SELECT LAST_INSERT_ID()");
+        id = result[0]?.["LAST_INSERT_ID()"];
       }
+    }
 
-      const params = [
-        ...columns.map((k) => (entity as any)[k]),
-        ...columns
-          .filter((c) => !keys.includes(c))
-          .map((k) => (entity as any)[k]),
-      ];
-      const results = await this.client.query<T>(query, params);
-
-      let id: number | string | undefined =
-        (results[0] as any)?.id || (entity as any).id;
-
-      // Fallback ID retrieval for non-PostgreSQL if the driver didn't return it
-      if (!id && dbType === DBType.SQLite) {
-        id = (
-          await this.client.query<{ id: number }>(
-            "SELECT last_insert_rowid() as id",
-            [],
-          )
-        )[0]?.id;
-      } else if (!id && dbType === DBType.MySQL) {
-        id = (
-          await this.client.query<{ id: number }>(
-            "SELECT LAST_INSERT_ID() as id",
-            [],
-          )
-        )[0]?.id;
-      }
+    if (!id) throw new StabilizeError("Failed to retrieve upserted ID", "UPSERT_ERROR");
 
-      if (!id)
-        throw new StabilizeError(
-          "Failed to retrieve upserted ID",
-          "UPSERT_ERROR",
-        );
+    const result = results[0] ?? ((await this.findOne(id, {}, client)) as T);
 
-      if (this.cache) {
-        await this.cache.invalidatePattern(`find:${this.table}:*`);
-        if (this.cache.getStrategy() === "write-through") {
-          const queryBuilder = this.find().where("id = ?", id);
-          const result = (await queryBuilder.execute(this.client))[0] as T;
-          await this.cache.set(`findOne:${this.table}:${id}`, [result], 60);
-          this.logger.logDebug(
-            `Upserted ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
-          );
-          return result;
-        }
+    if (this.cache) {
+      await this.cache.invalidatePattern(`find:${this.table}:*`);
+      if (this.cache.getStrategy() === "write-through") {
+        await this.cache.set(`findOne:${this.table}:${id}`, [result], 60);
       }
-
-      const result = (await this.findOne(id)) as T;
-      this.logger.logDebug(
-        `Upserted ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
-      );
-      return result;
-    });
+    }
+    
+    this.logger.logDebug(
+      `Upserted ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
+    );
+    return result;
   }
 
+  /**
+   * Deletes a record by its ID. Performs a soft delete if enabled on the model.
+   * @param id The ID of the record to delete.
+   * @returns A promise that resolves when the operation is complete.
+   * @example
+   * ```
+   * await userRepository.delete(1);
+   * ```
+   */
   async delete(id: number | string): Promise<void> {
+    return this.client.transaction((txClient) => this._delete(id, txClient));
+  }
+
+  /**
+   * @internal
+   * The private implementation for deleting a record, executed within a transaction.
+   */
+  private async _delete(id: number | string, client: DBClient): Promise<void> {
     const start = performance.now();
     this.logger.logDebug(`Deleting ${this.table} with ID ${id}`);
-    if (this.softDeleteField) {
-      await this.client.query(
-        `UPDATE ${this.table} SET ${this.softDeleteField} = ? WHERE id = ?`,
-        [new Date().toISOString(), id],
-      );
-    } else {
-      await this.client.query(`DELETE FROM ${this.table} WHERE id = ?`, [id]);
-    }
+
+    const query = this.softDeleteField
+      ? `UPDATE ${this.table} SET ${this.softDeleteField} = ? WHERE id = ?`
+      : `DELETE FROM ${this.table} WHERE id = ?`;
+    const params = this.softDeleteField ? [new Date().toISOString(), id] : [id];
+    
+    await client.query(query, params);
+
     if (this.cache) {
       await this.cache.invalidate([
         `find:${this.table}`,
@@ -459,37 +559,77 @@ export class Repository<T> {
     );
   }
 
+  /**
+   * Deletes multiple records by their IDs in batches.
+   * @param ids An array of IDs to delete.
+   * @param options Optional: Specify batch size.
+   * @returns A promise that resolves when the operation is complete.
+   * @example
+   * ```
+   * await userRepository.bulkDelete([1, 2, 3]);
+   * ```
+   */
   async bulkDelete(
     ids: (number | string)[],
     options: { batchSize?: number } = {},
+  ): Promise<void> {
+    return this.client.transaction((txClient) =>
+      this._bulkDelete(ids, options, txClient),
+    );
+  }
+
+  /**
+   * @internal
+   * The private implementation for bulk deleting records, executed within a transaction.
+   */
+  private async _bulkDelete(
+    ids: (number | string)[],
+    options: { batchSize?: number },
+    client: DBClient,
   ): Promise<void> {
     const start = performance.now();
     this.logger.logDebug(`Bulk deleting ${ids.length} ${this.table} entities`);
     if (!ids.length) return;
-    const batchSize = options.batchSize || 1000;
 
+    const batchSize = options.batchSize || 1000;
     for (let i = 0; i < ids.length; i += batchSize) {
       const batch = ids.slice(i, i + batchSize);
-      await this.client.transaction(async () => {
-        const placeholders = batch.map(() => "?").join(", ");
-        const query = this.softDeleteField
-          ? `UPDATE ${this.table} SET ${this.softDeleteField} = ? WHERE id IN (${placeholders})`
-          : `DELETE FROM ${this.table} WHERE id IN (${placeholders})`;
-        const params = this.softDeleteField
-          ? [new Date().toISOString(), ...batch]
-          : batch;
-        await this.client.query(query, params);
-      });
-    }
-    if (this.cache) {
-      await this.cache.invalidatePattern(`find:${this.table}:*`);
+      const placeholders = batch.map(() => "?").join(", ");
+      const query = this.softDeleteField
+        ? `UPDATE ${this.table} SET ${this.softDeleteField} = ? WHERE id IN (${placeholders})`
+        : `DELETE FROM ${this.table} WHERE id IN (${placeholders})`;
+      const params = this.softDeleteField
+        ? [new Date().toISOString(), ...batch]
+        : batch;
+      await client.query(query, params);
     }
+
+    if (this.cache) await this.cache.invalidatePattern(`find:${this.table}:*`);
+
     this.logger.logDebug(
       `Bulk deleted ${ids.length} ${this.table} entities in ${(performance.now() - start).toFixed(2)}ms`,
     );
   }
 
+  /**
+   * Recovers a soft-deleted record by its ID.
+   * Throws an error if soft delete is not enabled on the model.
+   * @param id The ID of the record to recover.
+   * @returns A promise that resolves to the recovered entity.
+   * @example
+   * ```
+   * const recoveredUser = await userRepository.recover(1);
+   * ```
+   */
   async recover(id: number | string): Promise<T> {
+    return this.client.transaction((txClient) => this._recover(id, txClient));
+  }
+
+  /**
+   * @internal
+   * The private implementation for recovering a record, executed within a transaction.
+   */
+  private async _recover(id: number | string, client: DBClient): Promise<T> {
     const start = performance.now();
     this.logger.logDebug(`Recovering ${this.table} with ID ${id}`);
     if (!this.softDeleteField) {
@@ -498,25 +638,39 @@ export class Repository<T> {
         "RECOVER_ERROR",
       );
     }
-    return await this.client.transaction(async () => {
-      await this.client.query(
-        `UPDATE ${this.table} SET ${this.softDeleteField} = NULL WHERE id = ?`,
-        [id],
-      );
-      if (this.cache) {
-        await this.cache.invalidate([
-          `find:${this.table}`,
-          `findOne:${this.table}:${id}`,
-        ]);
-      }
-      const result = (await this.findOne(id))!;
-      this.logger.logDebug(
-        `Recovered ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
-      );
-      return result;
-    });
+    
+    await client.query(
+      `UPDATE ${this.table} SET ${this.softDeleteField} = NULL WHERE id = ?`,
+      [id],
+    );
+
+    const result = await this.findOne(id, {}, client);
+    if (!result) throw new StabilizeError("Failed to find recovered record.", "RECOVER_ERROR");
+
+    if (this.cache) {
+      await this.cache.invalidate([
+        `find:${this.table}`,
+        `findOne:${this.table}:${id}`,
+      ]);
+    }
+    
+    this.logger.logDebug(
+      `Recovered ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
+    );
+    return result;
   }
 
+  /**
+   * Executes a raw SQL query directly against the database.
+   * Bypasses most ORM abstractions. Use with caution.
+   * @param query The raw SQL query string with `?` placeholders.
+   * @param params An array of parameters to bind to the query.
+   * @returns A promise that resolves to an array of results.
+   * @example
+   * ```
+   * const activeUsers = await userRepository.rawQuery('SELECT * FROM users WHERE status = ?', ['active']);
+   * ```
+   */
   async rawQuery<T>(query: string, params: any[] = []): Promise<T[]> {
     const start = performance.now();
     this.logger.logDebug(`Executing raw query: ${query}`);
@@ -527,6 +681,12 @@ export class Repository<T> {
     return result;
   }
 
+  /**
+   * @internal
+   * Loads a relation by adding the appropriate JOIN clause to a query builder.
+   * @param queryBuilder The `QueryBuilder` instance to modify.
+   * @param relation The name of the relation to load.
+   */
   private async loadRelation(queryBuilder: QueryBuilder<T>, relation: string) {
     this.logger.logDebug(`Loading relation ${relation} for ${this.table}`);
     const rel = this.relations[relation];
@@ -562,4 +722,4 @@ export class Repository<T> {
         );
     }
   }
-}
+}