@geekmidas/envkit 0.0.7 → 0.0.8

package/src/SnifferEnvironmentParser.ts

@@ -0,0 +1,207 @@
+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();
+
+  /**
+   * Wraps a Zod schema to always return mock values.
+   * This ensures .parse() and .safeParse() never fail.
+   */
+  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),
+          });
+        }
+
+        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-ignore
+          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.
+   */
+  getEnvironmentVariables(): string[] {
+    return Array.from(this.accessedVars).sort();
+  }
+}
+
+/**
+ * A ConfigParser that always succeeds with mock values.
+ */
+class SnifferConfigParser<TResponse extends EmptyObject> extends ConfigParser<TResponse> {
+  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 '';
+  }
+}

package/src/__tests__/EnvironmentParser.spec.ts

@@ -689,4 +689,151 @@ describe('EnvironmentParser', () => {
       expect(_typeCheck2).toBe(true);
     });
   });
+
+  describe('Environment variable tracking', () => {
+    it('should track accessed environment variables', () => {
+      const env = { APP_NAME: 'Test App', PORT: '3000' };
+      const parser = new EnvironmentParser(env);
+
+      const config = parser.create((get) => ({
+        appName: get('APP_NAME').string(),
+        port: get('PORT').string().transform(Number),
+      }));
+
+      const envVars = config.getEnvironmentVariables();
+
+      expect(envVars).toEqual(['APP_NAME', 'PORT']);
+    });
+
+    it('should track variables even when not parsed', () => {
+      const env = {};
+      const parser = new EnvironmentParser(env);
+
+      const config = parser.create((get) => ({
+        database: get('DATABASE_URL').string().optional(),
+        redis: get('REDIS_URL').string().optional(),
+      }));
+
+      // Should track even without calling parse()
+      const envVars = config.getEnvironmentVariables();
+
+      expect(envVars).toEqual(['DATABASE_URL', 'REDIS_URL']);
+    });
+
+    it('should track variables in nested configurations', () => {
+      const env = {
+        DB_HOST: 'localhost',
+        DB_PORT: '5432',
+        API_KEY: 'secret',
+      };
+      const parser = new EnvironmentParser(env);
+
+      const config = parser.create((get) => ({
+        database: {
+          host: get('DB_HOST').string(),
+          port: get('DB_PORT').string().transform(Number),
+        },
+        api: {
+          key: get('API_KEY').string(),
+        },
+      }));
+
+      const envVars = config.getEnvironmentVariables();
+
+      expect(envVars).toEqual(['API_KEY', 'DB_HOST', 'DB_PORT']);
+    });
+
+    it('should return sorted environment variable names', () => {
+      const env = {};
+      const parser = new EnvironmentParser(env);
+
+      const config = parser.create((get) => ({
+        zValue: get('Z_VALUE').string().optional(),
+        aValue: get('A_VALUE').string().optional(),
+        mValue: get('M_VALUE').string().optional(),
+      }));
+
+      const envVars = config.getEnvironmentVariables();
+
+      // Should be sorted alphabetically
+      expect(envVars).toEqual(['A_VALUE', 'M_VALUE', 'Z_VALUE']);
+    });
+
+    it('should deduplicate environment variable names', () => {
+      const env = { SHARED_VAR: 'value' };
+      const parser = new EnvironmentParser(env);
+
+      const config = parser.create((get) => ({
+        value1: get('SHARED_VAR').string(),
+        value2: get('SHARED_VAR').string(),
+        value3: get('SHARED_VAR').string(),
+      }));
+
+      const envVars = config.getEnvironmentVariables();
+
+      // Should only appear once despite being accessed 3 times
+      expect(envVars).toEqual(['SHARED_VAR']);
+    });
+
+    it('should track variables with default values', () => {
+      const env = {};
+      const parser = new EnvironmentParser(env);
+
+      const config = parser.create((get) => ({
+        port: get('PORT').string().default('3000'),
+        host: get('HOST').string().default('localhost'),
+      }));
+
+      const envVars = config.getEnvironmentVariables();
+
+      // Should track even when defaults are used
+      expect(envVars).toEqual(['HOST', 'PORT']);
+    });
+
+    it('should work with empty configuration', () => {
+      const env = {};
+      const parser = new EnvironmentParser(env);
+
+      const config = parser.create(() => ({}));
+
+      const envVars = config.getEnvironmentVariables();
+
+      expect(envVars).toEqual([]);
+    });
+
+    it('should track variables accessed through coerce', () => {
+      const env = { NUM_WORKERS: '4', TIMEOUT: '30000' };
+      const parser = new EnvironmentParser(env);
+
+      const config = parser.create((get) => ({
+        workers: get('NUM_WORKERS').coerce.number(),
+        timeout: get('TIMEOUT').coerce.number(),
+      }));
+
+      const envVars = config.getEnvironmentVariables();
+
+      expect(envVars).toEqual(['NUM_WORKERS', 'TIMEOUT']);
+    });
+
+    it('should track variables with complex transformations', () => {
+      const env = {
+        ALLOWED_ORIGINS: 'http://localhost,https://example.com',
+        FEATURE_FLAGS: 'auth,cache',
+      };
+      const parser = new EnvironmentParser(env);
+
+      const config = parser.create((get) => ({
+        origins: get('ALLOWED_ORIGINS')
+          .string()
+          .transform((v) => v.split(',')),
+        features: get('FEATURE_FLAGS')
+          .string()
+          .transform((v) => v.split(',')),
+      }));
+
+      const envVars = config.getEnvironmentVariables();
+
+      expect(envVars).toEqual(['ALLOWED_ORIGINS', 'FEATURE_FLAGS']);
+    });
+  });
 });

