@geekmidas/envkit 0.0.8 → 0.1.0

package/README.md

@@ -1,84 +1,51 @@
 # @geekmidas/envkit
 
-A type-safe environment configuration parser that uses Zod schemas to validate and parse environment variables or configuration objects.
+Type-safe environment configuration utilities for parsing environment variables and building environment records from typed resources.
 
 ## Features
 
-- 🔒 **Type-safe**: Full TypeScript support with automatic type inference
-- ✅ **Schema validation**: Uses Zod schemas for robust validation
-- 🏗️ **Nested configuration**: Support for complex, nested configuration structures
-- 🚨 **Error aggregation**: Collects and reports all validation errors at once
-- 🔍 **Path-based access**: Uses lodash's `get` and `set` for deep object access
-- 🎯 **Zero dependencies**: Only depends on Zod and minimal lodash utilities
+- **EnvironmentParser**: Parse and validate environment variables with Zod schemas
+- **EnvironmentBuilder**: Build environment records from type-discriminated objects
+- **SstEnvironmentBuilder**: SST-specific builder with built-in resolvers for AWS resources
+- Full TypeScript support with automatic type inference
+- Nested configuration support
+- Error aggregation and reporting
 
 ## Installation
 
 ```bash
-npm install @geekmidas/envkit zod
-# or
-yarn add @geekmidas/envkit zod
-# or
 pnpm add @geekmidas/envkit zod
 ```
 
-## Quick Start
+## EnvironmentParser
+
+Parse and validate environment variables using Zod schemas.
+
+### Basic Usage
 
 ```typescript
 import { EnvironmentParser } from '@geekmidas/envkit';
-import { z } from 'zod';
 
-// Create parser with your config object (e.g., process.env)
 const parser = new EnvironmentParser(process.env);
 
-// Define your configuration schema
 const config = parser.create((get) => ({
   port: get('PORT').string().transform(Number).default(3000),
   database: {
     host: get('DATABASE_HOST').string(),
     port: get('DATABASE_PORT').string().transform(Number),
     name: get('DATABASE_NAME').string(),
-    user: get('DATABASE_USER').string(),
-    password: get('DATABASE_PASSWORD').string()
   },
   api: {
     key: get('API_KEY').string().min(32),
     url: get('API_URL').url(),
-    timeout: get('API_TIMEOUT').string().transform(Number).default(5000)
   }
 }));
 
-// Parse and validate
-try {
-  const parsedConfig = config.parse();
-  console.log('Configuration loaded successfully:', parsedConfig);
-} catch (error) {
-  console.error('Configuration validation failed:', error);
-  process.exit(1);
-}
-```
-
-## Usage
-
-### Basic Configuration
-
-The simplest use case is parsing flat environment variables:
-
-```typescript
-const parser = new EnvironmentParser(process.env);
-
-const config = parser.create((get) => ({
-  appName: get('APP_NAME').string(),
-  port: get('PORT').string().transform(Number),
-  isProduction: get('NODE_ENV').string().transform(env => env === 'production')
-}));
-
-const { appName, port, isProduction } = config.parse();
+const parsedConfig = config.parse();
 ```
 
 ### Nested Configuration
 
-Create deeply nested configuration structures:
-
 ```typescript
 const config = parser.create((get) => ({
   server: {
@@ -87,79 +54,25 @@ const config = parser.create((get) => ({
     ssl: {
       enabled: get('SSL_ENABLED').string().transform(v => v === 'true'),
       certPath: get('SSL_CERT_PATH').string().optional(),
-      keyPath: get('SSL_KEY_PATH').string().optional()
-    }
-  },
-  features: {
-    authentication: get('FEATURE_AUTH').string().transform(v => v === 'true'),
-    rateLimit: get('FEATURE_RATE_LIMIT').string().transform(v => v === 'true'),
-    cache: {
-      enabled: get('CACHE_ENABLED').string().transform(v => v === 'true'),
-      ttl: get('CACHE_TTL').string().transform(Number).default(3600)
     }
   }
 }));
 ```
 
-### Using Different Config Sources
-
-While `process.env` is the most common source, you can use any object:
-
-```typescript
-// From a JSON file
-import configJson from './config.json';
-const parser = new EnvironmentParser(configJson);
-
-// From a custom object
-const customConfig = {
-  API_URL: 'https://api.example.com',
-  API_KEY: 'secret-key-123'
-};
-const parser = new EnvironmentParser(customConfig);
-
-// Combining multiple sources
-const mergedConfig = {
-  ...defaultConfig,
-  ...process.env
-};
-const parser = new EnvironmentParser(mergedConfig);
-```
-
-### Advanced Validation
-
-Leverage Zod's full validation capabilities:
-
-```typescript
-const config = parser.create((get) => ({
-  email: get('ADMIN_EMAIL').string().email(),
-  webhook: get('WEBHOOK_URL').url(),
-  retries: get('MAX_RETRIES').string().transform(Number).int().min(0).max(10),
-  allowedOrigins: get('ALLOWED_ORIGINS')
-    .string()
-    .transform(origins => origins.split(','))
-    .refine(origins => origins.every(o => o.startsWith('http')), {
-      message: 'All origins must be valid URLs'
-    }),
-  logLevel: get('LOG_LEVEL')
-    .enum(['debug', 'info', 'warn', 'error'])
-    .default('info')
-}));
-```
-
 ### Error Handling
 
