mrepo-sql 1.0.0 → 1.0.2

package/dist/db/repo.d.ts

@@ -2,43 +2,60 @@ import mariadb, { type PoolConfig } from "mariadb";
 import { ExecSPOptions } from "../interfaces/db.interface.js";
 export declare class BaseRepository {
     private pool;
+    /**
+     * Creates a new BaseRepository instance.
+     * @param {PoolConfig} config - Connection configuration for the MariaDB pool.
+     */
     constructor(config: PoolConfig);
     /**
      * Executes a stored procedure with the given parameters and handling options.
-     * @OPTIONS {params: any[] | Record<string, any>, out: OutVariable[], plain: boolean, extract: boolean, order: string[], deleteExtra: boolean, fillWithNulls: boolean}
-     * @param spName The name of the stored procedure to call.
-     * @param options The options for the stored procedure execution.
-     * @returns The result of the stored procedure execution, typed as T.
+     *
+     * @param {string} spName - The name of the stored procedure to call.
+     * @param {ExecSPOptions} options - Execution and result handling options.
+     * @param {any[] | Record<string, any>} [options.params=[]] - Parameters for the SP.
+     * @param {OutVariable[]} [options.out=[]] - Output variables to handle.
+     * @param {boolean} [options.plain=true] - Whether to return a single object (true) or an array of results.
+     * @param {boolean} [options.extract=false] - Whether to extract parameters from an object based on `order`.
+     * @param {string[]} [options.order=[]] - The order of keys for parameter extraction.
+     * @param {boolean} [options.deleteExtra=false] - Whether to remove keys not present in `order`.
+     * @param {boolean} [options.fillWithNulls=false] - Whether to fill missing ordered parameters with null.
+     * @returns {Promise<T>} The result of the stored procedure execution.
      */
     execSP<T = any>(spName: string, { params, out, plain, extract, order, deleteExtra, fillWithNulls, }: ExecSPOptions): Promise<T>;
     /**
-     * Retrieves all records from a view.
+     * Retrieves all records from a database view.
      *
-     * @param viewName - The name of the view to query.
-     * @returns The result of the query.
+     * @param {string} viewName - The name of the view to query.
+     * @returns {Promise<T[]>} An array containing the records from the view.
      */
     view<T = any>(viewName: string): Promise<T[]>;
     /**
-     * Executes a query with the given parameters.
+     * Executes a raw SQL query with optional parameters.
      *
-     * @param query - The SQL query to execute.
-     * @param params - The parameters to pass to the query.
-     * @returns The result of the query.
+     * @param {string} query - The SQL query to execute.
+     * @param {any[]} [params] - The parameters to safely bind to the query.
+     * @returns {Promise<T[]>} The result set from the query.
      */
     query<T = any>(query: string, params?: any[]): Promise<T[]>;
     /**
-     * Connects to the database.
+     * Tests the database connection and invokes callbacks based on the result.
      *
-     * @param onSuccess - Callback function to execute on success.
-     * @param onError - Callback function to execute on error.
+     * @param {function} [onSuccess] - Callback function to execute if the connection is successful.
+     * @param {function} [onError] - Callback function to execute if the connection fails.
+     * @throws {Error} If the connection fails and no onError callback is provided.
      */
     connectDB(onSuccess?: () => void, onError?: (error: Error) => void): Promise<void>;
     /**
-     * Closes the connection pool.
+     * Closes the connection pool and all active connections.
      *
-     * @param onSuccess - Callback function to execute on success.
-     * @param onError - Callback function to execute on error.
+     * @param {function} [onSuccess] - Callback function to execute after the pool is closed.
+     * @param {function} [onError] - Callback function to execute if closing the pool fails.
+     * @returns {Promise<void>}
      */
     closeDB(onSuccess?: () => void, onError?: (error: Error) => void): Promise<void>;
+    /**
+     * Returns the underlying MariaDB connection pool.
+     * @returns {Promise<mariadb.Pool>} The MariaDB pool instance.
+     */
     getOriginalPool(): Promise<mariadb.Pool>;
 }

package/dist/db/repo.js

