@geekmidas/envkit 0.0.3 → 0.0.4

package/src/EnvironmentParser.ts

@@ -2,7 +2,18 @@ import get from 'lodash.get';
 import set from 'lodash.set';
 import { z } from 'zod/v4';
 
+/**
+ * Parses and validates configuration objects against Zod schemas.
+ * Handles nested configurations and aggregates validation errors.
+ * 
+ * @template TResponse - The shape of the configuration object
+ */
 export class ConfigParser<TResponse extends EmptyObject> {
+  /**
+   * Creates a new ConfigParser instance.
+   * 
+   * @param config - The configuration object to parse
+   */
   constructor(private readonly config: TResponse) {}
   /**
    * Parses the config object and validates it against the Zod schemas
@@ -56,9 +67,41 @@ export class ConfigParser<TResponse extends EmptyObject> {
   }
 }
 
+/**
+ * Parses environment variables with type-safe validation using Zod schemas.
+ * Provides a fluent API for defining environment variable schemas with automatic
+ * error context enrichment.
+ * 
+ * @template T - The type of the configuration object (typically process.env)
+ * 
+ * @example
+ * ```typescript
+ * const config = new EnvironmentParser(process.env)
+ *   .create((get) => ({
+ *     port: get('PORT').string().transform(Number).default(3000),
+ *     database: {
+ *       url: get('DATABASE_URL').string().url()
+ *     }
+ *   }))
+ *   .parse();
+ * ```
+ */
 export class EnvironmentParser<T extends EmptyObject> {
+  /**
+   * Creates a new EnvironmentParser instance.
+   * 
+   * @param config - The configuration object to parse (typically process.env)
+   */
   constructor(private readonly config: T) {}
 
+  /**
+   * Wraps a Zod schema to intercept parse/safeParse calls and enrich error messages
+   * with environment variable context.
+   * 
+   * @param schema - The Zod schema to wrap
+   * @param name - The environment variable name for error context
+   * @returns A wrapped Zod schema with enhanced error reporting
+   */
   private wrapSchema = (schema: z.ZodType, name: string): z.ZodType => {
     // Create a proxy that intercepts all method calls on the schema
     return new Proxy(schema, {
@@ -126,6 +169,13 @@ export class EnvironmentParser<T extends EmptyObject> {
     });
   };
 
+  /**
+   * Creates a proxied version of the Zod object that wraps all schema creators
+   * to provide enhanced error messages with environment variable context.
+   * 
+   * @param name - The environment variable name
+   * @returns A proxied Zod object with wrapped schema creators
+   */
   private getZodGetter = (name: string) => {
     // Return an object that has all Zod schemas but with our wrapper
     return new Proxy(
@@ -148,7 +198,8 @@ export class EnvironmentParser<T extends EmptyObject> {
           if (value && typeof value === 'object') {
             return new Proxy(value, {
               get: (nestedTarget, nestedProp) => {
-                const nestedValue = nestedTarget[nestedProp as keyof typeof nestedTarget];
+                const nestedValue =
+                  nestedTarget[nestedProp as keyof typeof nestedTarget];
                 if (typeof nestedValue === 'function') {
                   return (...args: any[]) => {
                     const schema = nestedValue(...args);
@@ -167,10 +218,10 @@ export class EnvironmentParser<T extends EmptyObject> {
   };
 
   /**
-   * Creates a new JordConfigParser object that can be used to parse the config object
+   * Creates a new ConfigParser object that can be used to parse the config object
    *
    * @param builder - A function that takes a getter function and returns a config object
-   * @returns A JordConfigParser object that can be used to parse the config object
+   * @returns A ConfigParser object that can be used to parse the config object
    */
   create<TReturn extends EmptyObject>(
     builder: (get: EnvFetcher) => TReturn,
@@ -180,6 +231,12 @@ export class EnvironmentParser<T extends EmptyObject> {
   }
 }
 
+/**
+ * Infers the TypeScript type of a configuration object based on its Zod schemas.
+ * Recursively processes nested objects and extracts types from Zod schemas.
+ * 
+ * @template T - The configuration object type
+ */
 export type InferConfig<T extends EmptyObject> = {
   [K in keyof T]: T[K] extends z.ZodSchema
     ? z.infer<T[K]>
@@ -188,12 +245,32 @@ export type InferConfig<T extends EmptyObject> = {
       : T[K];
 };
 
+/**
+ * Function type for fetching environment variables with Zod validation.
+ * Returns a Zod object scoped to a specific environment variable.
+ * 
+ * @template TPath - The environment variable path type
+ * @param name - The environment variable name
+ * @returns A Zod object for defining the schema
+ */
 export type EnvFetcher<TPath extends string = string> = (
   name: TPath,
 ) => typeof z;
 
+/**
+ * Function type for building environment configuration objects.
+ * Takes an EnvFetcher and returns a configuration object with Zod schemas.
+ * 
+ * @template TResponse - The response configuration object type
+ * @param get - The environment variable fetcher function
+ * @returns The configuration object with Zod schemas
+ */
 export type EnvironmentBuilder<TResponse extends EmptyObject> = (
   get: EnvFetcher,
 ) => TResponse;
 
+/**
+ * Type alias for a generic object with unknown values.
+ * Used as a constraint for configuration objects.
+ */
 export type EmptyObject = Record<string | number | symbol, unknown>;

package/src/sst.ts

@@ -0,0 +1,221 @@
+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('api_v2') // 'APIV2'
+ */
+export function environmentCase(name: string) {
+  return snakecase(name)
+    .toUpperCase()
+    .replace(/_\d+/g, (r) => {
+      return r.replace('_', '');
+    });
+}
+
+/**
+ * Enumeration of supported SST (Serverless Stack Toolkit) resource types.
+ * Used to identify and process different AWS and SST resources.
+ */
+export enum ResourceType {
+  ApiGatewayV2 = 'sst.aws.ApiGatewayV2',
+  Postgres = 'sst.aws.Postgres',
+  Function = 'sst.aws.Function',
+  Bucket = 'sst.aws.Bucket',
+  Vpc = 'sst.aws.Vpc',
+  Secret = 'sst.sst.Secret',
+  SSTSecret = 'sst:sst:Secret',
+  SSTFunction = 'sst:sst:Function',
+  SSTApiGatewayV2 = 'sst:aws:ApiGatewayV2',
+  SSTPostgres = 'sst:aws:Postgres',
+  SSTBucket = 'sst:aws:Bucket',
+}
+
+/**
+ * Processes a Secret resource into environment variables.
+ * 
+ * @param name - The resource name
+ * @param value - The Secret resource
+ * @returns Object with environment variable mappings
+ */
+const secret = (name: string, value: Secret) => ({
+  [environmentCase(name)]: value.value,
+});
+/**
+ * Processes a Postgres database resource into environment variables.
+ * Creates multiple environment variables for database connection details.
+ * 
+ * @param key - The resource key
+ * @param value - The Postgres resource
+ * @returns Object with database connection environment variables
+ */
+const postgres = (key: string, value: Postgres) => {
+  const prefix = `${environmentCase(key)}`;
+  return {
+    [`${prefix}_NAME`]: value.database,
+    [`${prefix}_HOST`]: value.host,
+    [`${prefix}_PASSWORD`]: value.password,
+    [`${prefix}_PORT`]: value.port,
+    [`${prefix}_USERNAME`]: value.username,
+  };
+};
+
+/**
+ * Processes a Bucket resource into environment variables.
+ * 
+ * @param name - The resource name
+ * @param value - The Bucket resource
+ * @returns Object with bucket name environment variable
+ */
+const bucket = (name: string, value: Bucket) => {
+  const prefix = `${environmentCase(name)}`;
+  return {
+    [`${prefix}_NAME`]: value.name,
+  };
+};
+
+/**
+ * No-operation processor for resources that don't require environment variables.
+ * 
+ * @param name - The resource name (unused)
+ * @param value - The resource value (unused)
+ * @returns Empty object
+ */
+const noop = (name: string, value: any) => ({});
+
+/**
+ * Map of resource types to their corresponding processor functions.
+ * Each processor converts resource data into environment variables.
+ */
+const processors: Record<ResourceType, ResourceProcessor<any>> = {
+  [ResourceType.ApiGatewayV2]: noop,
+  [ResourceType.Function]: noop,
+  [ResourceType.Vpc]: noop,
+  [ResourceType.Secret]: secret,
+  [ResourceType.Postgres]: postgres,
+  [ResourceType.Bucket]: bucket,
+
+  [ResourceType.SSTSecret]: secret,
+  [ResourceType.SSTBucket]: bucket,
+  [ResourceType.SSTFunction]: noop,
+  [ResourceType.SSTPostgres]: postgres,
+  [ResourceType.SSTApiGatewayV2]: noop,
+};
+
+/**
+ * Normalizes SST resources and plain strings into environment variables.
+ * Processes resources based on their type and converts names to environment case.
+ * 
+ * @param record - Object containing resources and/or string values
+ * @returns Normalized environment variables object
+ * 
+ * @example
+ * normalizeResourceEnv({
+ *   apiUrl: 'https://api.example.com',
+ *   database: { type: ResourceType.Postgres, ... }
+ * })
+ */
+export function normalizeResourceEnv(
+  record: Record<string, Resource | string>,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [k, value] of Object.entries(record)) {
+    if (typeof value === 'string') {
+      env[environmentCase(k)] = value;
+      continue;
+    }
+
+    const processor = processors[value.type];
+    if (processor) {
+      Object.assign(env, processor(k, value));
+    } else {
+      console.warn(`No processor found for resource type: `, { value });
+    }
+  }
+
+  return env;
+}
+
+/**
+ * AWS API Gateway V2 resource type.
+ * Represents an HTTP/WebSocket API.
+ */
+export type ApiGatewayV2 = {
+  type: ResourceType.ApiGatewayV2;
+  url: string;
+};
+
+/**
+ * PostgreSQL database resource type.
+ * Contains all connection details needed to connect to the database.
+ */
+export type Postgres = {
+  database: string;
+  host: string;
+  password: string;
+  port: number;
+  type: ResourceType.Postgres;
+  username: string;
+};
+
+/**
+ * AWS Lambda Function resource type.
+ */
+export type Function = {
+  name: string;
+  type: ResourceType.Function;
+};
+
+/**
+ * AWS S3 Bucket resource type.
+ */
+export type Bucket = {
+  name: string;
+  type: ResourceType.Bucket;
+};
+
+/**
+ * AWS VPC (Virtual Private Cloud) resource type.
+ */
+export type Vpc = {
+  bastion: string;
+  type: ResourceType.Vpc;
+};
+
+/**
+ * Secret resource type for storing sensitive values.
+ */
+export type Secret = {
+  type: ResourceType.Secret;
+  value: string;
+};
+
+/**
+ * Union type of all supported SST resource types.
+ */
+export type Resource =
+  | ApiGatewayV2
+  | Postgres
+  | Function
+  | Bucket
+  | Vpc
+  | Secret;
+
+/**
+ * Function type for processing a specific resource type into environment variables.
+ * 
+ * @template K - The specific resource type
+ * @param name - The resource name
+ * @param value - The resource value
+ * @returns Object mapping environment variable names to values
+ */
+export type ResourceProcessor<K extends Resource> = (
+  name: string,
+  value: K,
+) => Record<string, string | number>;