@pfeiferio/konfi

A strict, predictable JSON-based configuration loader with interpolation and merging.

konfi is designed for application startup configuration, not runtime templating. It focuses on deterministic behavior, explicit merging, and safe value resolution.

Features

• JSON configuration files
• Recursive config merging
• Value interpolation with fixpoint resolution
• Environment variable support
• Deterministic, testable behavior
• No magic defaults, no global state
• Zero dependencies

Installation

npm install @pfeiferio/konfi

Basic Usage

import { readConfig } from '@pfeiferio/konfi'

const config = readConfig('./config.json')

Typed Configuration (TypeScript)

konfi supports fully typed configuration using generics.

import { readConfig, readConfigs } from '@pfeiferio/konfi'

interface AppConfig {
  server: {
    host: string
    port: number
  }
  database: {
    url: string
  }
}

const config = readConfig<AppConfig>('./config.json')

// fully typed
config.server.host
config.server.port

Configuration Files

A configuration file is plain JSON.

{
  "server": {
    "host": "localhost",
    "port": 8080
  }
}

Nested structures are preserved.

Interpolation

Values may reference other config values or environment variables.

{
  "baseUrl": "http://${server.host}:${server.port}",
  "server": {
    "host": "localhost",
    "port": 8080
  }
}

Result:

{
  baseUrl: "http://localhost:8080",
  server: {
    host: "localhost",
    port: 8080
  }
}

Environment Variables

{
  "db": {
    "password": "${env.DB_PASSWORD}"
  }
}

Multiple Config Files

You can load and merge multiple config files in order:

import { readConfigs } from '@pfeiferio/konfi'

const config = readConfigs([
  './config.base.json',
  './config.prod.json'
])

Later files override earlier ones using strict merge rules.

Merge Semantics

• Plain objects are merged recursively
• Arrays are overwritten
• Primitives overwrite previous values
• Inputs are never mutated

This makes configuration behavior explicit and predictable.

Error Handling

• Invalid JSON throws immediately
• Circular or unresolved interpolation fails deterministically
• No silent fallbacks

Configuration errors are intended to surface at startup, not at runtime.

Design Goals

• Explicit configuration
• Deterministic startup behavior
• No implicit defaults
• Easy to reason about
• Suitable for backend and service configuration

konfi is not:

• a template engine
• a dotenv replacement
• a runtime configuration system

License

MIT