@geekmidas/envkit 0.0.6 → 0.0.8

package/src/EnvironmentParser.ts

@@ -13,8 +13,12 @@ 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) {}
+  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
@@ -65,6 +69,26 @@ export class ConfigParser<TResponse extends EmptyObject> {
 
     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();
+  }
 }
 
 /**
@@ -87,6 +111,11 @@ export class ConfigParser<TResponse extends EmptyObject> {
  * ```
  */
 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.
    *
@@ -177,6 +206,9 @@ export class EnvironmentParser<T extends EmptyObject> {
    * @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 },
@@ -227,7 +259,24 @@ export class EnvironmentParser<T extends EmptyObject> {
     builder: (get: EnvFetcher) => TReturn,
   ): ConfigParser<TReturn> {
     const config = builder(this.getZodGetter);
-    return new ConfigParser(config);
+    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();
   }
 }
 

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']);
+    });
+  });
 });