seniority

seniority — which source outranks the others.

import { explain, ConfigError, envBoolean, … } from 'seniority';

FunctionsCopy Anchor Link

checkCopy Anchor Link

The throwing form: the resolved values, or one CONFIG-class error listing every violation. validate is the record; this is the rendering a program that just wants to exit reaches for (E1, E3 — a message and a hint, never a stack).

function check(shape: Record<string, Shape>, resolution: Resolution): Record<string, unknown>;

Returns Record<string, unknown>

decodeFileContentCopy Anchor Link

A config file saved as UTF-16 — PowerShell's Out-File default on Windows — is not valid UTF-8, and reading it as UTF-8 produces text no parser can use. A UTF-8 BOM is deliberately left where it is: that is what 10.0.1 does, and one of its four cases asserts it.

function decodeFileContent(buffer: Buffer): string;

Returns string

explanationEventCopy Anchor Link

The agent rendering: the family's { event, data } envelope over the same projection.

function explanationEvent(e: Explanation): ExplanationEvent;

Returns ExplanationEvent

explanationJsonCopy Anchor Link

The --json rendering: the same record, with set spelled out rather than inferred from a missing key.

function explanationJson(e: Explanation): ExplanationJson;

Returns ExplanationJson

getDefaultSearchPlacesCopy Anchor Link

.foorc, .foorc.json, foo.config.js, … — the async explorer's twenty-one places, in order.

function getDefaultSearchPlaces(moduleName: string): string[];

Returns string[]

getDefaultSearchPlacesSyncCopy Anchor Link

The same list minus every .mjs: a synchronous load cannot import an ES module.

function getDefaultSearchPlacesSync(moduleName: string): string[];

Returns string[]

getPropertyByPathCopy Anchor Link

A property name, or a period-delimited path, or an array of names.

function getPropertyByPath(source: unknown, path: string | readonly string[]): unknown;

Returns unknown

loaderForCopy Anchor Link

The loader for a path, or the USAGE refusal that names what is missing.

function loaderFor(filepath: string, loaders?: Readonly<Record<string, Loader>>): Loader;

Returns Loader

loadPathCopy Anchor Link

Read one file and parse it. The object check is here rather than in each loader so a caller's loader cannot be the reason a non-object reaches the resolver.

function loadPath(filepath: string, options?: LoadOptions): Promise<Record<string, unknown>>;

Returns Promise<Record<string, unknown>>

searchCopy Anchor Link

The nearest match, or undefined.

function search(names: string | readonly string[], options: SearchOptions): Found | undefined;

Returns Found \| undefined

searchAllCopy Anchor Link

Every match on the way up, nearest directory first and, within a directory, in the order given.

function searchAll(names: string | readonly string[], options: SearchOptions): Found[];

Returns Found[]

truthTableCopy Anchor Link

Every combination of order, grouped by winner, highest first: each source, then every subset of the sources below it in increasing binary order, and last the row with nothing set. 2ⁿ rows for n sources, each row and its set frozen.

function truthTable<S extends string>(order: readonly S[]): TruthRow<S>[];

Returns TruthRow<S>[]

validateCopy Anchor Link

Every violation, in the order the shape declares its options — never the first one alone. A config file with three mistakes should be fixable in one pass, not three runs.

function validate(shape: Record<string, Shape>, resolution: Resolution): Violation[];

Returns Violation[]

ClassesCopy Anchor Link

LoaderErrorCopy Anchor Link

A format nobody declared a loader for.

class LoaderError extends Error {
    readonly extension: string;
    readonly hint: string;
    readonly exitCode = 2;
    constructor(message: string, extension: string, hint: string);
}

ConstantsCopy Anchor Link

builtinLoadersCopy Anchor Link

The four Node can read unaided. Frozen: one caller's loaders['.json'] = … must not reach another's.

const defaultLoaders: Readonly<Record<string, Loader>>;

defaultLoadersCopy Anchor Link

The async loader table. Frozen: index.test.ts asserts that deleting a key throws.

const defaultLoaders: Readonly<Record<string, Loader>>;

