env-typed-checker 0.1.1 → 0.2.0

package/README.md

@@ -1,34 +1,34 @@
-# env-typed-checker 🩺
+# env-typed-checker 
 
-A tiny, developer-friendly library to **validate and parse environment variables** using a simple schema.
+Validate and parse environment variables using a tiny schema — with both a **TypeScript/Node API** and a **CLI**.
 
-env-typed-checker prevents your application from starting with:
+It helps your app fail fast when configuration is wrong:
 
-- ❌ missing environment variables  
-- ❌ wrong types (e.g. PORT="abc")  
-- ❌ invalid URLs or JSON  
-- ❌ silent configuration mistakes  
+- ❌ Missing required variables
+- ❌ Wrong types (e.g. `PORT="abc"`)
+- ❌ Invalid URLs or JSON
+- ❌ Silent mistakes that only crash later
 
 ---
 
 ## ✨ Features
 
-- Simple schema syntax  
-- Automatic `.env` loading  
-- Type parsing (number, boolean, json, url)  
-- Optional variables with `?`  
-- Friendly aggregated error messages  
-- TypeScript support out of the box  
-- Zero dependencies except `dotenv`
+- Simple schema syntax (`"number"`, `"boolean?"`, `"url"`, `"json"`, `"string"`)
+- Loads `.env` automatically via `dotenv` (optional)
+- Aggregated, friendly error output (shows all issues at once)
+- TypeScript types inferred from the schema
+- CLI for quick checks (great for CI)
+- Minimal dependencies (runtime: `dotenv` only)
 
 ---
 
-## 📦 Installation
+## 📦 Install
 
 ```bash
 npm install env-typed-checker
 ```
-### 🚀 Basic Usage
+
+## 🚀 Quick Start (Code)
 
 ```ts
 import { envDoctor } from "env-typed-checker";
@@ -39,10 +39,15 @@ export const config = envDoctor({
   DEBUG: "boolean?"
 });
 ```
-### Result
-* **PORT** → `number` (e.g., `"3000"` becomes `3000`)
-* **DB_URL** → `string` (validated as a proper URL string)
-* **DEBUG** → `boolean | undefined` (optional field; parses `"true"`, `"1"`, etc.)
+
+### What you get
+
+* PORT → number
+
+* DB_URL → string (validated as URL)
+
+* DEBUG → boolean | undefined (optional)
+
 
 ### 🧩 Supported Types
 | Type | Description |
