@biorate/config

Application configurator — hierarchical key-value store with string interpolation, references, and template expressions.

Features

• get / has / set / merge — standard config API with dot-notation and array paths.
• String interpolation — ${path} and @{path} placeholders resolve to other config values.
• Link references — #{path} points to an entire subtree.
• RegExp templates — R{/pattern/flags} creates RegExp objects at config runtime.
• Function templates — F{args => body} creates executable functions.
• Empty value templates — !{object}, !{array}, !{void}, !{null}, !{string} produce typed empty values.
• Toggle per template type — Config.Template.* flags enable/disable individual template processors.
• Recursive templating — get() resolves templates on read (not on merge), so circular-safe.

Installation

pnpm add @biorate/config

Requires @biorate/errors, @biorate/inversion, traverse, lodash-es (peer).

Quick start

import { Config } from '@biorate/config';

const config = new Config();

config.set('host', 'localhost');
config.set('port', 3000);
config.merge({ url: 'http://${host}:${port}/api' });

console.log(config.get<string>('url')); // 'http://localhost:3000/api'
console.log(config.has('host'));        // true

Module reference

Config — Main class

import { Config } from '@biorate/config';

Decorated with @injectable() for DI use.

Static members

| Member | Signature | Description | |---------------------|------------------------------------------------|--------------------------------------| | Config.Template | static Template: { string, link, regexp, function, empty } | Toggle each template type (true by default). |

Instance members

| Member | Signature | Description | |------------|---------------------------------------------------------|-------------------------------------------------------| | get<T> | get<T = unknown>(path, def?): T | Resolves path. Throws UndefinedConfigPathError if no def. String/object values are template-resolved. | | has | has(path): boolean | Checks if path exists in the data tree. | | set | set(path, value): void | Sets a value at the path (creates intermediates). | | merge | merge(data): void | Deep merges data into the store via lodash.merge. |

path is of type PropertyPath = string | string[] — dot-separated or array paths.

Template types

Configured per key by flag:

Config.Template.string = false;    // disable ${...} / @{...} interpolation
Config.Template.link = false;      // disable #{...} references
Config.Template.regexp = false;    // disable R{/pattern/}  
Config.Template.function = false;  // disable F{...} function creation
Config.Template.empty = false;     // disable !{...} empty values

IConfig — Interface

import { IConfig } from '@biorate/config';

interface IConfig {
  get<T>(path: PropertyPath, def?: T): T;
  has(path: PropertyPath): boolean;
  set(path: PropertyPath, value: unknown): void;
  merge(data: unknown): void;
}

The contract used by DI consumers. Config implements IConfig.

IResult — Template result type

import { IResult } from '@biorate/config';

type IResult = {
  value: string | RegExp | (() => unknown) | unknown[] | unknown | Record<string, unknown> | null | undefined;
};

Internal type representing the resolved value after a template processor runs.

UndefinedConfigPathError — Error class

import { UndefinedConfigPathError } from '@biorate/config';

class UndefinedConfigPathError extends BaseError {
  constructor(path: PropertyPath);
}

Thrown by config.get(path) when a path does not exist and no default value is provided.

Template reference

String interpolation — ${...} / @{...}

config.merge({
  protocol: 'https://',
  host: 'hostname.ru',
  path: 'main',
  url1: '${protocol}${host}/${path}',
  url2: '@{protocol}@{host}/@{path}',
});

config.get('url1'); // 'https://hostname.ru/main'
config.get('url2'); // 'https://hostname.ru/main'

Both $ and @ prefixes work identically. Supports recursion — templates within templates resolve iteratively.

Link references — #{...}

config.merge({
  obj1: { a: 1, b: 2 },
  obj2: '#{obj1}',
});

config.get('obj2'); // { a: 1, b: 2 } — same object reference (via config lookup)

The entire value at the referenced path is injected.

RegExp templates — R{/pattern/flags}

config.merge({
  regexp: 'R{/^test$/igm}',
});

const re = config.get<RegExp>('regexp');
console.log(re.test('test')); // true

Creates a RegExpExt instance (extends RegExp with custom toJSON()).

Function templates — F{args => body}

config.merge({
  sum: 'F{a, b => return a + b;}',
});

const fn = config.get<(a: number, b: number) => number>('sum');
console.log(fn(1, 2)); // 3

Arguments are comma-separated, body follows =>.

Empty templates — !{type}

| Template | Result | |-----------------|-------------| | '!{object}' | {} | | '!{array}' | [] | | '!{void}' | undefined | | '!{null}' | null | | '!{string}' | "" | | '!{ }' | null |

Architecture

Config implements IConfig
│
├── data: {}                         Internal object tree
├── Template (static flags)          Toggle processors
│
├── get(path, def?)
│   ├── lodash.get(data, path)
│   ├── if string → template(value)
│   │   ├── Template.string()        Replace ${...} / @{...}
│   │   ├── Template.link()          Replace #{...}
│   │   ├── Template.regexp()        Parse R{/.../}
│   │   ├── Template.function()      Parse F{...}
│   │   └── Template.empty()         Parse !{...}
│   ├── if object → templatize()     Recursive via traverse
│   └── throw UndefinedConfigPathError if missing and no def
│
├── has(path)                        lodash.has(data, path)
├── set(path, value)                 lodash.set(data, path, value)
└── merge(data)                      lodash.merge(data, data)

Learn

• Documentation can be found here - docs.

Release History

See the CHANGELOG

License

MIT

Copyright (c) 2021-present Leonid Levkin (llevkin)