package/src/__tests__/SnifferEnvironmentParser.spec.ts

@@ -0,0 +1,332 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod/v4';
+import { SnifferEnvironmentParser } from '../SnifferEnvironmentParser';
+
+describe('SnifferEnvironmentParser', () => {
+  describe('Environment variable tracking', () => {
+    it('should track accessed environment variables', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      sniffer.create((get) => ({
+        appName: get('APP_NAME').string(),
+        port: get('PORT').string().transform(Number),
+      }));
+
+      const envVars = sniffer.getEnvironmentVariables();
+      expect(envVars).toEqual(['APP_NAME', 'PORT']);
+    });
+
+    it('should track variables in nested configurations', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      sniffer.create((get) => ({
+        database: {
+          host: get('DB_HOST').string(),
+          port: get('DB_PORT').string().transform(Number),
+        },
+        api: {
+          key: get('API_KEY').string(),
+        },
+      }));
+
+      const envVars = sniffer.getEnvironmentVariables();
+      expect(envVars).toEqual(['API_KEY', 'DB_HOST', 'DB_PORT']);
+    });
+
+    it('should return sorted environment variable names', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      sniffer.create((get) => ({
+        zValue: get('Z_VALUE').string(),
+        aValue: get('A_VALUE').string(),
+        mValue: get('M_VALUE').string(),
+      }));
+
+      const envVars = sniffer.getEnvironmentVariables();
+      expect(envVars).toEqual(['A_VALUE', 'M_VALUE', 'Z_VALUE']);
+    });
+
+    it('should deduplicate environment variable names', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      sniffer.create((get) => ({
+        value1: get('SHARED_VAR').string(),
+        value2: get('SHARED_VAR').string(),
+        value3: get('SHARED_VAR').string(),
+      }));
+
+      const envVars = sniffer.getEnvironmentVariables();
+      expect(envVars).toEqual(['SHARED_VAR']);
+    });
+
+    it('should track variables accessed through coerce', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      sniffer.create((get) => ({
+        workers: get('NUM_WORKERS').coerce.number(),
+        timeout: get('TIMEOUT').coerce.number(),
+      }));
+
+      const envVars = sniffer.getEnvironmentVariables();
+      expect(envVars).toEqual(['NUM_WORKERS', 'TIMEOUT']);
+    });
+  });
+
+  describe('Mock value parsing', () => {
+    it('should never throw when parsing - returns mock values', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      const config = sniffer.create((get) => ({
+        required: get('REQUIRED_VAR').string(),
+        alsoRequired: get('ALSO_REQUIRED').string(),
+      }));
+
+      // Should not throw even though env vars are not set
+      expect(() => config.parse()).not.toThrow();
+    });
+
+    it('should return empty string for string schemas', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      const config = sniffer
+        .create((get) => ({
+          value: get('STRING_VAR').string(),
+        }))
+        .parse();
+
+      expect(config.value).toBe('');
+    });
+
+    it('should return 0 for number schemas', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      const config = sniffer
+        .create((get) => ({
+          value: get('NUMBER_VAR').coerce.number(),
+        }))
+        .parse();
+
+      expect(config.value).toBe(0);
+    });
+
+    it('should return false for boolean schemas', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      const config = sniffer
+        .create((get) => ({
+          value: get('BOOL_VAR').coerce.boolean(),
+        }))
+        .parse();
+
+      expect(config.value).toBe(false);
+    });
+
+    it('should return empty array for array schemas', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      const config = sniffer
+        .create((get) => ({
+          value: get('ARRAY_VAR').array(z.string()),
+        }))
+        .parse();
+
+      expect(config.value).toEqual([]);
+    });
+
+    it('should return undefined for optional schemas', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      const config = sniffer
+        .create((get) => ({
+          value: get('OPTIONAL_VAR').string().optional(),
+        }))
+        .parse();
+
+      expect(config.value).toBeUndefined();
+    });
+
+    it('should handle nested configurations', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      const config = sniffer
+        .create((get) => ({
+          database: {
+            host: get('DB_HOST').string(),
+            port: get('DB_PORT').coerce.number(),
+          },
+          cache: {
+            enabled: get('CACHE_ENABLED').coerce.boolean(),
+          },
+        }))
+        .parse();
+
+      expect(config).toEqual({
+        database: {
+          host: '',
+          port: 0,
+        },
+        cache: {
+          enabled: false,
+        },
+      });
+    });
+
+    it('should track variables with transforms', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      sniffer.create((get) => ({
+        origins: get('ALLOWED_ORIGINS')
+          .string()
+          .transform((v) => v.split(',')),
+        port: get('PORT').string().transform(Number),
+      }));
+
+      // Should track the env vars even with transforms
+      expect(sniffer.getEnvironmentVariables()).toEqual([
+        'ALLOWED_ORIGINS',
+        'PORT',
+      ]);
+    });
+  });
+
+  describe('Service registration simulation', () => {
+    it('should allow simulated service registration to succeed', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      // Simulate a service that would normally fail without env vars
+      const mockService = {
+        serviceName: 'database' as const,
+        register(envParser: SnifferEnvironmentParser) {
+          const config = envParser
+            .create((get) => ({
+              url: get('DATABASE_URL').string(),
+              poolSize: get('DB_POOL_SIZE').coerce.number(),
+            }))
+            .parse();
+
+          // Service uses parsed values to create connection
+          return { url: config.url, poolSize: config.poolSize };
+        },
+      };
+
+      // Should not throw
+      expect(() => mockService.register(sniffer)).not.toThrow();
+
+      // Should have tracked the env vars
+      expect(sniffer.getEnvironmentVariables()).toEqual([
+        'DATABASE_URL',
+        'DB_POOL_SIZE',
+      ]);
+    });
+
+    it('should work with multiple services', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      const databaseService = {
+        serviceName: 'db' as const,
+        register(envParser: SnifferEnvironmentParser) {
+          return envParser
+            .create((get) => ({
+              host: get('DB_HOST').string(),
+              port: get('DB_PORT').coerce.number(),
+            }))
+            .parse();
+        },
+      };
+
+      const cacheService = {
+        serviceName: 'cache' as const,
+        register(envParser: SnifferEnvironmentParser) {
+          return envParser
+            .create((get) => ({
+              url: get('REDIS_URL').string(),
+              ttl: get('CACHE_TTL').coerce.number(),
+            }))
+            .parse();
+        },
+      };
+
+      // Register both services
+      databaseService.register(sniffer);
+      cacheService.register(sniffer);
+
+      // Should have tracked all env vars from both services
+      expect(sniffer.getEnvironmentVariables()).toEqual([
+        'CACHE_TTL',
+        'DB_HOST',
+        'DB_PORT',
+        'REDIS_URL',
+      ]);
+    });
+
+    it('should handle async service registration', async () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      const asyncService = {
+        serviceName: 'async' as const,
+        async register(envParser: SnifferEnvironmentParser) {
+          const config = envParser
+            .create((get) => ({
+              apiKey: get('API_KEY').string(),
+              endpoint: get('API_ENDPOINT').string(),
+            }))
+            .parse();
+
+          // Simulate async initialization
+          await Promise.resolve();
+          return config;
+        },
+      };
+
+      await expect(asyncService.register(sniffer)).resolves.not.toThrow();
+      expect(sniffer.getEnvironmentVariables()).toEqual([
+        'API_ENDPOINT',
+        'API_KEY',
+      ]);
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should return empty array when no variables accessed', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      sniffer.create(() => ({}));
+
+      expect(sniffer.getEnvironmentVariables()).toEqual([]);
+    });
+
+    it('should handle deeply nested objects', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      sniffer.create((get) => ({
+        level1: {
+          level2: {
+            level3: {
+              value: get('DEEP_VALUE').string(),
+            },
+          },
+        },
+      }));
+
+      expect(sniffer.getEnvironmentVariables()).toEqual(['DEEP_VALUE']);
+    });
+
+    it('should handle multiple create calls', () => {
+      const sniffer = new SnifferEnvironmentParser();
+
+      sniffer.create((get) => ({
+        first: get('FIRST_VAR').string(),
+      }));
+
+      sniffer.create((get) => ({
+        second: get('SECOND_VAR').string(),
+      }));
+
+      // Should accumulate vars from both create calls
+      expect(sniffer.getEnvironmentVariables()).toEqual([
+        'FIRST_VAR',
+        'SECOND_VAR',
+      ]);
+    });
+  });
+});

package/src/index.ts

@@ -1 +1 @@
-export { EnvironmentParser } from './EnvironmentParser';
+export { EnvironmentParser, ConfigParser } from './EnvironmentParser';