@spfn/core 0.1.0-alpha.88 → 0.2.0-beta.1

package/dist/env/index.d.ts

@@ -1,508 +1,779 @@
+export { L as LogLevel } from '../types-BGl4QL1w.js';
+
 /**
- * Environment Variable Management - Configuration Types
+ * Environment Variable Management - Parsers
  *
- * Type definitions for centralized environment variable loading
+ * Parser functions that transform and validate environment variable strings.
+ * All parsers follow the pattern: (value: string) => T or throw Error
  */
 /**
- * Options for loading environment variables
+ * Parser function that transforms and validates a string value
+ * @throws Error if validation fails
  */
-interface LoadEnvironmentOptions {
-    /**
-     * Base directory for .env files
-     * @default process.cwd()
-     */
-    basePath?: string;
-    /**
-     * Additional custom paths to load
-     * Loaded after standard files
-     * @default []
-     */
-    customPaths?: string[];
-    /**
-     * Enable debug logging
-     * @default false
-     */
-    debug?: boolean;
-    /**
-     * Override NODE_ENV for file selection
-     * @default process.env.NODE_ENV
-     */
-    nodeEnv?: string;
-    /**
-     * Required environment variables
-     * Throws error if any are missing after loading
-     * @default []
-     */
-    required?: string[];
-    /**
-     * Skip loading if environment already loaded
-     * Set to false to force reload (useful for testing)
-     * @default true
-     */
-    useCache?: boolean;
-}
+type Parser<T> = (value: string) => T;
 /**
- * Result of environment loading operation
+ * Parse a non-empty string
+ *
+ * @param value - Value to parse
+ * @returns Trimmed string
+ * @throws Error if string is empty after trimming
+ *
+ * @example
+ * ```typescript
+ * const name = getEnvVar('APP_NAME', {
+ *   validator: parseString,
+ * });
+ * ```
  */
-interface LoadResult {
-    /**
-     * Whether loading was successful overall
-     */
-    success: boolean;
-    /**
-     * Files that were successfully loaded
-     */
-    loaded: string[];
-    /**
-     * Files that failed to load (with reasons)
-     */
-    failed: Array<{
-        path: string;
-        reason: string;
-    }>;
-    /**
-     * Environment variables that were parsed from files
-     */
-    parsed: Record<string, string>;
-    /**
-     * Error messages if any critical errors occurred
-     */
-    errors?: string[];
-    /**
-     * Warning messages for non-critical issues
-     */
-    warnings: string[];
-}
+declare function parseString(value: string): string;
 /**
- * Options for getting environment variables
+ * Create a string parser with validation rules
+ *
+ * @param options - Validation options
+ * @returns Parser function
+ *
+ * @example
+ * ```typescript
+ * const apiKey = getEnvVar('API_KEY', {
+ *   validator: createStringParser({
+ *     minLength: 32,
+ *     pattern: /^[A-Za-z0-9_-]+$/,
+ *   }),
+ * });
+ * ```
  */
-interface GetEnvOptions {
-    /**
-     * Throw error if variable not found
-     * @default false
-     */
-    required?: boolean;
-    /**
-     * Default value if variable not found
-     * Only used if required is false
-     */
-    default?: string;
-    /**
-     * Custom validation function
-     * Return true if valid, false if invalid
-     */
-    validator?: (value: string) => boolean;
-    /**
-     * Custom error message for validation failure
-     */
-    validationError?: string;
-}
+declare function createStringParser(options?: {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: RegExp;
+    trim?: boolean;
+}): Parser<string>;
 /**
- * Standard environment file names in priority order
+ * Parse a boolean environment variable
  *
- * Next.js-style loading behavior:
- * - development: .env → .env.development → .env.local → .env.development.local
- * - production:  .env → .env.production → .env.local → .env.production.local
- * - test:        .env → .env.test → (skip .env.local) → .env.test.local
+ * Accepts: 'true', '1', 'yes' (case-insensitive) → true
+ *          'false', '0', 'no' (case-insensitive) → false
  *
- * Note: .env.local is excluded in test environment for proper test isolation
+ * @param value - Value to parse
+ * @returns Boolean value
+ * @throws Error if value is not a valid boolean string
+ *
+ * @example
+ * ```typescript
+ * const debug = getEnvVar('DEBUG', {
+ *   default: 'false',
+ *   validator: parseBoolean,
+ * });
+ * ```
  */
