typenvx/dist/src/index.d.ts

Typenv is a modern, type-safe alternative to .env files, providing advanced validation, intelligent interpolation, and conditional logic for better environment management.

type EnvxType = "string" | "number" | "boolean" | "enum" | "email" | "url";
interface EnvxVarSchema {
    type: EnvxType;
    required?: boolean;
    default?: string | number | boolean;
    values?: Array<string>;
    deprecated?: boolean;
    description?: string;
}
type EnvxSchema = Record<string, EnvxVarSchema>;
type EnvxResult = Record<string, string | number | boolean>;
declare class EnvxError extends Error {
    constructor(message: string);
}

/**
 * Loads and validates a pre-generated `.env` file using a corresponding schema from `.envx.meta.json`,
 * and returns a fully typed, type-safe environment object.
 *
 * This function is designed for **runtime environments** where you don’t want to ship `.envx` files
 * to production, but instead use the compiled `.env` + generated schema (`.envx.meta.json`).
 *
 * > Note: This function **does NOT** mutate `process.env`. If you need to inject variables into
 * > `process.env`, consider using `loadEnvx()` instead.
 *
 * ---
 *
 * ## How it works:
 *
 * - Reads the `.env` file (default: `.env` or `config.outputs.env`)
 * - Reads the compiled schema file (default: `.envx.meta.json` or `config.outputs.metaFilePath`)
 * - Validates the values based on types (string, number, boolean, enum, etc.)
 * - Returns a typed object matching the expected shape.
 *
 * ---
 *
 * ## Type Generation (Optional)
 * To benefit from static typing, run the following to generate your types:
 *
 * ```bash
 * npx typenv types --out types/envx.d.ts
 * ```
 *
 * Then use it like:
 *
 * ```ts
 * import { getEnv } from "typenvx";
 * import type { EnvVars } from "../types/envx"; // <- your generated types
 *
 * const env = getEnv<EnvVars>();
 * console.log(env.API_URL); // Fully typed
 * ```
 *
 * ---
 *
 * @template T - The type of the expected environment object. Defaults to `EnvxResult`.
 * @param {string} [filePath=DEFAULT_ENV_FILE] - Path to the `.env` file. Defaults to the configured or standard path.
 * @returns {T} A fully validated and typed environment object.
 *
 * @throws {EnvxError} If the `.env` or `.envx.meta.json` file is missing or invalid.
 *
 * @example
 * ```ts
 * // Assuming `.env` and `.envx.meta.json` exist
 * const env = getEnv();
 * console.log(env.DATABASE_URL); // Typed access
 * ```
 */
declare function getEnv<T extends Record<string, any> = EnvxResult>(filePath?: string): T;
/**
 * Loads and parses a `.envx` file into a fully typed, validated environment object.
 *
 * Designed for **development**, **server-side rendering**, or any environment
 * where `.envx` files are available and can be parsed at runtime.
 *
 * ---
 *
 * ## What it does
 *
 * - Reads a `.envx` file (default: `.envx`)
 * - Optionally uses a provided schema, or reads schema inline from the file itself
 * - Validates and casts values based on type definitions
 * - Returns a fully typed result, **without modifying `process.env`**
 *
 * ---
 *
 * ## When to use
 *
 * This function is ideal when you:
 * - Want full `.envx` syntax support (e.g., multi-line values, inline schema)
 * - Don't want to pre-generate `.env` or `.envx.meta.json`
 * - Are working in **development** or **local SSR** environments
 *
 * ---
 *
 * ## Type-Safety
 *
 * If you want full IntelliSense and compile-time safety, you can generate types:
 *
 * ```bash
 * npx typenv types --out types/envx.d.ts
 * ```
 *
 * ```ts
 * import { getEnvx } from "typenvx";
 * import type { EnvVars } from "./types/envx";
 *
 * const env = getEnvx<EnvVars>();
 * console.log(env.API_URL); // fully typed
 * ```
 *
 * ---
 *
 * ## Future-proof Design
 *
 * `getEnvx()` serves as the **most powerful way** to handle `.envx` at runtime.
 * Until native `.envx` support is adopted in runtimes like Node.js or Deno,
 * this function provides full spec-compliant parsing with validation.
 *
 * ---
 *
 * @template T - The expected shape of the environment variables.
 * @param {string} [filePath=DEFAULT_ENVX_FILE] - Path to the `.envx` file.
 * @param {EnvxSchema} [schema] - Optional schema override (if not inline).
 * @returns {T} A fully validated, typed object of environment variables.
 *
 * @throws {EnvxError} If the file cannot be read, parsed, or validated.
 */
declare function getEnvx<T extends Record<string, any> = EnvxResult>(filePath?: string, schema?: EnvxSchema): 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 EnvxResult).
 * @param {string} [filePath=DEFAULT_ENVX_FILE] - Path to the `.envx` file.
 * @param {EnvxSchema} [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 "typenvx";
 * loadEnvx("path/to/.envx");
 * console.log(process.env.API_KEY);
 * ```
 */
declare function loadEnvx<T extends Record<string, any> = EnvxResult>(filePath?: string, schema?: EnvxSchema): T;

export { EnvxError, type EnvxResult, type EnvxSchema, type EnvxType, type EnvxVarSchema, getEnv, getEnvx, loadEnvx };