Config API for Bun and Node

interface Setting<V, Live extends boolean = false, Given extends boolean = true, IsSecret extends boolean = false> {
    readonly [mark]: Described
    /** what the program reads it as; nothing at run time */
    readonly '~value'?: V
    readonly '~live'?: Live
    readonly '~given'?: Given
    readonly '~secret'?: IsSecret
}

class Secret {}

reveal(): string

toString(): string

toJSON(): string

type Value<D> = D extends Setting<infer V, boolean, boolean, boolean> ? V : D extends string ? string : D extends number ? number : D extends boolean ? boolean : D extends null ? null : D extends readonly (infer I)[] ? readonly Value<I>[] : D extends object ? {
    readonly [K in keyof D]: Value<D[K]>
} : never

type Changes<D> = {
    readonly [K in keyof D as LiveIn<D[K]> extends true ? K : never]?: D[K] extends Setting<infer V, true, boolean, boolean> ? V : Changes<D[K]>
}

type Overlay<D> = {
    readonly [K in keyof D]?: D[K] extends Setting<infer V, boolean, boolean, boolean> ? V extends Secret ? string : V : D[K] extends readonly unknown[] ? Value<D[K]> : D[K] extends object ? Overlay<D[K]> : Value<D[K]>
}

interface FileLayer {
    readonly [layerMark]: 'file'
    readonly path: string
    readonly optional: boolean
}

interface EnvLayer {
    readonly [layerMark]: 'env'
    readonly prefix: string
    /** a setting's own variable, by its path */
    readonly vars: Readonly<Record<string, string>>
    readonly files: readonly string[]
    readonly from: Readonly<Record<string, string | undefined>> | undefined
}

type Layer<D> = FileLayer | EnvLayer | Overlay<D> | false | null | undefined

interface Vars {
    readonly [key: string]: string | Vars
}

interface EnvOptions {
    /** a setting's variable of its own, in place of its prefixed one */
    vars?: Vars | undefined
    /** .env files, whose variables count where the process has none; Bun reads .env itself */
    files?: readonly string[] | undefined
    /** these variables in place of the process's, the only environment read, as a test gives them */
    from?: Readonly<Record<string, string | undefined>> | undefined
}

interface ConfigOptions<V> {
    /**
     * the program's own check of the whole value, at open and before a change
     * is kept: a Standard Schema such as zod's or valibot's, or a function
     * that throws
     */
    validate?: StandardSchemaV1 | ((value: V) => unknown) | undefined
    /** refuses to open while a kept change no longer fits, rather than ignoring it and saying so */
    strict?: boolean | undefined
}

interface UpdateOptions {
    /** keeps the change only while the config is at this version, else ConflictError */
    ifVersion?: number | undefined
}

interface ExplainLine {
    readonly path: string
    /** as JSON, a duration spelled, a secret as *** */
    readonly value: string
    /** the layer that gave it: APP_PORT, app.yaml, layer 2, the declaration, a change */
    readonly from: string
    /** the values it went over, newest first */
    readonly over: string
}

type Explained = readonly ExplainLine[] & {
    readonly notes: readonly string[]
}

interface Bounds {
    min?: number | undefined
    max?: number | undefined
}

interface DurationBounds {
    min?: DurationText | undefined
    max?: DurationText | undefined
}

function secret(given: StringConstructor | string): Setting<Secret, false, true, true>

function required<T extends Token>(type: T): Setting<Of<T>>
function required<V>(rule: Setting<V, false, false>): Setting<V>

function live<V>(rule: Setting<V, false, true>): Setting<V, true>
function live<const V extends Primitive | readonly Primitive[]>(value: V): Setting<Widened<V>, true>

function int(rules?: Bounds): Setting<number, false, false>
function int(fallback: number, rules?: Bounds): Setting<number>

function oneOf<const O extends readonly [string, ...string[]]>(values: O): Setting<O[number], false, false>
function oneOf<const T extends string, const O extends readonly string[]>(fallback: T, others: O): Setting<T | O[number]>

function duration(rules?: DurationBounds): Setting<DurationText, false, false>
function duration(fallback: DurationText, rules?: DurationBounds): Setting<DurationText>

function list<T extends Token>(item: T, options?: ListOptions<Of<T>>): Setting<readonly Of<T>[]>
function list<V>(item: Setting<V, false, boolean>, options?: ListOptions<V>): Setting<readonly V[]>
function list<G extends object>(item: G, options?: ListOptions<Value<G>>): Setting<readonly Value<G>[]>

function file(path: string, options?: FileOptions): FileLayer

function env(prefix: string, options?: EnvOptions): EnvLayer

class Config<D> {
    readonly name: string
}

static open<D>(link: Link, name: string, layers: readonly unknown[], options: ConfigOptions<Value<D>>): Promise<Config<D>>

get value(): Value<D>

get version(): number

update(changes: Changes<D>, options?: UpdateOptions): Promise<void>

reset(path?: string): Promise<void>

watch(watcher: (next: Value<D>, previous: Value<D> | undefined) => void): () => void

explain(): Explained

stop(): Promise<void>