@@ -4,6 +4,10 @@ const defaultConfig = {
     multipleStatements: true,
 };
 export class BaseRepository {
+    /**
+     * Creates a new BaseRepository instance.
+     * @param {PoolConfig} config - Connection configuration for the MariaDB pool.
+     */
     constructor(config) {
         this.pool = mariadb.createPool({
             ...defaultConfig,
@@ -12,10 +16,17 @@ export class BaseRepository {
     }
     /**
      * Executes a stored procedure with the given parameters and handling options.
-     * @OPTIONS {params: any[] | Record<string, any>, out: OutVariable[], plain: boolean, extract: boolean, order: string[], deleteExtra: boolean, fillWithNulls: boolean}
-     * @param spName The name of the stored procedure to call.
-     * @param options The options for the stored procedure execution.
-     * @returns The result of the stored procedure execution, typed as T.
+     *
+     * @param {string} spName - The name of the stored procedure to call.
+     * @param {ExecSPOptions} options - Execution and result handling options.
+     * @param {any[] | Record<string, any>} [options.params=[]] - Parameters for the SP.
+     * @param {OutVariable[]} [options.out=[]] - Output variables to handle.
+     * @param {boolean} [options.plain=true] - Whether to return a single object (true) or an array of results.
+     * @param {boolean} [options.extract=false] - Whether to extract parameters from an object based on `order`.
+     * @param {string[]} [options.order=[]] - The order of keys for parameter extraction.
+     * @param {boolean} [options.deleteExtra=false] - Whether to remove keys not present in `order`.
+     * @param {boolean} [options.fillWithNulls=false] - Whether to fill missing ordered parameters with null.
+     * @returns {Promise<T>} The result of the stored procedure execution.
      */
     async execSP(spName, { params = [], out = [], plain = true, extract = false, order = [], deleteExtra = false, fillWithNulls = false, }) {
         const endParams = extract && !Array.isArray(params) && params !== null
@@ -30,7 +41,7 @@ export class BaseRepository {
         try {
             conn = await this.pool.getConnection();
             const declareOutVars = out.length
-                ? out.map(({ name, type }) => `SET @${name} = CAST(NULL AS ${type ?? 'VARCHAR(255)'});`).join('\n')
+                ? out.map(({ name, type }) => `SET ${name} = CAST(NULL AS ${type ?? 'VARCHAR(255)'});`).join('\n')
                 : '';
             const selectOuts = out.length
                 ? 'SELECT ' + out
@@ -54,10 +65,10 @@ export class BaseRepository {
         }
     }
     /**
-     * Retrieves all records from a view.
+     * Retrieves all records from a database view.
      *
-     * @param viewName - The name of the view to query.
-     * @returns The result of the query.
+     * @param {string} viewName - The name of the view to query.
+     * @returns {Promise<T[]>} An array containing the records from the view.
      */
     async view(viewName) {
         let conn;
@@ -75,11 +86,11 @@ export class BaseRepository {
         }
     }
     /**
-     * Executes a query with the given parameters.
+     * Executes a raw SQL query with optional parameters.
      *
-     * @param query - The SQL query to execute.
-     * @param params - The parameters to pass to the query.
-     * @returns The result of the query.
+     * @param {string} query - The SQL query to execute.
+     * @param {any[]} [params] - The parameters to safely bind to the query.
+     * @returns {Promise<T[]>} The result set from the query.
      */
     async query(query, params) {
         let conn;
@@ -97,10 +108,11 @@ export class BaseRepository {
         }
     }
     /**
-     * Connects to the database.
+     * Tests the database connection and invokes callbacks based on the result.
      *
-     * @param onSuccess - Callback function to execute on success.
-     * @param onError - Callback function to execute on error.
+     * @param {function} [onSuccess] - Callback function to execute if the connection is successful.
+     * @param {function} [onError] - Callback function to execute if the connection fails.
+     * @throws {Error} If the connection fails and no onError callback is provided.
      */
     async connectDB(onSuccess, onError) {
         try {
@@ -114,10 +126,11 @@ export class BaseRepository {
         }
     }
     /**
-     * Closes the connection pool.
+     * Closes the connection pool and all active connections.
      *
-     * @param onSuccess - Callback function to execute on success.
-     * @param onError - Callback function to execute on error.
+     * @param {function} [onSuccess] - Callback function to execute after the pool is closed.
+     * @param {function} [onError] - Callback function to execute if closing the pool fails.
+     * @returns {Promise<void>}
      */
     async closeDB(onSuccess, onError) {
         return this.pool.end().then(() => {
@@ -127,6 +140,10 @@ export class BaseRepository {
             throw error;
         });
     }
+    /**
+     * Returns the underlying MariaDB connection pool.
+     * @returns {Promise<mariadb.Pool>} The MariaDB pool instance.
+     */
     async getOriginalPool() {
         return this.pool;
     }

package/dist/interfaces/db.interface.d.ts

@@ -1,20 +1,48 @@
+/**
+ * Represents an output variable for a stored procedure.
+ */
 export interface OutVariable {
+    /** The name of the variable (without the @ symbol). */
     name: string;
+    /** The SQL type of the variable (e.g., 'VARCHAR(255)', 'INT'). Defaults to 'VARCHAR(255)'. */
     type?: string;
 }
+/**
+ * Options for executing a stored procedure.
+ */
 export interface ExecSPOptions {
-    /** Parameters to pass to the SP. Can be an array or an object if `extract` is true. */
+    /**
+     * Parameters to pass to the stored procedure.
+     * Can be an array of values or an object (if `extract` is set to true).
+     */
     params?: any[] | Record<string, any>;
-    /** Definition of output variables. */
+    /**
+     * Definitions of output variables to be captured after execution.
+     */
     out?: OutVariable[];
-    /** If true, flattens the result into a single object. */
+    /**
+     * If true, flattens the result into a single object when the SP returns a single row.
+     * @default true
+     */
     plain?: boolean;
-    /** If true, extracts parameters from an object based on the `order` array. */
+    /**
+     * If true, extracts parameters from an object based on the `order` array.
+     * Useful when you want to pass an object but the SP expects positional parameters.
+     * @default false
+     */
     extract?: boolean;
-    /** The order of keys to extract from `params`. */
+    /**
+     * The order of keys to extract from `params` when `extract` is true.
+     */
     order?: string[];
-    /** If true, deletes extra parameters not specified in `order`. */
+    /**
+     * If true, deletes keys from the `params` object that are not specified in the `order` array.
+     * @default false
+     */
     deleteExtra?: boolean;
-    /** If true, fills missing ordered parameters with null. */
+    /**
+     * If true, fills missing parameters defined in `order` with `null` if they are not in `params`.
+     * @default false
+     */
     fillWithNulls?: boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mrepo-sql",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "With mrepo-sql, the ability to create repositories with features that improve code readability and project scalability is added.",
   "license": "MIT",
   "author": "daniel_hz",

package/src/db/repo.ts

@@ -9,6 +9,11 @@ const defaultConfig = {
 
 export class BaseRepository {
     private pool: mariadb.Pool;
+
+    /**
+     * Creates a new BaseRepository instance.
+     * @param {PoolConfig} config - Connection configuration for the MariaDB pool.
+     */
     constructor(config: PoolConfig) {
         this.pool = mariadb.createPool(
             {
@@ -20,10 +25,17 @@ export class BaseRepository {
 
     /**
      * Executes a stored procedure with the given parameters and handling options.
-     * @OPTIONS {params: any[] | Record<string, any>, out: OutVariable[], plain: boolean, extract: boolean, order: string[], deleteExtra: boolean, fillWithNulls: boolean}
-     * @param spName The name of the stored procedure to call.
-     * @param options The options for the stored procedure execution.
-     * @returns The result of the stored procedure execution, typed as T.
+     * 
+     * @param {string} spName - The name of the stored procedure to call.
+     * @param {ExecSPOptions} options - Execution and result handling options.
+     * @param {any[] | Record<string, any>} [options.params=[]] - Parameters for the SP.
+     * @param {OutVariable[]} [options.out=[]] - Output variables to handle.
+     * @param {boolean} [options.plain=true] - Whether to return a single object (true) or an array of results.
+     * @param {boolean} [options.extract=false] - Whether to extract parameters from an object based on `order`.
+     * @param {string[]} [options.order=[]] - The order of keys for parameter extraction.
+     * @param {boolean} [options.deleteExtra=false] - Whether to remove keys not present in `order`.
+     * @param {boolean} [options.fillWithNulls=false] - Whether to fill missing ordered parameters with null.
+     * @returns {Promise<T>} The result of the stored procedure execution.
      */
     async execSP<T = any>(spName: string, {
         params = [],
@@ -50,7 +62,7 @@ export class BaseRepository {
             conn = await this.pool.getConnection();
 
             const declareOutVars = out.length
-                ? out.map(({ name, type }) => `SET @${name} = CAST(NULL AS ${type ?? 'VARCHAR(255)'});`).join('\n')
+                ? out.map(({ name, type }) => `SET ${name} = CAST(NULL AS ${type ?? 'VARCHAR(255)'});`).join('\n')
                 : '';
 
             const selectOuts = out.length
@@ -76,10 +88,10 @@ export class BaseRepository {
     }
 
     /**
-     * Retrieves all records from a view.
+     * Retrieves all records from a database view.
      * 
-     * @param viewName - The name of the view to query.
-     * @returns The result of the query.
+     * @param {string} viewName - The name of the view to query.
+     * @returns {Promise<T[]>} An array containing the records from the view.
      */
     async view<T = any>(viewName: string): Promise<T[]> {
         let conn;
@@ -95,11 +107,11 @@ export class BaseRepository {
     }
 
     /**
-     * Executes a query with the given parameters.
+     * Executes a raw SQL query with optional parameters.
      * 
-     * @param query - The SQL query to execute.
-     * @param params - The parameters to pass to the query.
-     * @returns The result of the query.
+     * @param {string} query - The SQL query to execute.
+     * @param {any[]} [params] - The parameters to safely bind to the query.
+     * @returns {Promise<T[]>} The result set from the query.
      */
     async query<T = any>(query: string, params?: any[]): Promise<T[]> {
         let conn;
@@ -115,10 +127,11 @@ export class BaseRepository {
     }
 
     /**
-     * Connects to the database.
+     * Tests the database connection and invokes callbacks based on the result.
      * 
-     * @param onSuccess - Callback function to execute on success.
-     * @param onError - Callback function to execute on error.
+     * @param {function} [onSuccess] - Callback function to execute if the connection is successful.
+     * @param {function} [onError] - Callback function to execute if the connection fails.
+     * @throws {Error} If the connection fails and no onError callback is provided.
      */
     async connectDB(onSuccess?: () => void, onError?: (error: Error) => void) {
         try {
@@ -132,10 +145,11 @@ export class BaseRepository {
     }
 
     /**
-     * Closes the connection pool.
+     * Closes the connection pool and all active connections.
      * 
-     * @param onSuccess - Callback function to execute on success.
-     * @param onError - Callback function to execute on error.
+     * @param {function} [onSuccess] - Callback function to execute after the pool is closed.
+     * @param {function} [onError] - Callback function to execute if closing the pool fails.
+     * @returns {Promise<void>}
      */
     async closeDB(onSuccess?: () => void, onError?: (error: Error) => void) {
         return this.pool.end().then(() => {
@@ -146,6 +160,10 @@ export class BaseRepository {
         });
     }
 
+    /**
+     * Returns the underlying MariaDB connection pool.
+     * @returns {Promise<mariadb.Pool>} The MariaDB pool instance.
+     */
     async getOriginalPool() {
         return this.pool;
     }

package/src/interfaces/db.interface.ts

@@ -1,21 +1,49 @@
+/**
+ * Represents an output variable for a stored procedure.
+ */
 export interface OutVariable {
+    /** The name of the variable (without the @ symbol). */
     name: string;
+    /** The SQL type of the variable (e.g., 'VARCHAR(255)', 'INT'). Defaults to 'VARCHAR(255)'. */
     type?: string;
 }
 
+/**
+ * Options for executing a stored procedure.
+ */
 export interface ExecSPOptions {
-    /** Parameters to pass to the SP. Can be an array or an object if `extract` is true. */
+    /** 
+     * Parameters to pass to the stored procedure. 
+     * Can be an array of values or an object (if `extract` is set to true).
+     */
     params?: any[] | Record<string, any>;
-    /** Definition of output variables. */
+    /** 
+     * Definitions of output variables to be captured after execution. 
+     */
     out?: OutVariable[];
-    /** If true, flattens the result into a single object. */
+    /** 
+     * If true, flattens the result into a single object when the SP returns a single row. 
+     * @default true
+     */
     plain?: boolean;
-    /** If true, extracts parameters from an object based on the `order` array. */
+    /** 
+     * If true, extracts parameters from an object based on the `order` array. 
+     * Useful when you want to pass an object but the SP expects positional parameters.
+     * @default false
+     */
     extract?: boolean;
-    /** The order of keys to extract from `params`. */
+    /** 
+     * The order of keys to extract from `params` when `extract` is true. 
+     */
     order?: string[];
-    /** If true, deletes extra parameters not specified in `order`. */
+    /** 
+     * If true, deletes keys from the `params` object that are not specified in the `order` array. 
+     * @default false
+     */
     deleteExtra?: boolean;
-    /** If true, fills missing ordered parameters with null. */
+    /** 
+     * If true, fills missing parameters defined in `order` with `null` if they are not in `params`. 
+     * @default false
+     */
     fillWithNulls?: boolean;
 }

package/test-autocomplete.js

@@ -0,0 +1,16 @@
+import { BaseRepository } from "./dist/index.js";
+
+/**
+ * This is a sample JS file to verify autocomplete.
+ * If you hover over BaseRepository or its methods, you should see full documentation.
+ */
+
+const repo = new BaseRepository({
+    host: 'localhost',
+    user: 'root',
+    password: 'password',
+    database: 'test'
+});
+
+// Try typing 'repo.execSP(' and observe the parameter hints!
+// repo.execSP('sp_test', { params: ... });