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

package/README.md

@@ -1,385 +1,1450 @@
-# NodeJS Star DB Query Builder
+# Star DB Query Builder
+
+A powerful and flexible database query builder library for Node.js applications, supporting PostgreSQL and MySQL databases with TypeScript support.
+
+## Table of Contents
+
+- [Features](#-features)
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Database Initialization](#database-initialization)
+- [Query Methods](#query-methods)
+  - [findFirst](#findfirst)
+  - [findMany](#findmany)
+  - [insert](#insert)
+  - [insertMany](#insertmany)
+  - [update](#update)
+  - [updateMany](#updatemany)
+  - [deleteOne](#deleteone)
+  - [deleteMany](#deletemany)
+  - [joins](#joins)
+  - [rawQuery](#rawquery)
+- [Transactions](#transactions)
+  - [withTransaction](#withtransaction)
+  - [beginTransaction](#begintransaction)
+- [Types and Interfaces](#types-and-interfaces)
+- [Advanced Usage](#advanced-usage)
+- [Monitoring](#monitoring)
+- [Best Practices](#best-practices)
+- [Error Handling](#error-handling)
+- [Contributing](#contributing)
+- [License](#license)
+
+## ✨ Features
+
+### 🔧 **Core Functionality**
+
+- **🔄 Multi-Connection Support**: Connect simultaneously to multiple PostgreSQL and MySQL databases
+- **🛡️ Type Safety**: Complete TypeScript support with strong typing
+- **⚡ Auto Retry**: Automatic retry for transient errors (timeouts, lost connections)
+- **📊 Monitoring**: Event system for monitoring and logging
+- **🔍 Query Builder**: Fluent interface for building complex queries
+- **📦 Batch Operations**: Optimized batch operations (insertMany, updateMany)
+
+### 🗄️ **Database Support**
+
+- **PostgreSQL**: Complete support with extensions (unaccent)
+- **MySQL**: Full compatibility with MySQL 5.7+
+- **Connection Pooling**: Efficient connection management
+- **Transaction Support**: Full ACID transaction support with automatic rollback
+- **Raw SQL**: Execute custom SQL queries when needed
+
+### 🛠️ **Development Tools**
+
+- **ESLint + Prettier**: Clean and consistent code
+- **Jest**: Unit and integration tests
+- **Husky**: Git hooks for code quality
+- **TypeScript**: Compilation and typing
+
+## 📦 Installation
 
-🎉 Welcome to the NodeJS Database Library! This library provides a set of robust methods to interact with your database seamlessly. With TypeScript support, it ensures type safety and great developer experience.
+```bash
+npm install @starbemtech/star-db-query-builder
+# or
+pnpm add @starbemtech/star-db-query-builder
+# or
+yarn add @starbemtech/star-db-query-builder
+```
 
-## Features
+## Quick Start
 
-- **Multi-Connection Support:** Simultaneously connect to multiple MySQL and PostgreSQL databases.
-- **Automatic Retry:** Automatically retries queries in case of transient errors (e.g. connection loss or timeouts).
-- **External Configuration:** Customize connection pool settings and retry parameters through external configuration.
-- **Monitoring and Logging:** Emits events during the connection and query lifecycle, making it easier to integrate with your logging and monitoring systems.
+```typescript
+import {
+  initDb,
+  getDbClient,
+  findFirst,
+  insert,
+} from '@starbemtech/star-db-query-builder'
+
+// Initialize database connection
+await initDb({
+  type: 'pg', // or 'mysql'
+  options: {
+    host: 'localhost',
+    port: 5432,
+    database: 'myapp',
+    user: 'username',
+    password: 'password',
+  },
+})
 
-## Installation
+// Get database client
+const dbClient = getDbClient()
 
-```bash
-// Use npm
-$ npm install star-db-query-builder
-
-// Use yarn
-$ yarn add star-db-query-builder
+// Find a user
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: { email: { operator: '=', value: 'user@example.com' } },
+})
 
-// Use pnpm
-$ pnpm install star-db-query-builder
+// Insert a new user
+const newUser = await insert({
+  tableName: 'users',
+  dbClient,
+  data: { name: 'John Doe', email: 'john@example.com' },
+})
 ```
 
-## Usage
+## Database Initialization
 
-### Initialization
+### initDb
 
-First, initialize the database with the appropriate configuration.
+Initializes a database connection with the specified configuration.
 
 ```typescript
-import { initDb, getDbClient, PoolConfig } from 'star-db-query-builder';
+await initDb({
+  name?: string,                    // Optional client name (default: 'default')
+  type: 'pg' | 'mysql',            // Database type
+  options: PoolConfig | MySqlPoolOptions, // Connection options
+  retryOptions?: RetryOptions,      // Optional retry configuration
+  installUnaccentExtension?: boolean // PostgreSQL unaccent extension
+})
+```
 
-// Use PostgresSQL
-const pgPoolOptions: PoolConfig = {
-  host: process.env.PG_HOST,
-  user: process.env.PG_USER,
-  password: process.env.PG_PASS,
-  database: process.env.PG_DB,
-  // OR
-  connectionURL: 'YOUR POSTGRES CONNECTION URL'
-  max: Number(process.env.PG_POOL_MAX) || 10,
-  connectionTimeoutMillis: Number(process.env.PG_CONN_TIMEOUT) || 0,
-  // Other pool options as needed
-}
+#### PostgreSQL Example
 
-initDb({
-  name: 'pg-prod',
+```typescript
+import { initDb } from '@starbemtech/star-db-query-builder'
+
+await initDb({
+  name: 'main',
   type: 'pg',
-  options: pgPoolOptions,
+  options: {
+    host: 'localhost',
+    port: 5432,
+    database: 'myapp',
+    user: 'postgres',
+    password: 'password',
+    max: 20,
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: 2000,
+  },
   retryOptions: {
     retries: 3,
     factor: 2,
     minTimeout: 1000,
-    // Other retry parameters if needed
-  }
-});
+    maxTimeout: 5000,
+  },
+  installUnaccentExtension: true,
+})
+```
+
+#### MySQL Example
 
-// User MySQL
-initDb({
-  name: 'mysql-prod',
+```typescript
+import { initDb } from '@starbemtech/star-db-query-builder'
+
+await initDb({
+  name: 'analytics',
   type: 'mysql',
   options: {
-    host: process.env.MYSQL_HOST,
-    user: process.env.MYSQL_USER,
-    password: process.env.MYSQL_PASS,
-    database: process.env.MYSQL_DB,
-    connectionLimit: Number(process.env.MYSQL_CONN_LIMIT) || 10,
-    // OR
-    url: 'YOUR MYSQL CONNECTION URL'
-    // Other pool options as needed
+    host: 'localhost',
+    port: 3306,
+    database: 'analytics',
+    user: 'root',
+    password: 'password',
+    connectionLimit: 10,
+    acquireTimeout: 60000,
+    timeout: 60000,
   },
-  retryOptions: {
-    retries: 3,
-    factor: 2,
-    minTimeout: 1000,
-    // Other retry parameters if needed
-  }
-});
+})
+```
+
+### getDbClient
+
+Retrieves a database client by name.
+
+```typescript
+const dbClient = getDbClient(name?: string)
+```
+
+```typescript
+// Get default client
+const defaultClient = getDbClient()
 
-// In your service, create an instance of getDbClient
-const dbClient = getDbClient('pg-prod');
+// Get named client
+const analyticsClient = getDbClient('analytics')
 ```
 
-### Methods
+## Query Methods
 
-#### findFirst
+### findFirst
 
-Retrieve the first matching record from a table.
+Finds the first record that matches the specified conditions.
 
 ```typescript
-import { findFirst } from 'star-db-query-builder'
+const result = await findFirst<T>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  select?: string[],
+  where?: Conditions<T>,
+  groupBy?: string[],
+  orderBy?: OrderBy
+})
+```
+
+#### Examples
+
+```typescript
+// Find user by email
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: {
+    email: { operator: '=', value: 'user@example.com' },
+  },
+})
 
-const result = await findFirst({
+// Find with specific fields
+const user = await findFirst({
   tableName: 'users',
   dbClient,
   select: ['id', 'name', 'email'],
   where: {
-    id: { operator: '=', value: 1 },
+    status: { operator: '=', value: 'active' },
   },
 })
 
-console.log(result)
+// Find with complex conditions
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: {
+    AND: [
+      { email: { operator: '=', value: 'user@example.com' } },
+      { status: { operator: '=', value: 'active' } },
+    ],
+  },
+})
+
+// Find with ordering
+const latestUser = await findFirst({
+  tableName: 'users',
+  dbClient,
+  orderBy: [{ field: 'created_at', direction: 'DESC' }],
+})
 ```
 
-#### findMany
+### findMany
 
-Retrieve multiple records from a table.
+Finds multiple records that match the specified conditions.
 
 ```typescript
-import { findMany } from 'star-db-query-builder'
+const results = await findMany<T>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  select?: string[],
+  where?: Conditions<T>,
+  groupBy?: string[],
+  orderBy?: OrderBy,
+  limit?: number,
+  offset?: number,
+  unaccent?: boolean
+})
+```
+
+#### Examples
 
-const results = await findMany({
+```typescript
+// Find all active users
+const users = await findMany({
   tableName: 'users',
   dbClient,
-  select: ['id', 'name', 'email'],
   where: {
-    status: { operator: '= ', value: 'active' },
+    status: { operator: '=', value: 'active' },
   },
+})
+
+// Find with pagination
+const users = await findMany({
+  tableName: 'users',
+  dbClient,
   limit: 10,
-  offset: 0,
+  offset: 20,
+  orderBy: [{ field: 'created_at', direction: 'DESC' }],
+})
+
+// Find with complex conditions
+const users = await findMany({
+  tableName: 'users',
+  dbClient,
+  where: {
+    OR: [
+      { status: { operator: '=', value: 'active' } },
+      { status: { operator: '=', value: 'pending' } },
+    ],
+    created_at: {
+      operator: '>=',
+      value: new Date('2023-01-01'),
+    },
+  },
 })
 
-console.log(results)
+// Find with grouping
+const userStats = await findMany({
+  tableName: 'users',
+  dbClient,
+  select: ['status', 'COUNT(*) as count'],
+  groupBy: ['status'],
+})
 ```
 
-#### insert
+### insert
 
-Insert a new record into a table.
+Inserts a single record into the database.
 
 ```typescript
-import { insert } from 'star-db-query-builder'
+const result = await insert<P, R>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  data: P,
+  returning?: string[]
+})
+```
 
-const newUser = { name: 'John Doe', email: 'john@example.com' }
+#### Examples
 
-const insertedUser = await insert({
+```typescript
+// Simple insert
+const user = await insert({
   tableName: 'users',
   dbClient,
-  data: newUser,
-  returning: ['id', 'name', 'email'],
+  data: {
+    name: 'John Doe',
+    email: 'john@example.com',
+    age: 30,
+  },
+})
+
+// Insert with specific returning fields
+const user = await insert({
+  tableName: 'users',
+  dbClient,
+  data: {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  },
+  returning: ['id', 'name', 'email', 'created_at'],
 })
 
-console.log(insertedUser)
+// Insert with TypeScript typing
+interface UserData {
+  name: string
+  email: string
+  age: number
+}
+
+interface User {
+  id: string
+  name: string
+  email: string
+  age: number
+  created_at: Date
+  updated_at: Date
+}
+
+const user: User = await insert<UserData, User>({
+  tableName: 'users',
+  dbClient,
+  data: {
+    name: 'John Doe',
+    email: 'john@example.com',
+    age: 30,
+  },
+})
 ```
 
-#### update
+### insertMany
 
-Update an existing record in a table.
+Inserts multiple records into the database in a single operation.
 
 ```typescript
-import { update } from 'star-db-query-builder'
+const results = await insertMany<P, R>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  data: P[],
+  returning?: string[]
+})
+```
 
-const updatedUser = { name: 'John Smith' }
+#### Examples
 
-const result = await update({
+```typescript
+// Insert multiple users
+const users = await insertMany({
+  tableName: 'users',
+  dbClient,
+  data: [
+    { name: 'John Doe', email: 'john@example.com' },
+    { name: 'Jane Doe', email: 'jane@example.com' },
+    { name: 'Bob Smith', email: 'bob@example.com' },
+  ],
+})
+
+// Insert with returning fields
+const users = await insertMany({
   tableName: 'users',
   dbClient,
-  id: 1,
-  data: updatedUser,
+  data: [
+    { name: 'John Doe', email: 'john@example.com' },
+    { name: 'Jane Doe', email: 'jane@example.com' },
+  ],
   returning: ['id', 'name', 'email'],
 })
+```
+
+### update
+
+Updates a single record by ID.
+
+```typescript
+const result = await update<P, R>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  id: string,
+  data: P,
+  returning?: string[]
+})
+```
 
-console.log(result)
+#### Examples
+
+```typescript
+// Simple update
+const updatedUser = await update({
+  tableName: 'users',
+  dbClient,
+  id: 'user-123',
+  data: {
+    name: 'John Updated',
+    age: 31,
+  },
+})
+
+// Update with returning fields
+const updatedUser = await update({
+  tableName: 'users',
+  dbClient,
+  id: 'user-123',
+  data: {
+    status: 'active',
+    last_login: new Date(),
+  },
+  returning: ['id', 'status', 'last_login', 'updated_at'],
+})
 ```
 
-#### deleteOne
+### updateMany
 
-Delete a record from a table.
+Updates multiple records based on specified conditions.
 
 ```typescript
-import { deleteOne } from 'star-db-query-builder'
+const results = await updateMany<P, R>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  data: P,
+  where: Conditions<T>,
+  returning?: string[]
+})
+```
+
+#### Examples
+
+```typescript
+// Update all inactive users
+const updatedUsers = await updateMany({
+  tableName: 'users',
+  dbClient,
+  data: {
+    status: 'active',
+    updated_at: new Date(),
+  },
+  where: {
+    status: { operator: '=', value: 'inactive' },
+  },
+})
+
+// Update with complex conditions
+const updatedUsers = await updateMany({
+  tableName: 'users',
+  dbClient,
+  data: {
+    last_login: new Date(),
+    login_count: { operator: '+', value: 1 },
+  },
+  where: {
+    AND: [
+      { status: { operator: '=', value: 'active' } },
+      { last_login: { operator: '<', value: new Date('2023-01-01') } },
+    ],
+  },
+  returning: ['id', 'name', 'last_login', 'login_count'],
+})
+```
+
+### deleteOne
 
+Deletes a single record by ID (soft delete by default).
+
+```typescript
+await deleteOne<T>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  id: string,
+  permanently?: boolean
+})
+```
+
+#### Examples
+
+```typescript
+// Soft delete (sets status to 'deleted')
 await deleteOne({
   tableName: 'users',
   dbClient,
-  id: 1,
-  permanently: true,
+  id: 'user-123',
 })
 
