@vivekrajput/envvault 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vivek Rajput
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# 📦 envvault
+
+<p align="center">
+  🔐 Type-safe environment variable validation for Node.js & TypeScript  
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/npm/v/envvault.svg" />
+  <img src="https://img.shields.io/npm/dw/envvault.svg" />
+  <img src="https://img.shields.io/github/stars/twojokers2000/envvault?style=social" />
+  <img src="https://img.shields.io/badge/zero-dependency-true-green" />
+  <img src="https://img.shields.io/badge/typescript-ready-blue" />
+</p>
+
+---
+
+## 🚨 The Problem
+
+Using `process.env` directly is unsafe:
+
+```ts
+const port = process.env.PORT; // string | undefined 😬
+```
+
+* ❌ No type safety
+* ❌ No validation
+* ❌ Runtime crashes
+* ❌ Silent bugs
+
+---
+
+## ✅ The Solution
+
+```ts
+import { env, number } from "envvault";
+
+const config = env({
+  PORT: number(),
+});
+
+config.PORT; // number ✅
+```
+
+👉 Fail fast. Stay safe. Ship confidently.
+
+---
+
+## ✨ Features
+
+* 🔒 Type-safe environment variables
+* ⚡ Runtime validation
+* 🧠 Default values support
+* 🧩 Optional variables support
+* 💥 Clear error messages
+* 📦 Zero dependencies
+* 🚀 Framework agnostic
+
+---
+
+## 📦 Installation
+
+```bash
+npm install envvault
+```
+
+---
+
+## ⚡ Quick Start
+
+```ts
+import { env, string, number, boolean } from "envvault";
+
+const config = env({
+  DATABASE_URL: string(),
+  PORT: number().default(3000),
+  DEBUG: boolean().optional(),
+});
+```
+
+---
+
+## 🧠 Example
+
+```ts
+const config = env({
+  API_KEY: string(),
+  PORT: number().default(3000),
+  NODE_ENV: string(),
+  DEBUG: boolean().optional(),
+});
+
+console.log(config.PORT); // number
+```
+
+---
+
+## 💥 Error Example
+
+```bash
+❌ Invalid environment variable: PORT must be a number
+```
+
+👉 Your app crashes early instead of failing in production.
+
+---
+
+## 🆚 Comparison
+
+| Feature     | envvault  | manual |
+| ----------- | --------  | ------ |
+| Type safety | ✅        | ❌      |
+| Validation  | ✅        | ❌      |
+| Defaults    | ✅        | ⚠️     |
+| DX          | 🔥        | ❌      |
+
+---
+
+## 📁 Example `.env`
+
+```env
+PORT=3000
+DATABASE_URL=postgres://localhost:5432/db
+DEBUG=true
+```
+
+---
+
+## 🧩 API
+
+### Validators
+
+```ts
+string()
+number()
+boolean()
+```
+
+### Modifiers
+
+```ts
+.optional()
+.default(value)
+```
+
+---
+
+## 🛠 Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+---
+
+## 🚀 Roadmap
+
+* [ ] URL / enum validators
+* [ ] CLI support
+* [ ] Better error formatting
+* [ ] Browser support
+
+---
+
+## 🤝 Contributing
+
+PRs are welcome! Feel free to open issues or suggest improvements.
+
+---
+
+## 📄 License
+
+MIT © Vivek Kumar
+
+---
+
+## ⭐ Support
+
+If you like this project:
+
+* ⭐ Star the repo
+* 🐛 Report issues
+* 💡 Suggest features
+
+---
+
+## 🔥 One-line Pitch
+
+> envvault = Zod for environment variables (zero dependency)
+

package/dist/index.d.mts

