Package Exports

@supernal/hydra-config
@supernal/hydra-config/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@supernal/hydra-config) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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:

User patterns (first in searchPaths)
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:

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.