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

package/docs/methods/joins.md

@@ -0,0 +1,781 @@
+# joins
+
+Executes queries with JOIN operations to combine data from multiple tables.
+
+## Signature
+
+```typescript
+joins<T>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  select: string[],
+  joins: JoinClause[],
+  where?: Conditions<T>,
+  groupBy?: string[],
+  orderBy?: OrderBy,
+  limit?: number,
+  offset?: number,
+  unaccent?: boolean
+}): Promise<T[]>
+```
+
+## Parameters
+
+| Parameter   | Type              | Required | Description                                        |
+| ----------- | ----------------- | -------- | -------------------------------------------------- |
+| `tableName` | `string`          | ✅       | Name of the main database table                    |
+| `dbClient`  | `IDatabaseClient` | ✅       | Database client instance                           |
+| `select`    | `string[]`        | ✅       | Array of field names to select (must be specified) |
+| `joins`     | `JoinClause[]`    | ✅       | Array of JOIN clauses                              |
+| `where`     | `Conditions<T>`   | ❌       | Conditions to filter records                       |
+| `groupBy`   | `string[]`        | ❌       | Fields to group by                                 |
+| `orderBy`   | `OrderBy`         | ❌       | Sort order specification                           |
+| `limit`     | `number`          | ❌       | Maximum number of records to return                |
+| `offset`    | `number`          | ❌       | Number of records to skip                          |
+| `unaccent`  | `boolean`         | ❌       | Enable unaccent search for PostgreSQL              |
+
+## JoinClause Interface
+
+```typescript
+interface JoinClause {
+  type: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL'
+  table: string
+  on: string
+}
+```
+
+## Return Value
+
+- **Type**: `Promise<T[]>`
+- **Description**: Returns an array of records from the joined tables
+
+## Examples
+
+### Basic JOIN
+
+```typescript
+import { joins } from '@starbemtech/star-db-query-builder'
+
+// Get users with their orders
+const usersWithOrders = await joins({
+  tableName: 'users',
+  dbClient,
+  select: [
+    'users.id',
+    'users.name',
+    'users.email',
+    'orders.total',
+    'orders.created_at',
+  ],
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+  where: {
+    'users.status': { operator: '=', value: 'active' },
+  },
+})
+
+console.log(usersWithOrders)
+// [
+//   {
+//     id: 'user-1',
+//     name: 'John Doe',
+//     email: 'john@example.com',
+//     total: 150.00,
+//     created_at: '2023-12-01T10:00:00.000Z'
+//   },
+//   // ... more results
+// ]
+```
+
+### Multiple JOINs
+
+```typescript
+// Complex report with multiple tables
+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',
+    'plans.price as plan_price',
+  ],
+  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',
+    },
+  ],
+  where: {
+    'users.status': { operator: '=', value: 'active' },
+  },
+  groupBy: [
+    'users.id',
+    'users.name',
+    'users.email',
+    'plans.name',
+    'plans.price',
+  ],
+  orderBy: [{ field: 'total_spent', direction: 'DESC' }],
+})
+```
+
+### Different JOIN Types
+
+```typescript
+// INNER JOIN - only users with orders
+const usersWithOrders = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'INNER',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+
+// LEFT JOIN - all users, with or without orders
+const allUsersWithOrders = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+
+// RIGHT JOIN - all orders, with or without users
+const ordersWithUsers = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'RIGHT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+
+// FULL OUTER JOIN - all users and all orders
+const allData = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'FULL',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+```
+
+### Complex WHERE Conditions with JOINs
+
+```typescript
+// Users with orders from last month
+const recentUsers = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'users.email', 'orders.total', 'orders.created_at'],
+  joins: [
+    {
+      type: 'INNER',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+  where: {
+    AND: [
+      { 'users.status': { operator: '=', value: 'active' } },
+      {
+        'orders.created_at': { operator: '>=', value: new Date('2023-11-01') },
+      },
+      { 'orders.total': { operator: '>', value: 100 } },
+    ],
+  },
+  orderBy: [{ field: 'orders.created_at', direction: 'DESC' }],
+})
+```
+
+### Aggregation with JOINs
+
+```typescript
+// User statistics with order data
+const userStats = await joins({
+  tableName: 'users',
+  dbClient,
+  select: [
+    'users.id',
+    'users.name',
+    'COUNT(orders.id) as order_count',
+    'SUM(orders.total) as total_spent',
+    'AVG(orders.total) as avg_order_value',
+    'MAX(orders.created_at) as last_order_date',
+  ],
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+  where: {
+    'users.created_at': { operator: '>=', value: new Date('2023-01-01') },
+  },
+  groupBy: ['users.id', 'users.name'],
+  having: {
+    'COUNT(orders.id)': { operator: '>', value: 0 },
+  },
+  orderBy: [{ field: 'total_spent', direction: 'DESC' }],
+})
+```
+
+### Pagination with JOINs
+
+```typescript
+// Paginated user orders
+const paginatedOrders = await joins({
+  tableName: 'users',
+  dbClient,
+  select: [
+    'users.name',
+    'users.email',
+    'orders.id',
+    'orders.total',
+    'orders.status',
+    'orders.created_at',
+  ],
+  joins: [
+    {
+      type: 'INNER',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+  where: {
+    'orders.status': { operator: '=', value: 'completed' },
+  },
+  limit: 20,
+  offset: 0,
+  orderBy: [{ field: 'orders.created_at', direction: 'DESC' }],
+})
+```
+
+### TypeScript Usage
+
+```typescript
+interface UserWithOrder {
+  user_id: string
+  user_name: string
+  user_email: string
+  order_id: string
+  order_total: number
+  order_status: string
+  order_created_at: Date
+}
+
+// Typed usage
+const usersWithOrders: UserWithOrder[] = await joins<UserWithOrder>({
+  tableName: 'users',
+  dbClient,
+  select: [
+    'users.id as user_id',
+    'users.name as user_name',
+    'users.email as user_email',
+    'orders.id as order_id',
+    'orders.total as order_total',
+    'orders.status as order_status',
+    'orders.created_at as order_created_at',
+  ],
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+  where: {
+    'users.status': { operator: '=', value: 'active' },
+  },
+})
+```
+
+### Error Handling
+
+```typescript
+try {
+  const result = await joins({
+    tableName: 'users',
+    dbClient,
+    select: ['users.name', 'orders.total'],
+    joins: [
+      {
+        type: 'LEFT',
+        table: 'orders',
+        on: 'users.id = orders.user_id',
+      },
+    ],
+  })
+
+  console.log(`Found ${result.length} records`)
+} catch (error) {
+  console.error('Join query error:', error.message)
+  // Handle error appropriately
+}
+```
+
+## Generated SQL Examples
+
+### Simple LEFT JOIN
+
+```sql
+SELECT users.id, users.name, users.email, orders.total, orders.created_at
+FROM users
+LEFT JOIN orders ON users.id = orders.user_id
+WHERE users.status = $1
+```
+
+### Multiple JOINs with GROUP BY
+
+```sql
+SELECT
+  users.name,
+  users.email,
+  COUNT(orders.id) as order_count,
+  SUM(orders.total) as total_spent,
+  plans.name as plan_name
+FROM users
+LEFT JOIN orders ON users.id = orders.user_id
+LEFT JOIN user_plans ON users.id = user_plans.user_id
+LEFT JOIN plans ON user_plans.plan_id = plans.id
+WHERE users.status = $1
+GROUP BY users.id, users.name, users.email, plans.name
+ORDER BY total_spent DESC
+```
+
+### Complex WHERE with JOINs
+
+```sql
+SELECT users.name, users.email, orders.total, orders.created_at
+FROM users
+INNER JOIN orders ON users.id = orders.user_id
+WHERE (users.status = $1 AND orders.created_at >= $2 AND orders.total > $3)
+ORDER BY orders.created_at DESC
+```
+
+## Best Practices
+
+### 1. Always Specify SELECT Fields
+
+```typescript
+// Good: Explicit field selection
+const result = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.id', 'users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+
+// Avoid: Not specifying select fields
+const result = await joins({
+  tableName: 'users',
+  dbClient,
+  select: [], // This will cause issues
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+```
+
+### 2. Use Table Aliases for Clarity
+
+```typescript
+// Good: Use table prefixes for clarity
+const result = await joins({
+  tableName: 'users',
+  dbClient,
+  select: [
+    'users.id as user_id',
+    'users.name as user_name',
+    'orders.id as order_id',
+    'orders.total as order_total',
+  ],
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+```
+
+### 3. Choose Appropriate JOIN Types
+
+```typescript
+// Use INNER JOIN when you need matching records from both tables
+const usersWithOrders = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'INNER', // Only users who have orders
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+
+// Use LEFT JOIN when you want all records from the main table
+const allUsersWithOrders = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'LEFT', // All users, even those without orders
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+```
+
+### 4. Use Proper Indexing
+
+```sql
+-- Ensure proper indexes exist for JOIN conditions
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_user_plans_user_id ON user_plans(user_id);
+CREATE INDEX idx_user_plans_plan_id ON user_plans(plan_id);
+```
+
+### 5. Handle NULL Values in JOINs
+
+```typescript
+// Handle NULL values from LEFT JOINs
+const result = await joins({
+  tableName: 'users',
+  dbClient,
+  select: [
+    'users.name',
+    'COALESCE(orders.total, 0) as total_spent',
+    'CASE WHEN orders.id IS NULL THEN 0 ELSE 1 END as has_orders',
+  ],
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+})
+```
+
+## Common Use Cases
+
+### 1. User Dashboard Data
+
+```typescript
+const getUserDashboardData = async (userId: string) => {
+  return joins({
+    tableName: 'users',
+    dbClient,
+    select: [
+      'users.name',
+      'users.email',
+      'COUNT(orders.id) as total_orders',
+      'SUM(orders.total) as total_spent',
+      'plans.name as current_plan',
+      'plans.price as plan_price',
+    ],
+    joins: [
+      {
+        type: 'LEFT',
+        table: 'orders',
+        on: 'users.id = orders.user_id',
+      },
+      {
+        type: 'LEFT',
+        table: 'user_plans',
+        on: 'users.id = user_plans.user_id AND user_plans.is_active = true',
+      },
+      {
+        type: 'LEFT',
+        table: 'plans',
+        on: 'user_plans.plan_id = plans.id',
+      },
+    ],
+    where: {
+      'users.id': { operator: '=', value: userId },
+    },
+    groupBy: [
+      'users.id',
+      'users.name',
+      'users.email',
+      'plans.name',
+      'plans.price',
+    ],
+  })
+}
+```
+
+### 2. Sales Report
+
+```typescript
+const getSalesReport = async (startDate: Date, endDate: Date) => {
+  return joins({
+    tableName: 'orders',
+    dbClient,
+    select: [
+      'users.name as customer_name',
+      'users.email as customer_email',
+      'orders.id as order_id',
+      'orders.total as order_total',
+      'orders.status as order_status',
+      'products.name as product_name',
+      'order_items.quantity',
+      'order_items.price as item_price',
+    ],
+    joins: [
+      {
+        type: 'INNER',
+        table: 'users',
+        on: 'orders.user_id = users.id',
+      },
+      {
+        type: 'INNER',
+        table: 'order_items',
+        on: 'orders.id = order_items.order_id',
+      },
+      {
+        type: 'INNER',
+        table: 'products',
+        on: 'order_items.product_id = products.id',
+      },
+    ],
+    where: {
+      AND: [
+        { 'orders.created_at': { operator: '>=', value: startDate } },
+        { 'orders.created_at': { operator: '<=', value: endDate } },
+        { 'orders.status': { operator: '=', value: 'completed' } },
+      ],
+    },
+    orderBy: [{ field: 'orders.created_at', direction: 'DESC' }],
+  })
+}
+```
+
+### 3. Product Analytics
+
+```typescript
+const getProductAnalytics = async () => {
+  return joins({
+    tableName: 'products',
+    dbClient,
+    select: [
+      'products.name as product_name',
+      'categories.name as category_name',
+      'COUNT(order_items.id) as times_ordered',
+      'SUM(order_items.quantity) as total_quantity_sold',
+      'SUM(order_items.price * order_items.quantity) as total_revenue',
+      'AVG(order_items.price) as avg_price',
+    ],
+    joins: [
+      {
+        type: 'LEFT',
+        table: 'categories',
+        on: 'products.category_id = categories.id',
+      },
+      {
+        type: 'LEFT',
+        table: 'order_items',
+        on: 'products.id = order_items.product_id',
+      },
+      {
+        type: 'LEFT',
+        table: 'orders',
+        on: 'order_items.order_id = orders.id AND orders.status = "completed"',
+      },
+    ],
+    groupBy: ['products.id', 'products.name', 'categories.name'],
+    having: {
+      'COUNT(order_items.id)': { operator: '>', value: 0 },
+    },
+    orderBy: [{ field: 'total_revenue', direction: 'DESC' }],
+  })
+}
+```
+
+### 4. User Activity Feed
+
+```typescript
+const getUserActivityFeed = async (userId: string, limit: number = 50) => {
+  return joins({
+    tableName: 'users',
+    dbClient,
+    select: [
+      'activity_logs.action',
+      'activity_logs.description',
+      'activity_logs.created_at',
+      'orders.id as order_id',
+      'orders.total as order_total',
+      'products.name as product_name',
+    ],
+    joins: [
+      {
+        type: 'LEFT',
+        table: 'activity_logs',
+        on: 'users.id = activity_logs.user_id',
+      },
+      {
+        type: 'LEFT',
+        table: 'orders',
+        on: 'activity_logs.entity_id = orders.id AND activity_logs.entity_type = "order"',
+      },
+      {
+        type: 'LEFT',
+        table: 'order_items',
+        on: 'orders.id = order_items.order_id',
+      },
+      {
+        type: 'LEFT',
+        table: 'products',
+        on: 'order_items.product_id = products.id',
+      },
+    ],
+    where: {
+      'users.id': { operator: '=', value: userId },
+    },
+    limit,
+    orderBy: [{ field: 'activity_logs.created_at', direction: 'DESC' }],
+  })
+}
+```
+
+## Performance Considerations
+
+### 1. Index Strategy for JOINs
+
+```sql
+-- Create indexes on JOIN columns
+CREATE INDEX idx_orders_user_id ON orders(user_id);
+CREATE INDEX idx_order_items_order_id ON order_items(order_id);
+CREATE INDEX idx_order_items_product_id ON order_items(product_id);
+CREATE INDEX idx_user_plans_user_id ON user_plans(user_id);
+CREATE INDEX idx_user_plans_plan_id ON user_plans(plan_id);
+
+-- Composite indexes for common query patterns
+CREATE INDEX idx_orders_user_status_created ON orders(user_id, status, created_at);
+CREATE INDEX idx_order_items_order_product ON order_items(order_id, product_id);
+```
+
+### 2. Query Optimization
+
+```typescript
+// Good: Use indexed fields in WHERE clauses
+const result = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'INNER',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+  where: {
+    'users.status': { operator: '=', value: 'active' }, // Indexed field
+    'orders.created_at': { operator: '>=', value: new Date('2023-01-01') }, // Indexed field
+  },
+})
+
+// Avoid: Using non-indexed fields in WHERE clauses
+const result = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'INNER',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+  where: {
+    'users.bio': { operator: 'LIKE', value: '%developer%' }, // Non-indexed field
+  },
+})
+```
+
+### 3. Limit Result Sets
+
+```typescript
+// Always use LIMIT for large result sets
+const result = await joins({
+  tableName: 'users',
+  dbClient,
+  select: ['users.name', 'orders.total'],
+  joins: [
+    {
+      type: 'LEFT',
+      table: 'orders',
+      on: 'users.id = orders.user_id',
+    },
+  ],
+  limit: 1000, // Prevent memory issues
+  orderBy: [{ field: 'users.created_at', direction: 'DESC' }],
+})
+```
+
+## Error Messages
+
+Common error messages you might encounter:
+
+- `Table name is required` - The `tableName` parameter is missing
+- `DB client is required` - The `dbClient` parameter is missing
+- `column "field_name" does not exist` - Invalid field name in SELECT or WHERE clause
+- `relation "table_name" does not exist` - Invalid table name in JOIN clause
+- `syntax error at or near "JOIN"` - Invalid JOIN syntax
+- Database-specific errors from the underlying database driver