dotenv-extended/dotenv-extended.d.ts

A module for loading .env files and optionally loading defaults and a schema for validating all values are present.

/// <reference types="dotenv" />

/**
 * The result of a call to load() or parse()
 */
export interface IEnvironmentMap {
    [name: string]: string;
}

/**
 * DotenvExtended options for load().
 */
export interface IDotenvExtendedOptions {
    /**
     * Sets the encoding of the .env files.
     *
     * @default 'utf-8'
     */
    encoding?: string;

    /**
     * Sets whether a log message is shown when missing the .env or .env.defaults files.
     *
     * @default true
     */
    silent?: boolean;

    /**
     * Path to the main .env file that contains your variables.
     * Can be a string path or layered string[] where later entries override earlier ones.
     *
     * @default '.env'
     */
    path?: string | string[];

    /**
     * The path to the file that default values are loaded from.
     * Can be a string path or layered string[] where later entries override earlier ones.
     *
     * @default '.env.defaults'
     */
    defaults?: string | string[];

    /**
     * The path to the file that contains the schema of what values should be available
     * from combining .env and .env.defaults.
     *
     * @default '.env.schema'
     */
    schema?: string;

    /**
     * Optional schema extension path(s). These are layered on top of `schema` in order.
     * Later entries override earlier keys (including base schema keys).
     */
    schemaExtends?: string | string[];

    /**
     * Causes the library to throw a MISSING CONFIG VALUES error listing all of the variables
     * missing the combined .env and .env.defaults files.
     *
     * @default false
     */
    errorOnMissing?: boolean;

    /**
     * Causes the library to throw a EXTRA CONFIG VALUES error listing all of the extra variables
     * from the combined .env and .env.defaults files.
     *
     * @default false
     */
    errorOnExtra?: boolean;

    /**
     * Causes the library to throw a REGEX MISMATCH error listing all of the invalid variables from the combined .env
     * and .env.defaults files. Also a SyntaxError is thrown in case .env.schema contains a syntactically invalid regex.
     *
     * @default false
     */
    errorOnRegex?: boolean;

    /**
     * Causes the library to throw when a configured dotenv file path cannot be found.
     * Applies to `path`, `defaults`, and `schema` when they are loaded.
     *
     * @default false
     */
    errorOnMissingFiles?: boolean;

    /**
     * Causes the library add process.env variables to error checking. The variables in process.env overrides the
     * variables in .env and .env.defaults while checking
     *
     * @default false
     */
    includeProcessEnv?: boolean;

    /**
     * Causes the returned object (and any process assignment) to include only variables present in the schema file.
     * This is useful when `includeProcessEnv` is enabled for validation, but you only want schema-defined keys.
     *
     * @default false
     */
    returnSchemaOnly?: boolean;

    /**
     * Sets whether the loaded values are assigned to the process.env object.
     * If this is false, values are only available from the returned object.
     *
     * @default true
     */
    assignToProcessEnv?: boolean;

    /**
     * By defaut, dotenv-entended will not overwrite any varibles that are already set in the process.env object.
     * If you would like to enable overwriting any already existing values, set this value to true.
     *
     * @default false
     */
    overrideProcessEnv?: boolean;
}

export { parse } from 'dotenv';

/**
 * Loads the dotenv files, .env, .env.defaults and .env.schema.
 *
 * @param options
 */
export function load(options?: IDotenvExtendedOptions): IEnvironmentMap;