@@ -53,26 +58,55 @@ export const config = envDoctor({
 | **json** | Validates and parses a valid JSON string |
 | **url** | Validates for a properly formatted URL |
 
+
 ### Optional Values
 Add ? to make a variable optional:
 ```ts
-{ DEBUG: "boolean?" }
+envDoctor({ DEBUG: "boolean?" });
 ```
 If missing → value will be undefined.
 
+
+### ⚙️ Options
+
+```ts
+envDoctor(schema, {
+  loadDotEnv: true,   // default: true (loads .env)
+  env: process.env    // default: process.env (override for tests)
+});
+```
+
+### 🧪 Testing with custom env
+
+```ts
+import { envDoctor } from "env-typed-checker";
+
+const cfg = envDoctor(
+  { PORT: "number" },
+  { loadDotEnv: false, env: { PORT: "3000" } }
+);
+
+console.log(cfg.PORT); // 3000
+```
+
 ### ❌ Error Example
-Given this .env:
-```.env
+
+Given a `.env` like:
+
+```env
 PORT=abc
 DB_URL=not-a-url
-Code:
 ```
+
 ```ts
+import { envDoctor } from "env-typed-checker";
+
 envDoctor({
   PORT: "number",
   DB_URL: "url"
 });
 ```
+
 ### Output:
 
 ```ts
@@ -82,24 +116,56 @@ ENV validation failed
 ```
 All errors are shown together so you can fix them in one go.
 
-### ⚙️ Options
-```ts
-envDoctor(schema, {
-  loadDotEnv: true,   // auto load .env (default)
-  env: process.env    // custom env source (useful for tests)
-});
+# 🖥️ CLI
+
+Validate your environment without writing code — perfect for CI pipelines.
+
+## 1) Create a schema file
+
+`env.schema.json`
+```json
+{
+  "PORT": "number",
+  "DB_URL": "url",
+  "DEBUG": "boolean?"
+}
 ```
-### 🧪 Example with Custom Env (Testing)
 
-```ts
-const cfg = envDoctor(
-  { PORT: "number" },
-  { loadDotEnv: false, env: { PORT: "3000" } }
-);
+## 2) Run the check
 
-console.log(cfg.PORT); // 3000 (number)
+```bash
+npx env-typed-checker check --schema env.schema.json
 ```
-### 🛠 Development
+
+### Options
+
+```bash
+# Custom env file
+npx env-typed-checker check --schema env.schema.json --env-file .env.production
+
+# Skip dotenv (use process.env only)
+npx env-typed-checker check --schema env.schema.json --no-dotenv
+```
+
+## Exit codes
+
+* `0` = OK
+
+* `1` = validation failed
+
+* `2` = CLI usage / unexpected error
+
+## ✅ CI Example (GitHub Actions)
+
+Add this to your workflow to fail the build if env is invalid:
+
+```yml
+- name: Validate env
+  run: npx env-typed-checker check --schema env.schema.json
+```
+(If you use a different env file in CI, pass --env-file.)
+
+## 🛠 Development
 Clone the repo and install:
 ```bash
 npm install
@@ -111,43 +177,36 @@ npm run test       # run tests
 npm run typecheck  # TypeScript check
 npm run dev        # watch build
 ```
+
 ### 🤝 Contributing
-Contributions are welcome!
+PRs are welcome!
+
+* Add new validators (e.g. `enum`, `regex`, `email`)
+
+* Improve CLI output formatting
+
+* Add .env.example generator
+
+* Improve docs & examples
 
-* Improve error messages
-* Add more boolean variants
-* Enhance URL validation
-* Add JSON schema validation
-* Write better docs & examples
 * Please read CONTRIBUTING.md before opening a PR.
 
 ###  📌 Roadmap
-#### v1 (current)
-* Schema validation
-* Type parsing
-* Optional values
-* Friendly errors
-
-#### v2 (planned)
-* CLI support
-* .env.example generator
-* Strict unknown variable check
-* Framework integrations
+* `.env.example` generator
 
-# 📝 License
-MIT
+* Strict mode: warn on unknown variables
 
+* More schema features: enums, defaults, min/max
 
----
+* Framework helpers (Next.js / Express / etc.)
 
-```yml
-If you want, I can help you add:
 
-- badges (npm version, CI, coverage)  
-- a small logo  
-- example project section  
+# 📝 License
+MIT
 
-Just tell me 👍
-```
 
+---
 
+```yml
+::contentReference[oaicite:0]{index=0}
+```

package/bin/env-typed-checker.cjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../dist/cli.js");
+
+const code = runCli(process.argv.slice(2), console);
+process.exitCode = code;

package/dist/chunk-U6GH2TRS.mjs

@@ -0,0 +1,126 @@
+// src/index.ts
+import * as dotenv from "dotenv";
+
+// src/error.ts
+var EnvDoctorError = class extends Error {
+  constructor(issues) {
+    const header = "ENV validation failed";
+    const lines = issues.map((i) => `- ${i.key}: ${i.message}`);
+    super([header, ...lines].join("\n"));
+    this.name = "EnvDoctorError";
+    this.issues = issues;
+  }
+};
+
+// src/parsers.ts
+function parseByType(type, raw) {
+  switch (type) {
+    case "string":
+      return raw;
+    case "number": {
+      const n = Number(raw.trim());
+      if (!Number.isFinite(n)) {
+        throw new Error(`expected number, got "${raw}"`);
+      }
+      return n;
+    }
+    case "boolean": {
+      const v = raw.trim().toLowerCase();
+      if (["true", "1", "yes", "y", "on"].includes(v)) return true;
+      if (["false", "0", "no", "n", "off"].includes(v)) return false;
+      throw new Error(
+        `expected boolean (true/false/1/0/yes/no/on/off), got "${raw}"`
+      );
+    }
+    case "json": {
+      try {
+        return JSON.parse(raw);
+      } catch {
+        throw new Error(`expected json, got "${raw}"`);
+      }
+    }
+    case "url": {
+      try {
+        new URL(raw);
+        return raw;
+      } catch {
+        throw new Error(`expected url, got "${raw}"`);
+      }
+    }
+    /* v8 ignore next -- @preserve */
+    default: {
+      const _never = type;
+      return _never;
+    }
+  }
+}
+function splitOptional(schemaValue) {
+  const optional = schemaValue.endsWith("?");
+  const base = optional ? schemaValue.slice(0, -1) : schemaValue;
+  const allowed = ["string", "number", "boolean", "json", "url"];
+  if (!allowed.includes(base)) {
+    throw new Error(
+      `Unsupported type "${schemaValue}". Supported: string, number, boolean, json, url (optional with ?)`
+    );
+  }
+  return { baseType: base, optional };
+}
+
+// src/validator.ts
+function validateAndParse(schema, env) {
+  const issues = [];
+  const out = {};
+  for (const [key, schemaValue] of Object.entries(schema)) {
+    let baseType;
+    let optional;
+    try {
+      ({ baseType, optional } = splitOptional(schemaValue));
+    } catch (e) {
+      issues.push({
+        key,
+        kind: "invalid",
+        message: String(e)
+      });
+      continue;
+    }
+    const raw = env[key];
+    if (raw === void 0 || raw === "") {
+      if (optional) {
+        out[key] = void 0;
+      } else {
+        issues.push({
+          key,
+          kind: "missing",
+          message: "missing required environment variable"
+        });
+      }
+      continue;
+    }
+    try {
+      out[key] = parseByType(baseType, raw);
+    } catch (e) {
+      issues.push({
+        key,
+        kind: "invalid",
+        message: String(e)
+      });
+    }
+  }
+  if (issues.length > 0) {
+    throw new EnvDoctorError(issues);
+  }
+  return out;
+}
+
+// src/index.ts
+function envDoctor(schema, options = {}) {
+  const { loadDotEnv = true, env = process.env } = options;
+  if (loadDotEnv) dotenv.config();
+  return validateAndParse(schema, env);
+}
+
+export {
+  EnvDoctorError,
+  envDoctor
+};
+//# sourceMappingURL=chunk-U6GH2TRS.mjs.map

package/dist/chunk-U6GH2TRS.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/error.ts","../src/parsers.ts","../src/validator.ts"],"sourcesContent":["import * as dotenv from \"dotenv\";\nimport { validateAndParse } from \"./validator\";\nimport type { EnvDoctorOptions, EnvDoctorResult, EnvDoctorSchema } from \"./types\";\n\nexport type { EnvDoctorOptions, EnvDoctorSchema } from \"./types\";\nexport { EnvDoctorError } from \"./error\";\n\nexport function envDoctor<TSchema extends EnvDoctorSchema>(\n  schema: TSchema,\n  options: EnvDoctorOptions = {}\n): EnvDoctorResult<TSchema> {\n  const { loadDotEnv = true, env = process.env } = options;\n\n  if (loadDotEnv) dotenv.config();\n\n  return validateAndParse(schema, env);\n}\n","export type EnvDoctorIssue =\n  | { key: string; kind: \"missing\"; message: string }\n  | { key: string; kind: \"invalid\"; message: string };\n\nexport class EnvDoctorError extends Error {\n  public readonly issues: EnvDoctorIssue[];\n\n  constructor(issues: EnvDoctorIssue[]) {\n    const header = \"ENV validation failed\";\n    const lines = issues.map((i) => `- ${i.key}: ${i.message}`);\n    super([header, ...lines].join(\"\\n\"));\n    this.name = \"EnvDoctorError\";\n    this.issues = issues;\n  }\n}\n","import type { EnvBaseType } from \"./types\";\n\nexport function parseByType(type: EnvBaseType, raw: string): unknown {\n  switch (type) {\n    case \"string\":\n      return raw;\n\n    case \"number\": {\n      // Trim to handle \" 3000 \"\n      const n = Number(raw.trim());\n      if (!Number.isFinite(n)) {\n        throw new Error(`expected number, got \"${raw}\"`);\n      }\n      return n;\n    }\n\n    case \"boolean\": {\n      const v = raw.trim().toLowerCase();\n      if ([\"true\", \"1\", \"yes\", \"y\", \"on\"].includes(v)) return true;\n      if ([\"false\", \"0\", \"no\", \"n\", \"off\"].includes(v)) return false;\n      throw new Error(\n        `expected boolean (true/false/1/0/yes/no/on/off), got \"${raw}\"`,\n      );\n    }\n\n    case \"json\": {\n      try {\n        return JSON.parse(raw);\n      } catch {\n        throw new Error(`expected json, got \"${raw}\"`);\n      }\n    }\n\n    case \"url\": {\n      try {\n        // If it doesn't parse as a URL, this throws.\n        // We return the original string (common for configs).\n        new URL(raw);\n        return raw;\n      } catch {\n        throw new Error(`expected url, got \"${raw}\"`);\n      }\n    }\n\n    /* v8 ignore next -- @preserve */\n    default: {\n      // Exhaustive check (unreachable at runtime)\n      const _never: never = type;\n      return _never;\n    }\n  }\n}\n\nexport function splitOptional(schemaValue: string): {\n  baseType: EnvBaseType;\n  optional: boolean;\n} {\n  const optional = schemaValue.endsWith(\"?\");\n  const base = optional ? schemaValue.slice(0, -1) : schemaValue;\n\n  // runtime safety\n  const allowed = [\"string\", \"number\", \"boolean\", \"json\", \"url\"] as const;\n  if (!allowed.includes(base as any)) {\n    throw new Error(\n      `Unsupported type \"${schemaValue}\". Supported: string, number, boolean, json, url (optional with ?)`,\n    );\n  }\n\n  return { baseType: base as EnvBaseType, optional };\n}\n","import { EnvDoctorError, type EnvDoctorIssue } from \"./error\";\nimport { parseByType, splitOptional } from \"./parsers\";\nimport type { EnvDoctorResult, EnvDoctorSchema } from \"./types\";\n\nexport function validateAndParse<TSchema extends EnvDoctorSchema>(\n  schema: TSchema,\n  env: Record<string, string | undefined>,\n): EnvDoctorResult<TSchema> {\n  const issues: EnvDoctorIssue[] = [];\n  const out: Record<string, unknown> = {};\n\n  for (const [key, schemaValue] of Object.entries(schema)) {\n    let baseType: any;\n    let optional: boolean;\n\n    try {\n      ({ baseType, optional } = splitOptional(schemaValue));\n    } catch (e) {\n      issues.push({\n        key,\n        kind: \"invalid\",\n        message: String(e),\n      });\n      continue;\n    }\n\n    const raw = env[key];\n\n    if (raw === undefined || raw === \"\") {\n      if (optional) {\n        out[key] = undefined;\n      } else {\n        issues.push({\n          key,\n          kind: \"missing\",\n          message: \"missing required environment variable\",\n        });\n      }\n      continue;\n    }\n\n    try {\n      out[key] = parseByType(baseType, raw);\n    } catch (e) {\n      issues.push({\n        key,\n        kind: \"invalid\",\n        message: String(e),\n      });\n    }\n  }\n\n  if (issues.length > 0) {\n    throw new EnvDoctorError(issues);\n  }\n\n  return out as EnvDoctorResult<TSchema>;\n}\n"],"mappings":";AAAA,YAAY,YAAY;;;ACIjB,IAAM,iBAAN,cAA6B,MAAM;AAAA,EAGxC,YAAY,QAA0B;AACpC,UAAM,SAAS;AACf,UAAM,QAAQ,OAAO,IAAI,CAAC,MAAM,KAAK,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE;AAC1D,UAAM,CAAC,QAAQ,GAAG,KAAK,EAAE,KAAK,IAAI,CAAC;AACnC,SAAK,OAAO;AACZ,SAAK,SAAS;AAAA,EAChB;AACF;;;ACZO,SAAS,YAAY,MAAmB,KAAsB;AACnE,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO;AAAA,IAET,KAAK,UAAU;AAEb,YAAM,IAAI,OAAO,IAAI,KAAK,CAAC;AAC3B,UAAI,CAAC,OAAO,SAAS,CAAC,GAAG;AACvB,cAAM,IAAI,MAAM,yBAAyB,GAAG,GAAG;AAAA,MACjD;AACA,aAAO;AAAA,IACT;AAAA,IAEA,KAAK,WAAW;AACd,YAAM,IAAI,IAAI,KAAK,EAAE,YAAY;AACjC,UAAI,CAAC,QAAQ,KAAK,OAAO,KAAK,IAAI,EAAE,SAAS,CAAC,EAAG,QAAO;AACxD,UAAI,CAAC,SAAS,KAAK,MAAM,KAAK,KAAK,EAAE,SAAS,CAAC,EAAG,QAAO;AACzD,YAAM,IAAI;AAAA,QACR,yDAAyD,GAAG;AAAA,MAC9D;AAAA,IACF;AAAA,IAEA,KAAK,QAAQ;AACX,UAAI;AACF,eAAO,KAAK,MAAM,GAAG;AAAA,MACvB,QAAQ;AACN,cAAM,IAAI,MAAM,uBAAuB,GAAG,GAAG;AAAA,MAC/C;AAAA,IACF;AAAA,IAEA,KAAK,OAAO;AACV,UAAI;AAGF,YAAI,IAAI,GAAG;AACX,eAAO;AAAA,MACT,QAAQ;AACN,cAAM,IAAI,MAAM,sBAAsB,GAAG,GAAG;AAAA,MAC9C;AAAA,IACF;AAAA;AAAA,IAGA,SAAS;AAEP,YAAM,SAAgB;AACtB,aAAO;AAAA,IACT;AAAA,EACF;AACF;AAEO,SAAS,cAAc,aAG5B;AACA,QAAM,WAAW,YAAY,SAAS,GAAG;AACzC,QAAM,OAAO,WAAW,YAAY,MAAM,GAAG,EAAE,IAAI;AAGnD,QAAM,UAAU,CAAC,UAAU,UAAU,WAAW,QAAQ,KAAK;AAC7D,MAAI,CAAC,QAAQ,SAAS,IAAW,GAAG;AAClC,UAAM,IAAI;AAAA,MACR,qBAAqB,WAAW;AAAA,IAClC;AAAA,EACF;AAEA,SAAO,EAAE,UAAU,MAAqB,SAAS;AACnD;;;ACjEO,SAAS,iBACd,QACA,KAC0B;AAC1B,QAAM,SAA2B,CAAC;AAClC,QAAM,MAA+B,CAAC;AAEtC,aAAW,CAAC,KAAK,WAAW,KAAK,OAAO,QAAQ,MAAM,GAAG;AACvD,QAAI;AACJ,QAAI;AAEJ,QAAI;AACF,OAAC,EAAE,UAAU,SAAS,IAAI,cAAc,WAAW;AAAA,IACrD,SAAS,GAAG;AACV,aAAO,KAAK;AAAA,QACV;AAAA,QACA,MAAM;AAAA,QACN,SAAS,OAAO,CAAC;AAAA,MACnB,CAAC;AACD;AAAA,IACF;AAEA,UAAM,MAAM,IAAI,GAAG;AAEnB,QAAI,QAAQ,UAAa,QAAQ,IAAI;AACnC,UAAI,UAAU;AACZ,YAAI,GAAG,IAAI;AAAA,MACb,OAAO;AACL,eAAO,KAAK;AAAA,UACV;AAAA,UACA,MAAM;AAAA,UACN,SAAS;AAAA,QACX,CAAC;AAAA,MACH;AACA;AAAA,IACF;AAEA,QAAI;AACF,UAAI,GAAG,IAAI,YAAY,UAAU,GAAG;AAAA,IACtC,SAAS,GAAG;AACV,aAAO,KAAK;AAAA,QACV;AAAA,QACA,MAAM;AAAA,QACN,SAAS,OAAO,CAAC;AAAA,MACnB,CAAC;AAAA,IACH;AAAA,EACF;AAEA,MAAI,OAAO,SAAS,GAAG;AACrB,UAAM,IAAI,eAAe,MAAM;AAAA,EACjC;AAEA,SAAO;AACT;;;AHlDO,SAAS,UACd,QACA,UAA4B,CAAC,GACH;AAC1B,QAAM,EAAE,aAAa,MAAM,MAAM,QAAQ,IAAI,IAAI;AAEjD,MAAI,WAAY,CAAO,cAAO;AAE9B,SAAO,iBAAiB,QAAQ,GAAG;AACrC;","names":[]}

