@dbs-portal/core-config/README.md

Advanced configuration management for DBS Portal with convict schema validation and deepmerge support

# @dbs-portal/core-config

Advanced configuration management for DBS Portal with convict schema validation and deepmerge support.

## Features

- 🔒 **Type-safe configuration** with TypeScript support
- ✅ **Schema validation** using convict for robust configuration validation
- 🔄 **Intelligent merging** with deepmerge for complex configuration scenarios
- 🌍 **Multiple providers** for loading configuration from various sources
- 🔧 **Environment-specific** configurations with validation
- 📦 **Modular architecture** with clean separation of concerns
- 🧪 **Comprehensive testing** with full test coverage

## Installation

```bash
yarn add @dbs-portal/core-config
```

## Quick Start

```typescript
import { ConfigManager, EnhancedObjectProvider, ConvictValidator } from '@dbs-portal/core-config'

// Create configuration providers
const defaultProvider = EnhancedObjectProvider.development()
const envProvider = EnhancedEnvironmentProvider.withValidation()

// Create configuration manager
const configManager = new ConfigManager({
  providers: [defaultProvider, envProvider],
  validators: [new ConvictValidator()],
  validateOnLoad: true,
  mergeStrategy: 'deep'
})

// Load and validate configuration
const config = await configManager.load()
console.log('Configuration loaded:', config)
```

## Core Components

### Convict Schema Validation

The package uses convict for robust schema validation with custom formats:

```typescript
import { loadAndValidateConfig, getValidatedConfig } from '@dbs-portal/core-config/schemas'

// Load and validate configuration
const config = loadAndValidateConfig({
  env: 'production',
  port: 8080,
  database: {
    host: 'prod-db.example.com',
    port: 5432
  }
})

// Get default validated configuration
const defaults = getValidatedConfig()
```

### Enhanced Providers

#### EnhancedEnvironmentProvider

Comprehensive environment variable mapping with type coercion:

```typescript
import { EnhancedEnvironmentProvider } from '@dbs-portal/core-config/providers'

// With validation enabled
const envProvider = EnhancedEnvironmentProvider.withValidation({
  prefix: 'APP',
  typeCoercion: true
})

// For Docker environments
const dockerProvider = EnhancedEnvironmentProvider.forDocker()

// For Kubernetes environments
const k8sProvider = EnhancedEnvironmentProvider.forKubernetes()
```

#### EnhancedObjectProvider

Object-based provider with deep cloning and validation:

```typescript
import { EnhancedObjectProvider } from '@dbs-portal/core-config/providers'

// Environment-specific providers
const devProvider = EnhancedObjectProvider.development()
const prodProvider = EnhancedObjectProvider.production()
const testProvider = EnhancedObjectProvider.testing()

// Custom configuration with validation
const customProvider = EnhancedObjectProvider.from({
  name: 'Custom App',
  port: 4000
}, {
  validateWithConvict: true,
  mergeWithDefaults: true
})
```

### ConvictValidator

Dedicated validator using convict schema:

```typescript
import { ConvictValidator } from '@dbs-portal/core-config/validators'

const validator = new ConvictValidator()

// Validate configuration
const result = validator.validate(config)
if (!result.isValid) {
  console.error('Validation errors:', result.errors)
}

// Validate specific path
const pathResult = validator.validatePath(config, 'database.host')

// Get schema defaults
const defaults = validator.getDefaults()
```

### Configuration Manager with Deepmerge

The ConfigManager uses deepmerge for intelligent configuration merging:

```typescript
import { ConfigManager } from '@dbs-portal/core-config/managers'

const manager = new ConfigManager({
  providers: [baseProvider, overrideProvider],
  mergeStrategy: 'deep', // or 'shallow'
  validateOnLoad: true,
  validateOnChange: true
})

// Arrays are replaced, not concatenated
// Objects are deeply merged
const config = await manager.load()
```

## Environment-Specific Configurations

```typescript
import { 
  createDevelopmentConfig,
  createProductionConfig,
  createStagingConfig,
  createTestConfig,
  getConfigForEnvironment
} from '@dbs-portal/core-config/defaults'

// Get configuration for specific environment
const devConfig = createDevelopmentConfig()
const prodConfig = createProductionConfig()

// Get configuration based on NODE_ENV
const config = getConfigForEnvironment(process.env.NODE_ENV as Environment)
```

## Configuration Schema

The package includes a comprehensive convict schema covering:

- **Application settings** (name, version, port, host)
- **Logging configuration** (level, format, file rotation)
- **Database settings** (connection, pooling, timeouts)
- **Authentication** (JWT, sessions, bcrypt)
- **API configuration** (timeouts, retries, CORS)
- **Storage providers** (local, S3, Azure, GCP)
- **Email providers** (SMTP, SendGrid, Mailgun)
- **Monitoring** (Sentry, Prometheus, health checks)
- **Feature flags** (LaunchDarkly, local flags)

## Validation Features

- **Type validation** with custom formats
- **Environment validation** (development, staging, production, test)
- **Port validation** with proper ranges
- **URL validation** for API endpoints
- **Email validation** for email addresses
- **Positive integer validation** for counts and timeouts
- **Required string validation** for critical fields

## Testing

The package includes comprehensive tests covering:

```bash
# Run tests
yarn test

# Run tests with coverage
yarn test:coverage

# Run tests in watch mode
yarn test:watch
```

## TypeScript Support

Full TypeScript support with proper type definitions:

```typescript
import type { AppConfig, Environment, ConfigProvider } from '@dbs-portal/core-config/types'

// Type-safe configuration access
const config: Partial<AppConfig> = await configManager.load()
const dbHost: string = config.database?.host ?? 'localhost'
```

## Package Exports

The package provides multiple entry points:

- `@dbs-portal/core-config` - Main entry point
- `@dbs-portal/core-config/types` - Type definitions
- `@dbs-portal/core-config/schemas` - Convict schemas
- `@dbs-portal/core-config/providers` - Configuration providers
- `@dbs-portal/core-config/validators` - Validation utilities
- `@dbs-portal/core-config/managers` - Configuration managers
- `@dbs-portal/core-config/defaults` - Default configurations

## Migration from Previous Version

The package maintains backward compatibility while adding new features:

```typescript
// Old usage still works
import { ConfigManager, ObjectProvider } from '@dbs-portal/core-config'

// New enhanced usage
import { ConfigManager, EnhancedObjectProvider, ConvictValidator } from '@dbs-portal/core-config'
```

## License

MIT