dotenv-gad 1.2.0 → 1.2.2

package/README.md

@@ -2,6 +2,7 @@
 
 [![npm version](https://badge.fury.io/js/dotenv-gad.svg)](https://badge.fury.io/js/dotenv-gad)
 [![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:
 
@@ -54,6 +55,23 @@ 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:
+
+```bash
+npm ci
+npm run docs:serve
+```
+
+Docs preview on PRs
+
+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.
+
 ## CLI Commands
 
 | Command | Description                        |
@@ -159,6 +177,23 @@ 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).
+
+```ts
+// include raw values in errors (non-sensitive values only)
+import { loadEnv } from "dotenv-gad";
+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));
+}
+```
+
 ## more usages
 
 ### Environment-Specific Rules
@@ -198,6 +233,47 @@ Environment validation failed:
 }
 ```
 
+### Grouping / Namespaced envs
+
+You can group related environment variables into a single object using `object` with `properties` and an optional `envPrefix` (defaults to `KEY_`):
+
+```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 }
+    }
+  }
+});
+```
+
+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]

package/dist/cli/commands/sync.js

@@ -16,6 +16,25 @@ export default function (program) {
             Object.entries(schema).forEach(([key, rule]) => {
                 if (rule.sensitive)
                     return;
+                // If this is a grouped object with properties, emit grouped entries
+                const eff = rule;
+                if (eff.type === "object" && eff.properties) {
+                    const prefix = eff.envPrefix || `${key}_`;
+                    exampleContent += `# ${eff.docs || "No description available"}\n`;
+                    exampleContent += `# Group: ${key} (prefix=${prefix})\n`;
+                    Object.entries(eff.properties).forEach(([prop, pRule]) => {
+                        const pr = pRule;
+                        if (pr.sensitive)
+                            return;
+                        exampleContent += `# ${pr.docs || "No description available"}\n`;
+                        exampleContent += `# Type: ${pr.type}\n`;
+                        if (pr.default !== undefined) {
+                            exampleContent += `# Default: ${JSON.stringify(pr.default)}\n`;
+                        }
+                        exampleContent += `${prefix}${prop}=${pr.default ? JSON.stringify(pr.default) : ""}\n\n`;
+                    });
+                    return;
+                }
                 exampleContent += `# ${rule.docs || "No description available"}\n`;
                 exampleContent += `# Type: ${rule.type}\n`;
                 if (rule.default !== undefined) {

package/dist/cli/commands/utils.js

@@ -1,6 +1,6 @@
-import { readFileSync, writeFileSync, unlinkSync } from "fs";
-import { dirname, join } from "path";
-import { fileURLToPath } from "url";
+import { readFileSync, writeFileSync, unlinkSync, existsSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath, pathToFileURL } from "url";
 import { transformSync } from "esbuild";
 import Chalk from "chalk";
 import inquirer from "inquirer";
@@ -12,8 +12,13 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
  * @throws If the schema file is malformed or cannot be loaded.
  */
 export async function loadSchema(schemaPath) {
+    const absPath = resolve(schemaPath);
+    const importModule = async (filePath) => {
+        const fileUrl = pathToFileURL(filePath).href;
+        return (await import(`${fileUrl}?t=${Date.now()}`)).default;
+    };
     const loadTsModule = async (tsFilePath) => {
-        const tempFile = join(__dirname, "../../temp-schema.mjs");
+        const tempFile = join(__dirname, `../../temp-schema-${Date.now()}.mjs`);
         try {
             const tsCode = readFileSync(tsFilePath, "utf-8");
             const { code } = transformSync(tsCode, {
@@ -22,21 +27,23 @@ export async function loadSchema(schemaPath) {
                 target: "esnext",
             });
             writeFileSync(tempFile, code);
-            return (await import(`${tempFile}?t=${Date.now()}`)).default;
+            return await importModule(tempFile);
         }
         finally {
-            unlinkSync(tempFile);
+            if (existsSync(tempFile)) {
+                unlinkSync(tempFile);
+            }
         }
     };
     try {
-        if (schemaPath.endsWith(".ts")) {
-            return await loadTsModule(schemaPath);
+        if (absPath.endsWith(".ts")) {
+            return await loadTsModule(absPath);
         }
-        else if (schemaPath.endsWith(".js")) {
-            return (await import(`${schemaPath}?t=${Date.now()}`)).default;
+        else if (absPath.endsWith(".js")) {
+            return await importModule(absPath);
         }
-        else if (schemaPath.endsWith(".json")) {
-            return JSON.parse(readFileSync(schemaPath, "utf-8"));
+        else if (absPath.endsWith(".json")) {
+            return JSON.parse(readFileSync(absPath, "utf-8"));
         }
         throw new Error(`Unsupported schema format. Use .ts, .js or .json`);
     }

package/dist/types/schema.d.ts

@@ -19,6 +19,7 @@ export interface SchemaRule {
     error?: string;
     items?: SchemaRule;
     properties?: Record<string, SchemaRule>;
+    envPrefix?: string;
     env?: {
         [envName: string]: Partial<SchemaRule>;
     };

package/dist/types/utils.d.ts

@@ -10,6 +10,8 @@ import { SchemaDefinition } from "./schema.js";
  */
 export declare function loadEnv(schema: SchemaDefinition, options?: {
     strict?: boolean;
+    includeRaw?: boolean;
+    includeSensitive?: boolean;
 }): Record<string, any>;
 /**
  * Create a proxy around the validated environment variables. The proxy will

package/dist/types/validator.d.ts

@@ -11,8 +11,12 @@ export declare class EnvValidator {
      */
     constructor(schema: SchemaDefinition, options?: {
         strict?: boolean;
+        includeRaw?: boolean;
+        includeSensitive?: boolean;
     } | undefined);
     validate(env: Record<string, string | undefined>): Record<string, any>;
+    private redactValue;
+    private tryParseJSON;
     private validateKey;
     private getEffectiveRule;
 }

package/dist/validator.js

@@ -16,16 +16,85 @@ export class EnvValidator {
     validate(env) {
         this.errors = [];
         const result = {};
-        for (const [key, rule] of Object.entries(this.schema)) {
+        // Build grouping map for object types that support envPrefix.
+        // We'll collect all prefixes first and then make a single pass over env keys
+        // to assemble grouped objects for each schema key.
+        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];
+                }
+            }
+        }
+        // Micro-optimization: avoid creating intermediate arrays from Object.entries
+        const schemaKeys = Object.keys(this.schema);
+        for (let i = 0; i < schemaKeys.length; i++) {
+            const key = schemaKeys[i];
+            const rule = this.schema[key];
             try {
-                result[key] = this.validateKey(key, rule, env[key]);
+                // If we have grouped values for this key use them (preferred over JSON string)
+                const valToValidate = groupedEnv[key] && Object.keys(groupedEnv[key]).length > 0
+                    ? groupedEnv[key]
+                    : env[key];
+                // If both grouped and a top-level JSON value exist, prefer grouped and warn
+                if (groupedEnv[key] && Object.keys(groupedEnv[key]).length > 0 && env[key] !== undefined) {
+                    console.warn(`Both prefixed variables and top-level ${key} exist; prefixed vars are used`);
+                }
+                // If strict mode is enabled, and this key has grouped env vars, ensure there are no unexpected subkeys
+                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) {
+                    // Decide what to include in the error report depending on options:
+                    // - default: redact sensitive values and shorten long strings
+                    // - includeRaw: include raw values for non-sensitive fields
+                    // - includeSensitive: when used with includeRaw, include raw sensitive values too (use with caution)
+                    let displayedValue;
+                    if (env[key] === undefined) {
+                        displayedValue = undefined;
+                    }
+                    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: env[key],
+                        value: displayedValue,
                         rule,
                     });
                 }
@@ -36,13 +105,49 @@ export class EnvValidator {
             throw new AggregateError(this.errors, `Environment validation failed: ${keys}`);
         }
         if (this.options?.strict) {
-            const extraVars = Object.keys(env).filter((k) => !(k in this.schema));
+            const extraVars = [];
+            for (const k in env) {
+                if (!(k in this.schema))
+                    extraVars.push(k);
+            }
             if (extraVars.length > 0) {
                 throw new Error(`Unexpected environment variables: ${extraVars.join(", ")}`);
             }
         }
         return result;
     }
+    // Redact or trim sensitive values for error reporting
+    redactValue(value, sensitive) {
+        if (value === undefined)
+            return undefined;
+        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 === undefined || value === "") {
@@ -122,23 +227,23 @@ export class EnvValidator {
                 if (port < 1 || port > 65535) {
                     throw new Error("Must be between 1 and 65535");
                 }
+                value = port;
                 break;
             case "json":
-                try {
-                    value = JSON.parse(value);
-                }
-                catch {
+                // fast-path non-json strings
+                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)) {
-                    try {
-                        value = JSON.parse(value);
-                    }
-                    catch {
+                    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) => {
@@ -153,16 +258,18 @@ export class EnvValidator {
                 break;
             case "object":
                 if (typeof value === "string") {
-                    try {
-                        value = JSON.parse(value);
-                    }
-                    catch {
+                    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, propRule] of Object.entries(effectiveRule.properties)) {
+                    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]);
                         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotenv-gad",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "main": "dist/index.js",
   "types": "dist/types/index.d.ts",
   "type": "module",
@@ -17,6 +17,7 @@
     "lint:fix": "eslint src --ext .ts --fix",
     "format": "prettier --write \"src/**/*.ts\" \"__tests__/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\" \"__tests__/**/*.ts\"",
+    "bench": "node benchmarks/validate-bench.js",
     "prepublishOnly": "npm run build && npm test",
     "prepare": "husky"
   },