-console.log('User deleted')
+// Permanent delete
+await deleteOne({
+  tableName: 'users',
+  dbClient,
+  id: 'user-123',
+  permanently: true,
+})
 ```
 
-#### joins
+### deleteMany
+
+Deletes multiple records by IDs (soft delete by default).
+
+```typescript
+await deleteMany<T>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  ids: string[] | number[],
+  field?: string,
+  permanently?: boolean
+})
+```
 
-Execute a join query.
+#### Examples
 
 ```typescript
-import { joins } from 'star-db-query-builder'
+// Soft delete multiple users
+await deleteMany({
+  tableName: 'users',
+  dbClient,
+  ids: ['user-1', 'user-2', 'user-3'],
+})
 
-const joinResults = await joins({
+// Permanent delete with custom field
+await deleteMany({
   tableName: 'orders',
   dbClient,
-  select: ['orders.id', 'users.name'],
+  ids: [1, 2, 3],
+  field: 'order_id',
+  permanently: true,
+})
+```
+
+### joins
+
+Executes queries with JOIN operations.
+
+```typescript
+const results = await joins<T>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  select: string[],
+  joins: JoinClause[],
+  where?: Conditions<T>,
+  groupBy?: string[],
+  orderBy?: OrderBy,
+  limit?: number,
+  offset?: number,
+  unaccent?: boolean
+})
+```
+
+#### Examples
+
+```typescript
+// Simple JOIN
+const usersWithOrders = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.id', 'users.name', 'orders.total'],
   joins: [
     {
-      table: 'users',
-      on: { 'orders.userId': 'users.id' },
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
     },
   ],
   where: {
-    JOINS: [
-      {
-        'users.id': { operator: '=', value: exist.user_id },
-      },
-    ],
+    'users.status': { operator: '=', value: 'active' },
   },
 })
 
