seniority/precedence

flag > env > config file > package.json field > default

import { screaming, envName, envBoolean, … } from 'seniority/precedence';

function envBoolean(raw: string): boolean | undefined;

function envName(name: string, spec: OptionSpec, prefix: string | undefined): string | undefined;

function resolve(specs: Record<string, OptionSpec>, layers: Layers): Resolution;

function screaming(name: string): string;

class ConfigError extends Error {
    readonly hint?: string | undefined;
    constructor(message: string, hint?: string | undefined);
}

const ORDER: readonly ["flag", "env", "config", "package", "default"];

const RANK: Readonly<Record<BuiltinSource, number>>;

interface Candidate {
    source: Source;
    location: string;
    /** `undefined` when the layer had nothing for this option. */
    value: unknown;
    /** The line in `location` that set it, when the layer knows (R3). */
    line?: number;
}

interface Layer {
    path: string;
    data: Record<string, unknown>;
    /**
     * Key → the line in `path` that sets it, when the loader could tell (R3, R12). Optional
     * everywhere: a `.js` config has no line a parser can hand back without a parser, and a
     * missing line is reported as a missing line rather than as line zero.
     */
    lines?: Record<string, number>;
}

interface Layers {
    /** What the user typed: only options present on the command line. */
    flags: Record<string, unknown>;
    env: Record<string, string | undefined>;
    /** With a prefix, an option without `env:` reads `PREFIX_OPTION_NAME` (R2). */
    envPrefix?: string;
    config?: Layer;
    /** The `package.json` field named after the program, when present. */
    pkg?: Layer;
    /** Plugin-contributed sources, already read — see `seniority/plugin`'s `sources()`. */
    sources?: readonly SourceLayer[];
}

interface OptionSpec {
    /** Only `'boolean'` changes how the environment is read; everything else stays text. */
    type?: string;
    /** Environment variable consulted when the flag is absent (V2). */
    env?: string;
    default?: unknown;
}

interface Provenance {
    source: Source;
    /** The env name, the config file, or `package.json` — where a person would look. */
    location?: string;
    /** The line within `location`, when the layer recorded one (R3). A file source may; an env name cannot. */
    line?: number;
}

interface Resolution {
    values: Record<string, unknown>;
    provenance: Record<string, Provenance>;
    candidates: Record<string, Candidate[]>;
}

interface SourceLayer {
    /** The kind `--explain` prints and `provenance.source` carries: the plugin's own name for it. */
    source: string;
    /** Where a person would look — a path, a URL, a variable set. */
    location: string;
    /** Against `RANK`; strictly between `RANK.flag` and `RANK.default`. */
    rank: number;
    data: Record<string, unknown>;
}

type BuiltinSource = (typeof ORDER)[number];

type Source = BuiltinSource | (string & {});