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

npm install @sailboat-computer/config-loader

Usage

Basic Usage

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

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

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

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

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