@skyra/env-utilities/dist/cjs/index.d.cts

Functional utilities for reading and parsing environmental variables

import { DotenvConfigOptions, DotenvConfigOutput } from 'dotenv';

interface EnvLoaderOptions extends Omit<DotenvConfigOptions, 'path'> {
    /**
     * You may specify a custom environment if `NODE_ENV` isn't sufficient.
     */
    env?: string;
    /**
     * You may specify a required prefix for your dotenv variables (ex. `APP_`).
     */
    prefix?: string;
    /**
     * Specify a custom path if your file containing environment variables is located elsewhere.
     * Can also be an array of strings, specifying multiple paths.
     *
     * @default `path.resolve(process.cwd(), '.env')`
     *
     * @example with CJS
     * ```typescript
     * require('@skyra/env-utilities').setup({ path: '/custom/path/to/.env' })
     * ```
     * @example with ESM
     * ```typescript
     * import { setup } from '@skyra/env-utilities';
     *
     * const envFile = new URL('../.env', import.meta.url);
     * setup({ path: envFile })
     * ```
     */
    path?: string | URL;
}

declare function setup(pathOrOptions?: string | URL | EnvSetupOptions): DotenvConfigOutput;
interface EnvSetupOptions extends Omit<EnvLoaderOptions, 'path'> {
    /**
     * You may specify a custom path if your file containing environment variables is located elsewhere.
     */
    path?: string | URL;
}
type EnvSetupResult = DotenvConfigOutput;

type BooleanString = 'true' | 'false';
type IntegerString = `${bigint}`;
type NumberString = `${number}`;
type ArrayString = string & {
    __type__: 'ArrayString';
};
type EnvAny = keyof Env;
type EnvString = {
    [K in EnvAny]: Env[K] extends BooleanString | IntegerString | NumberString ? never : K;
}[EnvAny];
type EnvBoolean = {
    [K in EnvAny]: Env[K] extends BooleanString | undefined ? K : never;
}[EnvAny];
type EnvInteger = {
    [K in EnvAny]: Env[K] extends IntegerString | undefined ? K : never;
}[EnvAny];
type EnvNumber = {
    [K in EnvAny]: Env[K] extends NumberString | undefined ? K : never;
}[EnvAny];
type EnvArray = {
    [K in EnvAny]: Env[K] extends ArrayString | undefined ? K : never;
}[EnvAny];
interface Env {
    NODE_ENV: 'test' | 'development' | 'production';
    DOTENV_DEBUG?: BooleanString;
    DOTENV_ENCODING?: string;
    DOTENV_ENV?: string;
    DOTENV_PATH?: string;
    DOTENV_PREFIX?: string;
}

declare function envParseInteger(key: EnvInteger, defaultValue?: number): number;
declare function envParseInteger(key: EnvInteger, defaultValue: number | null): number | null;
declare function envParseNumber(key: EnvNumber, defaultValue?: number): number;
declare function envParseNumber(key: EnvNumber, defaultValue: number | null): number | null;
declare function envParseBoolean(key: EnvBoolean, defaultValue?: boolean): boolean;
declare function envParseBoolean(key: EnvBoolean, defaultValue: boolean | null): boolean | null;
declare function envParseString<K extends EnvString>(key: K, defaultValue?: Env[K]): NonNullable<Env[K]>;
declare function envParseString<K extends EnvString>(key: K, defaultValue: Env[K] | null): NonNullable<Env[K]> | null;
declare function envParseArray(key: EnvArray, defaultValue?: string[]): string[];
declare function envParseArray(key: EnvArray, defaultValue: string[] | null): string[] | null;
/**
 * Checks if the value of the specified environment variable is null.
 * @param key - The name of the environment variable.
 * @returns Whether the value of the specified environment variable is:
 * - The string `"0"`
 * - The string `"null"`, case insensitive
 */
declare function envIsNull(key: EnvAny): boolean;
/**
 * Checks if the value of the specified environment variable is undefined.
 * @param key - The name of the environment variable.
 * @returns Whether the value of the specified environment variable is:
 * - `undefined`
 * - An empty string (`""`)
 */
declare function envIsUndefined(key: EnvAny): boolean;
/**
 * Checks if the value of the specified environment variable is nullish.
 * @param key - The name of the environment variable.
 * @returns Whether the value of the specified environment variable is:
 * - `undefined`
 * - An empty string (`""`)
 * - The string `"0"`
 * - The string `"null"`, case insensitive
 */
declare function envIsNullish(key: EnvAny): boolean;
/**
 * Checks if any of the specified environment variables is defined.
 * @param key - The name of the environment variable.
 * @returns Whether the value of any of the specified environment variables is a non-empty string
 */
declare function envIsDefined(...keys: readonly EnvAny[]): boolean;

declare global {
    namespace NodeJS {
        interface ProcessEnv extends Env {
        }
    }
}

export { type ArrayString, type BooleanString, type Env, type EnvAny, type EnvArray, type EnvBoolean, type EnvInteger, type EnvNumber, type EnvSetupOptions, type EnvSetupResult, type EnvString, type IntegerString, type NumberString, envIsDefined, envIsNull, envIsNullish, envIsUndefined, envParseArray, envParseBoolean, envParseInteger, envParseNumber, envParseString, setup };