envguard-ts 1.0.0

package/dist/esm/validators.js

@@ -0,0 +1,124 @@
+function makeSpec(parse, validate, opts) {
+    return {
+        _type: undefined,
+        _required: opts.required,
+        _default: opts.default,
+        _secret: opts.secret ?? false,
+        _description: opts.description,
+        _parse: parse,
+        _validate: validate,
+    };
+}
+export function str(opts = {}) {
+    return makeSpec((raw) => raw, (value, field) => {
+        if (opts.choices && !opts.choices.includes(value)) {
+            throw new Error(`must be one of [${opts.choices.map((c) => JSON.stringify(c)).join(', ')}], got ${JSON.stringify(value)} for ${field}`);
+        }
+        if (opts.minLength !== undefined && value.length < opts.minLength) {
+            throw new Error(`must be at least ${opts.minLength} characters for ${field}`);
+        }
+        if (opts.maxLength !== undefined && value.length > opts.maxLength) {
+            throw new Error(`must be at most ${opts.maxLength} characters for ${field}`);
+        }
+        if (opts.pattern && !opts.pattern.test(value)) {
+            throw new Error(`must match pattern ${opts.pattern} for ${field}`);
+        }
+    }, { ...opts, required: opts.default === undefined });
+}
+export function num(opts = {}) {
+    return makeSpec((raw, field) => {
+        const n = Number(raw);
+        if (!Number.isFinite(n))
+            throw new Error(`must be a finite number for ${field}`);
+        return n;
+    }, (value, field) => {
+        if (opts.min !== undefined && value < opts.min) {
+            throw new Error(`must be >= ${opts.min} for ${field}`);
+        }
+        if (opts.max !== undefined && value > opts.max) {
+            throw new Error(`must be <= ${opts.max} for ${field}`);
+        }
+    }, { ...opts, required: opts.default === undefined });
+}
+const TRUTHY = new Set(['true', '1', 'yes', 'on']);
+const FALSY = new Set(['false', '0', 'no', 'off']);
+export function bool(opts = {}) {
+    return makeSpec((raw, field) => {
+        const lower = raw.toLowerCase();
+        if (TRUTHY.has(lower))
+            return true;
+        if (FALSY.has(lower))
+            return false;
+        throw new Error(`must be a boolean (true/false/1/0/yes/no/on/off) for ${field}, got ${JSON.stringify(raw)}`);
+    }, () => { }, { ...opts, required: opts.default === undefined });
+}
+export function url(opts = {}) {
+    return makeSpec((raw, field) => {
+        try {
+            const parsed = new URL(raw);
+            if (opts.protocols && !opts.protocols.includes(parsed.protocol)) {
+                throw new Error(`protocol must be one of [${opts.protocols.join(', ')}] for ${field}, got ${parsed.protocol}`);
+            }
+            return raw;
+        }
+        catch (e) {
+            if (e instanceof Error && e.message.includes('for ' + field))
+                throw e;
+            throw new Error(`must be a valid URL for ${field}`);
+        }
+    }, () => { }, { ...opts, required: opts.default === undefined });
+}
+export function port(opts = {}) {
+    return makeSpec((raw, field) => {
+        const n = parseInt(raw, 10);
+        if (Number.isNaN(n) || String(n) !== raw.trim()) {
+            throw new Error(`must be an integer port number for ${field}`);
+        }
+        if (n < 1 || n > 65535) {
+            throw new Error(`must be between 1 and 65535 for ${field}`);
+        }
+        return n;
+    }, () => { }, { ...opts, required: opts.default === undefined });
+}
+// RFC-5321-compatible simplified regex — fast and covers 99%+ real addresses
+const EMAIL_RE = /^[a-zA-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?)*\.[a-zA-Z]{2,}$/;
+export function email(opts = {}) {
+    return makeSpec((raw, field) => {
+        if (!EMAIL_RE.test(raw)) {
+            throw new Error(`must be a valid email address for ${field}`);
+        }
+        return raw;
+    }, () => { }, { ...opts, required: opts.default === undefined });
+}
+export function json(opts = {}) {
+    return makeSpec((raw, field) => {
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            throw new Error(`must be valid JSON for ${field}`);
+        }
+    }, () => { }, { ...opts, required: opts.default === undefined });
+}
+// ---------------------------------------------------------------------------
+// enums  (string union)
+// ---------------------------------------------------------------------------
+/**
+ * Validates that a variable matches one value from a const-asserted tuple.
+ * Provides a narrower return type than `str({ choices })`.
+ *
+ * @example
+ * ```ts
+ * LOG_LEVEL: enums(['debug', 'info', 'warn', 'error'] as const)
+ * ```
+ */
+export function enums(values, opts) {
+    const base = opts ?? {};
+    return makeSpec((raw, field) => {
+        if (!values.includes(raw)) {
+            throw new Error(`must be one of [${values.map((v) => JSON.stringify(v)).join(', ')}] for ${field}`);
+        }
+        return raw;
+    }, () => { }, { ...base, required: base.default === undefined });
+}
+//# sourceMappingURL=validators.js.map