@@ -0,0 +1,20 @@
+type EnvType = "string" | "number" | "boolean" | "url" | "email" | "port";
+interface EnvField<T = unknown> {
+    type: EnvType;
+    required?: boolean;
+    default?: T;
+    description?: string;
+    choices?: T[];
+}
+type EnvSchema = Record<string, EnvField>;
+type InferEnvType<T extends EnvType> = T extends "number" | "port" ? number : T extends "boolean" ? boolean : string;
+type InferSchema<S extends EnvSchema> = {
+    [K in keyof S]: S[K]["default"] extends NonNullable<S[K]["default"]> ? InferEnvType<S[K]["type"]> : S[K]["required"] extends false ? InferEnvType<S[K]["type"]> | undefined : InferEnvType<S[K]["type"]>;
+};
+declare class EnvValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+declare function createEnv<S extends EnvSchema>(schema: S, source?: Record<string, string | undefined>): InferSchema<S>;
+
+export { type EnvField, type EnvSchema, type EnvType, EnvValidationError, type InferEnvType, type InferSchema, createEnv };

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+type EnvType = "string" | "number" | "boolean" | "url" | "email" | "port";
+interface EnvField<T = unknown> {
+    type: EnvType;
+    required?: boolean;
+    default?: T;
+    description?: string;
+    choices?: T[];
+}
+type EnvSchema = Record<string, EnvField>;
+type InferEnvType<T extends EnvType> = T extends "number" | "port" ? number : T extends "boolean" ? boolean : string;
+type InferSchema<S extends EnvSchema> = {
+    [K in keyof S]: S[K]["default"] extends NonNullable<S[K]["default"]> ? InferEnvType<S[K]["type"]> : S[K]["required"] extends false ? InferEnvType<S[K]["type"]> | undefined : InferEnvType<S[K]["type"]>;
+};
+declare class EnvValidationError extends Error {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+declare function createEnv<S extends EnvSchema>(schema: S, source?: Record<string, string | undefined>): InferSchema<S>;
+
+export { type EnvField, type EnvSchema, type EnvType, EnvValidationError, type InferEnvType, type InferSchema, createEnv };

package/dist/index.js

@@ -0,0 +1,132 @@
+"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/index.ts
+var index_exports = {};
+__export(index_exports, {
+  EnvValidationError: () => EnvValidationError,
+  createEnv: () => createEnv
+});
+module.exports = __toCommonJS(index_exports);
+var EnvValidationError = class extends Error {
+  constructor(errors) {
+    super(`Environment validation failed:
+${errors.map((e) => `  \u2716 ${e}`).join("\n")}`);
+    this.name = "EnvValidationError";
+    this.errors = errors;
+  }
+};
+function validateEmail(value) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+function validateUrl(value) {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function validatePort(value) {
+  const num = Number(value);
+  return Number.isInteger(num) && num >= 1 && num <= 65535;
+}
+function coerce(value, type) {
+  switch (type) {
+    case "number":
+      return Number(value);
+    case "port":
+      return Number(value);
+    case "boolean":
+      return value.toLowerCase() === "true" || value === "1";
+    default:
+      return value;
+  }
+}
+function createEnv(schema, source = process.env) {
+  const errors = [];
+  const result = {};
+  for (const [key, field] of Object.entries(schema)) {
+    const rawValue = source[key];
+    const isRequired = field.required !== false;
+    if (rawValue === void 0 || rawValue === "") {
+      if (field.default !== void 0) {
+        result[key] = field.default;
+        continue;
+      }
+      if (isRequired) {
+        errors.push(
+          `Missing required variable "${key}"${field.description ? ` (${field.description})` : ""}`
+        );
+        continue;
+      }
+      result[key] = void 0;
+      continue;
+    }
+    switch (field.type) {
+      case "number":
+        if (isNaN(Number(rawValue))) {
+          errors.push(`"${key}" must be a valid number, got "${rawValue}"`);
+          continue;
+        }
+        break;
+      case "port":
+        if (!validatePort(rawValue)) {
+          errors.push(`"${key}" must be a valid port (1\u201365535), got "${rawValue}"`);
+          continue;
+        }
+        break;
+      case "boolean":
+        if (!["true", "false", "1", "0"].includes(rawValue.toLowerCase())) {
+          errors.push(`"${key}" must be true/false/1/0, got "${rawValue}"`);
+          continue;
+        }
+        break;
+      case "email":
+        if (!validateEmail(rawValue)) {
+          errors.push(`"${key}" must be a valid email, got "${rawValue}"`);
+          continue;
+        }
+        break;
+      case "url":
+        if (!validateUrl(rawValue)) {
+          errors.push(`"${key}" must be a valid URL, got "${rawValue}"`);
+          continue;
+        }
+        break;
+    }
+    const coerced = coerce(rawValue, field.type);
+    if (field.choices && !field.choices.includes(coerced)) {
+      errors.push(
+        `"${key}" must be one of [${field.choices.join(", ")}], got "${rawValue}"`
+      );
+      continue;
+    }
+    result[key] = coerced;
+  }
+  if (errors.length > 0) {
+    throw new EnvValidationError(errors);
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  EnvValidationError,
+  createEnv
+});

package/dist/index.mjs

@@ -0,0 +1,106 @@
+// src/index.ts
+var EnvValidationError = class extends Error {
+  constructor(errors) {
+    super(`Environment validation failed:
+${errors.map((e) => `  \u2716 ${e}`).join("\n")}`);
+    this.name = "EnvValidationError";
+    this.errors = errors;
+  }
+};
+function validateEmail(value) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+}
+function validateUrl(value) {
+  try {
+    new URL(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function validatePort(value) {
+  const num = Number(value);
+  return Number.isInteger(num) && num >= 1 && num <= 65535;
+}
+function coerce(value, type) {
+  switch (type) {
+    case "number":
+      return Number(value);
+    case "port":
+      return Number(value);
+    case "boolean":
+      return value.toLowerCase() === "true" || value === "1";
+    default:
+      return value;
+  }
+}
+function createEnv(schema, source = process.env) {
+  const errors = [];
+  const result = {};
+  for (const [key, field] of Object.entries(schema)) {
+    const rawValue = source[key];
+    const isRequired = field.required !== false;
+    if (rawValue === void 0 || rawValue === "") {
+      if (field.default !== void 0) {
+        result[key] = field.default;
+        continue;
+      }
+      if (isRequired) {
+        errors.push(
+          `Missing required variable "${key}"${field.description ? ` (${field.description})` : ""}`
+        );
+        continue;
+      }
+      result[key] = void 0;
+      continue;
+    }
+    switch (field.type) {
+      case "number":
+        if (isNaN(Number(rawValue))) {
+          errors.push(`"${key}" must be a valid number, got "${rawValue}"`);
+          continue;
+        }
+        break;
+      case "port":
+        if (!validatePort(rawValue)) {
+          errors.push(`"${key}" must be a valid port (1\u201365535), got "${rawValue}"`);
+          continue;
+        }
+        break;
+      case "boolean":
+        if (!["true", "false", "1", "0"].includes(rawValue.toLowerCase())) {
+          errors.push(`"${key}" must be true/false/1/0, got "${rawValue}"`);
+          continue;
+        }
+        break;
+      case "email":
+        if (!validateEmail(rawValue)) {
+          errors.push(`"${key}" must be a valid email, got "${rawValue}"`);
+          continue;
+        }
+        break;
+      case "url":
+        if (!validateUrl(rawValue)) {
+          errors.push(`"${key}" must be a valid URL, got "${rawValue}"`);
+          continue;
+        }
+        break;
+    }
+    const coerced = coerce(rawValue, field.type);
+    if (field.choices && !field.choices.includes(coerced)) {
+      errors.push(
+        `"${key}" must be one of [${field.choices.join(", ")}], got "${rawValue}"`
+      );
+      continue;
+    }
+    result[key] = coerced;
+  }
+  if (errors.length > 0) {
+    throw new EnvValidationError(errors);
+  }
+  return result;
+}
+export {
+  EnvValidationError,
+  createEnv
+};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@vivekrajput/envvault",
+  "version": "1.0.0",
+  "description": "Type-safe, zero-dependency environment variable validator for Node.js & TypeScript",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "env",
+    "environment",
+    "validation",
+    "typescript",
+    "type-safe",
+    "dotenv",
+    "config",
+    "zero-dependency"
+  ],
+  "author": "Vivek Rajput",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/twojokers2000/envvault"
+  },
+  "homepage": "https://github.com/twojokers2000/envvault#readme",
+  "bugs": {
+    "url": "https://github.com/twojokers2000/envvault/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}