gemini-configparser

1.4.2 verified Sat Apr 25 auth: no javascript

A configuration parser module for the Gemini (testplane) testing framework, version 1.4.2. It provides a declarative way to define configuration schemas using composable functions like `option`, `section`, `map`, and `root`. Supports parsing from CLI arguments, environment variables, and objects with validation and transformation. Differentiates from alternatives like `convict` by being tightly integrated with Gemini/testplane and offering a nested structure with functions.

Common errors

error Error: Unknown field 'extraField' ↓

cause Input data contains a key not defined in the schema.

fix

Remove the unknown key from input or add it to the section definition.

error Error: Expected number, got string ↓

cause parseEnv or parseCli returns a non-number when Number is expected.

fix

Ensure parseEnv/parseCli functions return the correct type; e.g., Number(rawValue) for numbers.

Warnings

gotcha All keys in the schema must be defined; unknown keys in input will be treated as errors. ↓

fix Include all possible keys in the section definition.

gotcha parseCli and parseEnv functions are applied to the raw string value; ensure they handle strings correctly. ↓

fix Wrap with Number() or String() as shown in quickstart.

gotcha defaultValue can be a function receiving config and currentNode for dynamic defaults. ↓

fix If you need a dynamic default, provide a function: defaultValue: (config, node) => ...

Install

npm install gemini-configparser

yarn add gemini-configparser

pnpm add gemini-configparser

Imports

option

wrong

import option from 'gemini-configparser'

correct

import { option } from 'gemini-configparser'

Default import is not supported; use named import.

section

wrong

const section = require('gemini-configparser').section

correct

import { section } from 'gemini-configparser'

CommonJS require works but TypeScript prefers import.

map

wrong

const map = require('gemini-configparser/map')

correct

import { map } from 'gemini-configparser'

map is a named export, not a submodule.

root

wrong

const root = require('gemini-configparser').root

correct

import { root } from 'gemini-configparser'

root is exported as named export.

Quickstart

Defines a config parser with nested sections, options with defaults and validation, then parses from options, env, and CLI arguments.

import { root, section, option } from 'gemini-configparser';

const configParser = root(section({
  server: section({
    port: option({
      defaultValue: 8080,
      parseEnv: Number,
      parseCli: Number,
      validate: (v) => { if (v < 0) throw new Error('port must be positive'); }
    }),
    host: option({
      defaultValue: 'localhost',
      parseEnv: String,
      parseCli: String
    })
  })
}), {
  envPrefix: 'MY_APP_',
  cliPrefix: '--'
});

const config = configParser({
  options: { server: { port: 3000 } },
  env: { MY_APP_SERVER_HOST: '0.0.0.0' },
  argv: ['--server:port', '4000']
});

console.log(config); // { server: { port: 4000, host: '0.0.0.0' } }