@thalorlabs/database/DOCSTYLE.md

Database utilities and connection helpers for TypeScript applications with MongoDB support

# DOCSTYLE.md — @thalorlabs/database

📄 JSDoc Standards for Database Utilities

This document defines the standards for documenting database utilities in @thalorlabs/database. The goal is to make database utilities easy to understand, maintain, and use across projects while keeping the docs concise and informative.

## 1. General Rules

- **Keep it clear**: database utilities should have descriptive, concise docs.
- **Include**:
  - Description (what the utility does and when to use it)
  - `@example` with common usage patterns
  - Configuration options and error handling
- **Exclude**:
  - Owners, version numbers, dates → track via git and package.json
  - Use `@remarks` sparingly, only for non-obvious behavior or constraints.

### Database Utility Policy

**This package only contains ThalorLabs database utilities** - standardized database patterns for our applications.

- ✅ Document: `mongoDBConnect`, `queryBuilder`, `migrationHelper` (our database utility contracts)
- ❌ Never document: Third-party database libraries, ORM-specific utilities
- Keep application-specific database logic local to the service that uses it

## 2. Template

```typescript
/**
 * Brief description of what the database 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
}
```

## 3. Examples

### Database Connection Utility

```typescript
/**
 * MongoDB connection utility with connection caching and error handling.
 *
 * Establishes a connection to MongoDB using the configured URI and options.
 * Implements connection caching to prevent multiple connections to the same database.
 * Handles connection errors and provides proper cleanup.
 *
 * @example
 * const connection = await mongoDBConnect();
 *
 * const connection = await mongoDBConnect();
 * const db = connection.connection.db;
 *
 * try {
 *   const connection = await mongoDBConnect();
 *   console.log('Connected to MongoDB');
 * } catch (error) {
 *   console.error('Connection failed:', error);
 * }
 */
export async function mongoDBConnect(): Promise<Mongoose> {
  // Connection logic
}
```

### Query Builder Utility

```typescript
/**
 * Query builder utility for constructing MongoDB queries with common patterns.
 *
 * Provides a fluent interface for building complex MongoDB queries
 * with validation and type safety. Supports filtering, sorting, pagination, and search.
 *
 * @example
 * const { query, options } = queryBuilder()
 *   .where('status', 'active')
 *   .sort('createdAt', -1)
 *   .limit(10)
 *   .build();
 *
 * const { query, options } = queryBuilder()
 *   .search('name', 'john')
 *   .paginate(1, 20)
 *   .build();
 */
export function queryBuilder() {
  // Query builder logic
}
```

### Migration Utility

```typescript
/**
 * Database migration utility for managing schema changes and data transformations.
 *
 * Provides a framework for running database migrations with version tracking
 * and rollback capabilities. Supports both up and down migrations.
 *
 * @example
 * await migrationHelper.runMigrations();
 *
 * await migrationHelper.runMigration('add-user-indexes', {
 *   up: async (db) => { /* migration logic */ },
 *   down: async (db) => { /* rollback logic */ }
 * });
 */
export async function migrationHelper(
  migrationName: string,
  migration: MigrationDefinition
): Promise<void> {
  // Migration logic
}
```

### Database Utility Types

```typescript
/**
 * Configuration options for database utilities.
 *
 * Defines all available configuration options with their types and defaults.
 * Used to provide type safety and IntelliSense for database utility configuration.
 */
export interface DatabaseUtilityOptions {
  option1?: string;
  option2?: number;
  option3?: boolean;
}

/**
 * Result type for database utility operations.
 *
 * Ensures consistent return types across database utilities.
 * Used for type safety and error handling.
 */
export interface DatabaseUtilityResult {
  success: boolean;
  data?: any;
  error?: string;
}
```

## 4. Documentation Standards

### Database Utility Function Documentation

- **Description**: What the utility does and when to use it
- **Configuration**: Document all configuration options and their defaults
- **Usage notes**: Any important behavior or error handling requirements
- **Examples**: 2-3 examples showing common usage patterns
- **Error handling**: Document how errors are handled and what responses are returned

### Configuration Interface Documentation

- **Properties**: Document all configuration properties
- **Optional properties**: Note which properties are optional and their defaults
- **Type information**: Explain the type and purpose of each property
- **Usage examples**: Show how to use the configuration in practice

### Type Definition Documentation

- **Purpose**: What the type represents
- **Generic parameters**: Document any generic type parameters
- **Usage**: How the type is typically used in database utilities
- **Constraints**: Any type constraints or requirements

## 5. Examples Guidelines

- **Basic usage**: Show typical database utility usage patterns
- **Configuration**: Demonstrate different configuration options
- **Error handling**: Show how errors are handled and what responses are returned
- **Integration**: Show how utilities work with MongoDB and other database operations
- **Real-world scenarios**: Include practical examples from actual use cases

## 6. Notes

- Examples are mandatory for all database utility functions and types
- Show both utility creation and usage patterns
- Include configuration examples where relevant
- Use consistent formatting and spacing
- Reference related database utilities and types in examples
- Always show the complete utility signature with proper types