@crane-technologies/database 2.1.0

package/dist/components/Database.d.ts

@@ -0,0 +1,288 @@
+import { QueryResult } from "pg";
+import { Dependency } from "@/interfaces/Dependancy";
+import { DatabaseConfig } from "@/interfaces/DatabaseConfig";
+import { BulkInsertOptions } from "@/interfaces/BulkInsertOptions";
+import { QueryReference } from "@/utils/createQueries";
+/**
+ * Database class implements the Singleton pattern to manage PostgreSQL connections.
+ * Provides methods for executing SQL queries, transactions and dependency handling.
+ * Supports QueryReference objects for autocomplete.
+ *
+ * @class Database
+ * @example
+ * ```typescript
+ * import Database, { createQueries } from '@crane-technologies/database';
+ *
+ * const queries = createQueries({
+ *   users: {
+ *     getById: "SELECT * FROM users WHERE id = $1"
+ *   }
+ * });
+ *
+ * const db = Database.getInstance(config, queries);
+ *
+ * // ✅ Con autocompletado
+ * await db.query(queries.users.getById, [123]);
+ * ```
+ */
+declare class Database {
+    /** Unique singleton instance */
+    private static instance;
+    /** PostgreSQL connection pool */
+    private pool;
+    /** Dictionary of predefined SQL queries (flat map) */
+    private queries;
+    /** Logger instance */
+    private logger;
+    /** Database configuration */
+    private config;
+    /**
+     * Private constructor that implements the Singleton pattern.
+     * Use getInstance() to get the Database instance.
+     *
+     * @param {DatabaseConfig} config - Database configuration
+     * @param {Record<string, string>} flatMap - Flat map of queries
+     * @private
+     */
+    private constructor();
+    /**
+     * Initializes the PostgreSQL connection pool using provided configuration.
+     * Executed only once when creating the first singleton instance.
+     *
+     * @private
+     * @returns {void}
+     * @throws {Error} If pool initialization fails
+     */
+    private initializePool;
+    /**
+     * Static method to get the unique Database instance (Singleton pattern).
+     * Accepts the result of createQueries() or a plain object with queries.
+     *
+     * @param {DatabaseConfig} config - Database configuration (required on first call)
+     * @param {any} queries - Result from createQueries() or plain query object
+     * @returns {Database} The unique Database instance
+     * @throws {Error} If config is not provided on first initialization
+     *
+     * @example
+     * ```typescript
+     * // With createQueries (recommended)
+     * const queries = createQueries({
+     *   users: { getById: "SELECT * FROM users WHERE id = $1" }
+     * });
+     * const db = Database.getInstance(config, queries);
+     * await db.query(queries.users.getById, [123]);
+     *
+     * // With plain object (backward compatible)
+     * const db = Database.getInstance(config, {
+     *   getUser: "SELECT * FROM users WHERE id = $1"
+     * });
+     * await db.query("getUser", [123]);
+     * ```
+     */
+    static getInstance(config: DatabaseConfig, queries?: any): Database;
+    /**
+     * Validates that the pool is active and ready to accept connections.
+     *
+     * @private
+     * @throws {Error} If pool is closed or not initialized
+     */
+    private ensurePoolActive;
+    /**
+     * Extracts the SQL from a QueryReference or string key.
+     *
+     * @private
+     * @param query - QueryReference, string key, or raw SQL
+     * @returns The SQL query string
+     * @throws {Error} If query is not found
+     */
+    private getQuery;
+    /**
+     * Gets the SQL query string.
+     *
+     * @private
+     * @param query - QueryReference or string
+     * @returns The SQL query string
+     */
+    private getQueryName;
+    /**
+     * Executes a predefined SQL query using QueryReference or string key.
+     * Gets a connection from the pool, executes the query and releases the connection.
+     *
+     * @param {string | QueryReference} query - QueryReference object or query key
+     * @param {any[]} params - Optional parameters for the SQL query
+     * @returns {Promise<QueryResult>} SQL query result
+     * @throws {Error} If the query doesn't exist or execution fails
+     *
+     * @example
+     * ```typescript
+     * // With QueryReference (autocomplete!)
+     * const result = await db.queryList(queries.users.getById, [123]);
+     *
+     * // With string key (backward compatible)
+     * const result = await db.queryList("users.getById", [123]);
+     * ```
+     */
+    queryList(query: string | QueryReference, params?: any[]): Promise<QueryResult>;
+    /**
+     * Executes a direct SQL query (raw SQL text).
+     * Useful for dynamic queries that are not predefined in the dictionary.
+     * Gets a connection from the pool, executes the query and releases the connection.
+     *
+     * @param {string} sqlText - The complete SQL text of the query to execute
+     * @param {any[]} params - Optional parameters for the SQL query
+     * @returns {Promise<QueryResult>} SQL query result
+     * @throws {Error} If query execution fails
+     *
+     * @example
+     * ```typescript
+     * const result = await db.rawQuery("SELECT COUNT(*) FROM users WHERE active = $1", [true]);
+     * const count = result.rows[0].count;
+     * ```
+     */
+    rawQuery(sqlText: string, params?: any[]): Promise<QueryResult>;
+    /**
+     * Performs a high-performance bulk insert using PostgreSQL's native COPY ... FROM STDIN.
+     * Accepts an array of rows and streams them as CSV to the database.
+     * This is significantly faster than multiple INSERT statements.
+     *
+     * @param {string} table - The target table name.
+     * @param {string[]} columns - Array of column names to insert into (order matters).
+     * @param {(string | number | boolean | Date | null | undefined)[][]} rows - Array of row arrays, each representing a record.
+     * @param {BulkInsertOptions} [options] - Optional CSV formatting options (delimiter, header).
+     * @returns {Promise<{ inserted: number }>} Number of rows successfully inserted.
+     * @throws {Error} If the operation fails or the pool is not active.
+     *
+     * @example
+     * ```typescript
+     * await db.bulkInsert(
+     *   "users",
+     *   ["name", "email"],
+     *   [
+     *     ["Alice", "alice@email.com"],
+     *     ["Bob", "bob@email.com"]
+     *   ],
+     *   { header: false }
+     * );
+     * ```
+     */
+    bulkInsert(table: string, columns: string[], rows: (string | number | boolean | Date | null | undefined)[][], options?: BulkInsertOptions): Promise<{
+        inserted: number;
+    }>;
+    /**
+     * Generator that yields CSV lines for bulk insert operations.
+     * Optionally includes a header row with column names.
+     * Each yielded value is a CSV-formatted string representing a row.
+     *
+     * @private
+     * @param {string[]} columns - Array of column names.
+     * @param {(string | number | boolean | Date | null | undefined)[][]} rows - Array of row arrays.
+     * @param {string} delimiter - CSV delimiter character.
+     * @param {boolean} includeHeader - Whether to include a header row.
+     * @yields {string} CSV-formatted line.
+     */
+    private generateCsvLines;
+    /**
+     * Escapes a single value for safe inclusion in a CSV line.
+     * Handles delimiters, quotes, and line breaks according to CSV rules.
+     *
+     * @private
+     * @param {string | number | boolean | Date | null | undefined} value - The value to escape.
+     * @param {string} delimiter - The CSV delimiter character.
+     * @returns {string} The escaped CSV value.
+     */
+    private escapeCsvValue;
+    /**
+     * Safely quotes a SQL identifier (such as a table or column name) for use in queries.
+     * Escapes any double quotes within the identifier to prevent SQL injection or syntax errors.
+     *
+     * @private
+     * @param {string} identifier - The SQL identifier to quote (e.g., table or column name).
+     * @returns {string} The quoted and escaped identifier, safe for use in SQL statements.
+     *
+     * @example
+     * const quoted = db.quoteIdentifier('user"name');
+     * // quoted === '"user""name"'
+     */
+    private quoteIdentifier;
+    /**
+     * Smart method that executes queries automatically detecting the type.
+     * Supports QueryReference objects (from createQueries), string keys, or raw SQL.
+     *
+     * @param {string | QueryReference} query - QueryReference, query key, or raw SQL
+     * @param {any[]} params - Optional parameters for the SQL query
+     * @returns {Promise<QueryResult>} SQL query result
+     * @throws {Error} If query execution fails
+     *
+     * @example
+     * ```typescript
+     * // Using QueryReference (autocomplete!)
+     * const user = await db.query(queries.users.getById, [123]);
+     *
+     * // Using string key (backward compatible)
+     * const user = await db.query("users.getById", [123]);
+     *
+     * // Using raw SQL
+     * const products = await db.query("SELECT * FROM products WHERE price > $1", [100]);
+     * ```
+     */
+    query(query: string | QueryReference, params?: any[]): Promise<QueryResult>;
+    /**
+     * Executes multiple SQL queries within an atomic transaction.
+     * All queries execute or fail together (ACID compliance).
+     * Supports dependencies between queries, where the result of one query
+     * can be used as a parameter in subsequent queries.
+     * Supports QueryReference objects with autocomplete.
+     *
+     * @param {(string | QueryReference)[]} queryArray - Array of QueryReferences or query keys
+     * @param {any[][]} paramsArray - Array of arrays with parameters for each query
+     * @param {Dependency[]} dependencies - Optional array of dependencies between queries
+     * @returns {Promise<QueryResult[]>} Array with the results of all queries
+     * @throws {Error} If any query fails, the entire transaction is rolled back
+     *
+     * @example
+     * ```typescript
+     * // With QueryReference (autocomplete!)
+     * const results = await db.transaction(
+     *   [queries.users.create, queries.profiles.create],
+     *   [
+     *     ["John", "john@email.com"],
+     *     [null, "Profile description"]
+     *   ],
+     *   [{ sourceIndex: 0, targetIndex: 1, targetParamIndex: 0 }]
+     * );
+     *
+     * // With string keys (backward compatible)
+     * const results = await db.transaction(
+     *   ["users.create", "profiles.create"],
+     *   [["John", "john@email.com"], [null, "Profile description"]],
+     *   [{ sourceIndex: 0, targetIndex: 1, targetParamIndex: 0 }]
+     * );
+     * ```
+     */
+    transaction(queryArray: (string | QueryReference)[], paramsArray: any[][], dependencies?: Dependency[]): Promise<QueryResult[]>;
+    /**
+     * Closes all connections in the pool and cleans up resources.
+     * Should be called before application shutdown or when the database is no longer needed.
+     * After calling this method, the singleton instance is reset and a new one can be created.
+     *
+     * @returns {Promise<void>}
+     * @throws {Error} If there's an error closing the pool
+     *
+     * @example
+     * ```typescript
+     * process.on('SIGTERM', async () => {
+     *   const db = Database.getInstance();
+     *   await db.close();
+     *   process.exit(0);
+     * });
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * Updates the log level dynamically
+     * @param level - New log level (0-3)
+     */
+    setLogLevel(level: 0 | 1 | 2 | 3): void;
+}
+export default Database;
+//# sourceMappingURL=Database.d.ts.map

