@st4rbugs/ensure-env/dist/index.d.mts

Type-Safe Env Validator and Parser

type Parser<P> = (value: string) => P;
/** Configuration for an environment variable */
interface EnsureEnvConfig<T extends boolean = true, P = string> {
    /** The name of the environment variable. Make sure to load environment variables before using this function */
    name: string;
    /**
     * Whether the environment variable is required
     * @throws Error if the environment variable is required but not set
     * @default true
     **/
    required?: T;
    /**
     * A parser function to transform the value of the environment variable
     * @see EnvParsers for some common parsers
     **/
    parser?: Parser<P>;
    /** A fallback value to use when the environment variable is not set */
    fallback?: P;
}
/**
 * Ensure that an environment variable is set and optionally parse it
 * @param props - The configuration for the environment variable
 * @returns The value of the environment variable, or the fallback value if it is not set
 */
declare function ensureEnv<T extends boolean = true, P = string>(props: EnsureEnvConfig<T, P> & {
    fallback: P;
}): P extends boolean ? boolean : P;
declare function ensureEnv<T extends boolean = true, P = string>(props: EnsureEnvConfig<T, P> | string): P extends boolean ? boolean : T extends false ? P | undefined : P;

type ArgType<T> = [string | Parser<T>] | [{
    delimiter: string;
    parser: Parser<T>;
}] | [string, Parser<T>] | [];
declare abstract class AbstractDefaultParsers {
    /**
     * Parses a string into a boolean.
     * Returns `true` if the input is '1', 'true', or 'yes' (case-insensitive).
     */
    static booleanParser: Parser<boolean>;
    /**
     * Parses a string into an integer.
     * Uses radix 10 to avoid unexpected results.
     */
    static intParser: Parser<number>;
    /** Parses a string into a floating-point number. */
    static floatParser: Parser<number>;
    /** Returns the input string as-is. */
    static stringParser: Parser<string>;
    /**
     * Parses a JSON string into an object.
     * Note: This can throw a SyntaxError if the input is not valid JSON.
     */
    static jsonParser: Parser<Record<string, unknown>>;
    /**
     * Parses a string into an array of type T using the provided parser and optional delimiter.
     * If no delimiter is provided, a comma is used as the default delimiter.
     * @param args - The delimiter and parser to convert each array element.
     */
    static arrayParser: <T = string>(...args: ArgType<T>) => Parser<T[]>;
}
declare class DefaultParsers extends AbstractDefaultParsers {
    private static booleanValues;
    private static delimiter;
    static stringParser: Parser<string>;
    static booleanParser: Parser<boolean>;
    static intParser: Parser<number>;
    static floatParser: Parser<number>;
    static jsonParser: Parser<Record<string, unknown>>;
    static arrayParser<T = string>(...args: ArgType<T>): Parser<T[]>;
    /**
     * Parses the arguments provided to arrayParser and returns the delimiter and parser.
     * @param args - The arguments passed to arrayParser.
     * @returns A tuple containing the delimiter and parser.
     * @throws Error if the arguments are invalid.
     */
    private static parseArgs;
}

export { type EnsureEnvConfig, DefaultParsers as EnvParsers, type Parser, ensureEnv as default };