@arthur-lobo/zod-env 1.0.0

package/README.md

@@ -0,0 +1,121 @@
+# Zod Env
+
+A TypeScript library for loading and validating environment variables using [Zod](https://zod.dev/), providing strong and safe type validation for environment configurations.
+
+## Installation
+
+```bash
+npm install @arthur-lobo/zod-env
+```
+
+## Description
+
+`ZodEnv` allows you to define Zod schemas to validate environment variables, ensuring their values are in the correct format and providing default values when necessary. It supports both synchronous and asynchronous operations, and allow you to define how `.env` must be loaded.
+
+## Basic Usage
+
+### Synchronous Class: `ZodEnv`
+
+```typescript
+import { z } from 'zod';
+import { ZodEnv } from '@arthur-lobo/zod-env';
+
+const schema = z.object({
+  PORT: z.coerce.number().default(3000),
+  DATABASE_URL: z.string(),
+  DEBUG: z.coerce.boolean().default(false),
+});
+
+const env = new ZodEnv({
+  schema,
+  getEnv: () => process.env, // or any function that returns an object with the variables like `import.meta.env` when using vite to build your frontend
+});
+
+// Access validated values
+console.log(env.get('PORT')); // 3000 (or the value of process.env.PORT if defined)
+console.log(env.get('DATABASE_URL')); // validated string
+```
+
+### Asynchronous Class: `AsyncZodEnv`
+
+```typescript
+import { z } from 'zod';
+import { AsyncZodEnv } from '@arthur-lobo/zod-env';
+
+const schema = z.object({
+  API_KEY: z.string(),
+  TIMEOUT: z.coerce.number().default(5000),
+});
+
+const env = new AsyncZodEnv({
+  schema,
+  getEnv: async () => {
+    await someAsyncOperation();
+    return process.env;
+  },
+});
+
+// Access validated values asynchronously
+const apiKey = await env.get('API_KEY');
+const timeout = await env.get('TIMEOUT');
+```
+
+### Loading .env File
+
+You can automatically load a `.env` file using Node.js's `loadEnv` function:
+
+```typescript
+import { loadEnvFile } from 'node:process';
+
+const env = new ZodEnv({
+  schema: z.object({
+    SECRET_KEY: z.string(),
+  }),
+  loadEnv: loadEnvFile, // Loads the .env file
+  getEnv: () => process.env,
+});
+
+console.log(env.get('SECRET_KEY')); // Validated value from .env
+```
+
+For asynchronous operations:
+
+```typescript
+const env = new AsyncZodEnv({
+  schema: z.object({
+    SECRET_KEY: z.string(),
+  }),
+  loadEnv: async () => loadEnvFile(), // Loads .env asynchronously
+  getEnv: async () => process.env,
+});
+```
+
+## Schema Examples
+
+```typescript
+import { z } from 'zod';
+
+// Basic schema with default values
+const basicSchema = z.object({
+  PORT: z.coerce.number().default(3000),
+  HOST: z.string().default('localhost'),
+  DEBUG: z.coerce.boolean().default(false),
+});
+
+// Schema with custom validations
+const advancedSchema = z.object({
+  DATABASE_URL: z.string().url(),
+  JWT_SECRET: z.string().min(32, 'JWT secret must be at least 32 characters'),
+  MAX_CONNECTIONS: z.coerce.number().min(1).max(100),
+  ALLOWED_ORIGINS: z.string().transform(str => str.split(',')).pipe(z.array(z.string().url())),
+});
+```
+
+## Benefits
+
+- **Strong Type Validation**: Uses Zod to ensure environment variables are in the correct format.
+- **Default Values**: Native support for default values in the Zod schema.
+- **Flexibility**: Works with any source of environment variables (process.env, import.meta.env, custom files, etc.).
+- **.env Support**: Easy integration with `.env` files via Node.js's `loadEnvFile`.
+- **Async/Sync**: Choose between synchronous or asynchronous operations as needed.
+- **TypeScript**: Fully typed, providing autocomplete and type checking.

package/dist/index.cjs

@@ -0,0 +1,59 @@
+"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, {
+  AsyncZodEnv: () => AsyncZodEnv,
+  ZodEnv: () => ZodEnv
+});
+module.exports = __toCommonJS(index_exports);
+var import_zod = require("zod");
+var ZodEnv = class {
+  schema;
+  env;
+  constructor({ schema, loadEnv, getEnv }) {
+    this.schema = schema;
+    loadEnv?.();
+    this.env = schema.parse(getEnv());
+  }
+  get(key) {
+    return this.env[key];
+  }
+};
+var AsyncZodEnv = class {
+  schema;
+  env;
+  constructor({ schema, loadEnv, getEnv }) {
+    this.schema = schema;
+    if (typeof loadEnv === "function") {
+      this.env = loadEnv().then(getEnv).then((result) => schema.parse(result));
+    } else {
+      this.env = getEnv().then((result) => schema.parse(result));
+    }
+  }
+  async get(key) {
+    return (await this.env)[key];
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AsyncZodEnv,
+  ZodEnv
+});

