@envguard/node/dist/index.d.ts

EnvGuard Node.js runtime - Drop-in dotenv replacement with OS keychain

import { IKeychainProvider } from '@envguard/core';

/**
 * @module @envguard/node/types
 * @description Type definitions for EnvGuard Node.js runtime
 */

/**
 * Options for loading secrets
 */
interface LoadOptions {
    /**
     * Environment to load secrets for
     * @default Detected from NODE_ENV or 'development'
     */
    environment?: string;
    /**
     * Project root directory
     * @default process.cwd()
     */
    projectRoot?: string;
    /**
     * Package name override
     * @default Auto-detected from .envguard/config.json
     */
    packageName?: string;
    /**
     * Enable debug logging
     * @default false
     */
    debug?: boolean;
    /**
     * Override existing process.env values
     * @default false
     */
    override?: boolean;
    /**
     * Validate required secrets
     * @default true
     */
    validate?: boolean;
    /**
     * Path to template file
     * @default Auto-detected from config
     */
    templatePath?: string;
    /**
     * Target object to populate (instead of process.env)
     * @default process.env
     */
    processEnv?: Record<string, string | undefined>;
    /**
     * Custom keychain instance (for testing)
     */
    keychain?: IKeychainProvider;
}
/**
 * Result of loading secrets
 */
interface LoadResult {
    /**
     * Whether loading succeeded
     */
    success: boolean;
    /**
     * Secrets that were loaded
     */
    loaded: Record<string, string>;
    /**
     * Validation errors (if any)
     */
    errors: ValidationError[];
    /**
     * Number of secrets loaded
     */
    count: number;
}
/**
 * Validation error details
 */
interface ValidationError {
    /**
     * Key that failed validation
     */
    key: string;
    /**
     * Error message
     */
    message: string;
    /**
     * Whether the key is required
     */
    required: boolean;
}
/**
 * Options for populate() function
 */
interface PopulateOptions extends Omit<LoadOptions, 'processEnv'> {
}
/**
 * Options for reset() function
 */
interface ResetOptions {
    /**
     * Clear injected values from process.env
     * @default false
     */
    cleanEnv?: boolean;
}

/**
 * @module @envguard/node/loader
 * @description Main loader orchestration
 */

/**
 * Reset state and optionally clean process.env
 */
declare function reset(options?: {
    cleanEnv?: boolean;
}): void;

/**
 * @module @envguard/node/config
 * @description Environment detection utilities
 */
/**
 * Detect the current environment
 *
 * Priority order:
 * 1. ENVGUARD_ENV environment variable
 * 2. NODE_ENV environment variable
 * 3. Default to 'development'
 *
 * @returns Environment name (e.g., 'development', 'production', 'staging')
 *
 * @example
 * ```typescript
 * const env = detectEnvironment();
 * console.log(env); // 'development' or 'production'
 * ```
 */
declare function detectEnvironment(): string;

/**
 * @module @envguard/node
 * @description EnvGuard Node.js runtime - Secure secret management
 *
 * Drop-in replacement for dotenv that loads secrets from OS keychain.
 */

/**
 * Load secrets asynchronously
 *
 * @param options - Load options
 * @returns Promise of load result
 */
declare function load(options?: LoadOptions): Promise<LoadResult>;
/**
 * Get secrets without injecting (async)
 *
 * @param options - Populate options
 * @returns Promise of secrets
 */
declare function populate(options?: PopulateOptions): Promise<Record<string, string>>;

/**
 * Main config function (async version)
 * Loads secrets from keychain and injects into process.env
 *
 * @param options - Load options
 * @returns Promise of load result
 *
 * @example
 * ```typescript
 * import envguard from '@envguard/node';
 *
 * // Top-level await (ES modules)
 * const result = await envguard.config();
 *
 * // Or with IIFE
 * (async () => {
 *   const result = await envguard.config({
 *     environment: 'production',
 *     debug: true,
 *   });
 *   console.log(result);
 * })();
 * ```
 */
declare function config(options?: LoadOptions): Promise<LoadResult>;
/**
 * Parse function (for dotenv compatibility)
 * Note: EnvGuard doesn't parse .env files, but we provide this for compatibility
 */
declare function parse(_src: string | Buffer): Record<string, string>;
declare const _default: {
    config: typeof config;
    parse: typeof parse;
    load: typeof load;
    populate: typeof populate;
    reset: typeof reset;
    detectEnvironment: typeof detectEnvironment;
};

export { type LoadOptions, type LoadResult, type PopulateOptions, type ResetOptions, type ValidationError, config, _default as default, detectEnvironment, load, parse, populate, reset };