package/dist/cli.d.mts

@@ -0,0 +1,7 @@
+type Io = {
+    log: (msg: string) => void;
+    error: (msg: string) => void;
+};
+declare function runCli(argv: string[], io?: Io): number;
+
+export { runCli };

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+type Io = {
+    log: (msg: string) => void;
+    error: (msg: string) => void;
+};
+declare function runCli(argv: string[], io?: Io): number;
+
+export { runCli };

package/dist/cli.js

@@ -0,0 +1,247 @@
+"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/cli.ts
+var cli_exports = {};
+__export(cli_exports, {
+  runCli: () => runCli
+});
+module.exports = __toCommonJS(cli_exports);
+var import_node_fs = __toESM(require("fs"));
+var import_node_path = __toESM(require("path"));
+var dotenv2 = __toESM(require("dotenv"));
+
+// src/index.ts
+var dotenv = __toESM(require("dotenv"));
+
+// src/error.ts
+var EnvDoctorError = class extends Error {
+  constructor(issues) {
+    const header = "ENV validation failed";
+    const lines = issues.map((i) => `- ${i.key}: ${i.message}`);
+    super([header, ...lines].join("\n"));
+    this.name = "EnvDoctorError";
+    this.issues = issues;
+  }
+};
+
+// src/parsers.ts
+function parseByType(type, raw) {
+  switch (type) {
+    case "string":
+      return raw;
+    case "number": {
+      const n = Number(raw.trim());
+      if (!Number.isFinite(n)) {
+        throw new Error(`expected number, got "${raw}"`);
+      }
+      return n;
+    }
+    case "boolean": {
+      const v = raw.trim().toLowerCase();
+      if (["true", "1", "yes", "y", "on"].includes(v)) return true;
+      if (["false", "0", "no", "n", "off"].includes(v)) return false;
+      throw new Error(
+        `expected boolean (true/false/1/0/yes/no/on/off), got "${raw}"`
+      );
+    }
+    case "json": {
+      try {
+        return JSON.parse(raw);
+      } catch {
+        throw new Error(`expected json, got "${raw}"`);
+      }
+    }
+    case "url": {
+      try {
+        new URL(raw);
+        return raw;
+      } catch {
+        throw new Error(`expected url, got "${raw}"`);
+      }
+    }
+    /* v8 ignore next -- @preserve */
+    default: {
+      const _never = type;
+      return _never;
+    }
+  }
+}
+function splitOptional(schemaValue) {
+  const optional = schemaValue.endsWith("?");
+  const base = optional ? schemaValue.slice(0, -1) : schemaValue;
+  const allowed = ["string", "number", "boolean", "json", "url"];
+  if (!allowed.includes(base)) {
+    throw new Error(
+      `Unsupported type "${schemaValue}". Supported: string, number, boolean, json, url (optional with ?)`
+    );
+  }
+  return { baseType: base, optional };
+}
+
+// src/validator.ts
+function validateAndParse(schema, env) {
+  const issues = [];
+  const out = {};
+  for (const [key, schemaValue] of Object.entries(schema)) {
+    let baseType;
+    let optional;
+    try {
+      ({ baseType, optional } = splitOptional(schemaValue));
+    } catch (e) {
+      issues.push({
+        key,
+        kind: "invalid",
+        message: String(e)
+      });
+      continue;
+    }
+    const raw = env[key];
+    if (raw === void 0 || raw === "") {
+      if (optional) {
+        out[key] = void 0;
+      } else {
+        issues.push({
+          key,
+          kind: "missing",
+          message: "missing required environment variable"
+        });
+      }
+      continue;
+    }
+    try {
+      out[key] = parseByType(baseType, raw);
+    } catch (e) {
+      issues.push({
+        key,
+        kind: "invalid",
+        message: String(e)
+      });
+    }
+  }
+  if (issues.length > 0) {
+    throw new EnvDoctorError(issues);
+  }
+  return out;
+}
+
+// src/index.ts
+function envDoctor(schema, options = {}) {
+  const { loadDotEnv = true, env = process.env } = options;
+  if (loadDotEnv) dotenv.config();
+  return validateAndParse(schema, env);
+}
+
+// src/cli.ts
+function parseArgs(argv) {
+  const out = { useDotenv: true };
+  const [cmd, ...rest] = argv;
+  out.cmd = cmd;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--schema") {
+      out.schemaPath = rest[++i];
+    } else if (a.startsWith("--schema=")) {
+      out.schemaPath = a.split("=", 2)[1];
+    } else if (a === "--env-file") {
+      out.envFile = rest[++i];
+    } else if (a.startsWith("--env-file=")) {
+      out.envFile = a.split("=", 2)[1];
+    } else if (a === "--no-dotenv") {
+      out.useDotenv = false;
+    }
+  }
+  return out;
+}
+function loadSchema(schemaPath) {
+  const abs = import_node_path.default.resolve(process.cwd(), schemaPath);
+  const raw = import_node_fs.default.readFileSync(abs, "utf8");
+  const json = JSON.parse(raw);
+  if (!json || typeof json !== "object" || Array.isArray(json)) {
+    throw new Error("Schema must be a JSON object of key -> type.");
+  }
+  for (const [k, v] of Object.entries(json)) {
+    if (typeof k !== "string" || typeof v !== "string") {
+      throw new Error("Schema must be a JSON object of string -> string.");
+    }
+  }
+  return json;
+}
+function runCli(argv, io = console) {
+  const { cmd, schemaPath, envFile, useDotenv } = parseArgs(argv);
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    io.log(
+      [
+        "env-typed-checker",
+        "",
+        "Usage:",
+        "  env-typed-checker check --schema <file> [--env-file <file>] [--no-dotenv]",
+        "",
+        "Options:",
+        "  --schema <file>     Path to schema JSON (required)",
+        "  --env-file <file>   Env file path (default: .env)",
+        "  --no-dotenv         Do not load env file; use process.env only",
+        "",
+        "Exit codes:",
+        "  0 = OK, 1 = validation failed, 2 = CLI error"
+      ].join("\n")
+    );
+    return 0;
+  }
+  if (cmd !== "check") {
+    io.error(`Unknown command: ${cmd}`);
+    return 2;
+  }
+  if (!schemaPath) {
+    io.error("Missing required option: --schema <file>");
+    return 2;
+  }
+  try {
+    if (useDotenv) {
+      const p = envFile ?? ".env";
+      dotenv2.config({ path: import_node_path.default.resolve(process.cwd(), p) });
+    }
+    const schema = loadSchema(schemaPath);
+    envDoctor(schema, { loadDotEnv: false, env: process.env });
+    io.log("\u2705 Environment is valid.");
+    return 0;
+  } catch (e) {
+    if (e instanceof EnvDoctorError) {
+      io.error(e.message);
+      return 1;
+    }
+    io.error(String(e));
+    return 2;
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runCli
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts","../src/index.ts","../src/error.ts","../src/parsers.ts","../src/validator.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport * as dotenv from \"dotenv\";\nimport { envDoctor, EnvDoctorError } from \"./index\";\nimport type { EnvDoctorSchema } from \"./types\";\n\ntype Io = {\n  log: (msg: string) => void;\n  error: (msg: string) => void;\n};\n\nfunction parseArgs(argv: string[]) {\n  const out: {\n    cmd?: string;\n    schemaPath?: string;\n    envFile?: string;\n    useDotenv: boolean;\n  } = { useDotenv: true };\n\n  const [cmd, ...rest] = argv;\n  out.cmd = cmd;\n\n  for (let i = 0; i < rest.length; i++) {\n    const a = rest[i];\n\n    if (a === \"--schema\") {\n      out.schemaPath = rest[++i];\n    } else if (a.startsWith(\"--schema=\")) {\n      out.schemaPath = a.split(\"=\", 2)[1];\n    } else if (a === \"--env-file\") {\n      out.envFile = rest[++i];\n    } else if (a.startsWith(\"--env-file=\")) {\n      out.envFile = a.split(\"=\", 2)[1];\n    } else if (a === \"--no-dotenv\") {\n      out.useDotenv = false;\n    }\n  }\n\n  return out;\n}\n\nfunction loadSchema(schemaPath: string): EnvDoctorSchema {\n  const abs = path.resolve(process.cwd(), schemaPath);\n  const raw = fs.readFileSync(abs, \"utf8\");\n  const json = JSON.parse(raw);\n\n  if (!json || typeof json !== \"object\" || Array.isArray(json)) {\n    throw new Error(\"Schema must be a JSON object of key -> type.\");\n  }\n\n  // Ensure values are strings\n  for (const [k, v] of Object.entries(json)) {\n    if (typeof k !== \"string\" || typeof v !== \"string\") {\n      throw new Error(\"Schema must be a JSON object of string -> string.\");\n    }\n  }\n\n  return json as EnvDoctorSchema;\n}\n\nexport function runCli(argv: string[], io: Io = console): number {\n  const { cmd, schemaPath, envFile, useDotenv } = parseArgs(argv);\n\n  if (!cmd || cmd === \"help\" || cmd === \"--help\" || cmd === \"-h\") {\n    io.log(\n      [\n        \"env-typed-checker\",\n        \"\",\n        \"Usage:\",\n        \"  env-typed-checker check --schema <file> [--env-file <file>] [--no-dotenv]\",\n        \"\",\n        \"Options:\",\n        \"  --schema <file>     Path to schema JSON (required)\",\n        \"  --env-file <file>   Env file path (default: .env)\",\n        \"  --no-dotenv         Do not load env file; use process.env only\",\n        \"\",\n        \"Exit codes:\",\n        \"  0 = OK, 1 = validation failed, 2 = CLI error\",\n      ].join(\"\\n\"),\n    );\n    return 0;\n  }\n\n  if (cmd !== \"check\") {\n    io.error(`Unknown command: ${cmd}`);\n    return 2;\n  }\n\n  if (!schemaPath) {\n    io.error(\"Missing required option: --schema <file>\");\n    return 2;\n  }\n\n  try {\n    if (useDotenv) {\n      const p = envFile ?? \".env\";\n      dotenv.config({ path: path.resolve(process.cwd(), p) });\n    }\n\n    const schema = loadSchema(schemaPath);\n\n    // envDoctor will validate and throw EnvDoctorError if invalid\n    envDoctor(schema, { loadDotEnv: false, env: process.env });\n\n    io.log(\"✅ Environment is valid.\");\n    return 0;\n  } catch (e) {\n    if (e instanceof EnvDoctorError) {\n      io.error(e.message);\n      return 1;\n    }\n    io.error(String(e));\n    return 2;\n  }\n}\n","import * as dotenv from \"dotenv\";\nimport { validateAndParse } from \"./validator\";\nimport type { EnvDoctorOptions, EnvDoctorResult, EnvDoctorSchema } from \"./types\";\n\nexport type { EnvDoctorOptions, EnvDoctorSchema } from \"./types\";\nexport { EnvDoctorError } from \"./error\";\n\nexport function envDoctor<TSchema extends EnvDoctorSchema>(\n  schema: TSchema,\n  options: EnvDoctorOptions = {}\n): EnvDoctorResult<TSchema> {\n  const { loadDotEnv = true, env = process.env } = options;\n\n  if (loadDotEnv) dotenv.config();\n\n  return validateAndParse(schema, env);\n}\n","export type EnvDoctorIssue =\n  | { key: string; kind: \"missing\"; message: string }\n  | { key: string; kind: \"invalid\"; message: string };\n\nexport class EnvDoctorError extends Error {\n  public readonly issues: EnvDoctorIssue[];\n\n  constructor(issues: EnvDoctorIssue[]) {\n    const header = \"ENV validation failed\";\n    const lines = issues.map((i) => `- ${i.key}: ${i.message}`);\n    super([header, ...lines].join(\"\\n\"));\n    this.name = \"EnvDoctorError\";\n    this.issues = issues;\n  }\n}\n","import type { EnvBaseType } from \"./types\";\n\nexport function parseByType(type: EnvBaseType, raw: string): unknown {\n  switch (type) {\n    case \"string\":\n      return raw;\n\n    case \"number\": {\n      // Trim to handle \" 3000 \"\n      const n = Number(raw.trim());\n      if (!Number.isFinite(n)) {\n        throw new Error(`expected number, got \"${raw}\"`);\n      }\n      return n;\n    }\n\n    case \"boolean\": {\n      const v = raw.trim().toLowerCase();\n      if ([\"true\", \"1\", \"yes\", \"y\", \"on\"].includes(v)) return true;\n      if ([\"false\", \"0\", \"no\", \"n\", \"off\"].includes(v)) return false;\n      throw new Error(\n        `expected boolean (true/false/1/0/yes/no/on/off), got \"${raw}\"`,\n      );\n    }\n\n    case \"json\": {\n      try {\n        return JSON.parse(raw);\n      } catch {\n        throw new Error(`expected json, got \"${raw}\"`);\n      }\n    }\n\n    case \"url\": {\n      try {\n        // If it doesn't parse as a URL, this throws.\n        // We return the original string (common for configs).\n        new URL(raw);\n        return raw;\n      } catch {\n        throw new Error(`expected url, got \"${raw}\"`);\n      }\n    }\n\n    /* v8 ignore next -- @preserve */\n    default: {\n      // Exhaustive check (unreachable at runtime)\n      const _never: never = type;\n      return _never;\n    }\n  }\n}\n\nexport function splitOptional(schemaValue: string): {\n  baseType: EnvBaseType;\n  optional: boolean;\n} {\n  const optional = schemaValue.endsWith(\"?\");\n  const base = optional ? schemaValue.slice(0, -1) : schemaValue;\n\n  // runtime safety\n  const allowed = [\"string\", \"number\", \"boolean\", \"json\", \"url\"] as const;\n  if (!allowed.includes(base as any)) {\n    throw new Error(\n      `Unsupported type \"${schemaValue}\". Supported: string, number, boolean, json, url (optional with ?)`,\n    );\n  }\n\n  return { baseType: base as EnvBaseType, optional };\n}\n","import { EnvDoctorError, type EnvDoctorIssue } from \"./error\";\nimport { parseByType, splitOptional } from \"./parsers\";\nimport type { EnvDoctorResult, EnvDoctorSchema } from \"./types\";\n\nexport function validateAndParse<TSchema extends EnvDoctorSchema>(\n  schema: TSchema,\n  env: Record<string, string | undefined>,\n): EnvDoctorResult<TSchema> {\n  const issues: EnvDoctorIssue[] = [];\n  const out: Record<string, unknown> = {};\n\n  for (const [key, schemaValue] of Object.entries(schema)) {\n    let baseType: any;\n    let optional: boolean;\n\n    try {\n      ({ baseType, optional } = splitOptional(schemaValue));\n    } catch (e) {\n      issues.push({\n        key,\n        kind: \"invalid\",\n        message: String(e),\n      });\n      continue;\n    }\n\n    const raw = env[key];\n\n    if (raw === undefined || raw === \"\") {\n      if (optional) {\n        out[key] = undefined;\n      } else {\n        issues.push({\n          key,\n          kind: \"missing\",\n          message: \"missing required environment variable\",\n        });\n      }\n      continue;\n    }\n\n    try {\n      out[key] = parseByType(baseType, raw);\n    } catch (e) {\n      issues.push({\n        key,\n        kind: \"invalid\",\n        message: String(e),\n      });\n    }\n  }\n\n  if (issues.length > 0) {\n    throw new EnvDoctorError(issues);\n  }\n\n  return out as EnvDoctorResult<TSchema>;\n}\n"],"mappings":"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","names":["dotenv","path","fs"]}

