gem-hunter

Zod Env

Installation

bun add @arthur-lobo/zod-env zod
# or
npm install @arthur-lobo/zod-env zod

Description

Basic Usage

Synchronous Class: ZodEnv

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

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

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

const env = new AsyncZodEnv({
  schema: z.object({
    SECRET_KEY: z.string(),
  }),
  loadEnv: async () => loadEnvFile(), // Loads .env asynchronously
  getEnv: async () => process.env,
});

Schema Examples

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