tspace-mysql 1.9.0 → 1.9.1-beta.2

package/dist/lib/core/Builder.d.ts

@@ -3,8 +3,8 @@ import { DB } from "./DB";
 import { Join } from "./Join";
 import { CONSTANTS } from "../constants";
 import { QueryBuilder } from "./Driver";
-import { TPagination, TConnectionOptions, TPoolConnected, TConnectionTransaction } from "../types";
-declare class Builder extends AbstractBuilder {
+import type { TPagination, TConnectionOptions, TPoolConnected, TConnectionTransaction, TDriver, TSaveBuilderResult, TAction } from "../types";
+declare class Builder<TA extends TAction = null> extends AbstractBuilder {
     constructor();
     /**
      * The 'instance' method is used get instance.
@@ -14,21 +14,76 @@ declare class Builder extends AbstractBuilder {
     static get instance(): Builder;
     /**
      * The 'driver' method is used to get current driver
-     * @returns {string} driver
+     * @static
+     * @returns {TDriver} driver
+     */
+    static driver(): TDriver;
+    /**
+     * The 'driver' method is used to get current driver
+     * @returns {TDriver} driver
      */
-    driver(): string;
+    driver(): TDriver;
     /**
      * The 'database' method is used to get current database
      * @returns {string} database
      */
     database(): string;
     /**
-     * The 'rowLock' method is used to row level locks
+     * The 'rowLock' method is used to row level locks (`FOR UPDATE` or `FOR SHARE`) to the query.
      *
      * @param {string} mode
      * @returns {this} this
      */
-    rowLock(mode: "FOR_UPDATE" | "FOR_SHARE"): this;
+    rowLock(mode: "FOR_UPDATE" | "FOR_SHARE", opts?: {
+        skipLocked?: boolean;
+        nowait?: boolean;
+    }): this;
+    /**
+     * The 'forUpdate' method is used to applies a row-level exclusive lock (`FOR UPDATE`) to the query.
+     *
+     * This lock prevents other transactions from modifying or acquiring
+     * conflicting locks on the selected rows until the current transaction
+     * is committed or rolled back.
+     *
+     * Commonly used in queue systems or critical sections to safely
+     * select and update rows without race conditions.
+     *
+     * @param {Object} [opts] - Locking options
+     * @param {boolean} [opts.skipLocked=false] - If true, skips rows that are already locked by other transactions.
+     *                                           Useful for building non-blocking workers (e.g., job queues).
+     * @param {boolean} [opts.nowait=false] - If true, throws an error immediately if the lock cannot be acquired.
+     *
+     * @throws {Error} If both `skipLocked` and `nowait` are enabled at the same time.
+     *
+     * @returns {this} Returns the query builder instance for chaining.
+     */
+    forUpdate(opts?: {
+        skipLocked?: boolean;
+        nowait?: boolean;
+    }): this;
+    /**
+     * The 'forShare' method is used to applies a row-level exclusive lock (`FOR SHARE`) to the query.
+     *
+     * This lock prevents other transactions from modifying or acquiring
+     * conflicting locks on the selected rows until the current transaction
+     * is committed or rolled back.
+     *
+     * Commonly used in queue systems or critical sections to safely
+     * select and update rows without race conditions.
+     *
+     * @param {Object} [opts] - Locking options
+     * @param {boolean} [opts.skipLocked=false] - If true, skips rows that are already locked by other transactions.
+     *                                           Useful for building non-blocking workers (e.g., job queues).
+     * @param {boolean} [opts.nowait=false] - If true, throws an error immediately if the lock cannot be acquired.
+     *
+     * @throws {Error} If both `skipLocked` and `nowait` are enabled at the same time.
+     *
+     * @returns {this} Returns the query builder instance for chaining.
+     */
+    forShare(opts?: {
+        skipLocked?: boolean;
+        nowait?: boolean;
+    }): this;
     /**
      * The 'unset' method is used to drop a property as desired.
      * @param {object} options
@@ -80,6 +135,14 @@ declare class Builder extends AbstractBuilder {
      * @returns {this} this
      */
     select(...columns: string[]): this;
+    /**
+     * The 'addSelect' method is used to add columns you want to retrieve from a database table.
+     *
+     * It allows you to choose the specific columns that should be included in the result set of a database query.
+     * @param {string[]} ...columns
+     * @returns {this} this
+     */
+    addSelect(...columns: string[]): this;
     /**
      * The 'selectRaw' method is used to specify which columns you want to retrieve from a database table.
      *
@@ -106,7 +169,7 @@ declare class Builder extends AbstractBuilder {
      */
     selectObject(object: Record<string, string | `${string}.${string}`>, alias: string): this;
     /**
-     * The 'selectObject' method is used to specify which columns you want to retrieve from a database table.
+     * The 'selectArray' method is used to specify which columns you want to retrieve from a database table.
      *
      * It allows you to choose the specific columns that should be included in the result set to 'Object' of a database query.
      * @param {string} object table name
@@ -187,7 +250,7 @@ declare class Builder extends AbstractBuilder {
      * @param {string | number | undefined | null | Boolean} condition when condition true will return query callback
      * @returns {this} this
      */
-    when(condition: string | number | undefined | null | Boolean, callback: (query: Builder) => Builder): this;
+    when(condition: string | number | undefined | null | Boolean, callback: (query: Builder<any>) => Builder): this;
     /**
      * The 'where' method is used to add conditions to a database query.
      *
@@ -247,7 +310,7 @@ declare class Builder extends AbstractBuilder {
      * @param {string} sql where column with raw sql
      * @returns {this} this
      */
-    whereRaw(sql: string): this;
+    whereRaw(sql: string, parameters?: (boolean | number | string | any[] | null)[]): this;
     /**
      * The 'orWhereRaw' method is used to add a raw SQL condition to a database query.
      *
@@ -256,7 +319,7 @@ declare class Builder extends AbstractBuilder {
      * @param {string} sql where column with raw sql
      * @returns {this} this
      */
-    orWhereRaw(sql: string): this;
+    orWhereRaw(sql: string, parameters?: (boolean | number | string | any[] | null)[]): this;
     /**
      * The 'whereObject' method is used to add conditions to a database query.
      *
@@ -847,7 +910,7 @@ declare class Builder extends AbstractBuilder {
      * @param {array?} updateNotExists options for except update some records in your ${data} using name column(s)
      * @returns {this} this
      */
-    update(data: Record<string, any>, updateNotExists?: string[]): this;
+    update(data: Record<string, any>, updateNotExists?: string[]): Builder<"update">;
     /**
      * The 'updateMany' method is used to update existing records in a database table that are associated.
      *
@@ -858,7 +921,7 @@ declare class Builder extends AbstractBuilder {
      * @param {array?} updateNotExists options for except update some records in your ${data} using name column(s)
      * @returns {this} this
      */
-    updateMany(data: Record<string, any>, updateNotExists?: string[]): this;
+    updateMany(data: Record<string, any>, updateNotExists?: string[]): Builder<"updateMany">;
     /**
      * The 'updateCases' method is used to update records in a table based on specific conditions.
      *
@@ -881,7 +944,7 @@ declare class Builder extends AbstractBuilder {
     updateCases(cases: {
         condition: ((query: Builder) => Builder) | Record<string, any>;
         columns: Record<string, any>;
-    }[]): this;
+    }[]): Builder<"updateMany">;
     /**
      * The 'updateNotExists' method is used to update existing records in a database table that are associated.
      *
@@ -891,7 +954,7 @@ declare class Builder extends AbstractBuilder {
      * @param {object} data
      * @returns {this} this
      */
-    updateNotExists(data: Record<string, any>): this;
+    updateNotExists(data: Record<string, any>): Builder<'update'>;
     /**
      * The 'insert' method is used to insert a new record into a database table associated.
      *
@@ -899,7 +962,7 @@ declare class Builder extends AbstractBuilder {
      * @param {object} data
      * @returns {this} this
      */
-    insert(data: Record<string, any>): this;
+    insert(data: Record<string, any>): Builder<"create">;
     /**
      * The 'create' method is used to insert a new record into a database table associated.
      *
@@ -907,7 +970,7 @@ declare class Builder extends AbstractBuilder {
      * @param {object} data
      * @returns {this} this
      */
-    create(data: Record<string, any>): this;
+    create(data: Record<string, any>): Builder<"create">;
     /**
      * The 'createMultiple' method is used to insert a new records into a database table associated.
      *
@@ -915,7 +978,7 @@ declare class Builder extends AbstractBuilder {
      * @param {array} data create multiple data
      * @returns {this} this this
      */
-    createMultiple(data: any[]): this;
+    createMultiple(data: any[]): Builder<"createMany">;
     /**
      * The 'createMany' method is used to insert a new records into a database table associated.
      *
@@ -923,7 +986,7 @@ declare class Builder extends AbstractBuilder {
      * @param {array} data create multiple data
      * @returns {this} this this
      */
-    createMany(data: any[]): this;
+    createMany(data: any[]): Builder<"createMany">;
     /**
      * The 'insertMultiple' method is used to insert a new records into a database table associated.
      *
@@ -931,7 +994,7 @@ declare class Builder extends AbstractBuilder {
      * @param {array} data create multiple data
      * @returns {this} this this
      */
-    insertMultiple(data: any[]): this;
+    insertMultiple(data: any[]): Builder<"createMany">;
     /**
      * The 'insertMany' method is used to insert a new records into a database table associated.
      *
@@ -939,7 +1002,7 @@ declare class Builder extends AbstractBuilder {
      * @param {array} data create multiple data
      * @returns {this} this this
      */
-    insertMany(data: any[]): this;
+    insertMany(data: any[]): Builder<"createMany">;
     /**
      * The 'createNotExists' method to insert data into a database table while ignoring any duplicate key constraint violations.
      *
@@ -948,7 +1011,7 @@ declare class Builder extends AbstractBuilder {
      * @param {object} data create not exists data
      * @returns {this} this this
      */
-    createNotExists(data: Record<string, any>): this;
+    createNotExists(data: Record<string, any>): Builder<"create">;
     /**
      * The 'insertNotExists' method to insert data into a database table while ignoring any duplicate key constraint violations.
      *
@@ -959,7 +1022,7 @@ declare class Builder extends AbstractBuilder {
      */
     insertNotExists(data: Record<string, any> & {
         length?: never;
-    }): this;
+    }): Builder<"create">;
     /**
      * The 'createOrSelect' method to insert data into a database table while select any duplicate key constraint violations.
      *
@@ -970,7 +1033,7 @@ declare class Builder extends AbstractBuilder {
      */
     createOrSelect(data: Record<string, any> & {
         length?: never;
-    }): this;
+    }): Builder<'create'>;
     /**
      * The 'insertOrSelect' method to insert data into a database table while select any duplicate key constraint violations.
      *
@@ -981,7 +1044,7 @@ declare class Builder extends AbstractBuilder {
      */
     insertOrSelect(data: Record<string, any> & {
         length?: never;
-    }): this;
+    }): Builder<'create'>;
     /**
      * The 'updateOrCreate' method allows you to update an existing record in a database table if it exists or create a new record if it does not exist.
      *
@@ -992,7 +1055,7 @@ declare class Builder extends AbstractBuilder {
      */
     updateOrCreate(data: Record<string, any> & {
         length?: never;
-    }): this;
+    }): Builder<"createOrUpdate">;
     /**
      * The 'updateOrInsert' method allows you to update an existing record in a database table if it exists or create a new record if it does not exist.
      *
@@ -1003,7 +1066,7 @@ declare class Builder extends AbstractBuilder {
      */
     updateOrInsert(data: Record<string, any> & {
         length?: never;
-    }): this;
+    }): Builder<"createOrUpdate">;
     /**
      * The 'insertOrUpdate' method allows you to update an existing record in a database table if it exists or create a new record if it does not exist.
      *
@@ -1014,7 +1077,7 @@ declare class Builder extends AbstractBuilder {
      */
     insertOrUpdate(data: Record<string, any> & {
         length?: never;
-    }): this;
+    }): Builder<"createOrUpdate">;
     /**
      *
      * The 'createOrUpdate' method allows you to update an existing record in a database table if it exists or create a new record if it does not exist.
@@ -1026,7 +1089,7 @@ declare class Builder extends AbstractBuilder {
      */
     createOrUpdate(data: Record<string, any> & {
         length?: never;
-    }): this;
+    }): Builder<"createOrUpdate">;
     /**
      * The 'toString' method is used to retrieve the raw SQL query that would be executed by a query builder instance without actually executing it.
      *
@@ -1162,6 +1225,40 @@ declare class Builder extends AbstractBuilder {
         ParentTable: string;
         ParentColumn: string;
     }[]>;
+    /**
+     * Adds a foreign key constraint to a table.
+     *
+     * This method checks whether the specified foreign key constraint already exists
+     * on the table before attempting to create it. If the constraint exists, an error
+     * will be thrown to prevent duplication.
+     *
+     * @async
+     * @method addFK
+     * @param {Object} params - Parameters for creating the foreign key.
+     * @param {string} params.table - The name of the table where the foreign key will be added.
+     * @param {string} params.tableRef - The referenced table name.
+     * @param {string} params.key - The column in the current table that will act as the foreign key.
+     * @param {string} params.constraint - The name of the foreign key constraint.
+     * @param {Object} params.foreign - Foreign key configuration.
+     * @param {string} params.foreign.references - The referenced column in the referenced table.
+     * @param {string} params.foreign.onDelete - Action when a referenced row is deleted (e.g. CASCADE, SET NULL).
+     * @param {string} params.foreign.onUpdate - Action when a referenced row is updated (e.g. CASCADE, RESTRICT).
+     *
+     * @throws {Error} If the specified foreign key constraint already exists.
+     *
+     * @returns {Promise<void>} Resolves when the foreign key constraint is successfully created.
+     */
+    addFK({ table, tableRef, key, constraint, foreign }: {
+        table: string;
+        tableRef: string;
+        key: string;
+        constraint: string;
+        foreign: {
+            references: string;
+            onDelete: string;
+            onUpdate: string;
+        };
+    }): Promise<void>;
     /**
      * The `dropFK` method is used to remove a foreign key constraint from the database.
      * If a table name is provided, the constraint will be dropped from that table;
@@ -1208,10 +1305,172 @@ declare class Builder extends AbstractBuilder {
      * @returns {Promise<boolean>}
      *
      */
