@safe-hand/safe-env-check 1.0.2 → 1.1.0

package/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Build
+        run: npm run build
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: npm publish --access public
+
+      - name: Create GitHub Release
+        uses: ncipollo/release-action@v1
+        env:
+          GITHUB_TOKEN: ${{secrets.GH_PAT}}
+        with:
+          tag: ${{ github.ref_name }}

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)  
+and [Semantic Versioning](https://semver.org/).
+
+---
+
+## [Unreleased]
+
+### Added
+
+- Placeholder for upcoming changes
+
+---
+
+## [1.0.3] - 2026-02-18
+
+### Added
+
+- Initial CHANGELOG.md for tracking
+- Release workflow setup
+
+## [1.0.2] - 2026-02-18
+
+### Added
+
+- Initial npm release (version already existed)
+- Schema-based environment validation
+- CLI support
+- Strict mode
+- TypeScript support
+- Support for types: `string`, `number`, `boolean`, `enum`
+- Required and default value support
+
+### Fixed
+
+- None yet

package/README.md

@@ -1,19 +1,53 @@
 # safe-env-check
 
-A tiny TypeScript library to validate environment variables with schema, strict mode, dotenv and CLI support.
+![npm](https://img.shields.io/npm/v/@safe-hand/safe-env-check)
+![license](https://img.shields.io/npm/l/@safe-hand/safe-env-check)
+![downloads](https://img.shields.io/npm/dm/@safe-hand/safe-env-check)
 
-## Install
+A tiny TypeScript library to validate environment variables using a schema with support for:
+
+- ✅ Type validation
+- ✅ Required & default values
+- ✅ Enum values
+- ✅ Strict mode (no extra env vars)
+- ✅ dotenv integration
+- ✅ Custom error formatting
+- ✅ CLI support
+
+---
+
+## Installation
+
+```bash
+npm install @safe-hand/safe-env-check
+```
+
+or
 
 ```bash
-npm install safe-env-check
+yarn add @safe-hand/safe-env-check
 ```
 
-## Usage
+## Features
+
+- Validate process.env using a schema
+
+- Strongly typed output (TypeScript)
+
+- Prevents app startup with invalid configuration
 
-```js
-import { validateEnv } from "safe-env-check";
+- Supports CLI for CI/CD and deployment checks
 
-const env = validateEnv({
+- Customizable error messages
+
+- Optional strict mode to disallow unknown variables
+
+## Basic Usage
+
+### Define a schema
+
+```ts
+const schema = {
   PORT: { type: "number", required: true },
   JWT_SECRET: { type: "string", required: true },
   NODE_ENV: {
@@ -21,36 +55,90 @@ const env = validateEnv({
     values: ["development", "production"],
     default: "development",
   },
-});
+};
+```
+
+### Validate environment variables
+
+```ts
+import { validateEnv } from "@safe-hand/safe-env-check";
+
+const env = validateEnv(schema);
+
+console.log(env.PORT); // number
+console.log(env.NODE_ENV); // "development" | "production"
+```
+
+## Schema Options
+
+Each environment variables supports the following options:
+
+| Field      | Type                                           | Description                      |
+| ---------- | ---------------------------------------------- | -------------------------------- |
+| `type`     | `"string"  or "number" or "boolean" or "enum"` | Expected value type              |
+| `required` | `boolean`                                      | Whether the variable is required |
+| `default`  | `any`                                          | Default value if not provided    |
+| `values`   | `string[]`                                     | Required for `enum` type         |
+
+## Example
+
+```ts
+DATABASE_URL: { type: "string", required: true },
+DEBUG: { type: "boolean", default: false },
+MODE: { type: "enum", values: ["dev", "prod"] }
 ```
 
-**With Strict Mode**
+## Strict Mode
 
-```js
+Disallow environment variables that are not defined in the schema.
+
+```ts
 validateEnv(schema, { strict: true });
 ```
 
-**With Custom Error Formatter**
+If extra variables are found, validation will fail.
+
+## Custom Error Formatter
 
-```js
+You can control how errors are displayed:
+
+```ts
 validateEnv(schema, {
   formatError: (errors) => `Config error:\n${errors.join("\n")}`,
 });
 ```
 
-## CLI
+## Dotenv Support
+
+By default, the library loads .env automatically using dotenv.
+
+Example .env file:
 
-Create a file called env.schema.js
+```bash
+PORT=3000
+JWT_SECRET=supersecret
+NODE_ENV=development
+```
 
-```js
+## CLI Usage
+
+Create a schema file called env.schema.js:
+
+```ts
 module.exports = {
   PORT: { type: "number", required: true },
-  NODE_ENV: { type: "enum", values: ["dev", "prod"] },
+  NODE_ENV: { type: "enum", values: ["dev", "prod"], default: "dev" },
 };
 ```
 
+Run validation:
+
 ```bash
 npx safe-env-check env.schema.js
+npx safe-env-check env.schema.js
+npx safe-env-check --schema env.schema.js --strict
+npx safe-env-check env.schema.js --env-file .env.production
+npx safe-env-check env.schema.js --format json
 ```
 
 ## License

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/cli.js

@@ -0,0 +1,170 @@
+"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 __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
+));
+
+// src/cli.ts
+var import_dotenv = __toESM(require("dotenv"));
+var import_path = __toESM(require("path"));
+var import_fs = __toESM(require("fs"));
+
+// package.json
+var version = "1.1.0";
+
+// src/validateEnv.ts
+var validateEnv = (schema, options = {}) => {
+  const errors = [];
+  const result = {};
+  if (options.strict) {
+    const schemaKeys = Object.keys(schema);
+    const envKeys = Object.keys(process.env);
+    const unknownKeys = envKeys.filter((key) => !schemaKeys.includes(key));
+    if (unknownKeys.length)
+      errors.push(`Unknown evn variables: ${unknownKeys.join(", ")}`);
+  }
+  for (const key in schema) {
+    const rule = schema[key];
+    const rawValue = process.env[key];
+    if (!rawValue) {
+      if (rule.required && rule.default === void 0) {
+        errors.push(`${key} is required`);
+        continue;
+      }
+      result[key] = rule.default;
+      continue;
+    }
+    switch (rule.type) {
+      case "string":
+        result[key] = rawValue;
+        break;
+      case "number":
+        const num = Number(rawValue);
+        if (isNaN(num)) errors.push(`${key} must be a number`);
+        else result[key] = num;
+        break;
+      case "boolean":
+        result[key] = rawValue === "true";
+        break;
+      case "enum":
+        if (!rule.values.includes(rawValue)) {
+          errors.push(`${key} must be one of: ${rule.values.join(", ")}`);
+        } else {
+          result[key] = rawValue;
+        }
+        break;
+    }
+  }
+  if (errors.length) {
+    const message = options.formatError ? options.formatError(errors) : defaultErrorFormatter(errors);
+    throw new Error(message);
+  }
+  return result;
+};
+var defaultErrorFormatter = (errors) => {
+  return "\u274C Environment validation failed:\n" + errors.map((e) => `- ${e}`).join("\n");
+};
+
+// src/cli.ts
+var args = process.argv.slice(2);
+var getArg = (flag) => {
+  const index = args.indexOf(flag);
+  return index !== -1 ? args[index + 1] : void 0;
+};
+var hasFlag = (flag) => args.includes(flag);
+var getPositionalArgs = (args2) => {
+  return args2.filter((arg, index) => {
+    if (arg.startsWith("--")) return false;
+    const prev = args2[index - 1];
+    if (prev === "--schema" || prev === "--env-file" || prev === "--format") {
+      return false;
+    }
+    return true;
+  });
+};
+var printHelp = () => {
+  console.log(`
+safe-env-check
+
+Usage:
+  safe-env-check <schema-file> [options]
+
+Options:
+  --schema <file>           Path to schema file
+  --strict                  Enable strict mode
+  --env-file <file>         Load a custom .env file
+  --format json             Output errors as JSON
+  --quiet                   Suppress success message
+  --version                 Show version
+  --help                    Show help
+
+Examples:
+  safe-env-check env.schema.js
+  safe-env-check --schema env.schema.js --strict
+  safe-env-check env.schema.js --env-file .env.production
+  safe-env-check env.schema.js --format json
+  safe-env-check --strict env.schema.js
+`);
+};
+if (hasFlag("--help")) {
+  printHelp();
+  process.exit(0);
+}
+if (hasFlag("--version")) {
+  console.log(version);
+  process.exit(0);
+}
+var positionalArgs = getPositionalArgs(args);
+var schemaFile = getArg("--schema") || positionalArgs[0];
+if (!schemaFile) {
+  console.error("\u274C Schema file is required.\n");
+  printHelp();
+  process.exit(1);
+}
+var envFile = getArg("--env-file");
+if (envFile) {
+  import_dotenv.default.config({ path: envFile });
+}
+var isStrict = hasFlag("--strict");
+var isQuiet = hasFlag("--quiet");
+var format = getArg("--format");
+try {
+  const fullPath = import_path.default.resolve(process.cwd(), schemaFile);
+  if (!import_fs.default.existsSync(fullPath)) {
+    throw new Error(`Schema file not found: ${schemaFile}`);
+  }
+  const schema = require(fullPath);
+  validateEnv(schema, {
+    strict: isStrict,
+    formatError: (errors) => {
+      if (format === "json") {
+        return JSON.stringify({ errors }, null, 2);
+      }
+      return "\u274C Environment validation failed:\n" + errors.map((e) => `- ${e}`).join("\n");
+    }
+  });
+  if (!isQuiet) {
+    console.log("\u2705 Environment variables are valid");
+  }
+} catch (error) {
+  console.error(error);
+  process.exit(1);
+}

package/package.json

@@ -1,13 +1,18 @@
 {
   "name": "@safe-hand/safe-env-check",
-  "version": "1.0.2",
+  "version": "1.1.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shshamim63/safe-env-check.git"
+  },
+  "homepage": "https://github.com/your-username/your-repo#readme",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
     "safe-env-check": "dist/cli.js"
   },
   "scripts": {
-    "build": "tsup src/index.ts --dts",
+    "build": "tsup src/index.ts src/cli.ts --dts",
     "dev": "ts-node src/index.ts",
     "test": "jest",
     "lint": "tsc --noEmit"

package/src/cli.ts

@@ -1,20 +1,143 @@
+import dotenv from "dotenv";
 import path from "path";
+import fs from "fs";
+import { version } from "../package.json";
 import { validateEnv } from "./validateEnv";
 
-const schemaPath = process.argv[2];
+const args = process.argv.slice(2);
 
-if (!schemaPath) {
-  console.error("Usage: safe-env-check <schema-file>");
+/**
+ * Get value of a flag: --schema file, --env-file file, --format json
+ */
+const getArg = (flag: string): string | undefined => {
+  const index = args.indexOf(flag);
+  return index !== -1 ? args[index + 1] : undefined;
+};
+
+/**
+ * Check if flag exists
+ */
+const hasFlag = (flag: string) => args.includes(flag);
+
+/**
+ * Extract positional (non-flag) arguments safely
+ */
+const getPositionalArgs = (args: string[]) => {
+  return args.filter((arg, index) => {
+    // remove flags
+    if (arg.startsWith("--")) return false;
+
+    // remove values of flags
+    const prev = args[index - 1];
+    if (prev === "--schema" || prev === "--env-file" || prev === "--format") {
+      return false;
+    }
+
+    return true;
+  });
+};
+
+const printHelp = () => {
+  console.log(`
+safe-env-check
+
+Usage:
+  safe-env-check <schema-file> [options]
+
+Options:
+  --schema <file>           Path to schema file
+  --strict                  Enable strict mode
+  --env-file <file>         Load a custom .env file
+  --format json             Output errors as JSON
+  --quiet                   Suppress success message
+  --version                 Show version
+  --help                    Show help
+
+Examples:
+  safe-env-check env.schema.js
+  safe-env-check --schema env.schema.js --strict
+  safe-env-check env.schema.js --env-file .env.production
+  safe-env-check env.schema.js --format json
+  safe-env-check --strict env.schema.js
+`);
+};
+
+/* =======================
+   Early exit flags
+======================= */
+
+if (hasFlag("--help")) {
+  printHelp();
+  process.exit(0);
+}
+
+if (hasFlag("--version")) {
+  console.log(version);
+  process.exit(0);
+}
+
+/* =======================
+   Resolve schema file
+======================= */
+
+const positionalArgs = getPositionalArgs(args);
+const schemaFile = getArg("--schema") || positionalArgs[0];
+
+if (!schemaFile) {
+  console.error("❌ Schema file is required.\n");
+  printHelp();
   process.exit(1);
 }
 
+/* =======================
+   Load env file if provided
+======================= */
+
+const envFile = getArg("--env-file");
+
+if (envFile) {
+  dotenv.config({ path: envFile });
+}
+
+/* =======================
+   Flags
+======================= */
+
+const isStrict = hasFlag("--strict");
+const isQuiet = hasFlag("--quiet");
+const format = getArg("--format");
+
+/* =======================
+   Main logic
+======================= */
+
 try {
-  const fullPath = path.resolve(process.cwd(), schemaPath);
+  const fullPath = path.resolve(process.cwd(), schemaFile);
+
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(`Schema file not found: ${schemaFile}`);
+  }
+
   const schema = require(fullPath);
 
-  validateEnv(schema);
-  console.log("✅ Environment variables are valid");
-} catch (error: any) {
-  console.error(error.message);
+  validateEnv(schema, {
+    strict: isStrict,
+    formatError: (errors) => {
+      if (format === "json") {
+        return JSON.stringify({ errors }, null, 2);
+      }
+
+      return (
+        "❌ Environment validation failed:\n" +
+        errors.map((e) => `- ${e}`).join("\n")
+      );
+    },
+  });
+
+  if (!isQuiet) {
+    console.log("✅ Environment variables are valid");
+  }
+} catch (error) {
+  console.error(error);
   process.exit(1);
 }

package/tests/cli.test.ts

@@ -0,0 +1,200 @@
+import path from "path";
+
+/**
+ * Mock validateEnv
+ */
+const mockValidateEnv = jest.fn();
+
+jest.mock("../src/validateEnv", () => ({
+  validateEnv: mockValidateEnv,
+}));
+
+/**
+ * Mock fs
+ */
+jest.mock("fs", () => ({
+  existsSync: jest.fn(),
+}));
+
+/**
+ * Mock dotenv
+ */
+jest.mock("dotenv", () => ({
+  config: jest.fn(),
+}));
+
+/**
+ * Mock package.json version
+ */
+jest.mock("../package.json", () => ({
+  version: "1.0.0",
+}));
+
+describe("CLI", () => {
+  const originalArgv = process.argv;
+  const originalEnv = process.env;
+
+  let exitSpy: jest.SpyInstance;
+  let logSpy: jest.SpyInstance;
+  let errorSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    jest.resetModules();
+
+    process.argv = ["node", "cli.ts"];
+    process.env = { ...originalEnv };
+
+    exitSpy = jest.spyOn(process, "exit").mockImplementation((() => {
+      throw new Error("process.exit");
+    }) as never);
+
+    logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    process.env = originalEnv;
+    jest.restoreAllMocks();
+  });
+
+  test("prints help when --help is passed", () => {
+    process.argv = ["node", "cli.ts", "--help"];
+
+    expect(() => require("../src/cli")).toThrow("process.exit");
+
+    expect(exitSpy).toHaveBeenCalledWith(0);
+    expect(logSpy).toHaveBeenCalled();
+  });
+
+  test("prints version when --version is passed", () => {
+    process.argv = ["node", "cli.ts", "--version"];
+
+    expect(() => require("../src/cli")).toThrow("process.exit");
+
+    expect(logSpy).toHaveBeenCalledWith("1.0.0");
+    expect(exitSpy).toHaveBeenCalledWith(0);
+  });
+
+  test("fails when schema file is missing", () => {
+    process.argv = ["node", "cli.ts"];
+
+    expect(() => require("../src/cli")).toThrow("process.exit");
+
+    expect(errorSpy).toHaveBeenCalledWith("❌ Schema file is required.\n");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test("fails if schema file does not exist", () => {
+    const fs = require("fs");
+    fs.existsSync.mockReturnValue(false);
+
+    process.argv = ["node", "cli.ts", "env.schema.js"];
+
+    expect(() => require("../src/cli")).toThrow("process.exit");
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  test("loads custom env file when --env-file is provided", () => {
+    const fs = require("fs");
+    const dotenv = require("dotenv");
+
+    fs.existsSync.mockReturnValue(true);
+
+    const schemaPath = path.resolve(process.cwd(), "env.schema.js");
+
+    jest.doMock(schemaPath, () => ({}), { virtual: true });
+
+    process.argv = [
+      "node",
+      "cli.ts",
+      "env.schema.js",
+      "--env-file",
+      ".env.production",
+    ];
+
+    mockValidateEnv.mockImplementation(() => ({}));
+
+    require("../src/cli");
+
+    expect(dotenv.config).toHaveBeenCalledWith({
+      path: ".env.production",
+    });
+  });
+
+  test("calls validateEnv with correct options", () => {
+    const fs = require("fs");
+    fs.existsSync.mockReturnValue(true);
+
+    const schemaPath = path.resolve(process.cwd(), "env.schema.js");
+
+    jest.doMock(
+      schemaPath,
+      () => ({
+        PORT: { type: "number", required: true },
+      }),
+      { virtual: true },
+    );
+
+    process.argv = [
+      "node",
+      "cli.ts",
+      "env.schema.js",
+      "--strict",
+      "--format",
+      "json",
+    ];
+
+    mockValidateEnv.mockImplementation(() => ({}));
+
+    require("../src/cli");
+
+    expect(mockValidateEnv).toHaveBeenCalledWith(
+      expect.any(Object),
+      expect.objectContaining({
+        strict: true,
+        formatError: expect.any(Function),
+      }),
+    );
+
+    expect(logSpy).toHaveBeenCalledWith("✅ Environment variables are valid");
+  });
+
+  test("suppresses success message with --quiet", () => {
+    const fs = require("fs");
+    fs.existsSync.mockReturnValue(true);
+
+    const schemaPath = path.resolve(process.cwd(), "env.schema.js");
+
+    jest.doMock(schemaPath, () => ({}), { virtual: true });
+
+    process.argv = ["node", "cli.ts", "env.schema.js", "--quiet"];
+
+    mockValidateEnv.mockImplementation(() => ({}));
+
+    require("../src/cli");
+
+    expect(logSpy).not.toHaveBeenCalledWith(
+      "✅ Environment variables are valid",
+    );
+  });
+
+  test("prints formatted error when validateEnv throws", () => {
+    const fs = require("fs");
+    fs.existsSync.mockReturnValue(true);
+
+    const schemaPath = path.resolve(process.cwd(), "env.schema.js");
+
+    jest.doMock(schemaPath, () => ({}), { virtual: true });
+
+    process.argv = ["node", "cli.ts", "env.schema.js", "--format", "json"];
+
+    mockValidateEnv.mockImplementation(() => {
+      throw new Error(JSON.stringify({ errors: ["PORT is required"] }));
+    });
+
+    expect(() => require("../src/cli")).toThrow("process.exit");
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});

package/tsconfig.json

@@ -7,6 +7,7 @@
     "rootDir": "src",
     "strict": true,
     "moduleResolution": "node",
+    "resolveJsonModule": true,
     "esModuleInterop": true,
     "skipLibCheck": true
   },