zod-envkit 1.0.0

package/.env.example

@@ -0,0 +1,8 @@
+# Runtime mode
+NODE_ENV=development
+
+# HTTP port
+PORT=3000
+
+# Postgres connection string
+DATABASE_URL=postgresql://user:pass@localhost:5432/db

package/ENV.md

@@ -0,0 +1,7 @@
+# Environment variables
+
+|      Key       |  Required  |                  Example                   |         Description          |
+| :------------: | :--------: | :----------------------------------------: | :--------------------------: |
+|    NODE_ENV    |    yes     |                development                 |         Runtime mode         |
+|      PORT      |    yes     |                    3000                    |          HTTP port           |
+|  DATABASE_URL  |    yes     |  postgresql://user:pass@localhost:5432/db  |  Postgres connection string  |

package/README.md

@@ -0,0 +1,207 @@
+Type-safe environment variable validation and documentation using Zod.
+
+`zod-envkit` is a small library and CLI tool that helps you:
+- validate `process.env`
+- get **fully typed environment variables**
+- automatically generate `.env.example`
+- generate environment documentation (`ENV.md`)
+- treat environment variables as an **explicit contract**, not guesswork
+
+No cloud. No magic. Just code.
+
+---
+
+## Why
+
+The problem:
+- `process.env` is just `string | undefined`
+- environment errors often appear **only at runtime**
+- `.env.example` and documentation are often outdated or missing
+
+The solution:
+- define your environment **once**
+- get:
+  - early validation
+  - TypeScript types
+  - up-to-date `.env.example`
+  - up-to-date documentation
+
+---
+
+## Installation
+
+```bash
+npm install zod-envkit
+````
+
+or
+
+```bash
+pnpm add zod-envkit
+```
+
+---
+
+## Quick start
+
+```ts
+import "dotenv/config";
+import { z } from "zod";
+import { loadEnv, formatZodError } from "zod-envkit";
+
+const EnvSchema = z.object({
+  NODE_ENV: z.enum(["development", "test", "production"]),
+  PORT: z.coerce.number().int().min(1).max(65535),
+  DATABASE_URL: z.string().url()
+});
+
+const result = loadEnv(EnvSchema);
+
+if (!result.ok) {
+  console.error("Invalid environment:\n" + formatZodError(result.error));
+  process.exit(1);
+}
+
+export const env = result.env;
+```
+
+Now:
+
+* `env.PORT` is a **number**
+* `env.DATABASE_URL` is a **string**
+* TypeScript knows everything at compile time
+
+---
+
+## CLI: generate `.env.example` and `ENV.md`
+
+### 1️⃣ Create `env.meta.json` in your project root
+
+```json
+{
+  "NODE_ENV": {
+    "description": "Application runtime environment",
+    "example": "development"
+  },
+  "PORT": {
+    "description": "HTTP server port",
+    "example": "3000"
+  },
+  "DATABASE_URL": {
+    "description": "PostgreSQL connection string",
+    "example": "postgresql://user:pass@localhost:5432/db"
+  }
+}
+```
+
+---
+
+### 2️⃣ Run the CLI
+
+```bash
+npx zod-envkit
+```
+
+Or locally during development:
+
+```bash
+node dist/cli.js
+```
+
+---
+
+### 3️⃣ Output
+
+#### `.env.example`
+
+```env
+# Application runtime environment
+NODE_ENV=development
+
+# HTTP server port
+PORT=3000
+
+# PostgreSQL connection string
+DATABASE_URL=postgresql://user:pass@localhost:5432/db
+```
+
+#### `ENV.md`
+
+```md
+# Environment variables
+
+| Key | Required | Example | Description |
+|---|---:|---|---|
+| NODE_ENV | yes | development | Application runtime environment |
+| PORT | yes | 3000 | HTTP server port |
+| DATABASE_URL | yes | postgresql://... | PostgreSQL connection string |
+```
+
+---
+
+## CLI options
+
+```bash
+zod-envkit --help
+```
+
+```bash
+zod-envkit \
+  --config env.meta.json \
+  --out-example .env.example \
+  --out-docs ENV.md
+```
+
+---
+
+## Why not just dotenv?
+
+`dotenv`:
+
+* ❌ no validation
+* ❌ no types
+* ❌ no documentation
+
+`zod-envkit`:
+
+* ✅ validation
+* ✅ TypeScript inference
+* ✅ documentation
+* ✅ CLI tooling
+
+They work **great together**.
+
+---
+
+## Design decisions
+
+* ❌ does not try to automatically parse Zod schemas
+* ❌ does not couple to any framework
+* ✅ explicit configuration over magic
+* ✅ small, predictable API
+* ✅ library + CLI, both optional
+
+---
+
+## Roadmap
+
+* [ ] schema ↔ meta consistency checks
+* [ ] `zod-envkit check` (validation only)
+* [ ] grouping / sections in docs
+* [ ] prettier, human-friendly error output
+* [ ] JSON schema export
+
+---
+
+## Who is this for?
+
+* backend and fullstack projects
+* Node.js / Bun services
+* CI/CD pipelines
+* teams that treat env as part of their contract
+
+---
+
+## License
+
+MIT

package/dist/cli.cjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_node_fs = __toESM(require("fs"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_commander = require("commander");
+
+// src/generate.ts
+function strLen(s) {
+  return s.length;
+}
+function padCenter(text, width) {
+  const t = text ?? "";
+  const diff = width - strLen(t);
+  if (diff <= 0) return t;
+  const left = Math.floor(diff / 2);
+  const right = diff - left;
+  return " ".repeat(left) + t + " ".repeat(right);
+}
+function makeDivider(width, align) {
+  if (width < 3) width = 3;
+  if (align === "center") return ":" + "-".repeat(width - 2) + ":";
+  if (align === "right") return "-".repeat(width - 1) + ":";
+  return "-".repeat(width);
+}
+function generateEnvExample(meta) {
+  const lines = [];
+  for (const [key, m] of Object.entries(meta)) {
+    if (m.description) lines.push(`# ${m.description}`);
+    lines.push(`${key}=${m.example ?? ""}`);
+    lines.push("");
+  }
+  return lines.join("\n").trim() + "\n";
+}
+function generateEnvDocs(meta) {
+  const headers = ["Key", "Required", "Example", "Description"];
+  const rows = Object.entries(meta).map(([key, m]) => {
+    const req = m.required === false ? "no" : "yes";
+    return {
+      Key: key,
+      Required: req,
+      Example: m.example ?? "",
+      Description: m.description ?? ""
+    };
+  });
+  const widths = {
+    Key: headers[0].length,
+    Required: headers[1].length,
+    Example: headers[2].length,
+    Description: headers[3].length
+  };
+  for (const r of rows) {
+    widths.Key = Math.max(widths.Key, strLen(r.Key));
+    widths.Required = Math.max(widths.Required, strLen(r.Required));
+    widths.Example = Math.max(widths.Example, strLen(r.Example));
+    widths.Description = Math.max(widths.Description, strLen(r.Description));
+  }
+  widths.Key += 2;
+  widths.Required += 2;
+  widths.Example += 2;
+  widths.Description += 2;
+  const headerLine = `| ${padCenter(headers[0], widths.Key)} | ${padCenter(headers[1], widths.Required)} | ${padCenter(headers[2], widths.Example)} | ${padCenter(headers[3], widths.Description)} |`;
+  const dividerLine = `| ${makeDivider(widths.Key, "center")} | ${makeDivider(widths.Required, "center")} | ${makeDivider(widths.Example, "center")} | ${makeDivider(widths.Description, "center")} |`;
+  const bodyLines = rows.map((r) => {
+    return `| ${padCenter(r.Key, widths.Key)} | ${padCenter(r.Required, widths.Required)} | ${padCenter(r.Example, widths.Example)} | ${padCenter(r.Description, widths.Description)} |`;
+  });
+  return [
+    `# Environment variables`,
+    ``,
+    headerLine,
+    dividerLine,
+    ...bodyLines,
+    ``
+  ].join("\n");
+}
+
+// src/cli.ts
+var program = new import_commander.Command();
+program.name("zod-envkit").description("Generate .env.example and ENV.md from env.meta.json").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--out-example <file>", "Output file for .env.example", ".env.example").option("--out-docs <file>", "Output file for docs", "ENV.md").action((opts) => {
+  const configPath = import_node_path.default.resolve(process.cwd(), opts.config);
+  const raw = import_node_fs.default.readFileSync(configPath, "utf8");
+  const meta = JSON.parse(raw);
+  import_node_fs.default.writeFileSync(opts.outExample, generateEnvExample(meta), "utf8");
+  import_node_fs.default.writeFileSync(opts.outDocs, generateEnvDocs(meta), "utf8");
+  console.log(`Generated: ${opts.outExample}, ${opts.outDocs}`);
+});
+program.parse();

