env-typed-checker 0.1.1 → 0.2.1

package/README.md

@@ -1,34 +1,47 @@
-# 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 required variables
+- ❌ Wrong types (e.g. `PORT="abc"`)
+- ❌ Invalid URLs / emails / JSON
+- ❌ Values not matching allowed enums or regex patterns
+- ✅ Optional values + defaults
+- ✅ CLI checks for CI + .env generation
 
-- ❌ missing environment variables  
-- ❌ wrong types (e.g. PORT="abc")  
-- ❌ invalid URLs or JSON  
-- ❌ silent configuration mistakes  
 
 ---
 
 ## ✨ 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?"`, `"email"` `"url"`, `"json"`, `"string"`)
+- Advanced specs: `enum` and `regex`
+- Optional values with `?` and `optional: true`
+- Defaults (typed + validated)
+- CLI:
+
+  - `check` → validate env
+  - `generate` → generate/update `.env` from schema (no overwrite by default)
+- Uses `.env` via `dotenv` (optional)
+- Friendly aggregated errors (see everything that’s wrong at once)
 
 ---
 
-## 📦 Installation
+## 📦 Install
 
 ```bash
 npm install env-typed-checker
 ```
-### 🚀 Basic Usage
+
+Or run via npx:
+
+```bash
+npx env-typed-checker --help
+```
+
+## 🚀 Quick Start (Code)
 
 ```ts
 import { envDoctor } from "env-typed-checker";
@@ -36,13 +49,22 @@ import { envDoctor } from "env-typed-checker";
 export const config = envDoctor({
   PORT: "number",
   DB_URL: "url",
-  DEBUG: "boolean?"
+  ADMIN_EMAIL: "email",
+  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)
+
+* ADMIN_EMAIL → string (validated as email)
+
+* DEBUG → boolean | undefined (optional)
+
 
 ### 🧩 Supported Types
 | Type | Description |
@@ -52,87 +74,225 @@ export const config = envDoctor({
 | **boolean** | Supports `true` / `false`, `1` / `0`, and `yes` / `no` |
 | **json** | Validates and parses a valid JSON string |
 | **url** | Validates for a properly formatted URL |
+| **email** | Validates for a properly formatted email |
+
 
 ### Optional Values
 Add ? to make a variable optional:
 ```ts
-{ DEBUG: "boolean?" }
+envDoctor({ DEBUG: "boolean?" });
+```
+
+Or use object-style:
+
+```ts
+envDoctor({
+  DEBUG: { type: "boolean", optional: true },
+});
+```
+Missing optional vars become `undefined` unless you provide a default.
+
+### 🎯 Defaults
+Defaults can be provided in object-style specs.
+
+```ts
+import { envDoctor } from "env-typed-checker";
+
+const config = envDoctor({
+  PORT: { type: "number", default: 3000 },
+  DEBUG: { type: "boolean", default: "false" }, // string is allowed (parsed)
+  NODE_ENV: { type: "enum", values: ["dev", "prod"], default: "dev" },
+});
+```
+
+### Notes:
+
+- `number` default: number or string (string will be parsed)
+- `boolean` default: boolean or string (string will be parsed)
+- `url/email` defaults must be strings and must validate
+- `json` defaults can be any JSON-like value
+
+### ✅ Enum and Regex
+
+### Enum
+
+```ts
+const config = envDoctor({
+  NODE_ENV: { type: "enum", values: ["dev", "prod"] },
+});
+```
+
+### Regex
+
+```ts
+const config = envDoctor({
+  SLUG: { type: "regex", pattern: "^[a-z0-9-]+$", flags: "i" },
+});
+```
+
+### ⚙️ 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
 ```
-If missing → value will be undefined.
 
 ### ❌ Error Example
-Given this .env:
-```.env
+
+Given a `.env` like:
+
+```env
 PORT=abc
 DB_URL=not-a-url
-Code:
+NODE_ENV=staging
 ```
+
 ```ts
+import { envDoctor } from "env-typed-checker";
+
 envDoctor({
   PORT: "number",
   DB_URL: "url"
+  NODE_ENV: { type: "enum", values: ["dev", "prod"] },
 });
 ```
+
 ### Output:
 
 ```ts
 ENV validation failed
 - PORT: expected number, got "abc"
 - DB_URL: expected url, got "not-a-url"
