# seniority/config

> Every export of seniority/config, with its signature and doc comment: deepMerge, lineOf, loadWithExtends, candidates, discover, plus 3 types.

Source: https://seniority.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`. -->

```ts
import { deepMerge, lineOf, loadWithExtends, … } from 'seniority/config';
```

## Functions

### candidates

The discovery order as candidate paths, first hit wins; each entry says why it was tried.

```ts
function candidates(d: Discovery): {
    path: string;
    reason: string;
}[];
```

| Parameter | Type |
| :-- | :-- |
| `d` | `Discovery` |

**Returns** `{ path: string; reason: string; }[]`

### deepMerge

Objects merge recursively; anything else, the later value wins.

```ts
function deepMerge(base: Record<string, unknown>, over: Record<string, unknown>): Record<string, unknown>;
```

| Parameter | Type |
| :-- | :-- |
| `base` | `Record<string, unknown>` |
| `over` | `Record<string, unknown>` |

**Returns** `Record<string, unknown>`

### discover

Discover and load. `package.json#<name>` is not a file here — the engine reads the
owning package.json itself and treats the field as its own layer, below config.

```ts
function discover(d: Discovery): Promise<Loaded | undefined>;
```

| Parameter | Type |
| :-- | :-- |
| `d` | `Discovery` |

**Returns** `Promise<Loaded \| undefined>`

### lineOf

The line a top-level key is set on, one-based, or `undefined`.

Text, not a parse tree: a JSON parser that reported positions would *be* a parser, and
`JSON.parse` reports none. The scan is exact about what it can answer — a `"key":` on a
line — and silent about what it cannot, because a wrong line number in an error message
is worse than no line number at all (R3, R12).

```ts
function lineOf(text: string, key: string): number | undefined;
```

| Parameter | Type |
| :-- | :-- |
| `text` | `string` |
| `key` | `string` |

**Returns** `number \| undefined`

### loadWithExtends

Load a file and everything it extends, outermost first, the file's own keys winning.

The lines reported are the **extending file's own** (R3). A value a parent set and the
child did not override is cited through `chain` at the parent's path; a line number
borrowed across files would point confidently at the wrong text.

```ts
function loadWithExtends(path: string, options?: LoadConfigOptions, seen?: string[]): Promise<Loaded>;
```

| Parameter | Type |
| :-- | :-- |
| `path` | `string` |
| `options` (optional) | `LoadConfigOptions` |
| `seen` (optional) | `string[]` |

**Returns** `Promise<Loaded>`

## Interfaces

### Discovery

```ts
interface Discovery {
    name: string;
    cwd: string;
    env: Record<string, string | undefined>;
    /** `--config <path>`. */
    explicit?: string;
    /** `--no-config`. */
    disabled?: boolean;
    /** Extra loaders, by extension, merged over the four builtins (R6). */
    loaders?: Readonly<Record<string, Loader>>;
    /**
     * The extensions tried in the current directory, in order. Defaults to the four Node can
     * read; a program that injected a `.yaml` loader adds `.yaml` here. The two are separate
     * because supplying a parser and asking discovery to look for that format are different
     * decisions, and a program may want either without the other.
     */
    extensions?: readonly string[];
    /**
     * Walk up from `cwd` looking for the same names (R5). **Off by default**: a config found
     * in a directory the user did not name is the kind of surprise `--explain` exists to
     * prevent, so it is a program's decision rather than an ambient behaviour.
     */
    upward?: boolean;
    /** The highest directory an upward walk may look in, inclusive. Defaults to the filesystem root (Y10). */
    stopAt?: string;
}
```

### LoadConfigOptions

Options that reach a load, threaded through `extends` so every file in a chain reads the same way.

```ts
interface LoadConfigOptions {
    loaders?: Readonly<Record<string, Loader>>;
}
```

### Loaded

```ts
interface Loaded extends Layer {
    /** The files merged, outermost first — what `--explain` shows. */
    chain: string[];
}
```