envzod 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+## 1.0.0 — Initial Release
+
+- `createEnv(schema, options?)` — validate environment variables against a Zod schema
+- Full TypeScript inference — types flow from schema automatically
+- Pretty box-style error output with field names, messages, and received values
+- `verbose` mode — logs success summary in development
+- `onError` hook — custom error handling (Sentry, logging, etc.)
+- `source` option — custom env source instead of `process.env`
+- Dual CJS + ESM build with TypeScript declarations

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Sridhar-C-25
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,199 @@
+# envzod
+
+Universal, type-safe environment variable validation powered by [Zod](https://zod.dev).
+
+Works with **Next.js, Express, Fastify, Remix, Bun** — any Node.js project.
+
+---
+
+## Why
+
+- `process.env` values are all `string | undefined` — no types, no validation
+- Errors surface at runtime deep in your app instead of at startup
+- `zod-env` validates your env at boot and gives you a **fully typed object** — no casting needed
+
+---
+
+## Install
+
+```bash
+npm install envzod
+# or
+pnpm add envzod
+# or
+yarn add envzod
+```
+
+> `zod` is a peer dependency and is installed automatically (npm 7+, pnpm, yarn).
+
+---
+
+## Basic Usage
+
+```ts
+// env.ts
+import { createEnv } from 'envzod'
+import { z } from 'zod'
+
+export const env = createEnv({
+  DATABASE_URL: z.string().url(),
+  PORT: z.coerce.number().default(3000),
+  NODE_ENV: z.enum(['development', 'test', 'production']),
+  JWT_SECRET: z.string().min(32),
+})
+
+// Fully typed — no casting needed
+env.PORT         // number
+env.DATABASE_URL // string
+env.NODE_ENV     // "development" | "test" | "production"
+```
+
+---
+
+## Error Output
+
+When validation fails, `zod-env` prints a clear, readable error and throws:
+
+```
+╔════════════════════════════════════════════╗
+║  zod-env: Invalid Environment             ║
+╚════════════════════════════════════════════╝
+
+  ✗ DATABASE_URL
+    Invalid url
+    Got: "localhost/mydb"
+
+  ✗ JWT_SECRET
+    String must contain at least 32 character(s)
+    Got: "tooshort"
+
+  ✗ NODE_ENV
+    Invalid enum value. Expected 'development' | 'test' | 'production'
+    Got: "prod"
+
+  Fix the above and restart your server.
+```
+
+---
+
+## Options
+
+```ts
+const env = createEnv(schema, {
+  // Custom env source. Defaults to process.env
+  source: myCustomObject,
+
+  // Log "✅ zod-env: N variables validated" on success (good for dev)
+  verbose: true,
+
+  // Called with structured errors before throwing — use for Sentry, logging, etc.
+  onError: (errors) => {
+    Sentry.captureException(new Error('Invalid env'), { extra: { errors } })
+  },
+})
+```
+
+### `onError` signature
+
+```ts
+type EnvValidationError = {
+  field: string
+  message: string
+  received: string | undefined
+}
+```
+
+---
+
+## Framework Examples
+
+### Next.js (App Router)
+
+```ts
+// src/env.ts
+import { createEnv } from 'envzod'
+import { z } from 'zod'
+
+export const env = createEnv({
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  NEXT_PUBLIC_API_URL: z.string().url(),
+}, {
+  verbose: process.env.NODE_ENV === 'development',
+})
+```
+
+### Express
+
+```ts
+// src/env.ts
+import { createEnv } from 'envzod'
+import { z } from 'zod'
+
+export const env = createEnv({
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+}, {
+  verbose: process.env.NODE_ENV === 'development',
+})
+
+// app.ts
+import { env } from './env'
+app.listen(env.PORT)
+```
+
+### Bun
+
+```ts
+// env.ts
+import { createEnv } from 'envzod'
+import { z } from 'zod'
+
+export const env = createEnv({
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32),
+}, {
+  source: Bun.env,
+  verbose: Bun.env.NODE_ENV === 'development',
+})
+```
+
+---
+
+## TypeScript
+
+`zod-env` uses the `InferEnv<T>` utility type to derive the return type from your schema. No manual type annotations needed.
+
+```ts
+import type { InferEnv } from 'envzod'
+import { z } from 'zod'
+
+const schema = {
+  PORT: z.coerce.number(),
+  NODE_ENV: z.enum(['development', 'production']),
+}
+
+type Env = InferEnv<typeof schema>
+// { PORT: number; NODE_ENV: "development" | "production" }
+```
+
+---
+
+## vs t3-env
+
+| Feature | zod-env | t3-env |
+|---|---|---|
+| Framework | Universal | Next.js focused |
+| Setup | `createEnv(schema)` | Separate client/server schemas |
+| Dependencies | zod only | Next.js types + more |
+| Bundle | CJS + ESM | ESM only |
+| Error output | Pretty box | Zod default |
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,25 @@
+import { ZodTypeAny, z } from 'zod';
+
+/** A record of field names to Zod types */
+type EnvSchema = Record<string, ZodTypeAny>;
+/** Infer the output type of an env schema */
+type InferEnv<T extends EnvSchema> = {
+    [K in keyof T]: z.infer<T[K]>;
+};
+interface EnvOptions<T extends EnvSchema> {
+    /** Custom env source. Defaults to process.env */
+    source?: Record<string, string | undefined>;
+    /** Log a success summary table in development. Defaults to false */
+    verbose?: boolean;
+    /** Called with formatted error string before throwing. Use for custom logging/alerting */
+    onError?: (errors: EnvValidationError[]) => void;
+}
+interface EnvValidationError {
+    field: string;
+    message: string;
+    received: string | undefined;
+}
+
+declare function createEnv<T extends EnvSchema>(schema: T, options?: EnvOptions<T>): InferEnv<T>;
+
+export { type EnvOptions, type EnvSchema, type EnvValidationError, type InferEnv, createEnv };

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { ZodTypeAny, z } from 'zod';
+
+/** A record of field names to Zod types */
+type EnvSchema = Record<string, ZodTypeAny>;
+/** Infer the output type of an env schema */
+type InferEnv<T extends EnvSchema> = {
+    [K in keyof T]: z.infer<T[K]>;
+};
+interface EnvOptions<T extends EnvSchema> {
+    /** Custom env source. Defaults to process.env */
+    source?: Record<string, string | undefined>;
+    /** Log a success summary table in development. Defaults to false */
+    verbose?: boolean;
+    /** Called with formatted error string before throwing. Use for custom logging/alerting */
+    onError?: (errors: EnvValidationError[]) => void;
+}
+interface EnvValidationError {
+    field: string;
+    message: string;
+    received: string | undefined;
+}
+
+declare function createEnv<T extends EnvSchema>(schema: T, options?: EnvOptions<T>): InferEnv<T>;
+
+export { type EnvOptions, type EnvSchema, type EnvValidationError, type InferEnv, createEnv };

package/dist/index.js

@@ -0,0 +1,70 @@
+'use strict';
+
+var zod = require('zod');
+
+// src/format.ts
+var BOX_WIDTH = 44;
+function pad(text, width) {
+  return text + " ".repeat(Math.max(0, width - text.length));
+}
+function formatErrors(errors) {
+  const lines = [];
+  const title = "  zod-env: Invalid Environment         ";
+  lines.push(`\u2554${"\u2550".repeat(BOX_WIDTH)}\u2557`);
+  lines.push(`\u2551${pad(title, BOX_WIDTH)}\u2551`);
+  lines.push(`\u255A${"\u2550".repeat(BOX_WIDTH)}\u255D`);
+  lines.push("");
+  for (const err of errors) {
+    lines.push(`  \u2717 ${err.field}`);
+    lines.push(`    ${err.message}`);
+    if (err.received !== void 0) {
+      lines.push(`    Got: "${err.received}"`);
+    }
+    lines.push("");
+  }
+  lines.push("  Fix the above and restart your server.");
+  return lines.join("\n");
+}
+function formatSuccess(count) {
+  return `\u2705 zod-env: ${count} variable${count === 1 ? "" : "s"} validated`;
+}
+function validate(schema, source) {
+  const shape = {};
+  for (const key of Object.keys(schema)) {
+    shape[key] = schema[key];
+  }
+  const zodObject = zod.z.object(shape);
+  const result = zodObject.safeParse(source);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  const errors = result.error.issues.map((issue) => {
+    const field = issue.path[0]?.toString() ?? "unknown";
+    return {
+      field,
+      message: issue.message,
+      received: source[field]
+    };
+  });
+  return { success: false, errors };
+}
+
+// src/index.ts
+function createEnv(schema, options) {
+  const source = options?.source ?? process.env;
+  const result = validate(schema, source);
+  if (!result.success) {
+    const formatted = formatErrors(result.errors);
+    console.error(formatted);
+    options?.onError?.(result.errors);
+    throw new Error("zod-env: environment validation failed");
+  }
+  if (options?.verbose) {
+    console.log(formatSuccess(Object.keys(schema).length));
+  }
+  return result.data;
+}
+
+exports.createEnv = createEnv;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.mjs

@@ -0,0 +1,68 @@
+import { z } from 'zod';
+
+// src/format.ts
+var BOX_WIDTH = 44;
+function pad(text, width) {
+  return text + " ".repeat(Math.max(0, width - text.length));
+}
+function formatErrors(errors) {
+  const lines = [];
+  const title = "  zod-env: Invalid Environment         ";
+  lines.push(`\u2554${"\u2550".repeat(BOX_WIDTH)}\u2557`);
+  lines.push(`\u2551${pad(title, BOX_WIDTH)}\u2551`);
+  lines.push(`\u255A${"\u2550".repeat(BOX_WIDTH)}\u255D`);
+  lines.push("");
+  for (const err of errors) {
+    lines.push(`  \u2717 ${err.field}`);
+    lines.push(`    ${err.message}`);
+    if (err.received !== void 0) {
+      lines.push(`    Got: "${err.received}"`);
+    }
+    lines.push("");
+  }
+  lines.push("  Fix the above and restart your server.");
+  return lines.join("\n");
+}
+function formatSuccess(count) {
+  return `\u2705 zod-env: ${count} variable${count === 1 ? "" : "s"} validated`;
+}
+function validate(schema, source) {
+  const shape = {};
+  for (const key of Object.keys(schema)) {
+    shape[key] = schema[key];
+  }
+  const zodObject = z.object(shape);
+  const result = zodObject.safeParse(source);
+  if (result.success) {
+    return { success: true, data: result.data };
+  }
+  const errors = result.error.issues.map((issue) => {
+    const field = issue.path[0]?.toString() ?? "unknown";
+    return {
+      field,
+      message: issue.message,
+      received: source[field]
+    };
+  });
+  return { success: false, errors };
+}
+
+// src/index.ts
+function createEnv(schema, options) {
+  const source = options?.source ?? process.env;
+  const result = validate(schema, source);
+  if (!result.success) {
+    const formatted = formatErrors(result.errors);
+    console.error(formatted);
+    options?.onError?.(result.errors);
+    throw new Error("zod-env: environment validation failed");
+  }
+  if (options?.verbose) {
+    console.log(formatSuccess(Object.keys(schema).length));
+  }
+  return result.data;
+}
+
+export { createEnv };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "envzod",
+  "version": "1.0.0",
+  "description": "Universal, type-safe environment variable validation powered by Zod. Zero config, works everywhere.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.mjs",
+    "dist/index.d.ts",
+    "dist/index.d.mts",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck && npm test && npm run build"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "peerDependencies": {
+    "zod": ">=3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "keywords": [
+    "zod",
+    "env",
+    "environment",
+    "validation",
+    "typescript",
+    "nodejs",
+    "nextjs",
+    "process.env",
+    "env-validation",
+    "type-safe",
+    "dotenv",
+    "schema"
+  ],
+  "author": "Sridhar-C-25",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Sridhar-C-25/zod-env"
+  },
+  "bugs": {
+    "url": "https://github.com/Sridhar-C-25/zod-env/issues"
+  },
+  "homepage": "https://github.com/Sridhar-C-25/zod-env#readme"
+}