+- NODE_ENV: must be one of [dev, prod]
 ```
 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",
+  "ADMIN_EMAIL": "email",
+  "DEBUG": "boolean?",
+  "NODE_ENV": { "type": "enum", "values": ["dev", "prod"] },
+  "SLUG": { "type": "regex", "pattern": "^[a-z0-9-]+$", "flags": "i" }
+}
 ```
-### 🧪 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
+
+Useful flags
+
+```bash
+# Use a specific env file (instead of .env)
+npx env-typed-checker check --schema env.schema.json --env-file .env.production
+
+# Skip dotenv loading and validate only process.env
+npx env-typed-checker check --schema env.schema.json --no-dotenv
+```
+
+### `generate` — generate or update `.env`
+
+Generate values from schema (writes missing keys; does not overwrite existing values).
+
+```bash
+npx env-typed-checker generate --schema env.schema.json
+```
+### By default:
+
+- output file: .env
+- mode: update
+
+### Flags
+
+```bash
+# Custom output file
+npx env-typed-checker generate --schema env.schema.json --out .env.example
+
+# Create mode: refuse to overwrite an existing file
+npx env-typed-checker generate --schema env.schema.json --out .env --mode=create
+
+# Update mode: append only missing keys (safe)
+npx env-typed-checker generate --schema env.schema.json --out .env --mode=update
+
+# Do not write defaults (leave blank values)
+npx env-typed-checker generate --schema env.schema.json --no-defaults
+
+# Add inline type comments (useful for .env.example)
+npx env-typed-checker generate --schema env.schema.json --comment-types
+```
+
+### 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 specific env file in CI:
+
+```yml
+- name: Validate env
+  run: npx env-typed-checker check --schema env.schema.json --env-file .env.ci
+```
+
+## 🛠 Development
 Clone the repo and install:
 ```bash
 npm install
+npm test
 ```
-### Available Scripts
+### Common scripts:
 ```bash
 npm run build      # build package
 npm run test       # run tests
 npm run typecheck  # TypeScript check
 npm run dev        # watch build
 ```
+
 ### 🤝 Contributing
-Contributions are welcome!
-
-* 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
+PRs are welcome!
+
+* Improve docs / examples
+* Add more schema features
+* Improve CLI output formatting
+* Add integrations / templates
+
 
 # 📝 License
 MIT
@@ -141,13 +301,5 @@ MIT
 ---
 
 ```yml
-If you want, I can help you add:
-
-- badges (npm version, CI, coverage)  
-- a small logo  
-- example project section  
-
-Just tell me 👍
-```
-
-
+::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-L5DK6LRX.mjs