package/dist/esm/validators.js.map

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

package/dist/types/cli.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/types/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":""}

package/dist/types/core.d.ts

@@ -0,0 +1,70 @@
+import { type FieldError } from './errors.js';
+import type { ValidatorSpec } from './validators.js';
+/** A schema maps env var names to their validator specs. */
+export type Schema = Record<string, ValidatorSpec<any>>;
+/**
+ * Infer the output type from a schema.
+ * Required validators produce `T`, optional ones produce `T` (since the
+ * default fills the gap — callers never receive `undefined`).
+ */
+export type InferEnv<S extends Schema> = {
+    readonly [K in keyof S]: S[K] extends ValidatorSpec<infer T> ? T : never;
+};
+/** Options accepted by {@link createEnv}. */
+export interface CreateEnvOptions<S extends Schema> {
+    /** The schema describing every expected variable and its validator. */
+    schema: S;
+    /**
+     * Source of raw string values. Defaults to `process.env`.
+     * Override for testing or edge-runtime environments.
+     */
+    env?: Record<string, string | undefined>;
+    /**
+     * When `true`, `createEnv` returns `null` instead of throwing on failure.
+     * Useful for unit tests that want to inspect the error.
+     * @default false
+     */
+    skipValidation?: boolean;
+    /**
+     * Custom reporter called before throwing {@link EnvValidationError}.
+     * Receives the structured list of errors so you can log them however you like.
+     */
+    onError?: (errors: FieldError[]) => void;
+}
+/**
+ * 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 }),
+ *   },
+ * })
+ * ```
+ */
+export declare function createEnv<S extends Schema>(options: CreateEnvOptions<S>): InferEnv<S>;
+/**
+ * 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))
+ * ```
+ */
+export declare function generateExample(schema: Schema): string;
+/**
+ * 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.
+ */
+export declare function validateEnvFile(parsed: Record<string, string>, schema: Schema): FieldError[];
+//# sourceMappingURL=core.d.ts.map

package/dist/types/core.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,aAAa,CAAA;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAMpD,4DAA4D;AAE5D,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,GAAG,CAAC,CAAC,CAAA;AAEvD;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,MAAM,IAAI;IACvC,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK;CACzE,CAAA;AAMD,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM;IAChD,uEAAuE;IACvE,MAAM,EAAE,CAAC,CAAA;IACT;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;IACxC;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,IAAI,CAAA;CACzC;AAMD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAyCrF;AAMD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAwBtD;AAMD;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,MAAM,GACb,UAAU,EAAE,CAyBd"}

package/dist/types/errors.d.ts

