ultraenv 1.0.0

package/dist/chunk-MNVFG7H4.js

@@ -0,0 +1,611 @@
+import {
+  parseEnvFile
+} from "./chunk-HFXQGJY3.js";
+import {
+  readFileSync
+} from "./chunk-3VYXPTYV.js";
+import {
+  DEFAULT_ENV_DIR,
+  ENCODING,
+  ENVIRONMENT_VARIABLES,
+  MAX_INTERPOLATION_DEPTH,
+  MAX_VALUE_LENGTH
+} from "./chunk-XC65ORJ5.js";
+import {
+  ConfigError,
+  FileSystemError,
+  InterpolationError,
+  isUltraenvError
+} from "./chunk-5G2DU52U.js";
+
+// src/core/interpolation.ts
+function parseExpression(expr) {
+  if (expr.endsWith("^^")) {
+    return {
+      varName: expr.slice(0, -2),
+      op: "uppercase",
+      operand: "",
+      useColon: false
+    };
+  }
+  if (expr.endsWith(",,")) {
+    return {
+      varName: expr.slice(0, -2),
+      op: "lowercase",
+      operand: "",
+      useColon: false
+    };
+  }
+  const colonIndex = expr.indexOf(":");
+  if (colonIndex > 0) {
+    const varName = expr.slice(0, colonIndex);
+    const rest = expr.slice(colonIndex + 1);
+    if (/^-?\d+(:-?\d+)?$/.test(rest)) {
+      return {
+        varName,
+        op: "substring",
+        operand: rest,
+        useColon: true
+      };
+    }
+    return {
+      varName,
+      op: "default",
+      operand: rest,
+      useColon: true
+    };
+  }
+  const dashIndex = expr.indexOf("-");
+  if (dashIndex > 0) {
+    return {
+      varName: expr.slice(0, dashIndex),
+      op: "default",
+      operand: expr.slice(dashIndex + 1),
+      useColon: false
+    };
+  }
+  const plusIndex = expr.indexOf("+");
+  if (plusIndex > 0) {
+    const varName = expr.slice(0, plusIndex);
+    const rest = expr.slice(plusIndex + 1);
+    const useColon = rest.startsWith(":");
+    return {
+      varName,
+      op: "alternative",
+      /* v8 ignore start */
+      operand: useColon ? rest.slice(1) : rest,
+      /* v8 ignore stop */
+      useColon
+    };
+  }
+  const questionIndex = expr.indexOf("?");
+  if (questionIndex > 0) {
+    const varName = expr.slice(0, questionIndex);
+    const rest = expr.slice(questionIndex + 1);
+    const useColon = rest.startsWith(":");
+    return {
+      varName,
+      op: "error",
+      /* v8 ignore start */
+      operand: useColon ? rest.slice(1) : rest,
+      /* v8 ignore stop */
+      useColon
+    };
+  }
+  return {
+    varName: expr,
+    op: "simple",
+    operand: "",
+    useColon: false
+  };
+}
+function lookupVar(varName, env, systemEnv) {
+  if (varName in env) {
+    return [env[varName], true];
+  }
+  if (systemEnv !== void 0 && varName in systemEnv) {
+    const sysVal = systemEnv[varName];
+    if (sysVal !== void 0) {
+      return [sysVal, true];
+    }
+  }
+  return ["", false];
+}
+function evaluateExpression(parsed, env, systemEnv, expandValue, currentDepth) {
+  const [value, isSet] = lookupVar(parsed.varName, env, systemEnv);
+  const isNonEmpty = isSet && value !== "";
+  switch (parsed.op) {
+    case "simple":
+      if (!isSet) {
+        return "";
+      }
+      return value;
+    case "default": {
+      const shouldDefault = parsed.useColon ? !isNonEmpty : !isSet;
+      if (shouldDefault) {
+        return expandValue(parsed.operand, currentDepth);
+      }
+      return value;
+    }
+    case "alternative": {
+      const shouldAlt = parsed.useColon ? isNonEmpty : isSet;
+      if (shouldAlt) {
+        return expandValue(parsed.operand, currentDepth);
+      }
+      return "";
+    }
+    case "error": {
+      const shouldError = parsed.useColon ? !isNonEmpty : !isSet;
+      if (shouldError) {
+        const expandedMsg = expandValue(parsed.operand, currentDepth);
+        throw new InterpolationError(
+          /* v8 ignore start */
+          `Variable "${parsed.varName}" is ${parsed.useColon ? "unset or empty" : "unset"}: ${expandedMsg}`,
+          /* v8 ignore stop */
+          {
+            variable: parsed.varName,
+            /* v8 ignore start */
+            hint: parsed.operand || `Set the "${parsed.varName}" variable in your .env file.`
+            /* v8 ignore stop */
+          }
+        );
+      }
+      return value;
+    }
+    case "uppercase":
+      return value.toUpperCase();
+    case "lowercase":
+      return value.toLowerCase();
+    case "substring": {
+      const parts = parsed.operand.split(":");
+      const offset = parts[0] !== void 0 ? parseInt(parts[0], 10) : 0;
+      const lengthArg = parts[1] !== void 0 ? parseInt(parts[1], 10) : void 0;
+      if (!isSet) return "";
+      if (Number.isNaN(offset)) return value;
+      const safeOffset = offset < 0 ? Math.max(0, value.length + offset) : offset;
+      if (lengthArg !== void 0 && !Number.isNaN(lengthArg)) {
+        return value.slice(safeOffset, safeOffset + lengthArg);
+      }
+      return value.slice(safeOffset);
+    }
+  }
+}
+function resolveStringLength(varName, env, systemEnv) {
+  const [value, isSet] = lookupVar(varName, env, systemEnv);
+  if (!isSet) return "0";
+  return String(value.length);
+}
+function expandVariables(vars, env, options) {
+  const maxDepth = options?.maxDepth ?? MAX_INTERPOLATION_DEPTH;
+  const systemEnv = options?.systemEnv ?? {};
+  const resolvedMap = {};
+  const resolving = /* @__PURE__ */ new Set();
+  function expandValue(raw, depth) {
+    if (depth > maxDepth) {
+      throw new InterpolationError(
+        `Maximum interpolation depth (${maxDepth}) exceeded`,
+        {
+          hint: "Check for deeply nested variable references. Consider simplifying your variable definitions."
+        }
+      );
+    }
+    const result2 = [];
+    let i = 0;
+    const len = raw.length;
+    while (i < len) {
+      const ch = raw[i];
+      if (ch === "\\" && i + 1 < len && raw[i + 1] === "$") {
+        result2.push("$");
+        i += 2;
+        continue;
+      }
+      if (ch !== "$") {
+        result2.push(ch);
+        i++;
+        continue;
+      }
+      i++;
+      if (i < len && raw[i] === "{" && i + 1 < len && raw[i + 1] === "#") {
+        const closeIdx = raw.indexOf("}", i + 2);
+        if (closeIdx !== -1) {
+          const varName = raw.slice(i + 2, closeIdx).trim();
+          result2.push(resolveStringLength(varName, env, systemEnv));
+          i = closeIdx + 1;
+          continue;
+        }
+        result2.push("$");
+        continue;
+      }
+      if (i < len && raw[i] === "{") {
+        const closeIdx = findClosingBrace(raw, i + 1);
+        if (closeIdx !== -1) {
+          const inner = raw.slice(i + 1, closeIdx);
+          const parsed = parseExpression(inner);
+          if (resolving.has(parsed.varName)) {
+            const chain = Array.from(resolving).concat(parsed.varName).join(" \u2192 ");
+            throw new InterpolationError(
+              `Circular variable reference detected: ${chain}`,
+              {
+                variable: parsed.varName,
+                circular: true,
+                hint: "Break the cycle by removing one of the circular references."
+              }
+            );
+          }
+          resolving.add(parsed.varName);
+          if (parsed.varName in vars && !(parsed.varName in resolvedMap)) {
+            const refRaw = vars[parsed.varName];
+            resolvedMap[parsed.varName] = expandValue(refRaw, depth + 1);
+          }
+          const expanded = evaluateExpression(
+            parsed,
+            { ...resolvedMap, ...vars },
+            systemEnv,
+            expandValue,
+            depth + 1
+          );
+          result2.push(expanded);
+          resolving.delete(parsed.varName);
+          i = closeIdx + 1;
+          continue;
+        }
+        result2.push("${");
+        i++;
+        continue;
+      }
+      if (i < len && /^[A-Za-z_]/.test(raw[i])) {
+        let nameEnd = i + 1;
+        while (nameEnd < len && /^[A-Za-z0-9_]/.test(raw[nameEnd])) {
+          nameEnd++;
+        }
+        const varName = raw.slice(i, nameEnd);
+        if (resolving.has(varName)) {
+          const chain = Array.from(resolving).concat(varName).join(" \u2192 ");
+          throw new InterpolationError(
+            `Circular variable reference detected: ${chain}`,
+            {
+              variable: varName,
+              circular: true,
+              hint: "Break the cycle by removing one of the circular references."
+            }
+          );
+        }
+        resolving.add(varName);
+        if (varName in vars && !(varName in resolvedMap)) {
+          const refRaw = vars[varName];
+          resolvedMap[varName] = expandValue(refRaw, depth + 1);
+        }
+        const [resolvedValue] = lookupVar(varName, { ...resolvedMap, ...vars }, systemEnv);
+        result2.push(resolvedValue);
+        resolving.delete(varName);
+        i = nameEnd;
+        continue;
+      }
+      result2.push("$");
+    }
+    return result2.join("");
+  }
+  const result = {};
+  for (const key of Object.keys(vars)) {
+    const raw = vars[key];
+    result[key] = expandValue(raw, 0);
+  }
+  return result;
+}
+function findClosingBrace(str, startIndex) {
+  let depth = 1;
+  let i = startIndex;
+  const len = str.length;
+  while (i < len) {
+    const ch = str[i];
+    if (ch === "\\" && i + 1 < len) {
+      i += 2;
+      continue;
+    }
+    if (ch === "{") {
+      depth++;
+    } else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        return i;
+      }
+    }
+    i++;
+  }
+  return -1;
+}
+
+// src/core/cascade.ts
+import { join, resolve } from "path";
+import { existsSync } from "fs";
+function detectEnvironment(systemEnv) {
+  const env = systemEnv ?? process.env;
+  for (const varName of ENVIRONMENT_VARIABLES) {
+    const value = env[varName];
+    if (value !== void 0 && value !== "") {
+      return value.toLowerCase().trim();
+    }
+  }
+  return "development";
+}
+function detectFileType(fileName) {
+  const baseName = fileName.split("/").pop() ?? fileName;
+  const baseNameLower = baseName.toLowerCase();
+  const fileTypeMap = /* @__PURE__ */ new Map([
+    [".env", ".env" /* Env */],
+    [".env.local", ".env.local" /* EnvLocal */],
+    [".env.development", ".env.development" /* EnvDevelopment */],
+    [".env.development.local", ".env.development.local" /* EnvDevelopmentLocal */],
+    [".env.test", ".env.test" /* EnvTest */],
+    [".env.test.local", ".env.test.local" /* EnvTestLocal */],
+    [".env.production", ".env.production" /* EnvProduction */],
+    [".env.production.local", ".env.production.local" /* EnvProductionLocal */],
+    [".env.staging", ".env.staging" /* EnvStaging */],
+    [".env.staging.local", ".env.staging.local" /* EnvStagingLocal */],
+    [".env.ci", ".env.ci" /* EnvCI */]
+  ]);
+  return fileTypeMap.get(baseNameLower) ?? null;
+}
+function getStandardCascadeFiles(envDir, environment) {
+  const files = [];
+  let priority = 0;
+  files.push({
+    absolutePath: resolve(join(envDir, ".env")),
+    fileType: ".env" /* Env */,
+    priority: priority++,
+    exists: existsSync(resolve(join(envDir, ".env")))
+  });
+  if (environment !== "test") {
+    const localPath = resolve(join(envDir, ".env.local"));
+    files.push({
+      absolutePath: localPath,
+      fileType: ".env.local" /* EnvLocal */,
+      priority: priority++,
+      exists: existsSync(localPath)
+    });
+  }
+  const envSpecificPath = resolve(join(envDir, `.env.${environment}`));
+  const envFileType = detectFileType(`.env.${environment}`);
+  files.push({
+    absolutePath: envSpecificPath,
+    fileType: envFileType,
+    priority: priority++,
+    exists: existsSync(envSpecificPath)
+  });
+  if (environment !== "test") {
+    const envLocalPath = resolve(join(envDir, `.env.${environment}.local`));
+    const envLocalFileType = detectFileType(`.env.${environment}.local`);
+    files.push({
+      absolutePath: envLocalPath,
+      fileType: envLocalFileType,
+      priority: priority++,
+      exists: existsSync(envLocalPath)
+    });
+  }
+  return files;
+}
+function resolveCascade(options = {}) {
+  const envDir = resolve(options.envDir ?? process.cwd());
+  const environment = options.environment ?? detectEnvironment(options.systemEnv);
+  const mergeStrategy = options.mergeStrategy ?? "last-wins";
+  const includeSystemEnv = options.includeSystemEnv ?? true;
+  const systemEnv = options.systemEnv ?? process.env;
+  let entries;
+  if (options.paths !== void 0 && options.paths.length > 0) {
+    entries = options.paths.map((p, idx) => {
+      const absPath = resolve(p);
+      return {
+        absolutePath: absPath,
+        fileType: detectFileType(p),
+        priority: idx,
+        exists: existsSync(absPath)
+      };
+    });
+  } else if (options.files !== void 0 && options.files.length > 0) {
+    entries = options.files.map((fileType, idx) => {
+      const absPath = resolve(join(envDir, fileType));
+      return {
+        absolutePath: absPath,
+        fileType,
+        priority: idx,
+        exists: existsSync(absPath)
+      };
+    });
+  } else {
+    entries = getStandardCascadeFiles(envDir, environment);
+  }
+  const sorted = [...entries].sort((a, b) => a.priority - b.priority);
+  const existingFiles = sorted.filter((entry) => entry.exists);
+  const sources = {};
+  if (includeSystemEnv) {
+    for (const key of Object.keys(systemEnv)) {
+      const val = systemEnv[key];
+      if (val !== void 0) {
+        sources[key] = "system";
+      }
+    }
+  }
+  return {
+    files: sorted,
+    environment,
+    mergeStrategy,
+    includeSystemEnv,
+    envDir,
+    existingFiles,
+    sources
+  };
+}
+function mergeCascade(parsedFiles, cascade) {
+  const merged = {};
+  if (cascade.mergeStrategy === "first-wins") {
+    for (const file of parsedFiles) {
+      for (const envVar of file.vars) {
+        if (!(envVar.key in merged)) {
+          merged[envVar.key] = envVar.value;
+          cascade.sources[envVar.key] = file.path;
+        }
+      }
+    }
+  } else if (cascade.mergeStrategy === "last-wins") {
+    for (const file of parsedFiles) {
+      for (const envVar of file.vars) {
+        merged[envVar.key] = envVar.value;
+        cascade.sources[envVar.key] = file.path;
+      }
+    }
+  } else {
+    for (const file of parsedFiles) {
+      for (const envVar of file.vars) {
+        if (envVar.key in merged) {
+          throw new ConfigError(
+            /* v8 ignore start */
+            `Duplicate key "${envVar.key}" found in "${file.path}" (line ${envVar.lineNumber}). Previously defined in "${cascade.sources[envVar.key] ?? "unknown"}".`,
+            /* v8 ignore stop */
+            {
+              field: "mergeStrategy",
+              hint: `Either use 'first-wins' or 'last-wins' merge strategy, or rename one of the conflicting variables.`
+            }
+          );
+        }
+        merged[envVar.key] = envVar.value;
+        cascade.sources[envVar.key] = file.path;
+      }
+    }
+  }
+  return merged;
+}
+
+// src/core/loader.ts
+function resolveLoadOptions(options) {
+  const noop = () => {
+  };
+  return {
+    /* v8 ignore start */
+    envDir: options?.envDir ?? DEFAULT_ENV_DIR,
+    /* v8 ignore stop */
+    encoding: options?.encoding ?? ENCODING,
+    expandVars: options?.expandVariables ?? true,
+    overrideProcessEnv: options?.overrideProcessEnv ?? false,
+    maxInterpolationDepth: options?.maxInterpolationDepth ?? MAX_INTERPOLATION_DEPTH,
+    maxValueLength: options?.maxValueLength ?? MAX_VALUE_LENGTH,
+    mergeStrategy: options?.mergeStrategy ?? "last-wins",
+    processEnv: options?.processEnv ?? process.env,
+    onError: noop,
+    cascade: {
+      /* v8 ignore start */
+      envDir: options?.envDir ?? DEFAULT_ENV_DIR,
+      /* v8 ignore stop */
+      mergeStrategy: options?.mergeStrategy ?? "last-wins"
+    }
+  };
+}
+function load(options) {
+  const resolved = resolveLoadOptions(options);
+  const result = loadCoreSync(resolved);
+  applyToProcessEnv(result.env, resolved);
+  return result.env;
+}
+function loadSync(options) {
+  return load(options);
+}
+function loadWithResult(options) {
+  const startTime = Date.now();
+  const resolved = resolveLoadOptions(options);
+  const result = loadCoreSync(resolved);
+  const hadOverrides = applyToProcessEnv(result.env, resolved);
+  return {
+    env: result.env,
+    metadata: buildMetadata(result.parsed, result.env, startTime, resolved.envDir, hadOverrides),
+    parsed: result.parsed
+  };
+}
+function loadWithResultSync(options) {
+  return loadWithResult(options);
+}
+function loadCoreSync(resolved) {
+  const cascade = resolveCascade(resolved.cascade);
+  const parsed = [];
+  const existingEntries = cascade.existingFiles;
+  for (const entry of existingEntries) {
+    try {
+      const content = readFileSync(entry.absolutePath, resolved.encoding);
+      validateContentLengths(content, entry.absolutePath, resolved.maxValueLength);
+      const parsedFile = parseEnvFile(content, entry.absolutePath);
+      parsed.push(parsedFile);
+    } catch (error) {
+      resolved.onError(
+        isUltraenvError(error) ? error : new FileSystemError(`Failed to read "${entry.absolutePath}"`, {
+          path: entry.absolutePath,
+          operation: "read",
+          cause: error instanceof Error ? error : void 0
+        })
+      );
+    }
+  }
+  const merged = mergeCascade(parsed, cascade);
+  let env;
+  if (resolved.expandVars) {
+    env = expandVariables(merged, merged, {
+      maxDepth: resolved.maxInterpolationDepth,
+      systemEnv: resolved.processEnv
+    });
+  } else {
+    env = { ...merged };
+  }
+  return { env, parsed };
+}
+function applyToProcessEnv(env, resolved) {
+  if (!resolved.overrideProcessEnv) return false;
+  let hadOverrides = false;
+  for (const [key, value] of Object.entries(env)) {
+    if (process.env[key] !== value) {
+      hadOverrides = true;
+    }
+    process.env[key] = value;
+  }
+  return hadOverrides;
+}
+function validateContentLengths(content, filePath, maxValueLength) {
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const eqIndex = line.indexOf("=");
+    if (eqIndex === -1) continue;
+    const trimmed = line.slice(0, eqIndex).trim();
+    if (trimmed.startsWith("#")) continue;
+    const value = line.slice(eqIndex + 1).trimStart();
+    if (value.length > maxValueLength) {
+      throw new FileSystemError(
+        `Value for variable at line ${i + 1} exceeds maximum length of ${maxValueLength} bytes (${value.length} bytes)`,
+        {
+          path: filePath,
+          operation: "read",
+          hint: "Reduce the value length or increase maxValueLength in your ultraenv configuration."
+        }
+      );
+    }
+  }
+}
+function buildMetadata(parsed, env, startTime, envDir, hadOverrides) {
+  const filesFound = parsed.length;
+  const totalVars = Object.keys(env).length;
+  return {
+    totalVars,
+    filesParsed: filesFound,
+    filesFound,
+    loadTimeMs: Date.now() - startTime,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    envDir,
+    hadOverrides
+  };
+}
+
+export {
+  expandVariables,
+  resolveCascade,
+  mergeCascade,
+  load,
+  loadSync,
+  loadWithResult,
+  loadWithResultSync
+};