dotenvxjs/dist/src/index.d.mts

dotenvx is the official Node.js library for .envx files, offering advanced type validation, intelligent interpolation, and conditional logic. It makes environment management safer, more dynamic, and easier to maintain.

type EnvType = "string" | "number" | "boolean" | "enum" | "email" | "url";
interface EnvVarSchema {
    type: EnvType;
    required?: boolean;
    default?: string | number | boolean;
    values?: Array<string>;
    deprecated?: boolean;
    description?: string;
}
type EnvSchema = Record<string, EnvVarSchema>;
type EnvResult = Record<string, string | number | boolean>;

/**
 * Reads a pre-built `.env` file and its associated meta JSON schema,
 * then returns a type-safe object with all environment variables loaded and validated.
 *
 * **Important:**
 * - This function **does NOT** modify `process.env`.
 * - Intended for production or runtime environments where `.env` is pre-generated.
 *
 * @template T - The shape of the environment variables (defaults to EnvResult).
 * @param {string} [filePath=DEFAULT_ENV_FILE] - Path to the `.env` file.
 * @returns {T} Type-safe environment variables object.
 *
 * @throws {EnvxError} Throws if `.env` file does not exist.
 *
 * @example
 * ```ts
 * import { getEnv } from "dotenvx";
 * const env = getEnv<Envx>("path/to/.env");
 * console.log(env.API_URL);
 * ```
 */
declare function getEnv<T extends Record<string, any> = EnvResult>(filePath?: string): T;
/**
 * Reads a `.envx` file and returns a type-safe object representing the environment variables.
 *
 * **Important:**
 * - This function **does NOT** modify `process.env`.
 * - Validates environment variables against the provided schema and adds built-in variables automatically.
 *
 * @template T - The shape of the environment variables (defaults to EnvResult).
 * @param {string} [filePath=DEFAULT_ENVX_FILE] - Path to the `.envx` file.
 * @param {EnvSchema} [schema] - Optional schema for validation and type inference.
 * @returns {T} Typed environment variables object.
 *
 * @throws {EnvxError} Throws if `.envx` file does not exist.
 *
 * @example
 * ```ts
 * import { getEnvx } from "dotenvx";
 * const envx = getEnvx<Envx>("path/to/.envx", mySchema);
 * console.log(envx.DATABASE_URL);
 * ```
 */
declare function getEnvx<T extends Record<string, any> = EnvResult>(filePath?: string, schema?: EnvSchema): T;
/**
 * Loads environment variables from a `.envx` file, validates them against the schema,
 * and **injects them into `process.env`**, allowing global access within the Node.js process.
 *
 * Use this function when you want environment variables available globally in your app.
 *
 * @template T - The shape of the environment variables (defaults to EnvResult).
 * @param {string} [filePath=DEFAULT_ENVX_FILE] - Path to the `.envx` file.
 * @param {EnvSchema} [schema] - Optional schema for validation and type inference.
 * @returns {T} The loaded and injected environment variables as a typed object.
 *
 * @throws {EnvxError} Throws if `.envx` file does not exist.
 *
 * @example
 * ```ts
 * import { loadEnvx } from "dotenvx";
 * loadEnvx("path/to/.envx");
 * console.log(process.env.API_KEY);
 * ```
 */
declare function loadEnvx<T extends Record<string, any> = EnvResult>(filePath?: string, schema?: EnvSchema): T;

export { getEnv, getEnvx, loadEnvx };