-declare const ENV_FILE_PRIORITY: readonly [".env", ".env.{NODE_ENV}", ".env.local", ".env.{NODE_ENV}.local"];
+declare function parseBoolean(value: string): boolean;
 /**
- * Environment files that should only be loaded in test environment
+ * Parse and validate number
+ *
+ * @param value - Value to parse
+ * @param options - Validation options
+ * @returns Parsed number
+ * @throws Error if invalid number or constraint violation
+ *
+ * @example
+ * ```typescript
+ * const port = getEnvVar('PORT', {
+ *   default: '3000',
+ *   validator: (val) => parseNumber(val, { min: 1, max: 65535, integer: true }),
+ * });
+ * ```
  */
-declare const TEST_ONLY_FILES: readonly [".env.test", ".env.test.local"];
-
+declare function parseNumber(value: string, options?: {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}): number;
 /**
- * Environment Variable Management - Core Loader
+ * Create a number parser with specific constraints
+ *
+ * @param options - Validation constraints
+ * @returns Parser function
  *
- * Centralized singleton environment variable loader with dotenv priority support
+ * @example
+ * ```typescript
+ * const port = getEnvVar('PORT', {
+ *   default: '3000',
+ *   validator: createNumberParser({ min: 1, max: 65535, integer: true }),
+ * });
+ * ```
  */
-
+declare function createNumberParser(options?: {
+    min?: number;
+    max?: number;
+    integer?: boolean;
+}): Parser<number>;
 /**
- * Load environment variables from .env files with Next.js-style priority
+ * Parse integer with optional constraints
  *
- * Loading behavior by environment:
- * - (no NODE_ENV): .env → .env.local
- * - development: .env → .env.development → .env.local → .env.development.local
- * - production:  .env → .env.production → .env.local → .env.production.local
- * - test:        .env → .env.test → (skip .env.local) → .env.test.local
- * - local:       .env → .env.local → .env.local.local (duplicate .env.local prevented)
- * - staging/qa/etc: .env → .env.{NODE_ENV} → .env.local → .env.{NODE_ENV}.local
+ * @param value - Value to parse
+ * @param options - Min/max constraints
+ * @returns Parsed integer
+ * @throws Error if invalid or out of range
  *
- * Notes:
- * - .env.local is excluded in test environment for proper test isolation
- * - Any custom NODE_ENV value is supported (staging, qa, uat, preview, etc.)
- * - If NODE_ENV is not set, .env and .env.local are loaded
+ * @example
+ * ```typescript
+ * const retries = getEnvVar('MAX_RETRIES', {
+ *   default: '3',
+ *   validator: (val) => parseInteger(val, { min: 1, max: 10 }),
+ * });
+ * ```
+ */
+declare function parseInteger(value: string, options?: {
+    min?: number;
+    max?: number;
+}): number;
+/**
+ * Parse float/decimal number with optional constraints
  *
- * @param options - Loading options
- * @returns Load result with success status and loaded variables
+ * @param value - Value to parse
+ * @param options - Min/max constraints
+ * @returns Parsed decimal number
+ * @throws Error if invalid or out of range
  *
  * @example
  * ```typescript
- * // Simple usage (no NODE_ENV set)
- * const result = loadEnvironment();
- *
- * // With NODE_ENV=local
- * process.env.NODE_ENV = 'local';
- * const result = loadEnvironment({
- *   debug: true,
- *   required: ['DATABASE_URL'],
+ * const ratio = getEnvVar('CACHE_RATIO', {
+ *   default: '0.75',
+ *   validator: (val) => parseDecimal(val, { min: 0, max: 1 }),
  * });
- *
- * // With custom environment
- * process.env.NODE_ENV = 'staging';
- * const result = loadEnvironment();
  * ```
  */
-declare function loadEnvironment(options?: LoadEnvironmentOptions): LoadResult;
+declare function parseDecimal(value: string, options?: {
+    min?: number;
+    max?: number;
+}): number;
 /**
- * Get an environment variable with optional validation
+ * Parse and validate URL
  *
- * @param key - Environment variable name
- * @param options - Get options (default, required, validator)
- * @returns Variable value or undefined
- * @throws Error if required and not found, or validation fails
+ * @param value - Value to parse
+ * @param options - Validation options
+ * @returns Validated URL string
+ * @throws Error if invalid URL or protocol mismatch
  *
  * @example
  * ```typescript
- * // Simple get
- * const dbUrl = getEnvVar('DATABASE_URL');
- *
- * // With default
- * const port = getEnvVar('PORT', { default: '3000' });
+ * const apiUrl = getEnvVar('API_URL', {
+ *   validator: (val) => parseUrl(val, { protocol: 'https' }),
+ * });
+ * ```
+ */
+declare function parseUrl(value: string, options?: {
+    protocol?: 'http' | 'https' | 'any';
+}): string;
+/**
+ * Create a URL parser with specific protocol requirement
  *
- * // Required
- * const apiKey = getEnvVar('API_KEY', { required: true });
+ * @param protocol - Required protocol ('http', 'https', or 'any')
+ * @returns Parser function
  *
- * // With validation
- * const url = getEnvVar('API_URL', {
- *   validator: (val) => val.startsWith('https://'),
- *   validationError: 'API_URL must use HTTPS',
+ * @example
+ * ```typescript
+ * const apiUrl = getEnvVar('API_URL', {
+ *   validator: createUrlParser('https'),
  * });
  * ```
  */
