env-typed-checker 0.2.1 → 0.2.4

package/README.md

@@ -1,305 +1,334 @@
-# env-typed-checker 
+# env-typed-checker
 
-Validate and parse environment variables using a tiny schema — with both a **TypeScript/Node API** and a **CLI**.
+Validate and parse environment variables with a small schema, using either:
 
-It helps your app fail fast when configuration is wrong:
+- TypeScript/Node API (`envDoctor`)
+- CLI (`env-typed-checker check` and `generate`)
 
-- ❌ 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
+This package helps your app fail fast when config is wrong.
+This README is the complete guide for installing, configuring, and using the package.
 
+## Why use this
 
----
+- Catch missing env vars early
+- Parse types (`number`, `boolean`, `json`) safely
+- Validate `url`, `email`, `enum`, and `regex` values
+- Keep one schema for runtime + CI checks
+- Generate `.env` / `.env.example` from schema
+- Redact secret values in CLI validation output
 
-## ✨ Features
-
-- 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)
-
----
-
-## 📦 Install
+## Install
 
 ```bash
 npm install env-typed-checker
 ```
 
-Or run via npx:
+Or run directly:
 
 ```bash
 npx env-typed-checker --help
 ```
 
-## 🚀 Quick Start (Code)
+Requirements:
 
-```ts
-import { envDoctor } from "env-typed-checker";
+- Node.js `>=18`
 
-export const config = envDoctor({
-  PORT: "number",
-  DB_URL: "url",
-  ADMIN_EMAIL: "email",
-  DEBUG: "boolean?",
-});
+## Quick start (recommended): one schema for CLI + code
 
-```
+If you are new to this package, start with this pattern.
 
-### What you get
-
-* PORT → number
-
-* DB_URL → string (validated as URL)
-
-* ADMIN_EMAIL → string (validated as email)
-
-* DEBUG → boolean | undefined (optional)
+### 1) Create `env.schema.json`
 
+```json
+{
+  "PORT": { "type": "number", "default": 3000, "description": "HTTP port", "example": "8080" },
+  "DB_URL": { "type": "url", "description": "Primary database URL", "example": "postgres://user:pass@localhost:5432/app", "secret": true },
+  "ADMIN_EMAIL": { "type": "email", "description": "Ops contact email", "example": "ops@example.com" },
+  "DEBUG": "boolean?",
+  "NODE_ENV": { "type": "enum", "values": ["dev", "prod"], "default": "dev" },
+  "SLUG": { "type": "regex", "pattern": "^[a-z0-9-]+$", "flags": "i" },
+  "FEATURE_FLAGS": { "type": "json", "default": { "beta": false } }
+}
+```
 
-### 🧩 Supported Types
-| Type | Description |
-| :--- | :--- |
-| **string** | Any string value |
-| **number** | A finite number (automatically parsed from string) |
-| **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 |
+### 2) Reuse the same schema in app code
 
+ESM (NodeNext / `"type": "module"`):
 
-### Optional Values
-Add ? to make a variable optional:
 ```ts
-envDoctor({ DEBUG: "boolean?" });
-```
+// src/config.ts
+import { envDoctor, type EnvDoctorSchema } from "env-typed-checker";
+import schema from "../env.schema.json" assert { type: "json" };
 
-Or use object-style:
-
-```ts
-envDoctor({
-  DEBUG: { type: "boolean", optional: true },
+export const config = envDoctor(schema as EnvDoctorSchema, {
+  loadDotEnv: true,
 });
 ```
-Missing optional vars become `undefined` unless you provide a default.
 
-### 🎯 Defaults
-Defaults can be provided in object-style specs.
+CommonJS (or TS compiling to CJS):
 
 ```ts
-import { envDoctor } from "env-typed-checker";
+// src/config.ts
+import { envDoctor, type EnvDoctorSchema } 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" },
-});
-```
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const schema = require("../env.schema.json") as EnvDoctorSchema;
 
-### Notes:
+export const config = envDoctor(schema, { loadDotEnv: true });
+```
 
-- `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
+TypeScript JSON import note:
 
-### ✅ Enum and Regex
+```json
+{
+  "compilerOptions": {
+    "resolveJsonModule": true,
+    "esModuleInterop": true
+  }
+}
+```
 
-### Enum
+### 3) Validate env via CLI
 