-The parser aggregates all validation errors and throws a single `ZodError`:
+The parser aggregates all validation errors:
 
 ```typescript
+import { z } from 'zod';
+
 try {
   const config = parser.create((get) => ({
     required1: get('MISSING_VAR_1').string(),
     required2: get('MISSING_VAR_2').string(),
-    invalid: get('INVALID_NUMBER').string().transform(Number)
   })).parse();
 } catch (error) {
   if (error instanceof z.ZodError) {
-    console.error('Configuration errors:');
     error.errors.forEach(err => {
       console.error(`- ${err.path.join('.')}: ${err.message}`);
     });
@@ -167,129 +80,270 @@ try {
 }
 ```
 
-### Type Safety
+## EnvironmentBuilder
 
-The parsed configuration is fully typed:
+A generic builder for creating environment variables from objects with type-discriminated values.
+
+### Basic Usage
 
 ```typescript
-const config = parser.create((get) => ({
-  port: get('PORT').string().transform(Number),
-  features: {
-    auth: get('FEATURE_AUTH').string().transform(v => v === 'true')
+import { EnvironmentBuilder } from '@geekmidas/envkit';
+
+const env = new EnvironmentBuilder(
+  {
+    apiKey: { type: 'secret', value: 'xyz' },
+    appName: 'my-app',
+  },
+  {
+    // Resolver receives value without 'type' key
+    secret: (key, value) => ({ [key]: value.value }),
   }
-}));
+).build();
 
-const parsed = config.parse();
-// TypeScript knows: parsed.port is number, parsed.features.auth is boolean
+// Result: { API_KEY: 'xyz', APP_NAME: 'my-app' }
 ```
 
-## API Reference
+### How It Works
 
-### `EnvironmentParser`
+1. **Plain string values** are passed through with key transformation to `UPPER_SNAKE_CASE`
+2. **Object values** with a `type` property are matched against resolvers
+3. **Resolvers** receive values without the `type` key
+4. **Root-level keys** from resolver output are transformed to `UPPER_SNAKE_CASE`
 
-The main class for creating configuration parsers.
-
-#### Constructor
+### Multiple Resolvers
 
 ```typescript
-new EnvironmentParser(config: Record<string, unknown>)
+const env = new EnvironmentBuilder(
+  {
+    secret: { type: 'secret', value: 'my-secret' },
+    database: { type: 'postgres', host: 'localhost', port: 5432 },
+    bucket: { type: 'bucket', name: 'my-bucket' },
+  },
+  {
+    secret: (key, value) => ({ [key]: value.value }),
+    postgres: (key, value) => ({
+      [`${key}Host`]: value.host,
+      [`${key}Port`]: value.port,
+    }),
+    bucket: (key, value) => ({ [`${key}Name`]: value.name }),
+  }
+).build();
+
+// Result:
+// {
+//   SECRET: 'my-secret',
+//   DATABASE_HOST: 'localhost',
+//   DATABASE_PORT: 5432,
+//   BUCKET_NAME: 'my-bucket',
+// }
 ```
 
-- `config`: The configuration object to parse (typically `process.env`)
+### Typed Resolvers
+
+Resolver keys and values are type-checked based on the input record:
 
-#### Methods
+```typescript
+const env = new EnvironmentBuilder(
+  {
+    auth: { type: 'auth0' as const, domain: 'example.auth0.com', clientId: 'abc' },
+  },
+  {
+    // TypeScript enforces 'auth0' resolver exists and value has correct shape
+    auth0: (key, value) => ({
+      [`${key}Domain`]: value.domain,
+      [`${key}ClientId`]: value.clientId,
+    }),
+  }
+).build();
+
+// Result: { AUTH_DOMAIN: 'example.auth0.com', AUTH_CLIENT_ID: 'abc' }
+```
 
-##### `create<T>(schemaBuilder: (get: GetFunction) => T): ConfigParser<T>`
+### Handling Unmatched Values
 
-Creates a configuration parser with the specified schema.
+```typescript
+const env = new EnvironmentBuilder(
+  { unknown: { type: 'unknown-type', data: 'test' } },
+  {},
+  {
+    onUnmatchedValue: (key, value) => {
+      console.warn(`No resolver for "${key}":`, value);
+    },
+  }
+).build();
+```
 