-declare function getEnvVar(key: string, options?: GetEnvOptions): string | undefined;
+declare function createUrlParser(protocol?: 'http' | 'https' | 'any'): Parser<string>;
 /**
- * Get a required environment variable
+ * Parse PostgreSQL connection string
  *
- * @param key - Environment variable name
- * @returns Variable value
- * @throws Error if not found
+ * @param value - Value to parse
+ * @returns Validated PostgreSQL URL string
+ * @throws Error if invalid PostgreSQL URL
  *
  * @example
  * ```typescript
- * const dbUrl = requireEnvVar('DATABASE_URL');
+ * const dbUrl = getEnvVar('DATABASE_URL', {
+ *   required: true,
+ *   validator: parsePostgresUrl,
+ * });
  * ```
  */
-declare function requireEnvVar(key: string): string;
+declare function parsePostgresUrl(value: string): string;
 /**
- * Check if an environment variable exists
+ * Parse Redis connection string
  *
- * @param key - Environment variable name
- * @returns True if variable exists and is non-empty
+ * @param value - Value to parse
+ * @returns Validated Redis URL string
+ * @throws Error if invalid Redis URL
  *
  * @example
  * ```typescript
- * if (hasEnvVar('REDIS_URL')) {
- *   // Use Redis
- * }
+ * const redisUrl = getEnvVar('REDIS_URL', {
+ *   required: true,
+ *   validator: parseRedisUrl,
+ * });
  * ```
  */
-declare function hasEnvVar(key: string): boolean;
+declare function parseRedisUrl(value: string): string;
 /**
- * Get multiple environment variables at once
+ * Parse and validate enum value
  *
- * @param keys - Array of environment variable names
- * @returns Object mapping keys to values (undefined if not found)
+ * @param value - Value to parse
+ * @param allowed - Array of allowed values
+ * @param caseInsensitive - Whether to perform case-insensitive comparison
+ * @returns Validated enum value
+ * @throws Error if value not in allowed list
  *
  * @example
  * ```typescript
- * const { DATABASE_URL, REDIS_URL } = getEnvVars([
- *   'DATABASE_URL',
- *   'REDIS_URL',
- * ]);
+ * const env = getEnvVar('NODE_ENV', {
+ *   validator: (val) => parseEnum(val, ['development', 'production', 'test']),
+ * });
  * ```
  */
-declare function getEnvVars(keys: string[]): Record<string, string | undefined>;
+declare function parseEnum(value: string, allowed: string[], caseInsensitive?: boolean): string;
 /**
- * Check if environment has been loaded
+ * Create an enum parser with specific allowed values
  *
- * @returns True if loadEnvironment has been called successfully
+ * @param allowed - Array of allowed values
+ * @param caseInsensitive - Whether to perform case-insensitive comparison
+ * @returns Parser function
  *
  * @example
  * ```typescript
- * if (!isEnvironmentLoaded()) {
- *   loadEnvironment();
- * }
+ * const logLevel = getEnvVar('LOG_LEVEL', {
+ *   default: 'info',
+ *   validator: createEnumParser(['debug', 'info', 'warn', 'error']),
+ * });
  * ```
  */
-declare function isEnvironmentLoaded(): boolean;
+declare function createEnumParser(allowed: string[], caseInsensitive?: boolean): Parser<string>;
 /**
- * Reset environment loading state
- * FOR TESTING ONLY - DO NOT USE IN PRODUCTION
+ * Parse JSON string
+ *
+ * @param value - JSON string to parse
+ * @returns Parsed JSON value
+ * @throws Error if invalid JSON
  *
  * @example
  * ```typescript
- * // In test cleanup
- * afterEach(() => {
- *   resetEnvironment();
+ * const config = getEnvVar('CONFIG_JSON', {
+ *   validator: parseJson,
  * });
  * ```
  */
