@starbemtech/star-db-query-builder 1.3.1 → 1.4.0

package/docs/methods/transactions.md

@@ -1,737 +0,0 @@
-# Transactions
-
-Execute multiple database operations within a single transaction to ensure data consistency and atomicity.
-
-## Overview
-
-Transactions ensure that a series of database operations either all succeed or all fail together. This is crucial for maintaining data integrity when performing complex operations that involve multiple tables or records.
-
-## Available Methods
-
-### withTransaction
-
-Executes a function within a database transaction with automatic commit/rollback handling.
-
-```typescript
-withTransaction<T>(
-  dbClient: IDatabaseClient,
-  transactionFn: (tx: ITransactionClient) => Promise<T>
-): Promise<T>
-```
-
-### beginTransaction
-
-Creates a transaction client for manual transaction management.
-
-```typescript
-beginTransaction(dbClient: IDatabaseClient): Promise<ITransactionClient>
-```
-
-## ITransactionClient Interface
-
-```typescript
-interface ITransactionClient {
-  query: <T>(sql: string, params?: any[]) => Promise<T>
-  commit: () => Promise<void>
-  rollback: () => Promise<void>
-}
-```
-
-## Examples
-
-### Basic Transaction with withTransaction
-
-```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,
-      },
-    })
-
-    return { user, profile }
-  })
-}
-
-// Usage
-try {
-  const result = await createUserWithProfile(
-    { name: 'John Doe', email: 'john@example.com' },
-    { bio: 'Software developer', location: 'New York' }
-  )
-  console.log('User and profile created successfully:', result)
-} catch (error) {
-  console.error('Transaction failed:', error.message)
-  // Both user and profile creation were rolled back
-}
-```
-
-### E-commerce Order Processing
-
-```typescript
-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, // Will be calculated
-      },
-    })
-
-    let totalAmount = 0
-
-    // Create order items and calculate total
-    for (const item of orderItems) {
-      const orderItem = 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',
-      },
-    })
-
-    return { order, totalAmount }
-  })
-}
-```
-
-### Account Transfer
-
-```typescript
-const transferMoney = async (
-  fromAccountId: string,
-  toAccountId: string,
-  amount: number
-) => {
-  return withTransaction(dbClient, async (tx) => {
-    // Check sender balance
-    const fromAccount = await findFirst({
-      tableName: 'accounts',
-      dbClient: tx,
-      where: { id: { operator: '=', value: fromAccountId } },
-    })
-
-    if (!fromAccount || fromAccount.balance < amount) {
-      throw new Error('Insufficient funds')
-    }
-
-    // Debit from sender
-    await update({
-      tableName: 'accounts',
-      dbClient: tx,
-      id: fromAccountId,
-      data: {
-        balance: { operator: '-', value: amount },
-      },
-    })
-
-    // Credit to receiver
-    await update({
-      tableName: 'accounts',
-      dbClient: tx,
-      id: toAccountId,
-      data: {
-        balance: { operator: '+', value: amount },
-      },
-    })
-
-    // Create transaction record
-    const transaction = await insert({
-      tableName: 'transactions',
-      dbClient: tx,
-      data: {
-        from_account_id: fromAccountId,
-        to_account_id: toAccountId,
-        amount,
-        type: 'transfer',
-        status: 'completed',
-      },
-    })
-
-    return transaction
-  })
-}
-```
-
-### Manual Transaction Management
-
-```typescript
-import {
-  beginTransaction,
-  insert,
-  update,
-} from '@starbemtech/star-db-query-builder'
-
-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
-  }
-}
-```
-
-### Nested Operations with Error Handling
-
-```typescript
-const createUserWithMultipleRelations = async (userData: any) => {
-  return withTransaction(dbClient, async (tx) => {
-    try {
-      // Create user
-      const user = await insert({
-        tableName: 'users',
-        dbClient: tx,
-        data: userData,
-      })
-
-      // Create user preferences
-      const preferences = await insert({
-        tableName: 'user_preferences',
-        dbClient: tx,
-        data: {
-          user_id: user.id,
-          theme: 'dark',
-          notifications: true,
-        },
-      })
-
-      // Create user settings
-      const settings = await insert({
-        tableName: 'user_settings',
-        dbClient: tx,
-        data: {
-          user_id: user.id,
-          language: 'en',
-          timezone: 'UTC',
-        },
-      })
-
-      // Create audit log
-      await insert({
-        tableName: 'audit_logs',
-        dbClient: tx,
-        data: {
-          user_id: user.id,
-          action: 'user_created',
-          details: JSON.stringify({ email: user.email }),
-        },
-      })
-
-      return { user, preferences, settings }
-    } catch (error) {
-      // Transaction will be automatically rolled back
-      console.error('Failed to create user with relations:', error)
-      throw error
-    }
-  })
-}
-```
-
-### Batch Operations with Transactions
-
-```typescript
-const bulkUserCreation = async (usersData: any[]) => {
-  return withTransaction(dbClient, async (tx) => {
-    const results = []
-
-    for (const userData of usersData) {
-      // Create user
-      const user = await insert({
-        tableName: 'users',
-        dbClient: tx,
-        data: userData,
-      })
-
-      // Create default profile
-      const profile = await insert({
-        tableName: 'user_profiles',
-        dbClient: tx,
-        data: {
-          user_id: user.id,
-          bio: 'New user',
-          created_at: new Date(),
-        },
-      })
-
-      results.push({ user, profile })
-    }
-
-    // Create batch audit log
-    await insert({
-      tableName: 'audit_logs',
-      dbClient: tx,
-      data: {
-        action: 'bulk_user_creation',
-        details: JSON.stringify({
-          count: usersData.length,
-          user_ids: results.map((r) => r.user.id),
-        }),
-      },
-    })
-
-    return results
-  })
-}
-```
-
-### Conditional Transaction Logic
-
-```typescript
-const processPayment = async (paymentData: any) => {
-  return withTransaction(dbClient, async (tx) => {
-    // Create payment record
-    const payment = await insert({
-      tableName: 'payments',
-      dbClient: tx,
-      data: {
-        ...paymentData,
-        status: 'processing',
-      },
-    })
-
-    // Check if payment amount is above threshold
-    if (paymentData.amount > 1000) {
-      // Require manual approval for large payments
-      await insert({
-        tableName: 'payment_approvals',
-        dbClient: tx,
-        data: {
-          payment_id: payment.id,
-          status: 'pending',
-          requires_approval: true,
-        },
-      })
-
-      // Update payment status
-      await update({
-        tableName: 'payments',
-        dbClient: tx,
-        id: payment.id,
-        data: { status: 'pending_approval' },
-      })
-    } else {
-      // Auto-approve small payments
-      await update({
-        tableName: 'payments',
-        dbClient: tx,
-        id: payment.id,
-        data: { status: 'approved' },
-      })
-
-      // Process the payment
-      await processApprovedPayment(payment.id, tx)
-    }
-
-    return payment
-  })
-}
-
-const processApprovedPayment = async (
-  paymentId: string,
-  tx: ITransactionClient
-) => {
-  // Additional payment processing logic
-  await update({
-    tableName: 'payments',
-    dbClient: tx,
-    id: paymentId,
-    data: { status: 'completed', processed_at: new Date() },
-  })
-}
-```
-
-## Best Practices
-
-### 1. 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
-  })
-}
-```
-
-### 2. Handle Errors Properly
-
-```typescript
-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('duplicate key')) {
-      throw new Error('Record already exists')
-    }
-
-    throw error
-  }
-}
-```
-
-### 3. Use Appropriate Isolation Levels
-
-```typescript
-// For read-heavy operations, consider using read-only transactions
-const getReportData = async () => {
-  return withTransaction(dbClient, async (tx) => {
-    // Set transaction to read-only (database-specific)
-    await tx.query('SET TRANSACTION READ ONLY')
-
-    const users = await findMany({
-      tableName: 'users',
-      dbClient: tx,
-      where: { status: { operator: '=', value: 'active' } },
-    })
-
-    const orders = await findMany({
-      tableName: 'orders',
-      dbClient: tx,
-      where: { status: { operator: '=', value: 'completed' } },
-    })
-
-    return { users, orders }
-  })
-}
-```
-
-### 4. Avoid Nested Transactions
-
-```typescript
-// Good: Single transaction for related operations
-const createOrderWithItems = async (orderData: any, items: any[]) => {
-  return withTransaction(dbClient, async (tx) => {
-    const order = await insert({
-      tableName: 'orders',
-      dbClient: tx,
-      data: orderData,
-    })
-
-    for (const item of items) {
-      await insert({
-        tableName: 'order_items',
-        dbClient: tx,
-        data: { ...item, order_id: order.id },
-      })
-    }
-
-    return order
-  })
-}
-
-// Avoid: Nested transactions (not supported by most databases)
-const badNestedTransaction = async () => {
-  return withTransaction(dbClient, async (tx1) => {
-    // ... operations
-
-    return withTransaction(dbClient, async (tx2) => {
-      // This won't work as expected
-    })
-  })
-}
-```
-
-## Error Handling
-
-### Common Transaction Errors
-
-```typescript
-const handleTransactionErrors = async () => {
-  try {
-    return await withTransaction(dbClient, async (tx) => {
-      // Your transaction logic
-    })
-  } catch (error) {
-    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)
-  )
-}
-```
-
-## Performance Considerations
-
-### 1. Connection Pooling
-
-```typescript
-// Ensure your database client is configured with proper connection pooling
-await initDb({
-  type: 'pg',
-  options: {
-    host: 'localhost',
-    port: 5432,
-    database: 'myapp',
-    user: 'username',
-    password: 'password',
-    max: 20, // Maximum connections in pool
-    idleTimeoutMillis: 30000,
-    connectionTimeoutMillis: 2000,
-  },
-})
-```
-
-### 2. Transaction Timeout
-
-```typescript
-// Set appropriate timeouts for transactions
-const quickTransaction = async () => {
-  return withTransaction(dbClient, async (tx) => {
-    // Set a timeout for this transaction
-    const timeoutPromise = new Promise((_, reject) => {
-      setTimeout(() => reject(new Error('Transaction timeout')), 5000)
-    })
-
-    const transactionPromise = (async () => {
-      // Your transaction logic
-      return await someOperation(tx)
-    })()
-
-    return Promise.race([transactionPromise, timeoutPromise])
-  })
-}
-```
-
-### 3. Batch Operations
-
-```typescript
-// For large batch operations, consider processing in chunks
-const bulkUpdateWithTransactions = async (
-  records: any[],
-  chunkSize: number = 100
-) => {
-  const results = []
-
-  for (let i = 0; i < records.length; i += chunkSize) {
-    const chunk = records.slice(i, i + chunkSize)
-
-    const chunkResult = await withTransaction(dbClient, async (tx) => {
-      const chunkResults = []
-
-      for (const record of chunk) {
-        const result = await update({
-          tableName: 'records',
-          dbClient: tx,
-          id: record.id,
-          data: record.data,
-        })
-        chunkResults.push(result)
-      }
-
-      return chunkResults
-    })
-
-    results.push(...chunkResult)
-  }
-
-  return results
-}
-```
-
-## Database-Specific Considerations
-
-### PostgreSQL
-
-- Supports nested transactions (savepoints)
-- Has excellent transaction isolation
-- Supports advisory locks for complex scenarios
-
-### MySQL
-
-- Uses autocommit mode by default
-- Supports different isolation levels
-- Has limitations with nested transactions
-
-## Monitoring and Logging
-
-```typescript
-// Monitor transaction events
-import { monitor, MonitorEvents } from '@starbemtech/star-db-query-builder'
-
-monitor.on(MonitorEvents.TRANSACTION_COMMIT, (data) => {
-  console.log('Transaction committed:', data)
-})
-
-monitor.on(MonitorEvents.TRANSACTION_ROLLBACK, (data) => {
-  console.log('Transaction rolled back:', data)
-})
-
-monitor.on(MonitorEvents.QUERY_START, (data) => {
-  if (data.inTransaction) {
-    console.log('Query in transaction:', data.sql)
-  }
-})
-```
-
-## Summary
-
-Transactions are essential for maintaining data consistency in complex operations. The library provides two main approaches:
-
-1. **`withTransaction`**: Automatic transaction management with commit/rollback
-2. **`beginTransaction`**: Manual transaction control for advanced scenarios
-
-Always handle errors properly and keep transactions as short as possible to avoid performance issues and deadlocks.