node-safe-env 0.1.0

package/dist/index.cjs

@@ -0,0 +1,938 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  EnvValidationError: () => EnvValidationError,
+  createEnv: () => createEnv,
+  defineEnv: () => defineEnv,
+  maskEnv: () => maskEnv,
+  mergeSources: () => mergeSources,
+  readEnvFileSource: () => readEnvFileSource,
+  resolveExampleEnvPath: () => resolveExampleEnvPath,
+  traceEnv: () => traceEnv,
+  validateExampleEnv: () => validateExampleEnv,
+  validateExampleEnvFile: () => validateExampleEnvFile
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors/EnvValidationError.ts
+var EnvValidationError = class extends Error {
+  constructor(issues) {
+    super(
+      [
+        "Environment validation failed:",
+        ...issues.map((issue) => `- [${issue.code}] ${issue.message}`)
+      ].join("\n")
+    );
+    this.name = "EnvValidationError";
+    this.issues = issues;
+  }
+};
+
+// src/createEnv.ts
+var import_node_path2 = __toESM(require("path"), 1);
+
+// src/flattenSchema.ts
+function isEnvRule(value) {
+  return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+function toEnvKey(path3) {
+  return path3.map((segment) => segment.toUpperCase()).join("_");
+}
+function flattenSchema(schema, parentPath = []) {
+  const entries = [];
+  for (const [key, value] of Object.entries(schema)) {
+    const currentPath = [...parentPath, key];
+    if (isEnvRule(value)) {
+      entries.push({
+        path: currentPath,
+        envKey: toEnvKey(currentPath),
+        rule: value
+      });
+      continue;
+    }
+    if (typeof value === "object" && value !== null) {
+      entries.push(
+        ...flattenSchema(value, currentPath)
+      );
+    }
+  }
+  return entries;
+}
+
+// src/findUnknownEnvKeys.ts
+function findUnknownEnvKeys(schema, source) {
+  const knownKeys = new Set(flattenSchema(schema).map((entry) => entry.envKey));
+  const issues = [];
+  for (const key of Object.keys(source)) {
+    if (source[key] === void 0) {
+      continue;
+    }
+    if (knownKeys.has(key)) {
+      continue;
+    }
+    issues.push({
+      key,
+      code: "unknown_key",
+      message: `Environment variable "${key}" is not defined in the schema.`
+    });
+  }
+  return issues;
+}
+
+// src/loadEnvFiles.ts
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function stripInlineComment(input) {
+  let inSingleQuote = false;
+  let inDoubleQuote = false;
+  let isEscaped = false;
+  for (let index = 0; index < input.length; index += 1) {
+    const char = input[index];
+    if (isEscaped) {
+      isEscaped = false;
+      continue;
+    }
+    if (char === "\\") {
+      isEscaped = true;
+      continue;
+    }
+    if (char === '"' && !inSingleQuote) {
+      inDoubleQuote = !inDoubleQuote;
+      continue;
+    }
+    if (char === "'" && !inDoubleQuote) {
+      inSingleQuote = !inSingleQuote;
+      continue;
+    }
+    if (char === "#" && !inSingleQuote && !inDoubleQuote && (index === 0 || /\s/.test(input[index - 1] ?? ""))) {
+      return input.slice(0, index).trimEnd();
+    }
+  }
+  return input.trimEnd();
+}
+function parseEnvFile(filePath) {
+  if (!import_node_fs.default.existsSync(filePath)) {
+    return /* @__PURE__ */ Object.create(null);
+  }
+  const content = import_node_fs.default.readFileSync(filePath, "utf8");
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const rawLine of content.split(/\r?\n/)) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    if (line.startsWith("export ")) {
+      line = line.slice("export ".length).trim();
+      if (!line) {
+        continue;
+      }
+    }
+    const equalIndex = line.indexOf("=");
+    if (equalIndex <= 0) {
+      continue;
+    }
+    const key = line.slice(0, equalIndex).trim();
+    if (!ENV_KEY_PATTERN.test(key)) {
+      continue;
+    }
+    let value = stripInlineComment(line.slice(equalIndex + 1)).trim();
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    result[key] = value;
+  }
+  return result;
+}
+function loadEnvFiles(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const nodeEnv = options.nodeEnv ?? process.env.NODE_ENV ?? "development";
+  const base = parseEnvFile(import_node_path.default.join(cwd, ".env"));
+  const local = parseEnvFile(import_node_path.default.join(cwd, ".env.local"));
+  const environment = parseEnvFile(import_node_path.default.join(cwd, `.env.${nodeEnv}`));
+  const custom = options.envFile ? parseEnvFile(import_node_path.default.resolve(cwd, options.envFile)) : /* @__PURE__ */ Object.create(null);
+  return {
+    base,
+    local,
+    environment,
+    custom
+  };
+}
+
+// src/mergeSources.ts
+function mergeSources(files, runtimeValues = process.env) {
+  return Object.assign(
+    /* @__PURE__ */ Object.create(null),
+    files.base,
+    files.local,
+    files.environment,
+    files.custom,
+    runtimeValues
+  );
+}
+
+// src/applyTransform.ts
+function applyTransform(key, rule, result) {
+  if (result.issue || result.value === void 0 || !rule.transform) {
+    return result;
+  }
+  try {
+    return {
+      value: rule.transform(result.value)
+    };
+  } catch (error) {
+    const message = error instanceof Error && error.message ? error.message : `Environment variable "${key}" failed transform.`;
+    return {
+      issue: {
+        key,
+        code: "invalid_custom",
+        message
+      }
+    };
+  }
+}
+
+// src/validators/boolean.ts
+var TRUE_VALUES = /* @__PURE__ */ new Set(["true", "1", "yes", "on"]);
+var FALSE_VALUES = /* @__PURE__ */ new Set(["false", "0", "no", "off"]);
+var validateBoolean = ({ key, rawValue }) => {
+  const normalized = rawValue.trim().toLowerCase();
+  if (TRUE_VALUES.has(normalized)) {
+    return { value: true };
+  }
+  if (FALSE_VALUES.has(normalized)) {
+    return { value: false };
+  }
+  return {
+    issue: {
+      key,
+      code: "invalid_boolean",
+      message: `Environment variable "${key}" must be a valid boolean.`
+    }
+  };
+};
+
+// src/validators/enum.ts
+var validateEnum = ({ key, rawValue, rule }) => {
+  const enumRule = rule;
+  if (!enumRule.values.includes(rawValue)) {
+    return {
+      issue: {
+        key,
+        code: "invalid_enum",
+        message: `Environment variable "${key}" must be one of: ${enumRule.values.join(", ")}.`
+      }
+    };
+  }
+  return { value: rawValue };
+};
+
+// src/validators/json.ts
+var validateJson = ({ key, rawValue }) => {
+  try {
+    const parsed = JSON.parse(rawValue);
+    return { value: parsed };
+  } catch {
+    return {
+      issue: {
+        key,
+        code: "invalid_json",
+        message: `Environment variable "${key}" must contain valid JSON.`
+      }
+    };
+  }
+};
+
+// src/validators/number.ts
+var validateNumber = ({ key, rawValue }) => {
+  const parsed = Number(rawValue);
+  if (!Number.isFinite(parsed)) {
+    return {
+      issue: {
+        key,
+        code: "invalid_number",
+        message: `Environment variable "${key}" must be a valid number.`
+      }
+    };
+  }
+  return { value: parsed };
+};
+
+// src/validators/port.ts
+var validatePort = ({ key, rawValue }) => {
+  const num = Number(rawValue);
+  if (!Number.isInteger(num) || num < 1 || num > 65535) {
+    return {
+      issue: {
+        key,
+        code: "invalid_port",
+        message: `Environment variable "${key}" must be a valid port (1\u201365535).`
+      }
+    };
+  }
+  return { value: num };
+};
+
+// src/validators/string.ts
+var validateString = ({ rawValue }) => {
+  return { value: rawValue };
+};
+
+// src/validators/url.ts
+var validateUrl = ({ key, rawValue }) => {
+  try {
+    new URL(rawValue);
+    return { value: rawValue };
+  } catch {
+    return {
+      issue: {
+        key,
+        code: "invalid_url",
+        message: `Environment variable "${key}" must be a valid URL.`
+      }
+    };
+  }
+};
+
+// src/validators/int.ts
+var validateInt = ({ key, rawValue }) => {
+  const parsed = Number(rawValue);
+  if (!Number.isInteger(parsed)) {
+    return {
+      issue: {
+        key,
+        code: "invalid_number",
+        message: `Environment variable "${key}" must be a valid integer.`
+      }
+    };
+  }
+  return { value: parsed };
+};
+
+// src/validators/float.ts
+var validateFloat = ({ key, rawValue }) => {
+  const parsed = Number(rawValue);
+  if (!Number.isFinite(parsed)) {
+    return {
+      issue: {
+        key,
+        code: "invalid_number",
+        message: `Environment variable "${key}" must be a valid float.`
+      }
+    };
+  }
+  return { value: parsed };
+};
+
+// src/validators/array.ts
+var validateArray = ({ key, rawValue, rule }) => {
+  const arrayRule = rule;
+  const separator = arrayRule.separator ?? ",";
+  const trimItems = arrayRule.trimItems ?? true;
+  const allowEmptyItems = arrayRule.allowEmptyItems ?? false;
+  const splitValues = rawValue.split(separator);
+  const parsed = trimItems ? splitValues.map((item) => item.trim()) : splitValues;
+  if (!allowEmptyItems && parsed.some((item) => item === "")) {
+    const issue = {
+      key,
+      code: "invalid_array",
+      message: `Environment variable "${key}" cannot contain empty array items`
+    };
+    return { issue };
+  }
+  return { value: parsed };
+};
+
+// src/validators/custom.ts
+var validateCustom = ({ key, rawValue, rule }) => {
+  const customRule = rule;
+  try {
+    const parsed = customRule.parse(rawValue);
+    return { value: parsed };
+  } catch (error) {
+    const message = error instanceof Error && error.message ? error.message : `Environment variable "${key}" failed custom validation.`;
+    return {
+      issue: {
+        key,
+        code: "invalid_custom",
+        message
+      }
+    };
+  }
+};
+
+// src/validators/email.ts
+var validateEmail = ({ key, rawValue, rule }) => {
+  const emailRule = rule;
+  void emailRule;
+  const value = rawValue.trim();
+  if (!value) {
+    const issue = {
+      key,
+      code: "invalid_email",
+      message: `Environment variable "${key}" must be a valid email address`
+    };
+    return { issue };
+  }
+  if (/\s/.test(value)) {
+    const issue = {
+      key,
+      code: "invalid_email",
+      message: `Environment variable "${key}" must be a valid email address`
+    };
+    return { issue };
+  }
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  if (!emailRegex.test(value)) {
+    const issue = {
+      key,
+      code: "invalid_email",
+      message: `Environment variable "${key}" must be a valid email address`
+    };
+    return { issue };
+  }
+  return {
+    value
+  };
+};
+
+// src/validators/date.ts
+function isValidDate(date) {
+  return !Number.isNaN(date.getTime());
+}
+var validateDate = ({ key, rawValue, rule }) => {
+  const dateRule = rule;
+  void dateRule;
+  const value = rawValue.trim();
+  if (!value) {
+    const issue = {
+      key,
+      code: "invalid_date",
+      message: `Environment variable "${key}" must be a valid ISO date`
+    };
+    return { issue };
+  }
+  const isoDateRegex = /^\d{4}-\d{2}-\d{2}$/;
+  const isoDateTimeRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2}(\.\d{1,3})?)?(Z|[+-]\d{2}:\d{2})$/;
+  if (!isoDateRegex.test(value) && !isoDateTimeRegex.test(value)) {
+    const issue = {
+      key,
+      code: "invalid_date",
+      message: `Environment variable "${key}" must be a valid ISO date string`
+    };
+    return { issue };
+  }
+  const parsed = new Date(value);
+  if (!isValidDate(parsed)) {
+    const issue = {
+      key,
+      code: "invalid_date",
+      message: `Environment variable "${key}" must be a valid date`
+    };
+    return { issue };
+  }
+  if (isoDateRegex.test(value)) {
+    const [year, month, day] = value.split("-").map(Number);
+    if (parsed.getUTCFullYear() !== year || parsed.getUTCMonth() + 1 !== month || parsed.getUTCDate() !== day) {
+      const issue = {
+        key,
+        code: "invalid_date",
+        message: `Environment variable "${key}" must be a real calendar date`
+      };
+      return { issue };
+    }
+  }
+  return {
+    value: parsed
+  };
+};
+
+// src/validators/index.ts
+var validators = {
+  string: validateString,
+  number: validateNumber,
+  boolean: validateBoolean,
+  enum: validateEnum,
+  url: validateUrl,
+  port: validatePort,
+  json: validateJson,
+  int: validateInt,
+  float: validateFloat,
+  array: validateArray,
+  custom: validateCustom,
+  email: validateEmail,
+  date: validateDate
+};
+
+// src/parseValue.ts
+function parseValue(key, rawValue, rule) {
+  const validator = validators[rule.type];
+  const result = validator({
+    key,
+    rawValue,
+    rule
+  });
+  return applyTransform(key, rule, result);
+}
+
+// src/setNestedValue.ts
+function setNestedValue(target, path3, value) {
+  let current = target;
+  for (let index = 0; index < path3.length - 1; index += 1) {
+    const segment = path3[index];
+    const existing = current[segment];
+    if (typeof existing !== "object" || existing === null || Array.isArray(existing)) {
+      current[segment] = {};
+    }
+    current = current[segment];
+  }
+  current[path3[path3.length - 1]] = value;
+}
+
+// src/createEnv.ts
+function isEmptyString(value) {
+  return value.trim() === "";
+}
+function defaultToRawValue(value) {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  return JSON.stringify(value);
+}
+function resolveDefaultValue(value) {
+  return typeof value === "function" ? value() : value;
+}
+function parseDefaultValue(envKey, rule) {
+  const defaultKind = typeof rule.default === "function" ? "function" : "static";
+  let resolvedDefault;
+  try {
+    resolvedDefault = resolveDefaultValue(rule.default);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      issue: {
+        key: envKey,
+        code: "invalid_default",
+        message: `Default function for "${envKey}" threw an error: ${message}`
+      },
+      defaultKind
+    };
+  }
+  const rawDefault = defaultToRawValue(resolvedDefault);
+  return {
+    ...parseValue(envKey, rawDefault, rule),
+    defaultKind,
+    rawDefault
+  };
+}
+function countKeys(source) {
+  return Object.values(source).filter((value) => typeof value === "string").length;
+}
+function buildLoadedFileReport(loadedFiles, cwd, nodeEnv, envFile) {
+  return [
+    {
+      source: ".env",
+      path: import_node_path2.default.join(cwd, ".env"),
+      keyCount: countKeys(loadedFiles.base)
+    },
+    {
+      source: ".env.local",
+      path: import_node_path2.default.join(cwd, ".env.local"),
+      keyCount: countKeys(loadedFiles.local)
+    },
+    {
+      source: ".env.environment",
+      path: import_node_path2.default.join(cwd, `.env.${nodeEnv}`),
+      keyCount: countKeys(loadedFiles.environment)
+    },
+    {
+      source: "custom",
+      path: envFile ? import_node_path2.default.resolve(cwd, envFile) : void 0,
+      keyCount: countKeys(loadedFiles.custom)
+    }
+  ];
+}
+function buildSourceTrace(loadedFiles, runtimeValues) {
+  const trace = /* @__PURE__ */ Object.create(null);
+  const applySource = (source, label) => {
+    for (const [key, raw] of Object.entries(source)) {
+      if (typeof raw === "string") {
+        trace[key] = { source: label, raw };
+      }
+    }
+  };
+  applySource(loadedFiles.base, ".env");
+  applySource(loadedFiles.local, ".env.local");
+  applySource(loadedFiles.environment, ".env.environment");
+  applySource(loadedFiles.custom, "custom");
+  applySource(runtimeValues, "process.env");
+  return trace;
+}
+function maskDebugValue(value, sensitive) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return sensitive ? "***" : value;
+}
+function resolveDebugLogger(debug) {
+  if (debug === true) {
+    return (report) => {
+      console.info(report);
+    };
+  }
+  if (debug && typeof debug === "object" && debug.logger) {
+    return debug.logger;
+  }
+  return void 0;
+}
+function createEnv(schema, options = {}) {
+  const debugEnabled = options.debug !== void 0 && options.debug !== false;
+  const debugLogger = debugEnabled ? resolveDebugLogger(options.debug) : void 0;
+  const debugKeys = [];
+  let source;
+  let loadedFileReport = [];
+  let sourceTrace = /* @__PURE__ */ Object.create(null);
+  if (options.source) {
+    source = options.source;
+    if (debugEnabled) {
+      for (const [key, raw] of Object.entries(source)) {
+        if (typeof raw === "string") {
+          sourceTrace[key] = { source: "process.env", raw };
+        }
+      }
+    }
+  } else {
+    const loadedFiles = loadEnvFiles({
+      cwd: options.cwd,
+      nodeEnv: options.nodeEnv,
+      envFile: options.envFile
+    });
+    source = mergeSources(loadedFiles, process.env);
+    if (debugEnabled) {
+      const cwd = options.cwd ?? process.cwd();
+      const nodeEnv = options.nodeEnv ?? process.env.NODE_ENV ?? "development";
+      loadedFileReport = buildLoadedFileReport(
+        loadedFiles,
+        cwd,
+        nodeEnv,
+        options.envFile
+      );
+      sourceTrace = buildSourceTrace(loadedFiles, process.env);
+    }
+  }
+  const issues = [];
+  const result = {};
+  const flattenedSchema = flattenSchema(schema);
+  if (options.strict) {
+    issues.push(
+      ...findUnknownEnvKeys(schema, source)
+    );
+  }
+  for (const entry of flattenedSchema) {
+    const { path: path3, envKey, rule } = entry;
+    const currentValue = source[envKey];
+    const sourceInfo = sourceTrace[envKey];
+    const sensitive = rule.sensitive === true;
+    const defaultKind = rule.default === void 0 ? void 0 : typeof rule.default === "function" ? "function" : "static";
+    const pushDebugEntry = (status, values) => {
+      if (!debugEnabled) {
+        return;
+      }
+      debugKeys.push({
+        key: envKey,
+        ruleType: rule.type,
+        source: values.source,
+        usedDefault: values.usedDefault,
+        defaultKind: values.defaultKind,
+        raw: maskDebugValue(values.raw, sensitive),
+        parsed: maskDebugValue(values.parsed, sensitive),
+        status,
+        issue: values.issue
+      });
+    };
+    if (typeof currentValue !== "string") {
+      if (rule.default !== void 0) {
+        const parsedDefault = parseDefaultValue(envKey, rule);
+        if (parsedDefault.issue) {
+          issues.push(parsedDefault.issue);
+          pushDebugEntry("issue", {
+            source: "default",
+            usedDefault: true,
+            defaultKind: parsedDefault.defaultKind,
+            raw: parsedDefault.rawDefault,
+            issue: parsedDefault.issue
+          });
+          continue;
+        }
+        pushDebugEntry("defaulted", {
+          source: "default",
+          usedDefault: true,
+          defaultKind: parsedDefault.defaultKind,
+          raw: parsedDefault.rawDefault,
+          parsed: parsedDefault.value
+        });
+        setNestedValue(result, path3, parsedDefault.value);
+        continue;
+      }
+      if (rule.required) {
+        const issue = {
+          key: envKey,
+          code: "missing",
+          message: `Missing required environment variable "${envKey}".`
+        };
+        issues.push(issue);
+        pushDebugEntry("missing", {
+          source: "missing",
+          usedDefault: false,
+          defaultKind,
+          issue
+        });
+      } else {
+        pushDebugEntry("missing", {
+          source: "missing",
+          usedDefault: false,
+          defaultKind
+        });
+      }
+      continue;
+    }
+    const rawValue = currentValue;
+    if (!rule.allowEmpty && isEmptyString(rawValue)) {
+      if (rule.default !== void 0) {
+        const parsedDefault = parseDefaultValue(envKey, rule);
+        if (parsedDefault.issue) {
+          issues.push(parsedDefault.issue);
+          pushDebugEntry("issue", {
+            source: "default",
+            usedDefault: true,
+            defaultKind: parsedDefault.defaultKind,
+            raw: parsedDefault.rawDefault,
+            issue: parsedDefault.issue
+          });
+          continue;
+        }
+        pushDebugEntry("defaulted", {
+          source: "default",
+          usedDefault: true,
+          defaultKind: parsedDefault.defaultKind,
+          raw: parsedDefault.rawDefault,
+          parsed: parsedDefault.value
+        });
+        setNestedValue(result, path3, parsedDefault.value);
+        continue;
+      }
+      const issue = {
+        key: envKey,
+        code: "empty",
+        message: `Environment variable "${envKey}" cannot be empty.`
+      };
+      issues.push(issue);
+      pushDebugEntry("empty", {
+        source: sourceInfo?.source ?? "process.env",
+        usedDefault: false,
+        defaultKind,
+        raw: rawValue,
+        issue
+      });
+      continue;
+    }
+    const parsed = parseValue(envKey, rawValue, rule);
+    if (parsed.issue) {
+      issues.push(parsed.issue);
+      pushDebugEntry("issue", {
+        source: sourceInfo?.source ?? "process.env",
+        usedDefault: false,
+        defaultKind,
+        raw: rawValue,
+        issue: parsed.issue
+      });
+      continue;
+    }
+    pushDebugEntry("parsed", {
+      source: sourceInfo?.source ?? "process.env",
+      usedDefault: false,
+      defaultKind,
+      raw: rawValue,
+      parsed: parsed.value
+    });
+    setNestedValue(result, path3, parsed.value);
+  }
+  if (debugLogger) {
+    debugLogger({
+      loadedFiles: loadedFileReport,
+      keys: debugKeys
+    });
+  }
+  if (issues.length > 0) {
+    throw new EnvValidationError(issues);
+  }
+  return result;
+}
+
+// src/defineEnv.ts
+function defineEnv(schema) {
+  return schema;
+}
+
+// src/maskEnv.ts
+function maskValue() {
+  return "***";
+}
+function maskEnv(schema, env) {
+  const masked = {};
+  const envRecord = env;
+  for (const key of Object.keys(schema)) {
+    const value = envRecord[key];
+    if (value === void 0) {
+      continue;
+    }
+    masked[key] = schema[key].sensitive ? maskValue() : value;
+  }
+  return masked;
+}
+
+// src/traceEnv.ts
+function traceEnv(schema, sources, env) {
+  const traced = {};
+  const envRecord = env;
+  for (const key of Object.keys(schema)) {
+    const value = envRecord[key];
+    if (value === void 0) {
+      continue;
+    }
+    const sourceInfo = sources[key];
+    if (!sourceInfo) {
+      continue;
+    }
+    traced[key] = {
+      source: sourceInfo.source,
+      raw: sourceInfo.raw,
+      parsed: value
+    };
+  }
+  return traced;
+}
+
+// src/validateExampleEnv.ts
+function validateExampleEnv(schema, exampleSource) {
+  const issues = [];
+  const flattenedSchema = flattenSchema(schema);
+  const expectedKeys = new Set(flattenedSchema.map((entry) => entry.envKey));
+  for (const entry of flattenedSchema) {
+    const { envKey } = entry;
+    if (!(envKey in exampleSource)) {
+      issues.push({
+        key: envKey,
+        code: "missing_example_key",
+        message: `Environment variable "${envKey}" is missing from .env.example.`
+      });
+    }
+  }
+  for (const key of Object.keys(exampleSource)) {
+    if (exampleSource[key] === void 0) {
+      continue;
+    }
+    if (expectedKeys.has(key)) {
+      continue;
+    }
+    issues.push({
+      key,
+      code: "unknown_example_key",
+      message: `Environment variable "${key}" in .env.example is not defined in the schema.`
+    });
+  }
+  return issues;
+}
+
+// src/readEnvFileSource.ts
+var import_node_fs2 = require("fs");
+var import_node_path3 = require("path");
+function stripQuotes(value) {
+  if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+    return value.slice(1, -1);
+  }
+  return value;
+}
+function readEnvFileSource(filePath) {
+  if (!(0, import_node_fs2.existsSync)(filePath)) {
+    return {};
+  }
+  const content = (0, import_node_fs2.readFileSync)(filePath, "utf8");
+  const source = {};
+  for (const line of content.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+    const equalsIndex = trimmed.indexOf("=");
+    if (equalsIndex === -1) {
+      continue;
+    }
+    const key = trimmed.slice(0, equalsIndex).trim();
+    const rawValue = trimmed.slice(equalsIndex + 1).trim();
+    if (!key) {
+      continue;
+    }
+    source[key] = stripQuotes(rawValue);
+  }
+  return source;
+}
+function resolveExampleEnvPath(cwd = process.cwd(), exampleFile = ".env.example") {
+  return (0, import_node_path3.resolve)(cwd, exampleFile);
+}
+
+// src/validateExampleEnvFile.ts
+function validateExampleEnvFile(schema, options = {}) {
+  const filePath = resolveExampleEnvPath(options.cwd, options.exampleFile);
+  const exampleSource = readEnvFileSource(filePath);
+  return validateExampleEnv(schema, exampleSource);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EnvValidationError,
+  createEnv,
+  defineEnv,
+  maskEnv,
+  mergeSources,
+  readEnvFileSource,
+  resolveExampleEnvPath,
+  traceEnv,
+  validateExampleEnv,
+  validateExampleEnvFile
+});
+//# sourceMappingURL=index.cjs.map