package/dist/cli.mjs

@@ -0,0 +1,94 @@
+import {
+  EnvDoctorError,
+  envDoctor
+} from "./chunk-U6GH2TRS.mjs";
+
+// src/cli.ts
+import fs from "fs";
+import path from "path";
+import * as dotenv from "dotenv";
+function parseArgs(argv) {
+  const out = { useDotenv: true };
+  const [cmd, ...rest] = argv;
+  out.cmd = cmd;
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (a === "--schema") {
+      out.schemaPath = rest[++i];
+    } else if (a.startsWith("--schema=")) {
+      out.schemaPath = a.split("=", 2)[1];
+    } else if (a === "--env-file") {
+      out.envFile = rest[++i];
+    } else if (a.startsWith("--env-file=")) {
+      out.envFile = a.split("=", 2)[1];
+    } else if (a === "--no-dotenv") {
+      out.useDotenv = false;
+    }
+  }
+  return out;
+}
+function loadSchema(schemaPath) {
+  const abs = path.resolve(process.cwd(), schemaPath);
+  const raw = fs.readFileSync(abs, "utf8");
+  const json = JSON.parse(raw);
+  if (!json || typeof json !== "object" || Array.isArray(json)) {
+    throw new Error("Schema must be a JSON object of key -> type.");
+  }
+  for (const [k, v] of Object.entries(json)) {
+    if (typeof k !== "string" || typeof v !== "string") {
+      throw new Error("Schema must be a JSON object of string -> string.");
+    }
+  }
+  return json;
+}
+function runCli(argv, io = console) {
+  const { cmd, schemaPath, envFile, useDotenv } = parseArgs(argv);
+  if (!cmd || cmd === "help" || cmd === "--help" || cmd === "-h") {
+    io.log(
+      [
+        "env-typed-checker",
+        "",
+        "Usage:",
+        "  env-typed-checker check --schema <file> [--env-file <file>] [--no-dotenv]",
+        "",
+        "Options:",
+        "  --schema <file>     Path to schema JSON (required)",
+        "  --env-file <file>   Env file path (default: .env)",
+        "  --no-dotenv         Do not load env file; use process.env only",
+        "",
+        "Exit codes:",
+        "  0 = OK, 1 = validation failed, 2 = CLI error"
+      ].join("\n")
+    );
+    return 0;
+  }
+  if (cmd !== "check") {
+    io.error(`Unknown command: ${cmd}`);
+    return 2;
+  }
+  if (!schemaPath) {
+    io.error("Missing required option: --schema <file>");
+    return 2;
+  }
+  try {
+    if (useDotenv) {
+      const p = envFile ?? ".env";
+      dotenv.config({ path: path.resolve(process.cwd(), p) });
+    }
+    const schema = loadSchema(schemaPath);
+    envDoctor(schema, { loadDotEnv: false, env: process.env });
+    io.log("\u2705 Environment is valid.");
+    return 0;
+  } catch (e) {
+    if (e instanceof EnvDoctorError) {
+      io.error(e.message);
+      return 1;
+    }
+    io.error(String(e));
+    return 2;
+  }
+}
+export {
+  runCli
+};
+//# sourceMappingURL=cli.mjs.map

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["import fs from \"node:fs\";\nimport path from \"node:path\";\nimport * as dotenv from \"dotenv\";\nimport { envDoctor, EnvDoctorError } from \"./index\";\nimport type { EnvDoctorSchema } from \"./types\";\n\ntype Io = {\n  log: (msg: string) => void;\n  error: (msg: string) => void;\n};\n\nfunction parseArgs(argv: string[]) {\n  const out: {\n    cmd?: string;\n    schemaPath?: string;\n    envFile?: string;\n    useDotenv: boolean;\n  } = { useDotenv: true };\n\n  const [cmd, ...rest] = argv;\n  out.cmd = cmd;\n\n  for (let i = 0; i < rest.length; i++) {\n    const a = rest[i];\n\n    if (a === \"--schema\") {\n      out.schemaPath = rest[++i];\n    } else if (a.startsWith(\"--schema=\")) {\n      out.schemaPath = a.split(\"=\", 2)[1];\n    } else if (a === \"--env-file\") {\n      out.envFile = rest[++i];\n    } else if (a.startsWith(\"--env-file=\")) {\n      out.envFile = a.split(\"=\", 2)[1];\n    } else if (a === \"--no-dotenv\") {\n      out.useDotenv = false;\n    }\n  }\n\n  return out;\n}\n\nfunction loadSchema(schemaPath: string): EnvDoctorSchema {\n  const abs = path.resolve(process.cwd(), schemaPath);\n  const raw = fs.readFileSync(abs, \"utf8\");\n  const json = JSON.parse(raw);\n\n  if (!json || typeof json !== \"object\" || Array.isArray(json)) {\n    throw new Error(\"Schema must be a JSON object of key -> type.\");\n  }\n\n  // Ensure values are strings\n  for (const [k, v] of Object.entries(json)) {\n    if (typeof k !== \"string\" || typeof v !== \"string\") {\n      throw new Error(\"Schema must be a JSON object of string -> string.\");\n    }\n  }\n\n  return json as EnvDoctorSchema;\n}\n\nexport function runCli(argv: string[], io: Io = console): number {\n  const { cmd, schemaPath, envFile, useDotenv } = parseArgs(argv);\n\n  if (!cmd || cmd === \"help\" || cmd === \"--help\" || cmd === \"-h\") {\n    io.log(\n      [\n        \"env-typed-checker\",\n        \"\",\n        \"Usage:\",\n        \"  env-typed-checker check --schema <file> [--env-file <file>] [--no-dotenv]\",\n        \"\",\n        \"Options:\",\n        \"  --schema <file>     Path to schema JSON (required)\",\n        \"  --env-file <file>   Env file path (default: .env)\",\n        \"  --no-dotenv         Do not load env file; use process.env only\",\n        \"\",\n        \"Exit codes:\",\n        \"  0 = OK, 1 = validation failed, 2 = CLI error\",\n      ].join(\"\\n\"),\n    );\n    return 0;\n  }\n\n  if (cmd !== \"check\") {\n    io.error(`Unknown command: ${cmd}`);\n    return 2;\n  }\n\n  if (!schemaPath) {\n    io.error(\"Missing required option: --schema <file>\");\n    return 2;\n  }\n\n  try {\n    if (useDotenv) {\n      const p = envFile ?? \".env\";\n      dotenv.config({ path: path.resolve(process.cwd(), p) });\n    }\n\n    const schema = loadSchema(schemaPath);\n\n    // envDoctor will validate and throw EnvDoctorError if invalid\n    envDoctor(schema, { loadDotEnv: false, env: process.env });\n\n    io.log(\"✅ Environment is valid.\");\n    return 0;\n  } catch (e) {\n    if (e instanceof EnvDoctorError) {\n      io.error(e.message);\n      return 1;\n    }\n    io.error(String(e));\n    return 2;\n  }\n}\n"],"mappings":";;;;;;AAAA,OAAO,QAAQ;AACf,OAAO,UAAU;AACjB,YAAY,YAAY;AASxB,SAAS,UAAU,MAAgB;AACjC,QAAM,MAKF,EAAE,WAAW,KAAK;AAEtB,QAAM,CAAC,KAAK,GAAG,IAAI,IAAI;AACvB,MAAI,MAAM;AAEV,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,UAAM,IAAI,KAAK,CAAC;AAEhB,QAAI,MAAM,YAAY;AACpB,UAAI,aAAa,KAAK,EAAE,CAAC;AAAA,IAC3B,WAAW,EAAE,WAAW,WAAW,GAAG;AACpC,UAAI,aAAa,EAAE,MAAM,KAAK,CAAC,EAAE,CAAC;AAAA,IACpC,WAAW,MAAM,cAAc;AAC7B,UAAI,UAAU,KAAK,EAAE,CAAC;AAAA,IACxB,WAAW,EAAE,WAAW,aAAa,GAAG;AACtC,UAAI,UAAU,EAAE,MAAM,KAAK,CAAC,EAAE,CAAC;AAAA,IACjC,WAAW,MAAM,eAAe;AAC9B,UAAI,YAAY;AAAA,IAClB;AAAA,EACF;AAEA,SAAO;AACT;AAEA,SAAS,WAAW,YAAqC;AACvD,QAAM,MAAM,KAAK,QAAQ,QAAQ,IAAI,GAAG,UAAU;AAClD,QAAM,MAAM,GAAG,aAAa,KAAK,MAAM;AACvC,QAAM,OAAO,KAAK,MAAM,GAAG;AAE3B,MAAI,CAAC,QAAQ,OAAO,SAAS,YAAY,MAAM,QAAQ,IAAI,GAAG;AAC5D,UAAM,IAAI,MAAM,8CAA8C;AAAA,EAChE;AAGA,aAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,IAAI,GAAG;AACzC,QAAI,OAAO,MAAM,YAAY,OAAO,MAAM,UAAU;AAClD,YAAM,IAAI,MAAM,mDAAmD;AAAA,IACrE;AAAA,EACF;AAEA,SAAO;AACT;AAEO,SAAS,OAAO,MAAgB,KAAS,SAAiB;AAC/D,QAAM,EAAE,KAAK,YAAY,SAAS,UAAU,IAAI,UAAU,IAAI;AAE9D,MAAI,CAAC,OAAO,QAAQ,UAAU,QAAQ,YAAY,QAAQ,MAAM;AAC9D,OAAG;AAAA,MACD;AAAA,QACE;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,MACF,EAAE,KAAK,IAAI;AAAA,IACb;AACA,WAAO;AAAA,EACT;AAEA,MAAI,QAAQ,SAAS;AACnB,OAAG,MAAM,oBAAoB,GAAG,EAAE;AAClC,WAAO;AAAA,EACT;AAEA,MAAI,CAAC,YAAY;AACf,OAAG,MAAM,0CAA0C;AACnD,WAAO;AAAA,EACT;AAEA,MAAI;AACF,QAAI,WAAW;AACb,YAAM,IAAI,WAAW;AACrB,MAAO,cAAO,EAAE,MAAM,KAAK,QAAQ,QAAQ,IAAI,GAAG,CAAC,EAAE,CAAC;AAAA,IACxD;AAEA,UAAM,SAAS,WAAW,UAAU;AAGpC,cAAU,QAAQ,EAAE,YAAY,OAAO,KAAK,QAAQ,IAAI,CAAC;AAEzD,OAAG,IAAI,8BAAyB;AAChC,WAAO;AAAA,EACT,SAAS,GAAG;AACV,QAAI,aAAa,gBAAgB;AAC/B,SAAG,MAAM,EAAE,OAAO;AAClB,aAAO;AAAA,IACT;AACA,OAAG,MAAM,OAAO,CAAC,CAAC;AAClB,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/index.mjs