package/dist/cli.d.cts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import fs from "fs";
+import path from "path";
+import { Command } from "commander";
+
+// src/generate.ts
+function strLen(s) {
+  return s.length;
+}
+function padCenter(text, width) {
+  const t = text ?? "";
+  const diff = width - strLen(t);
+  if (diff <= 0) return t;
+  const left = Math.floor(diff / 2);
+  const right = diff - left;
+  return " ".repeat(left) + t + " ".repeat(right);
+}
+function makeDivider(width, align) {
+  if (width < 3) width = 3;
+  if (align === "center") return ":" + "-".repeat(width - 2) + ":";
+  if (align === "right") return "-".repeat(width - 1) + ":";
+  return "-".repeat(width);
+}
+function generateEnvExample(meta) {
+  const lines = [];
+  for (const [key, m] of Object.entries(meta)) {
+    if (m.description) lines.push(`# ${m.description}`);
+    lines.push(`${key}=${m.example ?? ""}`);
+    lines.push("");
+  }
+  return lines.join("\n").trim() + "\n";
+}
+function generateEnvDocs(meta) {
+  const headers = ["Key", "Required", "Example", "Description"];
+  const rows = Object.entries(meta).map(([key, m]) => {
+    const req = m.required === false ? "no" : "yes";
+    return {
+      Key: key,
+      Required: req,
+      Example: m.example ?? "",
+      Description: m.description ?? ""
+    };
+  });
+  const widths = {
+    Key: headers[0].length,
+    Required: headers[1].length,
+    Example: headers[2].length,
+    Description: headers[3].length
+  };
+  for (const r of rows) {
+    widths.Key = Math.max(widths.Key, strLen(r.Key));
+    widths.Required = Math.max(widths.Required, strLen(r.Required));
+    widths.Example = Math.max(widths.Example, strLen(r.Example));
+    widths.Description = Math.max(widths.Description, strLen(r.Description));
+  }
+  widths.Key += 2;
+  widths.Required += 2;
+  widths.Example += 2;
+  widths.Description += 2;
+  const headerLine = `| ${padCenter(headers[0], widths.Key)} | ${padCenter(headers[1], widths.Required)} | ${padCenter(headers[2], widths.Example)} | ${padCenter(headers[3], widths.Description)} |`;
+  const dividerLine = `| ${makeDivider(widths.Key, "center")} | ${makeDivider(widths.Required, "center")} | ${makeDivider(widths.Example, "center")} | ${makeDivider(widths.Description, "center")} |`;
+  const bodyLines = rows.map((r) => {
+    return `| ${padCenter(r.Key, widths.Key)} | ${padCenter(r.Required, widths.Required)} | ${padCenter(r.Example, widths.Example)} | ${padCenter(r.Description, widths.Description)} |`;
+  });
+  return [
+    `# Environment variables`,
+    ``,
+    headerLine,
+    dividerLine,
+    ...bodyLines,
+    ``
+  ].join("\n");
+}
+
+// src/cli.ts
+var program = new Command();
+program.name("zod-envkit").description("Generate .env.example and ENV.md from env.meta.json").option("-c, --config <file>", "Path to env meta json", "env.meta.json").option("--out-example <file>", "Output file for .env.example", ".env.example").option("--out-docs <file>", "Output file for docs", "ENV.md").action((opts) => {
+  const configPath = path.resolve(process.cwd(), opts.config);
+  const raw = fs.readFileSync(configPath, "utf8");
+  const meta = JSON.parse(raw);
+  fs.writeFileSync(opts.outExample, generateEnvExample(meta), "utf8");
+  fs.writeFileSync(opts.outDocs, generateEnvDocs(meta), "utf8");
+  console.log(`Generated: ${opts.outExample}, ${opts.outDocs}`);
+});
+program.parse();