-declare function resetEnvironment(): void;
-
+declare function parseJson<T = any>(value: string): T;
 /**
- * Environment Variable Management - Validators
+ * Create a typed JSON parser
+ *
+ * @returns Parser function
+ *
+ * @example
+ * ```typescript
+ * interface Config {
+ *   host: string;
+ *   port: number;
+ * }
  *
- * Common validation functions for environment variables
+ * const config = getEnvVar('CONFIG_JSON', {
+ *   validator: createJsonParser<Config>(),
+ * });
+ * ```
  */
+declare function createJsonParser<T>(): Parser<T>;
 /**
- * Validate that a value is a valid URL
+ * Parse comma-separated values into array
  *
- * @param value - Value to validate
- * @param options - Validation options
- * @returns True if valid URL, false otherwise
+ * @param value - Comma-separated string
+ * @param options - Parser options
+ * @returns Array of strings
  *
  * @example
  * ```typescript
- * const apiUrl = getEnvVar('API_URL', {
- *   validator: validateUrl,
+ * const hosts = getEnvVar('ALLOWED_HOSTS', {
+ *   validator: parseArray,
  * });
+ * // "localhost,example.com,api.example.com" → ['localhost', 'example.com', 'api.example.com']
  * ```
  */
-declare function validateUrl(value: string, options?: {
-    protocol?: 'http' | 'https' | 'any';
-}): boolean;
+declare function parseArray(value: string, options?: {
+    separator?: string;
+    trim?: boolean;
+    filter?: (item: string) => boolean;
+}): string[];
 /**
- * Create a URL validator with specific protocol requirement
+ * Create an array parser with item parser
  *
- * @param protocol - Required protocol ('http', 'https', or 'any')
- * @returns Validator function
+ * @param itemParser - Parser to apply to each array item
+ * @param options - Array parsing options
+ * @returns Parser function
  *
  * @example
  * ```typescript
- * const apiUrl = getEnvVar('API_URL', {
- *   validator: createUrlValidator('https'),
- *   validationError: 'API_URL must use HTTPS',
+ * // Parse comma-separated ports
+ * const ports = getEnvVar('PORTS', {
+ *   validator: createArrayParser(
+ *     createNumberParser({ min: 1, max: 65535, integer: true })
+ *   ),
  * });
+ * // "3000,4000,5000" → [3000, 4000, 5000]
  * ```
  */
-declare function createUrlValidator(protocol?: 'http' | 'https' | 'any'): (value: string) => boolean;
+declare function createArrayParser<T>(itemParser: Parser<T>, options?: {
+    separator?: string;
+}): Parser<T[]>;
 /**
- * Validate that a value is a valid number
+ * Create a secure secret parser with entropy validation
+ *
+ * Validates cryptographic secrets for sufficient length, character diversity, and randomness.
+ * Uses Shannon entropy to measure randomness quality.
  *
- * @param value - Value to validate
  * @param options - Validation options
- * @returns True if valid number, false otherwise
+ * @returns Parser function
  *
  * @example
  * ```typescript
- * const port = getEnvVar('PORT', {
- *   validator: (val) => validateNumber(val, { min: 1, max: 65535 }),
+ * const sessionSecret = getEnvVar('SESSION_SECRET', {
+ *   validator: createSecureSecretParser({
+ *     minLength: 32,        // Minimum 256-bit
+ *     minUniqueChars: 16,   // Character diversity
+ *     minEntropy: 3.5,      // Shannon entropy (bits/char)
+ *   }),
  * });
  * ```
  */
-declare function validateNumber(value: string, options?: {
-    min?: number;
-    max?: number;
-    integer?: boolean;
-}): boolean;
+declare function createSecureSecretParser(options?: {
+    minLength?: number;
+    minUniqueChars?: number;
+    minEntropy?: number;
+}): Parser<string>;
 /**
- * Create a number validator with specific constraints
+ * Create a password strength parser
  *
- * @param options - Validation constraints
- * @returns Validator function
+ * Validates password strength based on configurable requirements.
+ * Useful for enforcing password policies in environment variables or user input.
+ *
+ * @param options - Validation options
+ * @returns Parser function
  *
  * @example
  * ```typescript
- * const port = getEnvVar('PORT', {
- *   validator: createNumberValidator({ min: 1, max: 65535, integer: true }),
- *   validationError: 'PORT must be an integer between 1 and 65535',
+ * const adminPassword = getEnvVar('ADMIN_PASSWORD', {
+ *   validator: createPasswordParser({
+ *     minLength: 12,
+ *     requireUppercase: true,
+ *     requireLowercase: true,
+ *     requireNumber: true,
+ *     requireSpecial: true,
+ *   }),
  * });
  * ```
  */