-console.log(joinResults)
+// Multiple JOINs
+const report = await joins({
+  tableName: 'users',
+  dbClient,
+  select: [
+    'users.name',
+    'users.email',
+    'COUNT(orders.id) as order_count',
+    'SUM(orders.total) as total_spent',
+    'plans.name as plan_name',
+  ],
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+    {
+      type: 'LEFT',
+      table: 'user_plans',
+      on: 'users.id = user_plans.user_id',
+    },
+    {
+      type: 'LEFT',
+      table: 'plans',
+      on: 'user_plans.plan_id = plans.id',
+    },
+  ],
+  groupBy: ['users.id', 'users.name', 'users.email', 'plans.name'],
+  having: {
+    'COUNT(orders.id)': { operator: '>', value: 0 },
+  },
+  orderBy: [{ field: 'total_spent', direction: 'DESC' }],
+})
 ```
 
-#### insertMany
+### rawQuery
 
-Insert multiple records into a table at once, optimizing performance for batch operations.
+Executes raw SQL queries directly on the database.
 
-#### Parameters
-
-- `tableName`: Name of the table
-- `dbClient`: Database client (PostgreSQL or MySQL)
-- `data`: Array of objects with the data to be inserted
-- `returning` (optional): Array of fields to be returned after insertion
+```typescript
+const result = await rawQuery<T>({
+  dbClient: IDatabaseClient,
+  sql: string,
+  params?: any[]
+})
+```
 
-#### Usage Example
+#### Examples
 
 ```typescript
