@quatrain/config

Multi-source configuration manager and registry for Quatrain applications and autonomous agent tools.

Provides seamless, zero-dependency configuration management featuring:

• Central Registry Pattern: Multi-tool isolation mirroring Backend, Storage, and Log.
• Fail-Fast Validation: Immediate ConfigurationError when critical parameters or API credentials are missing or blank.
• Multi-Source Resolution: Hierarchical priority cascading (Memory > Environment > Object / JSON).
• Sub-Scoping & Dot Notation: Clean delegation across namespaces (e.g., Config.scope('odoo').requireString('apiKey')).

Installation

yarn add @quatrain/config
Copy

Usage

1. Isolated Tool Configurations (Agent Gateway & Multi-Tool)

Register independent configurations for distinct third-party tools or external services without namespace collision:

import { Config } from '@quatrain/config'

// Register tool credentials
Config.addConfig('odoo', {
  url: 'https://erp.example.com',
  database: 'production',
  apiKey: 'odoo-secret-key',
})

Config.addConfig('google-drive', {
  clientId: 'gdrive-client-id',
  clientSecret: 'gdrive-client-secret',
})

// Retrieve tool configurations safely
const odoo = Config.getConfig('odoo')
const odooUrl = odoo.requireString('url')
const apiKey = odoo.requireString('apiKey')

// Scoped access
const gdrive = Config.scope('google-drive')
const clientId = gdrive.requireString('clientId')
Copy

2. Global Default Configuration & Fail-Fast Helpers

Use the global default container for application runtime variables:

import { Config } from '@quatrain/config'

// Sets or overrides values in the in-memory store
Config.set('server.port', 3000)
Config.set('server.host', '0.0.0.0')

// Strict fail-fast access (throws ConfigurationError if missing)
const port = Config.requireNumber('server.port')
const host = Config.requireString('server.host')
const secret = Config.requireString(
  'JWT_SECRET',
  'Set JWT_SECRET in your environment or .env file',
)

// Optional values with fallbacks
const logLevel = Config.getString('LOG_LEVEL', 'info')
Copy

3. Multi-Source Priority & Environment Mapping

ConfigContainer resolves parameters across registered sources by descending priority:

1. MemoryConfigSource (Priority: 100) — Runtime programmatic overrides.
2. EnvConfigSource (Priority: 50) — Process environment variables, supporting automatic UPPER_SNAKE_CASE mapping (database.host -> DATABASE_HOST).
3. ObjectConfigSource (Priority: 10) — Structured JavaScript objects or parsed JSON files.

import { Config, ObjectConfigSource, EnvConfigSource } from '@quatrain/config'

const container = Config.getConfig()
container.addSource(new ObjectConfigSource({ title: 'Default Title' }))
Copy

License

AGPL-3.0-only © Quatrain Développement SAS