@geekmidas/envkit 0.5.0 → 0.7.0

package/dist/formatter-D85aIkpd.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"formatter-D85aIkpd.d.cts","names":[],"sources":["../src/formatter.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;AAgDgB,UAhDC,aAAA,CAgDe;EAAA;EAAA,MACtB,CAAA,EAAA,OAAA;;AACkB;AAwF5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA1FgB,gBAAA,QACR,CAAA,CAAE,oBACA;;;;iBAwFM,aAAA,CAAA"}
+{"version":3,"file":"formatter-D85aIkpd.d.cts","names":[],"sources":["../src/formatter.ts"],"sourcesContent":[],"mappings":";;;;;;AAKA;AAgDgB,UAhDC,aAAA,CAgDe;EAAA;EAAA,MACtB,CAAA,EAAA,OAAA;;AACkB;AAuF5B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAzFgB,gBAAA,QACR,CAAA,CAAE,oBACA;;;;iBAuFM,aAAA,CAAA"}

package/dist/{formatter-w8Tsccw4.cjs → formatter-HxePpSy2.cjs}

@@ -1,5 +1,3 @@
-const require_chunk = require('./chunk-CUT6urMc.cjs');
-const zod_v4 = require_chunk.__toESM(require("zod/v4"));
 
 //#region src/formatter.ts
 /**
@@ -58,7 +56,7 @@ function formatParseError(error, options = {}) {
 	const invalidVars = [];
 	for (const issue of error.issues) {
 		let envName = "";
-		if (issue.path.length > 0) envName = String(issue.path[0]);
+		if (issue.path.length > 0) envName = issue.path.map(String).join(".");
 		else {
 			const match = issue.message.match(/Environment variable "([^"]+)"/);
 			if (match?.[1]) envName = match[1];
@@ -122,4 +120,4 @@ Object.defineProperty(exports, 'isDevelopment', {
     return isDevelopment;
   }
 });
-//# sourceMappingURL=formatter-w8Tsccw4.cjs.map
+//# sourceMappingURL=formatter-HxePpSy2.cjs.map

package/dist/formatter-HxePpSy2.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter-HxePpSy2.cjs","names":["error: z.ZodError","options: FormatOptions","missingVars: Array<{ name: string; message: string }>","invalidVars: Array<{ name: string; value: unknown; message: string }>","lines: string[]","message: string"],"sources":["../src/formatter.ts"],"sourcesContent":["import type { z } from 'zod/v4';\n\n/**\n * Options for formatting parse errors.\n */\nexport interface FormatOptions {\n\t/** Whether to use colors in output. Defaults to auto-detect TTY. */\n\tcolors?: boolean;\n}\n\n/**\n * ANSI color codes for terminal output.\n */\nconst colors = {\n\treset: '\\x1b[0m',\n\tred: '\\x1b[31m',\n\tyellow: '\\x1b[33m',\n\tcyan: '\\x1b[36m',\n\tdim: '\\x1b[2m',\n\tbold: '\\x1b[1m',\n};\n\n/**\n * Formats a ZodError into a user-friendly string for development.\n *\n * @param error - The ZodError to format\n * @param options - Formatting options\n * @returns Formatted error message\n *\n * @example\n * ```typescript\n * try {\n *   config.parse();\n * } catch (error) {\n *   if (error instanceof ZodError) {\n *     console.error(formatParseError(error));\n *   }\n * }\n * ```\n *\n * Output:\n * ```\n * Environment Configuration Failed\n *\n * Missing Variables:\n *   DATABASE_URL - Required\n *   JWT_SECRET - Required\n *\n * Invalid Values:\n *   NODE_ENV = \"invalid\"\n *     Expected: \"development\" | \"staging\" | \"production\"\n * ```\n */\nexport function formatParseError(\n\terror: z.ZodError,\n\toptions: FormatOptions = {},\n): string {\n\tconst useColors =\n\t\toptions.colors ?? (process.stdout?.isTTY && process.env.NO_COLOR == null);\n\n\tconst c = useColors\n\t\t? colors\n\t\t: { reset: '', red: '', yellow: '', cyan: '', dim: '', bold: '' };\n\n\tconst missingVars: Array<{ name: string; message: string }> = [];\n\tconst invalidVars: Array<{ name: string; value: unknown; message: string }> =\n\t\t[];\n\n\tfor (const issue of error.issues) {\n\t\t// Extract environment variable name from path or message\n\t\tlet envName = '';\n\t\tif (issue.path.length > 0) {\n\t\t\t// Join the full path with '.' to show nested config keys and env var name\n\t\t\tenvName = issue.path.map(String).join('.');\n\t\t} else {\n\t\t\t// Try to extract from message like 'Environment variable \"NAME\": ...'\n\t\t\tconst match = issue.message.match(/Environment variable \"([^\"]+)\"/);\n\t\t\tif (match?.[1]) {\n\t\t\t\tenvName = match[1];\n\t\t\t}\n\t\t}\n\n\t\t// Determine if this is a missing or invalid value\n\t\t// Use type guard for received property\n\t\tconst received = 'received' in issue ? issue.received : undefined;\n\t\tconst isMissing =\n\t\t\tissue.code === 'invalid_type' &&\n\t\t\t(received === 'undefined' || received === 'null');\n\n\t\tif (isMissing) {\n\t\t\tmissingVars.push({\n\t\t\t\tname: envName || 'Unknown',\n\t\t\t\tmessage: cleanMessage(issue.message),\n\t\t\t});\n\t\t} else {\n\t\t\tinvalidVars.push({\n\t\t\t\tname: envName || 'Unknown',\n\t\t\t\tvalue: received,\n\t\t\t\tmessage: cleanMessage(issue.message),\n\t\t\t});\n\t\t}\n\t}\n\n\tconst lines: string[] = [];\n\n\tlines.push('');\n\tlines.push(`${c.red}${c.bold}Environment Configuration Failed${c.reset}`);\n\tlines.push('');\n\n\tif (missingVars.length > 0) {\n\t\tlines.push(`${c.yellow}Missing Variables:${c.reset}`);\n\t\tfor (const v of missingVars) {\n\t\t\tlines.push(`  ${c.cyan}${v.name}${c.reset} ${c.dim}- Required${c.reset}`);\n\t\t}\n\t\tlines.push('');\n\t}\n\n\tif (invalidVars.length > 0) {\n\t\tlines.push(`${c.yellow}Invalid Values:${c.reset}`);\n\t\tfor (const v of invalidVars) {\n\t\t\tconst valueStr =\n\t\t\t\tv.value !== undefined ? ` = ${JSON.stringify(v.value)}` : '';\n\t\t\tlines.push(`  ${c.cyan}${v.name}${c.reset}${valueStr}`);\n\t\t\tlines.push(`    ${c.dim}${v.message}${c.reset}`);\n\t\t}\n\t\tlines.push('');\n\t}\n\n\treturn lines.join('\\n');\n}\n\n/**\n * Cleans up a Zod error message by removing redundant prefixes.\n */\nfunction cleanMessage(message: string): string {\n\t// Remove \"Environment variable \"NAME\": \" prefix if present\n\treturn message.replace(/^Environment variable \"[^\"]+\": /, '');\n}\n\n/**\n * Checks if the current environment is development.\n */\nexport function isDevelopment(): boolean {\n\tconst nodeEnv = process.env.NODE_ENV?.toLowerCase();\n\treturn nodeEnv == null || nodeEnv === 'development' || nodeEnv === 'dev';\n}\n"],"mappings":";;;;;AAaA,MAAM,SAAS;CACd,OAAO;CACP,KAAK;CACL,QAAQ;CACR,MAAM;CACN,KAAK;CACL,MAAM;AACN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCD,SAAgB,iBACfA,OACAC,UAAyB,CAAE,GAClB;CACT,MAAM,YACL,QAAQ,WAAW,QAAQ,QAAQ,SAAS,QAAQ,IAAI,YAAY;CAErE,MAAM,IAAI,YACP,SACA;EAAE,OAAO;EAAI,KAAK;EAAI,QAAQ;EAAI,MAAM;EAAI,KAAK;EAAI,MAAM;CAAI;CAElE,MAAMC,cAAwD,CAAE;CAChE,MAAMC,cACL,CAAE;AAEH,MAAK,MAAM,SAAS,MAAM,QAAQ;EAEjC,IAAI,UAAU;AACd,MAAI,MAAM,KAAK,SAAS,EAEvB,WAAU,MAAM,KAAK,IAAI,OAAO,CAAC,KAAK,IAAI;OACpC;GAEN,MAAM,QAAQ,MAAM,QAAQ,MAAM,iCAAiC;AACnE,OAAI,QAAQ,GACX,WAAU,MAAM;EAEjB;EAID,MAAM,WAAW,cAAc,QAAQ,MAAM;EAC7C,MAAM,YACL,MAAM,SAAS,mBACd,aAAa,eAAe,aAAa;AAE3C,MAAI,UACH,aAAY,KAAK;GAChB,MAAM,WAAW;GACjB,SAAS,aAAa,MAAM,QAAQ;EACpC,EAAC;MAEF,aAAY,KAAK;GAChB,MAAM,WAAW;GACjB,OAAO;GACP,SAAS,aAAa,MAAM,QAAQ;EACpC,EAAC;CAEH;CAED,MAAMC,QAAkB,CAAE;AAE1B,OAAM,KAAK,GAAG;AACd,OAAM,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,KAAK,kCAAkC,EAAE,MAAM,EAAE;AACzE,OAAM,KAAK,GAAG;AAEd,KAAI,YAAY,SAAS,GAAG;AAC3B,QAAM,MAAM,EAAE,EAAE,OAAO,oBAAoB,EAAE,MAAM,EAAE;AACrD,OAAK,MAAM,KAAK,YACf,OAAM,MAAM,IAAI,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,MAAM,GAAG,EAAE,IAAI,YAAY,EAAE,MAAM,EAAE;AAE1E,QAAM,KAAK,GAAG;CACd;AAED,KAAI,YAAY,SAAS,GAAG;AAC3B,QAAM,MAAM,EAAE,EAAE,OAAO,iBAAiB,EAAE,MAAM,EAAE;AAClD,OAAK,MAAM,KAAK,aAAa;GAC5B,MAAM,WACL,EAAE,oBAAuB,KAAK,KAAK,UAAU,EAAE,MAAM,CAAC,IAAI;AAC3D,SAAM,MAAM,IAAI,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE;AACvD,SAAM,MAAM,MAAM,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,EAAE,MAAM,EAAE;EAChD;AACD,QAAM,KAAK,GAAG;CACd;AAED,QAAO,MAAM,KAAK,KAAK;AACvB;;;;AAKD,SAAS,aAAaC,SAAyB;AAE9C,QAAO,QAAQ,QAAQ,mCAAmC,GAAG;AAC7D;;;;AAKD,SAAgB,gBAAyB;CACxC,MAAM,UAAU,QAAQ,IAAI,UAAU,aAAa;AACnD,QAAO,WAAW,QAAQ,YAAY,iBAAiB,YAAY;AACnE"}

package/dist/formatter.cjs

@@ -1,4 +1,4 @@
-const require_formatter = require('./formatter-w8Tsccw4.cjs');
+const require_formatter = require('./formatter-HxePpSy2.cjs');
 
 exports.formatParseError = require_formatter.formatParseError;
 exports.isDevelopment = require_formatter.isDevelopment;

package/dist/formatter.mjs

@@ -1,3 +1,3 @@
-import { formatParseError, isDevelopment } from "./formatter-fz8V7x6i.mjs";
+import { formatParseError, isDevelopment } from "./formatter-BRRrxQi3.mjs";
 
 export { formatParseError, isDevelopment };

package/dist/index.cjs

@@ -1,6 +1,6 @@
 const require_EnvironmentBuilder = require('./EnvironmentBuilder-Djr1VsWM.cjs');
-const require_formatter = require('./formatter-w8Tsccw4.cjs');
-const require_EnvironmentParser = require('./EnvironmentParser-DlWHnhDY.cjs');
+const require_formatter = require('./formatter-HxePpSy2.cjs');
+const require_EnvironmentParser = require('./EnvironmentParser-DJdW7vOL.cjs');
 
 exports.ConfigParser = require_EnvironmentParser.ConfigParser;
 exports.EnvironmentBuilder = require_EnvironmentBuilder.EnvironmentBuilder;

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { EnvironmentBuilder, environmentCase } from "./EnvironmentBuilder-BSuHZm0y.mjs";
-import { formatParseError, isDevelopment } from "./formatter-fz8V7x6i.mjs";
-import { ConfigParser, EnvironmentParser } from "./EnvironmentParser-CBLsPUyQ.mjs";
+import { formatParseError, isDevelopment } from "./formatter-BRRrxQi3.mjs";
+import { ConfigParser, EnvironmentParser } from "./EnvironmentParser-zMblItla.mjs";
 
 export { ConfigParser, EnvironmentBuilder, EnvironmentParser, environmentCase, formatParseError, isDevelopment };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/envkit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "private": false,
   "type": "module",
   "exports": {

package/src/SnifferEnvironmentParser.ts

@@ -207,3 +207,100 @@ class SnifferConfigParser<
 		return '';
 	}
 }
+
+/**
+ * Result of sniffing with fire-and-forget handling.
+ */
+export interface SniffResult {
+	/** Environment variables that were accessed during sniffing */
+	envVars: 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(),
+		error,
+		unhandledRejections,
+	};
+}

