@nexe/config-manager/README.md

Nexe Config Manager - A flexible configuration management solution with multiple sources and hot reload support

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

```bash
# 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

```typescript
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

```typescript
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

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

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

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

### JSON File

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

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

### YAML File

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

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

### Consul

```typescript
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:

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

```typescript
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

```typescript
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](https://github.com/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](https://github.com/aqz236/nexe/issues).