# burgee/config

> Every export of burgee/config, with its signature and doc comment: ConfigError, envName, resolve, screaming, explain, plus 5 types.

Source: https://burgee.interlace.tools/docs/api/config

<!-- Generated by scripts/api-reference.ts from the built dist/*.d.ts. Do not edit; run `npx tsx scripts/api-reference.ts`. -->

`burgee/config` — the configuration layer, by itself.

Precedence, provenance and `--explain` come from `seniority`, the package whose job that
is. They were re-exported from the root barrel until the barrel's cost was measured
(see `index.ts`): 3,135 bundled bytes on the startup path of every program, for a
surface a program only touches when it wants to read or explain its own configuration.

```ts
import { ConfigError, envName, resolve, … } from 'burgee/config';
```

## Functions

### envName

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

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |
| `spec` | `OptionSpec` |
| `prefix` | `string \| undefined` |

**Returns** `string \| undefined`

### explain

The rendered form: what `--explain` prints.

```ts
function explain(name: string, resolution: Resolution): string;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |
| `resolution` | `Resolution` |

**Returns** `string`

### resolve

Every declared option, resolved through the layers; a missing required one is left undefined for the caller to report.

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

| Parameter | Type |
| :-- | :-- |
| `specs` | `Record<string, OptionSpec>` |
| `layers` | `Layers` |

**Returns** `Resolution`

### screaming

`region` → `REGION`, `dryRun` → `DRY_RUN`, `log-level` → `LOG_LEVEL` (yargs #2005: never camel-cased back).

```ts
function screaming(name: string): string;
```

| Parameter | Type |
| :-- | :-- |
| `name` | `string` |

**Returns** `string`

## Classes

### ConfigError

A value that cannot be used as configured: exit CONFIG (3), never a stack (E1, E3).

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

## Interfaces

### Candidate

```ts
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;
}
```

### Layers

```ts
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[];
}
```

### Provenance

```ts
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;
}
```

### Resolution

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

## Types

### Source

An **open** union (R13, PLAN D5). A plugin's source is a `Source` seniority has never
heard of; `(string & {})` keeps the five as completions while admitting the rest, so the
`sources` host of PLAN 1.3 is the additive change it reads as rather than a type break.

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