@@ -1,123 +1,7 @@
-// src/index.ts
-import * as dotenv from "dotenv";
-
-// src/error.ts
-var EnvDoctorError = class extends Error {
-  constructor(issues) {
-    const header = "ENV validation failed";
-    const lines = issues.map((i) => `- ${i.key}: ${i.message}`);
-    super([header, ...lines].join("\n"));
-    this.name = "EnvDoctorError";
-    this.issues = issues;
-  }
-};
-
-// src/parsers.ts
-function parseByType(type, raw) {
-  switch (type) {
-    case "string":
-      return raw;
-    case "number": {
-      const n = Number(raw.trim());
-      if (!Number.isFinite(n)) {
-        throw new Error(`expected number, got "${raw}"`);
-      }
-      return n;
-    }
-    case "boolean": {
-      const v = raw.trim().toLowerCase();
-      if (["true", "1", "yes", "y", "on"].includes(v)) return true;
-      if (["false", "0", "no", "n", "off"].includes(v)) return false;
-      throw new Error(
-        `expected boolean (true/false/1/0/yes/no/on/off), got "${raw}"`
-      );
-    }
-    case "json": {
-      try {
-        return JSON.parse(raw);
-      } catch {
-        throw new Error(`expected json, got "${raw}"`);
-      }
-    }
-    case "url": {
-      try {
-        new URL(raw);
-        return raw;
-      } catch {
-        throw new Error(`expected url, got "${raw}"`);
-      }
-    }
-    /* v8 ignore next -- @preserve */
-    default: {
-      const _never = type;
-      return _never;
-    }
-  }
-}
-function splitOptional(schemaValue) {
-  const optional = schemaValue.endsWith("?");
-  const base = optional ? schemaValue.slice(0, -1) : schemaValue;
-  const allowed = ["string", "number", "boolean", "json", "url"];
-  if (!allowed.includes(base)) {
-    throw new Error(
-      `Unsupported type "${schemaValue}". Supported: string, number, boolean, json, url (optional with ?)`
-    );
-  }
-  return { baseType: base, optional };
-}
-
-// src/validator.ts
-function validateAndParse(schema, env) {
-  const issues = [];
-  const out = {};
-  for (const [key, schemaValue] of Object.entries(schema)) {
-    let baseType;
-    let optional;
-    try {
-      ({ baseType, optional } = splitOptional(schemaValue));
-    } catch (e) {
-      issues.push({
-        key,
-        kind: "invalid",
-        message: String(e)
-      });
-      continue;
-    }
-    const raw = env[key];
-    if (raw === void 0 || raw === "") {
-      if (optional) {
-        out[key] = void 0;
-      } else {
-        issues.push({
-          key,
-          kind: "missing",
-          message: "missing required environment variable"
-        });
-      }
-      continue;
-    }
-    try {
-      out[key] = parseByType(baseType, raw);
-    } catch (e) {
-      issues.push({
-        key,
-        kind: "invalid",
-        message: String(e)
-      });
-    }
-  }
-  if (issues.length > 0) {
-    throw new EnvDoctorError(issues);
-  }
-  return out;
-}
-
-// src/index.ts
-function envDoctor(schema, options = {}) {
-  const { loadDotEnv = true, env = process.env } = options;
-  if (loadDotEnv) dotenv.config();
-  return validateAndParse(schema, env);
-}
+import {
+  EnvDoctorError,
+  envDoctor
+} from "./chunk-U6GH2TRS.mjs";
 export {
   EnvDoctorError,
   envDoctor

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/error.ts","../src/parsers.ts","../src/validator.ts"],"sourcesContent":["import * as dotenv from \"dotenv\";\nimport { validateAndParse } from \"./validator\";\nimport type { EnvDoctorOptions, EnvDoctorResult, EnvDoctorSchema } from \"./types\";\n\nexport type { EnvDoctorOptions, EnvDoctorSchema } from \"./types\";\nexport { EnvDoctorError } from \"./error\";\n\nexport function envDoctor<TSchema extends EnvDoctorSchema>(\n  schema: TSchema,\n  options: EnvDoctorOptions = {}\n): EnvDoctorResult<TSchema> {\n  const { loadDotEnv = true, env = process.env } = options;\n\n  if (loadDotEnv) dotenv.config();\n\n  return validateAndParse(schema, env);\n}\n","export type EnvDoctorIssue =\n  | { key: string; kind: \"missing\"; message: string }\n  | { key: string; kind: \"invalid\"; message: string };\n\nexport class EnvDoctorError extends Error {\n  public readonly issues: EnvDoctorIssue[];\n\n  constructor(issues: EnvDoctorIssue[]) {\n    const header = \"ENV validation failed\";\n    const lines = issues.map((i) => `- ${i.key}: ${i.message}`);\n    super([header, ...lines].join(\"\\n\"));\n    this.name = \"EnvDoctorError\";\n    this.issues = issues;\n  }\n}\n","import type { EnvBaseType } from \"./types\";\n\nexport function parseByType(type: EnvBaseType, raw: string): unknown {\n  switch (type) {\n    case \"string\":\n      return raw;\n\n    case \"number\": {\n      // Trim to handle \" 3000 \"\n      const n = Number(raw.trim());\n      if (!Number.isFinite(n)) {\n        throw new Error(`expected number, got \"${raw}\"`);\n      }\n      return n;\n    }\n\n    case \"boolean\": {\n      const v = raw.trim().toLowerCase();\n      if ([\"true\", \"1\", \"yes\", \"y\", \"on\"].includes(v)) return true;\n      if ([\"false\", \"0\", \"no\", \"n\", \"off\"].includes(v)) return false;\n      throw new Error(\n        `expected boolean (true/false/1/0/yes/no/on/off), got \"${raw}\"`,\n      );\n    }\n\n    case \"json\": {\n      try {\n        return JSON.parse(raw);\n      } catch {\n        throw new Error(`expected json, got \"${raw}\"`);\n      }\n    }\n\n    case \"url\": {\n      try {\n        // If it doesn't parse as a URL, this throws.\n        // We return the original string (common for configs).\n        new URL(raw);\n        return raw;\n      } catch {\n        throw new Error(`expected url, got \"${raw}\"`);\n      }\n    }\n\n    /* v8 ignore next -- @preserve */\n    default: {\n      // Exhaustive check (unreachable at runtime)\n      const _never: never = type;\n      return _never;\n    }\n  }\n}\n\nexport function splitOptional(schemaValue: string): {\n  baseType: EnvBaseType;\n  optional: boolean;\n} {\n  const optional = schemaValue.endsWith(\"?\");\n  const base = optional ? schemaValue.slice(0, -1) : schemaValue;\n\n  // runtime safety\n  const allowed = [\"string\", \"number\", \"boolean\", \"json\", \"url\"] as const;\n  if (!allowed.includes(base as any)) {\n    throw new Error(\n      `Unsupported type \"${schemaValue}\". Supported: string, number, boolean, json, url (optional with ?)`,\n    );\n  }\n\n  return { baseType: base as EnvBaseType, optional };\n}\n","import { EnvDoctorError, type EnvDoctorIssue } from \"./error\";\nimport { parseByType, splitOptional } from \"./parsers\";\nimport type { EnvDoctorResult, EnvDoctorSchema } from \"./types\";\n\nexport function validateAndParse<TSchema extends EnvDoctorSchema>(\n  schema: TSchema,\n  env: Record<string, string | undefined>,\n): EnvDoctorResult<TSchema> {\n  const issues: EnvDoctorIssue[] = [];\n  const out: Record<string, unknown> = {};\n\n  for (const [key, schemaValue] of Object.entries(schema)) {\n    let baseType: any;\n    let optional: boolean;\n\n    try {\n      ({ baseType, optional } = splitOptional(schemaValue));\n    } catch (e) {\n      issues.push({\n        key,\n        kind: \"invalid\",\n        message: String(e),\n      });\n      continue;\n    }\n\n    const raw = env[key];\n\n    if (raw === undefined || raw === \"\") {\n      if (optional) {\n        out[key] = undefined;\n      } else {\n        issues.push({\n          key,\n          kind: \"missing\",\n          message: \"missing required environment variable\",\n        });\n      }\n      continue;\n    }\n\n    try {\n      out[key] = parseByType(baseType, raw);\n    } catch (e) {\n      issues.push({\n        key,\n        kind: \"invalid\",\n        message: String(e),\n      });\n    }\n  }\n\n  if (issues.length > 0) {\n    throw new EnvDoctorError(issues);\n  }\n\n  return out as EnvDoctorResult<TSchema>;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "env-typed-checker",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Validate and parse environment variables with a tiny, type-safe schema.",
   "license": "MIT",
   "type": "commonjs",
@@ -8,6 +8,9 @@
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "bin": {
+    "env-typed-checker": "./bin/env-typed-checker.cjs"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -17,6 +20,7 @@
   },
   "files": [
     "dist",
+    "bin",
     "README.md",
     "LICENSE"
   ],