-- `schemaBuilder`: A function that receives a `get` function and returns the schema definition
-- Returns: A `ConfigParser` instance
+## SstEnvironmentBuilder
 
-### `ConfigParser`
+SST-specific builder with built-in resolvers for AWS resources.
 
-The configuration parser returned by `EnvironmentParser.create()`.
+### Basic Usage
 
-#### Methods
+```typescript
+import { SstEnvironmentBuilder, ResourceType } from '@geekmidas/envkit/sst';
 
-##### `parse(): T`
+const env = new SstEnvironmentBuilder({
+  database: {
+    type: ResourceType.Postgres,
+    host: 'db.example.com',
+    port: 5432,
+    database: 'myapp',
+    username: 'admin',
+    password: 'secret',
+  },
+  apiKey: {
+    type: ResourceType.Secret,
+    value: 'super-secret',
+  },
+  appName: 'my-app',
+}).build();
+
+// Result:
+// {
+//   DATABASE_HOST: 'db.example.com',
+//   DATABASE_PORT: 5432,
+//   DATABASE_NAME: 'myapp',
+//   DATABASE_USERNAME: 'admin',
+//   DATABASE_PASSWORD: 'secret',
+//   API_KEY: 'super-secret',
+//   APP_NAME: 'my-app',
+// }
+```
 
-Parses and validates the configuration.
+### Supported Resource Types
 
-- Returns: The parsed configuration object
-- Throws: `ZodError` if validation fails
+| Resource Type | Properties | Output |
+|--------------|------------|--------|
+| `Secret` / `SSTSecret` | `value` | `{key}: value` |
+| `Postgres` / `SSTPostgres` | `host`, `port`, `database`, `username`, `password` | `{key}Host`, `{key}Port`, `{key}Name`, `{key}Username`, `{key}Password` |
+| `Bucket` / `SSTBucket` | `name` | `{key}Name` |
+| `SnsTopic` | `arn` | `{key}Arn` |
+| `ApiGatewayV2` | - | No output (noop) |
+| `Function` | - | No output (noop) |
+| `Vpc` | - | No output (noop) |
 
-### `GetFunction`
+### Custom Resolvers
 
-The function passed to the schema builder for accessing configuration values.
+Add custom resolvers alongside built-in SST resolvers:
 
 ```typescript
-type GetFunction = (path: string) => ZodTypeAny
+const env = new SstEnvironmentBuilder(
+  {
+    database: { type: ResourceType.Postgres, /* ... */ },
+    custom: { type: 'my-custom' as const, data: 'custom-data' },
+  },
+  {
+    // Custom resolver merged with SST resolvers
+    'my-custom': (key, value) => ({ [`${key}Data`]: value.data }),
+  }
+).build();
+
+// Result includes both SST resources and custom type
 ```
 
-- `path`: The path to the configuration value (supports nested paths with dots)
-- Returns: A Zod schema that will be used to validate the value at the specified path
+### Resource Type Enum
+
+```typescript
+import { ResourceType } from '@geekmidas/envkit/sst';
+
+// Legacy format (dot notation)
+ResourceType.Postgres    // 'sst.aws.Postgres'
+ResourceType.Secret      // 'sst.sst.Secret'
+ResourceType.Bucket      // 'sst.aws.Bucket'
+
+// Modern format (colon notation)
+ResourceType.SSTPostgres // 'sst:aws:Postgres'
+ResourceType.SSTSecret   // 'sst:sst:Secret'
+ResourceType.SSTBucket   // 'sst:aws:Bucket'
+ResourceType.SnsTopic    // 'sst:aws:SnsTopic'
+```
 
-## Best Practices
+### Using with SST Resource
 
-1. **Define configuration at startup**: Parse your configuration once at application startup and export the result:
+Combine `SstEnvironmentBuilder` with `EnvironmentParser` to create a type-safe configuration from SST resources:
 
 ```typescript
 // config.ts
 import { EnvironmentParser } from '@geekmidas/envkit';
-import { z } from 'zod';
+import { SstEnvironmentBuilder } from '@geekmidas/envkit/sst';
+import { Resource } from 'sst';
 
-const parser = new EnvironmentParser(process.env);
+// Build environment variables from SST resources
+const env = new SstEnvironmentBuilder(Resource as {}).build();
+
+// Create parser with the normalized environment
+export const envParser = new EnvironmentParser(env);
 
-export const config = parser.create((get) => ({
-  // ... your schema
+// Define your configuration schema
+export const config = envParser.create((get) => ({
+  database: {
+    host: get('DATABASE_HOST').string(),
+    port: get('DATABASE_PORT').number(),
+    name: get('DATABASE_NAME').string(),
+    username: get('DATABASE_USERNAME').string(),
+    password: get('DATABASE_PASSWORD').string(),
+  },
+  apiKey: get('API_KEY').string(),
 })).parse();
+```
+
+This pattern allows you to:
+1. Normalize SST resources (Postgres, Secrets, Buckets, etc.) into flat environment variables
+2. Parse and validate them with Zod schemas
+3. Get full TypeScript type inference for your configuration
 
