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

package/.github/workflows/release.yml

@@ -3,7 +3,7 @@ name: Release
 on:
   push:
     tags:
-      - 'v*.*.*'
+      - "v*.*.*"
 
 jobs:
   release:
@@ -14,8 +14,8 @@ jobs:
       - name: Set up Node.js
         uses: actions/setup-node@v3
         with:
-          node-version: '20'
-          registry-url: 'https://registry.npmjs.org'
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
 
       - name: Install dependencies
         run: npm install
@@ -30,5 +30,7 @@ jobs:
 
       - name: Create GitHub Release
         uses: ncipollo/release-action@v1
+        env:
+          GITHUB_TOKEN: ${{secrets.GH_PAT}}
         with:
           tag: ${{ github.ref_name }}

package/README.md

@@ -4,7 +4,6 @@
 ![license](https://img.shields.io/npm/l/@safe-hand/safe-env-check)
 ![downloads](https://img.shields.io/npm/dm/@safe-hand/safe-env-check)
 
-
 A tiny TypeScript library to validate environment variables using a schema with support for:
 
 - ✅ Type validation
@@ -22,7 +21,9 @@ A tiny TypeScript library to validate environment variables using a schema with
 ```bash
 npm install @safe-hand/safe-env-check
 ```
+
 or
+
 ```bash
 yarn add @safe-hand/safe-env-check
 ```
@@ -44,6 +45,7 @@ yarn add @safe-hand/safe-env-check
 ## Basic Usage
 
 ### Define a schema
+
 ```ts
 const schema = {
   PORT: { type: "number", required: true },
@@ -57,26 +59,29 @@ const schema = {
 ```
 
 ### 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"
+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         |           |         |                     |
+| 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 },
@@ -84,14 +89,19 @@ MODE: { type: "enum", values: ["dev", "prod"] }
 ```
 
 ## Strict Mode
+
 Disallow environment variables that are not defined in the schema.
+
 ```ts
 validateEnv(schema, { strict: true });
 ```
+
 If extra variables are found, validation will fail.
 
 ## Custom Error Formatter
+
 You can control how errors are displayed:
+
 ```ts
 validateEnv(schema, {
   formatError: (errors) => `Config error:\n${errors.join("\n")}`,
@@ -103,6 +113,7 @@ validateEnv(schema, {
 By default, the library loads .env automatically using dotenv.
 
 Example .env file:
+
 ```bash
 PORT=3000
 JWT_SECRET=supersecret
@@ -112,6 +123,7 @@ NODE_ENV=development
 ## CLI Usage
 
 Create a schema file called env.schema.js:
+
 ```ts
 module.exports = {
   PORT: { type: "number", required: true },
@@ -120,10 +132,15 @@ module.exports = {
 ```
 
 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
 
-MIT © Shakhawat Hossain
+MIT © Shakhawat Hossain

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.3",
+  "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
   },