@geekmidas/envkit 0.0.8 → 0.1.0

package/dist/sst.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sst.mjs","names":["name: string","value: Secret","key: string","value: Postgres","value: Bucket","value: any","processors: Record<ResourceType, ResourceProcessor<any>>","record: Record<string, Resource | string>","env: Record<string, string>"],"sources":["../src/sst.ts"],"sourcesContent":["import snakecase from 'lodash.snakecase';\n\n/**\n * Converts a string to environment variable case format (UPPER_SNAKE_CASE).\n * Numbers following underscores are preserved without the underscore.\n *\n * @param name - The string to convert\n * @returns The converted string in environment variable format\n *\n * @example\n * environmentCase('myVariable') // 'MY_VARIABLE'\n * environmentCase('api_v2') // 'APIV2'\n */\nexport function environmentCase(name: string) {\n  return snakecase(name)\n    .toUpperCase()\n    .replace(/_\\d+/g, (r) => {\n      return r.replace('_', '');\n    });\n}\n\n/**\n * Enumeration of supported SST (Serverless Stack Toolkit) resource types.\n * Used to identify and process different AWS and SST resources.\n */\nexport enum ResourceType {\n  ApiGatewayV2 = 'sst.aws.ApiGatewayV2',\n  Postgres = 'sst.aws.Postgres',\n  Function = 'sst.aws.Function',\n  Bucket = 'sst.aws.Bucket',\n  Vpc = 'sst.aws.Vpc',\n  Secret = 'sst.sst.Secret',\n  SSTSecret = 'sst:sst:Secret',\n  SSTFunction = 'sst:sst:Function',\n  SSTApiGatewayV2 = 'sst:aws:ApiGatewayV2',\n  SSTPostgres = 'sst:aws:Postgres',\n  SSTBucket = 'sst:aws:Bucket',\n}\n\n/**\n * Processes a Secret resource into environment variables.\n *\n * @param name - The resource name\n * @param value - The Secret resource\n * @returns Object with environment variable mappings\n */\nconst secret = (name: string, value: Secret) => ({\n  [environmentCase(name)]: value.value,\n});\n/**\n * Processes a Postgres database resource into environment variables.\n * Creates multiple environment variables for database connection details.\n *\n * @param key - The resource key\n * @param value - The Postgres resource\n * @returns Object with database connection environment variables\n */\nconst postgres = (key: string, value: Postgres) => {\n  const prefix = `${environmentCase(key)}`;\n  return {\n    [`${prefix}_NAME`]: value.database,\n    [`${prefix}_HOST`]: value.host,\n    [`${prefix}_PASSWORD`]: value.password,\n    [`${prefix}_PORT`]: value.port,\n    [`${prefix}_USERNAME`]: value.username,\n  };\n};\n\n/**\n * Processes a Bucket resource into environment variables.\n *\n * @param name - The resource name\n * @param value - The Bucket resource\n * @returns Object with bucket name environment variable\n */\nconst bucket = (name: string, value: Bucket) => {\n  const prefix = `${environmentCase(name)}`;\n  return {\n    [`${prefix}_NAME`]: value.name,\n  };\n};\n\n/**\n * No-operation processor for resources that don't require environment variables.\n *\n * @param name - The resource name (unused)\n * @param value - The resource value (unused)\n * @returns Empty object\n */\nconst noop = (name: string, value: any) => ({});\n\n/**\n * Map of resource types to their corresponding processor functions.\n * Each processor converts resource data into environment variables.\n */\nconst processors: Record<ResourceType, ResourceProcessor<any>> = {\n  [ResourceType.ApiGatewayV2]: noop,\n  [ResourceType.Function]: noop,\n  [ResourceType.Vpc]: noop,\n  [ResourceType.Secret]: secret,\n  [ResourceType.Postgres]: postgres,\n  [ResourceType.Bucket]: bucket,\n\n  [ResourceType.SSTSecret]: secret,\n  [ResourceType.SSTBucket]: bucket,\n  [ResourceType.SSTFunction]: noop,\n  [ResourceType.SSTPostgres]: postgres,\n  [ResourceType.SSTApiGatewayV2]: noop,\n};\n\n/**\n * Normalizes SST resources and plain strings into environment variables.\n * Processes resources based on their type and converts names to environment case.\n *\n * @param record - Object containing resources and/or string values\n * @returns Normalized environment variables object\n *\n * @example\n * normalizeResourceEnv({\n *   apiUrl: 'https://api.example.com',\n *   database: { type: ResourceType.Postgres, ... }\n * })\n */\nexport function normalizeResourceEnv(\n  record: Record<string, Resource | string>,\n): Record<string, string> {\n  const env: Record<string, string> = {};\n  for (const [k, value] of Object.entries(record)) {\n    if (typeof value === 'string') {\n      env[environmentCase(k)] = value;\n      continue;\n    }\n\n    const processor = processors[value.type];\n    if (processor) {\n      Object.assign(env, processor(k, value));\n    } else {\n      console.warn(`No processor found for resource type: `, { value });\n    }\n  }\n\n  return env;\n}\n\n/**\n * AWS API Gateway V2 resource type.\n * Represents an HTTP/WebSocket API.\n */\nexport type ApiGatewayV2 = {\n  type: ResourceType.ApiGatewayV2;\n  url: string;\n};\n\n/**\n * PostgreSQL database resource type.\n * Contains all connection details needed to connect to the database.\n */\nexport type Postgres = {\n  database: string;\n  host: string;\n  password: string;\n  port: number;\n  type: ResourceType.Postgres;\n  username: string;\n};\n\n/**\n * AWS Lambda Function resource type.\n */\nexport type Function = {\n  name: string;\n  type: ResourceType.Function;\n};\n\n/**\n * AWS S3 Bucket resource type.\n */\nexport type Bucket = {\n  name: string;\n  type: ResourceType.Bucket;\n};\n\n/**\n * AWS VPC (Virtual Private Cloud) resource type.\n */\nexport type Vpc = {\n  bastion: string;\n  type: ResourceType.Vpc;\n};\n\n/**\n * Secret resource type for storing sensitive values.\n */\nexport type Secret = {\n  type: ResourceType.Secret;\n  value: string;\n};\n\n/**\n * Union type of all supported SST resource types.\n */\nexport type Resource =\n  | ApiGatewayV2\n  | Postgres\n  | Function\n  | Bucket\n  | Vpc\n  | Secret;\n\n/**\n * Function type for processing a specific resource type into environment variables.\n *\n * @template K - The specific resource type\n * @param name - The resource name\n * @param value - The resource value\n * @returns Object mapping environment variable names to values\n */\nexport type ResourceProcessor<K extends Resource> = (\n  name: string,\n  value: K,\n) => Record<string, string | number>;\n"],"mappings":";;;;;;;;;;;;;;AAaA,SAAgB,gBAAgBA,MAAc;AAC5C,QAAO,UAAU,KAAK,CACnB,aAAa,CACb,QAAQ,SAAS,CAAC,MAAM;AACvB,SAAO,EAAE,QAAQ,KAAK,GAAG;CAC1B,EAAC;AACL;;;;;AAMD,IAAY,wDAAL;AACL;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;;AACD;;;;;;;;AASD,MAAM,SAAS,CAACA,MAAcC,WAAmB,GAC9C,gBAAgB,KAAK,GAAG,MAAM,MAChC;;;;;;;;;AASD,MAAM,WAAW,CAACC,KAAaC,UAAoB;CACjD,MAAM,UAAU,EAAE,gBAAgB,IAAI,CAAC;AACvC,QAAO;IACH,EAAE,OAAO,SAAS,MAAM;IACxB,EAAE,OAAO,SAAS,MAAM;IACxB,EAAE,OAAO,aAAa,MAAM;IAC5B,EAAE,OAAO,SAAS,MAAM;IACxB,EAAE,OAAO,aAAa,MAAM;CAC/B;AACF;;;;;;;;AASD,MAAM,SAAS,CAACH,MAAcI,UAAkB;CAC9C,MAAM,UAAU,EAAE,gBAAgB,KAAK,CAAC;AACxC,QAAO,IACH,EAAE,OAAO,SAAS,MAAM,KAC3B;AACF;;;;;;;;AASD,MAAM,OAAO,CAACJ,MAAcK,WAAgB,CAAE;;;;;AAM9C,MAAMC,aAA2D;EAC9D,aAAa,eAAe;EAC5B,aAAa,WAAW;EACxB,aAAa,MAAM;EACnB,aAAa,SAAS;EACtB,aAAa,WAAW;EACxB,aAAa,SAAS;EAEtB,aAAa,YAAY;EACzB,aAAa,YAAY;EACzB,aAAa,cAAc;EAC3B,aAAa,cAAc;EAC3B,aAAa,kBAAkB;AACjC;;;;;;;;;;;;;;AAeD,SAAgB,qBACdC,QACwB;CACxB,MAAMC,MAA8B,CAAE;AACtC,MAAK,MAAM,CAAC,GAAG,MAAM,IAAI,OAAO,QAAQ,OAAO,EAAE;AAC/C,aAAW,UAAU,UAAU;AAC7B,OAAI,gBAAgB,EAAE,IAAI;AAC1B;EACD;EAED,MAAM,YAAY,WAAW,MAAM;AACnC,MAAI,UACF,QAAO,OAAO,KAAK,UAAU,GAAG,MAAM,CAAC;MAEvC,SAAQ,MAAM,yCAAyC,EAAE,MAAO,EAAC;CAEpE;AAED,QAAO;AACR"}
+{"version":3,"file":"sst.mjs","names":["record: Record<string, SstResource | string>"],"sources":["../src/sst.ts"],"sourcesContent":["// Re-export everything from SstEnvironmentBuilder\nexport {\n  SstEnvironmentBuilder,\n  sstResolvers,\n  ResourceType,\n  type ApiGatewayV2,\n  type Postgres,\n  type Function,\n  type Bucket,\n  type Vpc,\n  type Secret,\n  type SnsTopic,\n  type SstResource,\n  type ResourceProcessor,\n} from './SstEnvironmentBuilder';\n\n// Re-export environmentCase from EnvironmentBuilder\nexport { environmentCase } from './EnvironmentBuilder';\n\n// Re-export types from EnvironmentBuilder\nexport type {\n  EnvRecord,\n  EnvValue,\n  EnvironmentBuilderOptions,\n} from './EnvironmentBuilder';\n\n// Import for deprecated function\nimport {\n  SstEnvironmentBuilder,\n  type SstResource,\n} from './SstEnvironmentBuilder';\n\n/**\n * @deprecated Use `new SstEnvironmentBuilder(record).build()` instead.\n *\n * Normalizes SST resources and plain strings into environment variables.\n * Processes resources based on their type and converts names to environment case.\n *\n * @param record - Object containing resources and/or string values\n * @returns Normalized environment variables object\n *\n * @example\n * // Old usage (deprecated):\n * normalizeResourceEnv({ database: postgresResource })\n *\n * // New usage:\n * new SstEnvironmentBuilder({ database: postgresResource }).build()\n */\nexport function normalizeResourceEnv(\n  record: Record<string, SstResource | string>,\n): Record<string, string | number | boolean | Record<string, unknown>> {\n  return new SstEnvironmentBuilder(record).build();\n}\n\n// Keep Resource type as deprecated alias for backwards compatibility\n/**\n * @deprecated Use `SstResource` instead.\n */\nexport type Resource = SstResource;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAgDA,SAAgB,qBACdA,QACqE;AACrE,QAAO,IAAI,sBAAsB,QAAQ,OAAO;AACjD"}

package/docs/async-secrets-design.md

@@ -0,0 +1,355 @@
+# 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/envkit",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -20,6 +20,10 @@
       "require": "./dist/SnifferEnvironmentParser.cjs"
     }
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geekmidas/toolbox"
+  },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
@@ -30,7 +34,7 @@
     "lodash.snakecase": "~4.1.1"
   },
   "peerDependencies": {
-    "zod": "~3.25.67"
+    "zod": "~4.1.13"
   },
   "devDependencies": {
     "@types/lodash.set": "~4.3.9",

package/src/EnvironmentBuilder.ts

@@ -0,0 +1,196 @@
+import snakecase from 'lodash.snakecase';
+
+/**
+ * Converts a string to environment variable case format (UPPER_SNAKE_CASE).
+ * Numbers following underscores are preserved without the underscore.
+ *
+ * @param name - The string to convert
+ * @returns The converted string in environment variable format
+ *
+ * @example
+ * environmentCase('myVariable') // 'MY_VARIABLE'
+ * environmentCase('apiV2') // 'APIV2'
+ */
+export function environmentCase(name: string): string {
+  return snakecase(name)
+    .toUpperCase()
+    .replace(/_\d+/g, (r) => {
+      return r.replace('_', '');
+    });
+}
+
+/**
+ * A record of environment variable names to their values.
+ * Values can be primitives or nested records.
+ */
+export interface EnvRecord {
+  [key: string]: EnvValue;
+}
+
+/**
+ * Represents a value that can be stored in an environment record.
+ * Can be a primitive value or a nested record of environment values.
+ */
+export type EnvValue = string | number | boolean | EnvRecord;
+
+/**
+ * A resolver function that converts a typed value into environment variables.
+ *
+ * @template T - The type of value this resolver handles (without the `type` key)
+ * @param key - The key name from the input record
+ * @param value - The value to resolve (without the `type` key)
+ * @returns A record of environment variable names to their values
+ */
+export type EnvironmentResolver<T = any> = (key: string, value: T) => EnvRecord;
+
+/**
+ * A map of type discriminator strings to their resolver functions.
+ */
+export type Resolvers = Record<string, EnvironmentResolver<any>>;
+
+/**
+ * Options for configuring the EnvironmentBuilder.
+ */
+export interface EnvironmentBuilderOptions {
+  /**
+   * Handler called when a value's type doesn't match any registered resolver.
+   * Defaults to console.warn.
+   */
+  onUnmatchedValue?: (key: string, value: unknown) => void;
+}
+
+/**
+ * Input value type - either a string or an object with a `type` discriminator.
+ */
+export type InputValue = string | { type: string; [key: string]: unknown };
+
+/**
+ * Base type for typed input values with a specific type discriminator.
+ */
+export type TypedInputValue<TType extends string = string> = {
+  type: TType;
+  [key: string]: unknown;
+};
+
+/**
+ * Extracts the `type` string value from an input value.
+ */
+type ExtractType<T> = T extends { type: infer U extends string } ? U : never;
+
+/**
+ * Removes the `type` key from an object type.
+ */
+type OmitType<T> = T extends { type: string } ? Omit<T, 'type'> : never;
+
+/**
+ * Extracts all unique `type` values from a record (excluding plain strings).
+ */
+type AllTypeValues<TRecord extends Record<string, InputValue>> = {
+  [K in keyof TRecord]: ExtractType<TRecord[K]>;
+}[keyof TRecord];
+
+/**
+ * For a given type value, finds the corresponding value type (without `type` key).
+ */
+type ValueForType<
+  TRecord extends Record<string, InputValue>,
+  TType extends string,
+> = {
+  [K in keyof TRecord]: TRecord[K] extends { type: TType }
+    ? OmitType<TRecord[K]>
+    : never;
+}[keyof TRecord];
+
+/**
+ * Generates typed resolvers based on the input record.
+ * Keys are the `type` values, values are resolver functions receiving the value without `type`.
+ */
+export type TypedResolvers<TRecord extends Record<string, InputValue>> = {
+  [TType in AllTypeValues<TRecord>]: EnvironmentResolver<
+    ValueForType<TRecord, TType>
+  >;
+};
+
+/**
+ * A generic, extensible class for building environment variables from
+ * objects with type-discriminated values.
+ *
+ * @template TRecord - The input record type for type inference
+ * @template TResolvers - The resolvers type (defaults to TypedResolvers<TRecord>)
+ *
+ * @example
+ * ```typescript
+ * const env = new EnvironmentBuilder(
+ *   {
+ *     apiKey: { type: 'secret', value: 'xyz' },
+ *     appName: 'my-app'
+ *   },
+ *   {
+ *     // `value` is typed as { value: string } (without `type`)
+ *     secret: (key, value) => ({ [key]: value.value }),
+ *   }
+ * ).build();
+ * // { API_KEY: 'xyz', APP_NAME: 'my-app' }
+ * ```
+ */
+export class EnvironmentBuilder<
+  TRecord extends Record<string, InputValue> = Record<string, InputValue>,
+  TResolvers extends Resolvers = TypedResolvers<TRecord>,
+> {
+  private readonly record: TRecord;
+  private readonly resolvers: TResolvers;
+  private readonly options: Required<EnvironmentBuilderOptions>;
+
+  constructor(
+    record: TRecord,
+    resolvers: TResolvers,
+    options: EnvironmentBuilderOptions = {},
+  ) {
+    this.record = record;
+    this.resolvers = resolvers;
+    this.options = {
+      onUnmatchedValue:
+        options.onUnmatchedValue ??
+        ((key, value) => {
+          console.warn(`No resolver found for key "${key}":`, { value });
+        }),
+    };
+  }
+
+  /**
+   * Build environment variables from the input record.
+   *
+   * - Plain string values are passed through with key transformation
+   * - Object values with a `type` property are matched against resolvers
+   * - Resolvers receive values without the `type` key
+   * - Only root-level keys are transformed to UPPER_SNAKE_CASE
+   *
+   * @returns A record of environment variables
+   */
+  build(): EnvRecord {
+    const env: EnvRecord = {};
+
+    for (const [key, value] of Object.entries(this.record)) {
+      // Handle plain string values
+      if (typeof value === 'string') {
+        env[environmentCase(key)] = value;
+        continue;
+      }
+
+      // Handle objects with type discriminator
+      const { type, ...rest } = value;
+      const resolver = this.resolvers[type];
+      if (resolver) {
+        const resolved = resolver(key, rest);
+        // Transform only root-level keys from resolver output
+        for (const [resolvedKey, resolvedValue] of Object.entries(resolved)) {
+          env[environmentCase(resolvedKey)] = resolvedValue;
+        }
+      } else {
+        this.options.onUnmatchedValue(key, value);
+      }
+    }
+
+    return env;
+  }
+}

package/src/SnifferEnvironmentParser.ts

@@ -24,9 +24,7 @@ import {
  * const envVars = sniffer.getEnvironmentVariables(); // ['DATABASE_URL', 'API_KEY']
  * ```
  */
-export class SnifferEnvironmentParser<
-  T extends EmptyObject = EmptyObject,
-> {
+export class SnifferEnvironmentParser<T extends EmptyObject = EmptyObject> {
   private readonly accessedVars: Set<string> = new Set();
 
   /**
@@ -152,7 +150,9 @@ export class SnifferEnvironmentParser<
 /**
  * A ConfigParser that always succeeds with mock values.
  */
-class SnifferConfigParser<TResponse extends EmptyObject> extends ConfigParser<TResponse> {
+class SnifferConfigParser<
+  TResponse extends EmptyObject,
+> extends ConfigParser<TResponse> {
   parse(): any {
     return this.parseWithMocks(this.getConfig());
   }
@@ -175,7 +175,9 @@ class SnifferConfigParser<TResponse extends EmptyObject> extends ConfigParser<TR
       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);
+        result[key] = parsed.success
+          ? parsed.data
+          : this.getDefaultForSchema(schema);
       } else if (schema && typeof schema === 'object') {
         result[key] = this.parseWithMocks(schema as EmptyObject);
       }