envapt 1.1.0 → 2.0.0

package/dist/index.cjs

@@ -1,22 +1,31 @@
 'use strict';
 
 var dotenv = require('dotenv');
+var fs = require('fs');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
 
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // src/Error.ts
-var EnvaptErrorCodes = {
-  InvalidFallback: 617404,
-  MissingDelimiter: 967308,
-  InvalidArrayConverterType: 193159,
-  InvalidBuiltInConverter: 337271,
-  InvalidConverterType: 453217,
-  InvalidCustomConverter: 789432
-};
-var ReversedEnvaptErrorCodes = Object.fromEntries(
-  Object.entries(EnvaptErrorCodes).map(([key, value]) => [value, key])
-);
+var EnvaptErrorCodes = /* @__PURE__ */ ((EnvaptErrorCodes2) => {
+  EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidFallback"] = 101] = "InvalidFallback";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidFallbackType"] = 102] = "InvalidFallbackType";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["ArrayFallbackElementTypeMismatch"] = 103] = "ArrayFallbackElementTypeMismatch";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["FallbackConverterTypeMismatch"] = 104] = "FallbackConverterTypeMismatch";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidArrayConverterType"] = 201] = "InvalidArrayConverterType";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidBuiltInConverter"] = 202] = "InvalidBuiltInConverter";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidCustomConverter"] = 203] = "InvalidCustomConverter";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidConverterType"] = 204] = "InvalidConverterType";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["PrimitiveCoercionFailed"] = 205] = "PrimitiveCoercionFailed";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["MissingDelimiter"] = 301] = "MissingDelimiter";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["InvalidUserDefinedConfig"] = 302] = "InvalidUserDefinedConfig";
+  EnvaptErrorCodes2[EnvaptErrorCodes2["EnvFilesNotFound"] = 303] = "EnvFilesNotFound";
+  return EnvaptErrorCodes2;
+})(EnvaptErrorCodes || {});
 var EnvaptError = class _EnvaptError extends Error {
   static {
     __name(this, "EnvaptError");
@@ -24,7 +33,7 @@ var EnvaptError = class _EnvaptError extends Error {
   code;
   constructor(code, message) {
     super(message);
-    this.name = `${ReversedEnvaptErrorCodes[code]} [${code}]`;
+    this.name = `EnvaptError [${code}]`;
     this.code = code;
     Error.captureStackTrace(this, _EnvaptError);
   }
@@ -46,6 +55,28 @@ var ListOfBuiltInConverters = [
   "date",
   "time"
 ];
+var BuiltInConverterTypeCheckers = {
+  string: /* @__PURE__ */ __name((value) => typeof value === "string", "string"),
+  number: /* @__PURE__ */ __name((value) => typeof value === "number", "number"),
+  boolean: /* @__PURE__ */ __name((value) => typeof value === "boolean", "boolean"),
+  bigint: /* @__PURE__ */ __name((value) => typeof value === "bigint", "bigint"),
+  symbol: /* @__PURE__ */ __name((value) => typeof value === "symbol", "symbol"),
+  integer: /* @__PURE__ */ __name((value) => typeof value === "number" && Number.isInteger(value), "integer"),
+  float: /* @__PURE__ */ __name((value) => typeof value === "number", "float"),
+  json: /* @__PURE__ */ __name((value) => {
+    try {
+      JSON.parse(JSON.stringify(value));
+      return true;
+    } catch {
+      return false;
+    }
+  }, "json"),
+  array: /* @__PURE__ */ __name((value) => Array.isArray(value), "array"),
+  url: /* @__PURE__ */ __name((value) => value instanceof URL, "url"),
+  regexp: /* @__PURE__ */ __name((value) => value instanceof RegExp, "regexp"),
+  date: /* @__PURE__ */ __name((value) => value instanceof Date, "date"),
+  time: /* @__PURE__ */ __name((value) => typeof value === "number", "time")
+};
 
 // src/Validators.ts
 var Validator = class {
@@ -77,16 +108,10 @@ var Validator = class {
     );
     return validTypes.includes(value);
   }
-  /**
-   * Check if a value is a valid custom converter function
-   */
-  static isValidConverterFunction(converter) {
-    return typeof converter === "function";
-  }
   static customConvertor(converter) {
     if (typeof converter !== "function") {
       throw new EnvaptError(
-        EnvaptErrorCodes.InvalidCustomConverter,
+        203 /* InvalidCustomConverter */,
         `Custom converter must be a function, got ${typeof converter}.`
       );
     }
@@ -96,11 +121,11 @@ var Validator = class {
    */
   static arrayConverter(value) {
     if (!this.isArrayConverter(value)) {
-      throw new EnvaptError(EnvaptErrorCodes.MissingDelimiter, "Must have delimiter property");
+      throw new EnvaptError(301 /* MissingDelimiter */, "Must have delimiter property");
     }
     if (value.type !== void 0 && !this.isValidArrayConverterType(value.type)) {
       throw new EnvaptError(
-        EnvaptErrorCodes.InvalidArrayConverterType,
+        201 /* InvalidArrayConverterType */,
         `"${value.type}" is not a valid converter type`
       );
     }
@@ -110,15 +135,201 @@ var Validator = class {
    */
   static builtInConverter(value) {
     if (typeof value !== "string") {
-      throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Expected string, got ${typeof value}`);
+      throw new EnvaptError(204 /* InvalidConverterType */, `Expected string, got ${typeof value}`);
     }
     if (!ListOfBuiltInConverters.includes(value)) {
       throw new EnvaptError(
-        EnvaptErrorCodes.InvalidBuiltInConverter,
+        202 /* InvalidBuiltInConverter */,
         `"${value}" is not a valid converter type. Valid types are: ${ListOfBuiltInConverters.join(",")}`
       );
     }
   }
+  /**
+   * Validate that fallback type matches the converter's return type for built-in converters
+   */
+  static validateBuiltInConverterFallback(converter, fallback) {
+    const typeChecker = BuiltInConverterTypeCheckers[converter];
+    if (!typeChecker(fallback)) {
+      throw new EnvaptError(
+        104 /* FallbackConverterTypeMismatch */,
+        `Fallback type does not match converter "${converter}". Expected ${converter} compatible type.`
+      );
+    }
+  }
+  /**
+   * Validate that all elements in an array fallback have consistent types
+   */
+  static validateArrayFallbackElementTypes(fallback) {
+    if (fallback.length === 0) return;
+    const firstElementType = typeof fallback[0];
+    const hasInconsistentTypes = fallback.some((element, index) => {
+      if (index === 0) return false;
+      return typeof element !== firstElementType;
+    });
+    if (hasInconsistentTypes) {
+      throw new EnvaptError(
+        103 /* ArrayFallbackElementTypeMismatch */,
+        `All elements in array fallback must have the same type. Found mixed types.`
+      );
+    }
+  }
+  /**
+   * Validate that array converter type matches fallback element types
+   */
+  static validateArrayConverterElementTypeMatch(converterType, fallback) {
+    if (fallback.length === 0) return;
+    const firstElement = fallback[0];
+    const typeChecker = BuiltInConverterTypeCheckers[converterType];
+    if (!typeChecker(firstElement)) {
+      throw new EnvaptError(
+        103 /* ArrayFallbackElementTypeMismatch */,
+        `Array converter type "${converterType}" does not match fallback element type. Expected ${converterType} compatible elements.`
+      );
+    }
+  }
+  /**
+   * Check if a value is a primitive constructor
+   */
+  static isPrimitiveConstructor(value) {
+    return value === String || value === Number || value === Boolean || value === BigInt || value === Symbol;
+  }
+  /**
+   * Safely coerce a fallback value using a primitive constructor
+   */
+  static coercePrimitiveFallback(converter, fallback) {
+    if (this.isCorrectPrimitiveType(converter, fallback)) return fallback;
+    return this.performPrimitiveCoercion(converter, fallback);
+  }
+  /**
+   * Check if fallback is already the correct primitive type
+   */
+  static isCorrectPrimitiveType(converter, fallback) {
+    if (converter === String && typeof fallback === "string") return true;
+    if (converter === Number && typeof fallback === "number") return true;
+    if (converter === Boolean && typeof fallback === "boolean") return true;
+    if (converter === BigInt && typeof fallback === "bigint") return true;
+    if (converter === Symbol && typeof fallback === "symbol") return true;
+    return false;
+  }
+  /**
+   * Perform the actual primitive coercion
+   */
+  static performPrimitiveCoercion(converter, fallback) {
+    try {
+      if (converter === String) return String(fallback);
+      if (converter === Number) return Number(fallback);
+      if (converter === Boolean) return Boolean(fallback);
+      if (converter === BigInt) return BigInt(fallback);
+      if (converter === Symbol) return Symbol(fallback);
+    } catch (error) {
+      throw new EnvaptError(
+        205 /* PrimitiveCoercionFailed */,
+        `Failed to coerce fallback value using ${converter.name}: ${error.message}`
+      );
+    }
+    throw new EnvaptError(205 /* PrimitiveCoercionFailed */, `Unknown primitive converter: ${converter.name}`);
+  }
+  /**
+   * Make sure the user hasn't provided prohibited options in their dotenv config
+   */
+  static validateDotenvConfig(config2) {
+    if ("path" in config2 || "processEnv" in config2) {
+      throw new EnvaptError(
+        302 /* InvalidUserDefinedConfig */,
+        'Custom dotenvConfig should not include "path" or "processEnv" options. Those are managed by Envapter.'
+      );
+    }
+    const validKeys = /* @__PURE__ */ new Set(["encoding", "quiet", "debug", "override", "DOTENV_KEY"]);
+    const invalidKeys = Object.keys(config2).filter((key) => !validKeys.has(key));
+    if (invalidKeys.length > 0) {
+      throw new EnvaptError(
+        302 /* InvalidUserDefinedConfig */,
+        `Invalid dotenvConfig options: ${invalidKeys.join(", ")}. Allowed options: ${Array.from(validKeys).join(", ")}`
+      );
+    }
+    return true;
+  }
+  /**
+   * Check if each provided path resolves to an env file by trying to access it
+   */
+  static validateEnvFilesExist(paths) {
+    const missing = paths.filter((p) => {
+      try {
+        fs__default.default.accessSync(p, fs__default.default.constants.F_OK);
+        return false;
+      } catch {
+        return true;
+      }
+    });
+    if (missing.length > 0) {
+      throw new EnvaptError(
+        303 /* EnvFilesNotFound */,
+        `Environment file not found at path: ${missing.join(", ")}`
+      );
+    }
+  }
+};
+
+// src/core/EnvapterBase.ts
+var EnvaptCache = /* @__PURE__ */ new Map();
+var EnvapterBase = class _EnvapterBase {
+  static {
+    __name(this, "EnvapterBase");
+  }
+  static _envPaths = [".env"];
+  // default path
+  static _userDefinedDotenvConfig = { quiet: true };
+  /**
+   * Set custom .env file paths. Accepts either a single path or array of paths.
+   * Setting new paths clears the cache and reloads environment variables.
+   */
+  static set envPaths(paths) {
+    const newPaths = Array.isArray(paths) ? paths : [paths];
+    Validator.validateEnvFilesExist(newPaths);
+    this._envPaths = newPaths;
+    this.refreshCache();
+  }
+  /**
+   * Get currently configured .env file paths
+   */
+  static get envPaths() {
+    return this._envPaths;
+  }
+  /**
+   * Set custom dotenv configuration options.
+   */
+  static set dotenvConfig(config2) {
+    Validator.validateDotenvConfig(config2);
+    this._userDefinedDotenvConfig = config2;
+    this.refreshCache();
+  }
+  /**
+   * Get current dotenv configuration options
+   */
+  static get dotenvConfig() {
+    return this._userDefinedDotenvConfig;
+  }
+  static refreshCache() {
+    EnvaptCache.clear();
+    void this.config;
+  }
+  static get config() {
+    if (EnvaptCache.size === 0) {
+      const isolatedEnv = { ...process.env };
+      try {
+        dotenv.config({ path: this._envPaths, processEnv: isolatedEnv, ...this._userDefinedDotenvConfig });
+      } catch {
+      }
+      for (const [key, value] of Object.entries(isolatedEnv)) EnvaptCache.set(key, value);
+    }
+    return EnvaptCache;
+  }
+  /**
+   * Get raw environment variable value without parsing or conversion.
+   */
+  getRaw(key) {
+    return _EnvapterBase.config.get(key);
+  }
 };
 
 // src/BuiltInConverters.ts
@@ -127,15 +338,13 @@ var BuiltInConverters = class _BuiltInConverters {
     __name(this, "BuiltInConverters");
   }
   static string(raw, fallback) {
-    return raw ?? fallback;
+    return String(raw) || fallback;
   }
   static number(raw, fallback) {
-    if (raw === void 0) return fallback;
     const parsed = Number(raw);
     return Number.isNaN(parsed) ? fallback : parsed;
   }
   static boolean(raw, fallback) {
-    if (raw === void 0) return fallback;
     const lower = raw.toLowerCase().trim();
     const truthyValues = ["1", "yes", "true", "on"];
     const falsyValues = ["0", "no", "false", "off"];
@@ -144,7 +353,6 @@ var BuiltInConverters = class _BuiltInConverters {
     return fallback;
   }
   static bigint(raw, fallback) {
-    if (raw === void 0) return fallback;
     try {
       return BigInt(raw);
     } catch {
@@ -155,17 +363,14 @@ var BuiltInConverters = class _BuiltInConverters {
     return raw ? Symbol(raw) : fallback;
   }
   static integer(raw, fallback) {
-    if (raw === void 0) return fallback;
     const parsed = parseInt(raw, 10);
     return Number.isNaN(parsed) ? fallback : parsed;
   }
   static float(raw, fallback) {
-    if (raw === void 0) return fallback;
     const parsed = parseFloat(raw);
     return Number.isNaN(parsed) ? fallback : parsed;
   }
   static json(raw, fallback) {
-    if (raw === void 0) return fallback;
     try {
       return JSON.parse(raw);
     } catch {
@@ -173,12 +378,11 @@ var BuiltInConverters = class _BuiltInConverters {
     }
   }
   static array(raw, fallback, delimiter = ",") {
-    if (raw === void 0) return fallback;
     if (raw.trim() === "") return [];
-    return raw.split(delimiter).map((item) => item.trim()).filter((item) => item.length > 0);
+    const arr = raw.split(delimiter).map((item) => item.trim()).filter(Boolean);
+    return arr.length ? arr : fallback;
   }
   static url(raw, fallback) {
-    if (raw === void 0) return fallback;
     try {
       return new URL(raw);
     } catch {
@@ -186,7 +390,6 @@ var BuiltInConverters = class _BuiltInConverters {
     }
   }
   static regexp(raw, fallback) {
-    if (raw === void 0) return fallback;
     try {
       const match = raw.match(/^\/(.+)\/([gimsuvy]*)$/);
       if (match) return new RegExp(match[1], match[2]);
@@ -196,7 +399,6 @@ var BuiltInConverters = class _BuiltInConverters {
     }
   }
   static date(raw, fallback) {
-    if (raw === void 0) return fallback;
     if (/^\d+$/.test(raw)) {
       const timestamp = parseInt(raw, 10);
       const parsed2 = new Date(timestamp);
@@ -206,13 +408,13 @@ var BuiltInConverters = class _BuiltInConverters {
     return Number.isNaN(parsed.getTime()) ? fallback : parsed;
   }
   static time(raw, fallback) {
-    if (raw === void 0) return fallback;
     const match = raw.match(/^(\d+(?:\.\d+)?)(ms|s|m|h)?$/u);
     if (!match) return fallback;
-    const [, numStr, unit = "ms"] = match;
+    const [, numStr, capturedUnit] = match;
     if (!numStr) return fallback;
     const value = Number.parseFloat(numStr);
     if (Number.isNaN(value)) return fallback;
+    const unit = capturedUnit ?? "ms";
     const SECONDS_TO_MS = 1e3;
     const SECONDS_PER_MINUTE = 60;
     const MINUTES_PER_HOUR = 60;
@@ -221,24 +423,18 @@ var BuiltInConverters = class _BuiltInConverters {
     if (unit === "ms") return value;
     if (unit === "s") return value * SECONDS_TO_MS;
     if (unit === "m") return value * MINUTES_TO_MS;
-    if (unit === "h") return value * HOURS_TO_MS;
-    return fallback;
+    return value * HOURS_TO_MS;
   }
   /**
    * Process array with custom converter config
    */
   static processArrayConverter(raw, fallback, config2) {
-    if (raw === void 0) {
-      if (Array.isArray(fallback)) return fallback;
-      throw new EnvaptError(
-        EnvaptErrorCodes.InvalidFallback,
-        `ArrayConverter requires that the fallback be an array, got ${typeof fallback}`
-      );
-    }
     if (raw.trim() === "") return [];
     const items = raw.split(config2.delimiter).map((item) => String(item).trim()).filter(Boolean);
-    if (!config2.type) return items;
-    const converter = _BuiltInConverters.getConverter(config2.type);
+    if (!items.length) return fallback ? fallback : void 0;
+    const type = config2.type;
+    if (!type) return items;
+    const converter = _BuiltInConverters.getConverter(type);
     return items.map((item) => {
       const converted = converter(item, void 0);
       return converted ?? item;
@@ -263,11 +459,7 @@ var BuiltInConverters = class _BuiltInConverters {
       date: _BuiltInConverters.date,
       time: _BuiltInConverters.time
     };
-    const converter = converters[type];
-    if (!Validator.isValidConverterFunction(converter)) {
-      throw new EnvaptError(EnvaptErrorCodes.InvalidBuiltInConverter, `Unknown built-in converter: ${type}`);
-    }
-    return converter;
+    return converters[type];
   }
 };
 
@@ -280,12 +472,14 @@ var Parser = class {
     __name(this, "Parser");
   }
   TEMPLATE_REGEX = /\${\w*}/g;
+  /**
+   * Resolve template variables in a string while handling circular references and missing variables
+   * @internal
+   */
   resolveTemplate(key, value, stack = /* @__PURE__ */ new Set()) {
-    if (stack.has(key)) return value;
     stack.add(key);
     const out = value.replace(this.TEMPLATE_REGEX, (template) => {
       const variable = template.slice(2, -1);
-      if (!variable) return template;
       if (stack.has(variable)) return template;
       const raw = this.envService.getRaw(variable);
       if (!raw || raw === "") return template;
@@ -297,27 +491,71 @@ var Parser = class {
     stack.delete(key);
     return out;
   }
-  convertValue(key, fallback, converter, hasFallback = true) {
-    let resolvedConverter = this.resolveConverter(converter, fallback);
-    if (resolvedConverter === Number) resolvedConverter = "number";
-    else if (resolvedConverter === Boolean) resolvedConverter = "boolean";
-    else if (resolvedConverter === String) resolvedConverter = "string";
-    else if (resolvedConverter === BigInt) resolvedConverter = "bigint";
-    else if (resolvedConverter === Symbol) resolvedConverter = "symbol";
+  convertValue(key, fallback, converter, hasFallback) {
+    const resolvedConverter = this.resolveConverter(converter, fallback);
+    const processedFallback = this.processFallbackForConverter(resolvedConverter, fallback);
     if (Validator.isArrayConverter(resolvedConverter)) {
-      Validator.arrayConverter(resolvedConverter);
-      const parsed = this.envService.get(key, void 0);
-      if (parsed === void 0) return hasFallback ? fallback : null;
-      return BuiltInConverters.processArrayConverter(parsed, fallback, resolvedConverter);
+      return this.processArrayConverter(key, processedFallback, resolvedConverter, hasFallback);
+    }
+    if (Validator.isPrimitiveConstructor(resolvedConverter)) {
+      const stringConverter = this.convertPrimitiveToString(resolvedConverter);
+      return this.processBuiltInConverter(key, processedFallback, stringConverter, hasFallback, true);
     }
     if (Validator.isBuiltInConverter(resolvedConverter)) {
-      Validator.builtInConverter(resolvedConverter);
-      const parsed = this.envService.get(key, void 0);
-      if (parsed === void 0) return hasFallback ? fallback : null;
-      const converterFn = BuiltInConverters.getConverter(resolvedConverter);
-      const result = converterFn(parsed, fallback);
-      return result;
+      return this.processBuiltInConverter(key, processedFallback, resolvedConverter, hasFallback, false);
+    }
+    return this.processCustomConverter(key, processedFallback, resolvedConverter, hasFallback);
+  }
+  processFallbackForConverter(converter, fallback) {
+    if (Validator.isPrimitiveConstructor(converter) && fallback !== void 0) {
+      return Validator.coercePrimitiveFallback(converter, fallback);
+    }
+    return fallback;
+  }
+  convertPrimitiveToString(primitiveConstructor) {
+    if (primitiveConstructor === String) return "string";
+    if (primitiveConstructor === Number) return "number";
+    if (primitiveConstructor === Boolean) return "boolean";
+    if (primitiveConstructor === BigInt) return "bigint";
+    if (primitiveConstructor === Symbol) return "symbol";
+    throw new EnvaptError(204 /* InvalidConverterType */, `Unknown primitive constructor`);
+  }
+  processBuiltInConverter(key, fallback, resolvedConverter, hasFallback, wasOriginallyConstructor) {
+    Validator.builtInConverter(resolvedConverter);
+    if (hasFallback && fallback !== void 0 && !wasOriginallyConstructor) {
+      Validator.validateBuiltInConverterFallback(resolvedConverter, fallback);
+      if (resolvedConverter === "array" && Array.isArray(fallback)) {
+        Validator.validateArrayFallbackElementTypes(fallback);
+      }
     }
+    const parsed = this.envService.get(key, void 0);
+    if (parsed === void 0) return hasFallback ? fallback : null;
+    const converterFn = BuiltInConverters.getConverter(resolvedConverter);
+    const result = converterFn(parsed, fallback);
+    if (result === void 0 && !hasFallback) return null;
+    return result;
+  }
+  processArrayConverter(key, fallback, resolvedConverter, hasFallback) {
+    Validator.arrayConverter(resolvedConverter);
+    if (hasFallback && fallback !== void 0 && !Array.isArray(fallback)) {
+      throw new EnvaptError(
+        101 /* InvalidFallback */,
+        `ArrayConverter requires that the fallback be an array, got ${typeof fallback}`
+      );
+    }
+    if (hasFallback && Array.isArray(fallback)) {
+      Validator.validateArrayFallbackElementTypes(fallback);
+      if (resolvedConverter.type) {
+        Validator.validateArrayConverterElementTypeMatch(resolvedConverter.type, fallback);
+      }
+    }
+    const parsed = this.envService.get(key, void 0);
+    if (parsed === void 0) return hasFallback ? fallback : null;
+    const result = BuiltInConverters.processArrayConverter(parsed, fallback, resolvedConverter);
+    if (result === void 0 && !hasFallback) return null;
+    return result;
+  }
+  processCustomConverter(key, fallback, resolvedConverter, hasFallback) {
     Validator.customConvertor(resolvedConverter);
     const raw = this.envService.get(key, void 0);
     if (raw === void 0) return hasFallback ? fallback : null;
@@ -334,253 +572,230 @@ var Parser = class {
   }
 };
 
-// src/Envapter.ts
-var EnvaptCache = /* @__PURE__ */ new Map();
+// src/core/EnvironmentMethods.ts
 var Environment = /* @__PURE__ */ ((Environment2) => {
   Environment2[Environment2["Development"] = 0] = "Development";
   Environment2[Environment2["Staging"] = 1] = "Staging";
   Environment2[Environment2["Production"] = 2] = "Production";
   return Environment2;
 })(Environment || {});
-var Envapter = class _Envapter {
+var EnvironmentMethods = class _EnvironmentMethods extends EnvapterBase {
   static {
-    __name(this, "Envapter");
+    __name(this, "EnvironmentMethods");
   }
-  static parser = new Parser(new _Envapter());
-  static _envPaths = [".env"];
-  // default path
-  // Environment handling
-  static internalEnvironment = this.determineEnvironment(
-    this.get("ENVIRONMENT", this.get("ENV", this.get("NODE_ENV", "development")))
-  );
-  /**
-   * Set custom .env file paths. Accepts either a single path or array of paths.
-   * Setting new paths clears the cache and reloads environment variables.
-   *
-   * @param paths - Single file path or array of file paths to load
-   *
-   * @example
-   * ```ts
-   * // Single file
-   * Envapter.envPaths = '.env.production';
-   *
-   * // Multiple files (loaded in order)
-   * Envapter.envPaths = ['.env', '.env.local', '.env.production'];
-   * ```
-   */
-  static set envPaths(paths) {
-    this._envPaths = Array.isArray(paths) ? paths : [paths];
-    EnvaptCache.clear();
-    void this.config;
-    this.internalEnvironment = this.determineEnvironment(
-      this.get("ENVIRONMENT", this.get("ENV", this.get("NODE_ENV", "development")))
-    );
+  static _environment;
+  static determineEnvironment(env) {
+    const environment = env ?? this.getRawValue("ENVIRONMENT", this.getRawValue("ENV", this.getRawValue("NODE_ENV", "development")));
+    if (typeof environment === "string") {
+      this._environment = environment.toLowerCase() === "production" ? 2 /* Production */ : environment === "staging" ? 1 /* Staging */ : 0 /* Development */;
+    } else {
+      this._environment = environment;
+    }
+  }
+  static getRawValue(key, fallback) {
+    return this.config.get(key) || fallback;
   }
   /**
-   * Get currently configured .env file paths
-   * @returns Array of file paths being loaded
+   * Get the current application environment
    */
-  static get envPaths() {
-    return this._envPaths;
-  }
-  static determineEnvironment(env) {
-    if (typeof env === "string") {
-      switch (env.toLowerCase()) {
-        case "production":
-          return 2 /* Production */;
-        case "staging":
-          return 1 /* Staging */;
-        default:
-          return 0 /* Development */;
-      }
+  static get environment() {
+    if (this._environment === void 0) {
+      this.determineEnvironment();
     }
-    return env;
+    return this._environment;
   }
   /**
    * Set the application environment. Accepts either Environment enum or string value.
-   *
-   * @param env - Environment value ('development', 'staging', 'production') or Environment enum
-   *
-   * @example
-   * ```ts
-   * Envapter.environment = Environment.Production;
-   * Envapter.environment = 'staging';
-   * ```
    */
   static set environment(env) {
-    this.internalEnvironment = this.determineEnvironment(env);
+    this.determineEnvironment(env);
   }
   /**
-   * Get the current application environment
-   * @returns Current environment enum value
+   * @see {@link EnvironmentMethods.environment}
    */
-  static get environment() {
-    return this.internalEnvironment;
+  get environment() {
+    return _EnvironmentMethods.environment;
+  }
+  /**
+   * @see {@link EnvironmentMethods.environment}
+   */
+  set environment(env) {
+    _EnvironmentMethods.determineEnvironment(env);
   }
   /**
    * Check if the current environment is production
-   * @returns true if environment is production
    */
   static get isProduction() {
-    return this.internalEnvironment === 2 /* Production */;
+    return this.environment === 2 /* Production */;
+  }
+  /**
+   * @see {@link EnvironmentMethods.isProduction}
+   */
+  get isProduction() {
+    return _EnvironmentMethods.environment === 2 /* Production */;
   }
   /**
    * Check if the current environment is staging
-   * @returns true if environment is staging
    */
   static get isStaging() {
-    return this.internalEnvironment === 1 /* Staging */;
+    return this.environment === 1 /* Staging */;
+  }
+  /**
+   * @see {@link EnvironmentMethods.isStaging}
+   */
+  get isStaging() {
+    return _EnvironmentMethods.environment === 1 /* Staging */;
   }
   /**
    * Check if the current environment is development
-   * @returns true if environment is development
    */
   static get isDevelopment() {
-    return this.internalEnvironment === 0 /* Development */;
+    return this.environment === 0 /* Development */;
   }
-  static get config() {
-    if (EnvaptCache.size === 0) {
-      const isolatedEnv = { ...process.env };
-      try {
-        dotenv.config({ path: this._envPaths, quiet: true, processEnv: isolatedEnv });
-      } catch {
-      }
-      for (const [key, value] of Object.entries(isolatedEnv)) EnvaptCache.set(key, value);
-    }
-    return EnvaptCache;
+  /**
+   * @see {@link EnvironmentMethods.isDevelopment}
+   */
+  get isDevelopment() {
+    return _EnvironmentMethods.environment === 0 /* Development */;
+  }
+  static refreshCache() {
+    super.refreshCache();
+    this._environment = void 0;
+  }
+};
+
+// src/core/PrimitiveMethods.ts
+var PrimitiveMethods = class _PrimitiveMethods extends EnvironmentMethods {
+  static {
+    __name(this, "PrimitiveMethods");
   }
-  static _get(key, type = 0 /* String */, def) {
+  static parser = new Parser(new _PrimitiveMethods());
+  static _get(key, type, def) {
     const rawVal = this.config.get(key);
     if (!rawVal) return def;
     const parsed = this.parser.resolveTemplate(key, String(rawVal));
-    switch (type) {
-      case 0 /* String */: {
-        return BuiltInConverters.string(parsed, def);
-      }
-      case 1 /* Number */: {
-        return BuiltInConverters.number(parsed, def);
-      }
-      case 2 /* Boolean */: {
-        return BuiltInConverters.boolean(parsed, def);
-      }
-      case 3 /* BigInt */: {
-        return BuiltInConverters.bigint(parsed, def);
-      }
-      case 4 /* Symbol */: {
-        return BuiltInConverters.symbol(parsed, def);
-      }
-      default: {
-        return BuiltInConverters.string(parsed, def);
-      }
-    }
+    let result;
+    if (type === 1 /* Number */) result = BuiltInConverters.number(parsed, def);
+    else if (type === 2 /* Boolean */) result = BuiltInConverters.boolean(parsed, def);
+    else if (type === 3 /* BigInt */) result = BuiltInConverters.bigint(parsed, def);
+    else if (type === 4 /* Symbol */) result = BuiltInConverters.symbol(parsed, def);
+    else result = BuiltInConverters.string(parsed, def);
+    return result;
   }
   /**
    * Get a string environment variable with optional fallback.
    * Supports template variable resolution using ${VAR} syntax.
-   *
-   * @param key - Environment variable name
-   * @param def - Default value if variable is not found
-   * @returns The environment variable value or default
-   *
-   * @example
-   * ```ts
-   * const apiUrl = Envapter.get('API_URL', 'http://localhost:3000');
-   * ```
    */
   static get(key, def) {
     return this._get(key, 0 /* String */, def);
   }
+  /**
+   * @see {@link PrimitiveMethods.get}
+   */
+  get(key, def) {
+    return _PrimitiveMethods._get(key, 0 /* String */, def);
+  }
   /**
    * Get a number environment variable with optional fallback.
    * Automatically converts string values to numbers.
-   *
-   * @param key - Environment variable name
-   * @param def - Default value if variable is not found or cannot be converted
-   * @returns The environment variable value as number or default
-   *
-   * @example
-   * ```ts
-   * const port = Envapter.getNumber('PORT', 3000);
-   * ```
    */
   static getNumber(key, def) {
     return this._get(key, 1 /* Number */, def);
   }
+  /**
+   * @see {@link PrimitiveMethods.getNumber}
+   */
+  getNumber(key, def) {
+    return _PrimitiveMethods._get(key, 1 /* Number */, def);
+  }
   /**
    * Get a boolean environment variable with optional fallback.
-   * Recognizes: `1`, `yes`, `true` as **true**; `0`, `no`, `false` as **false** (case-insensitive).
-   *
-   * @param key - Environment variable name
-   * @param def - Default value if variable is not found or cannot be converted
-   * @returns The environment variable value as boolean or default
-   *
-   * @example
-   * ```ts
-   * const isProduction = Envapter.getBoolean('IS_PRODUCTION', false);
-   * ```
+   * Recognizes: `1`, `yes`, `true`, 'on' as **true**; `0`, `no`, `false`, 'off' as **false** (case-insensitive).
    */
   static getBoolean(key, def) {
     return this._get(key, 2 /* Boolean */, def);
   }
+  /**
+   * @see {@link PrimitiveMethods.getBoolean}
+   */
+  getBoolean(key, def) {
+    return _PrimitiveMethods._get(key, 2 /* Boolean */, def);
+  }
   /**
    * Get a bigint environment variable with optional fallback.
    * Automatically converts string values to bigint.
-   *
-   * @param key - Environment variable name
-   * @param def - Default value if variable is not found or cannot be converted
-   * @returns The environment variable value as bigint or default
-   *
-   * @example
-   * ```ts
-   * const largeNumber = Envapter.getBigInt('LARGE_NUMBER', 123456789012345678901234567890n);
-   * ```
    */
   static getBigInt(key, def) {
     return this._get(key, 3 /* BigInt */, def);
   }
+  /**
+   * @see {@link PrimitiveMethods.getBigInt}
+   */
+  getBigInt(key, def) {
+    return _PrimitiveMethods._get(key, 3 /* BigInt */, def);
+  }
   /**
    * Get a symbol environment variable with optional fallback.
    * Creates a symbol from the string value.
-   *
-   * @param key - Environment variable name
-   * @param def - Default value if variable is not found
-   * @returns The environment variable value as symbol or default
-   *
-   * @example
-   * ```ts
-   * const uniqueKey = Envapter.getSymbol('UNIQUE_KEY', Symbol('default'));
-   * ```
    */
   static getSymbol(key, def) {
     return this._get(key, 4 /* Symbol */, def);
   }
-  get(key, def) {
-    return _Envapter._get(key, 0 /* String */, def);
+  /**
+   * @see {@link PrimitiveMethods.getSymbol}
+   */
+  getSymbol(key, def) {
+    return _PrimitiveMethods._get(key, 4 /* Symbol */, def);
   }
-  getNumber(key, def) {
-    return _Envapter._get(key, 1 /* Number */, def);
+};
+
+// src/core/AdvancedMethods.ts
+var AdvancedMethods = class _AdvancedMethods extends PrimitiveMethods {
+  static {
+    __name(this, "AdvancedMethods");
   }
-  getBoolean(key, def) {
-    return _Envapter._get(key, 2 /* Boolean */, def);
+  static getUsing(key, converter, fallback) {
+    const rawVal = this.config.get(key);
+    if (!rawVal) return fallback;
+    const hasFallback = fallback !== void 0;
+    const result = this.parser.convertValue(key, fallback, converter, hasFallback);
+    return result;
   }
-  getBigInt(key, def) {
-    return _Envapter._get(key, 3 /* BigInt */, def);
+  getUsing(key, converter, fallback) {
+    return _AdvancedMethods.getUsing(key, converter, fallback);
   }
-  getSymbol(key, def) {
-    return _Envapter._get(key, 4 /* Symbol */, def);
+  /**
+   * Get an environment variable using a custom converter function.
+   */
+  static getWith(key, converter, fallback) {
+    const rawVal = this.config.get(key);
+    if (!rawVal) return fallback;
+    const hasFallback = fallback !== void 0;
+    const result = this.parser.convertValue(
+      key,
+      fallback,
+      converter,
+      hasFallback
+    );
+    return result;
   }
   /**
-   * Get raw environment variable value without parsing or conversion.
-   *
-   * @internal
+   * @see {@link AdvancedMethods.getWith}
    */
-  getRaw(key) {
-    return _Envapter.config.get(key);
+  getWith(key, converter, fallback) {
+    return _AdvancedMethods.getWith(key, converter, fallback);
+  }
+};
+
+// src/Envapter.ts
+var Envapter = class extends AdvancedMethods {
+  static {
+    __name(this, "Envapter");
   }
 };
 
 // src/Envapt.ts
-function createPropertyDecorator(key, fallback, converter, hasFallback = true) {
+function createPropertyDecorator(key, fallback, converter, hasFallback) {
   return function(target, prop) {
     const propKey = String(prop);
     const cacheKey = `${target.constructor.name}.${propKey}`;
@@ -618,7 +833,27 @@ function Envapt(key, fallbackOrOptions, converter) {
 }
 __name(Envapt, "Envapt");
 
+// src/Converters.ts
+var Converters = /* @__PURE__ */ ((Converters2) => {
+  Converters2["String"] = "string";
+  Converters2["Number"] = "number";
+  Converters2["Boolean"] = "boolean";
+  Converters2["Bigint"] = "bigint";
+  Converters2["Symbol"] = "symbol";
+  Converters2["Integer"] = "integer";
+  Converters2["Float"] = "float";
+  Converters2["Json"] = "json";
+  Converters2["Array"] = "array";
+  Converters2["Url"] = "url";
+  Converters2["Regexp"] = "regexp";
+  Converters2["Date"] = "date";
+  Converters2["Time"] = "time";
+  return Converters2;
+})(Converters || {});
+
+exports.Converters = Converters;
 exports.Envapt = Envapt;
+exports.EnvaptErrorCodes = EnvaptErrorCodes;
 exports.Envapter = Envapter;
 exports.Environment = Environment;
 //# sourceMappingURL=index.cjs.map