@ix-xs/node-comfort 1.2.0 → 2.1.0

package/src/Env.js

@@ -0,0 +1,689 @@
+"use strict";
+
+/**
+ * Environment variables you can trust: `.env` loading, typed getters, and
+ * `validate()` to check your whole configuration at startup and report
+ * every problem at once.
+ *
+ * The `.env` file in the working directory is loaded when the package is
+ * required; variables that are already set are never overwritten. Set
+ * `NODE_COMFORT_DOTENV=false` to turn that off. What it loaded has the
+ * lowest priority: a file you load yourself afterwards wins over it.
+ *
+ * @example
+ * const config = env.validate({
+ *   PORT: { type: "port", default: 3000 },
+ *   DATABASE_URL: { type: "url" },                  // required
+ *   CACHE_TTL: { type: "duration", default: "5m" }, // in ms
+ * });
+ * config.PORT; // a number, typed in your editor
+ */
+
+const fs = require("node:fs");
+const nodePath = require("node:path");
+const { ValidationError } = require("./errors.js");
+const { parseDuration } = require("./internal/shared.js");
+
+/**
+ * Options for `load()`.
+ * @typedef {object} EnvLoadOptions
+ * @property {boolean} [override] Overwrite variables that are already set.
+ * @property {boolean} [expand] Replace `${OTHER}` references. Defaults to `true`.
+ * @property {boolean} [required] Throw if a file is missing.
+ * @property {boolean | string} [cascade] Also load the files that go with each one: `.env.production.local`, `.env.local`, `.env.production`, then `.env`. `true` takes the mode from `NODE_ENV`; a string names it. `.env.local` is skipped in test mode, so tests run the same for everyone.
+ * @property {NodeJS.ProcessEnv} [target] Where to put the variables. Defaults to `process.env`.
+ */
+
+/**
+ * Options for `parse()`.
+ * @typedef {object} EnvParseOptions
+ * @property {boolean} [expand] Replace `$VAR`, `${VAR}` and `${VAR:-default}`. Defaults to `true`.
+ * @property {Record<string, string | undefined>} [env] Other variables usable in expansions. Defaults to `process.env`.
+ */
+
+/**
+ * Options shared by the typed getters.
+ * @template T
+ * @typedef {object} EnvGetterOptions
+ * @property {T} [default] Used when the variable is missing or empty. Without it, the variable is required.
+ * @property {boolean} [optional] Return `undefined` instead of throwing when it's missing.
+ * @property {NodeJS.ProcessEnv} [env] Where to read from. Defaults to `process.env`.
+ */
+
+/**
+ * One variable in `validate()`. It's required unless it has a `default` or
+ * `optional: true`.
+ *
+ * @typedef {(
+ *   { type: "string", default?: string, optional?: boolean, pattern?: RegExp, minLength?: number, description?: string } |
+ *   { type: "number", default?: number, optional?: boolean, min?: number, max?: number, integer?: boolean, description?: string } |
+ *   { type: "boolean", default?: boolean, optional?: boolean, description?: string } |
+ *   { type: "port", default?: number, optional?: boolean, description?: string } |
+ *   { type: "url", default?: string, optional?: boolean, protocols?: string[], description?: string } |
+ *   { type: "email", default?: string, optional?: boolean, description?: string } |
+ *   { type: "duration", default?: number | string, optional?: boolean, description?: string } |
+ *   { type: "list", default?: string[], optional?: boolean, separator?: string, description?: string } |
+ *   { type: "json", default?: unknown, optional?: boolean, description?: string } |
+ *   { type: "enum", values: readonly string[], default?: string, optional?: boolean, description?: string }
+ * )} EnvVarSpec
+ */
+
+/**
+ * The type a variable gets once read.
+ * @template {EnvVarSpec} S
+ * @typedef {S["type"] extends "number" | "port" | "duration" ? number : S["type"] extends "boolean" ? boolean : S["type"] extends "list" ? string[] : S["type"] extends "json" ? any : S extends { values: readonly (infer V)[] } ? V : string} EnvVarValue
+ */
+
+/**
+ * What `validate()` returns.
+ * @template {Record<string, EnvVarSpec>} T
+ * @typedef {{ -readonly [K in keyof T]: T[K] extends { optional: true } ? EnvVarValue<T[K]> | undefined : EnvVarValue<T[K]> }} EnvConfig
+ */
+
+const _TRUE = ["true", "1", "yes", "y", "on"];
+const _FALSE = ["false", "0", "no", "n", "off", ""];
+
+/**
+ * Reads a variable, ignoring what objects inherit: without this,
+ * `TOSTRING` is fine but `toString` would come back as a function.
+ * @param {Record<string, string | undefined>} source
+ * @param {string} name
+ * @returns {string | undefined}
+ */
+const _raw = (source, name) => (Object.hasOwn(source, name) ? source[name] : undefined);
+
+/**
+ * @param {string} name
+ * @param {string} code
+ * @param {string} message
+ * @returns {never}
+ */
+const _fail = (name, code, message) => {
+  throw new ValidationError([{ path: [name], code, message }], { message: `Environment variable ${name}: ${message}` });
+};
+
+/**
+ * @param {string} name
+ * @param {string} raw
+ * @param {EnvVarSpec} spec
+ * @returns {unknown}
+ */
+const _convert = (name, raw, spec) => {
+  const value = raw.trim();
+  switch (spec.type) {
+    case "string": {
+      if (spec.minLength !== undefined && value.length < spec.minLength) _fail(name, "too_small", `must contain at least ${spec.minLength} characters`);
+      if (spec.pattern && !spec.pattern.test(value)) _fail(name, "invalid_string", `does not match ${spec.pattern}`);
+      return raw;
+    }
+    case "number": {
+      const n = Number(value);
+      if (value === "" || !Number.isFinite(n)) _fail(name, "invalid_type", `must be a number, got "${raw}"`);
+      if (spec.integer && !Number.isInteger(n)) _fail(name, "invalid_type", `must be an integer, got "${raw}"`);
+      if (spec.min !== undefined && n < spec.min) _fail(name, "too_small", `must be >= ${spec.min}, got ${n}`);
+      if (spec.max !== undefined && n > spec.max) _fail(name, "too_big", `must be <= ${spec.max}, got ${n}`);
+      return n;
+    }
+    case "port": {
+      const n = Number(value);
+      if (!/^\d+$/.test(value) || n < 0 || n > 65535) _fail(name, "invalid_type", `must be a port number (0-65535), got "${raw}"`);
+      return n;
+    }
+    case "boolean": {
+      const lower = value.toLowerCase();
+      if (_TRUE.includes(lower)) return true;
+      if (_FALSE.includes(lower)) return false;
+      return _fail(name, "invalid_type", `must be a boolean (true/false, 1/0, yes/no, on/off), got "${raw}"`);
+    }
+    case "url": {
+      try {
+        const url = new URL(value);
+        if (spec.protocols && !spec.protocols.map((p) => p.replace(/:?$/, ":")).includes(url.protocol)) {
+          _fail(name, "invalid_string", `must use one of these protocols: ${spec.protocols.join(", ")}`);
+        }
+        return value;
+      } catch (error) {
+        if (error instanceof ValidationError) throw error;
+        return _fail(name, "invalid_string", `must be a valid URL, got "${raw}"`);
+      }
+    }
+    case "email": {
+      const { isEmail } = require("./Checker.js");
+      if (!isEmail(value)) _fail(name, "invalid_string", `must be an email address, got "${raw}"`);
+      return value;
+    }
+    case "duration": {
+      const ms = parseDuration(value);
+      if (ms === null) _fail(name, "invalid_type", `must be a duration such as "30s", "5m" or "1h", got "${raw}"`);
+      return ms;
+    }
+    case "list":
+      return value === "" ? [] : value.split(spec.separator ?? ",").map((item) => item.trim()).filter((item) => item !== "");
+    case "json":
+      try {
+        return JSON.parse(value);
+      } catch {
+        return _fail(name, "invalid_type", "must be valid JSON");
+      }
+    case "enum":
+      if (!spec.values.includes(value)) _fail(name, "invalid_enum_value", `must be one of: ${spec.values.join(", ")} (got "${raw}")`);
+      return value;
+    default:
+      return raw;
+  }
+};
+
+/**
+ * @param {string} name
+ * @param {EnvVarSpec & { optional?: boolean }} spec
+ * @param {NodeJS.ProcessEnv} source
+ * @returns {unknown}
+ */
+const _read = (name, spec, source) => {
+  const raw = _raw(source, name);
+  if (raw === undefined || raw.trim() === "") {
+    if ("default" in spec && spec.default !== undefined) {
+      return spec.type === "duration" && typeof spec.default === "string" ? _convert(name, spec.default, spec) : spec.default;
+    }
+    if (spec.optional) return undefined;
+    return _fail(name, "required", `is required but is not set${spec.description ? ` (${spec.description})` : ""}`);
+  }
+  return _convert(name, raw, spec);
+};
+
+const _LINE = /^[ \t]*(?:export[ \t]+)?([\w.-]+)[ \t]*[=:][ \t]*(?:("(?:\\.|[^"\\])*"|'[^']*'|`[^`]*`)[ \t]*(?:#[^\n]*)?|([^\n]*))$/gm;
+const _ESCAPE = /\\([nrt"\\$])/g;
+const _REFERENCE = /\\\$|\$\{([\w.]+)(?::?-([^}]*))?\}|\$([A-Za-z_]\w*)/g;
+/** @type {Record<string, string>} */
+const _ESCAPED = { n: "\n", r: "\r", t: "\t" };
+
+/**
+ * Parses the text of a `.env` file: quotes, multi-line values, `export`,
+ * comments, escapes, and `${VAR}` expansion (except in single quotes).
+ *
+ * @example
+ * env.parse('PORT=3000\nURL="http://localhost:${PORT}"');
+ * // { PORT: "3000", URL: "http://localhost:3000" }
+ *
+ * @param {string} content
+ * @param {EnvParseOptions} [options]
+ * @returns {Record<string, string>}
+ */
+function parse(content, options = {}) {
+  return _parse(content, options);
+}
+
+/**
+ * @param {string} content
+ * @param {EnvParseOptions} options
+ * @param {(name: string) => string | undefined} [wins] Values that a reference takes before the file's own: what the variable will really be once loaded.
+ * @returns {Record<string, string>}
+ */
+function _parse(content, options, wins) {
+  // A Map, so that a variable called __proto__ or toString is a variable like any other.
+  /** @type {Map<string, string>} */
+  const out = new Map();
+  /** @type {Set<string>} */
+  const literal = new Set();
+  const text = String(content).replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+  for (const [, key, quoted, bare] of text.matchAll(_LINE)) {
+    let value;
+    if (quoted !== undefined) {
+      const quote = quoted[0];
+      value = quoted.slice(1, -1);
+      if (quote === '"') value = value.replace(_ESCAPE, (_, char) => _ESCAPED[char] ?? char);
+      if (quote === "'") literal.add(key);
+      else literal.delete(key);
+    } else {
+      value = (bare ?? "").replace(/(?:^|[ \t]+)#.*$/, "").trim();
+      literal.delete(key);
+    }
+    out.set(key, value);
+  }
+  if (options.expand !== false) {
+    const base = options.env ?? process.env;
+    /**
+     * @param {string} name
+     * @param {string[]} seen The variables being expanded, to stop at a loop.
+     * @returns {string}
+     */
+    const resolve = (name, seen) => {
+      if (seen.includes(name)) return "";
+      const winner = wins?.(name);
+      if (winner !== undefined) return winner;
+      const own = out.get(name);
+      return own !== undefined ? expand(own, [...seen, name], name) : _raw(base, name) ?? "";
+    };
+    /**
+     * @param {string} value
+     * @param {string[]} seen
+     * @param {string} key
+     * @returns {string}
+     */
+    const expand = (value, seen, key) => {
+      if (literal.has(key) || !value.includes("$")) return value;
+      return value.replace(_REFERENCE, (match, braced, fallback, plain) => {
+        if (match === "\\$") return "$";
+        const resolved = resolve(braced ?? plain, seen);
+        return resolved === "" && fallback !== undefined ? fallback : resolved;
+      });
+    };
+    for (const [key, value] of out) out.set(key, expand(value, [key], key));
+  }
+  return Object.fromEntries(out);
+}
+
+/**
+ * What the automatic load of `.env` put in `process.env`. A later `load()`
+ * may replace these values, as long as nobody changed them in between: they
+ * came from a file, not from the real environment.
+ * @type {Map<string, string>}
+ */
+const _automatic = new Map();
+let _loadingAutomatically = false;
+
+/**
+ * The files that go with a `.env` file, most specific first.
+ * @param {string} file
+ * @param {string} mode
+ * @returns {string[]}
+ */
+const _cascade = (file, mode) => [`${file}.${mode}.local`, ...(mode === "test" ? [] : [`${file}.local`]), `${file}.${mode}`, file];
+
+/**
+ * Loads `.env` files into `process.env`. The first file to set a variable
+ * wins, and variables that are already set are kept, unless you pass
+ * `override`. The `.env` loaded by itself at startup doesn't count as
+ * already set: `.env.local` wins over it, as you'd expect.
+ *
+ * @example
+ * env.load();                                // ./.env
+ * env.load([".env.local", ".env"]);          // local values win
+ * env.load(".env.test", { override: true });
+ * env.load(".env", { cascade: true });       // .env.production.local, .env.local, .env.production, .env
+ *
+ * @param {string | string[]} [files=".env"] Relative to the working directory.
+ * @param {EnvLoadOptions} [options]
+ * @returns {Record<string, string>} Everything read from the files.
+ * @throws {Error} If `required` is set and a file is missing.
+ */
+function load(files = ".env", options = {}) {
+  const target = options.target ?? process.env;
+  const given = Array.isArray(files) ? files : [files];
+  const cascade = options.cascade === true ? mode() : options.cascade;
+  const own = target === process.env;
+  /** @type {Map<string, string>} */
+  const loaded = new Map();
+  /**
+   * The value a variable already has and keeps, whatever the files say.
+   * @param {string} key
+   * @returns {string | undefined}
+   */
+  const kept = (key) => {
+    if (options.override) return undefined;
+    const current = _raw(target, key);
+    return current !== undefined && !(own && _automatic.get(key) === current) ? current : undefined;
+  };
+  // A reference such as ${HOST} takes the value HOST ends up with, not the
+  // one of a file that lost.
+  const wins = (/** @type {string} */ key) => loaded.get(key) ?? kept(key);
+  for (const name of given) {
+    for (const file of cascade ? _cascade(name, cascade) : [name]) {
+      const full = nodePath.resolve(process.cwd(), file);
+      let content;
+      try {
+        content = fs.readFileSync(full, "utf8");
+      } catch (error) {
+        // Only the file you named has to exist, not the ones that go with it.
+        if (options.required && file === name) throw new Error(`Environment file not found: ${full}`, { cause: error });
+        continue;
+      }
+      const values = _parse(content, { expand: options.expand, env: target }, wins);
+      for (const [key, value] of Object.entries(values)) {
+        if (!loaded.has(key)) loaded.set(key, value);
+      }
+    }
+  }
+  for (const [key, value] of loaded) {
+    if (kept(key) !== undefined) continue;
+    target[key] = value;
+    if (!own) continue;
+    if (_loadingAutomatically) _automatic.set(key, value);
+    else _automatic.delete(key);
+  }
+  return Object.fromEntries(loaded);
+}
+
+/**
+ * Reads a variable, with a fallback. Never throws.
+ *
+ * @example
+ * env.get("REGION", "eu-west-1");
+ *
+ * @param {string} name
+ * @param {string} [fallback]
+ * @returns {string | undefined}
+ */
+function get(name, fallback) {
+  return _raw(process.env, name) ?? fallback;
+}
+
+/**
+ * Is the variable set, even to an empty string?
+ *
+ * @param {string} name
+ * @returns {boolean}
+ */
+function has(name) {
+  return _raw(process.env, name) !== undefined;
+}
+
+/**
+ * Reads a variable that must be set and not empty.
+ *
+ * @example
+ * const key = env.required("STRIPE_SECRET_KEY");
+ *
+ * @param {string} name
+ * @returns {string}
+ * @throws {ValidationError} If it's missing or empty.
+ */
+function required(name) {
+  return /** @type {string} */ (_read(name, { type: "string" }, process.env));
+}
+
+/**
+ * Reads a string. Required unless you give a default or `optional`.
+ *
+ * @example
+ * env.string("APP_NAME", { default: "my-app" });
+ *
+ * @param {string} name
+ * @param {EnvGetterOptions<string> & { pattern?: RegExp, minLength?: number }} [options]
+ * @returns {string}
+ * @throws {ValidationError}
+ */
+function string(name, options = {}) {
+  return /** @type {string} */ (_read(name, { ...options, type: "string" }, options.env ?? process.env));
+}
+
+/**
+ * Reads a number.
+ *
+ * @example
+ * env.number("WORKERS", { default: 4, min: 1, integer: true });
+ *
+ * @param {string} name
+ * @param {EnvGetterOptions<number> & { min?: number, max?: number, integer?: boolean }} [options]
+ * @returns {number}
+ * @throws {ValidationError}
+ */
+function number(name, options = {}) {
+  return /** @type {number} */ (_read(name, { ...options, type: "number" }, options.env ?? process.env));
+}
+
+/**
+ * Reads a boolean: `true`/`false`, `1`/`0`, `yes`/`no` or `on`/`off`.
+ *
+ * @example
+ * if (env.bool("FEATURE_BETA", { default: false })) enableBeta();
+ *
+ * @param {string} name
+ * @param {EnvGetterOptions<boolean>} [options]
+ * @returns {boolean}
+ * @throws {ValidationError}
+ */
+function bool(name, options = {}) {
+  return /** @type {boolean} */ (_read(name, { ...options, type: "boolean" }, options.env ?? process.env));
+}
+
+/**
+ * Reads a port number.
+ *
+ * @example
+ * server.listen(env.port("PORT", { default: 3000 }));
+ *
+ * @param {string} name
+ * @param {EnvGetterOptions<number>} [options]
+ * @returns {number}
+ * @throws {ValidationError}
+ */
+function port(name, options = {}) {
+  return /** @type {number} */ (_read(name, { ...options, type: "port" }, options.env ?? process.env));
+}
+
+/**
+ * Reads an absolute URL.
+ *
+ * @example
+ * env.url("DATABASE_URL", { protocols: ["postgres", "postgresql"] });
+ *
+ * @param {string} name
+ * @param {EnvGetterOptions<string> & { protocols?: string[] }} [options]
+ * @returns {string}
+ * @throws {ValidationError}
+ */
+function url(name, options = {}) {
+  return /** @type {string} */ (_read(name, { ...options, type: "url" }, options.env ?? process.env));
+}
+
+/**
+ * Reads a duration like `"30s"` or `"1h30m"` and returns milliseconds.
+ *
+ * @example
+ * env.duration("CACHE_TTL", { default: "10m" }); // 600000
+ *
+ * @param {string} name
+ * @param {EnvGetterOptions<number | string>} [options]
+ * @returns {number}
+ * @throws {ValidationError}
+ */
+function duration(name, options = {}) {
+  return /** @type {number} */ (_read(name, { ...options, type: "duration" }, options.env ?? process.env));
+}
+
+/**
+ * Reads a comma-separated list. Items are trimmed and empty ones dropped.
+ *
+ * @example
+ * // ALLOWED_ORIGINS="https://a.com, https://b.com"
+ * env.list("ALLOWED_ORIGINS", { default: [] }); // ["https://a.com", "https://b.com"]
+ *
+ * @param {string} name
+ * @param {EnvGetterOptions<string[]> & { separator?: string }} [options]
+ * @returns {string[]}
+ * @throws {ValidationError}
+ */
+function list(name, options = {}) {
+  return /** @type {string[]} */ (_read(name, { ...options, type: "list" }, options.env ?? process.env));
+}
+
+/**
+ * Reads a JSON value.
+ *
+ * @example
+ * const flags = env.json("FEATURE_FLAGS", { default: {} });
+ *
+ * @template [T=any]
+ * @param {string} name
+ * @param {EnvGetterOptions<T>} [options]
+ * @returns {T}
+ * @throws {ValidationError}
+ */
+function json(name, options = {}) {
+  return /** @type {T} */ (_read(name, { ...options, type: "json" }, options.env ?? process.env));
+}
+
+/**
+ * Reads a variable that must be one of the given values. The result has
+ * their literal type.
+ *
+ * @example
+ * env.oneOf("LOG_LEVEL", ["debug", "info", "warn", "error"], { default: "info" });
+ *
+ * @template {string} V
+ * @param {string} name
+ * @param {readonly V[]} values
+ * @param {EnvGetterOptions<V>} [options]
+ * @returns {V}
+ * @throws {ValidationError}
+ */
+function oneOf(name, values, options = {}) {
+  return /** @type {V} */ (_read(name, { ...options, type: "enum", values }, options.env ?? process.env));
+}
+
+/**
+ * Checks all your variables at once and returns a typed, frozen config. If
+ * anything is wrong, one `ValidationError` lists every problem, so a bad
+ * deployment fails at startup with the full picture.
+ *
+ * @example
+ * const config = env.validate({
+ *   NODE_ENV: { type: "enum", values: ["development", "production", "test"], default: "development" },
+ *   PORT: { type: "port", default: 3000 },
+ *   DATABASE_URL: { type: "url", protocols: ["postgres"] },
+ *   JWT_SECRET: { type: "string", minLength: 32 },
+ *   SENTRY_DSN: { type: "url", optional: true },
+ * });
+ * // ValidationError: Validation failed with 2 issues:
+ * //   • DATABASE_URL: is required but is not set
+ * //   • JWT_SECRET: must contain at least 32 characters
+ *
+ * @template {Record<string, EnvVarSpec>} T
+ * @param {T} spec
+ * @param {{ env?: NodeJS.ProcessEnv }} [options]
+ * @returns {Readonly<EnvConfig<T>>}
+ * @throws {ValidationError}
+ */
+function validate(spec, options = {}) {
+  const source = options.env ?? process.env;
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  /** @type {import("./errors").ValidationIssue[]} */
+  const issues = [];
+  for (const [name, varSpec] of Object.entries(spec)) {
+    try {
+      out[name] = _read(name, varSpec, source);
+    } catch (error) {
+      if (error instanceof ValidationError) issues.push(...error.issues);
+      else throw error;
+    }
+  }
+  if (issues.length) throw new ValidationError(issues);
+  return /** @type {any} */ (Object.freeze(out));
+}
+
+/**
+ * Quotes a value when spaces, `#` or `$` would otherwise change its meaning.
+ * @param {string} text
+ */
+const _quote = (text) => {
+  if (!/[\s#"'`$\\]/.test(text)) return text;
+  if (!text.includes("'") && !text.includes("\n")) return `'${text}'`;
+  return `"${text.replace(/[\\"$]/g, "\\$&").replace(/\n/g, "\\n")}"`;
+};
+
+/**
+ * Writes the `.env.example` that goes with a `validate()` spec: one entry
+ * per variable, with its description, type and default. Keep the file in
+ * the repository so nobody has to read the code to know what to set.
+ *
+ * @example
+ * const spec = {
+ *   PORT: { type: "port", default: 3000, description: "Port to listen on" },
+ *   DATABASE_URL: { type: "url", description: "Postgres connection string" },
+ * };
+ * fs.writeFileSync(".env.example", env.example(spec));
+ * // # Port to listen on
+ * // # port, default: 3000
+ * // PORT=3000
+ * //
+ * // # Postgres connection string
+ * // # url, required
+ * // DATABASE_URL=
+ *
+ * @param {Record<string, EnvVarSpec>} spec
+ * @returns {string}
+ */
+function example(spec) {
+  const blocks = [];
+  for (const [name, entry] of Object.entries(spec)) {
+    const fallback = "default" in entry && entry.default !== undefined ? entry.default : undefined;
+    const text = fallback === undefined ? "" : Array.isArray(fallback) ? fallback.join(entry.type === "list" ? entry.separator ?? "," : ",") : typeof fallback === "object" ? JSON.stringify(fallback) : String(fallback);
+    const kind = entry.type === "enum" ? entry.values.join(" | ") : entry.type;
+    const lines = [];
+    if (entry.description) lines.push(...entry.description.split(/\r?\n/).map((line) => `# ${line}`));
+    lines.push(`# ${kind}, ${fallback !== undefined ? `default: ${text}` : entry.optional ? "optional" : "required"}`);
+    lines.push(`${name}=${_quote(text)}`);
+    blocks.push(lines.join("\n"));
+  }
+  return `${blocks.join("\n\n")}\n`;
+}
+
+/**
+ * `NODE_ENV`, or `"development"` when it's not set.
+ *
+ * @returns {string}
+ */
+function mode() {
+  return process.env.NODE_ENV || "development";
+}
+
+/**
+ * Is `NODE_ENV` set to `"production"`?
+ * @returns {boolean}
+ */
+function isProduction() {
+  return mode() === "production";
+}
+
+/**
+ * Is `NODE_ENV` `"development"`, or not set?
+ * @returns {boolean}
+ */
+function isDevelopment() {
+  return mode() === "development";
+}
+
+/**
+ * Are we running tests? True when `NODE_ENV` is `"test"` or a test runner
+ * like `node --test` or Jest is detected.
+ * @returns {boolean}
+ */
+function isTest() {
+  return mode() === "test" || process.env.NODE_TEST_CONTEXT !== undefined || process.env.JEST_WORKER_ID !== undefined;
+}
+
+if (String(process.env.NODE_COMFORT_DOTENV).toLowerCase() !== "false") {
+  _loadingAutomatically = true;
+  try {
+    load(".env");
+  } catch {
+    // A broken .env file must never prevent the application from starting.
+  }
+  _loadingAutomatically = false;
+}
+
+module.exports = {
+  parse,
+  load,
+  // not shorthand: Node's ES module export detection stops at a bare `get`
+  get: get,
+  has,
+  required,
+  string,
+  number,
+  bool,
+  port,
+  url,
+  duration,
+  list,
+  json,
+  oneOf,
+  validate,
+  example,
+  mode,
+  isProduction,
+  isDevelopment,
+  isTest,
+};