tspace-mysql 1.9.0 → 1.9.1

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

@@ -3,7 +3,7 @@ import { DB } from "./DB";
 import { Join } from "./Join";
 import { CONSTANTS } from "../constants";
 import { QueryBuilder } from "./Driver";
-import { TPagination, TConnectionOptions, TPoolConnected, TConnectionTransaction } from "../types";
+import { TPagination, TConnectionOptions, TPoolConnected, TConnectionTransaction, TDriver } from "../types";
 declare class Builder extends AbstractBuilder {
     constructor();
     /**
@@ -14,21 +14,70 @@ declare class Builder extends AbstractBuilder {
     static get instance(): Builder;
     /**
      * The 'driver' method is used to get current driver
-     * @returns {string} 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
@@ -1162,6 +1211,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 +1291,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,10 +1575,10 @@ 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.
      *
@@ -1586,6 +1831,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.