-```ts
-const config = envDoctor({
-  NODE_ENV: { type: "enum", values: ["dev", "prod"] },
-});
+```bash
+npx env-typed-checker check --schema env.schema.json
 ```
 
-### Regex
+### 4) Generate `.env.example` from the same schema
 
-```ts
-const config = envDoctor({
-  SLUG: { type: "regex", pattern: "^[a-z0-9-]+$", flags: "i" },
-});
+```bash
+npx env-typed-checker generate --schema env.schema.json --out .env.example --comment-docs --example-values
 ```
 
-### ⚙️ Options
+Example output:
 
-```ts
-envDoctor(schema, {
-  loadDotEnv: true,   // default: true (loads .env)
-  env: process.env    // default: process.env (override for tests)
-});
+```env
+# HTTP port
+# example: 8080
+PORT=8080
+
+# Primary database URL
+# example: postgres://user:pass@localhost:5432/app
+DB_URL=postgres://user:pass@localhost:5432/app
 ```
 
+### 5) Use in CI (GitHub Actions annotations)
 
-### 🧪 Testing with custom env
+```yml
+- name: Validate env
+  run: npx env-typed-checker check --schema env.schema.json --format github
+```
+
+## API quick reference
 
 ```ts
 import { envDoctor } from "env-typed-checker";
 
-const cfg = envDoctor(
-  { PORT: "number" },
-  { loadDotEnv: false, env: { PORT: "3000" } }
+const config = envDoctor(
+  {
+    PORT: "number",
+    DEBUG: "boolean?",
+    NODE_ENV: { type: "enum", values: ["dev", "prod"] },
+  },
+  {
+    loadDotEnv: true,
+    env: process.env,
+  },
 );
-
-console.log(cfg.PORT); // 3000
 ```
 
-### ❌ Error Example
+### Parsed output types
 
-Given a `.env` like:
+| Schema type | Parsed result |
+| :--- | :--- |
+| `string` | `string` |
+| `number` | `number` |
+| `boolean` | `boolean` |
+| `json` | `unknown` |
+| `url` | `string` |
+| `email` | `string` |
+| `enum` | one of listed values |
+| `regex` | `string` |
 
-```env
-PORT=abc
-DB_URL=not-a-url
-NODE_ENV=staging
-```
+## Schema reference
 
-```ts
-import { envDoctor } from "env-typed-checker";
+### Primitive shorthand
 
-envDoctor({
-  PORT: "number",
-  DB_URL: "url"
-  NODE_ENV: { type: "enum", values: ["dev", "prod"] },
-});
+```json
+{
+  "PORT": "number",
+  "DEBUG": "boolean?",
+  "DB_URL": "url"
+}
 ```
 
-### Output:
+- Add `?` to mark optional keys.
+- Missing optional keys become `undefined` (unless default exists).
 
-```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]
+### Object syntax
+
+```json
+{
+  "PORT": { "type": "number", "default": 3000 },
+  "DEBUG": { "type": "boolean", "optional": true },
+  "NODE_ENV": { "type": "enum", "values": ["dev", "prod"] },
+  "SLUG": { "type": "regex", "pattern": "^[a-z0-9-]+$", "flags": "i" }
+}
 ```
-All errors are shown together so you can fix them in one go.
 
-# 🖥️ CLI
+### Defaults
 
-Validate your environment without writing code — perfect for CI pipelines.
+- `number`: number or numeric string
+- `boolean`: boolean or boolean-like string
+- `url` / `email`: valid strings
+- `json`: any JSON-like value
 
-## 1) Create a schema file
+### Metadata fields (object syntax only)
 
-`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" }
+  "API_KEY": {
+    "type": "string",
+    "description": "External service token",
+    "example": "sk_test_123",
+    "secret": true
+  }
 }
 ```
 
-## 2) Run the check
+- `description?: string` used by `generate --comment-docs`
+- `example?: string` used in comments and optional generation values
+- `secret?: boolean` redacts invalid raw values in CLI `check`
 
-```bash
-npx env-typed-checker check --schema env.schema.json
+If you need metadata for a primitive shorthand key, wrap it in object syntax:
+
+```json
+{
+  "PORT": { "type": "number", "description": "HTTP port" }
+}
 ```
 
-Useful flags
+### Runtime behavior notes
 
