@thalorlabs/database/DEVELOPMENT.md

Database utilities and connection helpers for TypeScript applications with MongoDB support

# DEVELOPMENT.md — @thalorlabs/database

📄 Developer Guide for Adding Database Utilities

This guide explains how to create, edit, and add new database utilities to the @thalorlabs/database package while maintaining type safety and consistent database patterns.

## Table of Contents

1. [Project Structure](#project-structure)
2. [Adding a New Database Utility](#adding-a-new-database-utility)
3. [Database Safety Requirements](#database-safety-requirements)
4. [Code Standards](#code-standards)
5. [Build and Validation](#build-and-validation)

## Project Structure

```
src/
├── index.ts                           # Main exports
├── mongoDbConnect.ts                  # MongoDB connection utility
├── constants/
│   └── constants.ts                   # Database constants and configuration
└── tests/
    └── mongoDbConnect.test.ts         # Test suite
```

## Adding a New Database Utility

### Step 1: Create Utility File

1. **Create a new file** in the `src` directory:

   ```bash
   # For database utilities
   touch src/yourDatabaseUtility.ts

   # For utility types (if needed)
   touch src/yourDatabaseUtilityTypes.ts
   ```

2. **Follow the naming convention**:
   - Database utilities: `camelCase` (e.g., `mongoDbConnect.ts`, `queryBuilder.ts`)
   - Utility types: `camelCase` + `Types` suffix (e.g., `queryBuilderTypes.ts`)

### Step 2: Implement the Database Utility

Follow the JSDoc standards from [DOCSTYLE.md](./DOCSTYLE.md):

```typescript
import { Mongoose, Connection } from 'mongoose';

/**
 * Brief description of what the utility does and when to use it.
 *
 * Additional details about configuration options, error handling, and usage scenarios.
 *
 * @example
 * const result = await yourDatabaseUtility(options);
 *
 * const result = await yourDatabaseUtility({
 *   option1: 'value1',
 *   option2: 'value2'
 * });
 */
export async function yourDatabaseUtility(
  options?: YourUtilityOptions
): Promise<YourUtilityResult> {
  // Database utility logic here
  // Handle errors appropriately
  // Return the result
}
```

### Step 3: Create Utility Types (if needed)

```typescript
/**
 * Configuration options for the database utility.
 */
export interface YourUtilityOptions {
  option1?: string;
  option2?: number;
  option3?: boolean;
}

/**
 * Result type for the database utility.
 */
export interface YourUtilityResult {
  success: boolean;
  data?: any;
  error?: string;
}
```

### Step 4: Export the Utility

Add the export to `src/index.ts`:

```typescript
// For database utilities
export { yourDatabaseUtility } from './yourDatabaseUtility';

// For utility types
export type {
  YourUtilityOptions,
  YourUtilityResult,
} from './yourDatabaseUtility';
```

## Database Safety Requirements

### Mandatory Database Safety

- ✅ **Connection management** - All utilities should handle database connections properly
- ✅ **TypeScript definitions** - Complete type definitions for utility parameters
- ✅ **Proper imports** - Correct import/export statements
- ✅ **Error handling** - Comprehensive error handling for database operations

### Database Validation

1. **Required parameters** - Document which parameters are mandatory
2. **Optional parameters** - Use optional parameters with defaults
3. **Error handling** - Always handle database errors appropriately
4. **Connection safety** - Ensure proper connection handling and cleanup

### Database Categories

1. **Connection utilities** - Database connection management, pooling
2. **Query utilities** - Query builders, data retrieval helpers
3. **Migration utilities** - Database schema migrations, data transformations
4. **Validation utilities** - Data validation, schema checking
5. **Utility functions** - Common database operations, helpers

### Third-Party Database Policy

**❌ DO NOT include third-party database libraries in this package**

This package should only contain your own standardized database utilities - the database patterns you guarantee across your applications.

**Examples of what NOT to include:**

- Mongoose models or schemas
- Third-party ORM utilities
- External database drivers
- Any external library's database utilities

**Examples of what TO include:**

- `mongoDBConnect` - your standardized connection utility
- `queryBuilder` - your query building utilities
- `migrationHelper` - your database migration utilities

**Why this matters:**

- **Stable contracts** - Applications consume your normalized database utilities, not third-party APIs
- **Encapsulation** - Third-party changes don't break your entire database ecosystem
- **Maintainability** - Update third-party integrations in one service, not everywhere

**Where to put third-party database utilities:**
Keep them local to the service that uses the library, not in the shared database package.

## Code Standards

### TypeScript Standards

- ✅ **Strict mode enabled** - All strict TypeScript rules apply
- ✅ **Explicit types** - Always specify types explicitly
- ✅ **Proper imports** - Use specific imports, not `import *`
- ✅ **No unused variables** - Clean up unused imports/variables

### Database Standards

- ✅ **Connection safety** - Follow proper database connection patterns
- ✅ **Error handling** - Always handle database errors appropriately
- ✅ **Type safety** - Use proper TypeScript types for database operations
- ✅ **Async support** - Support async/await patterns

### Documentation Standards

- ✅ **JSDoc required** - Every database utility function must have JSDoc
- ✅ **Examples required** - 2-3 examples per database utility function
- ✅ **Usage descriptions** - Document when and how to use the utility
- ✅ **Configuration options** - Document all configuration options

## Build and Validation

### Pre-commit Checklist

Before committing, ensure:

1. **TypeScript compiles**: `npm run build`
2. **No type errors**: Check for TypeScript errors
3. **Exports correct**: Verify all exports are in `index.ts`
4. **Documentation complete**: JSDoc follows DOCSTYLE.md
5. **Tests pass**: `npm test` - all tests must pass
6. **Coverage maintained**: `npm run test:coverage` - maintain high coverage
7. **README updated**: Add new database utility to README.md with usage examples

### Validation Commands

```bash
# Full validation pipeline
npm run build
npm test
npm run test:coverage
```

## Example: Adding a `queryBuilder` Utility

### 1. Create File

```bash
touch src/queryBuilder.ts
```

### 2. Implement Database Utility

```typescript
// src/queryBuilder.ts
import { FilterQuery, QueryOptions } from 'mongoose';

/**
 * Query builder utility for constructing MongoDB queries with common patterns.
 *
 * Provides a fluent interface for building complex MongoDB queries
 * with validation and type safety.
 *
 * @example
 * const query = queryBuilder()
 *   .where('status', 'active')
 *   .where('age', { $gte: 18 })
 *   .sort('createdAt', -1)
 *   .limit(10)
 *   .build();
 *
 * const query = queryBuilder()
 *   .search('name', 'john')
 *   .paginate(1, 20)
 *   .build();
 */
export function queryBuilder() {
  const query: FilterQuery<any> = {};
  const options: QueryOptions = {};

  return {
    where(field: string, value: any) {
      query[field] = value;
      return this;
    },

    search(field: string, term: string) {
      query[field] = { $regex: term, $options: 'i' };
      return this;
    },

    sort(field: string, direction: 1 | -1) {
      options.sort = { [field]: direction };
      return this;
    },

    limit(count: number) {
      options.limit = count;
      return this;
    },

    skip(count: number) {
      options.skip = count;
      return this;
    },

    paginate(page: number, limit: number) {
      options.skip = (page - 1) * limit;
      options.limit = limit;
      return this;
    },

    build() {
      return { query, options };
    },
  };
}

export interface QueryBuilderResult {
  query: FilterQuery<any>;
  options: QueryOptions;
}
```

### 3. Create Test File

```typescript
// src/tests/queryBuilder.test.ts
import { queryBuilder } from '../queryBuilder';

describe('queryBuilder', () => {
  it('should build a simple where query', () => {
    const { query, options } = queryBuilder().where('status', 'active').build();

    expect(query).toEqual({ status: 'active' });
    expect(options).toEqual({});
  });

  it('should build a complex query with pagination', () => {
    const { query, options } = queryBuilder()
      .where('age', { $gte: 18 })
      .search('name', 'john')
      .sort('createdAt', -1)
      .paginate(2, 10)
      .build();

    expect(query).toEqual({
      age: { $gte: 18 },
      name: { $regex: 'john', $options: 'i' },
    });
    expect(options).toEqual({
      sort: { createdAt: -1 },
      skip: 10,
      limit: 10,
    });
  });

  // Add more tests...
});
```

### 4. Export Utility

```typescript
// src/index.ts
export { queryBuilder } from './queryBuilder';
export type { QueryBuilderResult } from './queryBuilder';
```

## Database Integration

### Using with MongoDB

For database utilities in MongoDB applications:

```typescript
import { mongoDBConnect, queryBuilder } from '@thalorlabs/database';

const connection = await mongoDBConnect();
const User = connection.model('User', userSchema);

// Use query builder
const { query, options } = queryBuilder()
  .where('status', 'active')
  .sort('createdAt', -1)
  .limit(10)
  .build();

const users = await User.find(query, null, options);
```

### Using with Connection Management

```typescript
import { mongoDBConnect } from '@thalorlabs/database';

// Get cached connection
const connection = await mongoDBConnect();

// Use connection for operations
const db = connection.connection.db;
const collection = db.collection('users');
```

### Using with Error Handling

```typescript
import { mongoDBConnect } from '@thalorlabs/database';

try {
  const connection = await mongoDBConnect();
  // Use connection
} catch (error) {
  console.error('Database connection failed:', error);
  // Handle connection errors
}
```

## Troubleshooting

### Common Issues

**TypeScript Compilation Errors**

- Check import statements and file paths
- Verify all required dependencies are installed
- Ensure proper TypeScript configuration

**Database Connection Issues**

- Verify MongoDB is running and accessible
- Check MONGO_URI environment variable
- Ensure proper connection options

**Export Issues**

- Verify all database utilities are exported in `index.ts`
- Check that individual exports are properly configured
- Ensure file names match export names

**Test Issues**

- Ensure all database utilities have corresponding test files
- Check that test coverage meets requirements
- Verify database utility behavior is properly tested

## Resources

- [DOCSTYLE.md](./DOCSTYLE.md) - JSDoc documentation standards
- [PUBLISHING.md](./PUBLISHING.md) - Package publishing guide
- [README.md](./README.md) - User documentation