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

package/docs/INDEX.md

@@ -0,0 +1,145 @@
+# Star DB Query Builder - Documentation Index
+
+Welcome to the comprehensive documentation for the Star DB Query Builder library. This index provides quick access to all available documentation.
+
+## 📚 Main Documentation
+
+- **[README.md](./README.md)** - Complete library overview, installation, and quick start guide
+- **[Raw Query Examples](./raw-query-examples.md)** - Detailed examples for raw SQL queries
+
+## 🔧 Method Documentation
+
+### Query Methods
+
+- **[findFirst](./methods/findFirst.md)** - Find a single record with conditions
+- **[findMany](./methods/findMany.md)** - Find multiple records with pagination and filtering
+
+### Insert Methods
+
+- **[insert](./methods/insert.md)** - Insert a single record
+- **[insertMany](./methods/insertMany.md)** - Insert multiple records in batch
+
+### Update Methods
+
+- **[update](./methods/update.md)** - Update a single record by ID
+- **[updateMany](./methods/updateMany.md)** - Update multiple records with conditions
+
+### Delete Methods
+
+- **[deleteOne](./methods/deleteOne.md)** - Delete a single record by ID
+- **[deleteMany](./methods/deleteMany.md)** - Delete multiple records by IDs
+
+### Advanced Methods
+
+- **[joins](./methods/joins.md)** - Execute queries with JOIN operations
+- **[rawQuery](./methods/rawQuery.md)** - Execute raw SQL queries
+
+### Database Initialization
+
+- **[initDb](./methods/initDb.md)** - Initialize database connections
+- **[getDbClient](./methods/getDbClient.md)** - Retrieve database client instances
+
+## 🏗️ Architecture Documentation
+
+### Core Components
+
+- **[Types and Interfaces](./architecture/types.md)** - TypeScript type definitions
+- **[Database Clients](./architecture/database-clients.md)** - PostgreSQL and MySQL client implementations
+- **[Query Builder](./architecture/query-builder.md)** - Internal query building logic
+
+### Utilities
+
+- **[Utils](./architecture/utils.md)** - Helper functions for query construction
+- **[Error Handling](./architecture/error-handling.md)** - Error handling patterns and best practices
+
+## 📖 Guides and Tutorials
+
+### Getting Started
+
+- **[Installation Guide](./guides/installation.md)** - Step-by-step installation instructions
+- **[First Steps](./guides/first-steps.md)** - Your first database operations
+- **[TypeScript Setup](./guides/typescript-setup.md)** - TypeScript configuration and usage
+
+### Advanced Topics
+
+- **[Performance Optimization](./guides/performance.md)** - Tips for optimizing database performance
+- **[Security Best Practices](./guides/security.md)** - Security considerations and best practices
+- **[Testing](./guides/testing.md)** - How to test your database operations
+- **[Migration Guide](./guides/migration.md)** - Migrating from other ORMs
+
+### Database-Specific Guides
+
+- **[PostgreSQL Guide](./guides/postgresql.md)** - PostgreSQL-specific features and optimizations
+- **[MySQL Guide](./guides/mysql.md)** - MySQL-specific features and optimizations
+
+## 🎯 Use Cases and Examples
+
+### Common Patterns
+
+- **[User Management](./examples/user-management.md)** - Complete user CRUD operations
+- **[E-commerce](./examples/ecommerce.md)** - Product catalog and order management
+- **[Content Management](./examples/cms.md)** - Blog posts and content management
+- **[Analytics](./examples/analytics.md)** - Data aggregation and reporting
+
+### Real-World Scenarios
+
+- **[API Development](./examples/api-development.md)** - Building REST APIs with the library
+- **[Data Import/Export](./examples/data-import-export.md)** - Bulk data operations
+- **[Audit Logging](./examples/audit-logging.md)** - Implementing audit trails
+- **[Multi-tenant Applications](./examples/multi-tenant.md)** - Multi-tenant database patterns
+
+## 🔍 Reference
+
+### API Reference
+
+- **[Method Signatures](./reference/method-signatures.md)** - Complete method signatures and parameters
+- **[Type Definitions](./reference/type-definitions.md)** - All TypeScript interfaces and types
+- **[Error Codes](./reference/error-codes.md)** - Complete list of error codes and messages
+
+### Database Compatibility
+
+- **[PostgreSQL Features](./reference/postgresql-features.md)** - PostgreSQL-specific features
+- **[MySQL Features](./reference/mysql-features.md)** - MySQL-specific features
+- **[SQL Generation](./reference/sql-generation.md)** - Examples of generated SQL queries
+
+## 🚀 Quick Navigation
+
+### By Task
+
+- **Need to find data?** → [findFirst](./methods/findFirst.md) | [findMany](./methods/findMany.md)
+- **Need to insert data?** → [insert](./methods/insert.md) | [insertMany](./methods/insertMany.md)
+- **Need to update data?** → [update](./methods/update.md) | [updateMany](./methods/updateMany.md)
+- **Need to delete data?** → [deleteOne](./methods/deleteOne.md) | [deleteMany](./methods/deleteMany.md)
+- **Need complex queries?** → [joins](./methods/joins.md) | [rawQuery](./methods/rawQuery.md)
+
+### By Experience Level
+
+- **New to the library?** → [README.md](./README.md) → [First Steps](./guides/first-steps.md)
+- **Familiar with basics?** → [Method Documentation](./methods/) → [Examples](./examples/)
+- **Advanced user?** → [Architecture](./architecture/) → [Performance Guide](./guides/performance.md)
+
+### By Database
+
+- **Using PostgreSQL?** → [PostgreSQL Guide](./guides/postgresql.md) → [PostgreSQL Features](./reference/postgresql-features.md)
+- **Using MySQL?** → [MySQL Guide](./guides/mysql.md) → [MySQL Features](./reference/mysql-features.md)
+
+## 📝 Contributing to Documentation
+
+If you find any issues with the documentation or want to contribute improvements:
+
+1. Check the [Contributing Guidelines](../CONTRIBUTING.md)
+2. Follow the [Documentation Style Guide](./style-guide.md)
+3. Submit a pull request with your changes
+
+## 🆘 Getting Help
+
+- **Issues**: Check the [GitHub Issues](https://github.com/starbemtech/star-db-query-builder/issues)
+- **Discussions**: Join the [GitHub Discussions](https://github.com/starbemtech/star-db-query-builder/discussions)
+- **Examples**: Browse the [Examples](./examples/) directory
+- **API Reference**: Check the [Reference](./reference/) section
+
+---
+
+**Last Updated**: September 2025  
+**Version**: 1.2.0  
+**Maintainer**: Starbem Tech Team

package/docs/methods/findFirst.md

@@ -0,0 +1,394 @@
+# findFirst
+
+Finds the first record that matches the specified conditions from a database table.
+
+## Signature
+
+```typescript
+findFirst<T>({
+  tableName: string,
+  dbClient: IDatabaseClient,
+  select?: string[],
+  where?: Conditions<T>,
+  groupBy?: string[],
+  orderBy?: OrderBy
+}): Promise<T | null>
+```
+
+## Parameters
+
+| Parameter   | Type              | Required | Description                                          |
+| ----------- | ----------------- | -------- | ---------------------------------------------------- |
+| `tableName` | `string`          | ✅       | Name of the database table                           |
+| `dbClient`  | `IDatabaseClient` | ✅       | Database client instance                             |
+| `select`    | `string[]`        | ❌       | Array of field names to select (default: all fields) |
+| `where`     | `Conditions<T>`   | ❌       | Conditions to filter records                         |
+| `groupBy`   | `string[]`        | ❌       | Fields to group by                                   |
+| `orderBy`   | `OrderBy`         | ❌       | Sort order specification                             |
+
+## Return Value
+
+- **Type**: `Promise<T | null>`
+- **Description**: Returns the first matching record or `null` if no record is found
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { findFirst } from '@starbemtech/star-db-query-builder'
+
+// Find user by email
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: {
+    email: { operator: '=', value: 'user@example.com' },
+  },
+})
+
+console.log(user) // { id: 'user-123', name: 'John Doe', email: 'user@example.com', ... }
+```
+
+### With Specific Fields
+
+```typescript
+// Select only specific fields
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  select: ['id', 'name', 'email'],
+  where: {
+    status: { operator: '=', value: 'active' },
+  },
+})
+
+console.log(user) // { id: 'user-123', name: 'John Doe', email: 'user@example.com' }
+```
+
+### With Complex Conditions
+
+```typescript
+// Multiple conditions with AND
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: {
+    AND: [
+      { email: { operator: '=', value: 'user@example.com' } },
+      { status: { operator: '=', value: 'active' } },
+      { verified: { operator: '=', value: true } },
+    ],
+  },
+})
+
+// Multiple conditions with OR
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: {
+    OR: [
+      { email: { operator: '=', value: 'user@example.com' } },
+      { phone: { operator: '=', value: '+1234567890' } },
+    ],
+  },
+})
+```
+
+### With Ordering
+
+```typescript
+// Find the most recent user
+const latestUser = await findFirst({
+  tableName: 'users',
+  dbClient,
+  orderBy: [{ field: 'created_at', direction: 'DESC' }],
+})
+
+// Find the oldest active user
+const oldestUser = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: { status: { operator: '=', value: 'active' } },
+  orderBy: [{ field: 'created_at', direction: 'ASC' }],
+})
+```
+
+### With Grouping
+
+```typescript
+// Find the first user in each status group
+const userByStatus = await findFirst({
+  tableName: 'users',
+  dbClient,
+  select: ['status', 'name', 'created_at'],
+  groupBy: ['status'],
+  orderBy: [{ field: 'created_at', direction: 'ASC' }],
+})
+```
+
+### Advanced Conditions
+
+```typescript
+// Using different operators
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: {
+    age: { operator: '>=', value: 18 },
+    name: { operator: 'LIKE', value: '%John%' },
+    email: { operator: 'IS NOT NULL', value: null },
+    status: { operator: 'IN', value: ['active', 'pending'] },
+  },
+})
+
+// Using BETWEEN
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: {
+    created_at: {
+      operator: 'BETWEEN',
+      value: [new Date('2023-01-01'), new Date('2023-12-31')],
+    },
+  },
+})
+```
+
+### TypeScript Usage
+
+```typescript
+interface User {
+  id: string
+  name: string
+  email: string
+  age: number
+  status: 'active' | 'inactive' | 'pending'
+  created_at: Date
+  updated_at: Date
+}
+
+// Typed usage
+const user: User | null = await findFirst<User>({
+  tableName: 'users',
+  dbClient,
+  where: {
+    email: { operator: '=', value: 'user@example.com' },
+  },
+})
+
+if (user) {
+  console.log(`Found user: ${user.name}`)
+} else {
+  console.log('User not found')
+}
+```
+
+### Error Handling
+
+```typescript
+try {
+  const user = await findFirst({
+    tableName: 'users',
+    dbClient,
+    where: { email: { operator: '=', value: 'user@example.com' } },
+  })
+
+  if (user) {
+    console.log('User found:', user.name)
+  } else {
+    console.log('No user found with this email')
+  }
+} catch (error) {
+  console.error('Database error:', error.message)
+  // Handle error appropriately
+}
+```
+
+## Generated SQL Examples
+
+### Simple Query
+
+```sql
+SELECT * FROM users WHERE email = $1 LIMIT 1
+```
+
+### With Specific Fields
+
+```sql
+SELECT id, name, email FROM users WHERE status = $1 LIMIT 1
+```
+
+### With Complex Conditions
+
+```sql
+SELECT * FROM users
+WHERE (email = $1 AND status = $2 AND verified = $3)
+LIMIT 1
+```
+
+### With Ordering
+
+```sql
+SELECT * FROM users
+ORDER BY created_at DESC
+LIMIT 1
+```
+
+### With Grouping
+
+```sql
+SELECT status, name, created_at
+FROM users
+GROUP BY status
+ORDER BY created_at ASC
+LIMIT 1
+```
+
+## Best Practices
+
+### 1. Use Specific Field Selection
+
+```typescript
+// Good: Select only needed fields
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  select: ['id', 'name', 'email'],
+  where: { id: { operator: '=', value: 'user-123' } },
+})
+
+// Avoid: Selecting all fields when not needed
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: { id: { operator: '=', value: 'user-123' } },
+})
+```
+
+### 2. Use Appropriate Indexes
+
+Ensure your database has indexes on fields used in WHERE clauses for better performance:
+
+```sql
+-- Example indexes for common queries
+CREATE INDEX idx_users_email ON users(email);
+CREATE INDEX idx_users_status ON users(status);
+CREATE INDEX idx_users_created_at ON users(created_at);
+```
+
+### 3. Handle Null Results
+
+```typescript
+const user = await findFirst({
+  tableName: 'users',
+  dbClient,
+  where: { email: { operator: '=', value: 'nonexistent@example.com' } },
+})
+
+if (!user) {
+  // Handle case when no user is found
+  throw new Error('User not found')
+}
+```
+
+### 4. Use TypeScript for Type Safety
+
+```typescript
+interface UserSearchParams {
+  email?: string
+  status?: string
+  age?: number
+}
+
+const findUserByParams = async (
+  params: UserSearchParams
+): Promise<User | null> => {
+  const where: Conditions<User> = {}
+
+  if (params.email) {
+    where.email = { operator: '=', value: params.email }
+  }
+
+  if (params.status) {
+    where.status = { operator: '=', value: params.status }
+  }
+
+  if (params.age) {
+    where.age = { operator: '>=', value: params.age }
+  }
+
+  return findFirst<User>({
+    tableName: 'users',
+    dbClient,
+    where,
+  })
+}
+```
+
+## Common Use Cases
+
+### 1. User Authentication
+
+```typescript
+const authenticateUser = async (email: string, password: string) => {
+  const user = await findFirst({
+    tableName: 'users',
+    dbClient,
+    where: {
+      AND: [
+        { email: { operator: '=', value: email } },
+        { password: { operator: '=', value: password } },
+        { status: { operator: '=', value: 'active' } },
+      ],
+    },
+  })
+
+  return user
+}
+```
+
+### 2. Finding Latest Record
+
+```typescript
+const getLatestOrder = async (userId: string) => {
+  const order = await findFirst({
+    tableName: 'orders',
+    dbClient,
+    where: { user_id: { operator: '=', value: userId } },
+    orderBy: [{ field: 'created_at', direction: 'DESC' }],
+  })
+
+  return order
+}
+```
+
+### 3. Checking Existence
+
+```typescript
+const userExists = async (email: string): Promise<boolean> => {
+  const user = await findFirst({
+    tableName: 'users',
+    dbClient,
+    select: ['id'],
+    where: { email: { operator: '=', value: email } },
+  })
+
+  return user !== null
+}
+```
+
+## Performance Considerations
+
+- **Indexes**: Ensure proper indexes exist on fields used in WHERE clauses
+- **Field Selection**: Use `select` to limit returned fields when possible
+- **Limit Results**: `findFirst` automatically limits to 1 result, which is optimal
+- **Connection Pooling**: Use connection pooling for better performance in high-traffic applications
+
+## 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
+- Database-specific errors from the underlying database driver