-```bash
-# Use a specific env file (instead of .env)
-npx env-typed-checker check --schema env.schema.json --env-file .env.production
+- Empty strings (`""`) are treated as missing values.
+- Validation errors are aggregated and returned together.
+- CLI `check` merges `.env` values over current shell env when dotenv loading is enabled.
+
+## CLI reference
+
+### `check`
 
-# Skip dotenv loading and validate only process.env
-npx env-typed-checker check --schema env.schema.json --no-dotenv
+```bash
+env-typed-checker check --schema <file> [--env-file <file>] [--no-dotenv] [--format pretty|json|github]
 ```
 
-### `generate` — generate or update `.env`
+Flags:
 
-Generate values from schema (writes missing keys; does not overwrite existing values).
+- `--schema <file>` required schema file
+- `--env-file <file>` env file path (default `.env`)
+- `--no-dotenv` validate only current `process.env`
+- `--format pretty|json|github` output style (default `pretty`)
 
-```bash
-npx env-typed-checker generate --schema env.schema.json
+### `check` output formats
+
+`pretty` (default):
+
+```text
+ENV validation failed
+- PORT: expected number, got "abc"
 ```
-### By default:
 
-- output file: .env
-- mode: update
+`json`:
+
+```json
+{"error":"ENV validation failed","issues":[{"key":"PORT","kind":"invalid","message":"expected number, got \"abc\""}]}
+```
 
-### Flags
+`github` (for workflow annotations):
 
-```bash
-# Custom output file
-npx env-typed-checker generate --schema env.schema.json --out .env.example
+```text
+::error title=ENV validation::PORT: expected number, got "abc"
+```
 
-# Create mode: refuse to overwrite an existing file
-npx env-typed-checker generate --schema env.schema.json --out .env --mode=create
+When a key has `secret: true`, CLI output redacts raw invalid values:
 
-# Update mode: append only missing keys (safe)
-npx env-typed-checker generate --schema env.schema.json --out .env --mode=update
+```text
+SECRET_TOKEN: expected number, got "<redacted>"
+```
 
-# Do not write defaults (leave blank values)
-npx env-typed-checker generate --schema env.schema.json --no-defaults
+### `generate`
 
-# Add inline type comments (useful for .env.example)
-npx env-typed-checker generate --schema env.schema.json --comment-types
+```bash
+env-typed-checker generate --schema <file> [--out <file>] [--mode update|create] [--no-defaults] [--comment-types] [--comment-docs] [--example-values]
 ```
 
-### Exit codes
+Defaults:
+
+- output file: `.env`
+- mode: `update`
+- behavior: append only missing keys
+
+Flags:
 
-* `0` = OK
+- `--out <file>` custom output path
+- `--mode create` fail if file already exists
+- `--mode update` append missing keys only
+- `--no-defaults` write empty values instead of defaults
+- `--comment-types` add inline type comments
+- `--comment-docs` add `description` and `example` comments above keys
+- `--example-values` use schema `example` values as generated values
 
-* `1` = validation failed
+## Exit codes
 
-* `2` = CLI usage / unexpected error
+- `0` success
+- `1` validation failed
+- `2` CLI usage error or unexpected error
 
-## ✅ CI Example (GitHub Actions)
+## CI examples
 
-Add this to your workflow to fail the build if env is invalid:
+GitHub Actions with annotations:
 
 ```yml
 - name: Validate env
-  run: npx env-typed-checker check --schema env.schema.json
+  run: npx env-typed-checker check --schema env.schema.json --format github
 ```
-If you use a specific env file in CI:
+
+With custom env file:
 
 ```yml
 - name: Validate env
-  run: npx env-typed-checker check --schema env.schema.json --env-file .env.ci
+  run: npx env-typed-checker check --schema env.schema.json --env-file .env.ci --format github
 ```
 
-## 🛠 Development
-Clone the repo and install:
-```bash
-npm install
-npm test
-```
-### Common scripts:
-```bash
-npm run build      # build package
-npm run test       # run tests
-npm run typecheck  # TypeScript check
-npm run dev        # watch build
-```
+## Testing with custom env in code
 
-### 🤝 Contributing
-PRs are welcome!
+```ts
+import { envDoctor } from "env-typed-checker";
 