-declare function createNumberValidator(options?: {
-    min?: number;
-    max?: number;
-    integer?: boolean;
-}): (value: string) => boolean;
+declare function createPasswordParser(options?: {
+    minLength?: number;
+    requireUppercase?: boolean;
+    requireLowercase?: boolean;
+    requireNumber?: boolean;
+    requireSpecial?: boolean;
+}): Parser<string>;
 /**
- * Validate that a value is a valid boolean string
+ * Chain multiple parsers sequentially
+ *
+ * Each parser receives the output of the previous parser.
+ * Useful for multi-step validation/transformation.
  *
- * @param value - Value to validate
- * @returns True if valid boolean string, false otherwise
+ * @param parsers - Array of parser functions
+ * @returns Combined parser function
  *
  * @example
  * ```typescript
- * const debugMode = getEnvVar('DEBUG', {
- *   validator: validateBoolean,
+ * const apiKey = getEnvVar('API_KEY', {
+ *   validator: chain(
+ *     parseString,
+ *     createStringParser({ minLength: 32, pattern: /^[A-Za-z0-9_-]+$/ }),
+ *   ),
  * });
  * ```
  */
-declare function validateBoolean(value: string): boolean;
+declare function chain<T>(...parsers: Array<Parser<T>>): Parser<T>;
 /**
- * Parse a boolean environment variable
+ * Apply parser with fallback value
  *
- * @param value - Value to parse
- * @returns Boolean value
+ * If parser throws, returns fallback instead.
+ * Useful for optional environment variables with complex parsing.
+ *
+ * @param parser - Parser to attempt
+ * @param fallback - Fallback value if parsing fails
+ * @returns Parser function
  *
  * @example
  * ```typescript
- * const debug = parseBoolean(getEnvVar('DEBUG', { default: 'false' })!);
+ * const config = getEnvVar('CONFIG_JSON', {
+ *   validator: withFallback(parseJson, { host: 'localhost', port: 3000 }),
+ * });
  * ```
  */
-declare function parseBoolean(value: string): boolean;
+declare function withFallback<T>(parser: Parser<T>, fallback: T): Parser<T>;
 /**
- * Validate that a value is one of allowed options
+ * Make parser optional
  *
- * @param value - Value to validate
- * @param allowed - Array of allowed values
- * @param caseInsensitive - Whether to perform case-insensitive comparison
- * @returns True if value is in allowed list, false otherwise
+ * Returns undefined for empty strings instead of throwing.
+ *
+ * @param parser - Parser to make optional
+ * @returns Parser function that returns T | undefined
  *
  * @example
  * ```typescript
- * const env = getEnvVar('NODE_ENV', {
- *   validator: (val) => validateEnum(val, ['development', 'production', 'test']),
+ * const redisUrl = getEnvVar('REDIS_URL', {
+ *   validator: optional(parseRedisUrl),
  * });
+ * // Empty string → undefined
+ * // Valid URL → parsed URL
+ * // Invalid URL → throws
  * ```
  */
-declare function validateEnum(value: string, allowed: string[], caseInsensitive?: boolean): boolean;
+declare function optional<T>(parser: Parser<T>): Parser<T | undefined>;
+
 /**
- * Create an enum validator with specific allowed values
+ * Environment Variable Schema Definition System
  *
- * @param allowed - Array of allowed values
- * @param caseInsensitive - Whether to perform case-insensitive comparison
- * @returns Validator function
+ * 환경변수에 메타데이터를 정의하여 중앙 관리, 문서화, 검증을 지원합니다.
  *
  * @example
  * ```typescript
- * const logLevel = getEnvVar('LOG_LEVEL', {
- *   validator: createEnumValidator(['debug', 'info', 'warn', 'error']),
- *   validationError: 'LOG_LEVEL must be one of: debug, info, warn, error',
+ * const schema = defineEnvSchema({
+ *   DATABASE_URL: envUrl({
+ *     description: 'Database connection',
+ *     required: true,
+ *     validator: parsePostgresUrl,
+ *     sensitive: true,
+ *   })
  * });
  * ```
+ *
+ * @module env/schema
+ */
+/**
+ * 환경변수 스키마 정의
+ */
+interface EnvVarSchema<T = string> {
+    /** 환경변수 키 */
+    key: string;
+    /** 설명 (목적, 사용처) */
+    description: string;
+    /** 타입 */
+    type: 'string' | 'number' | 'boolean' | 'url' | 'enum' | 'json';
+    /** 필수 여부 */
+    required?: boolean;
+    /** 기본값 */
+    default?: T;
+    /** 검증/변환 함수 */
+    validator?: (value: string) => T;
+    /** Fallback 환경변수 키들 (backward compatibility) */
+    fallbackKeys?: string[];
+    /** 최소 길이 (문자열 타입) */
+    minLength?: number;
+    /** 민감정보 여부 (로깅 시 마스킹) */
+    sensitive?: boolean;
+    /** 예시 값들 (타입과 일치해야 함) */
+    examples?: T[];
+}
+/**
+ * 스키마 컬렉션 타입
+ */
+type EnvSchemaCollection = Record<string, EnvVarSchema<any>>;
+/**
+ * Helper type: Check if field has default value
+ */
+type HasDefault<T> = T extends {
+    default: any;
+} ? true : false;
+/**
+ * Helper type: Check if field is explicitly required
+ */
+type IsRequired<T> = T extends {
+    required: true;
+} ? true : false;
+/**
+ * Helper type: Check if field should be required (has default OR required: true)
+ */
+type ShouldBeRequired<T> = HasDefault<T> extends true ? true : IsRequired<T>;
+/**
+ * 스키마로부터 타입 추출
+ *
+ * required: true 또는 default가 있는 필드 → 필수
+ * required: false 또는 미지정 → optional (| undefined)
  */
