dotenv-gad 0.1.0

package/README.md

@@ -0,0 +1,202 @@
+# dotenv-gad
+
+[![npm version](https://badge.fury.io/js/dotenv-gad.svg)](https://badge.fury.io/js/dotenv-guard)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**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
+- Automatic documentation generation
+- TypeScript support
+- CLI tooling
+- Secret management
+
+## Installation
+
+```bash
+npm install dotenv-gad
+# or
+yarn add dotenv-gad
+# or
+pnpm add dotenv-gad
+```
+
+## Quick Start
+
+1. Create a schema file (`env.schema.ts`):
+
+```typescript
+import { defineSchema } from "dotenv-gad";
+
+export default defineSchema({
+  PORT: {
+    type: "number",
+    default: 3000,
+    docs: "Port to run the server on",
+  },
+  DATABASE_URL: {
+    type: "string",
+    required: true,
+    sensitive: true,
+  },
+});
+```
+
+2. Validate your environment:
+
+```typescript
+import { loadEnv } from "dotenv-gad";
+import schema from "./env.schema";
+
+const env = loadEnv(schema);
+console.log(`Server running on port ${env.PORT}`);
+```
+
+## CLI Commands
+
+| Command | Description                        |
+| ------- | ---------------------------------- |
+| `check` | Validate .env against schema       |
+| `sync`  | Generate/update .env.example       |
+| `types` | Generate env.d.ts TypeScript types |
+| `init`  | Create starter schema              |
+
+```bash
+npx dotenv-gad check
+npx dotenv-gad types
+```
+
+## Features
+
+### Core Validation
+
+- Type checking (string, number, boolean, array, object)
+- Required/optional fields
+- Default values
+- Custom validation functions
+- Environment-specific rules
+
+### Advanced Types
+
+```typescript
+{
+  API_URL: { type: 'url' },
+  EMAIL: { type: 'email' },
+  CONFIG: { type: 'json' },
+  TAGS: {
+    type: 'array',
+    items: { type: 'string' }
+  }
+}
+```
+
+### CLI Features
+
+- Color-coded output
+- Interactive fixes
+- Strict mode
+- Custom schema paths
+- CI/CD friendly (comming soon!)
+
+### Secret Management
+
+```typescript
+{
+  API_KEY: {
+    type: 'string',
+    sensitive: true, // Excluded from .env.example
+    validate: (val) => val.startsWith('sk_')
+  }
+}
+```
+
+## Framework Integrations
+
+### Express.js
+
+```typescript
+import express from "express";
+import { loadEnv } from "dotenv-gad";
+import schema from "./env.schema";
+
+const env = loadEnv(schema);
+const app = express();
+
+app.listen(env.PORT, () => {
+  console.log(`Server running on port ${env.PORT}`);
+});
+```
+
+### Next.js
+
+Create `next.config.js`:
+
+```javascript
+const { loadEnv } = require("dotenv-gad");
+const schema = require("./env.schema");
+
+const env = loadEnv(schema);
+
+module.exports = {
+  env: {
+    API_URL: env.API_URL,
+  },
+};
+```
+
+## Validation Reports
+
+Example error output:
+
+```
+Environment validation failed:
+  - DATABASE_URL: Missing required environment variable
+  - PORT: Must be a number (received: "abc")
+  - API_KEY: Must start with 'sk_' (received: "invalid")
+```
+
+## more usages
+
+### Environment-Specific Rules
+
+```typescript
+{
+  DEBUG: {
+    type: 'boolean',
+    env: {
+      development: { default: true },
+      production: { default: false }
+    }
+  }
+}
+```
+
+### Custom Validators
+
+```typescript
+{
+  PASSWORD: {
+    type: 'string',
+    validate: (val) => val.length >= 8,
+    error: 'Password must be at least 8 characters'
+  }
+}
+```
+
+### Transformations
+
+```typescript
+{
+  FEATURES: {
+    type: 'array',
+    transform: (val) => val.split(',')
+  }
+}
+```
+
+## 📜 License
+
+MIT © [Kasim Lyee]
+
+Contributions are welcome!!

package/dist/cli/commands/check.js

@@ -0,0 +1,41 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { validateEnv } from "../../index.js";
+import { AggregateError } from "../../errors.js";
+import { loadSchema } from "./utils.js";
+export default function (program) {
+    return new Command("check")
+        .description("Validate .env against schema")
+        .option("--strict", "Fail on extra env vars not in schema")
+        .option("--fix", "Attempt to fix errors interactively")
+        .action(async (option, command) => {
+        const rootOpts = command.parent.opts();
+        const spinner = ora("Validatng environment.......").start();
+        try {
+            const schema = await loadSchema(rootOpts.schema);
+            const env = validateEnv(schema, {
+                strict: option.strict,
+            });
+            spinner.succeed(chalk.green("Environment validation passed!"));
+            console.log(chalk.dim(`Found ${Object.keys(env).length} valid variables`));
+        }
+        catch (error) {
+            spinner.stop();
+            if (error instanceof AggregateError) {
+                console.error(chalk.red("\nEnvironment validation failed:"));
+                error.errors.forEach((e) => {
+                    console.log(`  ${chalk.yellow(e.key)}: ${e.message}`);
+                    if (e.rule?.docs) {
+                        console.log(chalk.dim(`  ${e.rule.docs}`));
+                    }
+                });
+                process.exit(1);
+            }
+            else {
+                console.error(chalk.red("Unexpected error:"), error);
+                process.exit(2);
+            }
+        }
+    });
+}

package/dist/cli/commands/init.js

@@ -0,0 +1,61 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { writeFileSync, existsSync } from "fs";
+import inquirer from "inquirer";
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export default function (program) {
+    return new Command("init")
+        .description("Initialize new schema file")
+        .option("--force", "Overwrite existing files")
+        .action(async (options, command) => {
+        const rootOpts = command.parent.opts();
+        const schemaPath = rootOpts.schema;
+        if (existsSync(schemaPath)) {
+            if (!options.force) {
+                const { overwrite } = await inquirer.prompt({
+                    type: "confirm",
+                    name: "overwrite",
+                    message: "Schema file already exists. Overwrite?",
+                    default: false,
+                });
+                if (!overwrite)
+                    process.exit(0);
+            }
+        }
+        const spinner = ora("Creating new schema...").start();
+        try {
+            const template = `import { defineSchema } from 'dotenv-gad';
+
+export default defineSchema({
+  // Add your environment variables here
+  PORT: {
+    type: 'number',
+    default: 3000,
+    docs: 'Port to run the server on'
+  },
+  NODE_ENV: {
+    type: 'string',
+    enum: ['development', 'production', 'test'],
+    default: 'development'
+  },
+  DB_URL: {
+    type: 'string',
+    required: true,
+    docs: 'Database connection URL'
+  }
+});
+`;
+            writeFileSync(schemaPath, template);
+            spinner.succeed(chalk.green(`Created ${schemaPath} successfully!`));
+            console.log(chalk.dim("\nEdit this file to define your environment schema"));
+        }
+        catch (error) {
+            spinner.fail(chalk.red("Failed to create schema file"));
+            console.error(error);
+            process.exit(1);
+        }
+    });
+}

package/dist/cli/commands/sync.js

@@ -0,0 +1,37 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { writeFileSync } from "fs";
+import { loadSchema } from "./utils.js";
+export default function (program) {
+    return new Command("sync")
+        .description("Genearte/update .env.example file")
+        .option("--output <file>", "Output file path", ".env.example")
+        .action(async (options, command) => {
+        const rootOpts = command.parent.opts();
+        const spinner = ora("Generating .env.example.......").start();
+        try {
+            const schema = await loadSchema(rootOpts.schema);
+            let exampleContent = "# Auto-generated by dotenv-gad\n\n";
+            Object.entries(schema).forEach(([key, rule]) => {
+                if (rule.sensitive)
+                    return;
+                exampleContent += `# ${rule.docs || "No description available"}\n`;
+                exampleContent += `# Type: ${rule.type}\n`;
+                if (rule.default !== undefined) {
+                    exampleContent += `# Default: ${JSON.stringify(rule.default)}\n`;
+                }
+                exampleContent += `${key}=${rule.default
+                    ? JSON.stringify(rule.default)
+                    : ""}\n\n`;
+            });
+            writeFileSync(options.output, exampleContent.trim());
+            spinner.succeed(chalk.green(`Generated ${options.output} successfully!`));
+        }
+        catch (error) {
+            spinner.fail(chalk.red(`Failed to generate .env.example`));
+            console.error(error);
+            process.exit(1);
+        }
+    });
+}

package/dist/cli/commands/types.js

@@ -0,0 +1,40 @@
+import { Command } from "commander";
+import chalk from "chalk";
+import ora from "ora";
+import { writeFileSync } from "fs";
+import { loadSchema } from "./utils.js";
+export default function (program) {
+    return new Command("types")
+        .description("Generate Typescript types")
+        .option("--output <file>", "Output file path", "env.d.ts")
+        .action(async (options, command) => {
+        const rootOpts = command.parent.opts();
+        const spinner = ora("Generating type definitions.......").start();
+        try {
+            const schema = await loadSchema(rootOpts.schema);
+            let typeContent = "// Auto-generated by dotenv-gad\n\ndeclare namespace NodeJS{\n  interface ProcessEnv{\n";
+            Object.entries(schema).forEach(([key, rule]) => {
+                let type;
+                switch (rule.type) {
+                    case "number":
+                        type = "number";
+                        break;
+                    case "boolean":
+                        type = "boolean";
+                        break;
+                    default:
+                        type = "string";
+                }
+                typeContent += `    ${key}${rule.required ? "" : "?"}:${type};\n`;
+            });
+            typeContent += "  }\n}\n";
+            writeFileSync(options.output, typeContent);
+            spinner.succeed(chalk.green(`Generated ${options.output} successfully!`));
+        }
+        catch (error) {
+            spinner.fail(chalk.red("Failed to generate type definitions"));
+            console.error(error);
+            process.exit(1);
+        }
+    });
+}

package/dist/cli/commands/utils.js

@@ -0,0 +1,40 @@
+import { readFileSync, writeFileSync, unlinkSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { transformSync } from "esbuild";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export async function loadSchema(schemaPath) {
+    try {
+        if (schemaPath.endsWith(".ts")) {
+            const code = readFileSync(schemaPath, "utf-8");
+            const result = transformSync(code, {
+                format: "esm",
+                loader: "ts",
+                target: "esnext",
+            });
+            // Create temporary file
+            const tempFile = join(__dirname, "../../temp-schema.mjs");
+            writeFileSync(tempFile, result.code);
+            try {
+                // Import with query string to bust cache
+                const module = await import(`${tempFile}?t=${Date.now()}`);
+                return module.default;
+            }
+            finally {
+                // Clean up temp file
+                unlinkSync(tempFile);
+            }
+        }
+        else if (schemaPath.endsWith(".js")) {
+            const module = await import(schemaPath);
+            return module.default;
+        }
+        else if (schemaPath.endsWith(".json")) {
+            return JSON.parse(readFileSync(schemaPath, "utf-8"));
+        }
+        throw new Error("Unsupported schema format. Use .ts, .js or .json");
+    }
+    catch (error) {
+        throw new Error(`Failed to load schema: ${error.message}`);
+    }
+}

package/dist/cli/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import chalk from "chalk";
+import figlet from "figlet";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import checkCommand from "./commands/check.js";
+import syncCommand from "./commands/sync.js";
+import typesCommand from "./commands/types.js";
+import initCommand from "./commands/init.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "../../package.json"), "utf-8"));
+export function createCLI() {
+    const program = new Command();
+    program
+        .version(pkg.version)
+        .description(chalk.green(figlet.textSync("dotenv-gad", {
+        font: "Standard",
+        horizontalLayout: "fitted",
+    })))
+        .option("--debug", "Enable debug output")
+        .option("--env <file>", "Specify env file path", ".env")
+        .option("--schema <file>", "Specify schema file path", "env.schema.ts");
+    const commands = [checkCommand, syncCommand, typesCommand, initCommand];
+    commands.forEach((command) => {
+        const cmd = command(program);
+        program.addCommand(cmd);
+    });
+    return program;
+}
+const program = createCLI();
+program.parse(process.argv);
+export default program;

package/dist/errors.js

@@ -0,0 +1,22 @@
+export class AggregateError extends Error {
+    errors;
+    constructor(errors, message) {
+        super(message);
+        this.errors = errors;
+        this.name = "AggregateError";
+        Object.setPrototypeOf(this, AggregateError.prototype);
+    }
+    toString() {
+        const errorList = this.errors
+            .map((e) => {
+            let msg = `  - ${e.key}:${e.message}`;
+            if (e.value !== undefined)
+                msg += ` (reaceived: ${JSON.stringify(e.value)})`;
+            if (e.rule?.docs)
+                msg += `\n   (${e.rule.docs})`;
+            return msg;
+        })
+            .join("\n");
+        return `${this.message}:\n${errorList}`;
+    }
+}

package/dist/index.js

@@ -0,0 +1,11 @@
+import { EnvValidator } from "./validator.js";
+import { defineSchema } from "./schema.js";
+import { AggregateError } from "./errors.js";
+import { loadEnv, createEnvProxy } from "./utils.js";
+import dotenv from "dotenv";
+export { defineSchema, AggregateError, EnvValidator, loadEnv, createEnvProxy };
+export function validateEnv(schema, options) {
+    const env = dotenv.config().parsed || {};
+    const validator = new EnvValidator(schema, options);
+    return validator.validate(env);
+}

package/dist/schema.js

@@ -0,0 +1,10 @@
+/**
+ * Define a schema for a set of environment variables.
+ *
+ * @param schema A record where each key is the name of an environment variable
+ * and the value is a `SchemaRule` object that defines the rules for that
+ * variable.
+ */
+export function defineSchema(schema) {
+    return schema;
+}

package/dist/utils.js

@@ -0,0 +1,36 @@
+import dotenv from "dotenv";
+import { EnvValidator } from "./validator.js";
+/**
+ * Load the environment variables from a .env file, validate them against the schema
+ * and return an object with the validated values.
+ *
+ * @param schema The schema definition for the environment variables.
+ * @param options Options for the validation process.
+ *
+ * @returns A validated object with the environment variables.
+ */
+export function loadEnv(schema, options) {
+    const env = dotenv.config().parsed || {};
+    const validator = new EnvValidator(schema, options);
+    return validator.validate(env);
+}
+/**
+ * Create a proxy around the validated environment variables. The proxy will
+ * throw an error if you try to access a variable that is not validated.
+ *
+ * @param validatedEnv The validated environment variables.
+ *
+ * @returns A proxy object that throws an error if you access an
+ * unvalidated variable.
+ */
+export function createEnvProxy(validatedEnv) {
+    return new Proxy(validatedEnv, {
+        get(target, prop) {
+            const value = target[prop];
+            if (value === undefined) {
+                throw new Error(`Environment variable ${String(prop)} is not validated`);
+            }
+            return value;
+        },
+    });
+}

package/dist/validator.js

@@ -0,0 +1,180 @@
+import { AggregateError } from "./errors.js";
+export class EnvValidator {
+    schema;
+    options;
+    errors = [];
+    constructor(schema, options) {
+        this.schema = schema;
+        this.options = options;
+    }
+    validate(env) {
+        this.errors = [];
+        const result = {};
+        for (const [key, rule] of Object.entries(this.schema)) {
+            try {
+                result[key] = this.validateKey(key, rule, env[key]);
+            }
+            catch (error) {
+                if (error instanceof Error) {
+                    this.errors.push({
+                        key,
+                        message: error.message,
+                        value: env[key],
+                        rule,
+                    });
+                }
+            }
+        }
+        if (this.errors.length > 0) {
+            const keys = this.errors.map((e) => e.key).join(", ");
+            throw new AggregateError(this.errors, `Environment validation failed: ${keys}`);
+        }
+        if (this.options?.strict) {
+            const extraVars = Object.keys(env).filter((k) => !(k in this.schema));
+            if (extraVars.length > 0) {
+                throw new Error(`Unexpected environment variables: ${extraVars.join(", ")}`);
+            }
+        }
+        return result;
+    }
+    validateKey(key, rule, value) {
+        const effectiveRule = this.getEffectiveRule(key, rule);
+        if (value === undefined) {
+            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 && value.length < effectiveRule.minLength) {
+                    throw new Error(`Environment variable ${key} must be at least ${effectiveRule.minLength} characters`);
+                }
+                if (effectiveRule.maxLength && 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 !== undefined && value < effectiveRule.min) {
+                    throw new Error(`Environment variable ${key} must be at least ${effectiveRule.min}`);
+                }
+                if (effectiveRule.max !== undefined && 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 "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 (!/^(?:[0-9]{1,3}\.){3}[0-9]{1,3}$/.test(String(value))) {
+                    throw new Error("Must be a valid IP address");
+                }
+                break;
+            case "port":
+                const port = Number(value);
+                if (isNaN(port))
+                    throw new Error("Must be a number");
+                if (port < 1 || port > 65535) {
+                    throw new Error("Must be between 1 and 65535");
+                }
+                break;
+            case "json":
+                try {
+                    value = JSON.parse(value);
+                }
+                catch {
+                    throw new Error("Must be valid JSON");
+                }
+                break;
+            case "array":
+                if (!Array.isArray(value)) {
+                    try {
+                        value = JSON.parse(value);
+                    }
+                    catch {
+                        throw new Error("Must be a valid array or JSON array string");
+                    }
+                }
+                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") {
+                    try {
+                        value = JSON.parse(value);
+                    }
+                    catch {
+                        throw new Error("Must be a valid object or JSON string");
+                    }
+                }
+                if (effectiveRule.properties) {
+                    const obj = {};
+                    for (const [prop, propRule] of Object.entries(effectiveRule.properties)) {
+                        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(value)) {
+            throw new Error(`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 };
+    }
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "dotenv-gad",
+  "version": "0.1.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "bin": {
+    "dotenv-guard": "./dist/cli/index.js"
+  },
+  "scripts": {
+    "build": "tsc && chmod +x ./dist/cli/index.js",
+    "test": "NODE_OPTIONS=--experimental-vm-modules jest",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "jest": {
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "transform": {}
+  },
+  "keywords": [
+    "dotenv",
+    "environment",
+    "validation",
+    "typescript",
+    "schema",
+    "configuration"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],
+  "author": "Kasim Lyee",
+  "license": "MIT",
+  "description": "Environment variable validation and type safety for Node.js and modern JavaScript applications",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kasimlyee/dotenv-gad.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kasimlyee/dotenv-gad/issues"
+  },
+  "homepage": "https://github.com/kasimlyee/dotenv-gad#readme",
+  "devDependencies": {
+    "@types/chalk": "^0.4.31",
+    "@types/commander": "^2.12.0",
+    "@types/dotenv": "^6.1.1",
+    "@types/figlet": "^1.7.0",
+    "@types/inquirer": "^9.0.8",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^24.0.3",
+    "@types/ora": "^3.1.0",
+    "jest-environment-jsdom": "^30.0.2",
+    "ts-jest": "^29.4.0"
+  },
+  "dependencies": {
+    "esbuild": "^0.25.5"
+  }
+}