env-safe-check 1.0.0 → 1.0.2

package/README.md

@@ -1,93 +1,255 @@
-# env-safe-check
-
-Reliable, minimal utility to validate required environment variables at runtime.
-
-This tiny library helps Node and TypeScript projects fail fast with a clear
-error message when required environment variables are missing or empty.
-
-**Highlights**
-
-- Zero runtime dependencies
-- Tiny API: a single `validateEnv()` function
-- Works in TypeScript and JavaScript projects (ESM)
-- Safe defaults for CI and production (exits with non-zero code on missing vars)
-
-## Installation
-
-Install from npm (devs using this repo can also build locally):
-
-```bash
-npm install env-safe-check
-```
-
-For local development (this repository):
-
-```bash
-npm install
-npm run build
-```
-
-## Quick usage
-
-TypeScript (recommended):
-
-```ts
-import { validateEnv } from 'env-safe-check';
-
-// throw and exit if any required env var is missing or empty
-validateEnv(['DATABASE_URL', 'API_KEY']);
-```
-
-JavaScript (ESM):
-
-```js
-import { validateEnv } from 'env-safe-check';
-
-validateEnv(['DATABASE_URL', 'API_KEY']);
-```
-
-When any required variable is missing the library prints a friendly list
-and exits the process with code `1`.
-
-## API
-
-- `validateEnv(required: string[]): void`
-  - `required` — array of environment variable names to verify.
-  - Throws/terminates the process (with a console error) when any are
-    missing or empty.
-
-## Project specifics (for contributors / package authors)
-
-- Source files are TypeScript in `src/`.
-- Build emits ESM JavaScript into `dist/`.
-- Source imports are written without `.js` extensions for ergonomics in
-  TypeScript; the build process rewrites emitted imports to include `.js`
-  so the output is runnable under Node ESM (`node >= 12` with ESM support).
-
-Commands:
-
-```bash
-# Build and patch emitted imports
-npm run build
-
-# Run TypeScript type-check only
-npx tsc --noEmit
-```
-
-## Publishing
-
-1. Bump the package version in `package.json`.
-2. Run `npm run build` to produce `dist/`.
-3. Verify the `main`/`exports` fields point to built files (if applicable).
-4. `npm publish --access public`
-
-## Contributing
-
-Contributions are welcome. Open issues for bugs or small feature requests.
-
-Please run the tests (if added) and ensure linting/type-checks pass before
-submitting a PR.
-
-## License
-
-MIT
+# env-safe-check
+
+Reliable, minimal utility to validate required environment variables at runtime.
+
+This tiny library helps Node and TypeScript projects fail fast with a clear
+error message when required environment variables are missing or empty.
+
+**Highlights**
+
+- Zero runtime dependencies
+- Two APIs: simple (legacy array) or powerful (schema-based)
+- Type-safe: automatic parsing for `string`, `number`, `boolean`, `json`
+- Custom validators: add your own validation logic
+- Defaults & optional vars: sensible config for each variable
+- Colorful error messages with variable descriptions
+- Works in TypeScript and JavaScript projects (ESM)
+- Safe defaults for CI and production (exits with non-zero code on errors)
+
+## Installation
+
+Install from npm (devs using this repo can also build locally):
+
+```bash
+npm install env-safe-check
+```
+
+For local development (this repository):
+
+```bash
+npm install
+npm run build
+```
+
+## Quick usage
+
+### Simple mode (Legacy)
+
+Validate a list of required environment variables:
+
+```ts
+import { validateEnv } from 'env-safe-check';
+
+// Exits with code 1 if any are missing
+validateEnv(['DATABASE_URL', 'API_KEY']);
+```
+
+### Schema mode (Recommended)
+
+Validate with types, defaults, custom validators, and descriptions:
+
+```ts
+import { validateEnv, type VariableSchema } from 'env-safe-check';
+
+const env = validateEnv({
+  schema: {
+    DATABASE_URL: { type: 'string', description: 'PostgreSQL connection URL' },
+    PORT: { type: 'number', default: '3000' },
+    DEBUG: { type: 'boolean', default: 'false', required: false },
+    NODE_ENV: {
+      type: 'string',
+      validator: (value) =>
+        ['development', 'production', 'test'].includes(value)
+          ? true
+          : 'Must be one of: development, production, test',
+    },
+    FEATURE_CONFIG: { type: 'json', required: false },
+  },
+  throwError: false, // default: exits process on error
+  silent: false,     // default: prints colorful output
+});
+
+// Returns parsed and validated env object:
+// { DATABASE_URL: string, PORT: number, DEBUG: boolean, NODE_ENV: string, FEATURE_CONFIG?: any }
+console.log(env.PORT); // 3000 (or parsed value from process.env.PORT)
+```
+
+## API
+
+### `validateEnv(required: string[]): void` (Legacy)
+
+- **required** — array of environment variable names to verify
+- **Returns** — void; exits process (code 1) if any are missing or empty
+- **Console output** — colorful error/success messages
+
+### `validateEnv(config: ValidateEnvOptions): Record<string, any>` (Recommended)
+
+- **config.schema** — Record of variable names to schema definitions
+  - Each value can be:
+    - A type string shorthand: `'string' | 'number' | 'boolean' | 'json'`
+    - A full `VariableSchema` object (see below)
+- **config.throwError** (default: `false`) — throw `EnvValidationError` instead of exiting process
+- **config.silent** (default: `false`) — suppress console output
+- **Returns** — `Record<string, any>` with parsed env variables
+- **Throws** — `EnvValidationError` if `throwError: true` and validation fails
+
+### `VariableSchema`
+
+```ts
+interface VariableSchema {
+  // Type of the variable. Parsed and validated accordingly.
+  // 'string' | 'number' | 'boolean' | 'json'
+  type?: 'string' | 'number' | 'boolean' | 'json';
+
+  // Whether this variable is required (default: true)
+  required?: boolean;
+
+  // Default value if not set and not required
+  default?: string;
+
+  // Custom validation function
+  // Return true if valid, or an error string if invalid
+  validator?: (value: string) => boolean | string;
+
+  // Description for error messages
+  description?: string;
+}
+```
+
+### `EnvValidationError`
+
+Thrown when validation fails with `throwError: true`:
+
+```ts
+try {
+  const env = validateEnv({ schema: { /* ... */ }, throwError: true });
+} catch (err) {
+  if (err instanceof EnvValidationError) {
+    console.error('Missing:', err.missing); // string[]
+    console.error('Invalid:', err.invalid); // Record<string, string>
+  }
+}
+```
+
+## Examples
+
+### Type parsing with defaults
+
+```ts
+const env = validateEnv({
+  schema: {
+    PORT: { type: 'number', default: '3000' },
+    TIMEOUT: { type: 'number', required: false },
+    ENABLE_CACHE: { type: 'boolean', default: 'true' },
+  },
+});
+
+// PORT is always a number (parsed from env or default)
+// TIMEOUT is optional; undefined if not set
+// ENABLE_CACHE is always a boolean
+```
+
+### Custom validators
+
+```ts
+const env = validateEnv({
+  schema: {
+    WORKER_THREADS: {
+      type: 'number',
+      validator: (val) => {
+        const num = Number(val);
+        if (num < 1 || num > 32) {
+          return 'Must be between 1 and 32';
+        }
+        return true;
+      },
+    },
+  },
+});
+```
+
+### Throw errors instead of exiting
+
+```ts
+try {
+  const env = validateEnv({
+    schema: { DB_URL: 'string' },
+    throwError: true,
+  });
+} catch (err) {
+  if (err instanceof EnvValidationError) {
+    // Handle custom error; code continues (doesn't exit)
+  }
+}
+```
+
+## Project specifics (for contributors / package authors)
+
+- Source files are TypeScript in `src/`.
+- Build emits ESM JavaScript into `dist/`.
+- Source imports are written without `.js` extensions for ergonomics in
+  TypeScript; the build process rewrites emitted imports to include `.js`
+  so the output is runnable under Node ESM (`node >= 12` with ESM support).
+
+Commands:
+
+```bash
+# Build and patch emitted imports
+npm run build
+
+# Run TypeScript type-check only
+npx tsc --noEmit
+```
+
+## Publishing
+
+1. Bump the package version in `package.json`.
+2. Run `npm run build` to produce `dist/`.
+3. Verify the `main`/`exports` fields point to built files (if applicable).
+4. `npm publish --access public`
+
+## Contributing
+
+Contributions are welcome. Open issues for bugs or small feature requests.
+
+Please run the tests (if added) and ensure linting/type-checks pass before submitting a PR.
+
+### Conventional Commits
+
+This project uses [semantic-release](https://semantic-release.gitbook.io/) to automate versioning and publishing based on commit messages. Please follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+
+```
+type(scope): subject
+
+body
+
+footer
+```
+
+**Types:**
+- `feat:` A new feature (bumps minor version)
+- `fix:` A bug fix (bumps patch version)
+- `docs:` Documentation changes
+- `style:` Code style changes (no logic changes)
+- `refactor:` Refactor code without changing behavior
+- `perf:` Performance improvements
+- `test:` Adding/updating tests
+- `ci:` CI/CD changes
+- `chore:` Build, dependencies, etc.
+
+**Breaking Changes:**
+- Add `BREAKING CHANGE: description` in the footer to bump major version
+- Or use `feat!:` in the type to indicate a breaking change
+
+**Examples:**
+```bash
+npm run cz                  # Interactive prompt (recommended)
+git commit -m "feat: add JSON type validation"
+git commit -m "fix: correct boolean parsing"
+git commit -m "feat!: change API to return parsed object"
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Variable type for validation and parsing.
+ */
+type VariableType = 'string' | 'number' | 'boolean' | 'json';
+/**
+ * Schema definition for a single environment variable.
+ */
+interface VariableSchema {
+    /**
+     * Type of the variable. Parsed and validated accordingly.
+     * @default 'string'
+     */
+    type?: VariableType;
+    /**
+     * Whether this variable is required.
+     * @default true
+     */
+    required?: boolean;
+    /**
+     * Default value if the variable is not set (and not required).
+     */
+    default?: string;
+    /**
+     * Custom validator function. Return true if valid, or an error message string if invalid.
+     */
+    validator?: (value: string) => boolean | string;
+    /**
+     * Description of the variable (for error messages).
+     */
+    description?: string;
+}
+/**
+ * Options for validateEnv function.
+ */
+interface ValidateEnvOptions {
+    /**
+     * Schema defining required/optional vars, types, defaults, and validators.
+     */
+    schema: Record<string, VariableSchema | VariableType>;
+    /**
+     * If true, throw a custom error instead of calling process.exit(1).
+     * @default false
+     */
+    throwError?: boolean;
+    /**
+     * If true, don't print console messages.
+     * @default false
+     */
+    silent?: boolean;
+}
+/**
+ * Custom error thrown when validation fails (if throwError option is true).
+ */
+declare class EnvValidationError extends Error {
+    readonly missing: string[];
+    readonly invalid: Record<string, string>;
+    constructor(message: string, missing?: string[], invalid?: Record<string, string>);
+}
+
+/**
+ * Validate environment variables against a schema with type checking, defaults, and custom validators.
+ *
+ * @overload
+ * function validateEnv(config: ValidateEnvOptions): Record<string, any>
+ *
+ * @overload
+ * function validateEnv(required: string[]): void
+ */
+declare function validateEnv(configOrRequired: ValidateEnvOptions | string[]): Record<string, any> | void;
+
+export { EnvValidationError, ValidateEnvOptions, VariableSchema, VariableType, validateEnv };

package/dist/index.js

@@ -0,0 +1,163 @@
+// src/types.ts
+var EnvValidationError = class extends Error {
+  constructor(message, missing = [], invalid = {}) {
+    super(message);
+    this.missing = missing;
+    this.invalid = invalid;
+    this.name = "EnvValidationError";
+  }
+};
+
+// src/validate.ts
+var colors = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  red: "\x1B[31m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m",
+  gray: "\x1B[90m"
+};
+function parseValue(value, type) {
+  switch (type) {
+    case "number":
+      const num = Number(value);
+      if (isNaN(num))
+        throw new Error("Invalid number");
+      return num;
+    case "boolean":
+      if (value.toLowerCase() === "true" || value === "1")
+        return true;
+      if (value.toLowerCase() === "false" || value === "0")
+        return false;
+      throw new Error("Invalid boolean (expected 'true', 'false', '1', or '0')");
+    case "json":
+      return JSON.parse(value);
+    case "string":
+    default:
+      return value;
+  }
+}
+function validateEnv(configOrRequired) {
+  if (Array.isArray(configOrRequired)) {
+    validateEnvLegacy(configOrRequired);
+    return;
+  }
+  const config = configOrRequired;
+  const { schema, throwError = false, silent = false } = config;
+  const missing = [];
+  const invalid = {};
+  const parsed = {};
+  for (const [key, schemaDef] of Object.entries(schema)) {
+    const varSchema = typeof schemaDef === "string" ? { type: schemaDef } : schemaDef;
+    const isRequired = varSchema.required !== false;
+    const type = varSchema.type || "string";
+    const value = process.env[key];
+    if (value === void 0 || value.trim() === "") {
+      if (isRequired) {
+        missing.push(key);
+      } else if (varSchema.default !== void 0) {
+        try {
+          parsed[key] = parseValue(varSchema.default, type);
+        } catch (err) {
+          invalid[key] = `Default value invalid: ${err.message}`;
+        }
+      }
+      continue;
+    }
+    try {
+      parsed[key] = parseValue(value, type);
+    } catch (err) {
+      invalid[key] = `${err.message}`;
+      continue;
+    }
+    if (varSchema.validator) {
+      const validationResult = varSchema.validator(value);
+      if (validationResult !== true) {
+        const errorMsg = typeof validationResult === "string" ? validationResult : "Validation failed";
+        invalid[key] = errorMsg;
+      }
+    }
+  }
+  const hasErrors = missing.length > 0 || Object.keys(invalid).length > 0;
+  if (hasErrors) {
+    const errorMsg = buildErrorMessage(missing, invalid, schema);
+    if (!silent) {
+      console.error(errorMsg);
+    }
+    if (throwError) {
+      throw new EnvValidationError(
+        "Environment variable validation failed",
+        missing,
+        invalid
+      );
+    } else {
+      process.exit(1);
+    }
+  }
+  if (!silent) {
+    console.log(`${colors.green}\u2705 All environment variables are valid.${colors.reset}`);
+  }
+  return parsed;
+}
+function validateEnvLegacy(required) {
+  const missing = required.filter((key) => {
+    const value = process.env[key];
+    return value === void 0 || value.trim() === "";
+  });
+  if (missing.length > 0) {
+    console.error(
+      `${colors.red}${colors.bold}\u274C Missing required environment variables:${colors.reset}
+`
+    );
+    missing.forEach((key) => {
+      console.error(`${colors.yellow}- ${key}${colors.reset}`);
+    });
+    console.error(
+      `
+${colors.cyan}Tip:${colors.reset} define them in your .env file or environment config.`
+    );
+    process.exit(1);
+  }
+  console.log(
+    `${colors.green}\u2705 All required environment variables are present.${colors.reset}`
+  );
+}
+function buildErrorMessage(missing, invalid, schema) {
+  let msg = `${colors.red}${colors.bold}\u274C Environment validation failed${colors.reset}
+`;
+  if (missing.length > 0) {
+    msg += `
+${colors.bold}Missing required variables:${colors.reset}
+`;
+    missing.forEach((key) => {
+      const desc = getSchemaDescription(key, schema);
+      msg += `  ${colors.yellow}${key}${colors.reset}${desc ? ` - ${colors.gray}${desc}${colors.reset}` : ""}
+`;
+    });
+  }
+  if (Object.keys(invalid).length > 0) {
+    msg += `
+${colors.bold}Invalid variables:${colors.reset}
+`;
+    for (const [key, error] of Object.entries(invalid)) {
+      msg += `  ${colors.yellow}${key}${colors.reset}: ${error}
+`;
+    }
+  }
+  msg += `
+${colors.cyan}Tip:${colors.reset} define/fix them in your .env file or environment config.`;
+  return msg;
+}
+function getSchemaDescription(key, schema) {
+  const def = schema[key];
+  if (!def)
+    return "";
+  if (typeof def === "string")
+    return "";
+  return def.description || "";
+}
+export {
+  EnvValidationError,
+  validateEnv
+};

package/package.json

@@ -1,18 +1,45 @@
 {
   "name": "env-safe-check",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "type": "module",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "test": "echo \"hello world\"",
-    "build": "tsc && node ./scripts/patch-extensions.cjs"
+    "build": "tsup src/index.ts --format esm --dts --out-dir dist",
+    "prepare": "npm run build && husky install",
+    "cz": "cz"
   },
-  "keywords": [],
-  "author": "",
+  "keywords": [
+    "env",
+    "environment",
+    "validation",
+    "safe",
+    "check",
+    "typescript"
+  ],
+  "author": "Pushpak Kurella",
   "license": "ISC",
   "description": "",
   "devDependencies": {
-    "typescript": "^5.9.3",
-    "@types/node": "^20.6.5"
+    "@commitlint/config-conventional": "^20.4.1",
+    "@semantic-release/github": "^12.0.6",
+    "@semantic-release/npm": "^13.1.4",
+    "@types/node": "^20.6.5",
+    "commitizen": "^4.3.1",
+    "commitlint": "^20.4.1",
+    "cz-conventional-changelog": "^3.3.0",
+    "husky": "^9.1.7",
+    "semantic-release": "^25.0.3",
+    "tsup": "^6.6.0",
+    "typescript": "^5.9.3"
+  },
+  "config": {
+    "commitizen": {
+      "path": "./node_modules/cz-conventional-changelog"
+    }
   }
 }

package/.github/workflows/npm-publish.yml

@@ -1,38 +0,0 @@
-# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
-# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
-
-name: Node.js Package
-
-on:
-  release:
-    types: [created]
-  workflow_dispatch: {}
-
-jobs:
-  build:
-    # Only run automatically for the `main` branch or when a release is created.
-    if: github.ref == 'refs/heads/main' || github.event_name == 'release' || github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-      - run: npm ci
-      - run: npm test
-
-  publish-npm:
-    needs: build
-    # Only publish when the run is for `main` or a release (keeps publishes scoped to main).
-    if: github.ref == 'refs/heads/main' || github.event_name == 'release' || github.event_name == 'workflow_dispatch'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          registry-url: https://registry.npmjs.org/
-      - run: npm ci
-      - run: npm publish
-        env:
-          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/scripts/patch-extensions.cjs

@@ -1,32 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-
-function walk(dir) {
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) walk(full);
-    else if (entry.isFile() && full.endsWith('.js')) patchFile(full);
-  }
-}
-
-function patchFile(file) {
-  let src = fs.readFileSync(file, 'utf8');
-  src = src.replace(/(from\s+|import\()(["'])(\.\/[^"'\)]+?)\2/g, (m, p1, q, p2) => {
-    if (/\.[a-zA-Z0-9]+$/.test(p2)) return m;
-    return `${p1}${q}${p2}.js${q}`;
-  });
-  src = src.replace(/(export\s+[^;]*?from\s+)(["'])(\.\/[^"']+?)\2/g, (m, p1, q, p2) => {
-    if (/\.[a-zA-Z0-9]+$/.test(p2)) return m;
-    return `${p1}${q}${p2}.js${q}`;
-  });
-  fs.writeFileSync(file, src, 'utf8');
-}
-
-const dist = path.join(__dirname, '..', 'dist');
-if (!fs.existsSync(dist)) {
-  console.error('dist directory not found; run tsc first');
-  process.exit(1);
-}
-walk(dist);
-console.log('Patched imports to include .js extensions in', dist);

package/scripts/patch-extensions.js

@@ -1,38 +0,0 @@
-const fs = require('fs');
-const path = require('path');
-
-function walk(dir) {
-  const entries = fs.readdirSync(dir, { withFileTypes: true });
-  for (const entry of entries) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) walk(full);
-    else if (entry.isFile() && full.endsWith('.js')) patchFile(full);
-  }
-}
-
-function patchFile(file) {
-  let src = fs.readFileSync(file, 'utf8');
-  // Replace import/export specifiers that are relative and have no extension
-  // Examples: import {x} from "./foo"  -> ./foo.js
-  //          export * from './bar'    -> ./bar.js
-  src = src.replace(/(from\s+|import\()(["'])(\.\/[^"'\)]+?)\2/g, (m, p1, q, p2) => {
-    // p2 is like ./module or ../module/sub
-    // If it already ends with an extension, leave it
-    if (/\.[a-zA-Z0-9]+$/.test(p2)) return m;
-    return `${p1}${q}${p2}.js${q}`;
-  });
-  // also handle export ... from '...'
-  src = src.replace(/(export\s+[^;]*?from\s+)(["'])(\.\/[^"']+?)\2/g, (m, p1, q, p2) => {
-    if (/\.[a-zA-Z0-9]+$/.test(p2)) return m;
-    return `${p1}${q}${p2}.js${q}`;
-  });
-  fs.writeFileSync(file, src, 'utf8');
-}
-
-const dist = path.join(__dirname, '..', 'dist');
-if (!fs.existsSync(dist)) {
-  console.error('dist directory not found; run tsc first');
-  process.exit(1);
-}
-walk(dist);
-console.log('Patched imports to include .js extensions in', dist);

package/src/index.ts

@@ -1 +0,0 @@
-export { validateEnv } from "./validate";

package/src/validate.ts

@@ -1,20 +0,0 @@
-export function validateEnv(required: string[]): void {
-  const missing = required.filter((key) => {
-    const value = process.env[key];
-    return value === undefined || value.trim() === "";
-  });
-
-  if (missing.length > 0) {
-    console.error("❌ Missing required environment variables:\n");
-
-    missing.forEach((key) => {
-      console.error(`- ${key}`);
-    });
-
-    console.error(
-      "\nPlease define them in your .env file or environment config."
-    );
-
-    process.exit(1);
-  }
-}

package/tsconfig.json

@@ -1,46 +0,0 @@
-{
-  // Visit https://aka.ms/tsconfig to read more about this file
-  "compilerOptions": {
-    // File Layout
-    // "rootDir": "./src",
-    // "outDir": "./dist",
-
-    // Environment Settings
-    // See also https://aka.ms/tsconfig/module
-    "module": "esnext",
-    "moduleResolution": "node",
-    "target": "esnext",
-    "outDir": "./dist",
-    "types": ["node"],
-    // For nodejs:
-    // "lib": ["esnext"],
-    // "types": ["node"],
-    // and npm install -D @types/node
-
-    // Other Outputs
-    "sourceMap": true,
-    "declaration": true,
-    "declarationMap": true,
-
-    // Stricter Typechecking Options
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true,
-
-    // Style Options
-    // "noImplicitReturns": true,
-    // "noImplicitOverride": true,
-    // "noUnusedLocals": true,
-    // "noUnusedParameters": true,
-    // "noFallthroughCasesInSwitch": true,
-    // "noPropertyAccessFromIndexSignature": true,
-
-    // Recommended Options
-    "strict": true,
-    "jsx": "react-jsx",
-    "verbatimModuleSyntax": true,
-    "isolatedModules": true,
-    "noUncheckedSideEffectImports": true,
-    "moduleDetection": "force",
-    "skipLibCheck": true,
-  }
-}