@geekmidas/envkit 0.0.2 → 0.0.4

package/dist/sst.mjs

@@ -0,0 +1,128 @@
+import snakecase from "lodash.snakecase";
+
+//#region src/sst.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('api_v2') // 'APIV2'
+*/
+function environmentCase(name) {
+	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.
+*/
+let ResourceType = /* @__PURE__ */ function(ResourceType$1) {
+	ResourceType$1["ApiGatewayV2"] = "sst.aws.ApiGatewayV2";
+	ResourceType$1["Postgres"] = "sst.aws.Postgres";
+	ResourceType$1["Function"] = "sst.aws.Function";
+	ResourceType$1["Bucket"] = "sst.aws.Bucket";
+	ResourceType$1["Vpc"] = "sst.aws.Vpc";
+	ResourceType$1["Secret"] = "sst.sst.Secret";
+	ResourceType$1["SSTSecret"] = "sst:sst:Secret";
+	ResourceType$1["SSTFunction"] = "sst:sst:Function";
+	ResourceType$1["SSTApiGatewayV2"] = "sst:aws:ApiGatewayV2";
+	ResourceType$1["SSTPostgres"] = "sst:aws:Postgres";
+	ResourceType$1["SSTBucket"] = "sst:aws:Bucket";
+	return ResourceType$1;
+}({});
+/**
+* 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, value) => ({ [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, value) => {
+	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, value) => {
+	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, value) => ({});
+/**
+* Map of resource types to their corresponding processor functions.
+* Each processor converts resource data into environment variables.
+*/
+const processors = {
+	[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, ... }
+* })
+*/
+function normalizeResourceEnv(record) {
+	const env = {};
+	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;
+}
+
+//#endregion
+export { ResourceType, environmentCase, normalizeResourceEnv };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/envkit",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "private": false,
   "type": "module",
   "exports": {
@@ -8,6 +8,11 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs",
       "types": "./src/index.ts"
+    },
+    "./sst": {
+      "import": "./dist/sst.mjs",
+      "require": "./dist/sst.cjs",
+      "types": "./src/sst.ts"
     }
   },
   "publishConfig": {
@@ -17,10 +22,12 @@
   "dependencies": {
     "zod": "~3.25.67",
     "lodash.set": "~4.3.2",
-    "lodash.get": "~4.4.2"
+    "lodash.get": "~4.4.2",
+    "lodash.snakecase": "~4.1.1"
   },
   "devDependencies": {
     "@types/lodash.set": "~4.3.9",
-    "@types/lodash.get": "~4.4.9"
+    "@types/lodash.get": "~4.4.9",
+    "@types/lodash.snakecase": "~4.1.9"
   }
 }

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,115 @@ 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, {
+      get: (target, prop) => {
+        if (prop === 'parse') {
+          return () => {
+            const value = get(this.config, name);
+            try {
+              return target.parse(value);
+            } catch (error) {
+              if (error instanceof z.ZodError) {
+                // Modify the error to include the environment variable name
+                const modifiedIssues = error.issues.map((issue) => ({
+                  ...issue,
+                  message: `Environment variable "${name}": ${issue.message}`,
+                  path: [name, ...issue.path],
+                }));
+                throw new z.ZodError(modifiedIssues);
+              }
+              throw error;
+            }
+          };
+        }
+
+        if (prop === 'safeParse') {
+          return () => {
+            const value = get(this.config, name);
+            const result = target.safeParse(value);
+
+            if (!result.success) {
+              // Modify the error to include the environment variable name
+              const modifiedIssues = result.error.issues.map(
+                (issue: z.core.$ZodIssue) => ({
+                  ...issue,
+                  message: `Environment variable "${name}": ${issue.message}`,
+                  path: [name, ...issue.path],
+                }),
+              );
+              return {
+                success: false as const,
+                error: new z.ZodError(modifiedIssues),
+              };
+            }
+
+            return result;
+          };
+        }
+
+        // For any method that returns a new schema (like transform, optional, etc.),
+        // wrap the result as well
+        const originalProp = target[prop as keyof typeof target];
+        if (typeof originalProp === 'function') {
+          return (...args: any[]) => {
+            const result = originalProp.apply(target, args);
+            // If the result is a ZodType, wrap it too
+            if (result && typeof result === 'object' && 'parse' in result) {
+              return this.wrapSchema(result, name);
+            }
+            return result;
+          };
+        }
+
+        return originalProp;
+      },
+    });
+  };
+
+  /**
+   * 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(
@@ -67,70 +184,44 @@ export class EnvironmentParser<T extends EmptyObject> {
         get: (target, prop) => {
           // deno-lint-ignore ban-ts-comment
           // @ts-ignore
-          const func = target[prop];
+          const value = target[prop];
 
-          if (typeof func === 'function') {
+          if (typeof value === 'function') {
             // Return a wrapper around each Zod schema creator
             return (...args: any[]) => {
-              const schema = func(...args);
-              // Add a custom parse method that gets the value from config
-              const originalParse = schema.parse;
-              const originalSafeParse = schema.safeParse;
-
-              schema.parse = () => {
-                const value = get(this.config, name);
-                try {
-                  return originalParse.call(schema, value);
-                } catch (error) {
-                  if (error instanceof z.ZodError) {
-                    // Modify the error to include the environment variable name
-                    const modifiedIssues = error.issues.map((issue) => ({
-                      ...issue,
-                      message: `Environment variable "${name}": ${issue.message}`,
-                      path: [name, ...issue.path],
-                    }));
-                    throw new z.ZodError(modifiedIssues);
-                  }
-                  throw error;
-                }
-              };
+              const schema = value(...args);
+              return this.wrapSchema(schema, name);
+            };
+          }
 
-              schema.safeParse = () => {
-                const value = get(this.config, name);
-                const result = originalSafeParse.call(schema, value);
-
-                if (!result.success) {
-                  // Modify the error to include the environment variable name
-                  const modifiedIssues = result.error.issues.map(
-                    (issue: z.core.$ZodIssue) => ({
-                      ...issue,
-                      message: `Environment variable "${name}": ${issue.message}`,
-                      path: [name, ...issue.path],
-                    }),
-                  );
-                  return {
-                    success: false as const,
-                    error: new z.ZodError(modifiedIssues),
+          // Handle objects like z.coerce
+          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 result;
-              };
-
-              return schema;
-            };
+                return nestedValue;
+              },
+            });
           }
-          return func;
+
+          return value;
         },
       },
     );
   };
 
   /**
-   * 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,
@@ -140,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]>
@@ -148,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>;