package/src/__tests__/SnifferEnvironmentParser.spec.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it } from 'vitest';
 import { z } from 'zod/v4';
-import { SnifferEnvironmentParser } from '../SnifferEnvironmentParser';
+import {
+	SnifferEnvironmentParser,
+	sniffWithFireAndForget,
+} from '../SnifferEnvironmentParser';
 
 describe('SnifferEnvironmentParser', () => {
 	describe('Environment variable tracking', () => {
@@ -384,3 +387,104 @@ describe('SnifferEnvironmentParser', () => {
 		});
 	});
 });
+
+describe('sniffWithFireAndForget', () => {
+	it('should capture environment variables from synchronous operations', async () => {
+		const sniffer = new SnifferEnvironmentParser();
+
+		const result = await sniffWithFireAndForget(sniffer, () => {
+			sniffer.create((get) => ({
+				dbUrl: get('DATABASE_URL').string(),
+				apiKey: get('API_KEY').string(),
+			}));
+		});
+
+		expect(result.envVars).toEqual(['API_KEY', 'DATABASE_URL']);
+		expect(result.error).toBeUndefined();
+		expect(result.unhandledRejections).toEqual([]);
+	});
+
+	it('should capture environment variables from async operations', async () => {
+		const sniffer = new SnifferEnvironmentParser();
+
+		const result = await sniffWithFireAndForget(sniffer, async () => {
+			await Promise.resolve();
+			sniffer.create((get) => ({
+				redisUrl: get('REDIS_URL').string(),
+			}));
+		});
+
+		expect(result.envVars).toEqual(['REDIS_URL']);
+		expect(result.error).toBeUndefined();
+	});
+
+	it('should capture error when operation throws synchronously', async () => {
+		const sniffer = new SnifferEnvironmentParser();
+
+		const result = await sniffWithFireAndForget(sniffer, () => {
+			sniffer.create((get) => ({
+				value: get('CAPTURED_BEFORE_ERROR').string(),
+			}));
+			throw new Error('Sync error');
+		});
+
+		// Should still capture env vars accessed before the error
+		expect(result.envVars).toEqual(['CAPTURED_BEFORE_ERROR']);
+		expect(result.error).toBeInstanceOf(Error);
+		expect(result.error?.message).toBe('Sync error');
+	});
+
+	it('should capture error when async operation rejects', async () => {
+		const sniffer = new SnifferEnvironmentParser();
+
+		const result = await sniffWithFireAndForget(sniffer, async () => {
+			sniffer.create((get) => ({
+				value: get('CAPTURED_BEFORE_REJECT').string(),
+			}));
+			throw new Error('Async rejection');
+		});
+
+		expect(result.envVars).toEqual(['CAPTURED_BEFORE_REJECT']);
+		expect(result.error).toBeInstanceOf(Error);
+		expect(result.error?.message).toBe('Async rejection');
+	});
+
+	it('should convert non-Error throws to Error objects', async () => {
+		const sniffer = new SnifferEnvironmentParser();
+
+		const result = await sniffWithFireAndForget(sniffer, () => {
+			throw 'string error';
+		});
+
+		expect(result.error).toBeInstanceOf(Error);
+		expect(result.error?.message).toBe('string error');
+	});
+
+	it('should use custom settle time', async () => {
+		const sniffer = new SnifferEnvironmentParser();
+		const startTime = Date.now();
+
+		await sniffWithFireAndForget(
+			sniffer,
+			() => {},
+			{ settleTimeMs: 50 },
+		);
+
+		const elapsed = Date.now() - startTime;
+		// Should wait at least 50ms but not much longer
+		expect(elapsed).toBeGreaterThanOrEqual(50);
+		expect(elapsed).toBeLessThan(200);
+	});
+
+	it('should return empty arrays when no vars accessed and no errors', async () => {
+		const sniffer = new SnifferEnvironmentParser();
+
+		const result = await sniffWithFireAndForget(sniffer, () => {
+			// Do nothing
+		});
+
+		expect(result.envVars).toEqual([]);
+		expect(result.error).toBeUndefined();
+		expect(result.unhandledRejections).toEqual([]);
+	});
+});

