zenvx 0.1.2 → 0.2.0

package/README.md

@@ -26,6 +26,16 @@ Standard Zod is great, but environment variables are always strings. This leads
 
 ---
 
+## Features
+
+- ✅ Type-safe environment variables
+- ✅ Smart coercion for numbers, booleans, and ports
+- ✅ Strict validation for strings, URLs, emails, JSON, enums
+- ✅ Beautiful, human-readable error reporting
+- ✅ Seamless TypeScript integration
+- ✅ `.env.example` auto-generation
+- ✅ Runtime **and** build-time validation modes
+
 ## Installation
 
 ```bash
@@ -42,7 +52,7 @@ yarn add zenvx zod
 
 Create a file (e.g., src/env.ts) and export your configuration:
 
-```javascript
+```ts
 import { defineEnv, tx } from "zenvx";
 
 export const env = defineEnv({
@@ -61,13 +71,84 @@ export const env = defineEnv({
 
 Now use it anywhere in your app:
 
-```javascript
+```ts
 import { env } from "./env";
 
 console.log(`Server running on port ${env.PORT}`);
 // TypeScript knows env.PORT is a number!
 ```
 
+## .env.example Auto-Generation
+
+zenvx can automatically generate a .env.example file from your schema — keeping your documentation always in sync.
+
+```ts
+defineEnv(
+  {
+    DATABASE_URL: tx.url(),
+    PORT: tx.port().default(3000),
+    DEBUG: tx.bool(),
+  },
+  {
+    generateExample: true,
+  },
+);
+```
+
+This produces:
+
+```
+# Example environment variables
+# Copy this file to .env and fill in the values
+
+DATABASE_URL=  #string
+PORT=3000  # number
+DEBUG_MODE=  # boolean
+
+```
+
+No more forgotten or outdated .env.example files.
+
+## Runtime vs Build-Time Validation
+
+Different environments need different failure behavior. zenvx supports both.
+
+### Runtime Validation (default)
+
+In runtime mode, environment variables are validated as soon as your application starts.
+
+```ts
+defineEnv(schema, { mode: "runtime" });
+```
+
+Behavior:
+
+- Environment variables are loaded and validated immediately
+- If validation fails:
+  - A formatted error message is printed to the console
+  - The process exits using process.exit(1)
+- Prevents the application from running with invalid configuration
+
+This mode ensures misconfigured environments are caught early and stop execution entirely.
+
+### Build-Time Validation
+
+IIn build-time mode, validation errors are thrown instead of terminating the process.
+
+```ts
+defineEnv(schema, { mode: "build" });
+```
+
+Behavior:
+
+- Environment variables are validated during execution
+- If validation fails:
+  - An error is thrown
+  - process.exit() is not called
+- Allows the calling environment (bundler, test runner, or script) to handle the failure
+
+This mode avoids hard exits and lets external tooling decide how to respond to configuration errors.
+
 ## Beautiful Error Handling
 
 If your .env file is missing values or has invalid types, zenvx stops the process immediately and prints a clear message:
@@ -95,13 +176,12 @@ DATABASE_URL: Must be a valid URL
 | `tx.email()`     | Valid email address.                                               | `"admin@app.com"`    | `"admin@..."`   |
 | `tx.json()`      | Parses a JSON string into an Object.                               | `{"foo":"bar"}`      | `{foo: "bar"}`  |
 | `tx.enum([...])` | Strict allow-list.                                                 | `"PROD"`             | `"PROD"`        |
-| `tx.ip()`        | Validates IPv4 format.                                             | `"192.168.1.1"`      | `"192..."`      |
 
 ## Customizing Error Messages
 
 Every tx validator accepts an optional custom error message.
 
