envapt 1.1.0 → 2.1.0

package/README.md

@@ -1,67 +1,127 @@
-# Envapt - The apt way to handle env
-
-A powerful TypeScript-first environment configuration library that provides type detection, template variable resolution, and decorator-based class property configuration by extending dotenv.
-
-## Features
-
-- 🔧 **Automatic Type Detection** - Types inferred from fallback values
+<p align="center">
+  <img src="assets/banner.png" alt="Envapt – The apt way to handle environment variables" width="100%" />
+</p>
+
+<p align="center">
+  A TypeScript environment configuration library that eliminates the boilerplate of parsing <code>.env</code> files.<br/>
+  Get environment variables with correct runtime typing and fallbacks, template support, and automatic, built-in, & custom transformations.<br/>
+  <strong>No more <code>process.env.PORT || '3000'</code> everywhere!</strong>
+</p>
+<div align="center">
+  <img alt="Build" src="https://img.shields.io/github/actions/workflow/status/materwelonDhruv/envapt/publish.yaml?branch=main&label=build&style=flat&logo=github&color=3fb950"></a>
+  <a href="https://codecov.io/github/materwelonDhruv/envapt"><img src="https://codecov.io/github/materwelonDhruv/envapt/branch/main/graph/badge.svg?token=IQ4GC645LO"/></a>
+  <a href="https://www.npmjs.com/package/envapt"><img alt="npm version" src="https://img.shields.io/npm/v/envapt?style=flat&color=cb3838&logo=npm"></a>
+  <a href="LICENSE"><img alt="License" src="https://img.shields.io/npm/l/envapt?style=flat&color=e97826&logo=apache"></a>
+  <a href="https://www.typescriptlang.org/"><img alt="Types" src="https://img.shields.io/badge/types-TypeScript-3178c6?style=flat&logo=typescript&logoColor=white"></a>
+  <a href="https://nodejs.org/api/esm.html"><img alt="ESM" src="https://img.shields.io/badge/ESM-Supported-ffca28?style=flat"></a>
+  <a href="https://nodejs.org/api/modules.html"><img alt="CJS" src="https://img.shields.io/badge/CJS-Supported-ff6b35?style=flat"></a>
+  <a href="https://nodejs.org/"><img alt="Node" src="https://img.shields.io/badge/node-%3E=22.0.0-339933?style=flat&logo=node.js&logoColor=white"></a>
+  <a href="https://bundlephobia.com/package/envapt"><img alt="Bundle Size" src="https://img.shields.io/bundlephobia/minzip/envapt?style=flat&color=success"></a>
+  <a href="https://www.npmjs.com/package/envapt"><img alt="Downloads" src="https://img.shields.io/npm/dm/envapt?style=flat&color=blue"></a>
+  <a href="https://github.com/materwelondhruv/envapt"><img alt="GitHub Stars" src="https://img.shields.io/github/stars/materwelondhruv/envapt?style=flat&color=yellow"></a>
+</div>
+
+---
+
+## ✨ Features
+
+- 🔧 **Automatic Type Detection** - Runtime types inferred from fallback values
 - 🔗 **Template Variables** - `${VAR}` syntax with circular reference protection
-- 🎯 **Class Properties** - Decorator-based configuration for class members
+- 🎯 **Class Properties** - Functional and Decorator-based configuration for class members
 - 🏷️ **Built-in & Custom Converters** - Ready-to-use converters for common patterns + custom transformations
 - 🌍 **Environment Detection** - Built-in development/staging/production handling
 - 📂 **Multiple .env Files** - Load from multiple sources
-- 💪 **Edge Case Handling** - Robust parsing for all scenarios
+- 💪 **Edge Case Handling** - Robust validation and parsing for all scenarios
 - 🛡️ **Type Safety** - Full TypeScript support with proper type inference
