@geekmidas/envkit 9.0.2 → 10.0.0-alpha.0

package/docs/api-reference.md

@@ -1,302 +0,0 @@
-# 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/docs/async-secrets-design.md

@@ -1,355 +0,0 @@
-# Async Secrets Resolution Design
-
-## Problem Statement
-
-Applications often need to fetch sensitive configuration values (secrets) from external providers like HashiCorp Vault, AWS Secrets Manager, or other secret management systems. The current `EnvironmentParser` only supports synchronous parsing of environment variables, which doesn't accommodate async secret fetching.
-
-Additionally, environment variables for secrets typically contain **references** to the actual secret (e.g., a Vault path), not the secret value itself:
-
-```bash
-# Environment variables
-DB_HOST=localhost           # Actual value
-DB_PASSWORD=/vault/prod/db  # Reference to secret, not the actual password
-API_KEY=/vault/prod/api     # Reference to secret
-```
-
-## Proposed Solution
-
-Extend `EnvironmentParser` with:
-1. A separate `getSecret()` getter to distinguish secrets from regular env vars
-2. A configurable `secretsResolver` that fetches actual values from refs
-3. A cache to avoid redundant fetches for the same ref
-4. An `echoSecretsResolver` for testing that returns refs as values
-
-## API Design
-
-### Constructor Options
-
-```typescript
-interface EnvironmentParserOptions {
-  /**
-   * Function to resolve secret references to actual values.
-   * Receives an array of refs (values from env vars marked as secrets).
-   * Returns a Map of ref → resolved value.
-   */
-  secretsResolver?: SecretsResolver;
-}
-
-type SecretsResolver = (refs: string[]) => Promise<Map<string, string>>;
-```
-
-### Getters
-
-```typescript
-parser.create((get, getSecret) => ({
-  // Regular env var - resolved synchronously
-  host: get('DB_HOST').string(),
-  port: get('PORT').string().transform(Number),
-
-  // Secret env var - resolved asynchronously via secretsResolver
-  // The env var value is treated as a ref, not the actual value
-  password: getSecret('DB_PASSWORD').string(),
-  apiKey: getSecret('API_KEY').string(),
-}));
-```
-
-### Parsed Config Types
-
-```typescript
-// Regular values are their actual types
-config.host     // string
-config.port     // number
-
-// Secret values are Promises of their types
-config.password // Promise<string>
-config.apiKey   // Promise<string>
-
-// Usage
-const password = await config.password;
-```
-
-### Built-in Resolvers
-
-```typescript
-import { echoSecretsResolver } from '@geekmidas/envkit';
-
-/**
- * Echo resolver returns the ref as the value.
- * Useful for testing where the "ref" IS the actual test value.
- */
-export const echoSecretsResolver: SecretsResolver = async (refs) =>
-  new Map(refs.map((ref) => [ref, ref]));
-```
-
-## Resolution Flow
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                         parse() called                               │
-└─────────────────────────────────────────────────────────────────────┘
-                                   │
-                                   ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  1. Regular env vars (get) are parsed synchronously as normal        │
-│     config.host = "localhost"                                        │
-│     config.port = 3000                                               │
-└─────────────────────────────────────────────────────────────────────┘
-                                   │
-                                   ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  2. Secret env vars (getSecret) return Promises                      │
-│     config.password = Promise<string>                                │
-│     config.apiKey = Promise<string>                                  │
-└─────────────────────────────────────────────────────────────────────┘
-                                   │
-                                   ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│  3. When Promise is awaited:                                         │
-│     a. Read ref from env var (e.g., "/vault/prod/db")               │
-│     b. Check cache - if cached, return cached value                  │
-│     c. If not cached, call secretsResolver([ref])                    │
-│     d. Cache the resolved value                                      │
-│     e. Apply Zod validation/transformation                           │
-│     f. Return validated value                                        │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-## Caching Strategy
-
-A resolved secrets cache prevents redundant API calls:
-
-```typescript
-// Internal cache (per EnvironmentParser instance)
-private resolvedCache = new Map<string, string>();
-
-async resolveSecret(ref: string): Promise<string> {
-  // Return cached value if available
-  if (this.resolvedCache.has(ref)) {
-    return this.resolvedCache.get(ref)!;
-  }
-
-  // Fetch from resolver
-  const resolved = await this.secretsResolver([ref]);
-  const value = resolved.get(ref);
-
-  if (value === undefined) {
-    throw new Error(`Secret resolver did not return value for ref: ${ref}`);
-  }
-
-  // Cache for future use
-  this.resolvedCache.set(ref, value);
-  return value;
-}
-```
-
-Benefits:
-- Same ref accessed multiple times → single resolver call
-- Consistent values within a parser instance
-- Reduces load on secret providers
-
-## Usage Examples
-
-### Production with Vault
-
-```typescript
-import { EnvironmentParser } from '@geekmidas/envkit';
-
-// Vault resolver implementation
-const vaultResolver: SecretsResolver = async (refs) => {
-  const secrets = await vaultClient.batchRead(refs);
-  return new Map(refs.map((ref, i) => [ref, secrets[i].value]));
-};
-
-const parser = new EnvironmentParser(process.env, {
-  secretsResolver: vaultResolver,
-});
-
-const config = parser.create((get, getSecret) => ({
-  database: {
-    host: get('DB_HOST').string(),
-    port: get('DB_PORT').coerce.number(),
-    password: getSecret('DB_PASSWORD').string(),
-  },
-  api: {
-    baseUrl: get('API_BASE_URL').string().url(),
-    key: getSecret('API_KEY').string().min(32),
-  },
-})).parse();
-
-// Use in service registration
-const databaseService = {
-  serviceName: 'database' as const,
-  async register(envParser: EnvironmentParser<{}>) {
-    const config = envParser.create((get, getSecret) => ({
-      host: get('DB_HOST').string(),
-      password: getSecret('DB_PASSWORD').string(),
-    })).parse();
-
-    // Await the secret
-    const password = await config.password;
-
-    return new Database({
-      host: config.host,
-      password,
-    });
-  },
-};
-```
-
-### Testing with Echo Resolver
-
-```typescript
-import { EnvironmentParser, echoSecretsResolver } from '@geekmidas/envkit';
-
-describe('DatabaseService', () => {
-  it('should connect with credentials', async () => {
-    // In tests, the "ref" IS the actual test value
-    const env = {
-      DB_HOST: 'localhost',
-      DB_PORT: '5432',
-      DB_PASSWORD: 'test-password-123', // This IS the password for tests
-    };
-
-    const parser = new EnvironmentParser(env, {
-      secretsResolver: echoSecretsResolver,
-    });
-
-    const service = await databaseService.register(parser);
-
-    expect(service.isConnected()).toBe(true);
-  });
-});
-```
-
-### AWS Secrets Manager
-
-```typescript
-import { SecretsManagerClient, BatchGetSecretValueCommand } from '@aws-sdk/client-secrets-manager';
-
-const awsResolver: SecretsResolver = async (refs) => {
-  const client = new SecretsManagerClient({});
-  const command = new BatchGetSecretValueCommand({
-    SecretIdList: refs,
-  });
-
-  const response = await client.send(command);
-  const result = new Map<string, string>();
-
-  for (const secret of response.SecretValues ?? []) {
-    if (secret.ARN && secret.SecretString) {
-      result.set(secret.ARN, secret.SecretString);
-    }
-  }
-
-  return result;
-};
-```
-
-## Type Definitions
-
-```typescript
-/**
- * Function type for resolving secret references to actual values.
- */
-export type SecretsResolver = (refs: string[]) => Promise<Map<string, string>>;
-
-/**
- * Extended getter that includes secret() method.
- */
-export type SecretEnvFetcher<TPath extends string = string> = (
-  name: TPath,
-) => typeof z;
-
-/**
- * Builder function signature with both getters.
- */
-export type EnvironmentBuilderWithSecrets<TResponse extends EmptyObject> = (
-  get: EnvFetcher,
-  getSecret: SecretEnvFetcher,
-) => TResponse;
-
-/**
- * Infers config type, wrapping secret values in Promise.
- */
-export type InferConfigWithSecrets<T extends EmptyObject> = {
-  [K in keyof T]: T[K] extends SecretSchema<infer U>
-    ? Promise<U>
-    : T[K] extends z.ZodSchema
-      ? z.infer<T[K]>
-      : T[K] extends Record<string, unknown>
-        ? InferConfigWithSecrets<T[K]>
-        : T[K];
-};
-```
-
-## Error Handling
-
-### Missing Resolver
-
-```typescript
-// If getSecret() is used but no resolver provided
-const parser = new EnvironmentParser(env); // no resolver
-
-const config = parser.create((get, getSecret) => ({
-  password: getSecret('DB_PASSWORD').string(),
-})).parse();
-
-await config.password;
-// Error: SecretsResolver is required when using getSecret().
-// Configure it via EnvironmentParser options.
-```
-
-### Missing Ref in Environment
-
-```typescript
-// If env var doesn't exist
-const env = { DB_HOST: 'localhost' }; // DB_PASSWORD not set
-
-const config = parser.create((get, getSecret) => ({
-  password: getSecret('DB_PASSWORD').string(),
-})).parse();
-
-await config.password;
-// Error: Environment variable "DB_PASSWORD" is not defined.
-// Expected a secret reference.
-```
-
-### Resolver Doesn't Return Value
-
-```typescript
-// If resolver doesn't return value for a ref
-const brokenResolver: SecretsResolver = async (refs) => new Map();
-
-await config.password;
-// Error: Secret resolver did not return value for ref: /vault/prod/db
-```
-
-## Migration Path
-
-Existing code using `EnvironmentParser` continues to work unchanged:
-
-```typescript
-// Before (still works)
-const config = parser.create((get) => ({
-  port: get('PORT').string().transform(Number),
-})).parse();
-
-// After (opt-in to secrets)
-const config = parser.create((get, getSecret) => ({
-  port: get('PORT').string().transform(Number),
-  password: getSecret('DB_PASSWORD').string(),
-})).parse();
-```
-
-## Open Questions
-
-1. **Batch resolution timing**: Should we batch all secret resolutions when `parse()` is called, or resolve lazily when each Promise is awaited?
-   - **Lazy (proposed)**: Each secret resolved on first await, cached for subsequent access
-   - **Eager**: All secrets resolved upfront in parse(), requires parseAsync()
-
-2. **Cache scope**: Should the cache be per-parser instance or global?
-   - **Per-instance (proposed)**: Isolated, predictable behavior
-   - **Global**: More efficient for multiple parsers with same refs
-
-3. **Cache invalidation**: Should there be a way to clear the cache?
-   - Could add `parser.clearSecretCache()` method if needed