@safe-hand/safe-env-check 1.0.1

package/README.md

@@ -0,0 +1,53 @@
+# safe-env-check
+
+A tiny TypeScript library to validate environment variables with schema, strict mode, dotenv and CLI support.
+
+## Install
+
+```bash
+npm install safe-env-check
+```
+
+## Usage
+
+```js
+import { validateEnv } from "safe-env-check";
+
+const env = validateEnv({
+  PORT: { type: "number", required: true },
+  JWT_SECRET: { type: "string", required: true },
+  NODE_ENV: {
+    type: "enum",
+    values: ["development", "production"],
+    default: "development",
+  },
+});
+```
+
+**With Strict Mode**
+
+```js
+validateEnv(schema, { strict: true });
+```
+
+**With Custom Error Formatter**
+
+```js
+validateEnv(schema, {
+  formatError: (errors) => `Config error:\n${errors.join("\n")}`,
+});
+```
+
+## CLI
+
+Create a file called env.schema.js
+
+```js
+module.exports = {
+  PORT: { type: "number", required: true },
+  NODE_ENV: { type: "enum", values: ["dev", "prod"] },
+};
+```
+```bash
+  npx safe-env-check env.schema.js
+```

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+type EnvField = {
+    type: "string";
+    required?: boolean;
+    default?: string;
+} | {
+    type: "number";
+    required?: boolean;
+    default?: number;
+} | {
+    type: "boolean";
+    required?: boolean;
+    default?: boolean;
+} | {
+    type: "enum";
+    values: readonly string[];
+    required?: boolean;
+    default?: string;
+};
+type EnvSchema = Record<string, EnvField>;
+interface ValidateEnvOptions {
+    strict?: boolean;
+    formatError?: (error: string[]) => string;
+}
+
+declare const validateEnv: <T extends EnvSchema>(schema: T, options?: ValidateEnvOptions) => { [K in keyof T]: any; };
+
+export { type EnvField, type EnvSchema, type ValidateEnvOptions, validateEnv };

package/dist/index.js

@@ -0,0 +1,82 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  validateEnv: () => validateEnv
+});
+module.exports = __toCommonJS(index_exports);
+
+// 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");
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  validateEnv
+});

package/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  testMatch: ["**/tests/**/*.test.ts"],
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@safe-hand/safe-env-check",
+  "version": "1.0.1",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "safe-env-check": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --dts",
+    "dev": "ts-node src/index.ts",
+    "test": "jest",
+    "lint": "tsc --noEmit"
+  },
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.2.3",
+    "jest": "^30.2.0",
+    "ts-jest": "^29.4.6",
+    "ts-node": "^10.9.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "dependencies": {
+    "dotenv": "^17.2.4"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,20 @@
+import path from "path";
+import { validateEnv } from "./validateEnv";
+
+const schemaPath = process.argv[2];
+
+if (!schemaPath) {
+  console.error("Usage: safe-env-check <schema-file>");
+  process.exit(1);
+}
+
+try {
+  const fullPath = path.resolve(process.cwd(), schemaPath);
+  const schema = require(fullPath);
+
+  validateEnv(schema);
+  console.log("✅ Environment variables are valid");
+} catch (error: any) {
+  console.error(error.message);
+  process.exit(1);
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { validateEnv } from "./validateEnv";
+
+export * from "./types";

package/src/types.ts

@@ -0,0 +1,17 @@
+export type EnvField =
+  | { type: "string"; required?: boolean; default?: string }
+  | { type: "number"; required?: boolean; default?: number }
+  | { type: "boolean"; required?: boolean; default?: boolean }
+  | {
+      type: "enum";
+      values: readonly string[];
+      required?: boolean;
+      default?: string;
+    };
+
+export type EnvSchema = Record<string, EnvField>;
+
+export interface ValidateEnvOptions {
+  strict?: boolean;
+  formatError?: (error: string[]) => string;
+}

package/src/validateEnv.ts

@@ -0,0 +1,74 @@
+import { EnvSchema, ValidateEnvOptions } from "./types";
+
+export const validateEnv = <T extends EnvSchema>(
+  schema: T,
+  options: ValidateEnvOptions = {},
+): { [K in keyof T]: any } => {
+  const errors: string[] = [];
+  const result: any = {};
+
+  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 === undefined) {
+        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;
+};
+
+const defaultErrorFormatter = (errors: string[]) => {
+  return (
+    "❌ Environment validation failed:\n" +
+    errors.map((e) => `- ${e}`).join("\n")
+  );
+};

package/tests/validateEnv.test.ts

@@ -0,0 +1,63 @@
+import { validateEnv } from "../src/validateEnv";
+
+describe("validateEnv", () => {
+  beforeEach(() => {
+    process.env = {};
+  });
+
+  it("validates required number", () => {
+    process.env.PORT = "3000";
+
+    const env = validateEnv({
+      PORT: { type: "number", required: true },
+    });
+
+    expect(env.PORT).toBe(3000);
+  });
+
+  it("throws on missing required", () => {
+    expect(() =>
+      validateEnv({
+        JWT_SECRET: { type: "string", required: true },
+      }),
+    ).toThrow("JWT_SECRET is required");
+  });
+
+  it("supports default value", () => {
+    const env = validateEnv({
+      NODE_ENV: { type: "string", default: "development" },
+    });
+
+    expect(env.NODE_ENV).toBe("development");
+  });
+
+  it("supports enum", () => {
+    process.env.MODE = "prod";
+
+    const env = validateEnv({
+      MODE: { type: "enum", values: ["dev", "prod"] },
+    });
+
+    expect(env.MODE).toBe("prod");
+  });
+
+  it("strict mode fails on unknown env", () => {
+    process.env.UNKNOWN = "123";
+
+    expect(() =>
+      validateEnv(
+        { PORT: { type: "number", required: true } },
+        { strict: true },
+      ),
+    ).toThrow("❌ Environment validation failed:");
+  });
+
+  it("custom error formatter", () => {
+    expect(() =>
+      validateEnv(
+        { PORT: { type: "number", required: true } },
+        { formatError: (errs) => "Custom: " + errs.join(",") },
+      ),
+    ).toThrow("Custom:");
+  });
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "declaration": true,
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}