@starbemtech/star-db-query-builder 1.1.0 → 1.2.1

package/src/db/__tests__/pgClient.test.ts

@@ -0,0 +1,260 @@
+import { createPgClient } from '../pgClient'
+import { Pool } from 'pg'
+
+// Mock pg module
+jest.mock('pg', () => ({
+  Pool: jest.fn(),
+}))
+
+// Mock monitor
+jest.mock('../../monitor/monitor', () => ({
+  monitor: {
+    emit: jest.fn(),
+  },
+  MonitorEvents: {
+    CONNECTION_CREATED: 'CONNECTION_CREATED',
+    QUERY_START: 'QUERY_START',
+    QUERY_END: 'QUERY_END',
+    QUERY_ERROR: 'QUERY_ERROR',
+    RETRY_ATTEMPT: 'RETRY_ATTEMPT',
+    TRANSACTION_COMMIT: 'TRANSACTION_COMMIT',
+    TRANSACTION_ROLLBACK: 'TRANSACTION_ROLLBACK',
+  },
+}))
+
+describe('PgClient', () => {
+  let mockPool: jest.Mocked<Pool>
+
+  beforeEach(() => {
+    mockPool = {
+      query: jest.fn(),
+      connect: jest.fn(),
+      end: jest.fn(),
+    } as any
+    ;(Pool as jest.MockedClass<typeof Pool>).mockImplementation(() => mockPool)
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+  })
+
+  describe('createPgClient', () => {
+    it('should return client with correct clientType', async () => {
+      const client = await createPgClient(mockPool)
+      expect(client.clientType).toBe('pg')
+    })
+
+    it('should execute query and return rows', async () => {
+      const mockRows = [{ id: 1, name: 'John Doe' }]
+      mockPool.query.mockResolvedValue({ rows: mockRows, rowCount: 1 } as any)
+      const client = await createPgClient(mockPool)
+      const result = await client.query('SELECT * FROM users WHERE id = $1', [
+        1,
+      ])
+      expect(mockPool.query).toHaveBeenCalledWith(
+        'SELECT * FROM users WHERE id = $1',
+        [1]
+      )
+      expect(result).toEqual(mockRows)
+    })
+
+    it('should handle query without parameters', async () => {
+      const mockRows = [{ id: 1, name: 'John Doe' }]
+      mockPool.query.mockResolvedValue({ rows: mockRows, rowCount: 1 } as any)
+      const client = await createPgClient(mockPool)
+      const result = await client.query('SELECT * FROM users')
+      expect(mockPool.query).toHaveBeenCalledWith(
+        'SELECT * FROM users',
+        undefined
+      )
+      expect(result).toEqual(mockRows)
+    })
+
+    it('should handle empty result set', async () => {
+      mockPool.query.mockResolvedValue({ rows: [], rowCount: 0 } as any)
+      const client = await createPgClient(mockPool)
+      const result = await client.query('SELECT * FROM users WHERE id = $1', [
+        999,
+      ])
+      expect(result).toEqual([])
+    })
+
+    it('should handle query errors', async () => {
+      const error = new Error('Database connection failed')
+      mockPool.query.mockRejectedValue(error)
+      const client = await createPgClient(mockPool)
+      await expect(client.query('SELECT * FROM users')).rejects.toThrow(
+        'Database connection failed'
+      )
+    })
+
+    it('should handle retry options', async () => {
+      const mockRows = [{ id: 1, name: 'John Doe' }]
+      mockPool.query.mockResolvedValue({ rows: mockRows, rowCount: 1 } as any)
+      const retryOptions = {
+        retries: 3,
+        factor: 2,
+        minTimeout: 1000,
+        maxTimeout: 5000,
+      }
+      const client = await createPgClient(mockPool, retryOptions)
+      const result = await client.query('SELECT * FROM users')
+      expect(result).toEqual(mockRows)
+    })
+
+    it('should handle transient errors with retry', async () => {
+      const transientError = new Error('Connection lost')
+      ;(transientError as any).code = 'ECONNRESET'
+      const mockRows = [{ id: 1, name: 'John Doe' }]
+      // First call fails with transient error, second succeeds
+      mockPool.query
+        .mockRejectedValueOnce(transientError)
+        .mockResolvedValueOnce({ rows: mockRows, rowCount: 1 } as any)
+      const retryOptions = {
+        retries: 3,
+        factor: 2,
+        minTimeout: 100,
+        maxTimeout: 500,
+      }
+      const client = await createPgClient(mockPool, retryOptions)
+      const result = await client.query('SELECT * FROM users')
+      expect(mockPool.query).toHaveBeenCalledTimes(2)
+      expect(result).toEqual(mockRows)
+    })
+
+    it('should throw non-transient errors immediately', async () => {
+      const permanentError = new Error('Table does not exist')
+      ;(permanentError as any).code = 'ER_NO_SUCH_TABLE'
+      mockPool.query.mockRejectedValue(permanentError)
+      const retryOptions = {
+        retries: 3,
+        factor: 2,
+        minTimeout: 100,
+        maxTimeout: 500,
+      }
+      const client = await createPgClient(mockPool, retryOptions)
+      await expect(
+        client.query('SELECT * FROM nonexistent_table')
+      ).rejects.toThrow('Table does not exist')
+      expect(mockPool.query).toHaveBeenCalledTimes(1)
+    })
+
+    it('should install unaccent extension when requested', async () => {
+      mockPool.query
+        .mockResolvedValueOnce({ rows: [], rowCount: 0 } as any) // Extension not found
+        .mockResolvedValueOnce({ rows: [], rowCount: 0 } as any) // Extension created
+        .mockResolvedValueOnce({ rows: [{ id: 1 }], rowCount: 1 } as any) // Query result
+      const client = await createPgClient(mockPool, undefined, undefined, true)
+      await client.query('SELECT * FROM users')
+      expect(mockPool.query).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "SELECT 1 FROM pg_extension WHERE extname = 'unaccent'"
+        )
+      )
+      expect(mockPool.query).toHaveBeenCalledWith(
+        expect.stringContaining('CREATE EXTENSION IF NOT EXISTS unaccent')
+      )
+    })
+
+    describe('beginTransaction', () => {
+      let mockClient: any
+
+      beforeEach(() => {
+        mockClient = {
+          query: jest.fn(),
+          release: jest.fn(),
+        }
+        mockPool.connect.mockResolvedValue(mockClient)
+      })
+
+      it('should create a transaction client', async () => {
+        const client = await createPgClient(mockPool)
+        const transaction = await client.beginTransaction()
+
+        expect(mockPool.connect).toHaveBeenCalled()
+        expect(mockClient.query).toHaveBeenCalledWith('BEGIN')
+        expect(transaction).toHaveProperty('query')
+        expect(transaction).toHaveProperty('commit')
+        expect(transaction).toHaveProperty('rollback')
+      })
+
+      it('should execute queries within transaction', async () => {
+        const mockRows = [{ id: 1, name: 'John Doe' }]
+        mockClient.query.mockResolvedValue({ rows: mockRows, rowCount: 1 })
+
+        const client = await createPgClient(mockPool)
+        const transaction = await client.beginTransaction()
+        const result = await transaction.query(
+          'SELECT * FROM users WHERE id = $1',
+          [1]
+        )
+
+        expect(mockClient.query).toHaveBeenCalledWith(
+          'SELECT * FROM users WHERE id = $1',
+          [1]
+        )
+        expect(result).toEqual(mockRows)
+      })
+
+      it('should commit transaction successfully', async () => {
+        const client = await createPgClient(mockPool)
+        const transaction = await client.beginTransaction()
+        await transaction.commit()
+
+        expect(mockClient.query).toHaveBeenCalledWith('COMMIT')
+        expect(mockClient.release).toHaveBeenCalled()
+      })
+
+      it('should rollback transaction on error', async () => {
+        const client = await createPgClient(mockPool)
+        const transaction = await client.beginTransaction()
+        await transaction.rollback()
+
+        expect(mockClient.query).toHaveBeenCalledWith('ROLLBACK')
+        expect(mockClient.release).toHaveBeenCalled()
+      })
+
+      it('should release connection even if commit fails', async () => {
+        const commitError = new Error('Commit failed')
+
+        // Mock the sequence: BEGIN succeeds, COMMIT fails
+        mockClient.query
+          .mockResolvedValueOnce({ rows: [], rowCount: 0 }) // BEGIN
+          .mockRejectedValueOnce(commitError) // COMMIT
+
+        const client = await createPgClient(mockPool)
+        const transaction = await client.beginTransaction()
+
+        await expect(transaction.commit()).rejects.toThrow('Commit failed')
+        expect(mockClient.release).toHaveBeenCalled()
+      })
+
+      it('should release connection even if rollback fails', async () => {
+        const rollbackError = new Error('Rollback failed')
+
+        // Mock the sequence: BEGIN succeeds, ROLLBACK fails
+        mockClient.query
+          .mockResolvedValueOnce({ rows: [], rowCount: 0 }) // BEGIN
+          .mockRejectedValueOnce(rollbackError) // ROLLBACK
+
+        const client = await createPgClient(mockPool)
+        const transaction = await client.beginTransaction()
+
+        await expect(transaction.rollback()).rejects.toThrow('Rollback failed')
+        expect(mockClient.release).toHaveBeenCalled()
+      })
+
+      it('should release connection if BEGIN fails', async () => {
+        const beginError = new Error('Begin transaction failed')
+        mockClient.query.mockRejectedValue(beginError)
+
+        const client = await createPgClient(mockPool)
+
+        await expect(client.beginTransaction()).rejects.toThrow(
+          'Begin transaction failed'
+        )
+        expect(mockClient.release).toHaveBeenCalled()
+      })
+    })
+  })
+})