-```javascript
+```ts
 export const env = defineEnv({
   API_KEY: tx.string("Please provide a REAL API Key, not just numbers!"),
   PORT: tx.port("Port is invalid or out of range"),
@@ -114,7 +194,7 @@ Custom .env Path
 
 By default, zenvx looks for .env in your project root. You can change this:
 
-```javascript
+```ts
 export const env = defineEnv(
   {
     PORT: tx.port(),
@@ -129,7 +209,7 @@ export const env = defineEnv(
 
 You can mix tx helpers with standard Zod schemas if you need specific logic.
 
-```javascript
+```ts
 import { defineEnv, tx } from "zenvx";
 import { z } from "zod";
 

package/dist/index.cjs

@@ -34,7 +34,73 @@ __export(index_exports, {
   tx: () => tx
 });
 module.exports = __toCommonJS(index_exports);
-var import_zod2 = require("zod");
+
+// src/core/tx.ts
+var import_zod = require("zod");
+var SEMVER_REGEX = /^\d+\.\d+\.\d+(-[0-9A-Za-z-.]+)?$/;
+var tx = {
+  /**
+   * STRICT STRING:
+   * Rejects purely numeric strings (e.g. "12345").
+   * Good for API Keys.
+   */
+  string: (message = "Value should be text, but looks like a number.") => import_zod.z.string().trim().regex(/^(?!\d+$).+$/, { error: message }).describe("Non-numeric string"),
+  /**
+   * SMART NUMBER:
+   * Automatically converts "3000" -> 3000.
+   * Fails if the value is not a valid number (e.g. "abc").
+   */
+  number: (message = "Must be a number") => import_zod.z.coerce.number({ error: message }).finite().describe("Numeric value"),
+  /**
+   * PORT VALIDATOR:
+   * Coerces to number and ensures it is between 1 and 65535.
+   */
+  port: (message = "Must be a valid port (1\u201365535)") => import_zod.z.coerce.number({ error: message }).int().min(1).max(65535).describe("TCP/UDP port number (1\u201365535)"),
+  /**
+   * SMART BOOLEAN:
+   * Handles "true", "TRUE", "1" -> true
+   * Handles "false", "FALSE", "0" -> false
+   * Throws error on anything else.
+   */
+  bool: (message) => {
+    return import_zod.z.union([import_zod.z.string(), import_zod.z.boolean()]).transform((val, ctx) => {
+      if (typeof val === "boolean") return val;
+      const v = val.toLowerCase();
+      if (v === "true" || v === "1") return true;
+      if (v === "false" || v === "0") return false;
+      ctx.addIssue({
+        code: import_zod.z.ZodIssueCode.custom,
+        message: message || 'Must be a boolean ("true"/"false"/"1"/"0")'
+      });
+      return import_zod.z.NEVER;
+    });
+  },
+  /**
+   * URL:
+   * Strict URL checking.
+   */
+  url: (message = "Must be a valid URL (e.g. https://...)") => import_zod.z.url({ error: message }).describe("A valid URL including protocol"),
+  email: (message = "Must be a valid email address") => import_zod.z.email({ error: message }).describe("A valid email address"),
+  positiveNumber: (message = "Must be > 0") => import_zod.z.coerce.number().gt(0, { error: message }).describe("A positive number"),
+  nonEmptyString: (message = "Cannot be empty") => import_zod.z.string().trim().min(1, { error: message }).describe("A non-empty string"),
+  semver: (message = "Must be valid semver") => import_zod.z.string().regex(SEMVER_REGEX, { error: message }).describe("Semantic version (x.y.z)"),
+  path: (message = "Must be a valid path") => import_zod.z.string().trim().min(1, { error: message }).describe("Filesystem path"),
+  enum: (values, message = `Must be one of: ${values.join(", ")}`) => import_zod.z.enum(values, { error: message }).describe(`One of: ${values.join(", ")}`),
+  json: (message = "Must be valid JSON") => import_zod.z.string().transform((val, ctx) => {
+    try {
+      return JSON.parse(val);
+    } catch {
+      ctx.addIssue({
+        code: "custom",
+        error: message
+      });
+      return import_zod.z.NEVER;
+    }
+  }).describe("JSON-encoded value")
+};
+
+// src/core/define-env.ts
+var import_zod4 = require("zod");
 
 // src/loaders/dotenv.ts
 var import_dotenv = __toESM(require("dotenv"), 1);
@@ -54,23 +120,29 @@ Tip: Set { dotenv: false } if you manage environment variables yourself.`
 }
 
 // src/core/parser.ts
-var import_zod = require("zod");
-function parseEnv(schema, source) {
+var import_zod2 = require("zod");
+function parseEnv(schema, source, mode = "runtime") {
   const result = schema.safeParse(source);
   if (!result.success) {
     const issues = result.error.issues.map((i) => `\u274C ${i.path.join(".")}: ${i.message}`).join("\n");
-    throw new Error(
-      [
-        "",
-        "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
-        "\u2502  \u274C INVALID ENVIRONMENT VARIABLES DETECTED   \u2502",
-        "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
-        issues,
-        ""
-      ].join("\n")
-    );
+    const header = mode === "build" ? [
+      "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
+      "\u2502  \u274C INVALID ENVIRONMENT VARIABLES DETECTED   \u2502",
+      "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518"
+    ] : [
+      "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
+      "\u2502 \u26A0 WARNING INVALID ENVIRONMENT VARIABLES \u26A0  \u2502",
+      "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518"
+    ];
+    const box = ["", ...header, issues, ""].join("\n");
+    if (mode === "build") {
+      throw new Error(box);
+    } else {
+      console.warn(box);
+      process.exit(1);
+    }
   }
-  return result.data;
+  return result.success ? result.data : {};
 }
 
 // src/core/proxy.ts
@@ -88,84 +160,50 @@ function createTypedProxy(obj) {
   });
 }
 
-// src/index.ts
-var tx = {
-  /**
-   * STRICT STRING:
-   * Rejects purely numeric strings (e.g. "12345").
-   * Good for API Keys.
-   */
-  string: (message) => import_zod2.z.string().refine((val) => !/^\d+$/.test(val), {
-    error: message || "Value should be text, but looks like a number."
-  }),
-  /**
-   * SMART NUMBER:
-   * Automatically converts "3000" -> 3000.
-   * Fails if the value is not a valid number (e.g. "abc").
-   */
-  number: (message) => import_zod2.z.coerce.number({ error: message || "Must be a number" }),
-  /**
-   * PORT VALIDATOR:
-   * Coerces to number and ensures it is between 1 and 65535.
-   */
-  port: (message) => import_zod2.z.coerce.number().min(1).max(65535).catch((ctx) => {
-    ctx.error;
-    return -1;
-  }).refine((val) => val >= 1 && val <= 65535, {
-    error: message || "Must be a valid port (1-65535)."
-  }),
-  /**
-   * SMART BOOLEAN:
-   * Handles "true", "TRUE", "1" -> true
-   * Handles "false", "FALSE", "0" -> false
-   * Throws error on anything else.
-   */
-  bool: (message) => import_zod2.z.string().transform((val, ctx) => {
-    const v = val.toLowerCase();
-    if (v === "true" || v === "1") return true;
-    if (v === "false" || v === "0") return false;
-    ctx.addIssue({
-      code: import_zod2.z.ZodIssueCode.custom,
-      error: message || "Must be a boolean (true/false or 1/0)."
-    });
-    return import_zod2.z.NEVER;
-  }),
-  /**
-   * URL:
-   * Strict URL checking.
-   */
-  url: (message) => import_zod2.z.url({ error: message || "Must be a valid URL (e.g. https://...)" }),
-  /**
-   * EMAIL:
-   * Strict Email checking.
-   */
-  email: (message) => import_zod2.z.email({ error: message || "Must be a valid email address." }),
-  positiveNumber: (message) => import_zod2.z.coerce.number().refine((val) => val > 0, { error: message || "Must be > 0" }),
-  nonEmptyString: (message) => import_zod2.z.string().min(1, { error: message || "Cannot be empty" }),
-  semver: (message) => import_zod2.z.string().refine((val) => /^\d+\.\d+\.\d+(-[0-9A-Za-z-.]+)?$/.test(val), {
-    error: message || "Must be valid semver"
-  }),
-  path: (message) => import_zod2.z.string().min(1, { error: message || "Must be a valid path" }),
-  enum: (values, message) => import_zod2.z.string().refine((val) => values.includes(val), {
-    error: message || `Must be one of: ${values.join(", ")}`
-  }),
-  json: (message) => import_zod2.z.string().transform((val, ctx) => {
-    try {
-      return JSON.parse(val);
-    } catch {
-      ctx.addIssue({
-        code: import_zod2.z.ZodIssueCode.custom,
-        message: message || "Must be valid JSON"
-      });
-      return import_zod2.z.NEVER;
+// src/core/generate-example.ts
+var import_zod3 = require("zod");
+var import_fs2 = __toESM(require("fs"), 1);
+function getZodTypeName(schema) {
+  let type = "unknown";
+  if (schema instanceof import_zod3.ZodString) type = "string";
+  else if (schema instanceof import_zod3.ZodNumber) type = "number";
+  else if (schema instanceof import_zod3.ZodBoolean) type = "boolean";
+  return type;
+}
+function generateExample(schema, path = ".env.example") {
+  const header = [
+    "# Example environment variables",
+    "# Copy this file to .env and fill in the values",
+    ""
+  ];
+  const lines = Object.entries(schema.shape).map(([key, zodSchema]) => {
+    let placeholder = "";
+    let othertype = null;
+    let actualSchema = zodSchema;
+    if (zodSchema instanceof import_zod3.ZodOptional) actualSchema = zodSchema.unwrap();
+    if (zodSchema instanceof import_zod3.ZodDefault) {
+      actualSchema = zodSchema.def.innerType;
+      placeholder = zodSchema.def.defaultValue ?? "";
+      othertype = typeof zodSchema.def.defaultValue;
     }
-  })
-};
+    const type = getZodTypeName(actualSchema);
+    return `${key}=${placeholder ?? ""}  # ${othertype ?? type}`;
+  });
+  const content = [...header, ...lines].join("\n") + "\n";
+  import_fs2.default.writeFileSync(path, content);
+  console.log(content);
+  console.log(`\u2705 .env.example generated at ${path}`);
+}
+
+// src/core/define-env.ts
 function defineEnv(shape, options) {
   const fileEnv = loadDotEnv(options?.path);
   const merged = { ...fileEnv, ...process.env };
-  const schema = import_zod2.z.object(shape);
-  const parsed = parseEnv(schema, merged);
+  const schema = import_zod4.z.object(shape);
+  const parsed = parseEnv(schema, merged, options?.mode ?? "runtime");
+  if (options?.generateExample) {
+    generateExample(schema);
+  }
   return createTypedProxy(parsed);
 }
 // Annotate the CommonJS export names for ESM import in node:

package/dist/index.d.cts

@@ -1,8 +1,5 @@
 import { z } from 'zod';
 
-interface DefineEnvOptions {
-    path?: string;
-}
 declare const tx: {
     /**
      * STRICT STRING:
@@ -20,31 +17,35 @@ declare const tx: {
      * PORT VALIDATOR:
      * Coerces to number and ensures it is between 1 and 65535.
      */
-    port: (message?: string) => z.ZodCatch<z.ZodCoercedNumber<unknown>>;
+    port: (message?: string) => z.ZodCoercedNumber<unknown>;
     /**
      * SMART BOOLEAN:
      * Handles "true", "TRUE", "1" -> true
      * Handles "false", "FALSE", "0" -> false
      * Throws error on anything else.
      */
-    bool: (message?: string) => z.ZodPipe<z.ZodString, z.ZodTransform<boolean, string>>;
+    bool: (message?: string) => z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>, z.ZodTransform<boolean, string | boolean>>;
     /**
      * URL:
      * Strict URL checking.
      */
     url: (message?: string) => z.ZodURL;
-    /**
-     * EMAIL:
-     * Strict Email checking.
-     */
     email: (message?: string) => z.ZodEmail;
     positiveNumber: (message?: string) => z.ZodCoercedNumber<unknown>;
     nonEmptyString: (message?: string) => z.ZodString;
     semver: (message?: string) => z.ZodString;
     path: (message?: string) => z.ZodString;
-    enum: <T extends readonly [string, ...string[]]>(values: T, message?: string) => z.ZodString;
-    json: (message?: string) => z.ZodPipe<z.ZodString, z.ZodTransform<any, string>>;
+    enum: <T extends readonly [string, ...string[]]>(values: T, message?: string) => z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>;
+    json: <T = unknown>(message?: string) => z.ZodPipe<z.ZodString, z.ZodTransform<Awaited<T>, string>>;
 };
+
+type ValidationMode = "runtime" | "build";
+interface DefineEnvOptions {
+    path?: string;
+    mode?: ValidationMode;
+    generateExample?: boolean;
+}
+
 declare function defineEnv<T extends z.ZodRawShape>(shape: T, options?: DefineEnvOptions): { [K in keyof T]: z.core.output<T[K]>; };
 
-export { defineEnv, tx };
+export { type DefineEnvOptions, defineEnv, tx };

package/dist/index.d.ts

@@ -1,8 +1,5 @@
 import { z } from 'zod';
 
-interface DefineEnvOptions {
-    path?: string;
-}
 declare const tx: {
     /**
      * STRICT STRING:
@@ -20,31 +17,35 @@ declare const tx: {
      * PORT VALIDATOR:
      * Coerces to number and ensures it is between 1 and 65535.
      */
-    port: (message?: string) => z.ZodCatch<z.ZodCoercedNumber<unknown>>;
+    port: (message?: string) => z.ZodCoercedNumber<unknown>;
     /**
      * SMART BOOLEAN:
      * Handles "true", "TRUE", "1" -> true
      * Handles "false", "FALSE", "0" -> false
      * Throws error on anything else.
      */
-    bool: (message?: string) => z.ZodPipe<z.ZodString, z.ZodTransform<boolean, string>>;
+    bool: (message?: string) => z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodBoolean]>, z.ZodTransform<boolean, string | boolean>>;
     /**
      * URL:
      * Strict URL checking.
      */
     url: (message?: string) => z.ZodURL;
-    /**
-     * EMAIL:
-     * Strict Email checking.
-     */
     email: (message?: string) => z.ZodEmail;
     positiveNumber: (message?: string) => z.ZodCoercedNumber<unknown>;
     nonEmptyString: (message?: string) => z.ZodString;
     semver: (message?: string) => z.ZodString;
     path: (message?: string) => z.ZodString;
-    enum: <T extends readonly [string, ...string[]]>(values: T, message?: string) => z.ZodString;
-    json: (message?: string) => z.ZodPipe<z.ZodString, z.ZodTransform<any, string>>;
+    enum: <T extends readonly [string, ...string[]]>(values: T, message?: string) => z.ZodEnum<{ [k_1 in T[number]]: k_1; } extends infer T_1 ? { [k in keyof T_1]: T_1[k]; } : never>;
+    json: <T = unknown>(message?: string) => z.ZodPipe<z.ZodString, z.ZodTransform<Awaited<T>, string>>;
 };
+
+type ValidationMode = "runtime" | "build";
+interface DefineEnvOptions {
+    path?: string;
+    mode?: ValidationMode;
+    generateExample?: boolean;
+}
+
 declare function defineEnv<T extends z.ZodRawShape>(shape: T, options?: DefineEnvOptions): { [K in keyof T]: z.core.output<T[K]>; };
 
-export { defineEnv, tx };
+export { type DefineEnvOptions, defineEnv, tx };

package/dist/index.js

@@ -1,5 +1,69 @@
-// src/index.ts
-import { z as z2 } from "zod";
+// src/core/tx.ts
+import { z } from "zod";
+var SEMVER_REGEX = /^\d+\.\d+\.\d+(-[0-9A-Za-z-.]+)?$/;
+var tx = {
+  /**
+   * STRICT STRING:
+   * Rejects purely numeric strings (e.g. "12345").
+   * Good for API Keys.
+   */
+  string: (message = "Value should be text, but looks like a number.") => z.string().trim().regex(/^(?!\d+$).+$/, { error: message }).describe("Non-numeric string"),
+  /**
+   * SMART NUMBER:
+   * Automatically converts "3000" -> 3000.
+   * Fails if the value is not a valid number (e.g. "abc").
+   */
+  number: (message = "Must be a number") => z.coerce.number({ error: message }).finite().describe("Numeric value"),
+  /**
+   * PORT VALIDATOR:
+   * Coerces to number and ensures it is between 1 and 65535.
+   */
+  port: (message = "Must be a valid port (1\u201365535)") => z.coerce.number({ error: message }).int().min(1).max(65535).describe("TCP/UDP port number (1\u201365535)"),
+  /**
+   * SMART BOOLEAN:
+   * Handles "true", "TRUE", "1" -> true
+   * Handles "false", "FALSE", "0" -> false
+   * Throws error on anything else.
+   */
+  bool: (message) => {
+    return z.union([z.string(), z.boolean()]).transform((val, ctx) => {
+      if (typeof val === "boolean") return val;
+      const v = val.toLowerCase();
+      if (v === "true" || v === "1") return true;
+      if (v === "false" || v === "0") return false;
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: message || 'Must be a boolean ("true"/"false"/"1"/"0")'
+      });
+      return z.NEVER;
+    });
+  },
+  /**
+   * URL:
+   * Strict URL checking.
+   */
+  url: (message = "Must be a valid URL (e.g. https://...)") => z.url({ error: message }).describe("A valid URL including protocol"),
+  email: (message = "Must be a valid email address") => z.email({ error: message }).describe("A valid email address"),
+  positiveNumber: (message = "Must be > 0") => z.coerce.number().gt(0, { error: message }).describe("A positive number"),
+  nonEmptyString: (message = "Cannot be empty") => z.string().trim().min(1, { error: message }).describe("A non-empty string"),
+  semver: (message = "Must be valid semver") => z.string().regex(SEMVER_REGEX, { error: message }).describe("Semantic version (x.y.z)"),
+  path: (message = "Must be a valid path") => z.string().trim().min(1, { error: message }).describe("Filesystem path"),
+  enum: (values, message = `Must be one of: ${values.join(", ")}`) => z.enum(values, { error: message }).describe(`One of: ${values.join(", ")}`),
+  json: (message = "Must be valid JSON") => z.string().transform((val, ctx) => {
+    try {
+      return JSON.parse(val);
+    } catch {
+      ctx.addIssue({
+        code: "custom",
+        error: message
+      });
+      return z.NEVER;
+    }
+  }).describe("JSON-encoded value")
+};
+
+// src/core/define-env.ts
+import { z as z3 } from "zod";
 
 // src/loaders/dotenv.ts
 import dotenv from "dotenv";