+- ⚡ **Lightweight** - Minimal overhead with [`dotenv`](https://www.npmjs.com/package/dotenv) bundled
 
-## Table of Contents
+---
+
+## 📚 Table of Contents
+
+### ⚙️ Essentials
 
 - [Requirements](#requirements)
 - [Quick Start](#quick-start)
   - [Installation](#installation)
   - [Basic Usage](#basic-usage)
+
+### 🧬 API Reference
+
 - [API Reference](#api-reference)
   - [Decorator API](#decorator-api)
-  - [Built-in Converters](#built-in-converters)
-  - [Custom Array Converters](#custom-array-converters)
-  - [Custom Converters](#custom-converters)
-  - [Handling Missing Values](#handling-missing-values)
+    - [Modern Syntax (Recommended)](#modern-syntax-recommended)
+    - [Classic Syntax](#classic-syntax)
+    - [Automatic Runtime Type Detection](#automatic-runtime-type-detection)
+    - [Primitive Converters](#primitive-converters)
+    - [Built-in Converters](#built-in-converters)
+    - [Custom Array Converters](#custom-array-converters)
+    - [Custom Converters](#custom-converters)
+    - [Handling Missing Values](#handling-missing-values)
   - [Functional API](#functional-api)
+  - [Converter Type Quick Reference](#converter-type-quick-reference)
+
+### 🌍 Environment & Templates
+
 - [Environment Detection](#environment-detection)
+  - [Environment Management](#environment-management)
 - [Template Variables](#template-variables)
+  - [Circular Reference Protection](#circular-reference-protection)
+
+### 🛠 Configuration & Errors
+
+- [Configuration](#configuration)
+  - [Multiple .env Files](#multiple-env-files)
+  - [Dotenv Configuration](#dotenv-configuration)
+- [Error Handling](#error-handling)
+  - [Error Code Reference](#error-code-reference)
+
+### 🚀 Examples
+
 - [Advanced Examples](#advanced-examples)
+  - [Complex Configuration](#complex-configuration)
+
+---
 
 ## Requirements
 
-- **Node.js**: v22 or later (recommended for ESM and nodenext support)
-- **TypeScript**: v5.8 or later
-- **Dependencies**:
-  - `dotenv` (runtime dependency | bundled)
-- **TypeScript Compiler Options**:
-  - `experimentalDecorators: true`
-  - `module: nodenext OR esnext`
-  - `moduleResolution: nodenext OR bundler`
-  - `target: ESnext`
-  - `lib: ESNext`
-- **ESM Support**: Project uses ESM, so your environment and tooling should support ES modules.
+#### 🟢 Runtime
 
-## Quick Start
+- **Node.js**: `>=22.0.0`  
+  _Recommended for full ESM and `nodenext` support_
 
-### Installation
+- **TypeScript**: `>=5.8`
 
-```bash
-# npm
-npm install envapt
+#### 📦 Runtime Dependency
 
-# pnpm
-pnpm add envapt
+- **dotenv**: _(bundled at runtime)_
 
-# yarn
-yarn add envapt
+#### 🛠️ TypeScript Compiler Options
+
+```jsonc
+// tsconfig.json (required settings)
+{
+  "experimentalDecorators": true,
+  "module": "esnext", // or "nodenext"
+  "moduleResolution": "bundler", // or "nodenext"
+  "target": "ESNext",
+  "lib": ["ESNext"]
+}
 ```
 
+## Quick Start
+
+### Installation
+
+| Package Manager | Command              |
+| --------------- | -------------------- |
+| **npm**         | `npm install envapt` |
+| **pnpm**        | `pnpm add envapt`    |
+| **yarn**        | `yarn add envapt`    |
+
 ### Basic Usage
 
-Create a `.env` file:
+**Step 1:** Create a `.env` file:
 
 ```env
 APP_PORT=8443
@@ -72,22 +132,22 @@ MAX_CONNECTIONS=100
 ALLOWED_ORIGINS=https://app.com,https://admin.com
 ```
 
-Use with decorators (recommended):
+Use with decorators:
 
 ```ts
-import { Envapt, Envapter } from 'envapt';
+import { Envapt, Envapter, Converters } from 'envapt';
 
 // Global app configuration (static properties)
 class AppConfig extends Envapter {
   @Envapt('APP_PORT', 3000)
   static readonly port: number;
 
-  @Envapt('APP_URL', 'http://localhost:3000', 'url')
+  @Envapt('APP_URL', 'http://localhost:3000', Converters.Url)
   static readonly url: URL;
 
   @Envapt('ALLOWED_ORIGINS', {
     fallback: ['http://localhost:3000'],
-    converter: 'array'
+    converter: Converters.Array
   })
   static readonly allowedOrigins: string[];
 }
@@ -97,10 +157,10 @@ class DatabaseService {
   @Envapt('DATABASE_URL', 'sqlite://memory')
   declare readonly databaseUrl: string;
 
-  @Envapt('MAX_CONNECTIONS', { converter: 'number', fallback: 10 })
+  @Envapt('MAX_CONNECTIONS', { converter: Converters.Number, fallback: 10 })
   declare readonly maxConnections: number;
 
-  @Envapt('REQUEST_TIMEOUT', { converter: 'time', fallback: 5000 })
+  @Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: 5000 })
   declare readonly timeout: number; // Converts "5s" to 5000ms
 
   async connect() {
@@ -117,8 +177,7 @@ const dbService = new DatabaseService();
 await dbService.connect();
 ```
 
-Or use functionally:\
-<sub>Limited to primitives, String, Number, Boolean, Symbol, and BigInt. Does not support converters.</sub>
+Or use functionally:
 
 ```ts
 import { Envapter } from 'envapt';
@@ -151,9 +210,9 @@ The `@Envapt` decorator can be used on both **static** and **instance** class pr
 @Envapt('ENV_VAR', fallback?, converter?)
 ```
 
-#### Automatic Type Detection
+#### Automatic Runtime Type Detection
 
-Types are automatically inferred from fallback values. Use static properties for app-wide config and instance properties for service-specific config:
+Types are automatically inferred from fallback values.
 
 ```ts
 class Config extends Envapter {
@@ -183,65 +242,144 @@ class Config extends Envapter {
 }
 ```
 
+#### Primitive Converters
+
+Envapt allows using the 5 "primitive" type-like converters. These **will** coerce values.
+
+> [!NOTE]
+> The runtime validator will ignore this usage, allowing type coercion for flexibility.
+
+**Valid Primitive Types:** `String`, `Number`, `Boolean`, `Symbol`, and `BigInt`.
+
+```ts
+class Config extends Envapter {
+  @Envapt('PORT_STRING', { fallback: 'hello-world', converter: String })
+  static readonly portAsString: string;
+
+  @Envapt('DEBUG_FLAG', { fallback: true, converter: Boolean })
+  static readonly debugMode: boolean;
+
+  @Envapt('USER_ID', { fallback: 12345, converter: Number })
+  static readonly userId: number;
+
+  @Envapt('MAX_SAFE_INT', { fallback: 9007199254740991n, converter: BigInt })
+  static readonly maxSafeInt: bigint;
+
+  @Envapt('APP_INSTANCE', { fallback: Symbol(main), converter: Symbol })
+  static readonly appInstance: symbol;
+
+  // Instance properties work the same way
+  @Envapt('CONNECTION_TIMEOUT', { fallback: 5000, converter: Number })
+  declare readonly timeout: number;
+
+  // Type coercion example
+  @Envapt('PERMISSIONS', { fallback: '72394823472342983', converter: BigInt })
+  declare readonly permissions: bigint; // Converts "72394823472342983" to BigInt
+}
+```
+
+**When to use primitive converters:**
+
+- When you need explicit type coercion between incompatible types
+- When working with external systems that provide values in unexpected formats
+
 #### Built-in Converters
 
 Envapt provides many built-in converters for common patterns:
 
+> [!IMPORTANT]
+> **Use the `Converters` enum** instead of string literals. They look better, and provide better type inference:
+>
+> ```ts
+> import { Converters } from 'envapt';
+> // ✅ Recommended: Use enum
+> @Envapt('PORT', { converter: Converters.Number, fallback: 3000 })
+>
+> // ❌ Discouraged: String literals (still supported for compatibility)
+> @Envapt('PORT', { converter: 'number', fallback: 3000 })
+> ```
+
+> [!IMPORTANT]
+> Built-in converters enforce **strict type validation** between the converter and fallback types. The converter's expected return type must match the fallback's type.
+
 ```ts
 class Config extends Envapter {
   // Basic types
-  @Envapt('APP_NAME', { converter: 'string', fallback: 'MyApp' })
+  @Envapt('APP_NAME', { converter: Converters.String, fallback: 'MyApp' })
   static readonly appName: string;
 
-  @Envapt('PORT', { converter: 'number', fallback: 3000 })
+  @Envapt('PORT', { converter: Converters.Number, fallback: 3000 })
   static readonly port: number;
 
-  @Envapt('PRODUCTION_MODE', { converter: 'boolean', fallback: false })
+  @Envapt('PRODUCTION_MODE', { converter: Converters.Boolean, fallback: false })
   static readonly productionMode: boolean;
 
   // Advanced types
-  @Envapt('CORS_ORIGINS', { converter: 'array', fallback: [] })
+  @Envapt('CORS_ORIGINS', { converter: Converters.Array, fallback: [] })
   static readonly corsOrigins: string[];
 
-  @Envapt('CONFIG_JSON', { converter: 'json', fallback: {} })
+  @Envapt('CONFIG_JSON', { converter: Converters.Json, fallback: {} })
   static readonly config: object;
 
-  @Envapt('API_URL', { converter: 'url', fallback: new URL('http://localhost') })
+  @Envapt('API_URL', { converter: Converters.Url, fallback: new URL('http://localhost') })
   static readonly apiUrl: URL;
 
-  @Envapt('TIMEOUT', { converter: 'time', fallback: 5000 })
+  @Envapt('TIMEOUT', { converter: Converters.Time, fallback: 5000 })
   static readonly timeout: number; // Converts "30s" to 30000ms
 
   // Instance properties work the same way
-  @Envapt('CACHE_TTL', { converter: 'time', fallback: 3600000 })
+  @Envapt('CACHE_TTL', { converter: Converters.Time, fallback: 3600000 })
   declare readonly cacheTtl: number; // "1h" becomes 3600000ms
 }
 ```
 
+> [!WARNING]
+> These will throw runtime errors due to type mismatches:
+>
+> ```ts
+> // ❌ String converter with number fallback
+> @Envapt('VAR', { converter: Converters.String, fallback: 42 })
+>
+> // ❌ URL converter with string fallback
+> @Envapt('VAR', { converter: Converters.Url, fallback: 'http://example.com' })
+>
+> // ✅ Use primitive constructors for type coercion instead
+> @Envapt('VAR', { converter: String, fallback: 42 })
+> ```
+
 **Available Built-in Converters:**
 
-- `'string'` - String values
-- `'number'` - Numeric values (integers and floats)
-- `'integer'` - Integer values only
-- `'float'` - Float values only
-- `'boolean'` - Boolean values (true/false, yes/no, on/off, 1/0)
-- `'bigint'` - BigInt values for large integers
-- `'symbol'` - Symbol values (creates symbols from string descriptions)
-- `'json'` - JSON objects/arrays (safe parsing with fallback)
-- `'array'` - Comma-separated string arrays
-- `'url'` - URL objects
-- `'regexp'` - Regular expressions (supports `/pattern/flags` syntax)
-- `'date'` - Date objects (supports ISO strings and timestamps)
-- `'time'` - Time values (converts "5s", "30m", "2h" to milliseconds)
+| **Converter**        | **Alias**   | **Description**                                                      |
+| -------------------- | ----------- | -------------------------------------------------------------------- |
+| `Converters.String`  | `'string'`  | String values                                                        |
+| `Converters.Number`  | `'number'`  | Numeric values (integers and floats)                                 |
+| `Converters.Integer` | `'integer'` | Integer values only                                                  |
+| `Converters.Float`   | `'float'`   | Float values only                                                    |
+| `Converters.Boolean` | `'boolean'` | Boolean values (`true`/`false`, `yes`/`no`, `on`/`off`, `1`/`0`)     |
+| `Converters.Bigint`  | `'bigint'`  | BigInt values for large integers                                     |
+| `Converters.Symbol`  | `'symbol'`  | Symbol values (creates symbols from string descriptions)             |
+| `Converters.Json`    | `'json'`    | JSON objects/arrays (safe parsing with fallback)                     |
+| `Converters.Array`   | `'array'`   | Comma-separated string arrays                                        |
+| `Converters.Url`     | `'url'`     | URL objects                                                          |
+| `Converters.Regexp`  | `'regexp'`  | Regular expressions (supports `/pattern/flags` syntax)               |
+| `Converters.Date`    | `'date'`    | Date objects (supports ISO strings and timestamps)                   |
+| `Converters.Time`    | `'time'`    | Time values (e.g. `"5s"`, `"30m"`, `"2h"` converted to milliseconds) |
 
 #### Custom Array Converters
 
 For more control over array parsing:
 
+> [!IMPORTANT]
+> Array converters validate that:
+>
+> 1. **Fallback must be an array** (if provided)
+> 2. **All fallback elements have consistent types** (no mixed types like `['string', 42, true]`)
+> 3. **Array converter `type` matches fallback element types** (if `type` is specified)
+
 ```ts
 class Config extends Envapter {
   // Basic array (comma-separated strings)
-  @Envapt('TAGS', { converter: 'array', fallback: [] })
+  @Envapt('TAGS', { converter: Converters.Array, fallback: [] })
   static readonly tags: string[];
 
   // Custom delimiter
@@ -249,7 +387,7 @@ class Config extends Envapter {
   declare readonly allowedMethods: string[];
 
   // Custom delimiter with type conversion
-  @Envapt('RATE_LIMITS', { converter: { delimiter: ',', type: 'number' }, fallback: [100] })
+  @Envapt('RATE_LIMITS', { converter: { delimiter: ',', type: Converters.Number }, fallback: [100] })
   declare readonly rateLimits: number[];
 
   @Envapt('FEATURE_FLAGS', { converter: { delimiter: ';', type: 'boolean' }, fallback: [false] })
@@ -257,10 +395,24 @@ class Config extends Envapter {
 }
 ```
 
+> [!WARNING]
+> These will throw runtime validation errors:
+>
+> ```ts
+> // ❌ Mixed types in fallback array
+> @Envapt('MIXED', { converter: Converters.Array, fallback: ['string', 42, true] })
+>
+> // ❌ Array converter type doesn't match fallback elements
+> @Envapt('NUMS', { converter: { delimiter: ',', type: Converters.Number }, fallback: ['not', 'numbers'] })
+>
+> // ❌ Non-array fallback with array converter
+> @Envapt('INVALID', { converter: Converters.Array, fallback: 'not-an-array' })
+> ```
+
 **ArrayConverter Interface:**
 
 - `delimiter: string` - The string used to split array elements
-- `type?: BuiltInConverter` - Optional type to convert each element to (excludes 'array', 'json', and 'regexp')
+- `type?: BuiltInConverter` - Optional type to convert each element to (excludes `Converters.Array`, `Converters.Json`, and `Converters.Regexp`)
 
 #### Custom Converters
 
@@ -304,7 +456,7 @@ class Config extends Envapter {
   static readonly optionalFeature: string | undefined;
 
   // Returns null if not found (no fallback provided)
-  @Envapt('MISSING_CONFIG', { converter: 'string' })
+  @Envapt('MISSING_CONFIG', { converter: Converters.String })
   static readonly missingConfig: string | null;
 
   // Uses fallback if not found
@@ -319,19 +471,92 @@ class Config extends Envapter {
 
 ### Functional API
 
+For functional-style environment variable on primitive types:
+
 ```ts
-import { Envapter } from 'envapt';
+import { Envapter, Converters } from 'envapt';
 
-// Type-specific getters
+// Basic type-specific getters
 const str = Envapter.get('STRING_VAR', 'default');
 const num = Envapter.getNumber('NUMBER_VAR', 42);
 const bool = Envapter.getBoolean('BOOLEAN_VAR', false);
+const bigint = Envapter.getBigInt('BIGINT_VAR', 100n);
+const symbol = Envapter.getSymbol('SYMBOL_VAR', Symbol('default'));
 
-// Instance methods (same API)
+// Advanced converter methods
+const jsonData = Envapter.getUsing('CONFIG_JSON', Converters.Json);
+const urlArray = Envapter.getUsing('API_URLS', { delimiter: ',', type: Converters.Url });
+const customData = Envapter.getWith('RAW_DATA', (raw) => raw?.split('|').map((s) => s.trim()));
+
+// Instance methods (same API available)
 const envapter = new Envapter();
 const value = envapter.get('VAR', 'default');
+const processed = envapter.getUsing('DATA', Converters.Array);
 ```
 
+For functional-style environment variable access with converters:
+
+```ts
+import { Envapter, Converters } from 'envapt';
+
+// Use built-in converters directly
+const config = Envapter.getUsing('API_CONFIG', Converters.Json, { default: 'value' });
+const urls = Envapter.getUsing('SERVICE_URLS', { delimiter: '|', type: Converters.Url });
+const typedConfig = Envapter.getUsing<{ host: string; port: number; ssl: boolean }>('DATABASE_CONFIG', Converters.Json);
+// typedConfig is now typed as { host: string; port: number; ssl: boolean } instead of JsonValue | undefined
+
+// Use custom converter functions
+const processedData = Envapter.getWith(
+  'RAW_DATA',
+  (raw, fallback) => {
+    if (!raw) return fallback ?? [];
+    return raw.split(',').map((item) => ({ name: item.trim(), enabled: true }));
+  },
+  []
+);
+
+// Instance methods work the same way
+const envapter = new Envapter();
+const result = envapter.getUsing('DATABASE_CONFIG', Converters.Json);
+```
+
+> [!TIP]
+> **Type Override with `getUsing`**
+>
+> You can explicitly specify the return type for `getUsing` when TypeScript's inference isn't specific enough (especially useful with `Converters.Json`):
+>
+> ```ts
+> // Default behavior
+> const config = Envapter.getUsing('CONFIG', Converters.Json); // type: JsonValue | undefined (undefined because no fallback)
+>
+> // Override with specific interface
+> interface DatabaseConfig {
+>   host: string;
+>   port: number;
+>   ssl: boolean;
+> }
+> const dbConfig = Envapter.getUsing<DatabaseConfig>('DB_CONFIG', Converters.Json);
+> // dbConfig is now properly typed as DatabaseConfig
+> ```
+>
+> _Make sure the fallback value matches the expected type, if you use a fallback. Otherwise you'll see a TypeScript error._\
+> _This does NOT validate the type at runtime. You'll need to handle that yourself._
+
+### Converter Type Quick Reference
+
+| **Use Case**            | **Converter Type**        | **Example**                                               |
+| ----------------------- | ------------------------- | --------------------------------------------------------- |
+| **Type coercion**       | Primitive constructors    | `converter: String`                                       |
+| **Strict validation**   | Built-in converters       | `converter: Converters.String`                            |
+| **Array parsing**       | Built-in Array converters | `converter: { delimiter: ',', type?: Converters.String }` |
+| **Complex transforms**  | Custom function           | `converter: (raw, fallback) => ...`                       |
+| **Functional built-in** | `getUsing()` method       | `Envapter.getUsing('VAR', Converters.Json)`               |
+| **Type override**       | `getUsing<T>()` method    | `Envapter.getUsing<MyType>('VAR', Converters.Json)`       |
+| **Functional custom**   | `getWith()` method        | `Envapter.getWith('VAR', (raw) => transform(raw))`        |
+
+> [!TIP]
+> **Use the `Converters` enum**. They look better. Start with built-in converters, use primitive constructors when you need coercion, and custom converters for complex transforms.
+
 ## Environment Detection
 
 Envapt automatically detects your environment from these variables (in order):
@@ -348,7 +573,7 @@ Supported values: `development`, `staging`, `production` (case-sensitive)
 import { Envapter, EnvaptEnvironment } from 'envapt';
 
 // Check current environment
-console.log(Envapter.environment); // Environment.Development
+console.log(Envapter.environment); // Environment.Development (default)
 console.log(Envapter.isProduction); // false
 console.log(Envapter.isDevelopment); // true
 console.log(Envapter.isStaging); // false
@@ -358,6 +583,8 @@ Envapter.environment = EnvaptEnvironment.Production;
 Envapter.environment = 'staging'; // string also works
 ```
 
+## Configuration
+
 ### Multiple .env Files
 
 ```ts
@@ -373,6 +600,29 @@ Envapter.envPaths = resolve(__dirname, '.env.production');
 // Or just don't set a path for it to default to .env at the root of your project
 ```
 
+### Dotenv Configuration
+
+Envapt allows you to customize dotenv behavior by setting configuration options:
+
+```ts
+import { Envapter } from 'envapt';
+
+// Set dotenv configuration options
+Envapter.dotenvConfig = {
+  encoding: 'latin1', // File encoding (default: 'utf8')
+  debug: true, // Enable debug logging
+  override: true, // Override existing environment variables
+  quiet: false, // Suppress non-error output (default: true)
+  DOTENV_KEY: 'key...' // Decryption key for .env.vault files
+};
+
+// Get current configuration
+console.log(Envapter.dotenvConfig);
+```
+
+> [!NOTE]
+> The `path` and `processEnv` options are managed internally by Envapter and cannot be set via `dotenvConfig`.
+
 ## Template Variables
 
 Envapt supports variable interpolation with `${VARIABLE}` syntax:
@@ -396,19 +646,79 @@ CIRCULAR_B=${CIRCULAR_A}
 
 Circular references are detected and preserved as-is rather than causing infinite loops.
 
+## Error Handling
+
+Envapt provides detailed error codes for better debugging and error handling:
+
+```ts
+import { EnvaptError, EnvaptErrorCodes } from 'envapt';
+
+try {
+  // This will throw an error for invalid configuration
+  Envapter.dotenvConfig = { path: '.env.custom' };
+} catch (error) {
+  if (error instanceof EnvaptError) {
+    console.log('Error code:', error.code);
+    console.log('Error message:', error.message);
+
+    // Handle specific error types
+    switch (error.code) {
+      case EnvaptErrorCodes.InvalidUserDefinedConfig:
+        console.log('Invalid configuration provided');
+        break;
+      case EnvaptErrorCodes.EnvFileNotFound:
+        console.log('Environment file not found');
+        break;
+      default:
+        console.warn('Unhandled error code:', error.code);
+        break;
+    }
+  }
+}
+```
+
+### Error Code Reference
+
+#### 🔧 Fallback Errors (1xx)
+
+| **Error Code**                           | **Description**                                           |
+| ---------------------------------------- | --------------------------------------------------------- |
+| `InvalidFallback` (101)                  | Invalid fallback value provided                           |
+| `InvalidFallbackType` (102)              | Fallback value type doesn't match expected converter type |
+| `ArrayFallbackElementTypeMismatch` (103) | Array fallback contains elements of wrong type            |
+| `FallbackConverterTypeMismatch` (104)    | Fallback type doesn't match the specified converter       |
+
+#### 🧪 Converter Errors (2xx)
+
+| **Error Code**                    | **Description**                                |
+| --------------------------------- | ---------------------------------------------- |
+| `InvalidArrayConverterType` (201) | Invalid array converter configuration provided |
+| `InvalidBuiltInConverter` (202)   | Invalid built-in converter specified           |
+| `InvalidCustomConverter` (203)    | Custom converter function is invalid           |
+| `InvalidConverterType` (204)      | Converter type is not recognized               |
+| `PrimitiveCoercionFailed` (205)   | Primitive type coercion failed                 |
+
+#### 📂 Environment File & Config Errors (3xx)
+
+| **Error Code**                   | **Description**                                |
+| -------------------------------- | ---------------------------------------------- |
+| `MissingDelimiter` (301)         | Delimiter is missing in array converter config |
+| `InvalidUserDefinedConfig` (302) | Invalid user-defined configuration provided    |
+| `EnvFilesNotFound` (303)         | Specified environment file doesn't exist       |
+
 ## Advanced Examples
 
 ### Complex Configuration
 
 ```ts
-import { Envapt, Envapter } from 'envapt';
+import { Envapt, Envapter, Converters } from 'envapt';
 
 class AppConfig extends Envapter {
   // Global settings (static)
   @Envapt('PORT', 3000)
   static readonly port: number;
 
-  @Envapt('REQUEST_TIMEOUT', { converter: 'time', fallback: 10000 })
+  @Envapt('REQUEST_TIMEOUT', { converter: Converters.Time, fallback: 10000 })
   static readonly requestTimeout: number; // "5s" -> 5000ms (if env is set to "5s")
 
   @Envapt('FEATURE_FLAGS', {
@@ -424,7 +734,7 @@ class AppConfig extends Envapter {
   @Envapt('DB_URL', 'sqlite://memory')
   declare readonly databaseUrl: string;
 
-  @Envapt('CACHE_TTL', { converter: 'time', fallback: 3600000 })
+  @Envapt('CACHE_TTL', { converter: Converters.Time, fallback: 3600000 })
   declare readonly cacheTtl: number; // "1h" -> 3600000ms
 
   @Envapt('REDIS_URLS', {
@@ -440,3 +750,20 @@ class AppConfig extends Envapter {
   }
 }
 ```
+
+---
+
+<hr/>
+
+<p align="center">
+  <a href="https://github.com/materwelondhruv/envapt">⭐️ Star it on GitHub</a> •
+  <a href="https://github.com/materwelondhruv/envapt/issues">🐛 Report a bug</a> • 
+  <a href="https://github.com/materwelondhruv/envapt/issues/new?labels=enhancement">💡 Request a feature</a>
+</p>
+
+<p align="center">
+  <sub>
+    Built by <a href="https://github.com/materwelondhruv">@materwelonDhruv</a> • Licensed under 
+    <a href="LICENSE">Apache 2.0</a>
+  </sub>
+</p>