envapt 1.0.0

package/dist/index.js

@@ -0,0 +1,625 @@
+'use strict';
+
+var dotenv = require('dotenv');
+
+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 EnvaptError = class _EnvaptError extends Error {
+  static {
+    __name(this, "EnvaptError");
+  }
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = `${ReversedEnvaptErrorCodes[code]} [${code}]`;
+    this.code = code;
+    Error.captureStackTrace(this, _EnvaptError);
+  }
+};
+
+// src/ListOfBuiltInConverters.ts
+var ListOfBuiltInConverters = [
+  "string",
+  "number",
+  "boolean",
+  "bigint",
+  "symbol",
+  "integer",
+  "float",
+  "json",
+  "array",
+  "url",
+  "regexp",
+  "date",
+  "time"
+];
+
+// src/Validators.ts
+var Validator = class {
+  static {
+    __name(this, "Validator");
+  }
+  /**
+   * Check if a value is a built-in converter type
+   */
+  static isBuiltInConverter(value) {
+    if (typeof value === "string") return ListOfBuiltInConverters.includes(value);
+    return false;
+  }
+  /**
+   * Check if a value is an ArrayConverter configuration object
+   */
+  static isArrayConverter(value) {
+    return typeof value === "object" && value !== null && "delimiter" in value && typeof value.delimiter === "string";
+  }
+  /**
+   * Check if a value is a valid ArrayConverter type
+   */
+  static isValidArrayConverterType(value) {
+    if (typeof value !== "string") return false;
+    const invalidTypes = ["array", "json", "regexp"];
+    if (invalidTypes.includes(value)) return false;
+    const validTypes = ListOfBuiltInConverters.filter(
+      (type) => !invalidTypes.includes(type)
+    );
+    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,
+        `Custom converter must be a function, got ${typeof converter}.`
+      );
+    }
+  }
+  /**
+   * Validate ArrayConverter configuration with runtime checks
+   */
+  static arrayConverter(value) {
+    if (!this.isArrayConverter(value)) {
+      throw new EnvaptError(EnvaptErrorCodes.MissingDelimiter, "Must have delimiter property");
+    }
+    if (value.type !== void 0 && !this.isValidArrayConverterType(value.type)) {
+      throw new EnvaptError(
+        EnvaptErrorCodes.InvalidArrayConverterType,
+        `"${value.type}" is not a valid converter type`
+      );
+    }
+  }
+  /**
+   * Validate that a string is a valid built-in converter type
+   */
+  static builtInConverter(value) {
+    if (typeof value !== "string") {
+      throw new EnvaptError(EnvaptErrorCodes.InvalidConverterType, `Expected string, got ${typeof value}`);
+    }
+    if (!ListOfBuiltInConverters.includes(value)) {
+      throw new EnvaptError(
+        EnvaptErrorCodes.InvalidBuiltInConverter,
+        `"${value}" is not a valid converter type. Valid types are: ${ListOfBuiltInConverters.join(",")}`
+      );
+    }
+  }
+};
+
+// src/BuiltInConverters.ts
+var BuiltInConverters = class _BuiltInConverters {
+  static {
+    __name(this, "BuiltInConverters");
+  }
+  static string(raw, fallback) {
+    return 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"];
+    if (truthyValues.includes(lower)) return true;
+    if (falsyValues.includes(lower)) return false;
+    return fallback;
+  }
+  static bigint(raw, fallback) {
+    if (raw === void 0) return fallback;
+    try {
+      return BigInt(raw);
+    } catch {
+      return fallback;
+    }
+  }
+  static symbol(raw, fallback) {
+    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 {
+      return fallback;
+    }
+  }
+  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);
+  }
+  static url(raw, fallback) {
+    if (raw === void 0) return fallback;
+    try {
+      return new URL(raw);
+    } catch {
+      return fallback;
+    }
+  }
+  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]);
+      return new RegExp(raw);
+    } catch {
+      return fallback;
+    }
+  }
+  static date(raw, fallback) {
+    if (raw === void 0) return fallback;
+    if (/^\d+$/.test(raw)) {
+      const timestamp = parseInt(raw, 10);
+      const parsed2 = new Date(timestamp);
+      return Number.isNaN(parsed2.getTime()) ? fallback : parsed2;
+    }
+    const parsed = new Date(raw);
+    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;
+    if (!numStr) return fallback;
+    const value = Number.parseFloat(numStr);
+    if (Number.isNaN(value)) return fallback;
+    const SECONDS_TO_MS = 1e3;
+    const SECONDS_PER_MINUTE = 60;
+    const MINUTES_PER_HOUR = 60;
+    const MINUTES_TO_MS = SECONDS_PER_MINUTE * SECONDS_TO_MS;
+    const HOURS_TO_MS = MINUTES_PER_HOUR * MINUTES_TO_MS;
+    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;
+  }
+  /**
+   * 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);
+    return items.map((item) => {
+      const converted = converter(item, void 0);
+      return converted ?? item;
+    });
+  }
+  /**
+   * Get the converter function for a built-in converter type
+   */
+  static getConverter(type) {
+    const converters = {
+      string: _BuiltInConverters.string,
+      number: _BuiltInConverters.number,
+      boolean: _BuiltInConverters.boolean,
+      integer: _BuiltInConverters.integer,
+      bigint: _BuiltInConverters.bigint,
+      symbol: _BuiltInConverters.symbol,
+      float: _BuiltInConverters.float,
+      json: _BuiltInConverters.json,
+      array: _BuiltInConverters.array,
+      url: _BuiltInConverters.url,
+      regexp: _BuiltInConverters.regexp,
+      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;
+  }
+};
+
+// src/Parser.ts
+var Parser = class {
+  constructor(envService) {
+    this.envService = envService;
+  }
+  static {
+    __name(this, "Parser");
+  }
+  TEMPLATE_REGEX = /\${\w*}/g;
+  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;
+      const resolved = this.resolveTemplate(variable, raw, new Set(stack));
+      if (resolved.includes(`\${${key}}`)) return template;
+      if (resolved === raw && /\$\{[^}]*\}/.test(resolved)) return template;
+      return resolved;
+    });
+    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";
+    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);
+    }
+    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;
+    }
+    Validator.customConvertor(resolvedConverter);
+    const raw = this.envService.get(key, void 0);
+    if (raw === void 0) return hasFallback ? fallback : null;
+    return resolvedConverter(raw, fallback);
+  }
+  resolveConverter(converter, fallback) {
+    if (converter) return converter;
+    const fallbackType = typeof fallback;
+    if (fallbackType === "number") return "number";
+    if (fallbackType === "boolean") return "boolean";
+    if (fallbackType === "bigint") return "bigint";
+    if (fallbackType === "symbol") return "symbol";
+    return "string";
+  }
+};
+
+// src/Envapter.ts
+var EnvaptCache = /* @__PURE__ */ new Map();
+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 {
+  static {
+    __name(this, "Envapter");
+  }
+  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")))
+    );
+  }
+  /**
+   * Get currently configured .env file paths
+   * @returns Array of file paths being loaded
+   */
+  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 */;
+      }
+    }
+    return env;
+  }
+  /**
+   * 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);
+  }
+  /**
+   * Get the current application environment
+   * @returns Current environment enum value
+   */
+  static get environment() {
+    return this.internalEnvironment;
+  }
+  /**
+   * Check if the current environment is production
+   * @returns true if environment is production
+   */
+  static get isProduction() {
+    return this.internalEnvironment === 2 /* Production */;
+  }
+  /**
+   * Check if the current environment is staging
+   * @returns true if environment is staging
+   */
+  static get isStaging() {
+    return this.internalEnvironment === 1 /* Staging */;
+  }
+  /**
+   * Check if the current environment is development
+   * @returns true if environment is development
+   */
+  static get isDevelopment() {
+    return this.internalEnvironment === 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;
+  }
+  static _get(key, type = 0 /* String */, 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);
+      }
+    }
+  }
+  /**
+   * 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);
+  }
+  /**
+   * 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);
+  }
+  /**
+   * 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);
+   * ```
+   */
+  static getBoolean(key, def) {
+    return this._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);
+  }
+  /**
+   * 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);
+  }
+  getNumber(key, def) {
+    return _Envapter._get(key, 1 /* Number */, def);
+  }
+  getBoolean(key, def) {
+    return _Envapter._get(key, 2 /* Boolean */, def);
+  }
+  getBigInt(key, def) {
+    return _Envapter._get(key, 3 /* BigInt */, def);
+  }
+  getSymbol(key, def) {
+    return _Envapter._get(key, 4 /* Symbol */, def);
+  }
+  /**
+   * Get raw environment variable value without parsing or conversion.
+   *
+   * @internal
+   */
+  getRaw(key) {
+    return _Envapter.config.get(key);
+  }
+};
+
+// src/Envapt.ts
+function createPropertyDecorator(key, fallback, converter, hasFallback = true) {
+  return function(target, prop) {
+    const propKey = String(prop);
+    const cacheKey = `${target.constructor.name}.${propKey}`;
+    Object.defineProperty(target, propKey, {
+      get: /* @__PURE__ */ __name(function() {
+        let value = EnvaptCache.get(cacheKey);
+        if (value === void 0) {
+          const parser = new Parser(new Envapter());
+          value = parser.convertValue(key, fallback, converter, hasFallback);
+          EnvaptCache.set(cacheKey, value);
+        }
+        return value;
+      }, "get"),
+      configurable: false,
+      enumerable: true
+    });
+  };
+}
+__name(createPropertyDecorator, "createPropertyDecorator");
+function Envapt(key, fallbackOrOptions, converter) {
+  let fallback;
+  let actualConverter;
+  let hasFallback = true;
+  if (fallbackOrOptions && typeof fallbackOrOptions === "object" && ("fallback" in fallbackOrOptions || "converter" in fallbackOrOptions)) {
+    const options = fallbackOrOptions;
+    fallback = options.fallback;
+    actualConverter = options.converter;
+    hasFallback = "fallback" in options;
+  } else {
+    fallback = fallbackOrOptions;
+    actualConverter = converter;
+    hasFallback = arguments.length > 1;
+  }
+  return createPropertyDecorator(key, fallback, actualConverter, hasFallback);
+}
+__name(Envapt, "Envapt");
+
+exports.Envapt = Envapt;
+exports.Envapter = Envapter;
+exports.Environment = Environment;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map