dotenv-gad 1.4.1 → 1.4.2

package/README.md

@@ -1,8 +1,12 @@
 # dotenv-gad
 
 [![npm version](https://badge.fury.io/js/dotenv-gad.svg)](https://badge.fury.io/js/dotenv-gad)
+[![CI](https://github.com/kasimlyee/dotenv-gad/actions/workflows/ci.yml/badge.svg)](https://github.com/kasimlyee/dotenv-gad/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)
+[![TypeScript](https://img.shields.io/badge/TypeScript-first--class-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Docs](https://img.shields.io/badge/docs-latest-blue?style=flat-square)](https://kasimlyee.github.io/dotenv-gad/)
+[![npm downloads](https://img.shields.io/npm/dm/dotenv-gad.svg)](https://www.npmjs.com/package/dotenv-gad)
 
 **dotenv-gad** is an environment variable validation library that brings type safety, schema validation, and runtime checks to your Node.js and JavaScript applications. It works with any environment variable source — `.env` files, platform dashboards (Vercel, Railway, Docker), CI/CD pipelines, or `process.env` directly.
 

package/dist/client.cjs

@@ -0,0 +1,32 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/client.ts
+var client_exports = {};
+__export(client_exports, {
+  default: () => client_default,
+  env: () => env
+});
+module.exports = __toCommonJS(client_exports);
+var env = {};
+var client_default = env;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  env
+});

package/dist/index.cjs

@@ -0,0 +1,436 @@
+"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 src_exports = {};
+__export(src_exports, {
+  AggregateError: () => AggregateError,
+  EnvAggregateError: () => EnvAggregateError,
+  EnvValidationError: () => EnvValidationError,
+  EnvValidator: () => EnvValidator,
+  composeSchema: () => composeSchema,
+  createEnvProxy: () => createEnvProxy,
+  defineSchema: () => defineSchema,
+  loadEnv: () => loadEnv,
+  validateEnv: () => validateEnv
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/errors.ts
+var EnvValidationError = class extends Error {
+  constructor(key, message, receiveValue) {
+    super(message);
+    this.key = key;
+    this.message = message;
+    this.receiveValue = receiveValue;
+    this.name = "EnvValidationError";
+  }
+};
+var EnvAggregateError = class _EnvAggregateError extends Error {
+  constructor(errors, message) {
+    super(message);
+    this.errors = errors;
+    this.name = "EnvAggregateError";
+    Object.setPrototypeOf(this, _EnvAggregateError.prototype);
+  }
+  toString() {
+    const errorList = this.errors.map((e) => {
+      let msg = `  - ${e.key}: ${e.message}`;
+      if (e.value !== void 0)
+        msg += ` (received: ${JSON.stringify(e.value)})`;
+      if (e.rule?.docs) msg += `
+    ${e.rule.docs}`;
+      return msg;
+    }).join("\n");
+    return `${this.message}:
+${errorList}`;
+  }
+};
+var AggregateError = EnvAggregateError;
+
+// src/validator.ts
+var EnvValidator = class {
+  /**
+   * Constructs a new EnvValidator instance.
+   * @param {SchemaDefinition} schema The schema definition for the environment variables.
+   * @param {Object} [options] Optional options for the validation process.
+   * @param {boolean} [options.strict] When true, environment variables not present in the schema will be rejected.
+   */
+  constructor(schema, options) {
+    this.schema = schema;
+    this.options = options;
+  }
+  errors = [];
+  validate(env) {
+    this.errors = [];
+    const result = {};
+    const groupedEnv = {};
+    const prefixes = [];
+    for (const [k, r] of Object.entries(this.schema)) {
+      const eff = this.getEffectiveRule(k, r);
+      if (eff.type === "object" && eff.properties) {
+        const prefix = eff.envPrefix ?? `${k}_`;
+        prefixes.push({ key: k, prefix });
+        groupedEnv[k] = {};
+      }
+    }
+    const envKeys = Object.keys(env);
+    for (let i = 0; i < envKeys.length; i++) {
+      const eKey = envKeys[i];
+      for (let j = 0; j < prefixes.length; j++) {
+        const { key, prefix } = prefixes[j];
+        if (eKey.startsWith(prefix)) {
+          const subKey = eKey.slice(prefix.length);
+          groupedEnv[key][subKey] = env[eKey];
+        }
+      }
+    }
+    const schemaKeys = Object.keys(this.schema);
+    for (let i = 0; i < schemaKeys.length; i++) {
+      const key = schemaKeys[i];
+      const rule = this.schema[key];
+      try {
+        const valToValidate = groupedEnv[key] && Object.keys(groupedEnv[key]).length > 0 ? groupedEnv[key] : env[key];
+        if (groupedEnv[key] && Object.keys(groupedEnv[key]).length > 0 && env[key] !== void 0) {
+          console.warn(`Both prefixed variables and top-level ${key} exist; prefixed vars are used`);
+        }
+        if (this.options?.strict && groupedEnv[key] && Object.keys(groupedEnv[key]).length > 0) {
+          const propNames = rule.properties ? Object.keys(rule.properties) : [];
+          const extras = Object.keys(groupedEnv[key]).filter((s) => !propNames.includes(s));
+          if (extras.length > 0) {
+            this.errors.push({
+              key,
+              message: `Unexpected grouped environment variables: ${extras.join(", ")}`,
+              value: Object.keys(groupedEnv[key]),
+              rule
+            });
+            continue;
+          }
+        }
+        result[key] = this.validateKey(key, rule, valToValidate);
+      } catch (error) {
+        if (error instanceof Error) {
+          let displayedValue;
+          if (env[key] === void 0) {
+            displayedValue = void 0;
+          } else if (this.options?.includeRaw) {
+            if (rule.sensitive && !this.options?.includeSensitive) {
+              displayedValue = "****";
+            } else {
+              displayedValue = env[key];
+            }
+          } else {
+            displayedValue = this.redactValue(env[key], rule.sensitive);
+          }
+          this.errors.push({
+            key,
+            message: error.message,
+            value: displayedValue,
+            rule
+          });
+        }
+      }
+    }
+    if (this.options?.strict) {
+      const prefixedKeys = /* @__PURE__ */ new Set();
+      for (const p of prefixes) {
+        for (const eKey of envKeys) {
+          if (eKey.startsWith(p.prefix)) prefixedKeys.add(eKey);
+        }
+      }
+      for (const k of envKeys) {
+        if (!(k in this.schema) && !prefixedKeys.has(k)) {
+          this.errors.push({
+            key: k,
+            message: `Unexpected environment variable`
+          });
+        }
+      }
+    }
+    if (this.errors.length > 0) {
+      const keys = this.errors.map((e) => e.key).join(", ");
+      throw new EnvAggregateError(
+        this.errors,
+        `Environment validation failed: ${keys}`
+      );
+    }
+    return result;
+  }
+  // Redact or trim sensitive values for error reporting
+  redactValue(value, sensitive) {
+    if (value === void 0) return void 0;
+    if (sensitive) return "****";
+    if (typeof value !== "string") return value;
+    if (value.length > 64) {
+      return `${value.slice(0, 4)}...${value.slice(-4)}`;
+    }
+    return value;
+  }
+  // Try to quickly determine if a string *might* be JSON before parsing to avoid
+  // costly exceptions in the hot path for clearly non-JSON values.
+  tryParseJSON(value) {
+    if (typeof value !== "string") return { ok: false };
+    const s = value.trim();
+    if (!s) return { ok: false };
+    const c = s[0];
+    if (c !== "{" && c !== "[" && c !== '"' && c !== "t" && c !== "f" && c !== "n" && (c < "0" || c > "9") && c !== "-") {
+      return { ok: false };
+    }
+    try {
+      return { ok: true, value: JSON.parse(s) };
+    } catch {
+      return { ok: false };
+    }
+  }
+  validateKey(key, rule, value) {
+    const effectiveRule = this.getEffectiveRule(key, rule);
+    if (value === void 0 || value === "") {
+      if (effectiveRule.required)
+        throw new Error(`Missing required environment variable`);
+      return effectiveRule.default;
+    }
+    if (effectiveRule.transform) {
+      value = effectiveRule.transform(value);
+    }
+    switch (effectiveRule.type) {
+      case "string":
+        value = String(value).trim();
+        if (effectiveRule.minLength !== void 0 && value.length < effectiveRule.minLength) {
+          throw new Error(
+            `Environment variable ${key} must be at least ${effectiveRule.minLength} characters`
+          );
+        }
+        if (effectiveRule.maxLength !== void 0 && value.length > effectiveRule.maxLength) {
+          throw new Error(
+            `Environment variable ${key} must be at most ${effectiveRule.maxLength} characters`
+          );
+        }
+        break;
+      case "number":
+        value = Number(value);
+        if (isNaN(value)) {
+          throw new Error(`Environment variable ${key} must be a number`);
+        }
+        if (effectiveRule.min !== void 0 && value < effectiveRule.min) {
+          throw new Error(
+            `Environment variable ${key} must be at least ${effectiveRule.min}`
+          );
+        }
+        if (effectiveRule.max !== void 0 && value > effectiveRule.max) {
+          throw new Error(
+            `Environment variable ${key} must be at most ${effectiveRule.max}`
+          );
+        }
+        break;
+      case "boolean":
+        if (typeof value === "string") {
+          value = value.toLowerCase();
+          if (value === "true") {
+            value = true;
+          } else if (value === "false") {
+            value = false;
+          }
+        }
+        if (typeof value !== "boolean") {
+          throw new Error(
+            `Environment variable ${key} must be a boolean (true/false)`
+          );
+        }
+        value = Boolean(value);
+        break;
+      case "date":
+        const date = new Date(value);
+        if (isNaN(date.getTime())) {
+          throw new Error(`Environment variable ${key} must be a valid date`);
+        }
+        value = date;
+        break;
+      case "url":
+        try {
+          new URL(String(value));
+        } catch {
+          throw new Error("Must be a valid URL");
+        }
+        break;
+      case "email":
+        if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(String(value))) {
+          throw new Error("Must be a valid email");
+        }
+        break;
+      case "ip":
+        if (!/^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/.test(String(value))) {
+          throw new Error("Must be a valid IP address");
+        }
+        break;
+      case "port":
+        const port = Number(value);
+        if (isNaN(port) || !Number.isInteger(port)) throw new Error("Must be an integer");
+        if (port < 1 || port > 65535) {
+          throw new Error("Must be between 1 and 65535");
+        }
+        value = port;
+        break;
+      case "json":
+        const maybeJson = this.tryParseJSON(value);
+        if (!maybeJson.ok) {
+          throw new Error("Must be valid JSON");
+        }
+        value = maybeJson.value;
+        break;
+      case "array":
+        if (!Array.isArray(value)) {
+          const parsed = this.tryParseJSON(value);
+          if (!parsed.ok || !Array.isArray(parsed.value)) {
+            throw new Error("Must be a valid array or JSON array string");
+          }
+          value = parsed.value;
+        }
+        if (effectiveRule.items) {
+          value = value.map((item, i) => {
+            try {
+              return this.validateKey(
+                `${key}[${i}]`,
+                effectiveRule.items,
+                item
+              );
+            } catch (error) {
+              throw new Error(`Array item '${i}':${error.message}`);
+            }
+          });
+        }
+        break;
+      case "object":
+        if (typeof value === "string") {
+          const parsed = this.tryParseJSON(value);
+          if (!parsed.ok || typeof parsed.value !== "object" || Array.isArray(parsed.value)) {
+            throw new Error("Must be a valid object or JSON string");
+          }
+          value = parsed.value;
+        }
+        if (effectiveRule.properties) {
+          const obj = {};
+          for (const prop in effectiveRule.properties) {
+            if (!Object.prototype.hasOwnProperty.call(effectiveRule.properties, prop)) continue;
+            const propRule = effectiveRule.properties[prop];
+            try {
+              obj[prop] = this.validateKey(
+                `${key}.${prop}`,
+                propRule,
+                value[prop]
+              );
+            } catch (error) {
+              throw new Error(`Property '${prop}':${error.message}`);
+            }
+          }
+          value = obj;
+        }
+        break;
+    }
+    if (effectiveRule.enum && !effectiveRule.enum.includes(value)) {
+      throw new Error(
+        `Environment variable ${key} must be one of ${effectiveRule.enum.join(
+          ", "
+        )}`
+      );
+    }
+    if (effectiveRule.regex && !effectiveRule.regex.test(String(value))) {
+      throw new Error(
+        effectiveRule.regexError || `Environment variable ${key} must match ${effectiveRule.regex}`
+      );
+    }
+    if (effectiveRule.validate && !effectiveRule.validate(value)) {
+      throw new Error(effectiveRule.error || "Custom validation failed");
+    }
+    return value;
+  }
+  getEffectiveRule(key, rule) {
+    const envName = process.env.NODE_ENV || "development";
+    const envRule = rule.env?.[envName] || {};
+    return { ...rule, ...envRule };
+  }
+};
+
+// src/schema.ts
+function defineSchema(schema) {
+  return schema;
+}
+
+// src/utils.ts
+var import_dotenv = __toESM(require("dotenv"), 1);
+function loadEnv(schema, options) {
+  const fileEnv = import_dotenv.default.config({ debug: false, path: options?.path }).parsed || {};
+  const env = { ...process.env, ...fileEnv };
+  const validator = new EnvValidator(schema, options);
+  return validator.validate(env);
+}
+function createEnvProxy(validatedEnv) {
+  return new Proxy(validatedEnv, {
+    get(target, prop) {
+      if (typeof prop === "string" && !(prop in target)) {
+        throw new Error(
+          `Environment variable ${prop} is not validated`
+        );
+      }
+      return target[prop];
+    }
+  });
+}
+
+// src/compose.ts
+function composeSchema(...schemas) {
+  const result = /* @__PURE__ */ Object.create(null);
+  for (const schema of schemas) {
+    for (const key of Object.keys(schema)) {
+      if (key === "__proto__" || key === "constructor" || key === "prototype") continue;
+      result[key] = schema[key];
+    }
+  }
+  return result;
+}
+
+// src/index.ts
+var import_dotenv2 = __toESM(require("dotenv"), 1);
+function validateEnv(schema, options) {
+  const fileEnv = import_dotenv2.default.config({ debug: false, path: options?.path }).parsed || {};
+  const env = { ...process.env, ...fileEnv };
+  const validator = new EnvValidator(schema, options);
+  return validator.validate(env);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AggregateError,
+  EnvAggregateError,
+  EnvValidationError,
+  EnvValidator,
+  composeSchema,
+  createEnvProxy,
+  defineSchema,
+  loadEnv,
+  validateEnv
+});

package/dist/vite-plugin.js

@@ -71,7 +71,7 @@ function generateDtsContent(filteredKeys, schemaAbsPath, dtsAbsPath) {
         "// ──────────────────────────────────────────────────────────────",
         "",
         'declare module "dotenv-gad/client" {',
-        `  interface DotenvGadEnv extends ${envType} {}`,
+        `  export interface DotenvGadEnv extends ${envType} {}`,
         "  export const env: DotenvGadEnv;",
         "  export default env;",
         "}",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotenv-gad",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",
   "type": "module",
@@ -8,7 +8,7 @@
     "dotenv-gad": "./dist/cli/index.js"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && tsup",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -40,7 +40,8 @@
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
     },
     "./vite": {
       "types": "./dist/types/vite-plugin.d.ts",
@@ -48,12 +49,14 @@
     },
     "./client": {
       "types": "./dist/types/client.d.ts",
-      "import": "./dist/client.js"
+      "import": "./dist/client.js",
+      "require": "./dist/client.cjs"
     },
     "./package.json": "./package.json"
   },
   "files": [
     "dist/**/*.js",
+    "dist/**/*.cjs",
     "dist/**/*.d.ts",
     "README.md",
     "LICENSE"
@@ -78,6 +81,7 @@
     "globals": "^15.14.0",
     "husky": "^9.1.7",
     "prettier": "^3.4.2",
+    "tsup": "^8.5.1",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.19.1",
     "vite": "^6.0.0",