-    hasIndex({ index, table }: {
-        index: string;
+    hasIndex({ name, table }: {
+        name: string;
+        table?: string;
+    }): Promise<boolean>;
+    /**
+     * Adds an index to a table.
+     *
+     * This method checks whether the specified index already exists on the table
+     * before attempting to create it. If the index exists, an error will be thrown
+     * to prevent duplication.
+     *
+     * @async
+     * @method addIndex
+     * @param {Object} params - Parameters for creating the index.
+     * @param {string} params.name - The name of the index.
+     * @param {string} [params.table] - The table where the index will be created. Defaults to the current model table.
+     * @param {string[]} params.columns - The columns included in the index.
+     *
+     * @throws {Error} If the specified index already exists.
+     *
+     * @returns {Promise<void>} Resolves when the index has been successfully created.
+     */
+    addIndex({ name, table, columns }: {
+        name: string;
+        table?: string;
+        columns: string[];
+    }): Promise<void>;
+    /**
+     * Drops an index from a table.
+     *
+     * This method checks whether the specified index exists on the table
+     * before attempting to drop it. If the index does not exist, an error
+     * will be thrown.
+     *
+     * @async
+     * @method dropIndex
+     * @param {Object} params - Parameters for dropping the index.
+     * @param {string} params.name - The name of the index to drop.
+     * @param {string} [params.table] - The table from which the index will be removed. Defaults to the current model table.
+     *
+     * @throws {Error} If the specified index was not found.
+     *
+     * @returns {Promise<void>} Resolves when the index has been successfully dropped.
+     */
+    dropIndex({ name, table }: {
+        name: string;
+        table?: string;
+    }): Promise<void>;
+    /**
+     * Checks whether a unique constraint exists on a table.
+     *
+     * This method queries the database metadata to determine if the specified
+     * unique constraint exists on the given table.
+     *
+     * @async
+     * @method hasUnique
+     * @param {Object} params - Parameters for checking the unique constraint.
+     * @param {string} params.name - The name of the unique constraint.
+     * @param {string} [params.table] - The table to check. Defaults to the current model table.
+     *
+     * @returns {Promise<boolean>} Returns `true` if the unique constraint exists, otherwise `false`.
+     */
+    hasUnique({ name, table }: {
+        name: string;
+        table?: string;
+    }): Promise<boolean>;
+    /**
+     * Adds a unique constraint to a table.
+     *
+     * This method checks whether the specified unique constraint already exists
+     * on the table before attempting to create it. If the constraint already exists,
+     * an error will be thrown to prevent duplication.
+     *
+     * @async
+     * @method addUnique
+     * @param {Object} params - Parameters for creating the unique constraint.
+     * @param {string} params.name - The name of the unique constraint.
+     * @param {string} [params.table] - The table where the unique constraint will be added. Defaults to the current model table.
+     * @param {string[]} params.columns - The columns that will be included in the unique constraint.
+     *
+     * @throws {Error} If the specified unique constraint already exists.
+     *
+     * @returns {Promise<void>} Resolves when the unique constraint has been successfully created.
+     */
+    addUnique({ name, table, columns }: {
+        name: string;
+        table?: string;
+        columns: string[];
+    }): Promise<void>;
+    /**
+     * Drops a unique constraint from a table.
+     *
+     * This method checks whether the specified unique constraint exists
+     * on the table before attempting to remove it. If the constraint does
+     * not exist, an error will be thrown.
+     *
+     * @async
+     * @method dropUnique
+     * @param {Object} params - Parameters for dropping the unique constraint.
+     * @param {string} params.name - The name of the unique constraint to drop.
+     * @param {string} [params.table] - The table from which the unique constraint will be removed. Defaults to the current model table.
+     *
+     * @throws {Error} If the specified unique constraint was not found.
+     *
+     * @returns {Promise<void>} Resolves when the unique constraint has been successfully dropped.
+     */
+    dropUnique({ name, table }: {
+        name: string;
+        table?: string;
+    }): Promise<void>;
+    /**
+     * Checks whether a primary key constraint exists on a table.
+     *
+     * This method queries the database metadata to determine if the specified
+     * table contains a primary key constraint.
+     *
+     * @async
+     * @method hasPrimaryKey
+     * @param {Object} [params={}] - Parameters for checking the primary key.
+     * @param {string} [params.table] - The table to check. Defaults to the current model table.
+     *
+     * @returns {Promise<boolean>} Returns `true` if the table has a primary key constraint,
+     * otherwise `false`.
+     */
+    hasPrimaryKey({ table }?: {
         table?: string;
     }): Promise<boolean>;
+    /**
+     * Adds a primary key constraint to a table.
+     *
+     * This method checks whether the table already has a primary key
+     * before attempting to create one. If a primary key already exists,
+     * an error will be thrown.
+     *
+     * @async
+     * @method addPrimaryKey
+     * @param {Object} params - Parameters for creating the primary key.
+     * @param {string} [params.table] - The table where the primary key will be added. Defaults to the current model table.
+     * @param {string[]} params.columns - The column(s) that will form the primary key.
+     *
+     * @throws {Error} If the table already has a primary key constraint.
+     *
+     * @returns {Promise<void>} Resolves when the primary key has been successfully created.
+     */
+    addPrimaryKey({ table, columns }: {
+        table?: string;
+        columns: string[];
+    }): Promise<void>;
+    /**
+     * Drops the primary key constraint from a table.
+     *
+     * This method checks whether the table has a primary key before
+     * attempting to remove it. If no primary key exists, an error will be thrown.
+     *
+     * @async
+     * @method dropPrimaryKey
+     * @param {Object} [params={}] - Parameters for dropping the primary key.
+     * @param {string} [params.table] - The table from which the primary key will be removed. Defaults to the current model table.
+     *
+     * @throws {Error} If the specified primary key constraint was not found.
+     *
+     * @returns {Promise<void>} Resolves when the primary key constraint has been successfully removed.
+     */
+    dropPrimaryKey({ table }?: {
+        table?: string;
+    }): Promise<void>;
     /**
      * The 'bindColumn' method is used to concat table and column -> `users`.`id`
      * @param {string} column
@@ -1330,37 +1589,41 @@ declare class Builder extends AbstractBuilder {
      * The 'find' method is used to retrieve a single record from a database table by its primary key.
      *
      * This method allows you to quickly fetch a specific record by specifying the primary key value, which is typically an integer id.
-     * @param {number} id
+     * @param {number | string} primaryKey
      * @returns {promise<any>}
      */
-    find(id: number): Promise<Record<string, any> | null>;
+    find(primaryKey: number | string): Promise<Record<string, any> | null>;
     /**
      * The 'pagination' method is used to perform pagination on a set of database query results obtained through the Query Builder.
      *
      * It allows you to split a large set of query results into smaller, more manageable pages,
      * making it easier to display data in a web application and improve user experience
-     * @param {?object} paginationOptions
-     * @param {number} paginationOptions.limit default 15
-     * @param {number} paginationOptions.page default 1
+     * @param    {object?}  opts by default page = 1 , limit = 15
+     * @property {number?}  opts.limit
+     * @property {number?}  opts.page
+     * @property {boolean?} opts.distinct
      * @returns {promise<Pagination>}
      */
-    pagination(paginationOptions?: {
+    pagination(opts?: {
         limit?: number;
         page?: number;
+        distinct?: boolean;
     }): Promise<TPagination>;
     /**
      * The 'paginate' method is used to perform pagination on a set of database query results obtained through the Query Builder.
      *
      * It allows you to split a large set of query results into smaller, more manageable pages,
      * making it easier to display data in a web application and improve user experience
-     * @param {?object} paginationOptions
-     * @param {number} paginationOptions.limit
-     * @param {number} paginationOptions.page
+     * @param    {object?}  opts by default page = 1 , limit = 15
+     * @property {number?}  opts.limit
+     * @property {number?}  opts.page
+     * @property {boolean?} opts.distinct
      * @returns {promise<Pagination>}
      */
-    paginate(paginationOptions?: {
+    paginate(opts?: {
         limit?: number;
         page?: number;
+        distinct?: boolean;
     }): Promise<TPagination>;
     /**
      *
@@ -1546,7 +1809,7 @@ declare class Builder extends AbstractBuilder {
      */
     save({ waitMs }?: {
         waitMs?: number | undefined;
-    }): Promise<Record<string, any> | any[] | null | undefined>;
+    }): Promise<TSaveBuilderResult<TA>>;
     /**
      *
      * The 'makeSelectStatement' method is used to make select statement.
@@ -1586,6 +1849,15 @@ declare class Builder extends AbstractBuilder {
      * @async
      */
     getTables(): Promise<string[]>;
+    /**
+     * The `getTable` method is used to retrieve a list of all table names
+     * in the current database.
+     *
+     * @returns {Promise<string[]>} A promise that resolves to an array of table names.
+     *
+     * @async
+     */
+    hasTable(table: string): Promise<boolean>;
     /**
      *
      * The 'showColumns' method is used to show columns table.
@@ -1639,7 +1911,7 @@ declare class Builder extends AbstractBuilder {
     }): Promise<boolean>;
     protected exceptColumns(): Promise<string[]>;
     protected _updateHandler(column: string, value?: string | number | null | boolean): string;
-    copyBuilder(instance: Builder, options?: {
+    copyBuilder(instance: Builder<any>, options?: {
         update?: boolean;
         insert?: boolean;
         delete?: boolean;