@geekmidas/envkit 1.1.1 → 10.0.0-alpha.0

package/src/EnvironmentParser.ts

@@ -1,330 +0,0 @@
-import get from 'lodash.get';
-import set from 'lodash.set';
-import { z } from 'zod/v4';
-import { formatParseError, isDevelopment } from './formatter.js';
-
-/**
- * Parses and validates configuration objects against Zod schemas.
- * Handles nested configurations and aggregates validation errors.
- *
- * @template TResponse - The shape of the configuration object
- */
-export class ConfigParser<TResponse extends EmptyObject> {
-	/**
-	 * Creates a new ConfigParser instance.
-	 *
-	 * @param config - The configuration object to parse
-	 * @param envVars - Set of environment variable names that were accessed
-	 */
-	constructor(
-		private readonly config: TResponse,
-		private readonly envVars: Set<string> = new Set(),
-	) {}
-	/**
-	 * Parses the config object and validates it against the Zod schemas
-	 * @returns The parsed config object
-	 */
-	parse(): InferConfig<TResponse> {
-		const errors: z.core.$ZodIssue[] = [];
-
-		const parseDeep = <T>(config: T, path: string[] = []) => {
-			const result: EmptyObject = {};
-
-			if (config && typeof config !== 'object') {
-				return config;
-			}
-
-			for (const key in config) {
-				const schema = config[key];
-				const currentPath = [...path, key];
-
-				if (schema instanceof z.ZodType) {
-					const parsed = schema.safeParse(undefined);
-					if (parsed.success) {
-						set(result, key, parsed.data);
-					} else {
-						// If the schema is invalid, assign the error
-						errors.push(
-							...parsed.error.issues.map((issue) => ({
-								...issue,
-								path: [...currentPath, ...(issue.path as string[])],
-							})),
-						);
-					}
-				} else if (schema) {
-					set(result, key, parseDeep(schema as EmptyObject, currentPath));
-				}
-			}
-
-			return result;
-		};
-
-		const parsedConfig = parseDeep(
-			this.config,
-		) as unknown as InferConfig<TResponse>;
-
-		if (errors.length > 0) {
-			const zodError = new z.ZodError(errors);
-			// In development, log a formatted error message before throwing
-			if (isDevelopment()) {
-				console.error(formatParseError(zodError));
-			}
-			throw zodError;
-		}
-
-		return parsedConfig;
-	}
-
-	/**
-	 * Returns an array of environment variable names that were accessed during config creation.
-	 * This is useful for deployment and configuration management to know which env vars are required.
-	 *
-	 * @returns Array of environment variable names, sorted alphabetically
-	 *
-	 * @example
-	 * ```typescript
-	 * const config = envParser.create((get) => ({
-	 *   dbUrl: get('DATABASE_URL').string(),
-	 *   port: get('PORT').number()
-	 * }));
-	 *
-	 * config.getEnvironmentVariables(); // ['DATABASE_URL', 'PORT']
-	 * ```
-	 */
-	getEnvironmentVariables(): string[] {
-		return Array.from(this.envVars).sort();
-	}
-}
-
-/**
- * Parses environment variables with type-safe validation using Zod schemas.
- * Provides a fluent API for defining environment variable schemas with automatic
- * error context enrichment.
- *
- * @template T - The type of the configuration object (typically process.env)
- *
- * @example
- * ```typescript
- * const config = new EnvironmentParser(process.env)
- *   .create((get) => ({
- *     port: get('PORT').string().transform(Number).default(3000),
- *     database: {
- *       url: get('DATABASE_URL').string().url()
- *     }
- *   }))
- *   .parse();
- * ```
- */
-export class EnvironmentParser<T extends EmptyObject> {
-	/**
-	 * Set to track which environment variable names have been accessed
-	 */
-	private readonly accessedVars: Set<string> = new Set();
-
-	/**
-	 * Creates a new EnvironmentParser instance.
-	 *
-	 * @param config - The configuration object to parse (typically process.env)
-	 */
-	constructor(private readonly config: T) {}
-
-	/**
-	 * Wraps a Zod schema to intercept parse/safeParse calls and enrich error messages
-	 * with environment variable context.
-	 *
-	 * @param schema - The Zod schema to wrap
-	 * @param name - The environment variable name for error context
-	 * @returns A wrapped Zod schema with enhanced error reporting
-	 */
-	private wrapSchema = (schema: z.ZodType, name: string): z.ZodType => {
-		// Create a proxy that intercepts all method calls on the schema
-		return new Proxy(schema, {
-			get: (target, prop) => {
-				if (prop === 'parse') {
-					return () => {
-						const value = get(this.config, name);
-						try {
-							return target.parse(value);
-						} catch (error) {
-							if (error instanceof z.ZodError) {
-								// Modify the error to include the environment variable name
-								const modifiedIssues = error.issues.map((issue) => ({
-									...issue,
-									message: `Environment variable "${name}": ${issue.message}`,
-									path: [name, ...issue.path],
-								}));
-								throw new z.ZodError(modifiedIssues);
-							}
-							throw error;
-						}
-					};
-				}
-
-				if (prop === 'safeParse') {
-					return () => {
-						const value = get(this.config, name);
-						const result = target.safeParse(value);
-
-						if (!result.success) {
-							// Modify the error to include the environment variable name
-							const modifiedIssues = result.error.issues.map(
-								(issue: z.core.$ZodIssue) => ({
-									...issue,
-									message: `Environment variable "${name}": ${issue.message}`,
-									path: [name, ...issue.path],
-								}),
-							);
-							return {
-								success: false as const,
-								error: new z.ZodError(modifiedIssues),
-							};
-						}
-
-						return result;
-					};
-				}
-
-				// For any method that returns a new schema (like transform, optional, etc.),
-				// wrap the result as well
-				const originalProp = target[prop as keyof typeof target];
-				if (typeof originalProp === 'function') {
-					return (...args: any[]) => {
-						const result = originalProp.apply(target, args);
-						// If the result is a ZodType, wrap it too
-						if (result && typeof result === 'object' && 'parse' in result) {
-							return this.wrapSchema(result, name);
-						}
-						return result;
-					};
-				}
-
-				return originalProp;
-			},
-		});
-	};
-
-	/**
-	 * Creates a proxied version of the Zod object that wraps all schema creators
-	 * to provide enhanced error messages with environment variable context.
-	 *
-	 * @param name - The environment variable name
-	 * @returns A proxied Zod object with wrapped schema creators
-	 */
-	private getZodGetter = (name: string) => {
-		// Track that this environment variable was accessed
-		this.accessedVars.add(name);
-
-		// Return an object that has all Zod schemas but with our wrapper
-		return new Proxy(
-			{ ...z },
-			{
-				get: (target, prop) => {
-					// deno-lint-ignore ban-ts-comment
-					// @ts-expect-error
-					const value = target[prop];
-
-					if (typeof value === 'function') {
-						// Return a wrapper around each Zod schema creator
-						return (...args: any[]) => {
-							const schema = value(...args);
-							return this.wrapSchema(schema, name);
-						};
-					}
-
-					// Handle objects like z.coerce
-					if (value && typeof value === 'object') {
-						return new Proxy(value, {
-							get: (nestedTarget, nestedProp) => {
-								const nestedValue =
-									nestedTarget[nestedProp as keyof typeof nestedTarget];
-								if (typeof nestedValue === 'function') {
-									return (...args: any[]) => {
-										const schema = nestedValue(...args);
-										return this.wrapSchema(schema, name);
-									};
-								}
-								return nestedValue;
-							},
-						});
-					}
-
-					return value;
-				},
-			},
-		);
-	};
-
-	/**
-	 * Creates a new ConfigParser object that can be used to parse the config object
-	 *
-	 * @param builder - A function that takes a getter function and returns a config object
-	 * @returns A ConfigParser object that can be used to parse the config object
-	 */
-	create<TReturn extends EmptyObject>(
-		builder: (get: EnvFetcher) => TReturn,
-	): ConfigParser<TReturn> {
-		const config = builder(this.getZodGetter);
-		return new ConfigParser(config, this.accessedVars);
-	}
-
-	/**
-	 * Returns an array of environment variable names that were accessed via the getter.
-	 * This is useful for build-time analysis to determine which env vars a service needs.
-	 *
-	 * @returns Array of environment variable names, sorted alphabetically
-	 *
-	 * @example
-	 * ```typescript
-	 * const sniffer = new EnvironmentParser({});
-	 * service.register(sniffer);
-	 * const envVars = sniffer.getEnvironmentVariables(); // ['DATABASE_URL', 'PORT']
-	 * ```
-	 */
-	getEnvironmentVariables(): string[] {
-		return Array.from(this.accessedVars).sort();
-	}
-}
-
-/**
- * Infers the TypeScript type of a configuration object based on its Zod schemas.
- * Recursively processes nested objects and extracts types from Zod schemas.
- *
- * @template T - The configuration object type
- */
-export type InferConfig<T extends EmptyObject> = {
-	[K in keyof T]: T[K] extends z.ZodSchema
-		? z.infer<T[K]>
-		: T[K] extends Record<string, unknown>
-			? InferConfig<T[K]>
-			: T[K];
-};
-
-/**
- * Function type for fetching environment variables with Zod validation.
- * Returns a Zod object scoped to a specific environment variable.
- *
- * @template TPath - The environment variable path type
- * @param name - The environment variable name
- * @returns A Zod object for defining the schema
- */
-export type EnvFetcher<TPath extends string = string> = (
-	name: TPath,
-) => typeof z;
-
-/**
- * Function type for building environment configuration objects.
- * Takes an EnvFetcher and returns a configuration object with Zod schemas.
- *
- * @template TResponse - The response configuration object type
- * @param get - The environment variable fetcher function
- * @returns The configuration object with Zod schemas
- */
-export type EnvironmentBuilder<TResponse extends EmptyObject> = (
-	get: EnvFetcher,
-) => TResponse;
-
-/**
- * Type alias for a generic object with unknown values.
- * Used as a constraint for configuration objects.
- */
-export type EmptyObject = Record<string | number | symbol, unknown>;

