envguard-ts 1.0.0

package/dist/cjs/core.js.map

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

package/dist/cjs/errors.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvValidationError = void 0;
+/**
+ * Thrown when one or more environment variables fail validation.
+ * Provides a structured list of field errors and a formatted human-readable message.
+ */
+class EnvValidationError extends Error {
+    constructor(errors) {
+        const lines = [
+            '',
+            '  ✖ Environment validation failed',
+            '',
+            ...errors.map((e) => `  ${e.field}: ${e.message}` +
+                (e.received !== undefined ? ` (received: ${JSON.stringify(e.received)})` : '')),
+            '',
+        ];
+        super(lines.join('\n'));
+        this.name = 'EnvValidationError';
+        this.errors = errors;
+        // Maintain proper prototype chain in transpiled CJS
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.EnvValidationError = EnvValidationError;
+//# sourceMappingURL=errors.js.map

package/dist/cjs/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":";;;AAUA;;;GAGG;AACH,MAAa,kBAAmB,SAAQ,KAAK;IAI3C,YAAY,MAAoB;QAC9B,MAAM,KAAK,GAAG;YACZ,EAAE;YACF,4CAA4C;YAC5C,EAAE;YACF,GAAG,MAAM,CAAC,GAAG,CACX,CAAC,CAAC,EAAE,EAAE,CACJ,UAAU,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,OAAO,EAAE;gBACrC,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAC1F;YACD,EAAE;SACH,CAAA;QACD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,oDAAoD;QACpD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACnD,CAAC;CACF;AAtBD,gDAsBC"}

package/dist/cjs/index.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * envx — Zero-dependency TypeScript env variable validator
+ * @module envx
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvValidationError = exports.enums = exports.json = exports.email = exports.port = exports.url = exports.bool = exports.num = exports.str = exports.validateEnvFile = exports.generateExample = exports.createEnv = void 0;
+// Core
+var core_js_1 = require("./core.js");
+Object.defineProperty(exports, "createEnv", { enumerable: true, get: function () { return core_js_1.createEnv; } });
+Object.defineProperty(exports, "generateExample", { enumerable: true, get: function () { return core_js_1.generateExample; } });
+Object.defineProperty(exports, "validateEnvFile", { enumerable: true, get: function () { return core_js_1.validateEnvFile; } });
+// Validators
+var validators_js_1 = require("./validators.js");
+Object.defineProperty(exports, "str", { enumerable: true, get: function () { return validators_js_1.str; } });
+Object.defineProperty(exports, "num", { enumerable: true, get: function () { return validators_js_1.num; } });
+Object.defineProperty(exports, "bool", { enumerable: true, get: function () { return validators_js_1.bool; } });
+Object.defineProperty(exports, "url", { enumerable: true, get: function () { return validators_js_1.url; } });
+Object.defineProperty(exports, "port", { enumerable: true, get: function () { return validators_js_1.port; } });
+Object.defineProperty(exports, "email", { enumerable: true, get: function () { return validators_js_1.email; } });
+Object.defineProperty(exports, "json", { enumerable: true, get: function () { return validators_js_1.json; } });
+Object.defineProperty(exports, "enums", { enumerable: true, get: function () { return validators_js_1.enums; } });
+// Errors
+var errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "EnvValidationError", { enumerable: true, get: function () { return errors_js_1.EnvValidationError; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAAA;;;GAGG;;;AAEH,OAAO;AACP,qCAAuE;AAA9D,oGAAA,SAAS,OAAA;AAAE,0GAAA,eAAe,OAAA;AAAE,0GAAA,eAAe,OAAA;AAGpD,aAAa;AACb,iDAA+E;AAAtE,oGAAA,GAAG,OAAA;AAAE,oGAAA,GAAG,OAAA;AAAE,qGAAA,IAAI,OAAA;AAAE,oGAAA,GAAG,OAAA;AAAE,qGAAA,IAAI,OAAA;AAAE,sGAAA,KAAK,OAAA;AAAE,qGAAA,IAAI,OAAA;AAAE,sGAAA,KAAK,OAAA;AAatD,SAAS;AACT,yCAAgD;AAAvC,+GAAA,kBAAkB,OAAA"}

package/dist/cjs/validators.js

@@ -0,0 +1,134 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.str = str;
+exports.num = num;
+exports.bool = bool;
+exports.url = url;
+exports.port = port;
+exports.email = email;
+exports.json = json;
+exports.enums = enums;
+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,
+    };
+}
+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 });
+}
+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']);
+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 });
+}
+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 });
+}
+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,}$/;
+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 });
+}
+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)
+ * ```
+ */
+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/cjs/validators.js.map

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

package/dist/esm/cli.js

@@ -0,0 +1,151 @@
+/**
+ * envx CLI — validate and generate .env files
+ *
+ * Commands:
+ *   envx check [--env <file>] [--schema <file>]
+ *   envx generate [--schema <file>] [--out <file>]
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { validateEnvFile, generateExample } from './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 import(resolved);
+    // 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 = 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 = 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/esm/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAA;AAC7B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAG5D,8EAA8E;AAC9E,mCAAmC;AACnC,8EAA8E;AAE9E,SAAS,YAAY,CAAC,OAAe;IACnC,MAAM,MAAM,GAA2B,EAAE,CAAA;IACzC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAA;QAC3B,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAQ;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAA;QAC/B,IAAI,KAAK,KAAK,CAAC,CAAC;YAAE,SAAQ;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA;QACvC,IAAI,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;QACxC,2BAA2B;QAC3B,IACE,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC9C,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,EAC9C,CAAC;YACD,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAA;QAC5B,CAAC;QACD,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;IACrB,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,SAAS,SAAS,CAAC,IAAc;IAC/B,MAAM,IAAI,GAAkC,EAAE,CAAA;IAC9C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,CAAA;QACnB,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9C,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;YACxB,MAAM,IAAI,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;YACxB,IAAI,IAAI,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;gBACjD,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;gBAChB,CAAC,EAAE,CAAA;YACL,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAA;YAClB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,8EAA8E;AAC9E,WAAW;AACX,8EAA8E;AAE9E,KAAK,UAAU,UAAU,CAAC,UAAkB;IAC1C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,CAAC,CAAA;IACxD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,CAAC,KAAK,CAAC,iCAAiC,QAAQ,EAAE,CAAC,CAAA;QAC1D,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IACD,mEAAmE;IACnE,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,CAAA;IAClC,sEAAsE;IACtE,MAAM,MAAM,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,MAAM,IAAI,GAAG,CAAW,CAAA;IAC3D,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QAClD,OAAO,CAAC,KAAK,CAAC,wDAAwD,CAAC,CAAA;QACvE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IACD,OAAO,MAAM,CAAA;AACf,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,IAAmC;IACzD,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;IACtE,MAAM,UAAU,GAAG,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAA;IAE7F,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAA;IACpD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC,KAAK,CAAC,8BAA8B,OAAO,EAAE,CAAC,CAAA;QACtD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACjB,CAAC;IAED,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,CAAA;IAC3C,MAAM,MAAM,GAAG,YAAY,CAAC,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;IAC7D,MAAM,MAAM,GAAG,eAAe,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAE9C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,CAAC,GAAG,CAAC,aAAa,OAAO,kBAAkB,CAAC,CAAA;QACnD,OAAM;IACR,CAAC;IAED,OAAO,CAAC,KAAK,CAAC,aAAa,OAAO,QAAQ,MAAM,CAAC,MAAM,qBAAqB,CAAC,CAAA;IAC7E,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,MAAM,QAAQ,GACZ,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAA;QACjG,OAAO,CAAC,KAAK,CAAC,aAAa,GAAG,CAAC,KAAK,YAAY,GAAG,CAAC,OAAO,GAAG,QAAQ,EAAE,CAAC,CAAA;IAC3E,CAAC;IACD,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,CAAA;IACjB,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,IAAmC;IAC5D,MAAM,UAAU,GAAG,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,oBAAoB,CAAA;IAC7F,MAAM,OAAO,GAAG,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,cAAc,CAAA;IAE9E,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,UAAU,CAAC,CAAA;IAC3C,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,CAAA;IACvC,EAAE,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,CAAA;IACvE,OAAO,CAAC,GAAG,CAAC,uBAAuB,OAAO,SAAS,CAAC,CAAA;AACtD,CAAC;AAED,SAAS,SAAS;IAChB,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;CAgBb,CAAC,CAAA;AACF,CAAC;AAED,8EAA8E;AAC9E,cAAc;AACd,8EAA8E;AAE9E,KAAK,UAAU,IAAI;IACjB,MAAM,CAAC,EAAE,AAAD,EAAG,OAAO,EAAE,GAAG,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAA;IAC3C,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,CAAA;IAE5B,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QAC7B,SAAS,EAAE,CAAA;QACX,OAAM;IACR,CAAC;IAED,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,OAAO;YACV,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAA;YACpB,MAAK;QACP,KAAK,UAAU;YACb,MAAM,WAAW,CAAC,IAAI,CAAC,CAAA;YACvB,MAAK;QACP;YACE,OAAO,CAAC,KAAK,CAAC,2BAA2B,OAAO,EAAE,CAAC,CAAA;YACnD,SAAS,EAAE,CAAA;YACX,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;IACnB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,0BAA0B,EAAE,GAAG,CAAC,CAAA;IAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AACjB,CAAC,CAAC,CAAA"}

package/dist/esm/core.js

@@ -0,0 +1,129 @@
+import { EnvValidationError } from './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 }),
+ *   },
+ * })
+ * ```
+ */
+export 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 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))
+ * ```
+ */
+export 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.
+ */
+export 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

package/dist/esm/core.js.map

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

package/dist/esm/errors.js

@@ -0,0 +1,22 @@
+/**
+ * Thrown when one or more environment variables fail validation.
+ * Provides a structured list of field errors and a formatted human-readable message.
+ */
+export class EnvValidationError extends Error {
+    constructor(errors) {
+        const lines = [
+            '',
+            '  ✖ Environment validation failed',
+            '',
+            ...errors.map((e) => `  ${e.field}: ${e.message}` +
+                (e.received !== undefined ? ` (received: ${JSON.stringify(e.received)})` : '')),
+            '',
+        ];
+        super(lines.join('\n'));
+        this.name = 'EnvValidationError';
+        this.errors = errors;
+        // Maintain proper prototype chain in transpiled CJS
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/esm/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAUA;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAI3C,YAAY,MAAoB;QAC9B,MAAM,KAAK,GAAG;YACZ,EAAE;YACF,4CAA4C;YAC5C,EAAE;YACF,GAAG,MAAM,CAAC,GAAG,CACX,CAAC,CAAC,EAAE,EAAE,CACJ,UAAU,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC,OAAO,EAAE;gBACrC,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAC1F;YACD,EAAE;SACH,CAAA;QACD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;QACpB,oDAAoD;QACpD,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAA;IACnD,CAAC;CACF"}

package/dist/esm/index.js

@@ -0,0 +1,11 @@
+/**
+ * envx — Zero-dependency TypeScript env variable validator
+ * @module envx
+ */
+// Core
+export { createEnv, generateExample, validateEnvFile } from './core.js';
+// Validators
+export { str, num, bool, url, port, email, json, enums } from './validators.js';
+// Errors
+export { EnvValidationError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO;AACP,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAGvE,aAAa;AACb,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAA;AAa/E,SAAS;AACT,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA"}