package/dist/index.cjs

@@ -0,0 +1,40 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  formatZodError: () => formatZodError,
+  loadEnv: () => loadEnv
+});
+module.exports = __toCommonJS(index_exports);
+function loadEnv(schema, opts) {
+  const parsed = schema.safeParse(process.env);
+  if (parsed.success) return { ok: true, env: parsed.data };
+  if (opts?.throwOnError) throw parsed.error;
+  return { ok: false, error: parsed.error };
+}
+function formatZodError(err) {
+  return err.issues.map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  formatZodError,
+  loadEnv
+});

package/dist/index.d.cts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+type EnvResult<T extends z.ZodTypeAny> = z.infer<T>;
+declare function loadEnv<T extends z.ZodTypeAny>(schema: T, opts?: {
+    throwOnError?: boolean;
+}): {
+    ok: true;
+    env: z.infer<T>;
+} | {
+    ok: false;
+    error: z.ZodError;
+};
+declare function formatZodError(err: z.ZodError): string;
+
+export { type EnvResult, formatZodError, loadEnv };

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import { z } from 'zod';
+
+type EnvResult<T extends z.ZodTypeAny> = z.infer<T>;
+declare function loadEnv<T extends z.ZodTypeAny>(schema: T, opts?: {
+    throwOnError?: boolean;
+}): {
+    ok: true;
+    env: z.infer<T>;
+} | {
+    ok: false;
+    error: z.ZodError;
+};
+declare function formatZodError(err: z.ZodError): string;
+
+export { type EnvResult, formatZodError, loadEnv };

