envguard-ts 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 envx contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,363 @@
+# envguard
+
+[![npm version](https://img.shields.io/npm/v/envguard?color=brightgreen)](https://www.npmjs.com/package/envguard)
+[![npm downloads](https://img.shields.io/npm/dw/envguard)](https://www.npmjs.com/package/envguard)
+[![bundle size](https://img.shields.io/bundlephobia/minzip/envguard?label=minzip)](https://bundlephobia.com/package/envguard)
+[![CI](https://github.com/Mehulbirare/npm-install-envx/actions/workflows/ci.yml/badge.svg)](https://github.com/Mehulbirare/npm-install-envx/actions)
+[![coverage](https://codecov.io/gh/Mehulbirare/npm-install-envx/branch/main/graph/badge.svg)](https://codecov.io/gh/Mehulbirare/npm-install-envx)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org/)
+[![license](https://img.shields.io/npm/l/envguard)](LICENSE)
+
+**Zero-dependency** TypeScript environment variable validator with compile-time type inference.  
+Validates on startup, throws human-readable errors, infers types — no `string` widening anywhere.
+
+```ts
+import { createEnv, str, num, bool, url, port } from 'envguard-ts'
+
+export const env = createEnv({
+  schema: {
+    DATABASE_URL: url(),
+    PORT:         port({ default: 3000 }),
+    NODE_ENV:     str({ choices: ['development', 'production', 'test'], default: 'development' }),
+    DEBUG:        bool({ default: false }),
+    API_KEY:      str({ secret: true }),   // masked in error output
+  },
+})
+
+env.PORT         // → number  (not string!)
+env.DATABASE_URL // → string
+env.DEBUG        // → boolean
+```
+
+If any required variable is missing or fails validation, `createEnv` throws a **structured, readable error at startup** — not a cryptic runtime crash deep in your app.
+
+```
+  ✖ Environment validation failed
+
+  DATABASE_URL: is required but missing
+  PORT: must be between 1 and 65535 (received: "99999")
+  NODE_ENV: must be one of ["development", "production", "test"] (received: "staging")
+```
+
+---
+
+## Table of contents
+
+- [Why envguard?](#why-envguard)
+- [Install](#install)
+- [Quick start](#quick-start)
+- [API reference](#api-reference)
+  - [createEnv](#createenv)
+  - [Validators](#validators)
+  - [generateExample](#generateexample)
+  - [validateEnvFile](#validateenvfile)
+  - [EnvValidationError](#envvalidationerror)
+- [CLI](#cli)
+- [Examples](#examples)
+- [Comparison](#comparison-vs-alternatives)
+- [Contributing](#contributing)
+
+---
+
+## Why envguard?
+
+| Feature | envguard | envalid | envsafe | t3-env |
+|---|:---:|:---:|:---:|:---:|
+| Zero dependencies | ✅ | ❌ (dotenv) | ✅ | ❌ (zod) |
+| TypeScript-first types | ✅ | ⚠️ | ✅ | ✅ |
+| Compile-time inference | ✅ | ❌ | ✅ | ✅ |
+| Bundle size | **< 3 KB** | ~15 KB | ~4 KB | ~12 KB |
+| Works in Edge / Deno / Bun | ✅ | ❌ | ⚠️ | ⚠️ |
+| CLI (`npx envguard check`) | ✅ | ❌ | ❌ | ❌ |
+| Auto `.env.example` gen | ✅ | ❌ | ❌ | ❌ |
+| Secret masking | ✅ | ❌ | ❌ | ❌ |
+| `choices` enum narrowing | ✅ | ✅ | ✅ | ✅ |
+
+---
+
+## Install
+
+```bash
+npm install envguard-ts
+# or
+pnpm add envguard-ts
+# or
+yarn add envguard-ts
+```
+
+No peer dependencies required. Works with Node ≥ 18, Deno, Bun, and all Edge runtimes.
+
+---
+
+## Quick start
+
+### 1. Create your env file
+
+```ts
+// src/env.ts
+import { createEnv, str, num, bool, url, port, email } from 'envguard-ts'
+
+export const env = createEnv({
+  schema: {
+    DATABASE_URL:  url({ protocols: ['postgresql:', 'postgres:'] }),
+    REDIS_URL:     url({ default: 'redis://localhost:6379' }),
+    PORT:          port({ default: 3000 }),
+    NODE_ENV:      str({ choices: ['development', 'production', 'test'], default: 'development' }),
+    DEBUG:         bool({ default: false }),
+    API_KEY:       str({ secret: true }),
+    ADMIN_EMAIL:   email({ default: 'admin@example.com' }),
+    MAX_POOL_SIZE: num({ default: 10, min: 1, max: 100 }),
+  },
+})
+```
+
+### 2. Import it everywhere
+
+```ts
+import { env } from './env'
+
+// Fully typed, never undefined at runtime
+const db = createPool(env.DATABASE_URL)
+app.listen(env.PORT)
+```
+
+### 3. Validate before deploy
+
+```bash
+npx envguard check --env .env.production --schema src/env.js
+```
+
+---
+
+## API reference
+
+### `createEnv(options)`
+
+The primary API. Validates environment variables and returns a **frozen, typed object**.
+
+```ts
+function createEnv<S extends Schema>(options: CreateEnvOptions<S>): InferEnv<S>
+```
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `schema` | `Schema` | required | Map of variable names → validators |
+| `env` | `Record<string, string \| undefined>` | `process.env` | Override the env source (great for tests) |
+| `skipValidation` | `boolean` | `false` | Return without throwing (useful in test setup) |
+| `onError` | `(errors: FieldError[]) => void` | — | Called before throwing, for custom logging |
+
+Throws [`EnvValidationError`](#envvalidationerror) if validation fails.
+
+---
+
+### Validators
+
+All validators accept a `BaseOptions` bag:
+
+```ts
+interface BaseOptions<T> {
+  default?:     T        // Makes the variable optional
+  description?: string  // Shown in generated .env.example
+  secret?:      boolean // Mask value in error output
+}
+```
+
+#### `str(opts?)`
+
+Validates a string. Returned type: `string`.
+
+```ts
+str()
+str({ choices: ['a', 'b', 'c'] })           // string literal union NOT inferred — use enums() for that
+str({ minLength: 1, maxLength: 255 })
+str({ pattern: /^[a-z]+$/ })
+str({ default: 'hello', secret: true })
+```
+
+| Option | Type | Description |
+|---|---|---|
+| `choices` | `string[]` | Restrict to allowed values |
+| `minLength` | `number` | Minimum string length (inclusive) |
+| `maxLength` | `number` | Maximum string length (inclusive) |
+| `pattern` | `RegExp` | Must match regex |
+
+#### `num(opts?)`
+
+Validates a number (integer or float). Returned type: `number`.
+
+```ts
+num()
+num({ min: 0, max: 100 })
+num({ default: 42 })
+```
+
+#### `bool(opts?)`
+
+Validates a boolean. Accepts: `true/false/1/0/yes/no/on/off` (case-insensitive). Returned type: `boolean`.
+
+```ts
+bool()
+bool({ default: false })
+```
+
+#### `url(opts?)`
+
+Validates a URL using the WHATWG `URL` parser. Returned type: `string`.
+
+```ts
+url()
+url({ protocols: ['https:'] })
+url({ protocols: ['postgresql:', 'postgres:'] })
+```
+
+#### `port(opts?)`
+
+Validates a port number (1–65535). Returned type: `number`.
+
+```ts
+port()
+port({ default: 3000 })
+```
+
+#### `email(opts?)`
+
+Validates an email address. Returned type: `string`.
+
+```ts
+email()
+email({ default: 'admin@example.com' })
+```
+
+#### `json<T>(opts?)`
+
+Parses a JSON-encoded string. Returned type: `T` (defaults to `unknown`).
+
+```ts
+json()
+json<string[]>({ default: [] })
+json<{ apiUrl: string; timeout: number }>()
+```
+
+#### `enums(values, opts?)`
+
+Validates against a const-asserted string tuple. **Narrows the return type** to the union.
+
+```ts
+enums(['debug', 'info', 'warn', 'error'] as const)
+// → ValidatorSpec<'debug' | 'info' | 'warn' | 'error'>
+```
+
+---
+
+### `generateExample(schema)`
+
+Generates the text of a `.env.example` file from a schema. Secrets are shown as `[secret]`.
+
+```ts
+import { generateExample } from 'envguard'
+import { schema } from './env'
+import fs from 'node:fs'
+
+fs.writeFileSync('.env.example', generateExample(schema))
+```
+
+Or use the CLI: `npx envguard generate`
+
+---
+
+### `validateEnvFile(parsed, schema)`
+
+Validates a pre-parsed `{ KEY: value }` map against a schema, returning errors without throwing. Used internally by the CLI.
+
+```ts
+const errors = validateEnvFile(
+  { PORT: 'not-a-number' },
+  { PORT: port() },
+)
+// errors → [{ field: 'PORT', message: '...', received: 'not-a-number' }]
+```
+
+---
+
+### `EnvValidationError`
+
+```ts
+class EnvValidationError extends Error {
+  readonly errors: readonly FieldError[]
+}
+
+interface FieldError {
+  field:    string           // Variable name
+  message:  string           // Human-readable failure reason
+  received: string | undefined  // Raw value (or '[secret]' / undefined)
+}
+```
+
+---
+
+## CLI
+
+```bash
+# Validate a .env file against a schema
+npx envguard check
+npx envguard check --env .env.production --schema dist/env.js
+
+# Generate .env.example from a schema
+npx envguard generate
+npx envguard generate --schema dist/env.js --out .env.example
+```
+
+The schema file must export the schema object as `default`, `schema`, or the module itself:
+
+```js
+// envguard-ts.schema.js  (default location)
+const { str, url, port } = require('envguard-ts')
+module.exports = {
+  DATABASE_URL: url(),
+  PORT: port({ default: 3000 }),
+  API_KEY: str({ secret: true }),
+}
+```
+
+Exit codes: `0` = valid, `1` = invalid or error.
+
+---
+
+## Examples
+
+- [Express](./examples/express/)
+- [Next.js](./examples/nextjs/)
+- [Fastify](./examples/fastify/)
+
+---
+
+## Comparison vs alternatives
+
+### vs `envalid`
+
+envalid is battle-tested but has a dotenv peer dependency, a larger bundle (~15 KB), no TypeScript-first design, and no CLI tooling. envguard is zero-dep and infers precise types at compile time.
+
+### vs `envsafe`
+
+envsafe is TS-first and has good inference but is no longer actively maintained. envguard adds the CLI, secret masking, and `.env.example` generation.
+
+### vs `t3-env`
+
+t3-env wraps Zod which is powerful but adds ~12 KB to your bundle and requires Zod as a peer. envguard is zero-dependency and covers 95% of real-world use cases in < 3 KB. If you already use Zod heavily, t3-env might be a better fit; otherwise envguard is the lighter choice.
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feat/my-feature`
+3. Run tests: `npm test`
+4. Submit a pull request
+
+Please ensure `npm run test:coverage` passes at ≥ 90% coverage before opening a PR.
+
+---
+
+## License
+
+MIT © envguard contributors

package/bin/envx.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+// envx CLI entry point
+import('../dist/esm/cli.js').catch((e) => {
+  // Fallback to CJS if ESM import fails (Node 18 with --require hooks, etc.)
+  try {
+    require('../dist/cjs/cli.js')
+  } catch {
+    console.error('[envx] Failed to load CLI:', e?.message ?? e)
+    process.exit(1)
+  }
+})

package/dist/cjs/cli.js

@@ -0,0 +1,153 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * envx CLI — validate and generate .env files
+ *
+ * Commands:
+ *   envx check [--env <file>] [--schema <file>]
+ *   envx generate [--schema <file>] [--out <file>]
+ */
+const fs = require("node:fs");
+const path = require("node:path");
+const core_js_1 = require("./core.js");
+// ---------------------------------------------------------------------------
+// Tiny .env parser (no dependency)
+// ---------------------------------------------------------------------------
+function parseEnvFile(content) {
+    const result = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const eqIdx = line.indexOf('=');
+        if (eqIdx === -1)
+            continue;
+        const key = line.slice(0, eqIdx).trim();
+        let value = line.slice(eqIdx + 1).trim();
+        // Strip surrounding quotes
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Arg parser
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+    const args = {};
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg !== undefined && arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith('--')) {
+                args[key] = next;
+                i++;
+            }
+            else {
+                args[key] = true;
+            }
+        }
+    }
+    return args;
+}
+// ---------------------------------------------------------------------------
+// Commands
+// ---------------------------------------------------------------------------
+async function loadSchema(schemaPath) {
+    const resolved = path.resolve(process.cwd(), schemaPath);
+    if (!fs.existsSync(resolved)) {
+        console.error(`[envx] schema file not found: ${resolved}`);
+        process.exit(1);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const mod = await Promise.resolve(`${resolved}`).then(s => require(s));
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
+    const schema = (mod.default ?? mod.schema ?? mod);
+    if (typeof schema !== 'object' || schema === null) {
+        console.error('[envx] schema file must export a default schema object');
+        process.exit(1);
+    }
+    return schema;
+}
+async function cmdCheck(args) {
+    const envFile = typeof args['env'] === 'string' ? args['env'] : '.env';
+    const schemaFile = typeof args['schema'] === 'string' ? args['schema'] : 'envguard.schema.js';
+    const envPath = path.resolve(process.cwd(), envFile);
+    if (!fs.existsSync(envPath)) {
+        console.error(`[envx] env file not found: ${envPath}`);
+        process.exit(1);
+    }
+    const schema = await loadSchema(schemaFile);
+    const parsed = parseEnvFile(fs.readFileSync(envPath, 'utf8'));
+    const errors = (0, core_js_1.validateEnvFile)(parsed, schema);
+    if (errors.length === 0) {
+        console.log(`\x1b[32m✔ ${envFile} is valid\x1b[0m`);
+        return;
+    }
+    console.error(`\x1b[31m✖ ${envFile} has ${errors.length} error(s):\x1b[0m\n`);
+    for (const err of errors) {
+        const received = err.received !== undefined ? ` (received: \x1b[90m${JSON.stringify(err.received)}\x1b[0m)` : '';
+        console.error(`  \x1b[33m${err.field}\x1b[0m: ${err.message}${received}`);
+    }
+    console.error('');
+    process.exit(1);
+}
+async function cmdGenerate(args) {
+    const schemaFile = typeof args['schema'] === 'string' ? args['schema'] : 'envguard.schema.js';
+    const outFile = typeof args['out'] === 'string' ? args['out'] : '.env.example';
+    const schema = await loadSchema(schemaFile);
+    const content = (0, core_js_1.generateExample)(schema);
+    fs.writeFileSync(path.resolve(process.cwd(), outFile), content, 'utf8');
+    console.log(`\x1b[32m✔ Generated ${outFile}\x1b[0m`);
+}
+function printHelp() {
+    console.log(`
+  \x1b[1menvx\x1b[0m — Environment variable validator
+
+  \x1b[1mUsage:\x1b[0m
+    envx check    [--env <file>]    [--schema <file>]
+    envx generate [--schema <file>] [--out <file>]
+
+  \x1b[1mCommands:\x1b[0m
+    check       Validate a .env file against a schema (default: .env / envx.schema.js)
+    generate    Generate a .env.example from a schema (default output: .env.example)
+
+  \x1b[1mOptions:\x1b[0m
+    --env       Path to the .env file          (default: .env)
+    --schema    Path to the schema JS/TS file  (default: envx.schema.js)
+    --out       Output path for generate       (default: .env.example)
+    --help      Show this help message
+`);
+}
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+async function main() {
+    const [, , command, ...rest] = process.argv;
+    const args = parseArgs(rest);
+    if (args['help'] || !command) {
+        printHelp();
+        return;
+    }
+    switch (command) {
+        case 'check':
+            await cmdCheck(args);
+            break;
+        case 'generate':
+            await cmdGenerate(args);
+            break;
+        default:
+            console.error(`[envx] Unknown command: ${command}`);
+            printHelp();
+            process.exit(1);
+    }
+}
+main().catch((err) => {
+    console.error('[envx] Unexpected error:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cjs/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/cjs/core.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEnv = createEnv;
+exports.generateExample = generateExample;
+exports.validateEnvFile = validateEnvFile;
+const errors_js_1 = require("./errors.js");
+// ---------------------------------------------------------------------------
+// createEnv
+// ---------------------------------------------------------------------------
+/**
+ * Validates environment variables against the provided schema and returns a
+ * fully-typed, frozen object. Throws {@link EnvValidationError} on failure.
+ *
+ * @example
+ * ```ts
+ * export const env = createEnv({
+ *   schema: {
+ *     DATABASE_URL: url(),
+ *     PORT: port({ default: 3000 }),
+ *     NODE_ENV: str({ choices: ['development', 'production', 'test'], default: 'development' }),
+ *     DEBUG: bool({ default: false }),
+ *     API_KEY: str({ secret: true }),
+ *   },
+ * })
+ * ```
+ */
+function createEnv(options) {
+    const { schema, env = process.env, skipValidation = false, onError } = options;
+    const errors = [];
+    const result = {};
+    for (const [field, spec] of Object.entries(schema)) {
+        const raw = env[field];
+        if (raw === undefined || raw === '') {
+            if (spec._default !== undefined) {
+                result[field] = spec._default;
+                continue;
+            }
+            if (!spec._required) {
+                // optional with no default → undefined (shouldn't happen given the overloads, but be safe)
+                result[field] = undefined;
+                continue;
+            }
+            errors.push({ field, message: 'is required but missing', received: undefined });
+            continue;
+        }
+        try {
+            const parsed = spec._parse(raw, field);
+            spec._validate(parsed, field);
+            result[field] = parsed;
+        }
+        catch (e) {
+            errors.push({
+                field,
+                message: e instanceof Error ? e.message : String(e),
+                received: spec._secret ? '[secret]' : raw,
+            });
+        }
+    }
+    if (errors.length > 0 && !skipValidation) {
+        onError?.(errors);
+        throw new errors_js_1.EnvValidationError(errors);
+    }
+    return Object.freeze(result);
+}
+// ---------------------------------------------------------------------------
+// generateExample
+// ---------------------------------------------------------------------------
+/**
+ * Generates the text content of a `.env.example` file from a schema.
+ * Variables without defaults are left blank; those with defaults show the default.
+ * Secrets are shown as `[secret]`.
+ *
+ * @example
+ * ```ts
+ * import { schema } from './env'
+ * import { generateExample } from 'envx'
+ * fs.writeFileSync('.env.example', generateExample(schema))
+ * ```
+ */
+function generateExample(schema) {
+    const lines = [
+        '# Auto-generated by envx — do not commit real secrets',
+        '',
+    ];
+    for (const [field, spec] of Object.entries(schema)) {
+        if (spec._description) {
+            lines.push(`# ${spec._description}`);
+        }
+        let value;
+        if (spec._secret) {
+            value = '[secret]';
+        }
+        else if (spec._default !== undefined) {
+            value = String(spec._default);
+        }
+        else {
+            value = '';
+        }
+        lines.push(`${field}=${value}`);
+    }
+    return lines.join('\n') + '\n';
+}
+// ---------------------------------------------------------------------------
+// validateEnvFile
+// ---------------------------------------------------------------------------
+/**
+ * Given the parsed key=value pairs from a `.env` file and a schema, returns
+ * any validation errors without throwing. Useful in CI/pre-deploy checks.
+ */
+function validateEnvFile(parsed, schema) {
+    const errors = [];
+    for (const [field, spec] of Object.entries(schema)) {
+        const raw = parsed[field];
+        if (raw === undefined || raw === '') {
+            if (spec._default !== undefined || !spec._required)
+                continue;
+            errors.push({ field, message: 'is required but missing', received: undefined });
+            continue;
+        }
+        try {
+            const parsed2 = spec._parse(raw, field);
+            spec._validate(parsed2, field);
+        }
+        catch (e) {
+            errors.push({
+                field,
+                message: e instanceof Error ? e.message : String(e),
+                received: spec._secret ? '[secret]' : raw,
+            });
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=core.js.map