package/src/SnifferEnvironmentParser.ts

@@ -1,334 +0,0 @@
-import { z } from 'zod/v4';
-import {
-	ConfigParser,
-	type EmptyObject,
-	type EnvFetcher,
-} from './EnvironmentParser';
-
-/**
- * A specialized EnvironmentParser for build-time analysis that tracks
- * which environment variables are accessed without requiring actual values.
- *
- * Unlike the regular EnvironmentParser, the sniffer:
- * - Always returns mock values from .parse() and .safeParse()
- * - Never throws validation errors
- * - Tracks all accessed environment variable names
- *
- * This allows service registration to succeed during build-time analysis
- * even when environment variables are not set.
- *
- * @example
- * ```typescript
- * const sniffer = new SnifferEnvironmentParser();
- * await service.register(sniffer); // Always succeeds
- * const envVars = sniffer.getEnvironmentVariables(); // ['DATABASE_URL', 'API_KEY']
- * ```
- */
-export class SnifferEnvironmentParser<_T extends EmptyObject = EmptyObject> {
-	private readonly accessedVars: Set<string> = new Set();
-	private readonly optionalVars: Set<string> = new Set();
-
-	/**
-	 * Wraps a Zod schema to always return mock values.
-	 * This ensures .parse() and .safeParse() never fail.
-	 * Also detects when .optional() or .default() is called to track optional vars.
-	 */
-	private wrapSchema = (schema: z.ZodType, name: string): z.ZodType => {
-		return new Proxy(schema, {
-			get: (target, prop) => {
-				if (prop === 'parse') {
-					return () => this.getMockValue(target);
-				}
-
-				if (prop === 'safeParse') {
-					return () => ({
-						success: true as const,
-						data: this.getMockValue(target),
-					});
-				}
-
-				// Detect .optional() or .default() — mark the variable as optional
-				if (prop === 'optional' || prop === 'default') {
-					this.optionalVars.add(name);
-				}
-
-				const originalProp = target[prop as keyof typeof target];
-				if (typeof originalProp === 'function') {
-					return (...args: any[]) => {
-						const result = originalProp.apply(target, args);
-						if (result && typeof result === 'object' && 'parse' in result) {
-							return this.wrapSchema(result, name);
-						}
-						return result;
-					};
-				}
-
-				return originalProp;
-			},
-		});
-	};
-
-	/**
-	 * Returns a mock value based on the Zod schema type.
-	 */
-	private getMockValue(schema: z.ZodType): unknown {
-		// Return type-appropriate mock values
-		if (schema instanceof z.ZodString) return '';
-		if (schema instanceof z.ZodNumber) return 0;
-		if (schema instanceof z.ZodBoolean) return false;
-		if (schema instanceof z.ZodArray) return [];
-		if (schema instanceof z.ZodOptional) return undefined;
-		if (schema instanceof z.ZodNullable) return null;
-
-		// For object schemas, build mock object from shape
-		if (schema instanceof z.ZodObject && schema.shape) {
-			const result: Record<string, unknown> = {};
-			for (const [key, value] of Object.entries(schema.shape)) {
-				if (value instanceof z.ZodType) {
-					result[key] = this.getMockValue(value);
-				}
-			}
-			return result;
-		}
-
-		return '';
-	}
-
-	/**
-	 * Creates a proxied Zod getter that tracks environment variable access.
-	 */
-	private getZodGetter = (name: string) => {
-		this.accessedVars.add(name);
-
-		return new Proxy(
-			{ ...z },
-			{
-				get: (target, prop) => {
-					// @ts-expect-error
-					const value = target[prop];
-
-					if (typeof value === 'function') {
-						return (...args: any[]) => {
-							const schema = value(...args);
-							return this.wrapSchema(schema, name);
-						};
-					}
-
-					if (value && typeof value === 'object') {
-						return new Proxy(value, {
-							get: (nestedTarget, nestedProp) => {
-								const nestedValue =
-									nestedTarget[nestedProp as keyof typeof nestedTarget];
-								if (typeof nestedValue === 'function') {
-									return (...args: any[]) => {
-										const schema = nestedValue(...args);
-										return this.wrapSchema(schema, name);
-									};
-								}
-								return nestedValue;
-							},
-						});
-					}
-
-					return value;
-				},
-			},
-		);
-	};
-
-	/**
-	 * Creates a ConfigParser that will return mock values when parsed.
-	 */
-	create<TReturn extends EmptyObject>(
-		builder: (get: EnvFetcher) => TReturn,
-	): ConfigParser<TReturn> {
-		const config = builder(this.getZodGetter);
-		return new SnifferConfigParser(config, this.accessedVars);
-	}
-
-	/**
-	 * Returns all environment variable names that were accessed.
-	 *
-	 * @param opts.markOptional - When true, optional variables (those accessed
-	 *   via `.optional()` or `.default()`) are suffixed with `?` (e.g. `PORT?`).
-	 */
-	getEnvironmentVariables(opts?: { markOptional?: boolean }): string[] {
-		const vars = Array.from(this.accessedVars).sort();
-		if (!opts?.markOptional) return vars;
-		return vars.map((name) =>
-			this.optionalVars.has(name) ? `${name}?` : name,
-		);
-	}
-
-	/**
-	 * Returns all environment variable names that were accessed via
-	 * `.optional()` or `.default()` — i.e. variables that are not required.
-	 */
-	getOptionalVariables(): string[] {
-		return Array.from(this.optionalVars).sort();
-	}
-}
-
-/**
- * A ConfigParser that always succeeds with mock values.
- */
-class SnifferConfigParser<
-	TResponse extends EmptyObject,
-> extends ConfigParser<TResponse> {
-	override parse(): any {
-		return this.parseWithMocks(this.getConfig());
-	}
-
-	private getConfig(): TResponse {
-		// Access the private config via any cast
-		return (this as any).config;
-	}
-
-	private parseWithMocks<T>(config: T): any {
-		const result: EmptyObject = {};
-
-		if (config && typeof config !== 'object') {
-			return config;
-		}
-
-		for (const key in config) {
-			const schema = config[key];
-
-			if (schema instanceof z.ZodType) {
-				// Use safeParse which will return mock values from our wrapped schema
-				const parsed = schema.safeParse(undefined);
-				result[key] = parsed.success
-					? parsed.data
-					: this.getDefaultForSchema(schema);
-			} else if (schema && typeof schema === 'object') {
-				result[key] = this.parseWithMocks(schema as EmptyObject);
-			}
-		}
-
-		return result;
-	}
-
-	private getDefaultForSchema(schema: z.ZodType): unknown {
-		if (schema instanceof z.ZodString) return '';
-		if (schema instanceof z.ZodNumber) return 0;
-		if (schema instanceof z.ZodBoolean) return false;
-		if (schema instanceof z.ZodArray) return [];
-		if (schema instanceof z.ZodOptional) return undefined;
-		if (schema instanceof z.ZodNullable) return null;
-
-		if (schema instanceof z.ZodObject && schema.shape) {
-			const result: Record<string, unknown> = {};
-			for (const [key, value] of Object.entries(schema.shape)) {
-				if (value instanceof z.ZodType) {
-					result[key] = this.getDefaultForSchema(value);
-				}
-			}
-			return result;
-		}
-
-		return '';
-	}
-}
-
-/**
- * Result of sniffing with fire-and-forget handling.
- */
-export interface SniffResult {
-	/** All environment variable names that were accessed during sniffing */
-	envVars: string[];
-	/**
-	 * Subset of envVars that are optional (accessed via `.optional()` or
-	 * `.default()`). These do not need to be present for the app to start.
-	 */
-	optionalEnvVars: string[];
-	/** Error thrown during sniffing (env vars may still be captured) */
-	error?: Error;
-	/** Unhandled promise rejections captured during sniffing */
-	unhandledRejections: Error[];
-}
-
-/**
- * Options for sniffing with fire-and-forget handling.
- */
-export interface SniffOptions {
-	/**
-	 * Time in milliseconds to wait for fire-and-forget promises to settle.
-	 * Some libraries like better-auth create async operations that may reject
-	 * after the initial event loop tick.
-	 * @default 100
-	 */
-	settleTimeMs?: number;
-}
-
-/**
- * Executes a sniffing operation with fire-and-forget handling.
- *
- * This function:
- * 1. Captures unhandled promise rejections during the operation
- * 2. Waits for async operations to settle before returning
- * 3. Gracefully handles errors without throwing
- *
- * Use this when sniffing environment variables from code that may:
- * - Throw synchronous errors
- * - Create fire-and-forget promises that reject
- * - Have async initialization that may fail
- *
- * @param sniffer - The SnifferEnvironmentParser instance to use
- * @param operation - The async operation to execute (e.g., service.register)
- * @param options - Optional configuration
- * @returns SniffResult with env vars and any errors encountered
- *
- * @example
- * ```typescript
- * const sniffer = new SnifferEnvironmentParser();
- * const result = await sniffWithFireAndForget(sniffer, async () => {
- *   await service.register({ envParser: sniffer });
- * });
- * console.log('Env vars:', result.envVars);
- * console.log('Error:', result.error);
- * console.log('Unhandled rejections:', result.unhandledRejections);
- * ```
- */
-export async function sniffWithFireAndForget(
-	sniffer: SnifferEnvironmentParser,
-	operation: () => unknown | Promise<unknown>,
-	options: SniffOptions = {},
-): Promise<SniffResult> {
-	const { settleTimeMs = 100 } = options;
-	const unhandledRejections: Error[] = [];
-
-	// Capture unhandled rejections during sniffing (fire-and-forget promises)
-	// Libraries like better-auth create async operations that may reject after
-	// the initial event loop tick
-	const captureRejection = (reason: unknown) => {
-		const err = reason instanceof Error ? reason : new Error(String(reason));
-		unhandledRejections.push(err);
-	};
-	process.on('unhandledRejection', captureRejection);
-
-	let error: Error | undefined;
-
-	try {
-		const result = operation();
-
-		// Handle async result
-		if (result && typeof result === 'object' && 'then' in result) {
-			await Promise.resolve(result).catch((e) => {
-				error = e instanceof Error ? e : new Error(String(e));
-			});
-		}
-	} catch (e) {
-		error = e instanceof Error ? e : new Error(String(e));
-	} finally {
-		// Wait for fire-and-forget promises to settle
-		await new Promise((resolve) => setTimeout(resolve, settleTimeMs));
-		process.off('unhandledRejection', captureRejection);
-	}
-
-	return {
-		envVars: sniffer.getEnvironmentVariables(),
-		optionalEnvVars: sniffer.getOptionalVariables(),
-		error,
-		unhandledRejections,
-	};
-}