-declare function createEnumValidator(allowed: string[], caseInsensitive?: boolean): (value: string) => boolean;
+type InferEnvType<T extends EnvSchemaCollection> = {
+    [K in keyof T as ShouldBeRequired<T[K]> extends true ? K : never]: T[K] extends EnvVarSchema<infer U> ? U : string;
+} & {
+    [K in keyof T as ShouldBeRequired<T[K]> extends true ? never : K]?: T[K] extends EnvVarSchema<infer U> ? U | undefined : string | undefined;
+};
 /**
- * Validate that a value matches a regular expression
+ * 스키마 정의 헬퍼 (타입 추론 지원)
  *
- * @param value - Value to validate
- * @param pattern - Regular expression pattern
- * @returns True if value matches pattern, false otherwise
+ * Automatically fills in the `key` property from object keys.
  *
  * @example
  * ```typescript
- * const apiKey = getEnvVar('API_KEY', {
- *   validator: (val) => validatePattern(val, /^[A-Za-z0-9_-]{32}$/),
+ * const schema = defineEnvSchema({
+ *   DATABASE_URL: envString({ description: 'Database URL', required: true })
  * });
+ * // Automatically adds key: 'DATABASE_URL'
  * ```
  */
-declare function validatePattern(value: string, pattern: RegExp): boolean;
+declare function defineEnvSchema<T extends Record<string, any>>(schema: T): {
+    [K in keyof T]: T[K] & {
+        key: K;
+    };
+};
 /**
- * Create a pattern validator with specific regex
+ * 문자열 스키마 헬퍼
  *
- * @param pattern - Regular expression pattern
- * @returns Validator function
+ * @example
+ * ```typescript
+ * const schema = {
+ *   API_KEY: {
+ *     ...envString({
+ *       description: 'API authentication key',
+ *       required: true,
+ *       sensitive: true,
+ *     }),
+ *     key: 'API_KEY',
+ *   }
+ * };
+ * ```
+ */
+declare function envString<T extends Omit<EnvVarSchema, 'key' | 'type'>>(options: T): T & {
+    type: 'string';
+};
+/**
+ * 숫자 스키마 헬퍼
  *
  * @example
  * ```typescript
- * const apiKey = getEnvVar('API_KEY', {
- *   validator: createPatternValidator(/^[A-Za-z0-9_-]{32}$/),
- *   validationError: 'API_KEY must be 32 alphanumeric characters',
- * });
+ * const schema = {
+ *   PORT: {
+ *     ...envNumber({
+ *       description: 'Server port',
+ *       default: 3000,
+ *       validator: createNumberParser({ min: 1, max: 65535 }),
+ *     }),
+ *     key: 'PORT',
+ *   }
+ * };
  * ```
  */
-declare function createPatternValidator(pattern: RegExp): (value: string) => boolean;
+declare function envNumber<T extends Omit<EnvVarSchema<number>, 'key' | 'type'>>(options: T): T & {
+    type: 'number';
+    validator: (value: string) => number;
+};
 /**
- * Validate that a value is not empty
+ * Boolean 스키마 헬퍼
  *
- * @param value - Value to validate
- * @returns True if not empty, false otherwise
+ * @example
+ * ```typescript
+ * const schema = {
+ *   DEBUG: {
+ *     ...envBoolean({
+ *       description: 'Enable debug mode',
+ *       default: false,
+ *     }),
+ *     key: 'DEBUG',
+ *   }
+ * };
+ * ```
+ */
+declare function envBoolean<T extends Omit<EnvVarSchema<boolean>, 'key' | 'type'>>(options: T): T & {
+    type: 'boolean';
+    validator: (value: string) => boolean;
+};
+/**
+ * URL 스키마 헬퍼
  *
  * @example
  * ```typescript
- * const name = getEnvVar('APP_NAME', {
- *   validator: validateNotEmpty,
- * });
+ * const schema = {
+ *   DATABASE_URL: {
+ *     ...envUrl({
+ *       description: 'Database connection URL',
+ *       required: true,
+ *       validator: parsePostgresUrl,
+ *     }),
+ *     key: 'DATABASE_URL',
+ *   }
+ * };
  * ```
  */
