Hydra Config

Hydra-style hierarchical YAML configuration with composition, patterns, and deep merge for JavaScript.

Why Hydra Config?

Inspired by Facebook's Hydra for Python, this library brings powerful configuration composition to JavaScript projects.

Features

• 🔄 Composable: Build configs from reusable patterns
• 📊 Hierarchical: Define defaults, override as needed
• 🔍 Type-Safe: Optional schema validation
• 🎯 Framework-Agnostic: Works with any JS project
• 🪶 Lightweight: Only requires yaml and fs-extra
• 💪 Battle-Tested: Used in production by Supernal Coding

Installation

npm install @supernal/hydra-config

Quick Start

const { ConfigLoader } = require('@supernal/hydra-config');

const loader = new ConfigLoader({
  searchPaths: [
    './config/patterns', // Your patterns
    './node_modules/@supernal/hydra-config/patterns', // Default patterns
  ],
});

const config = await loader.load('./config/project.yaml');
console.log(config);

Usage

Basic Configuration

# config/project.yaml
project:
  name: 'my-app'
  version: '1.0.0'

database:
  host: 'localhost'
  port: 5432

Composition with Defaults

# config/project.yaml
defaults:
  - base: production
  - database: postgres
  - cache: redis
  - _self_ # Apply user overrides last

project:
  name: 'my-app' # Override from patterns

database:
  host: 'custom-host' # Override specific values

Pattern Files

# config/patterns/database/postgres.yaml
database:
  type: 'postgres'
  host: 'localhost'
  port: 5432
  ssl: true
  pool:
    min: 2
    max: 10

API Reference

ConfigLoader

Main class for loading and resolving configurations.

const loader = new ConfigLoader(options);

Options:

• searchPaths (Array): Directories to search for patterns
• cache (Map): Optional cache instance

Methods:

load(configPath)

Load and resolve a configuration file.

const config = await loader.load('./config/project.yaml');

get(configPath)

Get configuration (uses cache if available).

const config = await loader.get('./config/project.yaml');

clearCache()

Clear the configuration cache.

loader.clearCache();

Error Classes

• YAMLSyntaxError: Invalid YAML syntax
• PatternNotFoundError: Referenced pattern not found
• CircularDependencyError: Circular dependency in defaults

Advanced Features

Deep Merge Strategies

# Append arrays (default)
features: [auth, admin]

# Replace arrays
features:
  __replace__: true
  values: [public-only]

Pattern Search Paths

Patterns are searched in order:

1. User patterns (first in searchPaths)
2. Shipped patterns (later in searchPaths)

This allows users to override default patterns.

Circular Dependency Detection

The system automatically detects and reports circular dependencies:

CircularDependencyError: Circular dependency detected
  base → db-config → advanced → base

Examples

See the examples/ directory for complete working examples:

• Basic Usage
• Composition
• Pattern Library

Comparison to Other Solutions

| Feature | Hydra Config | config | convict | rc | | -------------- | ------------ | ------ | ------- | ----- | | YAML Patterns | ✅ | ❌ | ❌ | ❌ | | Composition | ✅ | ❌ | ❌ | ❌ | | Deep Merge | ✅ | ⚠️ | ❌ | ⚠️ | | Search Paths | ✅ | ❌ | ❌ | ⚠️ | | Error Messages | ✅ Rich | Basic | Basic | Basic |

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

License

MIT - See LICENSE for details.

Credits

Inspired by Hydra by Facebook Research.

Built and maintained by Supernal Intelligence.