package/src/__tests__/formatter.spec.ts

@@ -102,6 +102,23 @@ describe('formatParseError', () => {
 		expect(formatted).toContain('Expected number, received string');
 	});
 
+	it('should join nested paths with dot', () => {
+		const error = new z.ZodError([
+			createIssue({
+				code: 'invalid_type',
+				expected: 'string',
+				received: 'undefined',
+				path: ['databaseUrl', 'DATABASE_URL'],
+				message: 'Environment variable "DATABASE_URL": Required',
+			}),
+		]);
+
+		const formatted = formatParseError(error, { colors: false });
+
+		// Should show the full path joined with '.'
+		expect(formatted).toContain('databaseUrl.DATABASE_URL');
+	});
+
 	it('should extract env name from message when path is empty', () => {
 		const error = new z.ZodError([
 			createIssue({

package/src/formatter.ts

@@ -1,4 +1,4 @@
-import { z } from 'zod/v4';
+import type { z } from 'zod/v4';
 
 /**
  * Options for formatting parse errors.
@@ -70,7 +70,8 @@ export function formatParseError(
 		// Extract environment variable name from path or message
 		let envName = '';
 		if (issue.path.length > 0) {
-			envName = String(issue.path[0]);
+			// Join the full path with '.' to show nested config keys and env var name
+			envName = issue.path.map(String).join('.');
 		} else {
 			// Try to extract from message like 'Environment variable "NAME": ...'
 			const match = issue.message.match(/Environment variable "([^"]+)"/);
@@ -103,9 +104,7 @@ export function formatParseError(
 	const lines: string[] = [];
 
 	lines.push('');
-	lines.push(
-		`${c.red}${c.bold}Environment Configuration Failed${c.reset}`,
-	);
+	lines.push(`${c.red}${c.bold}Environment Configuration Failed${c.reset}`);
 	lines.push('');
 
 	if (missingVars.length > 0) {