@@ -0,0 +1,262 @@
+// src/core/envDoctor.ts
+import * as dotenv from "dotenv";
+
+// src/errors/EnvDoctorError.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/validators/primitives.ts
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+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}"`);
+      }
+    }
+    case "email": {
+      const s = raw.trim();
+      if (!EMAIL_RE.test(s)) {
+        throw new Error(`expected email, got "${raw}"`);
+      }
+      return s;
+    }
+    default: {
+      throw new Error(`unsupported primitive type: ${String(type)}`);
+    }
+  }
+}
+function hasOwn(obj, key) {
+  return Object.prototype.hasOwnProperty.call(obj, key);
+}
+function coerceDefault(kind, def) {
+  if (def === void 0) return void 0;
+  switch (kind) {
+    case "string": {
+      if (typeof def !== "string")
+        throw new Error(`default for string must be a string`);
+      return def;
+    }
+    case "number": {
+      if (typeof def === "number") {
+        if (!Number.isFinite(def))
+          throw new Error(`default for number must be finite`);
+        return def;
+      }
+      if (typeof def === "string") return parseByType("number", def);
+      throw new Error(`default for number must be number or string`);
+    }
+    case "boolean": {
+      if (typeof def === "boolean") return def;
+      if (typeof def === "string") return parseByType("boolean", def);
+      throw new Error(`default for boolean must be boolean or string`);
+    }
+    case "json": {
+      return def;
+    }
+    case "url": {
+      if (typeof def !== "string")
+        throw new Error(`default for url must be a string`);
+      return parseByType("url", def);
+    }
+    case "email": {
+      if (typeof def !== "string")
+        throw new Error(`default for email must be a string`);
+      return parseByType("email", def);
+    }
+    /* c8 ignore next */
+    default: {
+      throw new Error(`unsupported default kind: ${String(kind)}`);
+    }
+  }
+}
+function normalizeSpec(schemaValue) {
+  if (typeof schemaValue === "string") {
+    const optional = schemaValue.endsWith("?");
+    const base = optional ? schemaValue.slice(0, -1) : schemaValue;
+    const allowed = [
+      "string",
+      "number",
+      "boolean",
+      "json",
+      "url",
+      "email"
+    ];
+    if (!allowed.includes(base)) {
+      throw new Error(
+        `Unsupported type "${schemaValue}". Supported: string, number, boolean, json, url, email (optional with ?)`
+      );
+    }
+    return { kind: base, optional };
+  }
+  if (!schemaValue || typeof schemaValue !== "object" || Array.isArray(schemaValue)) {
+    throw new Error("Schema value must be a string or object spec.");
+  }
+  const t = schemaValue.type;
+  const primitiveAllowed = [
+    "string",
+    "number",
+    "boolean",
+    "json",
+    "url",
+    "email"
+  ];
+  if (primitiveAllowed.includes(t)) {
+    const optional = !!schemaValue.optional;
+    const defaultValue = hasOwn(schemaValue, "default") ? coerceDefault(t, schemaValue.default) : void 0;
+    return { kind: t, optional, defaultValue };
+  }
+  if (t === "enum") {
+    const values = schemaValue.values;
+    if (!Array.isArray(values) || values.length === 0 || !values.every((v) => typeof v === "string")) {
+      throw new Error(`enum spec requires "values": string[] (non-empty)`);
+    }
+    const optional = !!schemaValue.optional;
+    let defaultValue = void 0;
+    if (hasOwn(schemaValue, "default")) {
+      const def = schemaValue.default;
+      if (typeof def !== "string") {
+        throw new Error(`default for enum must be a string`);
+      }
+      if (!values.includes(def)) {
+        throw new Error(
+          `default "${def}" must be one of [${values.join(", ")}]`
+        );
+      }
+      defaultValue = def;
+    }
+    return { kind: "enum", optional, values, defaultValue };
+  }
+  if (t === "regex") {
+    const pattern = schemaValue.pattern;
+    const flags = schemaValue.flags;
+    if (typeof pattern !== "string" || pattern.length === 0) {
+      throw new Error(`regex spec requires "pattern": string`);
+    }
+    if (flags !== void 0 && typeof flags !== "string") {
+      throw new Error(`regex spec "flags" must be a string if provided`);
+    }
+    let re;
+    try {
+      re = new RegExp(pattern, flags);
+    } catch (e) {
+      throw new Error(`invalid regex: ${String(e)}`);
+    }
+    const display = `/${pattern}/${flags ?? ""}`;
+    const optional = !!schemaValue.optional;
+    let defaultValue = void 0;
+    if (hasOwn(schemaValue, "default")) {
+      const def = schemaValue.default;
+      if (typeof def !== "string") {
+        throw new Error(`default for regex must be a string`);
+      }
+      if (!re.test(def)) {
+        throw new Error(`default "${def}" does not match ${display}`);
+      }
+      defaultValue = def;
+    }
+    return { kind: "regex", optional, re, display, defaultValue };
+  }
+  throw new Error(
+    `Unsupported object spec type "${String(t)}". Supported: primitives (string/number/boolean/json/url/email), enum, regex`
+  );
+}
+
+// src/core/runner.ts
+function validateAndParse(schema, env) {
+  const issues = [];
+  const out = {};
+  for (const [key, schemaValue] of Object.entries(schema)) {
+    let spec;
+    try {
+      spec = normalizeSpec(schemaValue);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      issues.push({ key, kind: "invalid", message: msg });
+      continue;
+    }
+    const raw = env[key];
+    if (raw === void 0 || raw === "") {
+      if (spec.defaultValue !== void 0) {
+        out[key] = spec.defaultValue;
+      } else if (spec.optional) {
+        out[key] = void 0;
+      } else {
+        issues.push({
+          key,
+          kind: "missing",
+          message: "missing required environment variable"
+        });
+      }
+      continue;
+    }
+    try {
+      if (spec.kind === "enum") {
+        if (!spec.values.includes(raw)) {
+          throw new Error(
+            `expected one of [${spec.values.join(", ")}], got "${raw}"`
+          );
+        }
+        out[key] = raw;
+      } else if (spec.kind === "regex") {
+        if (!spec.re.test(raw)) {
+          throw new Error(`does not match ${spec.display}`);
+        }
+        out[key] = raw;
+      } else {
+        out[key] = parseByType(spec.kind, raw);
+      }
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      issues.push({ key, kind: "invalid", message: msg });
+    }
+  }
+  if (issues.length > 0) throw new EnvDoctorError(issues);
+  return out;
+}
+
+// src/core/envDoctor.ts
+function envDoctor(schema, options = {}) {
+  const { loadDotEnv = true, env = process.env } = options;
+  if (loadDotEnv) dotenv.config();
+  return validateAndParse(schema, env);
+}
+
+export {
+  EnvDoctorError,
+  normalizeSpec,
+  envDoctor
+};
+//# sourceMappingURL=chunk-L5DK6LRX.mjs.map

