@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

yarn add @dbs-portal/core-config

Quick Start

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:

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:

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:

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:

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:

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

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:

# 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:

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:

// 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