@nexe/config-manager

@nexe/config-manager

A flexible configuration management solution with multiple sources and hot reload support.

Features

• 🔧 Multiple Configuration Sources: Support for environment variables, JSON, YAML, TOML, Consul, and custom sources
• 🔄 Hot Reload: Automatic configuration updates with change notifications
• 📊 Priority-based Configuration: Layer configurations with different priorities
• 🎯 Type Safety: Strong typing with TypeScript decorators
• 🔌 Dependency Injection: Seamless integration with tsyringe
• 📝 Validation: Built-in configuration validation support
• 🚀 Easy to Use: Simple API with minimal setup

Installation

# Using bun
bun add @nexe/config-manager

# Using npm
npm install @nexe/config-manager

# Using yarn
yarn add @nexe/config-manager

Quick Start

1. Define Configuration Class

import { ConfigProperty, ConfigSection } from '@nexe/config-manager';

@ConfigSection('database')
export class DatabaseConfig {
  @ConfigProperty('host')
  host = 'localhost';

  @ConfigProperty('port')
  port = 5432;

  @ConfigProperty('username')
  username = '';

  @ConfigProperty('password')
  password = '';

  @ConfigProperty('database')
  database = 'myapp';
}

2. Setup Configuration Manager

import 'reflect-metadata';
import { container } from 'tsyringe';
import { 
  ConfigManager, 
  EnvironmentConfigSource,
  JsonConfigSource 
} from '@nexe/config-manager';

// Register config manager
container.registerSingleton('IConfigManager', ConfigManager);

// Get config manager instance
const configManager = container.resolve<ConfigManager>('IConfigManager');

// Add configuration sources (higher priority first)
configManager.addSource(new EnvironmentConfigSource(), 100);
configManager.addSource(new JsonConfigSource('./config.json'), 50);

3. Use Configuration

// Get typed configuration
const dbConfig = await configManager.getConfig(DatabaseConfig);
console.log(`Connecting to ${dbConfig.host}:${dbConfig.port}`);

// Get individual values
const host = await configManager.get<string>('database.host', 'localhost');

Configuration Sources

Environment Variables

import { EnvironmentConfigSource } from '@nexe/config-manager';

configManager.addSource(new EnvironmentConfigSource(), 100);

JSON File

import { JsonConfigSource } from '@nexe/config-manager';

configManager.addSource(new JsonConfigSource('./config.json'), 50);

YAML File

import { YamlConfigSource } from '@nexe/config-manager';

configManager.addSource(new YamlConfigSource('./config.yaml'), 50);

Consul

import { ConsulConfigSource } from '@nexe/config-manager';

const consulSource = new ConsulConfigSource({
  host: 'localhost',
  port: 8500,
  basePath: 'config/myapp'
});

configManager.addSource(consulSource, 75);

Hot Reload

Subscribe to configuration changes:

// Subscribe to specific key changes
configManager.subscribe<string>('database.host', (newHost) => {
  console.log(`Database host changed to: ${newHost}`);
});

// Subscribe with path prefix
configManager.subscribe<number>('port', (newPort) => {
  console.log(`Port changed to: ${newPort}`);
}, { pathPrefix: 'database' });

Advanced Usage

Custom Configuration Source

import { IConfigSource } from '@nexe/config-manager';

export class CustomConfigSource implements IConfigSource {
  async load(key?: string): Promise<unknown> {
    // Your custom loading logic
    return value;
  }

  getName(): string {
    return 'custom-source';
  }

  supportsHotReload(): boolean {
    return false;
  }
}

configManager.addSource(new CustomConfigSource(), 25);

Configuration Factory

import { ConfigFactory } from '@nexe/config-manager';

// Use factory for convenient setup
const factory = new ConfigFactory();
factory
  .addEnvironmentSource(100)
  .addJsonSource('./config.json', 50)
  .addYamlSource('./config.yaml', 25);

const configManager = factory.build();

API Reference

ConfigManager

• addSource(source: IConfigSource, priority?: number): Add a configuration source
• get<T>(key: string, defaultValue?: T, options?: ConfigOptions): Get a configuration value
• getConfig<T>(configClass: new () => T, options?: ConfigOptions): Get a typed configuration object
• subscribe<T>(key: string, callback: (value: T) => void, options?: ConfigOptions): Subscribe to configuration changes
• unsubscribe(key: string, options?: ConfigOptions): Unsubscribe from configuration changes

Decorators

• @ConfigSection(section: string): Mark a class as a configuration section
• @ConfigProperty(key: string): Mark a property as a configuration property

License

MIT © aqz236

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

If you have any questions or issues, please open an issue on GitHub.