-declare function validateNotEmpty(value: string): boolean;
+declare function envUrl<T extends Omit<EnvVarSchema, 'key' | 'type'>>(options: T): T & {
+    type: 'url';
+};
 /**
- * Validate that a value has minimum length
+ * Enum 스키마 헬퍼
  *
- * @param value - Value to validate
- * @param minLength - Minimum required length
- * @returns True if meets minimum length, false otherwise
+ * @example
+ * ```typescript
+ * const schema = {
+ *   LOG_LEVEL: {
+ *     ...envEnum(['debug', 'info', 'warn', 'error'] as const, {
+ *       description: 'Logging level',
+ *       default: 'info',
+ *     }),
+ *     key: 'LOG_LEVEL',
+ *   }
+ * };
+ * ```
+ */
+declare function envEnum<T extends string, O extends Omit<EnvVarSchema<T>, 'key' | 'type' | 'validator'>>(allowed: readonly T[], options: O): O & {
+    type: 'enum';
+    validator: (val: string) => T;
+};
+/**
+ * JSON 스키마 헬퍼
  *
  * @example
  * ```typescript
- * const password = getEnvVar('DB_PASSWORD', {
- *   validator: (val) => validateMinLength(val, 8),
- * });
+ * const schema = {
+ *   CONFIG_JSON: {
+ *     ...envJson<{ host: string; port: number }>({
+ *       description: 'JSON configuration object',
+ *       required: true,
+ *     }),
+ *     key: 'CONFIG_JSON',
+ *   }
+ * };
  * ```
  */
-declare function validateMinLength(value: string, minLength: number): boolean;
+declare function envJson<T = any, O extends Omit<EnvVarSchema<T>, 'key' | 'type' | 'validator'> = Omit<EnvVarSchema<T>, 'key' | 'type' | 'validator'>>(options: O): O & {
+    type: 'json';
+    validator: (val: string) => T;
+};
 /**
- * Create a minimum length validator
+ * 환경변수가 클라이언트에서 접근 가능한지 확인
+ * (NEXT_PUBLIC_ 접두사로 판단)
  *
- * @param minLength - Minimum required length
- * @returns Validator function
+ * @param key - 환경변수 키
+ * @returns 클라이언트에서 접근 가능하면 true
  *
  * @example
  * ```typescript
- * const password = getEnvVar('DB_PASSWORD', {
- *   validator: createMinLengthValidator(8),
- *   validationError: 'DB_PASSWORD must be at least 8 characters',
- * });
+ * isClientAccessible('NEXT_PUBLIC_API_URL');  // true
+ * isClientAccessible('DATABASE_URL');         // false
  * ```
  */
-declare function createMinLengthValidator(minLength: number): (value: string) => boolean;
+declare function isClientAccessible(key: string): boolean;
 /**
- * Combine multiple validators with AND logic
+ * 환경변수가 서버 전용인지 확인
+ * (NEXT_PUBLIC_ 접두사가 없으면 서버 전용)
  *
- * @param validators - Array of validator functions
- * @returns Combined validator function
+ * @param key - 환경변수 키
+ * @returns 서버 전용이면 true
  *
  * @example
  * ```typescript
- * const port = getEnvVar('PORT', {
- *   validator: combineValidators([
- *     validateNotEmpty,
- *     createNumberValidator({ min: 1, max: 65535, integer: true }),
- *   ]),
- * });
+ * isServerOnly('DATABASE_URL');              // true
+ * isServerOnly('NEXT_PUBLIC_API_URL');       // false
  * ```
  */
-declare function combineValidators(validators: Array<(value: string) => boolean>): (value: string) => boolean;
+declare function isServerOnly(key: string): boolean;
+
 /**
- * Validate PostgreSQL connection string
+ * Environment Variable Registry
  *
- * @param value - Value to validate
- * @returns True if valid PostgreSQL URL, false otherwise
+ * 환경변수 스키마를 등록하고 타입 안전하게 접근할 수 있는 레지스트리
  *
  * @example
  * ```typescript
- * const dbUrl = getEnvVar('DATABASE_URL', {
- *   validator: validatePostgresUrl,
+ * const schema = defineEnvSchema({
+ *   DATABASE_URL: envString({ description: 'Database URL', required: true })
  * });
+ *
+ * const registry = createEnvRegistry(schema);
+ * const env = registry.validate(); // 검증 + env 반환
+ * console.log(env.DATABASE_URL);
  * ```
+ *
+ * @module env/registry
  */
