LayerC 🧥

Extensible configuration infrastructure for modern applications.

LayerC is a functional, middleware-based configuration engine inspired by RxJS. It provides a unified way to load, parse, and merge configuration from files, environment variables, and memory, with built-in support for audit tracing and type safety.

Features

• Functional API: Declarative configuration using high-order middleware functions.
• Middleware-based: Easily compose loaders, parsers, and merge strategies.
• Audit Tracing: Know exactly which file or environment variable set a specific value.
• Type Safety: Full TypeScript support with generics for your configuration schema.
• Multi-format: Supports JSON (default), YAML, TOML, and INI via optional adapters.
• Conflict Detection: Automatically detects and reports value overrides and type changes.

Installation

npm install layerc
# Or with adapters
npm install @layerc/loaders

Quick Start

import { layerc, file, env, load, yamlParser } from 'layerc';

interface AppConfig {
  port: number;
  db: {
    url: string;
  };
}

const { data } = await load(
  layerc<AppConfig>({ cwd: './config' },
    // 1. Add YAML support via adapter
    use(yamlParser),
    
    // 2. Load base files
    file('default.json'),
    file('production.yaml', { optional: true }),
    
    // 3. Override with env variables (APP_PORT -> port)
    env('APP_'),
    
    // 4. Map prefixed env vars to nested paths (DB_URL -> db.url)
    env('DB_', 'db')
  )
);

console.log(`Server starting on port ${data.port}...`);

Core Middlewares

| Middleware | Description | |------------|-------------| | file(path, options) | Loads a configuration file (auto-detects format). | | env(prefix, targetPath, options) | Loads environment variables with optional mapping. | | object(data, options) | Injects a plain JavaScript object. | | use(...extensions) | Registers parsers (YAML/TOML/etc) or loaders. | | strategy(path, strategy) | Sets custom merge logic for a specific path. |

Advanced Usage

Custom Merge Strategies

import { strategy, builtInStrategies } from 'layerc';

layerc()
  .use(strategy('tags', builtInStrategies.append)) // Append to arrays instead of overriding
  .file('config.json')
  .load();

Structured Calling (Destructuring)

The resolution result is designed for easy access:

const { data, get, traceOf, diagnostics } = await layerc('config.json').load();

const port = get('server.port');
const trace = traceOf('server.port'); // { current: { sourceId: 'env:1', ... }, history: [...] }

Documentation

• API Reference
• Architecture
• Design Principles

Development

CI/CD

This project uses GitHub Actions for CI/CD.

• CI: Runs on every push to main and on pull requests. It performs building, linting, typechecking, and testing.
• Release: Runs when a new tag starting with v (e.g., v0.1.0) is pushed. It builds and publishes all packages to npm.

Note for maintainers: Ensure you have an NPM_TOKEN secret configured in your GitHub repository settings to enable automated publishing.

License

MIT