@@ -20,22 +84,28 @@ Tip: Set { dotenv: false } if you manage environment variables yourself.`
 
 // src/core/parser.ts
 import "zod";
-function parseEnv(schema, source) {
+function parseEnv(schema, source, mode = "runtime") {
   const result = schema.safeParse(source);
   if (!result.success) {
     const issues = result.error.issues.map((i) => `\u274C ${i.path.join(".")}: ${i.message}`).join("\n");
-    throw new Error(
-      [
-        "",
-        "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
-        "\u2502  \u274C INVALID ENVIRONMENT VARIABLES DETECTED   \u2502",
-        "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
-        issues,
-        ""
-      ].join("\n")
-    );
+    const header = mode === "build" ? [
+      "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
+      "\u2502  \u274C INVALID ENVIRONMENT VARIABLES DETECTED   \u2502",
+      "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518"
+    ] : [
+      "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
+      "\u2502 \u26A0 WARNING INVALID ENVIRONMENT VARIABLES \u26A0  \u2502",
+      "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518"
+    ];
+    const box = ["", ...header, issues, ""].join("\n");
+    if (mode === "build") {
+      throw new Error(box);
+    } else {
+      console.warn(box);
+      process.exit(1);
+    }
   }
-  return result.data;
+  return result.success ? result.data : {};
 }
 
 // src/core/proxy.ts
@@ -53,84 +123,56 @@ function createTypedProxy(obj) {
   });
 }
 
-// src/index.ts
-var tx = {
-  /**
-   * STRICT STRING:
-   * Rejects purely numeric strings (e.g. "12345").
-   * Good for API Keys.
-   */
-  string: (message) => z2.string().refine((val) => !/^\d+$/.test(val), {
-    error: message || "Value should be text, but looks like a number."
-  }),
-  /**
-   * SMART NUMBER:
-   * Automatically converts "3000" -> 3000.
-   * Fails if the value is not a valid number (e.g. "abc").
-   */
-  number: (message) => z2.coerce.number({ error: message || "Must be a number" }),
-  /**
-   * PORT VALIDATOR:
-   * Coerces to number and ensures it is between 1 and 65535.
-   */
-  port: (message) => z2.coerce.number().min(1).max(65535).catch((ctx) => {
-    ctx.error;
-    return -1;
-  }).refine((val) => val >= 1 && val <= 65535, {
-    error: message || "Must be a valid port (1-65535)."
-  }),
-  /**
-   * SMART BOOLEAN:
-   * Handles "true", "TRUE", "1" -> true
-   * Handles "false", "FALSE", "0" -> false
-   * Throws error on anything else.
-   */
-  bool: (message) => z2.string().transform((val, ctx) => {
-    const v = val.toLowerCase();
-    if (v === "true" || v === "1") return true;
-    if (v === "false" || v === "0") return false;
-    ctx.addIssue({
-      code: z2.ZodIssueCode.custom,
-      error: message || "Must be a boolean (true/false or 1/0)."
-    });
-    return z2.NEVER;
-  }),
-  /**
-   * URL:
-   * Strict URL checking.
-   */
-  url: (message) => z2.url({ error: message || "Must be a valid URL (e.g. https://...)" }),
-  /**
-   * EMAIL:
-   * Strict Email checking.
-   */
-  email: (message) => z2.email({ error: message || "Must be a valid email address." }),
-  positiveNumber: (message) => z2.coerce.number().refine((val) => val > 0, { error: message || "Must be > 0" }),
-  nonEmptyString: (message) => z2.string().min(1, { error: message || "Cannot be empty" }),
-  semver: (message) => z2.string().refine((val) => /^\d+\.\d+\.\d+(-[0-9A-Za-z-.]+)?$/.test(val), {
-    error: message || "Must be valid semver"
-  }),
-  path: (message) => z2.string().min(1, { error: message || "Must be a valid path" }),
-  enum: (values, message) => z2.string().refine((val) => values.includes(val), {
-    error: message || `Must be one of: ${values.join(", ")}`
-  }),
-  json: (message) => z2.string().transform((val, ctx) => {
-    try {
-      return JSON.parse(val);
-    } catch {
-      ctx.addIssue({
-        code: z2.ZodIssueCode.custom,
-        message: message || "Must be valid JSON"
-      });
-      return z2.NEVER;
+// src/core/generate-example.ts
+import {
+  ZodDefault,
+  ZodOptional,
+  ZodString,
+  ZodNumber,
+  ZodBoolean
+} from "zod";
+import fs2 from "fs";
+function getZodTypeName(schema) {
+  let type = "unknown";
+  if (schema instanceof ZodString) type = "string";
+  else if (schema instanceof ZodNumber) type = "number";
+  else if (schema instanceof ZodBoolean) type = "boolean";
+  return type;
+}
+function generateExample(schema, path = ".env.example") {
+  const header = [
+    "# Example environment variables",
+    "# Copy this file to .env and fill in the values",
+    ""
+  ];
+  const lines = Object.entries(schema.shape).map(([key, zodSchema]) => {
+    let placeholder = "";
+    let othertype = null;
+    let actualSchema = zodSchema;
+    if (zodSchema instanceof ZodOptional) actualSchema = zodSchema.unwrap();
+    if (zodSchema instanceof ZodDefault) {
+      actualSchema = zodSchema.def.innerType;
+      placeholder = zodSchema.def.defaultValue ?? "";
+      othertype = typeof zodSchema.def.defaultValue;
     }
-  })
-};
+    const type = getZodTypeName(actualSchema);
+    return `${key}=${placeholder ?? ""}  # ${othertype ?? type}`;
+  });
+  const content = [...header, ...lines].join("\n") + "\n";
+  fs2.writeFileSync(path, content);
+  console.log(content);
+  console.log(`\u2705 .env.example generated at ${path}`);
+}
+
+// src/core/define-env.ts
 function defineEnv(shape, options) {
   const fileEnv = loadDotEnv(options?.path);
   const merged = { ...fileEnv, ...process.env };
-  const schema = z2.object(shape);
-  const parsed = parseEnv(schema, merged);
+  const schema = z3.object(shape);
+  const parsed = parseEnv(schema, merged, options?.mode ?? "runtime");
+  if (options?.generateExample) {
+    generateExample(schema);
+  }
   return createTypedProxy(parsed);
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zenvx",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",