@geekmidas/envkit 0.0.1

package/docs/api-reference.md

@@ -0,0 +1,302 @@
+# API Reference - @geekmidas/envkit
+
+## Classes
+
+### `EnvironmentParser`
+
+The main class for creating configuration parsers.
+
+```typescript
+class EnvironmentParser {
+  constructor(config: Record<string, unknown>)
+  create<T>(schemaBuilder: (get: GetFunction) => T): ConfigParser<T>
+}
+```
+
+#### Constructor
+
+Creates a new environment parser instance.
+
+**Parameters:**
+- `config: Record<string, unknown>` - The configuration object to parse (typically `process.env`)
+
+**Example:**
+```typescript
+const parser = new EnvironmentParser(process.env);
+```
+
+#### Methods
+
+##### `create<T>(schemaBuilder: (get: GetFunction) => T): ConfigParser<T>`
+
+Creates a configuration parser with the specified schema.
+
+**Parameters:**
+- `schemaBuilder: (get: GetFunction) => T` - A function that receives a `get` function and returns the schema definition
+
+**Returns:**
+- `ConfigParser<T>` - A configuration parser instance
+
+**Example:**
+```typescript
+const config = parser.create((get) => ({
+  port: get('PORT').string().transform(Number),
+  apiKey: get('API_KEY').string()
+}));
+```
+
+### `ConfigParser<T>`
+
+The configuration parser returned by `EnvironmentParser.create()`.
+
+```typescript
+class ConfigParser<T> {
+  parse(): T
+}
+```
+
+#### Methods
+
+##### `parse(): T`
+
+Parses and validates the configuration according to the defined schema.
+
+**Returns:**
+- `T` - The parsed and validated configuration object
+
+**Throws:**
+- `ZodError` - If validation fails. The error contains all validation failures aggregated together.
+
+**Example:**
+```typescript
+try {
+  const config = parser.create((get) => ({
+    port: get('PORT').string().transform(Number)
+  })).parse();
+  
+  console.log(config.port); // number
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    console.error('Validation errors:', error.errors);
+  }
+}
+```
+
+## Type Definitions
+
+### `GetFunction`
+
+The function passed to the schema builder for accessing configuration values.
+
+```typescript
+type GetFunction = (path: string) => ZodTypeAny
+```
+
+**Parameters:**
+- `path: string` - The path to the configuration value. Supports:
+  - Simple paths: `'PORT'`, `'API_KEY'`
+  - Nested paths with dots: `'database.host'`, `'api.endpoints.users'`
+
+**Returns:**
+- `ZodTypeAny` - A Zod schema that will be used to validate the value at the specified path
+
+**Usage:**
+```typescript
+const config = parser.create((get) => ({
+  // Simple path
+  port: get('PORT').string(),
+  
+  // Nested path - looks for 'DATABASE_HOST' in config
+  database: {
+    host: get('DATABASE_HOST').string()
+  },
+  
+  // With transformations
+  maxRetries: get('MAX_RETRIES').string().transform(Number),
+  
+  // With validation
+  email: get('ADMIN_EMAIL').string().email(),
+  
+  // With defaults
+  logLevel: get('LOG_LEVEL').string().default('info'),
+  
+  // Optional values
+  debugMode: get('DEBUG').string().optional()
+}));
+```
+
+## Error Handling
+
+### Validation Errors
+
+When validation fails, the parser throws a `ZodError` containing all validation failures:
+
+```typescript
+import { z } from 'zod';
+
+try {
+  const config = parser.create((get) => ({
+    port: get('PORT').string().transform(Number),
+    apiKey: get('API_KEY').string().min(32),
+    email: get('ADMIN_EMAIL').string().email()
+  })).parse();
+} catch (error) {
+  if (error instanceof z.ZodError) {
+    // error.errors is an array of all validation errors
+    error.errors.forEach(err => {
+      console.error(`${err.path.join('.')}: ${err.message}`);
+    });
+    
+    // Example output:
+    // port: Expected string, received undefined
+    // apiKey: String must contain at least 32 character(s)
+    // email: Invalid email
+  }
+}
+```
+
+### Error Aggregation
+
+The parser collects all validation errors before throwing, allowing you to see all configuration problems at once:
+
+```typescript
+// If multiple values are invalid, all errors are reported together
+const config = parser.create((get) => ({
+  database: {
+    host: get('DB_HOST').string(),        // Missing
+    port: get('DB_PORT').string(),        // Missing
+    name: get('DB_NAME').string()         // Missing
+  },
+  api: {
+    key: get('API_KEY').string(),         // Missing
+    url: get('API_URL').url()             // Invalid format
+  }
+}));
+
+// Throws ZodError with all 5 validation errors
+```
+
+## Path Resolution
+
+The parser uses lodash's `get` and `set` functions for path resolution:
+
+### Simple Paths
+```typescript
+// Configuration object
+const config = {
+  PORT: '3000',
+  API_KEY: 'secret'
+};
+
+// Access with get()
+get('PORT')     // Looks for config.PORT
+get('API_KEY')  // Looks for config.API_KEY
+```
+
+### Nested Objects
+```typescript
+// Configuration object
+const config = {
+  database: {
+    host: 'localhost',
+    port: '5432'
+  }
+};
+
+// Access with get()
+get('database.host')  // Returns 'localhost'
+get('database.port')  // Returns '5432'
+```
+
+### Environment Variable Mapping
+When using `process.env`, nested paths are automatically mapped:
+
+```typescript
+// These environment variables:
+// DATABASE_HOST=localhost
+// DATABASE_PORT=5432
+
+// Can be accessed as:
+const config = parser.create((get) => ({
+  database: {
+    host: get('DATABASE_HOST').string(),    // Maps to DATABASE_HOST
+    port: get('DATABASE_PORT').string()     // Maps to DATABASE_PORT
+  }
+}));
+```
+
+## Zod Schema Integration
+
+The parser returns Zod schemas, allowing you to use all Zod validation features:
+
+### Transformations
+```typescript
+get('PORT').string().transform(Number)
+get('ENABLED').string().transform(v => v === 'true')
+get('TAGS').string().transform(v => v.split(','))
+```
+
+### Validations
+```typescript
+get('EMAIL').string().email()
+get('URL').string().url()
+get('PORT').string().transform(Number).int().min(1).max(65535)
+get('NODE_ENV').enum(['development', 'production', 'test'])
+```
+
+### Refinements
+```typescript
+get('PASSWORD')
+  .string()
+  .min(8)
+  .refine(password => /[A-Z]/.test(password), {
+    message: 'Password must contain at least one uppercase letter'
+  })
+```
+
+### Complex Types
+```typescript
+// Arrays
+get('ALLOWED_ORIGINS')
+  .string()
+  .transform(v => v.split(','))
+  .pipe(z.array(z.string().url()))
+
+// Objects
+get('CONFIG_JSON')
+  .string()
+  .transform(v => JSON.parse(v))
+  .pipe(z.object({
+    timeout: z.number(),
+    retries: z.number()
+  }))
+```
+
+## TypeScript Integration
+
+The parser provides full type inference:
+
+```typescript
+const parser = new EnvironmentParser(process.env);
+
+const config = parser.create((get) => ({
+  server: {
+    port: get('PORT').string().transform(Number),
+    host: get('HOST').string().default('localhost')
+  },
+  features: {
+    auth: get('FEATURE_AUTH').string().transform(v => v === 'true'),
+    rateLimit: get('FEATURE_RATE_LIMIT').string().transform(v => v === 'true')
+  }
+}));
+
+const parsed = config.parse();
+
+// TypeScript knows:
+// parsed.server.port: number
+// parsed.server.host: string
+// parsed.features.auth: boolean
+// parsed.features.rateLimit: boolean
+```
+
+The types are automatically inferred from the Zod schemas, providing complete type safety without manual type definitions.