package/dist/index.js

@@ -0,0 +1,14 @@
+// src/index.ts
+function loadEnv(schema, opts) {
+  const parsed = schema.safeParse(process.env);
+  if (parsed.success) return { ok: true, env: parsed.data };
+  if (opts?.throwOnError) throw parsed.error;
+  return { ok: false, error: parsed.error };
+}
+function formatZodError(err) {
+  return err.issues.map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+}
+export {
+  formatZodError,
+  loadEnv
+};

package/env.meta.json

@@ -0,0 +1,5 @@
+{
+  "NODE_ENV": { "description": "Runtime mode", "example": "development" },
+  "PORT": { "description": "HTTP port", "example": "3000" },
+  "DATABASE_URL": { "description": "Postgres connection string", "example": "postgresql://user:pass@localhost:5432/db" }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "zod-envkit",
+  "version": "1.0.0",
+  "description": "Validate environment variables with Zod and generate .env.example",
+  "type": "module",
+
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+
+  "bin": {
+    "zod-envkit": "dist/cli.js"
+  },
+
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts src/cli.ts --watch --dts",
+    "test": "vitest run",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+
+  "keywords": ["env", "dotenv", "zod", "validation", "cli"],
+  "author": "",
+  "license": "MIT",
+
+  "dependencies": {
+    "commander": "^13.1.0",
+    "dotenv": "^17.2.3",
+    "zod": "^4.3.6"
+  },
+
+  "devDependencies": {
+    "@types/node": "^25.0.10",
+    "eslint": "^9.39.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { generateEnvDocs, generateEnvExample, type EnvMeta } from "./generate.js";
+
+const program = new Command();
+
+program
+  .name("zod-envkit")
+  .description("Generate .env.example and ENV.md from env.meta.json")
+  .option("-c, --config <file>", "Path to env meta json", "env.meta.json")
+  .option("--out-example <file>", "Output file for .env.example", ".env.example")
+  .option("--out-docs <file>", "Output file for docs", "ENV.md")
+  .action((opts) => {
+    const configPath = path.resolve(process.cwd(), opts.config);
+    const raw = fs.readFileSync(configPath, "utf8");
+    const meta: EnvMeta = JSON.parse(raw);
+
+    fs.writeFileSync(opts.outExample, generateEnvExample(meta), "utf8");
+    fs.writeFileSync(opts.outDocs, generateEnvDocs(meta), "utf8");
+
+    console.log(`Generated: ${opts.outExample}, ${opts.outDocs}`);
+  });
+
+program.parse();

package/src/generate.ts

@@ -0,0 +1,130 @@
+// src/generate.ts
+
+export type EnvMeta = Record<
+  string,
+  {
+    description?: string;
+    example?: string;
+    required?: boolean; // default: true
+  }
+>;
+
+function strLen(s: string): number {
+  return s.length;
+}
+
+function padCenter(text: string, width: number): string {
+  const t = text ?? "";
+  const diff = width - strLen(t);
+  if (diff <= 0) return t;
+
+  const left = Math.floor(diff / 2);
+  const right = diff - left;
+  return " ".repeat(left) + t + " ".repeat(right);
+}
+
+function padRight(text: string, width: number): string {
+  const t = text ?? "";
+  const diff = width - strLen(t);
+  if (diff <= 0) return t;
+  return t + " ".repeat(diff);
+}
+
+function makeDivider(width: number, align: "left" | "center" | "right"): string {
+  // Markdown alignment:
+  // left   : --- 
+  // center : :---:
+  // right  : ---:
+  if (width < 3) width = 3;
+
+  if (align === "center") return ":" + "-".repeat(width - 2) + ":";
+  if (align === "right") return "-".repeat(width - 1) + ":";
+  return "-".repeat(width);
+}
+
+/**
+ * Генерит .env.example красиво:
+ * - комментарий с description
+ * - KEY=example
+ */
+export function generateEnvExample(meta: EnvMeta): string {
+  const lines: string[] = [];
+
+  for (const [key, m] of Object.entries(meta)) {
+    if (m.description) lines.push(`# ${m.description}`);
+    lines.push(`${key}=${m.example ?? ""}`);
+    lines.push("");
+  }
+
+  return lines.join("\n").trim() + "\n";
+}
+
+/**
+ * Генерит ENV.md как ровную таблицу:
+ * - вычисляет ширины колонок по максимальной длине
+ * - паддит значения пробелами
+ * - ставит выравнивание :---: чтобы центрировалось в Markdown
+ */
+export function generateEnvDocs(meta: EnvMeta): string {
+  const headers = ["Key", "Required", "Example", "Description"] as const;
+
+  const rows = Object.entries(meta).map(([key, m]) => {
+    const req = m.required === false ? "no" : "yes";
+    return {
+      Key: key,
+      Required: req,
+      Example: m.example ?? "",
+      Description: m.description ?? "",
+    };
+  });
+
+  const widths = {
+    Key: headers[0].length,
+    Required: headers[1].length,
+    Example: headers[2].length,
+    Description: headers[3].length,
+  };
+
+  for (const r of rows) {
+    widths.Key = Math.max(widths.Key, strLen(r.Key));
+    widths.Required = Math.max(widths.Required, strLen(r.Required));
+    widths.Example = Math.max(widths.Example, strLen(r.Example));
+    widths.Description = Math.max(widths.Description, strLen(r.Description));
+  }
+
+  widths.Key += 2;
+  widths.Required += 2;
+  widths.Example += 2;
+  widths.Description += 2;
+
+  const headerLine =
+    `| ${padCenter(headers[0], widths.Key)} ` +
+    `| ${padCenter(headers[1], widths.Required)} ` +
+    `| ${padCenter(headers[2], widths.Example)} ` +
+    `| ${padCenter(headers[3], widths.Description)} |`;
+
+  const dividerLine =
+    `| ${makeDivider(widths.Key, "center")} ` +
+    `| ${makeDivider(widths.Required, "center")} ` +
+    `| ${makeDivider(widths.Example, "center")} ` +
+    `| ${makeDivider(widths.Description, "center")} |`;
+
+  const bodyLines = rows.map((r) => {
+    return (
+      `| ${padCenter(r.Key, widths.Key)} ` +
+      `| ${padCenter(r.Required, widths.Required)} ` +
+      `| ${padCenter(r.Example, widths.Example)} ` +
+      `| ${padCenter(r.Description, widths.Description)} |`
+    );
+  });
+
+
+  return [
+    `# Environment variables`,
+    ``,
+    headerLine,
+    dividerLine,
+    ...bodyLines,
+    ``,
+  ].join("\n");
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+import { z } from "zod";
+
+export type EnvResult<T extends z.ZodTypeAny> = z.infer<T>;
+
+export function loadEnv<T extends z.ZodTypeAny>(
+  schema: T,
+  opts?: { throwOnError?: boolean }
+):
+  | { ok: true; env: z.infer<T> }
+  | { ok: false; error: z.ZodError } {
+  const parsed = schema.safeParse(process.env);
+
+  if (parsed.success) return { ok: true, env: parsed.data };
+
+  if (opts?.throwOnError) throw parsed.error;
+  return { ok: false, error: parsed.error };
+}
+
+export function formatZodError(err: z.ZodError): string {
+  return err.issues
+    .map((i) => `- ${i.path.join(".") || "(root)"}: ${i.message}`)
+    .join("\n");
+}

package/test/basic.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { loadEnv } from "../src/index";
+
+describe("loadEnv", () => {
+  it("parses valid env", () => {
+    process.env.PORT = "3000";
+    const schema = z.object({ PORT: z.coerce.number() });
+
+    const res = loadEnv(schema);
+    expect(res.ok).toBe(true);
+
+    if (res.ok) expect(res.env.PORT).toBe(3000);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "Bundler",
+    "strict": true,
+    "declaration": true,
+    "skipLibCheck": true
+  }
+}