package/dist/index.d.cts

@@ -0,0 +1,30 @@
+import { ZodObject, z } from 'zod';
+
+interface ZodEnvConstructor {
+    schema: ZodObject;
+    loadEnv?: () => void;
+    getEnv: () => Record<string, any>;
+}
+declare class ZodEnv<S extends ZodObject> {
+    schema: S;
+    env: z.infer<S>;
+    constructor({ schema, loadEnv, getEnv }: ZodEnvConstructor & {
+        schema: S;
+    });
+    get<K extends keyof S["shape"]>(key: K): z.core.output<S>[K];
+}
+interface AsyncZodEnvConstructor {
+    schema: ZodObject;
+    loadEnv?: () => Promise<void>;
+    getEnv: () => Promise<Record<string, any>>;
+}
+declare class AsyncZodEnv<S extends ZodObject> {
+    schema: S;
+    env: Promise<z.infer<S>>;
+    constructor({ schema, loadEnv, getEnv }: AsyncZodEnvConstructor & {
+        schema: S;
+    });
+    get<K extends keyof S["shape"]>(key: K): Promise<z.core.output<S>[K]>;
+}
+
+export { AsyncZodEnv, ZodEnv };

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { ZodObject, z } from 'zod';
+
+interface ZodEnvConstructor {
+    schema: ZodObject;
+    loadEnv?: () => void;
+    getEnv: () => Record<string, any>;
+}
+declare class ZodEnv<S extends ZodObject> {
+    schema: S;
+    env: z.infer<S>;
+    constructor({ schema, loadEnv, getEnv }: ZodEnvConstructor & {
+        schema: S;
+    });
+    get<K extends keyof S["shape"]>(key: K): z.core.output<S>[K];
+}
+interface AsyncZodEnvConstructor {
+    schema: ZodObject;
+    loadEnv?: () => Promise<void>;
+    getEnv: () => Promise<Record<string, any>>;
+}
+declare class AsyncZodEnv<S extends ZodObject> {
+    schema: S;
+    env: Promise<z.infer<S>>;
+    constructor({ schema, loadEnv, getEnv }: AsyncZodEnvConstructor & {
+        schema: S;
+    });
+    get<K extends keyof S["shape"]>(key: K): Promise<z.core.output<S>[K]>;
+}
+
+export { AsyncZodEnv, ZodEnv };

package/dist/index.js

@@ -0,0 +1,33 @@
+// src/index.ts
+import "zod";
+var ZodEnv = class {
+  schema;
+  env;
+  constructor({ schema, loadEnv, getEnv }) {
+    this.schema = schema;
+    loadEnv?.();
+    this.env = schema.parse(getEnv());
+  }
+  get(key) {
+    return this.env[key];
+  }
+};
+var AsyncZodEnv = class {
+  schema;
+  env;
+  constructor({ schema, loadEnv, getEnv }) {
+    this.schema = schema;
+    if (typeof loadEnv === "function") {
+      this.env = loadEnv().then(getEnv).then((result) => schema.parse(result));
+    } else {
+      this.env = getEnv().then((result) => schema.parse(result));
+    }
+  }
+  async get(key) {
+    return (await this.env)[key];
+  }
+};
+export {
+  AsyncZodEnv,
+  ZodEnv
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@arthur-lobo/zod-env",
+  "version": "1.0.0",
+  "description": "load and validate your env with zod.",
+  "keywords": [
+    "zod",
+    "env",
+    "dotenv",
+    "validation"
+  ],
+  "license": "MIT",
+  "author": "Arthur Lobo",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.cjs",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest --run",
+    "build": "tsup",
+    "prepack": "npm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}