defaultLoadersSyncCopy Anchor Link

The sync table: no .mjs, no .mts, and loadJsSync in place of loadJs.

const defaultLoadersSync: Readonly<Record<string, Loader>>;

globalConfigSearchPlacesCopy Anchor Link

Tried in the user's global config directory, which is always the last directory a global search visits.

const globalConfigSearchPlaces: string[];

globalConfigSearchPlacesSyncCopy Anchor Link

The same, minus .mjs.

const globalConfigSearchPlacesSync: string[];

metaSearchPlacesCopy Anchor Link

Where cosmiconfig looks for its own configuration — the cosmiconfig key of a .config/config.* or a package.json. Internal to 10.0.1 and exported here because the meta explorer is the one part of the option pipeline a caller can observe.

const metaSearchPlaces: string[];

NOT_BUNDLEDCopy Anchor Link

The formats a caller may supply and this package will not bundle, listed so the refusal can name them and so a reader can see the 747 M/wk that is being declined rather than missed.

const NOT_BUNDLED: readonly string[];

TRUTH_TABLECopy Anchor Link

The table for the five built-in sources: 32 rows, frozen to the last array.

const TRUTH_TABLE: readonly TruthRow[];

WALK_LIMITCopy Anchor Link

How many directories one walk may visit.

const WALK_LIMIT = 64;

InterfacesCopy Anchor Link

ExplanationEventCopy Anchor Link

interface ExplanationEvent {
    event: 'config.explain';
    data: ExplanationJson;
}

ExplanationJsonCopy Anchor Link

interface ExplanationJson {
    option: string;
    value?: unknown;
    source?: string;
    location?: string;
    line?: number;
    candidates: ExplanationCandidateJson[];
}

FoundCopy Anchor Link

interface Found {
    /** The file, absolute. */
    path: string;
    /** The directory it was found in, absolute. */
    dir: string;
    /** How many steps up from `cwd` — `0` is `cwd` itself. What `--explain` prints as "found N levels up". */
    depth: number;
}

LoadOptionsCopy Anchor Link

interface LoadOptions {
    /** Merged over `defaultLoaders`; a caller may add a format or replace a builtin. */
    loaders?: Readonly<Record<string, Loader>>;
}

SearchOptionsCopy Anchor Link

interface SearchOptions {
    /** Where the walk starts. The first directory checked, not the first one above it. */
    cwd: string;
    /** The highest directory the walk may look in, inclusive. Defaults to the filesystem root. */
    stopAt?: string;
    /** Directories to visit at most. Defaults to `WALK_LIMIT`; a smaller number wins. */
    limit?: number;
    /** Injected for tests and for a caller with its own filesystem. Defaults to `existsSync`. */
    exists?: (path: string) => boolean;
    /** Injected the same way. Defaults to `realpathSync`, and a path that cannot be resolved is used as written. */
    realpath?: (path: string) => string;
}

ShapeCopy Anchor Link

What validation reads from a manifest, and no more.

interface Shape {
    type?: string;
    choices?: readonly unknown[];
    required?: boolean;
    default?: unknown;
}

TruthRowCopy Anchor Link

One combination: the sources that set a value, in the order given, and the one that wins.

interface TruthRow<S extends string = BuiltinSource> {
    readonly set: readonly S[];
    /** The first source of `set` in the order, or `null` when nothing set a value. */
    readonly winner: S | null;
}

ViolationCopy Anchor Link

interface Violation {
    key: string;
    /** The whole sentence, ready to print: the rule, then where the value came from. */
    message: string;
    /** What the value should have been — `'a string'`, `'one of fast, safe'`. */
    expected: string;
    value: unknown;
    /** Absent only for a required option that no source set: there is no origin to name. */
    provenance?: Provenance;
}

TypesCopy Anchor Link

LoaderCopy Anchor Link

What a loader is handed and what it gives back. The same shape cosmiconfig uses, so a caller's loader ports unchanged.

type Loader = (filepath: string, content: string) => unknown;

Re-exportedCopy Anchor Link

Documented on the page of the entry point that declares them.