package/dist/chunk-L5DK6LRX.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/envDoctor.ts","../src/errors/EnvDoctorError.ts","../src/validators/primitives.ts","../src/core/runner.ts"],"sourcesContent":["import * as dotenv from \"dotenv\";\nimport { validateAndParse } from \"./runner\";\nimport type { EnvDoctorOptions, EnvDoctorResult, EnvDoctorSchema } from \"../types\";\n\nexport type { EnvDoctorOptions, EnvDoctorSchema } from \"../types\";\nexport { EnvDoctorError } from \"../errors/EnvDoctorError\";\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, EnvSchemaValue } from \"../types\";\n\nconst EMAIL_RE = /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/;\n\nexport function parseByType(type: EnvBaseType, raw: string): unknown {\n  switch (type) {\n    case \"string\":\n      return raw;\n\n    case \"number\": {\n      const n = Number(raw.trim());\n      if (!Number.isFinite(n)) throw new Error(`expected number, got \"${raw}\"`);\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        new URL(raw);\n        return raw;\n      } catch {\n        throw new Error(`expected url, got \"${raw}\"`);\n      }\n    }\n\n    case \"email\": {\n      const s = raw.trim();\n      if (!EMAIL_RE.test(s)) {\n        throw new Error(`expected email, got \"${raw}\"`);\n      }\n      return s;\n    }\n\n    default: {\n      throw new Error(`unsupported primitive type: ${String(type)}`);\n    }\n  }\n}\n\nfunction hasOwn(obj: unknown, key: string): boolean {\n  return Object.prototype.hasOwnProperty.call(obj, key);\n}\n\n/**\n * Type-check + normalize a default value into the right runtime type.\n * - Allows string defaults for number/boolean (parsed)\n * - Validates url/email defaults\n * - json defaults can be any value\n */\nfunction coerceDefault(kind: EnvBaseType, def: unknown): unknown {\n  if (def === undefined) return undefined;\n\n  switch (kind) {\n    case \"string\": {\n      if (typeof def !== \"string\")\n        throw new Error(`default for string must be a string`);\n      return def;\n    }\n\n    case \"number\": {\n      if (typeof def === \"number\") {\n        if (!Number.isFinite(def))\n          throw new Error(`default for number must be finite`);\n        return def;\n      }\n      if (typeof def === \"string\") return parseByType(\"number\", def);\n      throw new Error(`default for number must be number or string`);\n    }\n\n    case \"boolean\": {\n      if (typeof def === \"boolean\") return def;\n      if (typeof def === \"string\") return parseByType(\"boolean\", def);\n      throw new Error(`default for boolean must be boolean or string`);\n    }\n\n    case \"json\": {\n      // allow any JSON-ish value\n      return def;\n    }\n\n    case \"url\": {\n      if (typeof def !== \"string\")\n        throw new Error(`default for url must be a string`);\n      return parseByType(\"url\", def);\n    }\n\n    case \"email\": {\n      if (typeof def !== \"string\")\n        throw new Error(`default for email must be a string`);\n      return parseByType(\"email\", def);\n    }\n\n    /* c8 ignore next */\n    default: {\n      throw new Error(`unsupported default kind: ${String(kind)}`);\n    }\n  }\n}\n\n/** Normalized spec used by the runner */\nexport type NormalizedSpec =\n  | { kind: EnvBaseType; optional: boolean; defaultValue?: unknown }\n  | {\n      kind: \"enum\";\n      optional: boolean;\n      values: readonly string[];\n      defaultValue?: string;\n    }\n  | {\n      kind: \"regex\";\n      optional: boolean;\n      re: RegExp;\n      display: string;\n      defaultValue?: string;\n    };\n\nexport function normalizeSpec(schemaValue: EnvSchemaValue): NormalizedSpec {\n  // --------------------\n  // String style: \"number?\" etc.\n  // --------------------\n  if (typeof schemaValue === \"string\") {\n    const optional = schemaValue.endsWith(\"?\");\n    const base = optional ? schemaValue.slice(0, -1) : schemaValue;\n\n    const allowed: readonly EnvBaseType[] = [\n      \"string\",\n      \"number\",\n      \"boolean\",\n      \"json\",\n      \"url\",\n      \"email\",\n    ];\n\n    if (!allowed.includes(base as EnvBaseType)) {\n      throw new Error(\n        `Unsupported type \"${schemaValue}\". Supported: string, number, boolean, json, url, email (optional with ?)`,\n      );\n    }\n\n    return { kind: base as EnvBaseType, optional };\n  }\n\n  // --------------------\n  // Object style\n  // --------------------\n  if (\n    !schemaValue ||\n    typeof schemaValue !== \"object\" ||\n    Array.isArray(schemaValue)\n  ) {\n    throw new Error(\"Schema value must be a string or object spec.\");\n  }\n\n  const t = (schemaValue as any).type;\n\n  // --------------------\n  // Primitive object spec: { type: \"number\", optional?: true, default?: ... }\n  // --------------------\n  const primitiveAllowed: readonly EnvBaseType[] = [\n    \"string\",\n    \"number\",\n    \"boolean\",\n    \"json\",\n    \"url\",\n    \"email\",\n  ];\n\n  if (primitiveAllowed.includes(t)) {\n    const optional = !!(schemaValue as any).optional;\n    const defaultValue = hasOwn(schemaValue, \"default\")\n      ? coerceDefault(t as EnvBaseType, (schemaValue as any).default)\n      : undefined;\n\n    return { kind: t as EnvBaseType, optional, defaultValue };\n  }\n\n  // --------------------\n  // Enum: { type: \"enum\", values: [...], optional?: true, default?: \"dev\" }\n  // --------------------\n  if (t === \"enum\") {\n    const values = (schemaValue as any).values;\n    if (\n      !Array.isArray(values) ||\n      values.length === 0 ||\n      !values.every((v: any) => typeof v === \"string\")\n    ) {\n      throw new Error(`enum spec requires \"values\": string[] (non-empty)`);\n    }\n\n    const optional = !!(schemaValue as any).optional;\n\n    let defaultValue: string | undefined = undefined;\n    if (hasOwn(schemaValue, \"default\")) {\n      const def = (schemaValue as any).default;\n      if (typeof def !== \"string\") {\n        throw new Error(`default for enum must be a string`);\n      }\n      if (!values.includes(def)) {\n        throw new Error(\n          `default \"${def}\" must be one of [${values.join(\", \")}]`,\n        );\n      }\n      defaultValue = def;\n    }\n\n    return { kind: \"enum\", optional, values, defaultValue };\n  }\n\n  // --------------------\n  // Regex: { type: \"regex\", pattern: \"...\", flags?: \"...\", optional?: true, default?: \"abc\" }\n  // --------------------\n  if (t === \"regex\") {\n    const pattern = (schemaValue as any).pattern;\n    const flags = (schemaValue as any).flags;\n\n    if (typeof pattern !== \"string\" || pattern.length === 0) {\n      throw new Error(`regex spec requires \"pattern\": string`);\n    }\n    if (flags !== undefined && typeof flags !== \"string\") {\n      throw new Error(`regex spec \"flags\" must be a string if provided`);\n    }\n\n    let re: RegExp;\n    try {\n      re = new RegExp(pattern, flags);\n    } catch (e) {\n      throw new Error(`invalid regex: ${String(e)}`);\n    }\n\n    const display = `/${pattern}/${flags ?? \"\"}`;\n    const optional = !!(schemaValue as any).optional;\n\n    let defaultValue: string | undefined = undefined;\n    if (hasOwn(schemaValue, \"default\")) {\n      const def = (schemaValue as any).default;\n      if (typeof def !== \"string\") {\n        throw new Error(`default for regex must be a string`);\n      }\n      if (!re.test(def)) {\n        throw new Error(`default \"${def}\" does not match ${display}`);\n      }\n      defaultValue = def;\n    }\n\n    return { kind: \"regex\", optional, re, display, defaultValue };\n  }\n\n  throw new Error(\n    `Unsupported object spec type \"${String(t)}\". Supported: primitives (string/number/boolean/json/url/email), enum, regex`,\n  );\n}\n","import { EnvDoctorError, type EnvDoctorIssue } from \"../errors/EnvDoctorError\";\nimport { normalizeSpec, parseByType } from \"../validators/primitives\";\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 spec: ReturnType<typeof normalizeSpec>;\n\n    try {\n      spec = normalizeSpec(schemaValue);\n    } catch (e) {\n      const msg = e instanceof Error ? e.message : String(e);\n      issues.push({ key, kind: \"invalid\", message: msg });\n      continue;\n    }\n\n    const raw = env[key];\n\n    // treat undefined or empty string as \"missing\"\n    if (raw === undefined || raw === \"\") {\n      if (spec.defaultValue !== undefined) {\n        out[key] = spec.defaultValue;\n      } else if (spec.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      if (spec.kind === \"enum\") {\n        if (!spec.values.includes(raw)) {\n          throw new Error(\n            `expected one of [${spec.values.join(\", \")}], got \"${raw}\"`,\n          );\n        }\n        out[key] = raw;\n      } else if (spec.kind === \"regex\") {\n        if (!spec.re.test(raw)) {\n          throw new Error(`does not match ${spec.display}`);\n        }\n        out[key] = raw;\n      } else {\n        // primitives: string/number/boolean/json/url/email\n        out[key] = parseByType(spec.kind, raw);\n      }\n    } catch (e) {\n      const msg = e instanceof Error ? e.message : String(e);\n      issues.push({ key, kind: \"invalid\", message: msg });\n    }\n  }\n\n  if (issues.length > 0) throw new EnvDoctorError(issues);\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;;;ACZA,IAAM,WAAW;AAEV,SAAS,YAAY,MAAmB,KAAsB;AACnE,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO;AAAA,IAET,KAAK,UAAU;AACb,YAAM,IAAI,OAAO,IAAI,KAAK,CAAC;AAC3B,UAAI,CAAC,OAAO,SAAS,CAAC,EAAG,OAAM,IAAI,MAAM,yBAAyB,GAAG,GAAG;AACxE,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;AACF,YAAI,IAAI,GAAG;AACX,eAAO;AAAA,MACT,QAAQ;AACN,cAAM,IAAI,MAAM,sBAAsB,GAAG,GAAG;AAAA,MAC9C;AAAA,IACF;AAAA,IAEA,KAAK,SAAS;AACZ,YAAM,IAAI,IAAI,KAAK;AACnB,UAAI,CAAC,SAAS,KAAK,CAAC,GAAG;AACrB,cAAM,IAAI,MAAM,wBAAwB,GAAG,GAAG;AAAA,MAChD;AACA,aAAO;AAAA,IACT;AAAA,IAEA,SAAS;AACP,YAAM,IAAI,MAAM,+BAA+B,OAAO,IAAI,CAAC,EAAE;AAAA,IAC/D;AAAA,EACF;AACF;AAEA,SAAS,OAAO,KAAc,KAAsB;AAClD,SAAO,OAAO,UAAU,eAAe,KAAK,KAAK,GAAG;AACtD;AAQA,SAAS,cAAc,MAAmB,KAAuB;AAC/D,MAAI,QAAQ,OAAW,QAAO;AAE9B,UAAQ,MAAM;AAAA,IACZ,KAAK,UAAU;AACb,UAAI,OAAO,QAAQ;AACjB,cAAM,IAAI,MAAM,qCAAqC;AACvD,aAAO;AAAA,IACT;AAAA,IAEA,KAAK,UAAU;AACb,UAAI,OAAO,QAAQ,UAAU;AAC3B,YAAI,CAAC,OAAO,SAAS,GAAG;AACtB,gBAAM,IAAI,MAAM,mCAAmC;AACrD,eAAO;AAAA,MACT;AACA,UAAI,OAAO,QAAQ,SAAU,QAAO,YAAY,UAAU,GAAG;AAC7D,YAAM,IAAI,MAAM,6CAA6C;AAAA,IAC/D;AAAA,IAEA,KAAK,WAAW;AACd,UAAI,OAAO,QAAQ,UAAW,QAAO;AACrC,UAAI,OAAO,QAAQ,SAAU,QAAO,YAAY,WAAW,GAAG;AAC9D,YAAM,IAAI,MAAM,+CAA+C;AAAA,IACjE;AAAA,IAEA,KAAK,QAAQ;AAEX,aAAO;AAAA,IACT;AAAA,IAEA,KAAK,OAAO;AACV,UAAI,OAAO,QAAQ;AACjB,cAAM,IAAI,MAAM,kCAAkC;AACpD,aAAO,YAAY,OAAO,GAAG;AAAA,IAC/B;AAAA,IAEA,KAAK,SAAS;AACZ,UAAI,OAAO,QAAQ;AACjB,cAAM,IAAI,MAAM,oCAAoC;AACtD,aAAO,YAAY,SAAS,GAAG;AAAA,IACjC;AAAA;AAAA,IAGA,SAAS;AACP,YAAM,IAAI,MAAM,6BAA6B,OAAO,IAAI,CAAC,EAAE;AAAA,IAC7D;AAAA,EACF;AACF;AAmBO,SAAS,cAAc,aAA6C;AAIzE,MAAI,OAAO,gBAAgB,UAAU;AACnC,UAAM,WAAW,YAAY,SAAS,GAAG;AACzC,UAAM,OAAO,WAAW,YAAY,MAAM,GAAG,EAAE,IAAI;AAEnD,UAAM,UAAkC;AAAA,MACtC;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAEA,QAAI,CAAC,QAAQ,SAAS,IAAmB,GAAG;AAC1C,YAAM,IAAI;AAAA,QACR,qBAAqB,WAAW;AAAA,MAClC;AAAA,IACF;AAEA,WAAO,EAAE,MAAM,MAAqB,SAAS;AAAA,EAC/C;AAKA,MACE,CAAC,eACD,OAAO,gBAAgB,YACvB,MAAM,QAAQ,WAAW,GACzB;AACA,UAAM,IAAI,MAAM,+CAA+C;AAAA,EACjE;AAEA,QAAM,IAAK,YAAoB;AAK/B,QAAM,mBAA2C;AAAA,IAC/C;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AAEA,MAAI,iBAAiB,SAAS,CAAC,GAAG;AAChC,UAAM,WAAW,CAAC,CAAE,YAAoB;AACxC,UAAM,eAAe,OAAO,aAAa,SAAS,IAC9C,cAAc,GAAmB,YAAoB,OAAO,IAC5D;AAEJ,WAAO,EAAE,MAAM,GAAkB,UAAU,aAAa;AAAA,EAC1D;AAKA,MAAI,MAAM,QAAQ;AAChB,UAAM,SAAU,YAAoB;AACpC,QACE,CAAC,MAAM,QAAQ,MAAM,KACrB,OAAO,WAAW,KAClB,CAAC,OAAO,MAAM,CAAC,MAAW,OAAO,MAAM,QAAQ,GAC/C;AACA,YAAM,IAAI,MAAM,mDAAmD;AAAA,IACrE;AAEA,UAAM,WAAW,CAAC,CAAE,YAAoB;AAExC,QAAI,eAAmC;AACvC,QAAI,OAAO,aAAa,SAAS,GAAG;AAClC,YAAM,MAAO,YAAoB;AACjC,UAAI,OAAO,QAAQ,UAAU;AAC3B,cAAM,IAAI,MAAM,mCAAmC;AAAA,MACrD;AACA,UAAI,CAAC,OAAO,SAAS,GAAG,GAAG;AACzB,cAAM,IAAI;AAAA,UACR,YAAY,GAAG,qBAAqB,OAAO,KAAK,IAAI,CAAC;AAAA,QACvD;AAAA,MACF;AACA,qBAAe;AAAA,IACjB;AAEA,WAAO,EAAE,MAAM,QAAQ,UAAU,QAAQ,aAAa;AAAA,EACxD;AAKA,MAAI,MAAM,SAAS;AACjB,UAAM,UAAW,YAAoB;AACrC,UAAM,QAAS,YAAoB;AAEnC,QAAI,OAAO,YAAY,YAAY,QAAQ,WAAW,GAAG;AACvD,YAAM,IAAI,MAAM,uCAAuC;AAAA,IACzD;AACA,QAAI,UAAU,UAAa,OAAO,UAAU,UAAU;AACpD,YAAM,IAAI,MAAM,iDAAiD;AAAA,IACnE;AAEA,QAAI;AACJ,QAAI;AACF,WAAK,IAAI,OAAO,SAAS,KAAK;AAAA,IAChC,SAAS,GAAG;AACV,YAAM,IAAI,MAAM,kBAAkB,OAAO,CAAC,CAAC,EAAE;AAAA,IAC/C;AAEA,UAAM,UAAU,IAAI,OAAO,IAAI,SAAS,EAAE;AAC1C,UAAM,WAAW,CAAC,CAAE,YAAoB;AAExC,QAAI,eAAmC;AACvC,QAAI,OAAO,aAAa,SAAS,GAAG;AAClC,YAAM,MAAO,YAAoB;AACjC,UAAI,OAAO,QAAQ,UAAU;AAC3B,cAAM,IAAI,MAAM,oCAAoC;AAAA,MACtD;AACA,UAAI,CAAC,GAAG,KAAK,GAAG,GAAG;AACjB,cAAM,IAAI,MAAM,YAAY,GAAG,oBAAoB,OAAO,EAAE;AAAA,MAC9D;AACA,qBAAe;AAAA,IACjB;AAEA,WAAO,EAAE,MAAM,SAAS,UAAU,IAAI,SAAS,aAAa;AAAA,EAC9D;AAEA,QAAM,IAAI;AAAA,IACR,iCAAiC,OAAO,CAAC,CAAC;AAAA,EAC5C;AACF;;;ACtQO,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;AAEJ,QAAI;AACF,aAAO,cAAc,WAAW;AAAA,IAClC,SAAS,GAAG;AACV,YAAM,MAAM,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC;AACrD,aAAO,KAAK,EAAE,KAAK,MAAM,WAAW,SAAS,IAAI,CAAC;AAClD;AAAA,IACF;AAEA,UAAM,MAAM,IAAI,GAAG;AAGnB,QAAI,QAAQ,UAAa,QAAQ,IAAI;AACnC,UAAI,KAAK,iBAAiB,QAAW;AACnC,YAAI,GAAG,IAAI,KAAK;AAAA,MAClB,WAAW,KAAK,UAAU;AACxB,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,KAAK,SAAS,QAAQ;AACxB,YAAI,CAAC,KAAK,OAAO,SAAS,GAAG,GAAG;AAC9B,gBAAM,IAAI;AAAA,YACR,oBAAoB,KAAK,OAAO,KAAK,IAAI,CAAC,WAAW,GAAG;AAAA,UAC1D;AAAA,QACF;AACA,YAAI,GAAG,IAAI;AAAA,MACb,WAAW,KAAK,SAAS,SAAS;AAChC,YAAI,CAAC,KAAK,GAAG,KAAK,GAAG,GAAG;AACtB,gBAAM,IAAI,MAAM,kBAAkB,KAAK,OAAO,EAAE;AAAA,QAClD;AACA,YAAI,GAAG,IAAI;AAAA,MACb,OAAO;AAEL,YAAI,GAAG,IAAI,YAAY,KAAK,MAAM,GAAG;AAAA,MACvC;AAAA,IACF,SAAS,GAAG;AACV,YAAM,MAAM,aAAa,QAAQ,EAAE,UAAU,OAAO,CAAC;AACrD,aAAO,KAAK,EAAE,KAAK,MAAM,WAAW,SAAS,IAAI,CAAC;AAAA,IACpD;AAAA,EACF;AAEA,MAAI,OAAO,SAAS,EAAG,OAAM,IAAI,eAAe,MAAM;AAEtD,SAAO;AACT;;;AH3DO,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/index.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 };