npm package: @sailboat-computer/config-loader
Description: Configuration loader for sailboat computer services
Latest version: 1.1.56

# Configuration Loader

A configuration loader for the Sailboat Computer system that provides:

- Loading configuration from JSON files
- Validating configuration against JSON schemas
- Watching for configuration changes
- Environment variable overrides
- Default values
- Configuration versioning and rollback support

## Installation

```bash
npm install @sailboat-computer/config-loader
```

## Usage

### Basic Usage

```typescript
import { loadConfig } from '@sailboat-computer/config-loader';

// Load configuration with default values
const config = await loadConfig<MyConfig>(
  'my-service/config.json',
  defaultConfig
);

// Use configuration
console.log(config.someValue);
```

### With Validation

```typescript
import { loadConfig } from '@sailboat-computer/config-loader';

// Load configuration with validation
const config = await loadConfig<MyConfig>(
  'my-service/config.json',
  defaultConfig,
  { validate: true }
);

// The loader will automatically look for 'my-service/config.schema.json'
// and validate the configuration against it
```

### Watching for Changes

```typescript
import { createConfigLoader } from '@sailboat-computer/config-loader';

// Create a loader with watching enabled
const loader = createConfigLoader({ watch: true });

// Load configuration
const config = await loader.load<MyConfig>('my-service/config.json');

// Watch for changes
loader.watch('my-service/config.json', (event) => {
  console.log('Configuration changed:', event.config);
});
```

### Environment Variable Overrides

The configuration loader supports overriding configuration values using environment variables. The environment variable names are constructed as follows:

```
CONFIG_<PATH>_<KEY>
```

Where:
- `<PATH>` is the configuration file path with slashes and dots replaced by underscores and converted to uppercase
- `<KEY>` is the configuration key with dots replaced by underscores and converted to uppercase

For example, to override the `database.host` value in the `my-service/config.json` file, you would set the environment variable:

```
CONFIG_MY_SERVICE_CONFIG_DATABASE_HOST=localhost
```

### Saving Configuration

```typescript
import { saveConfig } from '@sailboat-computer/config-loader';

// Save configuration
await saveConfig<MyConfig>(
  'my-service/config.json',
  config,
  'Updated database settings', // Optional description
  'admin' // Optional user
);
```

### Configuration Versioning

```typescript
import { 
  saveConfig, 
  getConfigVersions, 
  getConfigVersion, 
  rollbackConfig 
} from '@sailboat-computer/config-loader';

// Save configuration with description
await saveConfig<MyConfig>(
  'my-service/config.json',
  config,
  'Updated database settings'
);

// Get all versions
const versions = await getConfigVersions('my-service/config.json');
console.log(`Available versions: ${versions.length}`);

// Get a specific version
const version = await getConfigVersion<MyConfig>('my-service/config.json', 1);
console.log(`Version 1 created at: ${version?.metadata.timestamp}`);

// Rollback to a previous version
const rolledBackConfig = await rollbackConfig<MyConfig>(
  'my-service/config.json',
  1,
  'Rollback to initial configuration'
);
```

## API

### `loadConfig<T>(path: string, defaultConfig?: T, options?: ConfigLoaderOptions): Promise<T>`

Loads configuration from a file.

- `path`: Path to the configuration file (relative to baseDir)
- `defaultConfig`: Default configuration to use if the file doesn't exist or to merge with
- `options`: Configuration loader options

### `saveConfig<T>(path: string, config: T, description?: string, user?: string, options?: ConfigLoaderOptions): Promise<void>`

Saves configuration to a file.

- `path`: Path to the configuration file (relative to baseDir)
- `config`: Configuration to save
- `description`: Optional description of the change
- `user`: Optional user who made the change
- `options`: Configuration loader options

### `getConfigVersions(path: string, options?: ConfigLoaderOptions): Promise<ConfigVersionMetadata[]>`

Gets all available versions for a configuration file.

- `path`: Path to the configuration file (relative to baseDir)
- `options`: Configuration loader options
- Returns: List of version metadata

### `getConfigVersion<T>(path: string, version: number, options?: ConfigLoaderOptions): Promise<ConfigVersion<T> | null>`

Gets a specific version of a configuration file.

- `path`: Path to the configuration file (relative to baseDir)
- `version`: Version number
- `options`: Configuration loader options
- Returns: Configuration version or null if not found

### `rollbackConfig<T>(path: string, version: number, description?: string, user?: string, options?: ConfigLoaderOptions): Promise<T>`

Rolls back to a specific version of a configuration file.

- `path`: Path to the configuration file (relative to baseDir)
- `version`: Version number
- `description`: Optional description of the rollback
- `user`: Optional user who performed the rollback
- `options`: Configuration loader options
- Returns: The rolled back configuration

### `createConfigLoader(options?: ConfigLoaderOptions): ConfigLoader`

Creates a configuration loader.

- `options`: Configuration loader options

### `ConfigLoaderOptions`

Options for the configuration loader:

- `baseDir`: Base directory for configuration files (default: 'config')
- `envPrefix`: Environment variable prefix for configuration overrides (default: 'CONFIG_')
- `validate`: Whether to validate configuration against schema (default: true)
- `watch`: Whether to watch for configuration changes (default: false)
- `required`: Whether to throw an error if configuration file is not found (default: false)
- `mergeDefaults`: Whether to merge with default values (default: true)
- `logger`: Custom logger

## License

MIT