/**
 * Copyright (c) 2026 AzerothJS.
 *
 * This source code is licensed under the MIT license found in the
 * LICENSE file in the root directory of this source tree.
 */
/**
 * Typed configuration, loud at boot.
 *
 * The anti-`app.set('trust proxy', ...)`: configuration is a TYPED OBJECT built once at
 * startup from declared variables, not a string-keyed bag consulted at runtime. Three rules:
 *
 *   - EVERY failure at once. A missing DATABASE_URL and a malformed PORT report together in
 *     one thrown error at boot - not one per restart, which is how a bad deploy burns twenty
 *     minutes discovering variables one at a time.
 *   - TYPES from declarations. `num('PORT')` yields a number, `flag('DEBUG')` a boolean,
 *     `oneOf('MODE', [...])` a union - the config object's type is inferred from its shape,
 *     no interface written twice.
 *   - SECRETS marked at declaration. A `{ secret: true }` variable redacts itself from the
 *     config's own string/JSON representations, so `console.log(config)` in a debugging
 *     panic cannot leak credentials into logs.
 *
 * Reads default to `process.env` when it exists but take any record, so tests inject
 * environments without touching globals and non-Node runtimes pass their own.
 */
/** One declared configuration variable: how to read and parse it. */
export interface ConfigVar<T> {
    /** The environment variable name, e.g. 'DATABASE_URL'. */
    name: string;
    /** Parses the raw string; throws (or returns an Error message via throw) on bad input. */
    parse: (raw: string) => T;
    /** Used when the variable is absent. Absent + no default = a boot error. */
    defaultValue?: T | undefined;
    /** Redact from the config object's own serializations. */
    secret?: boolean | undefined;
}
/** A string variable. */
export declare function str(name: string, options?: {
    default?: string;
    secret?: boolean;
}): ConfigVar<string>;
/** A number variable; rejects anything Number() cannot fully parse. */
export declare function num(name: string, options?: {
    default?: number;
    secret?: boolean;
}): ConfigVar<number>;
/** A boolean flag: true/false/1/0/yes/no (case-insensitive) - anything else is a boot error. */
export declare function flag(name: string, options?: {
    default?: boolean;
    secret?: boolean;
}): ConfigVar<boolean>;
/** An enumerated variable: the value must be one of `values`, and the TYPE is their union. */
export declare function oneOf<const V extends readonly string[]>(name: string, values: V, options?: {
    default?: V[number];
    secret?: boolean;
}): ConfigVar<V[number]>;
/** The inferred config type of a shape of ConfigVars. */
export type ConfigOf<Shape extends Record<string, ConfigVar<unknown>>> = {
    readonly [K in keyof Shape]: Shape[K] extends ConfigVar<infer T> ? T : never;
};
/**
 * Builds the typed config from a shape, reading `env` (default: the process environment).
 * Throws ONE error naming every missing and every malformed variable. Secret values are
 * present on the object but redacted from its own JSON/string forms.
 */
export declare function loadConfig<Shape extends Record<string, ConfigVar<unknown>>>(shape: Shape, env?: Record<string, string | undefined>): ConfigOf<Shape>;