package/src/db/initDb.ts

@@ -3,11 +3,58 @@ import { createPool as createMySqlPool } from 'mysql2/promise'
 import { createPgClient } from './pgClient'
 import { createMysqlClient } from './mysqlClient'
 import { IDatabaseClient } from './IDatabaseClient'
-import { DBClients, RetryOptions } from '../default/types'
+import { DBClients, RetryOptions } from '../core/types'
 
 const dbClients: Record<string, IDatabaseClient> = {}
 const defaultName = 'default'
 
+/**
+ * Initialize a database client with the specified configuration
+ *
+ * @template T - The type of connection options (PoolConfig for PostgreSQL or PoolOptions for MySQL)
+ * @param config - Configuration object for database initialization
+ * @param config.name - Optional name for the database client (defaults to 'default')
+ * @param config.type - Database type ('pg' for PostgreSQL or 'mysql' for MySQL)
+ * @param config.options - Connection options specific to the database type
+ * @param config.retryOptions - Optional retry configuration for failed queries
+ * @param config.installUnaccentExtension - Optional flag to install unaccent extension (PostgreSQL only)
+ * @returns Promise<void> - Resolves when the database client is successfully initialized
+ *
+ * @throws {Error} When type is not provided or is invalid
+ * @throws {Error} When connection options are not provided
+ * @throws {Error} When an unsupported database type is specified
+ *
+ * @example
+ * // Initialize PostgreSQL client
+ * await initDb({
+ *   name: 'myPostgresDb',
+ *   type: 'pg',
+ *   options: {
+ *     host: 'localhost',
+ *     port: 5432,
+ *     database: 'mydb',
+ *     user: 'user',
+ *     password: 'password'
+ *   },
+ *   retryOptions: { maxRetries: 3, delay: 1000 },
+ *   installUnaccentExtension: true
+ * });
+ *
+ * @example
+ * // Initialize MySQL client
+ * await initDb({
+ *   name: 'myMysqlDb',
+ *   type: 'mysql',
+ *   options: {
+ *     host: 'localhost',
+ *     port: 3306,
+ *     database: 'mydb',
+ *     user: 'user',
+ *     password: 'password'
+ *   },
+ *   retryOptions: { maxRetries: 3, delay: 1000 }
+ * });
+ */
 export const initDb = async <T>(config: {
   name?: string
   type: DBClients
@@ -48,6 +95,53 @@ export const initDb = async <T>(config: {
   }
 }
 
+/**
+ * Initialize a database client with the specified configuration
+ *
+ * @template T - The type of connection options (PoolConfig for PostgreSQL or PoolOptions for MySQL)
+ * @param config - Configuration object for database initialization
+ * @param config.name - Optional name for the database client (defaults to 'default')
+ * @param config.type - Database type ('pg' for PostgreSQL or 'mysql' for MySQL)
+ * @param config.options - Connection options specific to the database type
+ * @param config.retryOptions - Optional retry configuration for failed queries
+ * @param config.installUnaccentExtension - Optional flag to install unaccent extension (PostgreSQL only)
+ * @returns Promise<void> - Resolves when the database client is successfully initialized
+ *
+ * @throws {Error} When database type is not provided or is invalid
+ * @throws {Error} When connection options are not provided
+ * @throws {Error} When an unsupported database type is specified
+ *
+ * @example
+ * // Initialize PostgreSQL client
+ * await initDb({
+ *   name: 'myPostgresDb',
+ *   type: 'pg',
+ *   options: {
+ *     host: 'localhost',
+ *     port: 5432,
+ *     database: 'mydb',
+ *     user: 'user',
+ *     password: 'password'
+ *   },
+ *   retryOptions: { maxRetries: 3, delay: 1000 },
+ *   installUnaccentExtension: true
+ * });
+ *
+ * @example
+ * // Initialize MySQL client
+ * await initDb({
+ *   name: 'myMysqlDb',
+ *   type: 'mysql',
+ *   options: {
+ *     host: 'localhost',
+ *     port: 3306,
+ *     database: 'mydb',
+ *     user: 'user',
+ *     password: 'password'
+ *   },
+ *   retryOptions: { maxRetries: 3, delay: 1000 }
+ * });
+ */
 export const getDbClient = (name?: string): IDatabaseClient => {
   const client = dbClients[name || defaultName]
   if (!client) {
@@ -57,6 +151,31 @@ export const getDbClient = (name?: string): IDatabaseClient => {
   return client
 }
 
+/**
+ * Retrieves a specific database client by name
+ *
+ * @param name - Optional name of the database client to retrieve. If not provided, returns the default client
+ * @returns IDatabaseClient - The requested database client instance
+ *
+ * @throws {Error} When the specified database client name is not found or not initialized
+ *
+ * @example
+ * // Get default database client
+ * const defaultClient = getDbClient();
+ *
+ * @example
+ * // Get specific database client by name
+ * const postgresClient = getDbClient('myPostgresDb');
+ * const mysqlClient = getDbClient('myMysqlDb');
+ *
+ * @example
+ * // Handle error when client is not found
+ * try {
+ *   const client = getDbClient('nonExistentDb');
+ * } catch (error) {
+ *   console.error('Database client not found:', error.message);
+ * }
+ */
 export const getAllDbClients = (): Record<string, IDatabaseClient> => {
   return dbClients
 }

package/src/db/mysqlClient.ts

@@ -1,7 +1,7 @@
-import { Pool } from 'mysql2/promise'
+import { Pool, PoolConnection } from 'mysql2/promise'
 import promiseRetry from 'promise-retry'
-import { IDatabaseClient } from './IDatabaseClient'
-import { RetryOptions } from '../default/types'
+import { IDatabaseClient, ITransactionClient } from './IDatabaseClient'
+import { RetryOptions } from '../core/types'
 import { monitor, MonitorEvents } from '../monitor/monitor'
 
 const transientErrorCodes = new Set([
@@ -11,10 +11,55 @@ const transientErrorCodes = new Set([
   'ECONNREFUSED',
 ])
 
+/**
+ * Checks if the given error is a transient error that can be retried
+ *
+ * Transient errors are temporary network or connection issues that typically
+ * resolve themselves and can be safely retried. This function checks if the
+ * error code matches known transient error patterns for MySQL connections.
+ *
+ * @param error - The error object to check
+ * @returns boolean - True if the error is transient and can be retried, false otherwise
+ *
+ * @example
+ * try {
+ *   const result = await pool.execute(sql, params);
+ * } catch (error) {
+ *   if (isTransientError(error)) {
+ *     // Retry the operation
+ *     console.log('Transient error detected, retrying...');
+ *   } else {
+ *     // Handle permanent error
+ *     throw error;
+ *   }
+ * }
+ */
 function isTransientError(error: any): boolean {
   return error && error.code && transientErrorCodes.has(error.code)
 }
 
+/**
+ * Creates a MySQL database client
+ *
+ * This function initializes a MySQL database client with the provided pool configuration
+ * and optional retry options. It sets up monitoring for connection events and query operations.
+ *
+ * @param pool - The MySQL pool instance
+ * @param retryOptions - Optional retry options for failed queries
+ * @returns IDatabaseClient - The MySQL database client instance
+ *
+ * @example
+ * const mysqlClient = createMysqlClient(pool, { retries: 3, factor: 2, minTimeout: 1000 });
+ *
+ * @example
+ * const mysqlClient = createMysqlClient(pool, { retries: 3, factor: 2, minTimeout: 1000 });
+ *
+ * @example
+ * const mysqlClient = createMysqlClient(pool, { retries: 3, factor: 2, minTimeout: 1000 });
+ *
+ * @example
+ * const mysqlClient = createMysqlClient(pool, { retries: 3, factor: 2, minTimeout: 1000 });
+ */
 export const createMysqlClient = (
   pool: Pool,
   retryOptions?: RetryOptions
@@ -80,5 +125,76 @@ export const createMysqlClient = (
         }
       }, retryOptions)
     },
+    beginTransaction: async (): Promise<ITransactionClient> => {
+      const connection: PoolConnection = await pool.getConnection()
+
+      try {
+        await connection.beginTransaction()
+
+        return {
+          query: async <T>(sql: string, params?: any[]): Promise<T> => {
+            const startTime = Date.now()
+            try {
+              monitor.emit(MonitorEvents.QUERY_START, {
+                clientType: 'mysql',
+                sql,
+                params,
+                attempt: 1,
+                inTransaction: true,
+              })
+
+              const [rows] = await connection.execute(sql, params)
+
+              const elapsedTime = Date.now() - startTime
+              monitor.emit(MonitorEvents.QUERY_END, {
+                clientType: 'mysql',
+                sql,
+                params,
+                attempt: 1,
+                elapsedTime,
+                inTransaction: true,
+              })
+
+              return rows as unknown as T
+            } catch (error) {
+              const elapsedTime = Date.now() - startTime
+              monitor.emit(MonitorEvents.QUERY_ERROR, {
+                clientType: 'mysql',
+                sql,
+                params,
+                attempt: 1,
+                elapsedTime,
+                error,
+                inTransaction: true,
+              })
+              throw error
+            }
+          },
+          commit: async (): Promise<void> => {
+            try {
+              await connection.commit()
+              monitor.emit(MonitorEvents.TRANSACTION_COMMIT, {
+                clientType: 'mysql',
+              })
+            } finally {
+              connection.release()
+            }
+          },
+          rollback: async (): Promise<void> => {
+            try {
+              await connection.rollback()
+              monitor.emit(MonitorEvents.TRANSACTION_ROLLBACK, {
+                clientType: 'mysql',
+              })
+            } finally {
+              connection.release()
+            }
+          },
+        }
+      } catch (error) {
+        connection.release()
+        throw error
+      }
+    },
   }
 }

package/src/db/pgClient.ts

@@ -1,15 +1,51 @@
-import { Pool, PoolConfig } from 'pg'
+import { Pool, PoolConfig, PoolClient } from 'pg'
 import promiseRetry from 'promise-retry'
-import { IDatabaseClient } from './IDatabaseClient'
-import { RetryOptions } from '../default/types'
+import { IDatabaseClient, ITransactionClient } from './IDatabaseClient'
+import { RetryOptions } from '../core/types'
 import { monitor, MonitorEvents } from '../monitor/monitor'
 
 const transientErrorCodes = new Set(['ECONNRESET', 'ETIMEDOUT', 'ECONNREFUSED'])
 
+/**
+ * Checks if the given error is a transient error that can be retried
+ *
+ * Transient errors are temporary network or connection issues that typically
+ * resolve themselves and can be safely retried. This function checks if the
+ * error code matches known transient error patterns for PostgreSQL connections.
+ *
+ * @param error - The error object to check
+ * @returns boolean - True if the error is transient and can be retried, false otherwise
+ *
+ * @example
+ * try {
+ *   const result = await pool.query(sql, params);
+ * } catch (error) {
+ *   if (isTransientError(error)) {
+ *     // Retry the operation
+ *     console.log('Transient error detected, retrying...');
+ *   } else {
+ *     // Handle permanent error
+ *     throw error;
+ *   }
+ * }
+ */
 function isTransientError(error: any): boolean {
   return error && error.code && transientErrorCodes.has(error.code)
 }
 
+/**
+ * Ensures that the unaccent extension is installed in the PostgreSQL database
+ *
+ * This function checks if the unaccent extension is installed in the database
+ * and installs it if it is not. It also emits a connection created event to
+ * the monitor.
+ *
+ * @param pool - The PostgreSQL pool instance
+ * @returns Promise<void> - Resolves when the unaccent extension is installed or already exists
+ *
+ * @example
+ * await ensureUnaccentExtension(pool);
+ */
 async function ensureUnaccentExtension(pool: Pool): Promise<void> {
   try {
     const checkResult = await pool.query(`
@@ -42,6 +78,27 @@ async function ensureUnaccentExtension(pool: Pool): Promise<void> {
   }
 }
 
+/**
+ * Creates a PostgreSQL database client
+ *
+ * This function initializes a PostgreSQL database client with the provided pool configuration
+ * and optional retry options. It sets up monitoring for connection events and query operations.
+ *
+ * @param pool - The PostgreSQL pool instance
+ * @param retryOptions - Optional retry options for failed queries
+ * @param poolConfig - Optional pool configuration
+ * @param installUnaccentExtension - Optional flag to install unaccent extension
+ * @returns IDatabaseClient - The PostgreSQL database client instance
+ *
+ * @example
+ * const pgClient = await createPgClient(pool, { retries: 3, factor: 2, minTimeout: 1000 });
+ *
+ * @example
+ * const pgClient = await createPgClient(pool, { retries: 3, factor: 2, minTimeout: 1000 });
+ *
+ * @example
+ * const pgClient = await createPgClient(pool, { retries: 3, factor: 2, minTimeout: 1000 });
+ */
 export const createPgClient = async (
   pool: Pool,
   retryOptions?: RetryOptions,
@@ -114,5 +171,76 @@ export const createPgClient = async (
         }
       }, retryOptions)
     },
+    beginTransaction: async (): Promise<ITransactionClient> => {
+      const client: PoolClient = await pool.connect()
+
+      try {
+        await client.query('BEGIN')
+
+        return {
+          query: async <T>(sql: string, params?: any[]): Promise<T> => {
+            const startTime = Date.now()
+            try {
+              monitor.emit(MonitorEvents.QUERY_START, {
+                clientType: 'pg',
+                sql,
+                params,
+                attempt: 1,
+                inTransaction: true,
+              })
+
+              const { rows } = await client.query(sql, params)
+
+              const elapsedTime = Date.now() - startTime
+              monitor.emit(MonitorEvents.QUERY_END, {
+                clientType: 'pg',
+                sql,
+                params,
+                attempt: 1,
+                elapsedTime,
+                inTransaction: true,
+              })
+
+              return rows as unknown as T
+            } catch (error) {
+              const elapsedTime = Date.now() - startTime
+              monitor.emit(MonitorEvents.QUERY_ERROR, {
+                clientType: 'pg',
+                sql,
+                params,
+                attempt: 1,
+                elapsedTime,
+                error,
+                inTransaction: true,
+              })
+              throw error
+            }
+          },
+          commit: async (): Promise<void> => {
+            try {
+              await client.query('COMMIT')
+              monitor.emit(MonitorEvents.TRANSACTION_COMMIT, {
+                clientType: 'pg',
+              })
+            } finally {
+              client.release()
+            }
+          },
+          rollback: async (): Promise<void> => {
+            try {
+              await client.query('ROLLBACK')
+              monitor.emit(MonitorEvents.TRANSACTION_ROLLBACK, {
+                clientType: 'pg',
+              })
+            } finally {
+              client.release()
+            }
+          },
+        }
+      } catch (error) {
+        client.release()
+        throw error
+      }
+    },
   }
 }