@dharaneesh/env-schema-validator 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DHARANEESH
+
+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,263 @@
+# @dharaneesh/env-schema-validator
+
+[![npm version](https://img.shields.io/npm/v/@dharaneesh/env-schema-validator)](https://www.npmjs.com/package/@dharaneesh/env-schema-validator)
+[![license](https://img.shields.io/npm/l/@dharaneesh/env-schema-validator)](./LICENSE)
+[![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)](./package.json)
+[![types](https://img.shields.io/badge/TypeScript-first-blue)](./src/index.ts)
+
+> Zero-dependency, TypeScript-first `.env` validator. Validates all environment variables **at startup**, returns a fully typed object, and tells you **everything that's wrong — all at once**.
+
+---
+
+## The Problem
+
+```ts
+// ❌ Without this package — crashes at runtime, no types, no helpful errors
+const port = Number(process.env.PORT);        // NaN if PORT is missing
+const db   = process.env.DATABASE_URL;        // string | undefined, no safety
+const flag = process.env.DEBUG === "true";    // works, but fragile
+```
+
+You only discover missing or malformed env vars when your app crashes in production — not at startup.
+
+---
+
+## The Solution
+
+```ts
+import { validateEnv } from "@dharaneesh/env-schema-validator";
+
+const env = validateEnv({
+  PORT:         { type: "number",  default: "3000" },
+  DATABASE_URL: { type: "url",     description: "PostgreSQL connection string" },
+  NODE_ENV:     { type: "string",  enum: ["development", "production", "test"] },
+  DEBUG:        { type: "boolean", required: false, default: "false" },
+  ADMIN_EMAIL:  { type: "email",   required: false },
+});
+
+// ✅ Fully typed — no casting needed
+env.PORT         // number
+env.DATABASE_URL // string (guaranteed valid URL)
+env.DEBUG        // boolean
+```
+
+If anything is wrong, you get one clear error at startup — before your server even starts:
+
+```
+EnvValidationError: Environment validation failed:
+
+  ✗ DATABASE_URL: is required but not set (PostgreSQL connection string)
+  ✗ PORT: must be a number, got "abc"
+  ✗ NODE_ENV: must be one of [development, production, test], got "prod"
+```
+
+---
+
+## Installation
+
+```bash
+npm install @dharaneesh/env-schema-validator
+```
+
+No other dependencies needed. Works with Node.js 18+, ESM and CJS projects.
+
+---
+
+## Usage
+
+### Basic
+
+```ts
+import { validateEnv } from "@dharaneesh/env-schema-validator";
+
+const env = validateEnv({
+  APP_NAME: { type: "string" },
+  PORT:     { type: "number", default: "3000" },
+  DEBUG:    { type: "boolean", required: false, default: "false" },
+});
+
+console.log(env.PORT);  // 3000 (number, not string)
+console.log(env.DEBUG); // false (boolean, not string)
+```
+
+### With dotenv
+
+```ts
+import "dotenv/config"; // loads .env into process.env first
+import { validateEnv } from "@dharaneesh/env-schema-validator";
+
+const env = validateEnv({
+  DATABASE_URL: { type: "url" },
+  JWT_SECRET:   { type: "string" },
+});
+```
+
+### Recommended — shared config module
+
+Create one file that validates everything at startup. Import it everywhere.
+
+```ts
+// src/config.ts
+import { validateEnv } from "@dharaneesh/env-schema-validator";
+
+export const config = validateEnv({
+  NODE_ENV:     { type: "string",  enum: ["development", "production", "test"] },
+  PORT:         { type: "number",  default: "3000" },
+  DATABASE_URL: { type: "url",     description: "PostgreSQL connection string" },
+  REDIS_URL:    { type: "url",     required: false },
+  JWT_SECRET:   { type: "string",  description: "At least 32 characters" },
+  JWT_EXPIRES:  { type: "string",  default: "7d" },
+  DEBUG:        { type: "boolean", required: false, default: "false" },
+  ADMIN_EMAIL:  { type: "email",   required: false },
+  SMTP_HOST:    { type: "string",  required: false },
+  SMTP_PORT:    { type: "number",  required: false, default: "587" },
+});
+
+// Now import config anywhere:
+// import { config } from "./config";
+// config.PORT        → number
+// config.DATABASE_URL → string
+// config.DEBUG       → boolean
+```
+
+### Validate a custom object (not process.env)
+
+```ts
+const env = validateEnv(
+  { PORT: { type: "number" } },
+  { PORT: "8080" }  // pass any Record<string, string | undefined>
+);
+```
+
+---
+
+## Schema Reference
+
+Every key in your schema maps to a `FieldSchema` object:
+
+| Field         | Type                                              | Default  | Description                                  |
+|---------------|---------------------------------------------------|----------|----------------------------------------------|
+| `type`        | `"string" \| "number" \| "boolean" \| "url" \| "email"` | —  | How to validate and coerce the raw value     |
+| `required`    | `boolean`                                         | `true`   | If `false`, missing field is skipped         |
+| `default`     | `string`                                          | —        | Raw string used when field is absent         |
+| `enum`        | `string[]`                                        | —        | Restricts to a list of allowed values        |
+| `description` | `string`                                          | —        | Shown in the error message when field fails  |
+
+---
+
+## Types Explained
+
+| Type      | What it accepts                                         | JS output   |
+|-----------|---------------------------------------------------------|-------------|
+| `string`  | Any non-empty string                                    | `string`    |
+| `number`  | Any numeric string (`"3000"`, `"3.14"`, `"-1"`)        | `number`    |
+| `boolean` | `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off`    | `boolean`   |
+| `url`     | Any string parseable by `new URL()` (must include protocol) | `string` |
+| `email`   | Basic `user@domain.tld` format                          | `string`    |
+
+Boolean coercion is **case-insensitive** — `TRUE`, `True`, `YES` all work.
+
+---
+
+## API
+
+### `validateEnv(schema, source?)`
+
+```ts
+function validateEnv<S extends EnvSchema>(
+  schema: S,
+  source?: Record<string, string | undefined>  // defaults to process.env
+): ValidatedEnv<S>
+```
+
+- **On success** — returns a typed `ValidatedEnv<S>` object with all values coerced to their proper JS types.
+- **On failure** — throws `EnvValidationError` with **all** problems listed, not just the first one.
+
+---
+
+### `EnvValidationError`
+
+```ts
+import { validateEnv, EnvValidationError } from "@dharaneesh/env-schema-validator";
+
+try {
+  const env = validateEnv(schema);
+} catch (err) {
+  if (err instanceof EnvValidationError) {
+    // Human-readable multi-line string — log this
+    console.error(err.message);
+
+    // Machine-readable array — use this programmatically
+    err.errors.forEach(({ key, message }) => {
+      console.error(`${key}: ${message}`);
+    });
+
+    process.exit(1);
+  }
+}
+```
+
+`err.errors` is an array of `{ key: string; message: string }` objects, one per failed field.
+
+---
+
+## Why Not Just Use `envalid` or `zod`?
+
+| Feature                          | `dotenv` | `envalid` | `zod` | **@dharaneesh/env-schema-validator** |
+|----------------------------------|:--------:|:---------:|:-----:|:------------------------:|
+| Zero runtime dependencies        | ✅        | ❌         | ❌    | ✅                        |
+| TypeScript types from schema     | ❌        | ✅         | ✅    | ✅                        |
+| URL + email types built-in       | ❌        | ✅         | ❌    | ✅                        |
+| Reports ALL errors at once       | ❌        | ✅         | ✅    | ✅                        |
+| ESM + CJS dual output            | ❌        | ❌         | ✅    | ✅                        |
+| Single file, no config needed    | ❌        | ❌         | ❌    | ✅                        |
+
+---
+
+## TypeScript Support
+
+Full types come included — no `@types/` package needed.
+
+```ts
+import { validateEnv, EnvSchema, ValidatedEnv, EnvValidationError } from "@dharaneesh/env-schema-validator";
+
+const schema = {
+  PORT: { type: "number" as const },
+  NAME: { type: "string" as const },
+} satisfies EnvSchema;
+
+type AppEnv = ValidatedEnv<typeof schema>;
+// { PORT: number; NAME: string }
+```
+
+---
+
+## Example `.env` File
+
+```env
+NODE_ENV=production
+PORT=3000
+DATABASE_URL=postgres://user:pass@localhost:5432/mydb
+JWT_SECRET=my-very-long-secret-key-here
+DEBUG=false
+ADMIN_EMAIL=admin@example.com
+```
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/dharaneesh-r/@dharaneesh/env-schema-validator
+cd @dharaneesh/env-schema-validator
+npm install
+npm test          # run tests
+npm run test:watch  # watch mode
+npm run build     # build dist/
+```
+
+---
+
+## License
+
+MIT © Dharaneesh R

package/dist/index.cjs

@@ -0,0 +1,122 @@
+"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,
+  validateEnv: () => validateEnv
+});
+module.exports = __toCommonJS(index_exports);
+var EnvValidationError = class extends Error {
+  constructor(errors) {
+    const lines = errors.map((e) => `  \u2717 ${e.key}: ${e.message}`).join("\n");
+    super(`Environment validation failed:
+
+${lines}
+`);
+    this.name = "EnvValidationError";
+    this.errors = errors;
+  }
+};
+function coerceBoolean(raw) {
+  if (["true", "1", "yes", "on"].includes(raw.toLowerCase())) return true;
+  if (["false", "0", "no", "off"].includes(raw.toLowerCase())) return false;
+  return void 0;
+}
+function coerceNumber(raw) {
+  const n = Number(raw);
+  return isNaN(n) ? void 0 : n;
+}
+function isValidUrl(raw) {
+  try {
+    new URL(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isValidEmail(raw) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(raw);
+}
+function validateEnv(schema, source = process.env) {
+  const errors = [];
+  const result = {};
+  for (const [key, field] of Object.entries(schema)) {
+    const required = field.required !== false;
+    const raw = source[key] ?? field.default;
+    if (raw === void 0 || raw === "") {
+      if (required) {
+        const hint = field.description ? ` (${field.description})` : "";
+        errors.push({ key, message: `is required but not set${hint}` });
+      }
+      continue;
+    }
+    switch (field.type) {
+      case "string":
+        result[key] = raw;
+        break;
+      case "number": {
+        const n = coerceNumber(raw);
+        if (n === void 0) {
+          errors.push({ key, message: `must be a number, got "${raw}"` });
+          continue;
+        }
+        result[key] = n;
+        break;
+      }
+      case "boolean": {
+        const b = coerceBoolean(raw);
+        if (b === void 0) {
+          errors.push({ key, message: `must be a boolean (true/false/1/0/yes/no/on/off), got "${raw}"` });
+          continue;
+        }
+        result[key] = b;
+        break;
+      }
+      case "url":
+        if (!isValidUrl(raw)) {
+          errors.push({ key, message: `must be a valid URL, got "${raw}"` });
+          continue;
+        }
+        result[key] = raw;
+        break;
+      case "email":
+        if (!isValidEmail(raw)) {
+          errors.push({ key, message: `must be a valid email, got "${raw}"` });
+          continue;
+        }
+        result[key] = raw;
+        break;
+    }
+    if (field.enum && result[key] !== void 0) {
+      const coerced = String(result[key]);
+      if (!field.enum.includes(coerced)) {
+        errors.push({ key, message: `must be one of [${field.enum.join(", ")}], got "${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,
+  validateEnv
+});

package/dist/index.d.cts

@@ -0,0 +1,23 @@
+type FieldType = "string" | "number" | "boolean" | "url" | "email";
+interface FieldSchema {
+    type: FieldType;
+    required?: boolean;
+    default?: string;
+    enum?: string[];
+    description?: string;
+}
+type EnvSchema = Record<string, FieldSchema>;
+type ValidatedEnv<S extends EnvSchema> = {
+    [K in keyof S]: S[K]["type"] extends "number" ? number : S[K]["type"] extends "boolean" ? boolean : string;
+};
+interface ValidationError {
+    key: string;
+    message: string;
+}
+declare class EnvValidationError extends Error {
+    errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+declare function validateEnv<S extends EnvSchema>(schema: S, source?: Record<string, string | undefined>): ValidatedEnv<S>;
+
+export { type EnvSchema, EnvValidationError, type FieldSchema, type FieldType, type ValidatedEnv, type ValidationError, validateEnv };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+type FieldType = "string" | "number" | "boolean" | "url" | "email";
+interface FieldSchema {
+    type: FieldType;
+    required?: boolean;
+    default?: string;
+    enum?: string[];
+    description?: string;
+}
+type EnvSchema = Record<string, FieldSchema>;
+type ValidatedEnv<S extends EnvSchema> = {
+    [K in keyof S]: S[K]["type"] extends "number" ? number : S[K]["type"] extends "boolean" ? boolean : string;
+};
+interface ValidationError {
+    key: string;
+    message: string;
+}
+declare class EnvValidationError extends Error {
+    errors: ValidationError[];
+    constructor(errors: ValidationError[]);
+}
+declare function validateEnv<S extends EnvSchema>(schema: S, source?: Record<string, string | undefined>): ValidatedEnv<S>;
+
+export { type EnvSchema, EnvValidationError, type FieldSchema, type FieldType, type ValidatedEnv, type ValidationError, validateEnv };

package/dist/index.js

@@ -0,0 +1,96 @@
+// src/index.ts
+var EnvValidationError = class extends Error {
+  constructor(errors) {
+    const lines = errors.map((e) => `  \u2717 ${e.key}: ${e.message}`).join("\n");
+    super(`Environment validation failed:
+
+${lines}
+`);
+    this.name = "EnvValidationError";
+    this.errors = errors;
+  }
+};
+function coerceBoolean(raw) {
+  if (["true", "1", "yes", "on"].includes(raw.toLowerCase())) return true;
+  if (["false", "0", "no", "off"].includes(raw.toLowerCase())) return false;
+  return void 0;
+}
+function coerceNumber(raw) {
+  const n = Number(raw);
+  return isNaN(n) ? void 0 : n;
+}
+function isValidUrl(raw) {
+  try {
+    new URL(raw);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isValidEmail(raw) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(raw);
+}
+function validateEnv(schema, source = process.env) {
+  const errors = [];
+  const result = {};
+  for (const [key, field] of Object.entries(schema)) {
+    const required = field.required !== false;
+    const raw = source[key] ?? field.default;
+    if (raw === void 0 || raw === "") {
+      if (required) {
+        const hint = field.description ? ` (${field.description})` : "";
+        errors.push({ key, message: `is required but not set${hint}` });
+      }
+      continue;
+    }
+    switch (field.type) {
+      case "string":
+        result[key] = raw;
+        break;
+      case "number": {
+        const n = coerceNumber(raw);
+        if (n === void 0) {
+          errors.push({ key, message: `must be a number, got "${raw}"` });
+          continue;
+        }
+        result[key] = n;
+        break;
+      }
+      case "boolean": {
+        const b = coerceBoolean(raw);
+        if (b === void 0) {
+          errors.push({ key, message: `must be a boolean (true/false/1/0/yes/no/on/off), got "${raw}"` });
+          continue;
+        }
+        result[key] = b;
+        break;
+      }
+      case "url":
+        if (!isValidUrl(raw)) {
+          errors.push({ key, message: `must be a valid URL, got "${raw}"` });
+          continue;
+        }
+        result[key] = raw;
+        break;
+      case "email":
+        if (!isValidEmail(raw)) {
+          errors.push({ key, message: `must be a valid email, got "${raw}"` });
+          continue;
+        }
+        result[key] = raw;
+        break;
+    }
+    if (field.enum && result[key] !== void 0) {
+      const coerced = String(result[key]);
+      if (!field.enum.includes(coerced)) {
+        errors.push({ key, message: `must be one of [${field.enum.join(", ")}], got "${coerced}"` });
+      }
+    }
+  }
+  if (errors.length > 0) throw new EnvValidationError(errors);
+  return result;
+}
+export {
+  EnvValidationError,
+  validateEnv
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@dharaneesh/env-schema-validator",
+  "version": "1.0.1",
+  "description": "Zero-dependency TypeScript-first .env validator. Fails fast with clear, human-readable errors.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": ["env", "dotenv", "validator", "schema", "typescript", "environment", "zero-dependency"],
+  "author": "Dharaneesh R",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/dharaneesh/env-schema-validator" },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}