package/dist/components/Database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Database.d.ts","sourceRoot":"","sources":["../../components/Database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAoB,WAAW,EAAE,MAAM,IAAI,CAAC;AAMnD,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,cAAM,QAAQ;IACZ,gCAAgC;IAChC,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAW;IAElC,iCAAiC;IACjC,OAAO,CAAC,IAAI,CAAQ;IAEpB,sDAAsD;IACtD,OAAO,CAAC,OAAO,CAAY;IAE3B,sBAAsB;IACtB,OAAO,CAAC,MAAM,CAAS;IAEvB,6BAA6B;IAC7B,OAAO,CAAC,MAAM,CAAiB;IAE/B;;;;;;;OAOG;IACH,OAAO;IAOP;;;;;;;OAOG;IACH,OAAO,CAAC,cAAc;IAuBtB;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;WACW,WAAW,CAAC,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,QAAQ;IA6B1E;;;;;OAKG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ;IAgChB;;;;;;OAMG;IACH,OAAO,CAAC,YAAY;IAUpB;;;;;;;;;;;;;;;;;OAiBG;IACG,SAAS,CACb,KAAK,EAAE,MAAM,GAAG,cAAc,EAC9B,MAAM,CAAC,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,WAAW,CAAC;IA6BvB;;;;;;;;;;;;;;;OAeG;IACG,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IA0BrE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,UAAU,CACd,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EAAE,EACjB,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,EAC/D,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IA6ChC;;;;;;;;;;;OAWG;IACH,OAAO,CAAE,gBAAgB;IAkBzB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAgBtB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,eAAe;IAIvB;;;;;;;;;;;;;;;;;;;;OAoBG;IACG,KAAK,CACT,KAAK,EAAE,MAAM,GAAG,cAAc,EAC9B,MAAM,CAAC,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,WAAW,CAAC;IAoBvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,WAAW,CACf,UAAU,EAAE,CAAC,MAAM,GAAG,cAAc,CAAC,EAAE,EACvC,WAAW,EAAE,GAAG,EAAE,EAAE,EACpB,YAAY,GAAE,UAAU,EAAO,GAC9B,OAAO,CAAC,WAAW,EAAE,CAAC;IAwEzB;;;;;;;;;;;;;;;;OAgBG;IACU,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAcnC;;;OAGG;IACI,WAAW,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI;CAI/C;AAED,eAAe,QAAQ,CAAC"}