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

package/src/{default → core}/types.ts

@@ -13,7 +13,7 @@ export interface QueryExec {
   values?: any[]
 }
 
-type SimpleValue = string | number | boolean | Date
+type SimpleValue = string | number | boolean | Date | null
 
 export interface OperatorCondition {
   operator:
@@ -55,7 +55,6 @@ export type DBClients = 'pg' | 'mysql'
 
 export type OrderBy = { field: string; direction: 'ASC' | 'DESC' }[]
 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
 export interface QueryParams<T> {
   tableName: string
   dbClient: IDatabaseClient
@@ -86,3 +85,13 @@ export interface QueryBuilder {
   limit?: string
   offset?: string
 }
+
+export interface RawQueryParams {
+  dbClient: IDatabaseClient
+  sql: string
+  params?: any[]
+}
+
+export interface TransactionParams {
+  dbClient: IDatabaseClient
+}

package/src/{default → core}/utils.ts

@@ -1,5 +1,22 @@
 import { Conditions, Condition, OrderBy, DBClients } from './types'
 
+/**
+ * Converts an array of strings to a comma-separated string with quotes
+ *
+ * This function takes an array of strings and converts it to a comma-separated string
+ * with quotes. It handles the differences between PostgreSQL and MySQL syntax for
+ * string arrays.
+ *
+ * @param items - The array of strings to convert
+ * @param clientType - The type of database client
+ * @returns A comma-separated string with quotes
+ *
+ * @example
+ * const items = ['item1', 'item2', 'item3']
+ * const clientType = 'pg'
+ * const result = arrayToStringWithQuotes(items, clientType)
+ * // result will be: 'item1', 'item2', 'item3'
+ */
 const arrayToStringWithQuotes = (
   items: string[],
   clientType: DBClients
@@ -10,9 +27,52 @@ const arrayToStringWithQuotes = (
   return itemsWithQuotes.join(', ')
 }
 
+/**
+ * Generates a PostgreSQL placeholder for a parameter
+ *
+ * This function generates a PostgreSQL placeholder for a parameter. It returns
+ * a string with a dollar sign and the index of the parameter.
+ *
+ * @param index - The index of the parameter
+ * @returns A PostgreSQL placeholder
+ *
+ * @example
+ * const index = 1
+ * const placeholder = pgPlaceholderGenerator(index)
+ * // placeholder will be: $1
+ */
 const pgPlaceholderGenerator = (index: number) => `$${index}`
+
+/**
+ * Generates a MySQL placeholder for a parameter
+ *
+ * This function generates a MySQL placeholder for a parameter. It returns
+ * a string with a question mark.
+ *
+ * @returns A MySQL placeholder
+ *
+ * @example
+ * const placeholder = mysqlPlaceholderGenerator()
+ * // placeholder will be: ?
+ */
 const mysqlPlaceholderGenerator = () => `?`
 
+/**
+ * Creates a SELECT clause for a query
+ *
+ * This function creates a SELECT clause for a query. It takes an array of fields
+ * and a database client type and returns a string with the fields separated by commas.
+ *
+ * @param fields - The array of fields to select
+ * @param clientType - The type of database client
+ * @returns A string with the fields separated by commas
+ *
+ * @example
+ * const fields = ['id', 'name', 'email']
+ * const clientType = 'pg'
+ * const result = createSelectFields(fields, clientType)
+ * // result will be: "id, name, email"
+ */
 export const createSelectFields = (
   fields: string[] = [],
   clientType: DBClients
@@ -22,6 +82,22 @@ export const createSelectFields = (
     : '*'
 }
 
+/**
+ * Generates placeholders for a query
+ *
+ * This function generates placeholders for a query. It takes an array of keys
+ * and a database client type and returns a string with the placeholders separated by commas.
+ *
+ * @param keys - The array of keys to generate placeholders for
+ * @param clientType - The type of database client
+ * @returns A string with the placeholders separated by commas
+ *
+ * @example
+ * const keys = ['id', 'name', 'email']
+ * const clientType = 'pg'
+ * const result = generatePlaceholders(keys, clientType)
+ * // result will be: $1, $2, $3
+ */
 export const generatePlaceholders = (
   keys: any[],
   clientType: DBClients
@@ -31,6 +107,22 @@ export const generatePlaceholders = (
     .join(', ')
 }
 
+/**
+ * Generates a SET clause for a query
+ *
+ * This function generates a SET clause for a query. It takes an array of keys
+ * and a database client type and returns a string with the keys and placeholders separated by commas.
+ *
+ * @param keys - The array of keys to generate SET clause for
+ * @param clientType - The type of database client
+ * @returns A string with the keys and placeholders separated by commas
+ *
+ * @example
+ * const keys = ['id', 'name', 'email']
+ * const clientType = 'pg'
+ * const result = generateSetClause(keys, clientType)
+ * // result will be: "id = $1, name = $2, email = $3"
+ */
 export const generateSetClause = (
   keys: any[],
   clientType: DBClients
@@ -42,6 +134,26 @@ export const generateSetClause = (
     .join(', ')
 }
 
+/**
+ * Creates a WHERE clause for a query
+ *
+ * This function creates a WHERE clause for a query. It takes an array of conditions
+ * and a database client type and returns a string with the conditions separated by AND.
+ *
+ * @param conditions - The array of conditions to create WHERE clause for
+ * @param startIndex - The index of the first parameter
+ * @param clientType - The type of database client
+ * @param unaccent - Whether to use unaccent function
+ * @returns A string with the conditions separated by AND
+ *
+ * @example
+ * const conditions = [{ field: 'name', operator: '=', value: 'John Doe' }]
+ * const startIndex = 1
+ * const clientType = 'pg'
+ * const unaccent = true
+ * const result = createWhereClause(conditions, startIndex, clientType, unaccent)
+ * // result will be: "name = $1"
+ */
 export const createWhereClause = <T>(
   conditions: Conditions<T> = {},
   startIndex = 1,
@@ -167,22 +279,78 @@ export const createWhereClause = <T>(
   return [whereClause, values, index]
 }
 
+/**
+ * Creates an ORDER BY clause for a query
+ *
+ * This function creates an ORDER BY clause for a query. It takes an array of
+ * order by fields and returns a string with the fields separated by commas.
+ *
+ * @param orderBy - The array of order by fields
+ * @returns A string with the fields separated by commas
+ *
+ * @example
+ * const orderBy = [{ field: 'created_at', direction: 'DESC' }]
+ * const result = createOrderByClause(orderBy)
+ * // result will be: "ORDER BY created_at DESC"
+ */
 export const createOrderByClause = (orderBy?: OrderBy) => {
   if (!orderBy || orderBy.length === 0) return ''
   const clause = orderBy.map((o) => `${o.field} ${o.direction}`).join(', ')
   return ` ORDER BY ${clause}`
 }
 
+/**
+ * Creates a GROUP BY clause for a query
+ *
+ * This function creates a GROUP BY clause for a query. It takes an array of
+ * group by fields and returns a string with the fields separated by commas.
+ *
+ * @param groupBy - The array of group by fields
+ * @returns A string with the fields separated by commas
+ *
+ * @example
+ * const groupBy = ['status']
+ * const result = createGroupByClause(groupBy)
+ * // result will be: "GROUP BY status"
+ */
 export const createGroupByClause = (groupBy?: string[]) => {
   if (!groupBy || groupBy.length === 0) return ''
   return ` GROUP BY ${groupBy.join(', ')}`
 }
 
+/**
+ * Creates a LIMIT clause for a query
+ *
+ * This function creates a LIMIT clause for a query. It takes a limit number
+ * and returns a string with the limit.
+ *
+ * @param limit - The limit number
+ * @returns A string with the limit
+ *
+ * @example
+ * const limit = 10
+ * const result = createLimitClause(limit)
+ * // result will be: "LIMIT 10"
+ */
 export const createLimitClause = (limit?: number) => {
   if (!limit) return ''
   return ` LIMIT ${limit}`
 }
 
+/**
+ * Creates an OFFSET clause for a query
+ *
+ * This function creates an OFFSET clause for a query. It takes an offset number
+ * and returns a string with the offset.
+ *
+ * @param offset - The offset number
+ * @returns A string with the offset
+ *
+ * @example
+ * const offset = 10
+ * const result = createOffsetClause(offset)
+ * // result will be: "OFFSET 10"
+ */
 export const createOffsetClause = (offset?: number) => {
   if (!offset) return ''
   return ` OFFSET ${offset}`

package/src/db/IDatabaseClient.ts

@@ -1,6 +1,16 @@
-import { DBClients } from '../default/types'
+import { DBClients } from '../core/types'
 
+export interface ITransactionClient {
+  query: <T>(sql: string, params?: any[]) => Promise<T>
+  commit: () => Promise<void>
+  rollback: () => Promise<void>
+}
+
+/**
+ * Database client interface
+ */
 export type IDatabaseClient = {
   clientType: DBClients
   query: <T>(sql: string, params?: any[]) => Promise<T>
+  beginTransaction: () => Promise<ITransactionClient>
 }

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

@@ -0,0 +1,262 @@
+import { createMysqlClient } from '../mysqlClient'
+import { createPool, Pool } from 'mysql2/promise'
+
+// Mock mysql2 module
+jest.mock('mysql2/promise', () => ({
+  createPool: 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('MySqlClient', () => {
+  let mockPool: jest.Mocked<Pool>
+
+  beforeEach(() => {
+    mockPool = {
+      query: jest.fn(),
+      connect: jest.fn(),
+      end: jest.fn(),
+      execute: jest.fn(),
+      getConnection: jest.fn(),
+      config: {},
+    } as any
+    ;(createPool as jest.MockedFunction<typeof createPool>).mockReturnValue(
+      mockPool
+    )
+  })
+
+  afterEach(() => {
+    jest.clearAllMocks()
+  })
+
+  describe('createMysqlClient', () => {
+    it('should return client with correct clientType', () => {
+      const client = createMysqlClient(mockPool)
+
+      expect(client.clientType).toBe('mysql')
+    })
+
+    it('should execute query and return rows', async () => {
+      const mockRows = [{ id: 1, name: 'John Doe' }]
+      mockPool.execute.mockResolvedValue([mockRows, []] as any)
+
+      const client = createMysqlClient(mockPool)
+      const result = await client.query('SELECT * FROM users WHERE id = ?', [1])
+
+      expect(mockPool.execute).toHaveBeenCalledWith(
+        'SELECT * FROM users WHERE id = ?',
+        [1]
+      )
+      expect(result).toEqual(mockRows)
+    })
+
+    it('should handle query without parameters', async () => {
+      const mockRows = [{ id: 1, name: 'John Doe' }]
+      mockPool.execute.mockResolvedValue([mockRows, []] as any)
+
+      const client = createMysqlClient(mockPool)
+      const result = await client.query('SELECT * FROM users')
+
+      expect(mockPool.execute).toHaveBeenCalledWith(
+        'SELECT * FROM users',
+        undefined
+      )
+      expect(result).toEqual(mockRows)
+    })
+
+    it('should handle empty result set', async () => {
+      mockPool.execute.mockResolvedValue([[], []] as any)
+
+      const client = createMysqlClient(mockPool)
+      const result = await client.query('SELECT * FROM users WHERE id = ?', [
+        999,
+      ])
+
+      expect(result).toEqual([])
+    })
+
+    it('should handle query errors', async () => {
+      const error = new Error('Database connection failed')
+      mockPool.execute.mockRejectedValue(error)
+
+      const client = createMysqlClient(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.execute.mockResolvedValue([mockRows, []] as any)
+
+      const retryOptions = {
+        retries: 3,
+        factor: 2,
+        minTimeout: 1000,
+        maxTimeout: 5000,
+      }
+
+      const client = createMysqlClient(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.execute
+        .mockRejectedValueOnce(transientError)
+        .mockResolvedValueOnce([mockRows, []] as any)
+
+      const retryOptions = {
+        retries: 3,
+        factor: 2,
+        minTimeout: 100,
+        maxTimeout: 500,
+      }
+
+      const client = createMysqlClient(mockPool, retryOptions)
+      const result = await client.query('SELECT * FROM users')
+
+      expect(mockPool.execute).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.execute.mockRejectedValue(permanentError)
+
+      const retryOptions = {
+        retries: 3,
+        factor: 2,
+        minTimeout: 100,
+        maxTimeout: 500,
+      }
+
+      const client = createMysqlClient(mockPool, retryOptions)
+
+      await expect(
+        client.query('SELECT * FROM nonexistent_table')
+      ).rejects.toThrow('Table does not exist')
+      expect(mockPool.execute).toHaveBeenCalledTimes(1)
+    })
+
+    describe('beginTransaction', () => {
+      let mockConnection: any
+
+      beforeEach(() => {
+        mockConnection = {
+          execute: jest.fn(),
+          beginTransaction: jest.fn(),
+          commit: jest.fn(),
+          rollback: jest.fn(),
+          release: jest.fn(),
+        }
+        mockPool.getConnection.mockResolvedValue(mockConnection)
+      })
+
+      it('should create a transaction client', async () => {
+        const client = createMysqlClient(mockPool)
+        const transaction = await client.beginTransaction()
+
+        expect(mockPool.getConnection).toHaveBeenCalled()
+        expect(mockConnection.beginTransaction).toHaveBeenCalled()
+        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' }]
+        mockConnection.execute.mockResolvedValue([mockRows, []])
+
+        const client = createMysqlClient(mockPool)
+        const transaction = await client.beginTransaction()
+        const result = await transaction.query(
+          'SELECT * FROM users WHERE id = ?',
+          [1]
+        )
+
+        expect(mockConnection.execute).toHaveBeenCalledWith(
+          'SELECT * FROM users WHERE id = ?',
+          [1]
+        )
+        expect(result).toEqual(mockRows)
+      })
+
+      it('should commit transaction successfully', async () => {
+        const client = createMysqlClient(mockPool)
+        const transaction = await client.beginTransaction()
+        await transaction.commit()
+
+        expect(mockConnection.commit).toHaveBeenCalled()
+        expect(mockConnection.release).toHaveBeenCalled()
+      })
+
+      it('should rollback transaction on error', async () => {
+        const client = createMysqlClient(mockPool)
+        const transaction = await client.beginTransaction()
+        await transaction.rollback()
+
+        expect(mockConnection.rollback).toHaveBeenCalled()
+        expect(mockConnection.release).toHaveBeenCalled()
+      })
+
+      it('should release connection even if commit fails', async () => {
+        const commitError = new Error('Commit failed')
+        mockConnection.commit.mockRejectedValue(commitError)
+
+        const client = createMysqlClient(mockPool)
+        const transaction = await client.beginTransaction()
+
+        await expect(transaction.commit()).rejects.toThrow('Commit failed')
+        expect(mockConnection.release).toHaveBeenCalled()
+      })
+
+      it('should release connection even if rollback fails', async () => {
+        const rollbackError = new Error('Rollback failed')
+        mockConnection.rollback.mockRejectedValue(rollbackError)
+
+        const client = createMysqlClient(mockPool)
+        const transaction = await client.beginTransaction()
+
+        await expect(transaction.rollback()).rejects.toThrow('Rollback failed')
+        expect(mockConnection.release).toHaveBeenCalled()
+      })
+
+      it('should release connection if beginTransaction fails', async () => {
+        const beginError = new Error('Begin transaction failed')
+        mockConnection.beginTransaction.mockRejectedValue(beginError)
+
+        const client = createMysqlClient(mockPool)
+
+        await expect(client.beginTransaction()).rejects.toThrow(
+          'Begin transaction failed'
+        )
+        expect(mockConnection.release).toHaveBeenCalled()
+      })
+    })
+  })
+})