package/examples/basic-usage.ts

@@ -0,0 +1,390 @@
+import { EnvironmentParser } from '@geekmidas/envkit';
+import { z } from 'zod';
+
+const parser = new EnvironmentParser(process.env as {});
+// Example 1: Basic configuration
+export function basicExample() {
+  const config = parser.create((get) => ({
+    appName: get('APP_NAME').string().default('My App'),
+    port: get('PORT').string().transform(Number).default(3000),
+    isDevelopment: get('NODE_ENV')
+      .string()
+      .transform((env) => env === 'development'),
+  }));
+
+  const result = config.parse();
+
+  return result;
+}
+
+// Example 2: Database configuration
+export function databaseExample() {
+  const config = parser.create((get) => ({
+    database: {
+      host: get('DB_HOST').string().default('localhost'),
+      port: get('DB_PORT').string().transform(Number).default(5432),
+      name: get('DB_NAME').string(),
+      user: get('DB_USER').string(),
+      password: get('DB_PASSWORD').string(),
+      ssl: get('DB_SSL')
+        .string()
+        .transform((v) => v === 'true')
+        .default(false),
+      poolSize: get('DB_POOL_SIZE')
+        .string()
+        .transform(Number)
+        .int()
+        .min(1)
+        .max(100)
+        .default(10),
+    },
+  }));
+
+  return config.parse();
+}
+
+// Example 3: API configuration with validation
+export function apiConfigExample() {
+  const config = parser.create((get) => ({
+    api: {
+      baseUrl: get('API_BASE_URL').url(),
+      key: get('API_KEY').string().min(32),
+      secret: get('API_SECRET').string().min(64),
+      timeout: get('API_TIMEOUT').string().transform(Number).default(5000),
+      retries: get('API_RETRIES').string().transform(Number).default(3),
+      endpoints: {
+        users: get('API_ENDPOINT_USERS').string().default('/api/v1/users'),
+        auth: get('API_ENDPOINT_AUTH').string().default('/api/v1/auth'),
+        products: get('API_ENDPOINT_PRODUCTS')
+          .string()
+          .default('/api/v1/products'),
+      },
+    },
+  }));
+
+  return config.parse();
+}
+
+// Example 4: Feature flags and complex validation
+export function featureFlagsExample() {
+  const config = parser.create((get) => ({
+    features: {
+      authentication: get('FEATURE_AUTH')
+        .string()
+        .transform((v) => v === 'true')
+        .default(true),
+      rateLimit: get('FEATURE_RATE_LIMIT')
+        .string()
+        .transform((v) => v === 'true')
+        .default(true),
+      cache: get('FEATURE_CACHE')
+        .string()
+        .transform((v) => v === 'true')
+        .default(false),
+      beta: {
+        enabled: get('FEATURE_BETA')
+          .string()
+          .transform((v) => v === 'true')
+          .default(false),
+        allowedUsers: get('FEATURE_BETA_USERS')
+          .string()
+          .transform((users) =>
+            users ? users.split(',').map((u) => u.trim()) : [],
+          )
+          .default([]),
+      },
+    },
+    rateLimit: {
+      windowMs: get('RATE_LIMIT_WINDOW_MS')
+        .string()
+        .transform(Number)
+        .default(60000),
+      maxRequests: get('RATE_LIMIT_MAX_REQUESTS')
+        .string()
+        .transform(Number)
+        .default(100),
+    },
+  }));
+
+  return config.parse();
+}
+
+// Example 5: Email configuration with refinements
+export function emailConfigExample() {
+  const config = parser.create((get) => ({
+    email: {
+      provider: get('EMAIL_PROVIDER').enum(['sendgrid', 'mailgun', 'ses']),
+      apiKey: get('EMAIL_API_KEY').string().min(20),
+      from: {
+        name: get('EMAIL_FROM_NAME').string().default('Support Team'),
+        address: get('EMAIL_FROM_ADDRESS').string().email(),
+      },
+      replyTo: get('EMAIL_REPLY_TO').string().email().optional(),
+      templates: {
+        welcome: get('EMAIL_TEMPLATE_WELCOME').string().uuid(),
+        resetPassword: get('EMAIL_TEMPLATE_RESET_PASSWORD').string().uuid(),
+        invoice: get('EMAIL_TEMPLATE_INVOICE').string().uuid().optional(),
+      },
+      smtp: {
+        host: get('SMTP_HOST').string().optional(),
+        port: get('SMTP_PORT').string().transform(Number).optional(),
+        secure: get('SMTP_SECURE')
+          .string()
+          .transform((v) => v === 'true')
+          .default(true),
+      },
+    },
+  }));
+
+  return config.parse();
+}
+
+// Example 6: Multi-environment configuration
+export function multiEnvironmentExample() {
+  const env = process.env.NODE_ENV || 'development';
+
+  // Different config sources based on environment
+  const configSource = {
+    ...process.env,
+    // Override with environment-specific values
+    ...(env === 'production'
+      ? {
+          LOG_LEVEL: 'error',
+          DEBUG: 'false',
+        }
+      : {
+          LOG_LEVEL: 'debug',
+          DEBUG: 'true',
+        }),
+  };
+
+  const parser = new EnvironmentParser(configSource);
+
+  const config = parser.create((get) => ({
+    env: get('NODE_ENV')
+      .enum(['development', 'staging', 'production'])
+      .default('development'),
+    logging: {
+      level: get('LOG_LEVEL').enum([
+        'trace',
+        'debug',
+        'info',
+        'warn',
+        'error',
+        'fatal',
+      ]),
+      pretty: get('LOG_PRETTY')
+        .string()
+        .transform((v) => v === 'true')
+        .default(env !== 'production'),
+      debug: get('DEBUG')
+        .string()
+        .transform((v) => v === 'true'),
+    },
+    server: {
+      host: get('HOST').string().default('0.0.0.0'),
+      port: get('PORT')
+        .string()
+        .transform(Number)
+        .default(env === 'production' ? 80 : 3000),
+      cors: {
+        enabled: get('CORS_ENABLED')
+          .string()
+          .transform((v) => v === 'true')
+          .default(true),
+        origins: get('CORS_ORIGINS')
+          .string()
+          .transform((origins) => origins.split(',').map((o) => o.trim()))
+          .refine((origins) => origins.every((o) => o.startsWith('http')), {
+            message: 'All CORS origins must be valid URLs',
+          })
+          .default(['http://localhost:3000']),
+      },
+    },
+  }));
+
+  return config.parse();
+}
+
+// Example 7: Error handling
+export function errorHandlingExample() {
+  try {
+    const config = parser
+      .create((get) => ({
+        required: {
+          apiKey: get('API_KEY').string().min(32),
+          databaseUrl: get('DATABASE_URL').string().url(),
+          adminEmail: get('ADMIN_EMAIL').string().email(),
+        },
+        optional: {
+          sentryDsn: get('SENTRY_DSN').string().url().optional(),
+          slackWebhook: get('SLACK_WEBHOOK').string().url().optional(),
+        },
+      }))
+      .parse();
+
+    return config;
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      console.error('Configuration validation failed:');
+      console.error('Missing or invalid environment variables:');
+
+      error.errors.forEach((err) => {
+        const path = err.path.join('.');
+        console.error(`  ${path}: ${err.message}`);
+      });
+
+      // In a real app, you might want to exit
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+
+// Example 8: Using with dotenv
+export function dotenvExample() {
+  // Load .env file
+  require('dotenv').config();
+
+  const config = parser.create((get) => ({
+    app: {
+      name: get('APP_NAME').string(),
+      version: get('APP_VERSION')
+        .string()
+        .regex(/^\d+\.\d+\.\d+$/),
+      description: get('APP_DESCRIPTION').string().optional(),
+    },
+    secrets: {
+      jwtSecret: get('JWT_SECRET').string().min(64),
+      encryptionKey: get('ENCRYPTION_KEY').string().length(32),
+      apiKeys: get('API_KEYS')
+        .string()
+        .transform((keys) => keys.split(',').map((k) => k.trim()))
+        .pipe(z.array(z.string().min(32))),
+    },
+  }));
+
+  return config.parse();
+}
+
+// Example 9: Custom transformations
+export function customTransformationsExample() {
+  const config = parser.create((get) => ({
+    // Parse JSON
+    features: get('FEATURES_JSON')
+      .string()
+      .transform((str) => JSON.parse(str))
+      .pipe(z.record(z.boolean())),
+
+    // Parse duration strings
+    timeouts: {
+      request: get('TIMEOUT_REQUEST')
+        .string()
+        .transform(parseDuration)
+        .default('30s'),
+      idle: get('TIMEOUT_IDLE').string().transform(parseDuration).default('5m'),
+    },
+
+    // Parse memory sizes
+    limits: {
+      memory: get('MEMORY_LIMIT')
+        .string()
+        .transform(parseMemorySize)
+        .default('512MB'),
+      upload: get('UPLOAD_LIMIT')
+        .string()
+        .transform(parseMemorySize)
+        .default('10MB'),
+    },
+
+    // Complex array parsing
+    allowedDomains: get('ALLOWED_DOMAINS')
+      .string()
+      .transform((domains) =>
+        domains
+          .split(',')
+          .map((d) => d.trim())
+          .filter(Boolean),
+      )
+      .pipe(z.array(z.string().regex(/^[a-z0-9.-]+$/i))),
+  }));
+
+  return config.parse();
+}
+
+// Helper functions for custom transformations
+function parseDuration(duration: string): number {
+  const match = duration.match(/^(\d+)(ms|s|m|h)$/);
+  if (!match) throw new Error(`Invalid duration: ${duration}`);
+
+  const [, value, unit] = match;
+  const multipliers = { ms: 1, s: 1000, m: 60000, h: 3600000 };
+  return parseInt(value) * multipliers[unit as keyof typeof multipliers];
+}
+
+function parseMemorySize(size: string): number {
+  const match = size.match(/^(\d+)(B|KB|MB|GB)$/i);
+  if (!match) throw new Error(`Invalid memory size: ${size}`);
+
+  const [, value, unit] = match;
+  const multipliers = { B: 1, KB: 1024, MB: 1048576, GB: 1073741824 };
+  return (
+    parseInt(value) *
+    multipliers[unit.toUpperCase() as keyof typeof multipliers]
+  );
+}
+
+// Example 10: Type-safe configuration module
+// config.ts - This is how you'd typically use it in a real app
+export const loadConfig = () => {
+  const parser = new EnvironmentParser(process.env as any);
+
+  return parser
+    .create((get) => ({
+      app: {
+        name: get('APP_NAME').string().default('My Application'),
+        env: get('NODE_ENV')
+          .enum(['development', 'staging', 'production'])
+          .default('development'),
+        port: get('PORT').string().transform(Number).default(3000),
+        host: get('HOST').string().default('localhost'),
+      },
+      database: {
+        url: get('DATABASE_URL').string().url(),
+        maxConnections: get('DB_MAX_CONNECTIONS')
+          .string()
+          .transform(Number)
+          .default(10),
+        ssl: get('DB_SSL')
+          .string()
+          .transform((v) => v === 'true')
+          .default(false),
+      },
+      redis: {
+        url: get('REDIS_URL').string().url().optional(),
+        ttl: get('REDIS_TTL').string().transform(Number).default(3600),
+      },
+      auth: {
+        jwtSecret: get('JWT_SECRET').string().min(32),
+        jwtExpiry: get('JWT_EXPIRY').string().default('7d'),
+        bcryptRounds: get('BCRYPT_ROUNDS')
+          .string()
+          .transform(Number)
+          .default(10),
+      },
+      features: {
+        signups: get('FEATURE_SIGNUPS')
+          .string()
+          .transform((v) => v === 'true')
+          .default(true),
+        subscriptions: get('FEATURE_SUBSCRIPTIONS')
+          .string()
+          .transform((v) => v === 'true')
+          .default(false),
+      },
+    }))
+    .parse();
+};
+
+// Export the config for use throughout the app
+export const config = loadConfig();

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@geekmidas/envkit",
+  "version": "0.0.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "~3.25.67",
+    "lodash.set": "~4.3.2",
+    "lodash.get": "~4.4.2"
+  },
+  "devDependencies": {
+    "@types/lodash.set": "~4.3.9",
+    "@types/lodash.get": "~4.4.9"
+  }
+}