-declare function validatePostgresUrl(value: string): boolean;
+
 /**
- * Validate Redis connection string
+ * 환경변수 레지스트리
  *
- * @param value - Value to validate
- * @returns True if valid Redis URL, false otherwise
+ * 스키마 기반 환경변수 관리 및 검증
+ */
+declare class EnvRegistry<T extends EnvSchemaCollection = EnvSchemaCollection> {
+    private schemas;
+    private hasValidated;
+    private valueCache;
+    constructor(schemas?: T);
+    /**
+     * 스키마 등록
+     */
+    register(schema: EnvVarSchema): void;
+    /**
+     * 여러 스키마 등록
+     */
+    registerMultiple(schemas: EnvSchemaCollection): void;
+    /**
+     * 캐시 및 검증 상태 리셋 (테스트용)
+     */
+    reset(): void;
+    /**
+     * 환경변수 원시값 가져오기 (fallback 지원)
+     */
+    private getRawValue;
+    /**
+     * 값에 validator 적용
+     */
+    private applyValidator;
+    /**
+     * 스키마 검증 수행 (값 읽기 없이)
+     *
+     * @internal
+     */
+    private validateSchemas;
+    /**
+     * 실제 접근 시점에 환경변수 값 가져오기 및 검증
+     *
+     * @internal
+     */
+    private getAndValidate;
+    /**
+     * 환경변수 검증 및 타입 안전한 env 객체 반환
+     *
+     * Proxy 기반으로 구현되어 실제 환경변수 접근 시점에 값을 읽고 검증합니다.
+     * 이를 통해 dotenv 로딩 타이밍과 무관하게 최신 환경변수 값을 가져올 수 있습니다.
+     *
+     * @returns 검증된 환경변수 객체 (Proxy)
+     * @throws {Error} 필수 변수 누락 또는 검증 실패 시
+     *
+     * @example
+     * ```typescript
+     * const registry = createEnvRegistry(schema);
+     * const env = registry.validate(); // 스키마만 검증
+     * // ... dotenv 로딩 ...
+     * console.log(env.DATABASE_URL); // 이 시점에 실제 값 읽기
+     * ```
+     */
+    validate(): InferEnvType<T>;
+}
+/**
+ * 레지스트리 생성 헬퍼
  *
  * @example
  * ```typescript
- * const redisUrl = getEnvVar('REDIS_URL', {
- *   validator: validateRedisUrl,
+ * const schema = defineEnvSchema({
+ *   DATABASE_URL: envString({ description: 'Database URL', required: true })
  * });
+ *
+ * const registry = createEnvRegistry(schema);
+ * const env = registry.validate();
  * ```
  */
-declare function validateRedisUrl(value: string): boolean;
+declare function createEnvRegistry<T extends EnvSchemaCollection>(schemas: T): EnvRegistry<T>;
+
+/**
+ * Environment Types
+ */
+/**
+ * Node.js environment types
+ */
+type NodeEnv = 'local' | 'development' | 'staging' | 'production' | 'test';
 
-export { ENV_FILE_PRIORITY, type GetEnvOptions, type LoadEnvironmentOptions, type LoadResult, TEST_ONLY_FILES, combineValidators, createEnumValidator, createMinLengthValidator, createNumberValidator, createPatternValidator, createUrlValidator, getEnvVar, getEnvVars, hasEnvVar, isEnvironmentLoaded, loadEnvironment, parseBoolean, requireEnvVar, resetEnvironment, validateBoolean, validateEnum, validateMinLength, validateNotEmpty, validateNumber, validatePattern, validatePostgresUrl, validateRedisUrl, validateUrl };
+export { EnvRegistry, type EnvSchemaCollection, type EnvVarSchema, type InferEnvType, type NodeEnv, type Parser, chain, createArrayParser, createEnumParser, createEnvRegistry, createJsonParser, createNumberParser, createPasswordParser, createSecureSecretParser, createStringParser, createUrlParser, defineEnvSchema, envBoolean, envEnum, envJson, envNumber, envString, envUrl, isClientAccessible, isServerOnly, optional, parseArray, parseBoolean, parseDecimal, parseEnum, parseInteger, parseJson, parseNumber, parsePostgresUrl, parseRedisUrl, parseString, parseUrl, withFallback };