dotenv-gad 1.4.0 → 1.4.2

package/README.md

@@ -1,18 +1,23 @@
 # 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)
-[![Docs](https://img.shields.io/badge/docs-latest-blue?style=flat-square)](https://kasimlyee.github.io/dotenv-gad/latest/)
-
-**dotenv-gad** is an environment variable validation tool that brings type safety and schema validation to your Node.js and JavaScript applications. It extends `dotenv` with features like:
-
-- Type-safe environment variables
-- Schema validation
-- Schema composition
-- Automatic documentation generation
-- TypeScript support
-- CLI tooling
-- Secret management
+[![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.
+
+- Type-safe environment variables with full IntelliSense
+- Schema validation (string, number, boolean, url, email, ip, port, json, array, object)
+- Schema composition for modular configs
+- Automatic documentation and `.env.example` generation
+- First-class TypeScript support
+- CLI tooling (check, sync, types, init, fix, docs)
+- Sensitive value management and redaction
+- Vite plugin with client-safe filtering and HMR
 
 ## Installation
 
@@ -55,22 +60,13 @@ const env = loadEnv(schema);
 console.log(`Server running on port ${env.PORT}`);
 ```
 
-Documentation
-
-[![Docs](https://img.shields.io/badge/docs-latest-blue?style=flat-square)](https://kasimlyee.github.io/dotenv-gad/latest/)
-
-Full documentation is available via GitHub Pages (published from `docs/`).
-
-To preview locally:
+`loadEnv` reads from both `process.env` and your `.env` file (if present). This means it works out of the box on platforms like Vercel, Railway, Docker, and AWS Lambda where variables are injected into `process.env` directly — no `.env` file required.
 
-```bash
-npm ci
-npm run docs:serve
-```
+## Documentation
 
-Docs preview on PRs
+[![Docs](https://img.shields.io/badge/docs-latest-blue?style=flat-square)](https://kasimlyee.github.io/dotenv-gad/)
 
-When you open or update a pull request that changes docs, an automated preview will be published to GitHub Pages under `previews/pr-<number>/` and a comment with the preview link will be posted on the PR. This makes it easy to review documentation changes without merging.
+Full documentation is available at [kasimlyee.github.io/dotenv-gad](https://kasimlyee.github.io/dotenv-gad/).
 
 ## CLI Commands
 
@@ -90,11 +86,12 @@ npx dotenv-gad types
 
 ## Vite Plugin
 
-The Vite plugin provides build-time environment variable validation with automatic client-safe filtering for browser-based applications.
+The Vite plugin validates environment variables at build time and exposes a typed, client-safe subset to your browser code via a virtual module.
 
-### Add to your `vite.config.ts`:
+### Setup
 
 ```typescript
+// vite.config.ts
 import { defineConfig } from "vite";
 import dotenvGad from "dotenv-gad/vite";
 
@@ -102,38 +99,39 @@ export default defineConfig({
   plugins: [
     dotenvGad({
       schemaPath: "./env.schema.ts",
-      clientPrefix: "VITE_", // Default prefix for client-safe variables
-      publicKeys: [], // Additional non-prefixed keys to expose
-      generatedTypes: true, // Generate dotenv-gad.d.ts for IntelliSense
+      // clientPrefix: "VITE_",   // default — keys matching this prefix are exposed
+      // publicKeys: [],          // additional non-prefixed keys to expose
+      // generatedTypes: true,    // generate .d.ts for IntelliSense
     }),
   ],
 });
 ```
 
-### Use validated environment variables in your app:
+### Usage
 
 ```typescript
 import { env } from "dotenv-gad/client";
 
-console.log(env.VITE_API_URL); // Full type safety & validation
+console.log(env.VITE_API_URL); // Full type safety & autocomplete
 ```
 
 ### Key Features
 
-- **Build-time validation**: Environment checked every dev/build cycle
-- **Client-safe filtering**: Only `VITE_` prefixed variables (or custom `publicKeys`) exposed to browser
-- **Automatic TypeScript types**: Generated `dotenv-gad.d.ts` for full IntelliSense
-- **Sensitive protection**: Variables marked `sensitive: true` are excluded by default
-- **HMR support**: Hot reload on `.env` changes during development
+- **Build-time validation** — environment checked every dev/build cycle
+- **Client-safe filtering** — only `VITE_*` prefixed variables (or custom `publicKeys`) exposed to browser
+- **Sensitive protection** — variables marked `sensitive: true` are always excluded
+- **Auto-generated types** — `dotenv-gad.d.ts` gives full IntelliSense on `env.`
+- **HMR support** — hot reload on `.env` or schema changes during development
+- **SSR safety** — server-side code gets the full env, not the filtered subset
 
 ## Features
 
 ### Core Validation
 
-- Type checking (string, number, boolean, array, object)
-- Required/optional fields
-- Default values
+- Type checking (string, number, boolean, array, object, url, email, ip, port, json, date)
+- Required/optional fields with defaults
 - Custom validation functions
+- Value transforms
 - Environment-specific rules
 
 ### Advanced Types
@@ -150,13 +148,23 @@ console.log(env.VITE_API_URL); // Full type safety & validation
 }
 ```
 
-### CLI Features
+### Schema Composition
 
-- Color-coded output
-- Interactive fixes
-- Strict mode
-- Custom schema paths
-- CI/CD friendly
+Merge multiple schemas for modular configuration:
+
+```typescript
+import { defineSchema, composeSchema } from "dotenv-gad";
+
+const baseSchema = defineSchema({
+  NODE_ENV: { type: "string", default: "development" },
+});
+
+const dbSchema = defineSchema({
+  DATABASE_URL: { type: "string", required: true, sensitive: true },
+});
+
+const schema = composeSchema(baseSchema, dbSchema);
+```
 
 ### Secret Management
 
@@ -164,12 +172,37 @@ console.log(env.VITE_API_URL); // Full type safety & validation
 {
   API_KEY: {
     type: 'string',
-    sensitive: true, // Excluded from .env.example
+    sensitive: true,       // masked in errors, excluded from .env.example
     validate: (val) => val.startsWith('sk_')
   }
 }
 ```
 
+### Grouping / Namespaced Envs
+
+Group related variables into a single validated object:
+
+```typescript
+const schema = defineSchema({
+  DATABASE: {
+    type: "object",
+    envPrefix: "DATABASE_", // optional; defaults to 'DATABASE_'
+    properties: {
+      DB_NAME: { type: "string", required: true },
+      PORT: { type: "port", default: 5432 },
+      PWD: { type: "string", sensitive: true },
+    },
+  },
+});
+```
+
+Given `DATABASE_DB_NAME=mydb`, `DATABASE_PORT=5432`, `DATABASE_PWD=supersecret`:
+
+```typescript
+const env = loadEnv(schema);
+// { DATABASE: { DB_NAME: 'mydb', PORT: 5432, PWD: 'supersecret' } }
+```
+
 ## Framework Integrations
 
 ### Express.js
@@ -189,8 +222,6 @@ app.listen(env.PORT, () => {
 
 ### Next.js
 
-Create `next.config.js`:
-
 ```javascript
 const { loadEnv } = require("dotenv-gad");
 const schema = require("./env.schema");
@@ -204,9 +235,7 @@ module.exports = {
 };
 ```
 
-## Validation Reports
-
-Example error output:
+## Error Reporting
 
 ```
 Environment validation failed:
@@ -215,38 +244,20 @@ Environment validation failed:
   - API_KEY: Must start with 'sk_' (received: "invalid")
 ```
 
-By default values in the report are redacted (sensitive values are always masked). You can opt-in to include raw values in error reports when instantiating the validator (useful for local debugging) by using the `includeRaw` option. If you also want to reveal values marked as `sensitive: true` set `includeSensitive` to `true` (use with caution).
+Sensitive values are always masked in error output. Use `includeRaw` for local debugging:
 
-```ts
-// include raw values in errors (non-sensitive values only)
-import { loadEnv } from "dotenv-gad";
+```typescript
 const env = loadEnv(schema, { includeRaw: true });
 
 // or with finer control
 import { EnvValidator } from "dotenv-gad";
-const validator = new EnvValidator(schema, { includeRaw: true, includeSensitive: true });
-try {
-  validator.validate(process.env);
-} catch (err) {
-  console.error(String(err));
-}
+const validator = new EnvValidator(schema, {
+  includeRaw: true,
+  includeSensitive: true,
+});
 ```
 
-## more usages
-
-### Environment-Specific Rules
-
-```typescript
-{
-  DEBUG: {
-    type: 'boolean',
-    env: {
-      development: { default: true },
-      production: { default: false }
-    }
-  }
-}
-```
+## More Examples
 
 ### Custom Validators
 
@@ -260,7 +271,7 @@ try {
 }
 ```
 
-### Transformations
+### Transforms
 
 ```typescript
 {
@@ -271,49 +282,22 @@ try {
 }
 ```
 
-### Grouping / Namespaced envs
-
-You can group related environment variables into a single object using `object` with `properties` and an optional `envPrefix` (defaults to `KEY_`):
+### Environment-Specific Rules
 
-```ts
-const schema = defineSchema({
-  DATABASE: {
-    type: 'object',
-    envPrefix: 'DATABASE_', // optional; defaults to 'DATABASE_'
-    properties: {
-      DB_NAME: { type: 'string', required: true },
-      PORT: { type: 'port', default: 5432 },
-      PWD: { type: 'string', sensitive: true }
+```typescript
+{
+  DEBUG: {
+    type: 'boolean',
+    env: {
+      development: { default: true },
+      production: { default: false }
     }
   }
-});
-```
-
-Given the following environment:
-
-```
-DATABASE_DB_NAME=mydb
-DATABASE_PORT=5432
-DATABASE_PWD=supersecret
-```
-
-`loadEnv(schema)` will return:
-
-```ts
-{ DATABASE: { DB_NAME: 'mydb', PORT: 5432, PWD: 'supersecret' } }
+}
 ```
 
-Notes and behavior:
-
-- The default `envPrefix` is `${KEY}_` (for `DATABASE` it's `DATABASE_`) if you don't specify `envPrefix`.
-- Prefixed variables take precedence over a JSON top-level env var (e.g., `DATABASE` = '{...}'). If both are present, prefixed variables win and a warning is printed.
-- In strict mode (`{ strict: true }`), unexpected subkeys inside a group (e.g., `DATABASE_EXTRA`) will cause validation to fail.
-- `sensitive` and `includeRaw` behavior still applies for grouped properties: sensitive properties are still masked in errors unless `includeSensitive` is explicitly set.
-
-The CLI `sync` command will now generate grouped entries in `.env.example` for object properties so it's easier to scaffold grouped configuration.
-
 ## License
 
 MIT © [Kasim Lyee]
 
-[Contributions](https://github.com/kasimlyee/dotenv-gad/blob/main/CONTRIBUTING.md) are welcome!!
+[Contributions](https://github.com/kasimlyee/dotenv-gad/blob/main/CONTRIBUTING.md) are welcome!

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/index.js

@@ -8,7 +8,8 @@ export { defineSchema, EnvAggregateError,
 /** @deprecated Use `EnvAggregateError` instead. */
 AggregateError, EnvValidationError, EnvValidator, loadEnv, createEnvProxy, composeSchema, };
 export function validateEnv(schema, options) {
-    const env = dotenv.config({ debug: false, path: options?.path }).parsed || {};
+    const fileEnv = dotenv.config({ debug: false, path: options?.path }).parsed || {};
+    const env = { ...process.env, ...fileEnv };
     const validator = new EnvValidator(schema, options);
     return validator.validate(env);
 }

package/dist/utils.js

@@ -14,7 +14,8 @@ import { EnvValidator } from "./validator.js";
  * @returns {InferEnv<S>} The validated environment variables.
  */
 export function loadEnv(schema, options) {
-    const env = dotenv.config({ debug: false, path: options?.path }).parsed || {};
+    const fileEnv = dotenv.config({ debug: false, path: options?.path }).parsed || {};
+    const env = { ...process.env, ...fileEnv };
     const validator = new EnvValidator(schema, options);
     return validator.validate(env);
 }

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.0",
+  "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",