v2: Support Zod Mini; Remove dotenv & dotenv-expand; Improve Logging & Functionality (#189)

* v2: initial refactoring

* Support both Zod and Zod Mini (WIP)

* Fully support Zod Mini & Zod v4

* Fix linting issues, clean up documentation, etc.

* Delete local.ts

Signed-off-by: Noah Tigner <46695778+noahtigner@users.noreply.github.com>

* Remove dotenv & dotenv-expand (WIP)

* Fix deep variable expansion

* Simplify variable expansion logic & reorganize tests

* Update README to reflect support for Zod v4/v4/mini

* Update validateEnvVars docstring

* Removed dotenv & dotenv-expand!

* Update documentation to clarify inspiration from dotenv-expand

* Add CHANGELOG.md; correct which versions of Zod are supported

* Update README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Signed-off-by: Noah Tigner <46695778+noahtigner@users.noreply.github.com>

* Clarify CHANGELOG, Align devDeps and peerDeps, improve test efficacy

* Update expandValue to prevent infinite loops with circular env var references

* Simplify & Document Regex Patterns

---------

Signed-off-by: Noah Tigner <46695778+noahtigner@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: noahtigner

.gitignore

@@ -2,3 +2,5 @@ node_modules/
 dist/
 coverage/
 local.js
+local.ts
+.git

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+## 2.0.0
+
+- Add support for Zod Mini
+- Remove dotenv and dotenv-expand peer dependencies
+- Made the `envPath` parameter optional. If not provided, no file is read, and only `process.env` is validated
+- Improve how field `.meta` is logged (`title`, `description`, and `examples` supported)
+- Improve how `schema` is validated and field types are allowed/disallowed
+- Refactor the codebase to improve readability and maintainability
+- Update README with new instructions and examples
+- Updated tests to cover new functionality and edge cases
+
+## 1.0.1
+
+- Update eslint to v9, apply new linting rules, and bump several dev dependencies
+
+## 1.0.0
+
+- Update the tests to reflect new zod v4 error message
+- Update methodology of passing description data into a schema
+- Update method for pulling descriptions off of schema fields
+- Remove some @ts-expect-error comments that were no longer necessary
+- Update check for types allowed. (`_def` has been moved here)
+
+## < 1.0.0
+
+Please see the [commit history](https://github.com/noahtigner/validate-env-vars/commits/main/)

README.md

@@ -13,7 +13,11 @@
 </div>
 
 <p align="center">
-    A lightweight utility to check the presence and validity of environment variables, as specified by a Zod schema
+    A lightweight utility for checking the presence and validity of environment variables, as specified by a Zod schema.
+</p>
+
+<p align="center">
+   validate-env-vars supports Zod v4 and Zod Mini!
 </p>
 
 # Installation
@@ -31,50 +35,41 @@ npm install validate-env-vars --save-dev
 ```javascript
 #!/usr/bin/env node
 
-import validateEnvVars, {
-	envEnum,
-	envString,
-	envNonEmptyString,
-} from 'validate-env-vars';
+import validateEnvVars from 'validate-env-vars';
+import { z } from 'zod';
 
-const envSchema = envObject({
-	NODE_ENV: envEnum(['development', 'production', 'test']),
-	API_BASE: envString().url(),
-	GITHUB_USERNAME: envNonEmptyString(),
+const envSchema = z.object({
+	NODE_ENV: z.enum(['development', 'production', 'test']),
+	API_BASE: z.url(),
+	GITHUB_USERNAME: z.string().min(1),
 });
 
 validateEnvVars({ schema: envSchema });
 ```
 
-You may use the predefined `env*` functions, or create your own using Zod
-
 ---
 
 ### Programmatically check an .env.production file against a Zod schema:
 
 ```javascript
-import validateEnvVars, {
-    envEnum,
-    envString,
-    envNonEmptyString,
-} from 'validate-env-vars';
-
-const envSchema = envObject({
-	NODE_ENV: envEnum(['development', 'production', 'test']),
-	API_BASE: envString().url(),
-	GITHUB_USERNAME: envNonEmptyString(),
+import validateEnvVars from 'validate-env-vars';
+import { z } from 'zod';
+
+const envSchema = z.object({
+	NODE_ENV: z.enum(['development', 'production', 'test']),
+	API_BASE: z.url(),
+	GITHUB_USERNAME: z.string().min(1),
 });
 
-const prefilight() => {
-    try {
-        validateEnvVars({ schema: envSchema, envPath: '.env.production' })
-        // ... other code
-    }
-    catch (error) {
-        console.error(error);
-        // ... other code
-    }
-}
+const preflight = () => {
+	try {
+		validateEnvVars({ schema: envSchema, envPath: '.env.production' });
+		// ... other code
+	} catch (error) {
+		console.error(error);
+		// ... other code
+	}
+};
 ```
 
 ---
@@ -84,16 +79,12 @@ const prefilight() => {
 1. Define a Zod schema in a .ts file at the root of your project
 
 ```javascript
-import validateEnvVars, {
-    envEnum,
-    envString,
-    envNonEmptyString,
-} from 'validate-env-vars';
-
-const envSchema = envObject({
-	NODE_ENV: envEnum(['development', 'production', 'test']),
-	VITE_API_BASE: envString().url(),
-	VITE_GITHUB_USERNAME: envNonEmptyString(),
+import { z } from 'zod';
+
+const envSchema = z.object({
+	NODE_ENV: z.enum(['development', 'production', 'test']),
+	VITE_API_BASE: z.url(),
+	VITE_GITHUB_USERNAME: z.string().min(1),
 });
 
 // make the type of the environment variables available globally
@@ -136,15 +127,40 @@ interface ImportMeta {
 
 4. Add your schema configuration file to your tsconfig's `include`
 
-# Tips:
-
-- If you don't have a `.env` file, you can pass an empty file. This is useful for testing and CI/CD environments, where environment variables may be set programmatically.
-
 # Config Options
 
 | Option                   | Type        | Description                                                    | Default |
 | ------------------------ | ----------- | -------------------------------------------------------------- | ------- |
-| `schema`                 | `EnvObject` | The schema to validate against                                 |         |
-| `envPath` (optional)     | `string`    | The path to the .env file                                      | `.env`  |
+| `schema`                 | `EnvObject` | The schema to validate against (must use string-based types)   |         |
+| `envPath` (optional)     | `string`    | The path to the .env file                                      |         |
 | `exitOnError` (optional) | `boolean`   | Whether to exit the process or throw if validation fails       | `false` |
 | `logVars` (optional)     | `boolean`   | Whether to output successfully parsed variables to the console | `true`  |
+
+**Note:** The `schema` must be a `z.object()` whose fields use string-based types—such as `z.string()`, `z.enum()`, `z.literal()`, or compositions like union/optional of these types. You may also use any Zod string refinements and formats (e.g., `.min()`, `.max()`, `.url()`, `.email()`, `.regex()`, `.refine()`, etc.) to validate and transform string values. Environment variables are always read as strings.
+
+# Schema Recipes
+
+Since environment variables are always read as strings, you'll need to validate and transform them appropriately. Here are some common patterns:
+
+```javascript
+const envNonEmptyString = () =>
+	z
+		.string()
+		.min(1, { message: 'Variable cannot be empty' })
+		.refine((val) => val !== 'undefined', {
+			message: "Variable cannot equal 'undefined'",
+		});
+
+// Integer from string
+const envInteger = () =>
+	z.string().regex(/^-?\d+$/, {
+		message: 'Variable must be a valid integer',
+	});
+
+// Boolean from string
+const envBoolean = () => z.enum(['true', 'false']);
+
+// Comma-separated list
+const envList = () =>
+	z.string().transform((val) => val.split(',').map((s) => s.trim()));
+```

__tests__/.env.test

@@ -1,5 +1,9 @@
-EXPECTED_1=one
-EXPECTED_2=true
-EXPECTED_3=1
-EXPANDED_1=${EXPECTED_1}
-EXPANDED_2=${SOME_NON_EXISTENT_ENV_VAR}
+TEST_EXPECTED_1=one
+TEST_EXPECTED_NUMBER=1
+TEST_EXPECTED_INT=42
+TEST_EXPECTED_URL=http://example.com
+TEST_EXPANDED_1=${TEST_EXPECTED_1}
+TEST_EXPANDED_2=${SOME_NON_EXISTENT_ENV_VAR}
+TEST_EXPANDED_3=${TEST_EXPANDED_1}+${TEST_EXPECTED_2}
+TEST_EXPECTED_2=true
+TEST_EXPANDED_WITH_FALLBACK=${SOME_NON_EXISTENT_ENV_VAR:-fallback}

__tests__/compatibility.test.ts

@@ -0,0 +1,43 @@
+import { z as zodClassic } from 'zod';
+import * as zodMini from 'zod/mini';
+
+import { validate } from '../src/validateInput';
+
+const zodClassicSchema = zodClassic.object({
+	VAR1: zodClassic.string(),
+	VAR2: zodClassic.enum(['value1', 'value2']),
+});
+
+const zodMiniSchema = zodMini.object({
+	VAR1: zodMini.string(),
+	VAR2: zodMini.enum(['value1', 'value2']),
+});
+
+describe('Library is compatible with both Zod v4 and Zod Mini', () => {
+	it('validates schemas', () => {
+		const data = { VAR1: 'test', VAR2: 'value1' };
+		expect(() =>
+			validate({ schema: zodClassicSchema, vars: data, logVars: true })
+		).not.toThrow();
+		expect(() =>
+			validate({ schema: zodMiniSchema, vars: data, logVars: true })
+		).not.toThrow();
+	});
+	it('throws for invalid schemas', () => {
+		const invalidData = { VAR1: 'test', VAR2: 'invalidValue' };
+		expect(() =>
+			validate({
+				schema: zodClassicSchema,
+				vars: invalidData,
+				logVars: true,
+			})
+		).toThrow();
+		expect(() =>
+			validate({
+				schema: zodMiniSchema,
+				vars: invalidData,
+				logVars: true,
+			})
+		).toThrow();
+	});
+});