@@ -0,0 +1,19 @@
+/** A single field-level validation failure. */
+export interface FieldError {
+    /** The environment variable name. */
+    field: string;
+    /** Human-readable description of what went wrong. */
+    message: string;
+    /** The raw value that failed validation (undefined if variable was missing). */
+    received: string | undefined;
+}
+/**
+ * Thrown when one or more environment variables fail validation.
+ * Provides a structured list of field errors and a formatted human-readable message.
+ */
+export declare class EnvValidationError extends Error {
+    /** Structured list of every field that failed. */
+    readonly errors: readonly FieldError[];
+    constructor(errors: FieldError[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/types/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAA;IACb,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAA;IACf,gFAAgF;IAChF,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;CAC7B;AAED;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAA;gBAE1B,MAAM,EAAE,UAAU,EAAE;CAkBjC"}

package/dist/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * envx — Zero-dependency TypeScript env variable validator
+ * @module envx
+ */
+export { createEnv, generateExample, validateEnvFile } from './core.js';
+export type { Schema, InferEnv, CreateEnvOptions } from './core.js';
+export { str, num, bool, url, port, email, json, enums } from './validators.js';
+export type { ValidatorSpec, BaseOptions, StrOptions, NumOptions, BoolOptions, UrlOptions, PortOptions, EmailOptions, JsonOptions, } from './validators.js';
+export { EnvValidationError } from './errors.js';
+export type { FieldError } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AACvE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAGnE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAC/E,YAAY,EACV,aAAa,EACb,WAAW,EACX,UAAU,EACV,UAAU,EACV,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,WAAW,GACZ,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAChD,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA"}

package/dist/types/validators.d.ts

@@ -0,0 +1,157 @@
+/** Options shared by every validator. */
+export interface BaseOptions<T> {
+    /**
+     * Default value used when the env var is absent.
+     * When provided, the variable becomes optional in validation.
+     */
+    default?: T;
+    /**
+     * Human-readable description shown in generated .env.example files.
+     */
+    description?: string;
+    /**
+     * When true, the value is masked as `[secret]` in log output.
+     */
+    secret?: boolean;
+}
+/** Marker interface carried by every validator spec. */
+export interface ValidatorSpec<T> {
+    readonly _type: T;
+    readonly _required: boolean;
+    readonly _default: T | undefined;
+    readonly _secret: boolean;
+    readonly _description: string | undefined;
+    /** @internal */
+    readonly _parse: (raw: string, field: string) => T;
+    /** @internal */
+    readonly _validate: (value: T, field: string) => void;
+}
+/** Options for {@link str}. */
+export interface StrOptions extends BaseOptions<string> {
+    /** Restrict to a specific set of allowed values. */
+    choices?: readonly string[];
+    /** Minimum string length (inclusive). */
+    minLength?: number;
+    /** Maximum string length (inclusive). */
+    maxLength?: number;
+    /** Regex the value must match. */
+    pattern?: RegExp;
+}
+/**
+ * Validates a string environment variable.
+ *
+ * @example
+ * ```ts
+ * NODE_ENV: str({ choices: ['development', 'production', 'test'], default: 'development' })
+ * ```
+ */
+export declare function str(opts: StrOptions & {
+    default: string;
+}): ValidatorSpec<string>;
+export declare function str(opts?: StrOptions): ValidatorSpec<string>;
+/** Options for {@link num}. */
+export interface NumOptions extends BaseOptions<number> {
+    /** Minimum value (inclusive). */
+    min?: number;
+    /** Maximum value (inclusive). */
+    max?: number;
+}
+/**
+ * Validates a numeric environment variable. Accepts integers and floats.
+ *
+ * @example
+ * ```ts
+ * TIMEOUT_MS: num({ default: 5000, min: 0 })
+ * ```
+ */
+export declare function num(opts: NumOptions & {
+    default: number;
+}): ValidatorSpec<number>;
+export declare function num(opts?: NumOptions): ValidatorSpec<number>;
+/** Options for {@link bool}. */
+export type BoolOptions = BaseOptions<boolean>;
+/**
+ * Validates a boolean environment variable.
+ * Accepts: `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off` (case-insensitive).
+ *
+ * @example
+ * ```ts
+ * DEBUG: bool({ default: false })
+ * ```
+ */
+export declare function bool(opts: BoolOptions & {
+    default: boolean;
+}): ValidatorSpec<boolean>;
+export declare function bool(opts?: BoolOptions): ValidatorSpec<boolean>;
+/** Options for {@link url}. */
+export interface UrlOptions extends BaseOptions<string> {
+    /** Restrict allowed URL protocols, e.g. `['https:']`. */
+    protocols?: readonly string[];
+}
+/**
+ * Validates that an environment variable is a valid URL.
+ *
+ * @example
+ * ```ts
+ * DATABASE_URL: url({ protocols: ['postgresql:', 'postgres:'] })
+ * ```
+ */
+export declare function url(opts: UrlOptions & {
+    default: string;
+}): ValidatorSpec<string>;
+export declare function url(opts?: UrlOptions): ValidatorSpec<string>;
+/** Options for {@link port}. */
+export type PortOptions = BaseOptions<number>;
+/**
+ * Validates a TCP/UDP port number (1–65535).
+ *
+ * @example
+ * ```ts
+ * PORT: port({ default: 3000 })
+ * ```
+ */
+export declare function port(opts: PortOptions & {
+    default: number;
+}): ValidatorSpec<number>;
+export declare function port(opts?: PortOptions): ValidatorSpec<number>;
+/** Options for {@link email}. */
+export type EmailOptions = BaseOptions<string>;
+/**
+ * Validates an email address environment variable.
+ *
+ * @example
+ * ```ts
+ * SMTP_FROM: email({ default: 'no-reply@example.com' })
+ * ```
+ */
+export declare function email(opts: EmailOptions & {
+    default: string;
+}): ValidatorSpec<string>;
+export declare function email(opts?: EmailOptions): ValidatorSpec<string>;
+/** Options for {@link json}. */
+export interface JsonOptions<T> extends BaseOptions<T> {
+}
+/**
+ * Parses a JSON-encoded environment variable into type `T`.
+ * The generic parameter should match the expected shape of the parsed value.
+ *
+ * @example
+ * ```ts
+ * FEATURE_FLAGS: json<{ betaUsers: boolean }>()
+ * ```
+ */
+export declare function json<T = unknown>(opts: JsonOptions<T> & {
+    default: T;
+}): ValidatorSpec<T>;
+export declare function json<T = unknown>(opts?: JsonOptions<T>): ValidatorSpec<T>;
+/**
+ * Validates that a variable matches one value from a const-asserted tuple.
+ * Provides a narrower return type than `str({ choices })`.
+ *
+ * @example
+ * ```ts
+ * LOG_LEVEL: enums(['debug', 'info', 'warn', 'error'] as const)
+ * ```
+ */
+export declare function enums<const T extends readonly string[]>(values: T, opts?: BaseOptions<T[number]>): ValidatorSpec<T[number]>;
+//# sourceMappingURL=validators.d.ts.map

package/dist/types/validators.d.ts.map

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

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "envguard-ts",
+  "version": "1.0.0",
+  "description": "Zero-dependency TypeScript environment variable validator with compile-time type inference",
+  "keywords": [
+    "env",
+    "environment",
+    "validation",
+    "typescript",
+    "zod",
+    "dotenv",
+    "config",
+    "schema",
+    "type-safe"
+  ],
+  "author": "Mehulbirare",
+  "license": "MIT",
+  "homepage": "https://github.com/Mehulbirare/envguard-ts#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mehulbirare/envguard-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Mehulbirare/envguard-ts/issues"
+  },
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
+    }
+  },
+  "bin": {
+    "envx": "./bin/envx.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:esm": "tsc -p tsconfig.esm.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:types": "tsc -p tsconfig.types.json",
+    "test": "jest",
+    "test:coverage": "jest --coverage",
+    "test:watch": "jest --watch",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run test:coverage",
+    "size": "npx bundlesize"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.14.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.4",
+    "typescript": "^5.5.2"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "sideEffects": false,
+  "bundlesize": [
+    {
+      "path": "./dist/esm/index.js",
+      "maxSize": "3 kB"
+    }
+  ]
+}