-import { insertMany } from 'star-db-query-builder'
+// Simple raw query
+const users = await rawQuery({
+  dbClient,
+  sql: 'SELECT * FROM users WHERE active = true',
+})
 
-// Data for insertion
-const usersData = [
-  { name: 'João Silva', email: 'joao@example.com', age: 30 },
-  { name: 'Maria Santos', email: 'maria@example.com', age: 25 },
-  { name: 'Pedro Costa', email: 'pedro@example.com', age: 35 },
-]
+// Raw query with parameters
+const user = await rawQuery({
+  dbClient,
+  sql: 'SELECT * FROM users WHERE id = ? AND email = ?',
+  params: ['user-123', 'user@example.com'],
+})
 
-// Insert multiple users
-const insertedUsers = await insertMany({
-  tableName: 'users',
-  dbClient: dbClient,
-  data: usersData,
-  returning: ['id', 'name', 'email', 'created_at'],
+// Complex aggregation
+const stats = await rawQuery({
+  dbClient,
+  sql: `
+    SELECT 
+      COUNT(*) as total_users,
+      AVG(age) as avg_age,
+      MAX(created_at) as last_created
+    FROM users 
+    WHERE created_at >= ?
+  `,
+  params: [new Date('2023-01-01')],
 })
+```
+
+## Transactions
+
+Execute multiple database operations within a single transaction to ensure data consistency and atomicity.
+
+### withTransaction
 
-console.log('Users inserted:', insertedUsers)
+Executes a function within a database transaction with automatic commit/rollback handling.
+
+```typescript
+const result = await withTransaction<T>(
+  dbClient: IDatabaseClient,
+  transactionFn: (tx: ITransactionClient) => Promise<T>
+): Promise<T>
 ```
 
-#### Features
+#### Examples
 
-- **Automatic UUID Generation**: Each record receives a unique ID automatically
-- **Automatic Timestamp**: The `updated_at` field is filled automatically
-- **Support for PostgreSQL and MySQL**: Works with both databases
-- **Data Return**: Can return specific fields after insertion
-- **Optimized Performance**: Uses a single query to insert all records
+```typescript
+import {
+  withTransaction,
+  insert,
+  update,
+} from '@starbemtech/star-db-query-builder'
+
+// Create user with profile in a single transaction
+const createUserWithProfile = async (userData: any, profileData: any) => {
+  return withTransaction(dbClient, async (tx) => {
+    // Create user
+    const user = await insert({
+      tableName: 'users',
+      dbClient: tx,
+      data: userData,
+    })
+
+    // Create user profile
+    const profile = await insert({
+      tableName: 'user_profiles',
+      dbClient: tx,
+      data: {
+        ...profileData,
+        user_id: user.id,
+      },
+    })
 
-#### Database Behavior
+    return { user, profile }
+  })
+}
 
-**PostgreSQL**: Uses the `RETURNING` clause to return inserted data
-**MySQL**: Executes a separate query to fetch inserted records
+// E-commerce order processing
+const processOrder = async (orderData: any, orderItems: any[]) => {
+  return withTransaction(dbClient, async (tx) => {
+    // Create order
+    const order = await insert({
+      tableName: 'orders',
+      dbClient: tx,
+      data: {
+        ...orderData,
+        status: 'pending',
+        total: 0,
+      },
+    })
+
+    let totalAmount = 0
+
+    // Create order items and calculate total
+    for (const item of orderItems) {
+      await insert({
+        tableName: 'order_items',
+        dbClient: tx,
+        data: {
+          ...item,
+          order_id: order.id,
+        },
+      })
+
+      totalAmount += item.price * item.quantity
+
+      // Update product stock
+      await update({
+        tableName: 'products',
+        dbClient: tx,
+        id: item.product_id,
+        data: {
+          stock: { operator: '-', value: item.quantity },
+        },
+      })
+    }
+
+    // Update order total
+    await update({
+      tableName: 'orders',
+      dbClient: tx,
+      id: order.id,
+      data: {
+        total: totalAmount,
+        status: 'confirmed',
+      },
+    })
 
-#### Validations
+    return { order, totalAmount }
+  })
+}
+```
 
-- Checks if the table name was provided
-- Checks if the database client was provided
-- Checks if the data array is not empty
-- Ensures that all items have the same structure of fields
+### beginTransaction
 
-#### updateMany
+Creates a transaction client for manual transaction management.
 
-Updates multiple records in a table based on a where condition, optimizing performance for batch operations.
+```typescript
+const transaction = await beginTransaction(dbClient: IDatabaseClient): Promise<ITransactionClient>
+```
 
-#### Parameters
+#### Examples
 
-- `tableName`: Name of the table
-- `dbClient`: Database client (PostgreSQL or MySQL)
-- `data`: Object with the data to be updated
-- `where`: Where condition to filter which records to update
-- `returning` (optional): Array of fields to be returned after update
+```typescript
+import {
+  beginTransaction,
+  insert,
+  update,
+} from '@starbemtech/star-db-query-builder'
+
+// Manual transaction management
+const complexOperation = async () => {
+  const transaction = await beginTransaction(dbClient)
+
+  try {
+    // First operation
+    const user = await insert({
+      tableName: 'users',
+      dbClient: transaction,
+      data: { name: 'John Doe', email: 'john@example.com' },
+    })
+
+    // Second operation
+    const profile = await insert({
+      tableName: 'user_profiles',
+      dbClient: transaction,
+      data: { user_id: user.id, bio: 'Hello world' },
+    })
+
+    // Third operation
+    await update({
+      tableName: 'users',
+      dbClient: transaction,
+      id: user.id,
+      data: { profile_created: true },
+    })
+
+    // Commit all changes
+    await transaction.commit()
+    return { user, profile }
+  } catch (error) {
+    // Rollback on any error
+    await transaction.rollback()
+    throw error
+  }
+}
+```
 
-#### Usage Example
+### ITransactionClient Interface
 
 ```typescript
-import { updateMany } from 'star-db-query-builder'
+interface ITransactionClient {
+  query: <T>(sql: string, params?: any[]) => Promise<T>
+  commit: () => Promise<void>
+  rollback: () => Promise<void>
+}
+```
+
+## Types and Interfaces
+
+### Conditions
+
+Used for building WHERE clauses with type safety.
 
-// Update data
-const updateData = {
-  status: 'active',
-  updated_at: new Date(),
+```typescript
+type Conditions<T> = {
+  [P in keyof T]?: Condition<T[P]>
+} & LogicalCondition<T>
+
+type Condition<T> = OperatorCondition | LogicalCondition<T>
+
+interface OperatorCondition {
+  operator:
+    | '='
+    | '!='
+    | '>'
+    | '<'
+    | '>='
+    | '<='
+    | 'LIKE'
+    | 'NOT LIKE'
+    | 'ILIKE'
+    | 'IN'
+    | 'NOT IN'
+    | 'BETWEEN'
+    | 'IS NULL'
+    | 'IS NOT NULL'
+    | 'NOT EXISTS'
+  value: SimpleValue | SimpleValue[]
 }
 
-// Where condition
-const whereCondition = {
-  status: { operator: '=', value: 'pending' },
-  created_at: { operator: '<', value: new Date('2024-01-01') },
+interface LogicalCondition<T> {
+  OR?: Conditions<T>[]
+  AND?: Conditions<T>[]
+  JOINS?: Conditions<object>
+  notExists?: OperatorCondition
 }
+```
 
-// Update multiple users
-const updatedUsers = await updateMany({
-  tableName: 'users',
-  dbClient: dbClient,
-  data: updateData,
-  where: whereCondition,
-  returning: ['id', 'name', 'email', 'status', 'updated_at'],
-})
+### OrderBy
+
+Used for specifying sort order.
 
-console.log('Users updated:', updatedUsers)
+```typescript
+type OrderBy = { field: string; direction: 'ASC' | 'DESC' }[]
+```
+
+### JoinClause
+
+Used for JOIN operations.
+
+```typescript
+interface JoinClause {
+  type: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL'
+  table: string
+  on: string
+}
 ```
 
-#### Features
+## Advanced Usage
 
-- **Batch Update**: Updates multiple records with a single query
-- **Conditional Update**: Uses where conditions to filter which records to update
-- **Support for PostgreSQL and MySQL**: Works with both databases
-- **Data Return**: Can return specific fields after the update
-- **Optimized Performance**: Uses a single query to update all matching records
+### Complex WHERE Conditions
 
-#### Database Behavior
+```typescript
+const users = await findMany({
+  tableName: 'users',
+  dbClient,
+  where: {
+    AND: [
+      { status: { operator: '=', value: 'active' } },
+      {
+        OR: [
+          { age: { operator: '>=', value: 18 } },
+          { verified: { operator: '=', value: true } },
+        ],
+      },
+      { created_at: { operator: '>=', value: new Date('2023-01-01') } },
+    ],
+  },
+})
+```
 
-**PostgreSQL**: Uses the `RETURNING` clause to return updated data
-**MySQL**: Executes a separate query to fetch updated records
+### Using Unaccent for PostgreSQL
 
-#### Validations
+```typescript
+const users = await findMany({
+  tableName: 'users',
+  dbClient,
+  where: {
+    name: { operator: 'ILIKE', value: '%joão%' },
+  },
+  unaccent: true, // Enables unaccent search
+})
+```
 
-- Checks if the table name was provided
-- Checks if the database client was provided
-- Checks if the data object was provided
-- Checks if the where condition was provided
+### Using Unaccent for PostgreSQL
 
-### Monitoring and Logging
+```typescript
+const users = await findMany({
+  tableName: 'users',
+  dbClient,
+  where: {
+    name: { operator: 'ILIKE', value: '%joão%' },
+  },
+  unaccent: true, // Enables unaccent search
+})
+```
 
-The library provides a monitoring module that emits key events during the lifecycle of connections and queries. You can subscribe to these events to integrate with your logging or monitoring system.
+## Monitoring
 
-#### Available Events
+The library provides a comprehensive monitoring system to track database operations and performance.
 
-CONNECTION_CREATED: Emitted when a new connection (pool) is established.
-QUERY_START: Emitted just before a query starts executing.
-QUERY_END: Emitted after a query completes, including its execution time.
-QUERY_ERROR: Emitted when an error occurs during query execution.
-RETRY_ATTEMPT: Emitted when a query is retried due to a transient error.
+### Monitor Events
 
-```ts
+```typescript
 import { monitor, MonitorEvents } from '@starbemtech/star-db-query-builder'
 
+// Monitor connection events
 monitor.on(MonitorEvents.CONNECTION_CREATED, (data) => {
-  console.log('Connection created:', data)
+  console.log('Database connection created:', data)
 })
 
+// Monitor query events
 monitor.on(MonitorEvents.QUERY_START, (data) => {
-  console.log('Query started:', data)
+  console.log('Query started:', {
+    sql: data.sql,
+    params: data.params,
+    clientType: data.clientType,
+    attempt: data.attempt,
+  })
 })
 
 monitor.on(MonitorEvents.QUERY_END, (data) => {
-  console.log('Query finished:', data)
+  console.log('Query completed:', {
+    elapsedTime: data.elapsedTime,
+    clientType: data.clientType,
+  })
 })
 
 monitor.on(MonitorEvents.QUERY_ERROR, (data) => {
-  console.error('Query error:', data)
+  console.error('Query failed:', {
+    error: data.error,
+    sql: data.sql,
+    elapsedTime: data.elapsedTime,
+  })
 })
 
+// Monitor transaction events
+monitor.on(MonitorEvents.TRANSACTION_COMMIT, (data) => {
+  console.log('Transaction committed:', data)
+})
+
+monitor.on(MonitorEvents.TRANSACTION_ROLLBACK, (data) => {
+  console.log('Transaction rolled back:', data)
+})
+
+// Monitor retry attempts
 monitor.on(MonitorEvents.RETRY_ATTEMPT, (data) => {
-  console.warn('Retrying query:', data)
+  console.warn('Retry attempt:', {
+    attempt: data.attempt,
+    error: data.error,
+    sql: data.sql,
+  })
+})
+```
+
+### Custom Monitoring Implementation
+
+```typescript
+// Example: Log all database operations to a file
+import fs from 'fs'
+import path from 'path'
+
+const logFile = path.join(__dirname, 'database.log')
+
+monitor.on(MonitorEvents.QUERY_START, (data) => {
+  const logEntry = {
+    timestamp: new Date().toISOString(),
+    event: 'QUERY_START',
+    sql: data.sql,
+    params: data.params,
+    clientType: data.clientType,
+  }
+
+  fs.appendFileSync(logFile, JSON.stringify(logEntry) + '\n')
+})
+
+monitor.on(MonitorEvents.QUERY_END, (data) => {
+  const logEntry = {
+    timestamp: new Date().toISOString(),
+    event: 'QUERY_END',
+    elapsedTime: data.elapsedTime,
+    clientType: data.clientType,
+  }
+
+  fs.appendFileSync(logFile, JSON.stringify(logEntry) + '\n')
 })
 ```
 
-## Customizing the Retry Strategy
+### Performance Monitoring
+
+```typescript
+// Track slow queries
+monitor.on(MonitorEvents.QUERY_END, (data) => {
+  if (data.elapsedTime > 1000) {
+    // Queries taking more than 1 second
+    console.warn('Slow query detected:', {
+      sql: data.sql,
+      elapsedTime: data.elapsedTime,
+      clientType: data.clientType,
+    })
+  }
+})
 
-The automatic retry mechanism leverages the promise-retry library. You can customize the following parameters:
+// Track connection pool usage
+monitor.on(MonitorEvents.CONNECTION_CREATED, (data) => {
+  console.log('Connection pool status:', {
+    clientType: data.clientType,
+    poolOptions: data.poolOptions,
+  })
+})
+```
 
-- retries: Number of retry attempts.
-- factor: Exponential backoff factor.
-- minTimeout: Minimum time (in milliseconds) to wait between retry attempts.
+## Best Practices
 
-These parameters are passed via the retryOptions property when initializing the connection.
+### 1. Use TypeScript Types
+
+```typescript
+interface User {
+  id: string
+  name: string
+  email: string
+  created_at: Date
+}
+
+const users: User[] = await findMany<User>({
+  tableName: 'users',
+  dbClient,
+  where: { status: { operator: '=', value: 'active' } },
+})
+```
+
+### 2. Use Specific Field Selection
+
+```typescript
+// Good: Select only needed fields
+const users = await findMany({
+  tableName: 'users',
+  dbClient,
+  select: ['id', 'name', 'email'],
+  where: { status: { operator: '=', value: 'active' } },
+})
+
+// Avoid: Selecting all fields when not needed
+const users = await findMany({
+  tableName: 'users',
+  dbClient,
+  where: { status: { operator: '=', value: 'active' } },
+})
+```
+
+### 3. Use Pagination for Large Datasets
+
+```typescript
+const users = await findMany({
+  tableName: 'users',
+  dbClient,
+  limit: 50,
+  offset: 0,
+  orderBy: [{ field: 'created_at', direction: 'DESC' }],
+})
+```
+
+### 4. Use Batch Operations When Possible
+
+```typescript
+// Good: Batch insert
+const users = await insertMany({
+  tableName: 'users',
+  dbClient,
+  data: userArray,
+})
+
+// Avoid: Multiple individual inserts
+for (const user of userArray) {
+  await insert({ tableName: 'users', dbClient, data: user })
+}
+```
+
+### 5. Handle Errors Properly
+
+```typescript
+try {
+  const user = await findFirst({
+    tableName: 'users',
+    dbClient,
+    where: { email: { operator: '=', value: 'user@example.com' } },
+  })
+} catch (error) {
+  console.error('Database error:', error.message)
+  // Handle error appropriately
+}
+```
+
+### 6. Use Raw Queries Sparingly
+
+```typescript
+// Use built-in methods when possible
+const users = await findMany({
+  tableName: 'users',
+  dbClient,
+  where: { status: { operator: '=', value: 'active' } },
+})
+
+// Use rawQuery only for complex operations
+const complexStats = await rawQuery({
+  dbClient,
+  sql: 'SELECT ... complex aggregation ...',
+})
+```
+
+### 7. Use Transactions for Data Consistency
+
+```typescript
+// Good: Use transactions for related operations
+const createUserWithProfile = async (userData: any, profileData: any) => {
+  return withTransaction(dbClient, async (tx) => {
+    const user = await insert({
+      tableName: 'users',
+      dbClient: tx,
+      data: userData,
+    })
+
+    await insert({
+      tableName: 'user_profiles',
+      dbClient: tx,
+      data: { ...profileData, user_id: user.id },
+    })
+
+    return user
+  })
+}
+
+// Avoid: Multiple separate operations without transactions
+const badUserCreation = async (userData: any, profileData: any) => {
+  const user = await insert({
+    tableName: 'users',
+    dbClient,
+    data: userData,
+  })
+
+  // If this fails, the user will be created but profile won't
+  await insert({
+    tableName: 'user_profiles',
+    dbClient,
+    data: { ...profileData, user_id: user.id },
+  })
+
+  return user
+}
+```
+
+### 8. Keep Transactions Short
+
+```typescript
+// Good: Short, focused transaction
+const updateUserStatus = async (userId: string, status: string) => {
+  return withTransaction(dbClient, async (tx) => {
+    await update({
+      tableName: 'users',
+      dbClient: tx,
+      id: userId,
+      data: { status },
+    })
+
+    await insert({
+      tableName: 'user_status_history',
+      dbClient: tx,
+      data: { user_id: userId, status, changed_at: new Date() },
+    })
+  })
+}
+
+// Avoid: Long-running transactions
+const badTransaction = async () => {
+  return withTransaction(dbClient, async (tx) => {
+    // ... many operations
+    await someSlowOperation() // This could timeout
+    // ... more operations
+  })
+}
+```
+
+## Error Handling
+
+The library throws descriptive errors for common issues:
+
+### Common Errors
+
+- `Table name is required`
+- `DB client is required`
+- `Data object is required`
+- `ID is required`
+- `Where condition is required`
+- `Raw query execution failed: [database message]`
+- `Transaction execution failed: [database message]`
+
+### Transaction Error Handling
+
+```typescript
+import {
+  withTransaction,
+  insert,
+  update,
+} from '@starbemtech/star-db-query-builder'
+
+const safeTransaction = async () => {
+  try {
+    return await withTransaction(dbClient, async (tx) => {
+      // Transaction operations
+      const result = await someOperation(tx)
+      return result
+    })
+  } catch (error) {
+    // Transaction was automatically rolled back
+    console.error('Transaction failed:', error.message)
+
+    // Handle specific error types
+    if (error.message.includes('deadlock detected')) {
+      // Handle deadlock - you might want to retry
+      console.warn('Deadlock detected, retrying...')
+      // Implement retry logic
+    } else if (error.message.includes('serialization failure')) {
+      // Handle serialization failure
+      console.warn('Serialization failure, retrying...')
+      // Implement retry logic
+    } else if (error.message.includes('connection lost')) {
+      // Handle connection issues
+      console.error('Database connection lost')
+      // Implement reconnection logic
+    } else {
+      // Handle other errors
+      console.error('Transaction error:', error.message)
+    }
+
+    throw error
+  }
+}
+```
+
+### Retry Logic for Transient Errors
+
+```typescript
+const retryTransaction = async <T>(
+  transactionFn: (tx: ITransactionClient) => Promise<T>,
+  maxRetries: number = 3
+): Promise<T> => {
+  let lastError: Error
+
+  for (let attempt = 1; attempt <= maxRetries; attempt++) {
+    try {
+      return await withTransaction(dbClient, transactionFn)
+    } catch (error) {
+      lastError = error as Error
+
+      // Check if error is retryable
+      if (isRetryableError(error) && attempt < maxRetries) {
+        const delay = Math.pow(2, attempt) * 1000 // Exponential backoff
+        console.warn(
+          `Transaction attempt ${attempt} failed, retrying in ${delay}ms...`
+        )
+        await new Promise((resolve) => setTimeout(resolve, delay))
+        continue
+      }
+
+      throw error
+    }
+  }
+
+  throw lastError!
+}
+
+const isRetryableError = (error: any): boolean => {
+  const retryableErrors = [
+    'deadlock detected',
+    'serialization failure',
+    'connection lost',
+    'timeout',
+  ]
+
+  return retryableErrors.some((msg) =>
+    error.message?.toLowerCase().includes(msg)
+  )
+}
+```
+
+Always wrap database operations in try-catch blocks and handle errors appropriately in your application.
 
 ## Contributing
 
-Feel free to contribute by opening pull requests or issues with improvements and bug fixes.
+We welcome contributions to the Star DB Query Builder! Here's how you can help:
+
+### Development Setup
+
+1. **Clone the repository**
+
+   ```bash
+   git clone https://github.com/starbem/star-db-query-builder.git
+   cd star-db-query-builder
+   ```
+
+2. **Install dependencies**
+
+   ```bash
+   pnpm install
+   ```
+
+3. **Run tests**
+
+   ```bash
+   pnpm test
+   ```
+
+4. **Run linting**
+
+   ```bash
+   pnpm lint
+   ```
+
+5. **Build the project**
+   ```bash
+   pnpm build
+   ```
+
+### Contributing Guidelines
+
+- **Code Style**: Follow the existing code style and use Prettier for formatting
+- **TypeScript**: Maintain strict TypeScript typing
+- **Tests**: Add tests for new features and bug fixes
+- **Documentation**: Update documentation for any API changes
+- **Commit Messages**: Use conventional commit messages
+
+### Pull Request Process
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for your changes
+5. Ensure all tests pass (`pnpm test`)
+6. Run linting (`pnpm lint`)
+7. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+8. Push to your branch (`git push origin feature/amazing-feature`)
+9. Open a Pull Request
+
+### Reporting Issues
+
+When reporting issues, please include:
+
+- **Environment**: Node.js version, database type and version
+- **Steps to Reproduce**: Clear steps to reproduce the issue
+- **Expected Behavior**: What you expected to happen
+- **Actual Behavior**: What actually happened
+- **Code Sample**: Minimal code sample that demonstrates the issue
+
+### Feature Requests
+
+For feature requests, please:
+
+- **Describe the feature**: Clear description of what you want
+- **Use Case**: Explain why this feature would be useful
+- **Proposed API**: If you have ideas for the API design
+- **Alternatives**: Any alternative solutions you've considered
 
 ## License
 
-This project is licensed under the MIT License.
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Support
+
+- **Documentation**: [GitHub Wiki](https://github.com/starbem/star-db-query-builder/wiki)
+- **Issues**: [GitHub Issues](https://github.com/starbem/star-db-query-builder/issues)
+- **Discussions**: [GitHub Discussions](https://github.com/starbem/star-db-query-builder/discussions)
+
+## Changelog
 
-This documentation explains how to set up connections with external configuration for both connection pool and retry options, retrieve clients to execute queries, and monitor events for logging and diagnostics.
+See [CHANGELOG.md](CHANGELOG.md) for a list of changes and version history.
 
 ---
 
-💻 Happy Coding!
+Made with ❤️ by the Starbem team