-* Improve docs / examples
-* Add more schema features
-* Improve CLI output formatting
-* Add integrations / templates
+const cfg = envDoctor(
+  { PORT: "number" },
+  { loadDotEnv: false, env: { PORT: "3000" } },
+);
 
+console.log(cfg.PORT); // 3000
+```
 
-# 📝 License
-MIT
+## Common mistakes
 
+- Missing `--schema` in CLI commands
+- Using shorthand string syntax when you need metadata (`description`, `example`, `secret`)
+- Forgetting `resolveJsonModule` when importing `env.schema.json` in TypeScript
 
----
+## Development
 
-```yml
-::contentReference[oaicite:0]{index=0}
-```
+```bash
+npm install
+npm run lint
+npm run typecheck
+npm run test:coverage
+npm run build
+```
+
+## License
+
+MIT

package/bin/env-typed-checker.cjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
+"use strict";
 
-const { runCli } = require("../dist/cli.js");
+const { runCli } = require("../dist/cli/index.js");
 
 const code = runCli(process.argv.slice(2), console);
-process.exitCode = code;
+process.exitCode = typeof code === "number" ? code : 1;

package/dist/{chunk-L5DK6LRX.mjs → chunk-CCJEPMPN.mjs}

@@ -102,6 +102,33 @@ function coerceDefault(kind, def) {
     }
   }
 }
+function normalizeMeta(schemaValue) {
+  let description = void 0;
+  if (hasOwn(schemaValue, "description")) {
+    const d = schemaValue.description;
+    if (d !== void 0 && typeof d !== "string") {
+      throw new Error(`"description" must be a string if provided`);
+    }
+    description = d;
+  }
+  let example = void 0;
+  if (hasOwn(schemaValue, "example")) {
+    const ex = schemaValue.example;
+    if (ex !== void 0 && typeof ex !== "string") {
+      throw new Error(`"example" must be a string if provided`);
+    }
+    example = ex;
+  }
+  let secret = false;
+  if (hasOwn(schemaValue, "secret")) {
+    const s = schemaValue.secret;
+    if (s !== void 0 && typeof s !== "boolean") {
+      throw new Error(`"secret" must be a boolean if provided`);
+    }
+    secret = s === true;
+  }
+  return { description, example, secret };
+}
 function normalizeSpec(schemaValue) {
   if (typeof schemaValue === "string") {
     const optional = schemaValue.endsWith("?");
@@ -119,12 +146,17 @@ function normalizeSpec(schemaValue) {
         `Unsupported type "${schemaValue}". Supported: string, number, boolean, json, url, email (optional with ?)`
       );
     }
-    return { kind: base, optional };
+    return {
+      kind: base,
+      optional,
+      secret: false
+    };
   }
   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 meta = normalizeMeta(schemaValue);
   const primitiveAllowed = [
     "string",
     "number",
@@ -136,7 +168,12 @@ function normalizeSpec(schemaValue) {
   if (primitiveAllowed.includes(t)) {
     const optional = !!schemaValue.optional;
     const defaultValue = hasOwn(schemaValue, "default") ? coerceDefault(t, schemaValue.default) : void 0;
-    return { kind: t, optional, defaultValue };
+    return {
+      kind: t,
+      optional,
+      defaultValue,
+      ...meta
+    };
   }
   if (t === "enum") {
     const values = schemaValue.values;
@@ -157,7 +194,13 @@ function normalizeSpec(schemaValue) {
       }
       defaultValue = def;
     }
-    return { kind: "enum", optional, values, defaultValue };
+    return {
+      kind: "enum",
+      optional,
+      values,
+      defaultValue,
+      ...meta
+    };
   }
   if (t === "regex") {
     const pattern = schemaValue.pattern;
@@ -187,7 +230,14 @@ function normalizeSpec(schemaValue) {
       }
       defaultValue = def;
     }
-    return { kind: "regex", optional, re, display, defaultValue };
+    return {
+      kind: "regex",
+      optional,
+      re,
+      display,
+      defaultValue,
+      ...meta
+    };
   }
   throw new Error(
     `Unsupported object spec type "${String(t)}". Supported: primitives (string/number/boolean/json/url/email), enum, regex`
@@ -259,4 +309,4 @@ export {
   normalizeSpec,
   envDoctor
 };
-//# sourceMappingURL=chunk-L5DK6LRX.mjs.map
+//# sourceMappingURL=chunk-CCJEPMPN.mjs.map