-// Other files can import the typed config
-import { config } from './config';
+## API Reference
+
+### EnvironmentParser
+
+```typescript
+class EnvironmentParser {
+  constructor(config: Record<string, unknown>);
+  create<T>(schemaBuilder: (get: GetFunction) => T): ConfigParser<T>;
+}
 ```
 
-2. **Use meaningful defaults**: Provide sensible defaults for optional configuration:
+### EnvironmentBuilder
 
 ```typescript
-const config = parser.create((get) => ({
-  port: get('PORT').string().transform(Number).default(3000),
-  logLevel: get('LOG_LEVEL').enum(['debug', 'info', 'warn', 'error']).default('info')
-}));
+class EnvironmentBuilder<TRecord, TResolvers> {
+  constructor(
+    record: TRecord,
+    resolvers: TResolvers,
+    options?: EnvironmentBuilderOptions
+  );
+  build(): EnvRecord;
+}
+
+interface EnvironmentBuilderOptions {
+  onUnmatchedValue?: (key: string, value: unknown) => void;
+}
 ```
 
-3. **Group related configuration**: Organize your configuration into logical groups:
+### SstEnvironmentBuilder
 
 ```typescript
-const config = parser.create((get) => ({
-  server: { /* server config */ },
-  database: { /* database config */ },
-  features: { /* feature flags */ },
-  thirdParty: { /* external service config */ }
-}));
+class SstEnvironmentBuilder<TRecord> {
+  constructor(
+    record: TRecord,
+    additionalResolvers?: CustomResolvers<TRecord>,
+    options?: EnvironmentBuilderOptions
+  );
+  build(): EnvRecord;
+}
 ```
 
-4. **Document your configuration**: Add comments to explain complex validations:
+### environmentCase
 
 ```typescript
-const config = parser.create((get) => ({
-  // Maximum number of concurrent connections
-  maxConnections: get('MAX_CONNECTIONS')
-    .string()
-    .transform(Number)
-    .int()
-    .min(1)
-    .max(1000)
-    .default(100),
-  
-  // Comma-separated list of allowed origins
-  allowedOrigins: get('ALLOWED_ORIGINS')
-    .string()
-    .transform(origins => origins.split(',').map(o => o.trim()))
-    .default(['http://localhost:3000'])
-}));
+function environmentCase(name: string): string;
+
+// Examples:
+environmentCase('myVariable')  // 'MY_VARIABLE'
+environmentCase('apiUrl')      // 'API_URL'
+environmentCase('databaseName') // 'DATABASE_NAME'
 ```
 
 ## License
 
-MIT
+MIT

package/dist/EnvironmentBuilder-DHfDXJUm.d.mts

@@ -0,0 +1,131 @@
+//#region src/EnvironmentBuilder.d.ts
+/**
+ * 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'
+ */
+declare function environmentCase(name: string): string;
+/**
+ * A record of environment variable names to their values.
+ * Values can be primitives or nested records.
+ */
+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.
+ */
+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
+ */
+type EnvironmentResolver<T = any> = (key: string, value: T) => EnvRecord;
+/**
+ * A map of type discriminator strings to their resolver functions.
+ */
+type Resolvers = Record<string, EnvironmentResolver<any>>;
+/**
+ * Options for configuring the EnvironmentBuilder.
+ */
+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.
+ */
+type InputValue = string | {
+  type: string;
+  [key: string]: unknown;
+};
+/**
+ * Base type for typed input values with a specific type discriminator.
+ */
+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`.
+ */
+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' }
+ * ```
+ */
+declare class EnvironmentBuilder<TRecord extends Record<string, InputValue> = Record<string, InputValue>, TResolvers extends Resolvers = TypedResolvers<TRecord>> {
+  private readonly record;
+  private readonly resolvers;
+  private readonly options;
+  constructor(record: TRecord, resolvers: TResolvers, options?: EnvironmentBuilderOptions);
+  /**
+   * 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;
+}
+//#endregion
+export { EnvRecord, EnvValue, EnvironmentBuilder, EnvironmentBuilderOptions, EnvironmentResolver, InputValue, Resolvers, TypedInputValue, TypedResolvers, environmentCase };
+//# sourceMappingURL=EnvironmentBuilder-DHfDXJUm.d.mts.map