@onebun/envs 0.1.0

package/README.md

@@ -0,0 +1,206 @@
+# @onebun/envs
+
+Environment variables management package for OneBun framework with strict TypeScript support, validation, and Effect integration.
+
+## Features
+
+- 🔒 **Type-safe**: Full TypeScript support with type inference
+- 🛡️ **Validation**: Built-in validators and custom validation support
+- 📊 **Effect Integration**: Uses Effect library for error handling
+- 🔧 **Environment Loading**: Support for `.env` files and environment variables
+- 🎭 **Sensitive Data**: Automatic masking of sensitive values in logs
+- 🏗️ **Nested Configuration**: Support for nested configuration objects
+- 📝 **Validation Helpers**: Pre-built validators for common use cases
+
+## Installation
+
+```bash
+bun add @onebun/envs
+```
+
+## Quick Start
+
+```typescript
+import { TypedEnv, Env } from '@onebun/envs';
+
+// Define your configuration schema
+const schema = {
+  app: {
+    port: Env.number({ default: 3000, validate: Env.port() }),
+    host: Env.string({ default: 'localhost' }),
+    env: Env.string({ 
+      default: 'development',
+      validate: Env.oneOf(['development', 'production', 'test'])
+    })
+  },
+  database: {
+    url: Env.string({ 
+      required: true, 
+      validate: Env.url() 
+    }),
+    password: Env.string({ 
+      sensitive: true, 
+      required: true 
+    })
+  }
+};
+
+// Create typed configuration
+const config = await TypedEnv.createAsync(schema);
+
+// Access values with full type safety
+const port = config.get('app.port'); // number
+const dbUrl = config.get('database.url'); // string
+
+// Get safe config for logging (sensitive data masked)
+console.log(config.getSafeConfig());
+// Output: { app: { port: 3000, host: 'localhost', env: 'development' }, database: { url: 'postgres://...', password: '***' } }
+```
+
+## API Reference
+
+### Environment Variable Types
+
+- `Env.string(options)` - String configuration
+- `Env.number(options)` - Number configuration with range validation
+- `Env.boolean(options)` - Boolean configuration
+- `Env.array(options)` - Array configuration with length validation
+
+### Built-in Validators
+
+- `Env.regex(pattern, message?)` - Regular expression validation
+- `Env.oneOf(values, message?)` - Enum validation
+- `Env.url(message?)` - URL validation
+- `Env.email(message?)` - Email validation
+- `Env.port(message?)` - Port number validation (1-65535)
+
+### Configuration Options
+
+```typescript
+interface EnvVariableConfig<T> {
+  env?: string;           // Custom environment variable name
+  description?: string;   // Variable description
+  type: EnvValueType;    // Variable type
+  default?: T;           // Default value
+  required?: boolean;    // Required field
+  sensitive?: boolean;   // Sensitive field (masked in logs)
+  validate?: Function;   // Custom validation function
+  separator?: string;    // Array separator (default: ',')
+}
+```
+
+## Testing
+
+The package includes comprehensive unit tests with high coverage:
+
+```bash
+# Run tests
+bun test
+
+# Run tests with coverage
+bun run test:coverage
+```
+
+### Test Structure
+
+- **Unit Tests**: 95+ tests covering all core functionality
+- **Integration Tests**: Real-world scenarios and complex configurations  
+- **Error Handling**: Comprehensive error scenarios and edge cases
+- **Performance Tests**: Large configuration handling and efficiency
+
+### Test Coverage
+
+- ✅ **Types**: Error classes and type definitions
+- ✅ **Parser**: String-to-type conversion and validation
+- ✅ **Loader**: .env file loading and process.env handling
+- ✅ **TypedEnv**: Configuration creation and management
+- ✅ **Helpers**: All built-in validators and utilities
+- ✅ **Integration**: End-to-end workflows and complex scenarios
+
+### Running Specific Tests
+
+```bash
+# Run specific test file
+bun test tests/parser.test.ts
+
+# Run tests matching pattern
+bun test --match "*validation*"
+
+# Run tests in watch mode
+bun test --watch
+```
+
+## Environment Variable Loading
+
+The package supports multiple sources for environment variables:
+
+1. **Process Environment**: `process.env` variables
+2. **.env Files**: Support for `.env` file loading
+3. **Priority Control**: Configure which source takes precedence
+
+```typescript
+const config = await TypedEnv.createAsync(schema, {
+  envFilePath: '.env.production',
+  envOverridesDotEnv: true,  // process.env overrides .env file
+  loadDotEnv: true           // enable .env file loading
+});
+```
+
+## Advanced Usage
+
+### Custom Validation
+
+```typescript
+const schema = {
+  apiKey: Env.string({
+    required: true,
+    sensitive: true,
+    validate: (value: string) => {
+      if (value.length < 32) {
+        return Effect.fail(new Error('API key too short'));
+      }
+      return Effect.succeed(value);
+    }
+  })
+};
+```
+
+### Nested Configuration
+
+```typescript
+const schema = {
+  server: {
+    http: {
+      port: Env.number({ default: 3000 }),
+      host: Env.string({ default: 'localhost' })
+    },
+    https: {
+      port: Env.number({ default: 3443 }),
+      cert: Env.string({ sensitive: true })
+    }
+  }
+};
+
+// Access nested values
+const httpPort = config.get('server.http.port');
+const httpsCert = config.get('server.https.cert');
+```
+
+## Error Handling
+
+All validation errors are properly typed and provide detailed context:
+
+```typescript
+try {
+  const config = await TypedEnv.createAsync(schema);
+} catch (error) {
+  if (error instanceof EnvValidationError) {
+    console.log(`Validation failed for ${error.variable}: ${error.reason}`);
+    console.log(`Got value: ${error.value}`);
+  }
+}
+```
+
+## License
+
+MIT 

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@onebun/envs",
+  "version": "0.1.0",
+  "description": "Environment variables management package for OneBun framework",
+  "license": "LGPL-3.0",
+  "author": "RemRyahirev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RemRyahirev/onebun.git",
+    "directory": "packages/envs"
+  },
+  "bugs": {
+    "url": "https://github.com/RemRyahirev/onebun/issues"
+  },
+  "homepage": "https://github.com/RemRyahirev/onebun/tree/master/packages/envs#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "bun test",
+    "test:coverage": "bun test --coverage",
+    "lint": "eslint --fix --config ../../eslint.config.js ./"
+  },
+  "dependencies": {
+    "effect": "^3.13.10"
+  },
+  "devDependencies": {
+    "bun-types": "1.2.2"
+  },
+  "engines": {
+    "bun": "1.2.2"
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,259 @@
+import { Effect } from 'effect';
+
+import { EnvValidationError, type EnvVariableConfig } from './types';
+
+/**
+ * Helpers for creating environment variable configurations
+ */
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const Env = {
+  /**
+   * Create configuration for string variable
+   */
+  string(
+    options: {
+      env?: string;
+      description?: string;
+      default?: string;
+      required?: boolean;
+      sensitive?: boolean;
+      separator?: string;
+      validate?: (value: string) => Effect.Effect<string, EnvValidationError>;
+    } = {},
+  ): EnvVariableConfig<string> {
+    return {
+      type: 'string',
+      separator: ',',
+      ...options,
+    };
+  },
+
+  /**
+   * Create configuration for number variable
+   */
+  number(
+    options: {
+      env?: string;
+      description?: string;
+      default?: number;
+      required?: boolean;
+      sensitive?: boolean;
+      min?: number;
+      max?: number;
+      validate?: (value: number) => Effect.Effect<number, EnvValidationError>;
+    } = {},
+  ): EnvVariableConfig<number> {
+    let validator = options.validate;
+
+    // Add range validation if specified
+    if (options.min !== undefined || options.max !== undefined) {
+      const rangeValidator = (value: number) => {
+        if (options.min !== undefined && value < options.min) {
+          return Effect.fail(new EnvValidationError('', value, `Value must be >= ${options.min}`));
+        }
+        if (options.max !== undefined && value > options.max) {
+          return Effect.fail(new EnvValidationError('', value, `Value must be <= ${options.max}`));
+        }
+
+        return Effect.succeed(value);
+      };
+
+      if (validator) {
+        const originalValidator = validator;
+        validator = (value: number) =>
+          rangeValidator(value).pipe(Effect.flatMap(originalValidator));
+      } else {
+        validator = rangeValidator;
+      }
+    }
+
+    return {
+      type: 'number',
+      description: options.description,
+      default: options.default,
+      required: options.required,
+      sensitive: options.sensitive,
+      env: options.env,
+      validate: validator,
+    };
+  },
+
+  /**
+   * Create configuration for boolean variable
+   */
+  boolean(
+    options: {
+      env?: string;
+      description?: string;
+      default?: boolean;
+      required?: boolean;
+      sensitive?: boolean;
+      validate?: (value: boolean) => Effect.Effect<boolean, EnvValidationError>;
+    } = {},
+  ): EnvVariableConfig<boolean> {
+    return {
+      type: 'boolean',
+      ...options,
+    };
+  },
+
+  /**
+   * Create configuration for string array variable
+   */
+  array(
+    options: {
+      env?: string;
+      description?: string;
+      default?: string[];
+      required?: boolean;
+      sensitive?: boolean;
+      separator?: string;
+      minLength?: number;
+      maxLength?: number;
+      validate?: (value: string[]) => Effect.Effect<string[], EnvValidationError>;
+    } = {},
+  ): EnvVariableConfig<string[]> {
+    let validator = options.validate;
+
+    // Add length validation if specified
+    if (options.minLength !== undefined || options.maxLength !== undefined) {
+      const lengthValidator = (value: string[]) => {
+        if (options.minLength !== undefined && value.length < options.minLength) {
+          return Effect.fail(
+            new EnvValidationError(
+              '',
+              value,
+              `Array must have at least ${options.minLength} items`,
+            ),
+          );
+        }
+        if (options.maxLength !== undefined && value.length > options.maxLength) {
+          return Effect.fail(
+            new EnvValidationError('', value, `Array must have at most ${options.maxLength} items`),
+          );
+        }
+
+        return Effect.succeed(value);
+      };
+
+      if (validator) {
+        const originalValidator = validator;
+        validator = (value: string[]) =>
+          lengthValidator(value).pipe(Effect.flatMap(originalValidator));
+      } else {
+        validator = lengthValidator;
+      }
+    }
+
+    return {
+      type: 'array',
+      description: options.description,
+      default: options.default,
+      required: options.required,
+      sensitive: options.sensitive,
+      env: options.env,
+      separator: options.separator || ',',
+      validate: validator,
+    };
+  },
+
+  /**
+   * Create validator for string with regular expression
+   */
+  regex(
+    pattern: RegExp,
+    errorMessage?: string,
+  ): (value: string) => Effect.Effect<string, EnvValidationError> {
+    return (value: string) => {
+      if (!pattern.test(value)) {
+        return Effect.fail(
+          new EnvValidationError('', value, errorMessage || `Value must match pattern ${pattern}`),
+        );
+      }
+
+      return Effect.succeed(value);
+    };
+  },
+
+  /**
+   * Create validator for string from allowed values list
+   */
+  oneOf<T extends string>(
+    allowedValues: readonly T[],
+    errorMessage?: string,
+  ): (value: string) => Effect.Effect<T, EnvValidationError> {
+    return (value: string) => {
+      if (!allowedValues.includes(value as T)) {
+        return Effect.fail(
+          new EnvValidationError(
+            '',
+            value,
+            errorMessage || `Value must be one of: ${allowedValues.join(', ')}`,
+          ),
+        );
+      }
+
+      return Effect.succeed(value as T);
+    };
+  },
+
+  /**
+   * Create validator for URL
+   */
+  url(errorMessage?: string): (value: string) => Effect.Effect<string, EnvValidationError> {
+    return (value: string) => {
+      try {
+        const url = new URL(value);
+
+        // Reject potentially dangerous schemes
+        const dangerousSchemes = ['javascript', 'data', 'vbscript'];
+        if (dangerousSchemes.includes(url.protocol.slice(0, -1))) {
+          throw new Error('Dangerous URL scheme');
+        }
+
+        return Effect.succeed(value);
+      } catch {
+        return Effect.fail(
+          new EnvValidationError('', value, errorMessage || 'Value must be a valid URL'),
+        );
+      }
+    };
+  },
+
+  /**
+   * Create validator for email
+   */
+  email(errorMessage?: string): (value: string) => Effect.Effect<string, EnvValidationError> {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+    return (value: string) => {
+      if (!emailRegex.test(value)) {
+        return Effect.fail(
+          new EnvValidationError('', value, errorMessage || 'Value must be a valid email address'),
+        );
+      }
+
+      return Effect.succeed(value);
+    };
+  },
+
+  /**
+   * Create validator for port number
+   */
+  port(errorMessage?: string): (value: number) => Effect.Effect<number, EnvValidationError> {
+    return (value: number) => {
+      // eslint-disable-next-line no-magic-numbers
+      if (!Number.isInteger(value) || value < 1 || value > 65535) {
+        return Effect.fail(
+          new EnvValidationError(
+            '',
+            value,
+            errorMessage || 'Port must be an integer between 1 and 65535',
+          ),
+        );
+      }
+
+      return Effect.succeed(value);
+    };
+  },
+};

package/src/index.ts

@@ -0,0 +1,7 @@
+// Re-export Effect for convenience
+export { Effect } from 'effect';
+export * from './helpers';
+export * from './loader';
+export * from './parser';
+export * from './typed-env';
+export * from './types';

package/src/loader.ts

@@ -0,0 +1,150 @@
+import { Effect } from 'effect';
+
+import { EnvLoadError, type EnvLoadOptions } from './types';
+
+/**
+ * Environment variables loader
+ */
+export class EnvLoader {
+  /**
+   * Load environment variables from various sources.
+   * Priority (highest to lowest):
+   * 1. valueOverrides (if provided)
+   * 2. process.env (if envOverridesDotEnv = true)
+   * 3. .env file
+   * 4. process.env (if envOverridesDotEnv = false)
+   */
+  static load(options: EnvLoadOptions = {}): Effect.Effect<Record<string, string>, EnvLoadError> {
+    const {
+      envFilePath = '.env',
+      loadDotEnv = true,
+      envOverridesDotEnv = true,
+      valueOverrides,
+    } = options;
+
+    const loadDotEnvVars = loadDotEnv
+      ? EnvLoader.loadDotEnvFile(envFilePath)
+      : Effect.succeed({} as Record<string, string>);
+
+    const processEnvVars = EnvLoader.loadProcessEnv();
+
+    return loadDotEnvVars.pipe(
+      Effect.map((dotEnvVars) => {
+        let result: Record<string, string>;
+
+        if (envOverridesDotEnv) {
+          // Process environment variables have priority over .env
+          result = { ...dotEnvVars, ...processEnvVars };
+        } else {
+          // .env file has priority over process.env
+          result = { ...processEnvVars, ...dotEnvVars };
+        }
+
+        // Apply valueOverrides with highest priority
+        if (valueOverrides) {
+          for (const [key, value] of Object.entries(valueOverrides)) {
+            result[key] = String(value);
+          }
+        }
+
+        return result;
+      }),
+    );
+  }
+
+  /**
+   * Load variables from .env file
+   */
+  private static loadDotEnvFile(
+    filePath: string,
+  ): Effect.Effect<Record<string, string>, EnvLoadError> {
+    return Effect.tryPromise({
+      async try() {
+        const file = Bun.file(filePath);
+        const exists = await file.exists();
+
+        if (!exists) {
+          return {}; // File not found - not an error, just return empty object
+        }
+
+        const content = await file.text();
+
+        return EnvLoader.parseDotEnvContent(content);
+      },
+      catch: (error) =>
+        new EnvLoadError(
+          filePath,
+          `Failed to read .env file: ${error instanceof Error ? error.message : String(error)}`,
+        ),
+    });
+  }
+
+  /**
+   * Parse .env file content
+   */
+  private static parseDotEnvContent(content: string): Record<string, string> {
+    const variables: Record<string, string> = {};
+    const lines = content.split('\n');
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i].trim();
+
+      // Skip empty lines and comments
+      if (!line || line.startsWith('#')) {
+        continue;
+      }
+
+      // Find equals sign
+      const equalIndex = line.indexOf('=');
+      if (equalIndex === -1) {
+        continue; // Skip lines without equals sign
+      }
+
+      const key = line.slice(0, equalIndex).trim();
+      let value = line.slice(equalIndex + 1).trim();
+
+      // Remove quotes if present
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+
+      // Process escape sequences
+      value = value
+        .replace(/\\n/g, '\n')
+        .replace(/\\r/g, '\r')
+        .replace(/\\t/g, '\t')
+        .replace(/\\\\/g, '\\')
+        .replace(/\\"/g, '"')
+        .replace(/\\'/g, "'");
+
+      variables[key] = value;
+    }
+
+    return variables;
+  }
+
+  /**
+   * Load variables from process.env
+   */
+  private static loadProcessEnv(): Record<string, string> {
+    const variables: Record<string, string> = {};
+
+    for (const [key, value] of Object.entries(process.env)) {
+      if (value !== undefined) {
+        variables[key] = value;
+      }
+    }
+
+    return variables;
+  }
+
+  /**
+   * Check if .env file exists
+   */
+  static checkDotEnvExists(filePath: string = '.env'): Effect.Effect<boolean, never> {
+    return Effect.promise(() => Bun.file(filePath).exists());
+  }
+}

package/src/parser.ts

@@ -0,0 +1,149 @@
+import { Effect } from 'effect';
+
+import {
+  type EnvLoadOptions,
+  EnvValidationError,
+  type EnvValueType,
+  type EnvVariableConfig,
+} from './types';
+
+/**
+ * Environment variable parser
+ */
+export class EnvParser {
+  /**
+   * Parse string value according to configuration
+   */
+  static parse<T>(
+    variable: string,
+    value: string | undefined,
+    config: EnvVariableConfig<T>,
+    options: EnvLoadOptions = {},
+  ): Effect.Effect<T, EnvValidationError> {
+    const resolveValue = Effect.sync(() => {
+      // If value is not set
+      if (value === undefined) {
+        if (config.default !== undefined) {
+          return config.default;
+        }
+        if (config.required) {
+          throw new EnvValidationError(variable, value, 'Required variable is not set');
+        }
+
+        return EnvParser.getDefaultForTypeSync(config.type);
+      }
+
+      return value;
+    });
+
+    const parseValue = (resolvedValue: unknown) => {
+      if (typeof resolvedValue === 'string') {
+        const separator = config.separator || options.defaultArraySeparator || ',';
+
+        return EnvParser.parseByType(variable, resolvedValue, config.type, separator);
+      }
+
+      return Effect.succeed(resolvedValue);
+    };
+
+    const validateParsed = (parsed: unknown) =>
+      EnvParser.validateValue(variable, parsed as T, config);
+
+    return resolveValue.pipe(Effect.flatMap(parseValue), Effect.flatMap(validateParsed));
+  }
+
+  /**
+   * Parse value by type
+   */
+  private static parseByType(
+    variable: string,
+    value: string,
+    type: EnvValueType,
+    separator = ',',
+  ): Effect.Effect<unknown, EnvValidationError> {
+    return Effect.try({
+      try() {
+        switch (type) {
+          case 'string':
+            return value;
+
+          case 'number': {
+            // Empty string should be rejected for numbers
+            if (value.trim() === '') {
+              throw new Error(`"${value}" is not a valid number`);
+            }
+
+            const num = Number(value);
+            if (isNaN(num)) {
+              throw new Error(`"${value}" is not a valid number`);
+            }
+
+            return num;
+          }
+
+          case 'boolean': {
+            const lower = value.toLowerCase();
+            if (['true', '1', 'yes', 'on'].includes(lower)) {
+              return true;
+            }
+            if (['false', '0', 'no', 'off'].includes(lower)) {
+              return false;
+            }
+            throw new Error(`"${value}" is not a valid boolean`);
+          }
+
+          case 'array': {
+            if (value.trim() === '') {
+              return [];
+            }
+
+            return value.split(separator).map((item) => item.trim());
+          }
+
+          default:
+            throw new Error(`Unknown type: ${type}`);
+        }
+      },
+      catch: (error) =>
+        new EnvValidationError(
+          variable,
+          value,
+          error instanceof Error ? error.message : String(error),
+        ),
+    });
+  }
+
+  /**
+   * Validate value
+   */
+  private static validateValue<T>(
+    variable: string,
+    value: T,
+    config: EnvVariableConfig<T>,
+  ): Effect.Effect<T, EnvValidationError> {
+    if (config.validate) {
+      return config.validate(value);
+    }
+
+    return Effect.succeed(value);
+  }
+
+  /**
+   * Get default value for type (sync)
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private static getDefaultForTypeSync(type: EnvValueType): any {
+    switch (type) {
+      case 'string':
+        return '';
+      case 'number':
+        return 0;
+      case 'boolean':
+        return false;
+      case 'array':
+        return [];
+      default:
+        throw new EnvValidationError('unknown', undefined, `Unknown type: ${type}`);
+    }
+  }
+}

package/src/typed-env.ts

@@ -0,0 +1,323 @@
+import { Effect } from 'effect';
+
+import { EnvLoader } from './loader';
+import { EnvParser } from './parser';
+import {
+  type EnvLoadOptions,
+  type EnvSchema,
+  EnvValidationError,
+  type EnvVariableConfig,
+} from './types';
+
+/**
+ * Utility types for automatic type inference
+ */
+type DeepValue<T, Path extends string> = Path extends keyof T
+  ? T[Path]
+  : Path extends `${infer K}.${infer Rest}`
+    ? K extends keyof T
+      ? T[K] extends object
+        ? DeepValue<T[K], Rest>
+        : never
+      : never
+    : // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    any; // Fallback to any for complex paths
+
+type DeepPaths<T> = T extends object
+  ? {
+    [K in keyof T]: K extends string
+      ? T[K] extends object
+        ? K | `${K}.${DeepPaths<T[K]>}`
+        : K
+      : never;
+  }[keyof T]
+  : never;
+
+/**
+ * Sensitive value wrapper that sanitizes toString() output
+ */
+class SensitiveValue<T> {
+  constructor(private readonly _value: T) {}
+
+  get value(): T {
+    return this._value;
+  }
+
+  toString(): string {
+    return '***';
+  }
+
+  toJSON(): string {
+    return '***';
+  }
+
+  valueOf(): T {
+    return this._value;
+  }
+
+  [Symbol.toPrimitive](hint: string): string | number | T {
+    if (hint === 'string') {
+      return '***';
+    }
+    if (hint === 'number' && typeof this._value === 'number') {
+      return this._value;
+    }
+
+    return this._value;
+  }
+}
+
+/**
+ * Configuration proxy that intercepts access and provides type safety
+ */
+class ConfigProxy<T> {
+  private _isInitialized = false;
+  private _values: T | null = null;
+  private _sensitiveFields: Set<string> = new Set();
+
+  constructor(
+    private readonly _schema: EnvSchema<T>,
+    private readonly _options: EnvLoadOptions = {},
+  ) {
+    this.extractSensitiveFields(this._schema, '');
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private extractSensitiveFields(schema: any, prefix = ''): void {
+    for (const [key, config] of Object.entries(schema)) {
+      const fullPath = prefix ? `${prefix}.${key}` : key;
+
+      if (this.isEnvVariableConfig(config)) {
+        if ((config as EnvVariableConfig).sensitive) {
+          this._sensitiveFields.add(fullPath);
+        }
+      } else {
+        this.extractSensitiveFields(config, fullPath);
+      }
+    }
+  }
+
+  private isEnvVariableConfig(config: unknown): boolean {
+    return Boolean(config) && typeof config === 'object' && 'type' in config!;
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (this._isInitialized) {
+      return;
+    }
+
+    const rawVariables = await Effect.runPromise(EnvLoader.load(this._options));
+    this._values = this.parseNestedSchema(this._schema, rawVariables, '') as T;
+    this._isInitialized = true;
+  }
+
+   
+  private parseNestedSchema(
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    schema: any,
+    rawVariables: Record<string, string>,
+    prefix: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  ): any {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result: any = {};
+
+    for (const [key, config] of Object.entries(schema)) {
+      const fullPath = prefix ? `${prefix}.${key}` : key;
+
+      if (this.isEnvVariableConfig(config)) {
+        const envConfig = config as EnvVariableConfig;
+        const envVar = envConfig.env || this.pathToEnvVar(fullPath);
+        const rawValue = rawVariables[envVar];
+
+        try {
+          const parsed = Effect.runSync(
+            EnvParser.parse(
+              envVar,
+              rawValue,
+              // eslint-disable-next-line @typescript-eslint/no-explicit-any
+              envConfig as any,
+              this._options,
+            ),
+          );
+          result[key] = parsed;
+        } catch (error) {
+          if (error instanceof EnvValidationError) {
+            throw error;
+          }
+          throw new EnvValidationError(envVar, rawValue, String(error));
+        }
+      } else {
+        result[key] = this.parseNestedSchema(config, rawVariables, fullPath);
+      }
+    }
+
+    return result;
+  }
+
+  private pathToEnvVar(path: string): string {
+    return path.toUpperCase().replace(/\./g, '_');
+  }
+
+  private getValueByPath(obj: Record<string, unknown>, path: string): unknown {
+    const keys = path.split('.');
+    let current: Record<string, unknown> | unknown = obj;
+
+    for (const key of keys) {
+      if (current && typeof current === 'object' && key in current) {
+        current = current[key as keyof typeof current];
+      } else {
+        return undefined;
+      }
+    }
+
+    return current;
+  }
+
+  /**
+   * Synchronous get method with automatic type inference and sensitive data handling
+   */
+  get<P extends DeepPaths<T>>(path: P): DeepValue<T, P>;
+  get<P extends keyof T>(path: P): T[P];
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  get(path: string): any;
+  get(path: string): unknown {
+    if (!this._isInitialized || !this._values) {
+      throw new Error(
+        'Configuration not initialized. Call TypedEnv.create() or ensure initialization is complete.',
+      );
+    }
+
+    const value = this.getValueByPath(this._values, path);
+
+    // Wrap sensitive values
+    if (this._sensitiveFields.has(path)) {
+      return new SensitiveValue(value);
+    }
+
+    return value;
+  }
+
+  /**
+   * Get the entire configuration object
+   */
+  get values(): T {
+    if (!this._isInitialized || !this._values) {
+      throw new Error(
+        'Configuration not initialized. Call TypedEnv.create() or ensure initialization is complete.',
+      );
+    }
+
+    return this._values;
+  }
+
+  /**
+   * Initialize the configuration (async)
+   */
+  async initialize(): Promise<void> {
+    await this.ensureInitialized();
+  }
+
+  /**
+   * Check if configuration is initialized
+   */
+  get isInitialized(): boolean {
+    return this._isInitialized;
+  }
+
+  /**
+   * Get safe configuration for logging (sensitive data masked)
+   */
+  getSafeConfig(): T {
+    if (!this._isInitialized || !this._values) {
+      throw new Error('Configuration not initialized.');
+    }
+
+    return this.applySensitiveMask(this._values, '') as T;
+  }
+
+  private applySensitiveMask<U = unknown>(obj: U, prefix = ''): U {
+    if (obj === null || obj === undefined) {
+      return obj;
+    }
+
+    if (Array.isArray(obj)) {
+      return obj.map((item) =>
+        typeof item === 'object' ? this.applySensitiveMask<U>(item, prefix) : item,
+      ) as U;
+    }
+
+    if (typeof obj === 'object') {
+      const result: Record<string, unknown> = {};
+
+      for (const [key, value] of Object.entries(obj)) {
+        const fullPath = prefix ? `${prefix}.${key}` : key;
+
+        if (this._sensitiveFields.has(fullPath)) {
+          result[key] = '***';
+        } else if (value && typeof value === 'object') {
+          result[key] = this.applySensitiveMask<U>(value, fullPath);
+        } else {
+          result[key] = value;
+        }
+      }
+
+      return result as U;
+    }
+
+    return obj;
+  }
+}
+
+/**
+ * Static factory for creating typed environment configurations
+ */
+export class TypedEnv {
+  private static instances = new Map<string, ConfigProxy<unknown>>();
+
+  /**
+   * Create or get existing typed environment configuration
+   */
+  static create<T>(
+    schema: EnvSchema<T>,
+    options: EnvLoadOptions = {},
+    key = 'default',
+  ): ConfigProxy<T> {
+    if (!TypedEnv.instances.has(key)) {
+      const proxy = new ConfigProxy(schema, options);
+      TypedEnv.instances.set(key, proxy);
+
+      // Auto-initialize
+      proxy.initialize();
+    }
+
+    return TypedEnv.instances.get(key) as ConfigProxy<T>;
+  }
+
+  /**
+   * Create typed environment configuration with immediate initialization
+   */
+  static async createAsync<T>(
+    schema: EnvSchema<T>,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    options: any = {},
+    key = 'default',
+  ): Promise<ConfigProxy<T>> {
+    const proxy = TypedEnv.create(schema, options, key);
+    await proxy.initialize();
+
+    return proxy;
+  }
+
+  /**
+   * Clear all instances (useful for testing)
+   */
+  static clear(): void {
+    TypedEnv.instances.clear();
+  }
+}
+
+// Export type helpers for external use
+export type { DeepPaths, DeepValue, SensitiveValue };
+export { ConfigProxy };

package/src/types.ts

@@ -0,0 +1,115 @@
+import type { Effect } from 'effect';
+
+/**
+ * Environment variable value types
+ */
+export type EnvValueType = 'string' | 'number' | 'boolean' | 'array';
+
+/**
+ * Configuration for environment variable
+ */
+export interface EnvVariableConfig<T = unknown> {
+  /** Environment variable name (if different from schema key) */
+  env?: string;
+  /** Variable description */
+  description?: string;
+  /** Variable type */
+  type: EnvValueType;
+  /** Default value */
+  default?: T;
+  /** Required field - will throw error if not provided */
+  required?: boolean;
+  /** Sensitive field - will be masked in logs */
+  sensitive?: boolean;
+  /** Validation function */
+  validate?: (value: T) => Effect.Effect<T, EnvValidationError>;
+  /** Separator for arrays (default: ',') */
+  separator?: string;
+}
+
+/**
+ * Environment variables schema supporting nested objects
+ */
+export type EnvSchema<T> = {
+  [K in keyof T]: T[K] extends string | number | boolean | string[] | number[] | boolean[]
+    ? EnvVariableConfig<T[K]>
+    : T[K] extends Record<string, unknown>
+      ? EnvSchema<T[K]>
+      : EnvVariableConfig<T[K]>;
+};
+
+/**
+ * Format value for error messages
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function formatValue(value: any): string {
+  if (value === undefined) {
+    return 'undefined';
+  }
+  if (value === null) {
+    return 'null';
+  }
+  if (typeof value === 'string') {
+    return `"${value}"`;
+  }
+  if (typeof value === 'object') {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return '[object Object]';
+    }
+  }
+
+  return String(value);
+}
+
+/**
+ * Environment variable validation error
+ */
+export class EnvValidationError extends Error {
+  constructor(
+    public readonly variable: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/explicit-module-boundary-types
+    public readonly value: any,
+    public readonly reason: string,
+  ) {
+    super(
+      `Environment variable validation failed for "${variable}": ${reason}. Got: ${formatValue(value)}`,
+    );
+    this.name = 'EnvValidationError';
+  }
+}
+
+/**
+ * Environment variable loading error
+ */
+export class EnvLoadError extends Error {
+  constructor(
+    public readonly variable: string,
+    public readonly reason: string,
+  ) {
+    super(`Failed to load environment variable "${variable}": ${reason}`);
+    this.name = 'EnvLoadError';
+  }
+}
+
+/**
+ * Environment loading options
+ */
+export interface EnvLoadOptions {
+  /** Path to .env file (default: '.env') */
+  envFilePath?: string;
+  /** Whether to load .env file (default: true) */
+  loadDotEnv?: boolean;
+  /** Environment variables override .env file (default: true) */
+  envOverridesDotEnv?: boolean;
+  /** Strict mode - only load variables defined in schema (default: false) */
+  strict?: boolean;
+  /** Default separator for arrays (default: ',') */
+  defaultArraySeparator?: string;
+  /**
+   * Override values that take precedence over both process.env and .env file.
+   * Useful for multi-service setups where each service needs different values.
+   */
+  valueOverrides?: Record<string, string | number | boolean>;
+}