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

package/README.md

@@ -4,15 +4,37 @@
 ![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:
+A tiny TypeScript-first environment variable validator that ensures your application starts with a correct configuration.
 
-- ✅ Type validation
-- ✅ Required & default values
-- ✅ Enum values
-- ✅ Strict mode (no extra env vars)
+It validates process.env using a schema and provides strong **TypeScript typing**, **CLI validation**, and **CI/CD integration**.
+
+## Why safe-env-check?
+
+Environment variables are string-based and error-prone.
+
+Common problems:
+
+- Missing required variables
+- Incorrect types
+- Unexpected environment variables
+- Misconfigured deployments
+- Incorrect .env files in CI/CD
+
+safe-env-check prevents these issues **before your app starts**.
+
+## Features
+
+- ✅ Type validation (`string`, `number`, `boolean`, `enum`)
+- ✅ Required values
+- ✅ Default values
+- ✅ Enum validation
+- ✅ Strict mode (no unknown variables)
+- ✅ Prefix support (multi-environment setup)
 - ✅ dotenv integration
 - ✅ Custom error formatting
+- ✅ Type-safe output for TypeScript
 - ✅ CLI support
+- ✅ CI/CD friendly
 
 ---
 
@@ -28,20 +50,6 @@ or
 yarn add @safe-hand/safe-env-check
 ```
 
-## Features
-
-- Validate process.env using a schema
-
-- Strongly typed output (TypeScript)
-
-- Prevents app startup with invalid configuration
-
-- Supports CLI for CI/CD and deployment checks
-
-- Customizable error messages
-
-- Optional strict mode to disallow unknown variables
-
 ## Basic Usage
 
 ### Define a schema
@@ -69,9 +77,9 @@ console.log(env.PORT); // number
 console.log(env.NODE_ENV); // "development" | "production"
 ```
 
-## Schema Options
+### Schema Options
 
-Each environment variables supports the following options:
+Each environment variable supports the following options:
 
 | Field      | Type                                           | Description                      |
 | ---------- | ---------------------------------------------- | -------------------------------- |
@@ -80,25 +88,162 @@ Each environment variables supports the following options:
 | `default`  | `any`                                          | Default value if not provided    |
 | `values`   | `string[]`                                     | Required for `enum` type         |
 
-## Example
+### Example Schema
 
 ```ts
-DATABASE_URL: { type: "string", required: true },
-DEBUG: { type: "boolean", default: false },
-MODE: { type: "enum", values: ["dev", "prod"] }
+const schema = {
+  DATABASE_URL: { type: "string", required: true },
+  PORT: { type: "number", default: 3000 },
+  DEBUG: { type: "boolean", default: false },
+  MODE: {
+    type: "enum",
+    values: ["dev", "prod"],
+  },
+};
 ```
 
-## Strict Mode
+### Default Values
 
-Disallow environment variables that are not defined in the schema.
+If a variable is missing, the default value will be used.
+
+```ts
+const schema = {
+  PORT: { type: "number", default: 3000 },
+};
+```
+
+**`.env`**
+
+```bash
+# PORT missing
+```
+
+**Result:**
+
+```cmd
+PORT = 3000
+```
+
+### Required Variables
+
+```ts
+const schema = {
+  DATABASE_URL: { type: "string", required: true },
+};
+```
+
+If missing:
+
+```cmd
+Error ❌ Environment validation failed:
+- DATABASE_URL is required
+```
+
+### Boolean Parsing
+
+Boolean values accept:
+
+```bash
+true
+false
+```
+
+**Example:**
+
+```cmd
+DEBUG=true
+```
+
+**Schema**
+
+```ts
+const schema = {
+  DEBUG: {
+    type: "boolean",
+  },
+};
+```
+
+### Enum Validation
+
+Restrict values to a predefined list.
+
+```ts
+NODE_ENV: {
+  type: "enum",
+  values: ["development", "production", "test"],
+}
+```
+
+Invalid values will throw an error.
+
+### Strict Mode
+
+Prevent unexpected environment variables.
 
 ```ts
 validateEnv(schema, { strict: true });
 ```
 
-If extra variables are found, validation will fail.
+If .env contains variables not defined in the schema:
+
+```cmd
+Unknown env variables: SOME_RANDOM_VAR
+```
+
+### Prefix Support
+
+Useful for multi-service or multi-tenant configs.
+
+**Example** `.env`:
+
+```bash
+API_PORT=3000
+API_SECRET=123
+```
+
+**Schema:**
+
+```ts
+const schema = {
+  PORT: { type: "number" },
+  SECRET: { type: "string" },
+};
+```
+
+**Usage:**
+
+```ts
+validateEnv(schema, { prefix: "API_" });
+```
+
+### Env File Support
+
+Useful for defining custom env file.
+
+**Example** `.env.production`:
+
+```bash
+API_PORT=3000
+API_SECRET=123
+```
+
+**Schema:**
+
+```ts
+const schema = {
+  PORT: { type: "number" },
+  SECRET: { type: "string" },
+};
+```
+
+**Usage:**
 
-## Custom Error Formatter
+```ts
+validateEnv(schema, { prefix: "API_", envFile: ".env.production" });
+```
+
+### Custom Error Formatter
 
 You can control how errors are displayed:
 
@@ -108,11 +253,22 @@ validateEnv(schema, {
 });
 ```
 
-## Dotenv Support
+## Loading Environment Variables
+
+`safe-env-check` does **not automatically load `.env` files**.
+
+Load environment variables before calling `validateEnv`, for example using `dotenv`:
+
+```ts
+import dotenv from "dotenv";
+import { validateEnv } from "@safe-hand/safe-env-check";
+
+dotenv.config();
 
-By default, the library loads .env automatically using dotenv.
+const env = validateEnv(schema);
+```
 
-Example .env file:
+**Example** `.env`:
 
 ```bash
 PORT=3000
@@ -120,9 +276,17 @@ JWT_SECRET=supersecret
 NODE_ENV=development
 ```
 
+If you are using the CLI, you can provide a custom environment file:
+
+```bash
+safe-env-check --env-file .env.test
+```
+
 ## CLI Usage
 
-Create a schema file called env.schema.js:
+You can validate environment variables without writing code.
+
+This is useful for CI/CD pipelines.
 
 ```ts
 module.exports = {
@@ -131,16 +295,105 @@ module.exports = {
 };
 ```
 
-Run validation:
+**Run validation:**
 
-```bash
+```cmd
 npx safe-env-check env.schema.js
+```
+
+or
+
+```cmd
+npx safe-env-check --schema env.schema.js
+```
+
+### CLI Options
+
+| Flag            | Description                                                                                    |
+| --------------- | ---------------------------------------------------------------------------------------------- |
+| `--schema`      | schema file path                                                                               |
+| `--env-file`    | load a custom env file                                                                         |
+| `--strict`      | enable strict mode                                                                             |
+| `--prefix`      | env variable prefix                                                                            |
+| `--format json` | output errors in JSON                                                                          |
+| `--quiet`       | Suppress the success message "✅ Environment variables are valid" (errors still exit non-zero) |
+
+|
+
+### CLI Examples
+
+**Basic validation**
+
+```cmd
 npx safe-env-check env.schema.js
-npx safe-env-check --schema env.schema.js --strict
+```
+
+**Using strict mode**
+
+```cmd
+npx safe-env-check env.schema.js --strict
+```
+
+**Using prefix**
+
+```cmd
+npx safe-env-check env.schema.js --prefix API_
+```
+
+**Suppress success message**
+
+```cmd
+safe-env-check env.schema.js --quiet
+```
+
+**Validate production env file**
+
+```cmd
 npx safe-env-check env.schema.js --env-file .env.production
+```
+
+**JSON error output**
+
+```cmd
 npx safe-env-check env.schema.js --format json
 ```
 
+Useful for CI systems.
+
+## CI/CD Example
+
+Validate environment configuration during deployment.
+
+Example **GitHub Actions step**
+
+```yaml
+- name: Validate Environment Variables
+  run: npx safe-env-check env.schema.js --env-file .env.production --strict
+```
+
+This prevents deployments with invalid configuration.
+
+## TypeScript Type Safety
+
+The returned object is fully typed.
+
+```ts
+const env = validateEnv(schema);
+
+env.PORT; // number
+env.NODE_ENV; // "development" | "production"
+```
+
+## When to Use safe-env-check
+
+- Node.js APIs
+- Microservices
+- Docker containers
+- CI/CD pipelines
+- Serverless functions
+- Monorepos
+- Multi-environment deployments
+
 ## License
 
 MIT © Shakhawat Hossain

package/dist/cli/index.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node