@geekmidas/envkit 0.0.8 → 0.1.0

package/src/SstEnvironmentBuilder.ts

@@ -0,0 +1,298 @@
+import {
+  type EnvRecord,
+  EnvironmentBuilder,
+  type EnvironmentBuilderOptions,
+  type EnvironmentResolver,
+  type InputValue,
+  type Resolvers,
+} from './EnvironmentBuilder';
+
+/**
+ * Enumeration of supported SST (Serverless Stack Toolkit) resource types.
+ * Used to identify and process different AWS and SST resources.
+ */
+export enum ResourceType {
+  // Legacy format (dot notation)
+  ApiGatewayV2 = 'sst.aws.ApiGatewayV2',
+  Postgres = 'sst.aws.Postgres',
+  Function = 'sst.aws.Function',
+  Bucket = 'sst.aws.Bucket',
+  Vpc = 'sst.aws.Vpc',
+  Secret = 'sst.sst.Secret',
+
+  // Modern format (colon notation)
+  SSTSecret = 'sst:sst:Secret',
+  SSTFunction = 'sst:sst:Function',
+  SSTApiGatewayV2 = 'sst:aws:ApiGatewayV2',
+  SSTPostgres = 'sst:aws:Postgres',
+  SSTBucket = 'sst:aws:Bucket',
+  SnsTopic = 'sst:aws:SnsTopic',
+}
+
+/**
+ * AWS API Gateway V2 resource type.
+ * Represents an HTTP/WebSocket API.
+ */
+export type ApiGatewayV2 = {
+  type: ResourceType.ApiGatewayV2 | ResourceType.SSTApiGatewayV2;
+  url: string;
+};
+
+/**
+ * PostgreSQL database resource type.
+ * Contains all connection details needed to connect to the database.
+ */
+export type Postgres = {
+  type: ResourceType.Postgres | ResourceType.SSTPostgres;
+  database: string;
+  host: string;
+  password: string;
+  port: number;
+  username: string;
+};
+
+/**
+ * AWS Lambda Function resource type.
+ */
+export type Function = {
+  type: ResourceType.Function | ResourceType.SSTFunction;
+  name: string;
+};
+
+/**
+ * AWS S3 Bucket resource type.
+ */
+export type Bucket = {
+  type: ResourceType.Bucket | ResourceType.SSTBucket;
+  name: string;
+};
+
+/**
+ * AWS VPC (Virtual Private Cloud) resource type.
+ */
+export type Vpc = {
+  type: ResourceType.Vpc;
+  bastion: string;
+};
+
+/**
+ * Secret resource type for storing sensitive values.
+ */
+export type Secret = {
+  type: ResourceType.Secret | ResourceType.SSTSecret;
+  value: string;
+};
+
+/**
+ * AWS SNS Topic resource type.
+ */
+export type SnsTopic = {
+  type: ResourceType.SnsTopic;
+  arn: string;
+};
+
+/**
+ * Union type of all supported SST resource types.
+ */
+export type SstResource =
+  | ApiGatewayV2
+  | Postgres
+  | Function
+  | Bucket
+  | Vpc
+  | Secret
+  | SnsTopic;
+
+// Value types without the `type` key (for resolver parameters)
+type SecretValue = Omit<Secret, 'type'>;
+type PostgresValue = Omit<Postgres, 'type'>;
+type BucketValue = Omit<Bucket, 'type'>;
+type SnsTopicValue = Omit<SnsTopic, 'type'>;
+
+/**
+ * Function type for processing a specific resource type into environment variables.
+ *
+ * @template K - The specific resource type (without `type` key)
+ * @param name - The resource name
+ * @param value - The resource value (without `type` key)
+ * @returns Object mapping environment variable names to values
+ */
+export type ResourceProcessor<K> = (name: string, value: K) => EnvRecord;
+
+// SST Resource Resolvers (receive values without `type` key)
+
+const secretResolver = (name: string, value: SecretValue) => ({
+  [name]: value.value,
+});
+
+const postgresResolver = (key: string, value: PostgresValue) => ({
+  [`${key}Name`]: value.database,
+  [`${key}Host`]: value.host,
+  [`${key}Password`]: value.password,
+  [`${key}Port`]: value.port,
+  [`${key}Username`]: value.username,
+});
+
+const bucketResolver = (name: string, value: BucketValue) => ({
+  [`${name}Name`]: value.name,
+});
+
+const topicResolver = (name: string, value: SnsTopicValue) => ({
+  [`${name}Arn`]: value.arn,
+});
+
+const noopResolver = () => ({});
+
+/**
+ * Pre-configured resolvers for all SST resource types.
+ */
+export const sstResolvers: Resolvers = {
+  // Legacy format
+  [ResourceType.ApiGatewayV2]: noopResolver,
+  [ResourceType.Function]: noopResolver,
+  [ResourceType.Vpc]: noopResolver,
+  [ResourceType.Secret]: secretResolver,
+  [ResourceType.Postgres]: postgresResolver,
+  [ResourceType.Bucket]: bucketResolver,
+
+  // Modern format
+  [ResourceType.SSTSecret]: secretResolver,
+  [ResourceType.SSTBucket]: bucketResolver,
+  [ResourceType.SSTFunction]: noopResolver,
+  [ResourceType.SSTPostgres]: postgresResolver,
+  [ResourceType.SSTApiGatewayV2]: noopResolver,
+  [ResourceType.SnsTopic]: topicResolver,
+};
+
+/**
+ * All known SST resource type strings.
+ */
+type SstResourceTypeString = `${ResourceType}`;
+
+/**
+ * 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];
+
+/**
+ * Extracts only the custom (non-SST) type values from a record.
+ */
+type CustomTypeValues<TRecord extends Record<string, InputValue>> = Exclude<
+  AllTypeValues<TRecord>,
+  SstResourceTypeString
+>;
+
+/**
+ * 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 for custom (non-SST) types in the input record.
+ */
+type CustomResolvers<TRecord extends Record<string, InputValue>> =
+  CustomTypeValues<TRecord> extends never
+    ? Resolvers | undefined
+    : {
+        [TType in CustomTypeValues<TRecord>]: EnvironmentResolver<
+          ValueForType<TRecord, TType>
+        >;
+      };
+
+/**
+ * SST-specific environment builder with built-in resolvers for all known
+ * SST resource types.
+ *
+ * Wraps the generic EnvironmentBuilder with pre-configured SST resolvers.
+ *
+ * @template TRecord - The input record type for type inference
+ *
+ * @example
+ * ```typescript
+ * const env = new SstEnvironmentBuilder({
+ *   database: { type: 'sst:aws:Postgres', host: '...', ... },
+ *   apiKey: { type: 'sst:sst:Secret', value: 'secret' },
+ *   appName: 'my-app',
+ * }).build();
+ *
+ * // With custom resolvers (typed based on input)
+ * const env = new SstEnvironmentBuilder(
+ *   {
+ *     database: postgresResource,
+ *     custom: { type: 'my-custom' as const, data: 'foo' },
+ *   },
+ *   {
+ *     // TypeScript requires 'my-custom' resolver with typed value
+ *     'my-custom': (key, value) => ({ [`${key}Data`]: value.data }),
+ *   }
+ * ).build();
+ * ```
+ */
+export class SstEnvironmentBuilder<
+  TRecord extends Record<string, SstResource | InputValue | string>,
+> {
+  private readonly builder: EnvironmentBuilder<
+    Record<string, InputValue>,
+    Resolvers
+  >;
+
+  /**
+   * Create a new SST environment builder.
+   *
+   * @param record - Object containing SST resources, custom resources, and/or string values
+   * @param additionalResolvers - Optional custom resolvers (typed based on custom types in record)
+   * @param options - Optional configuration options
+   */
+  constructor(
+    record: TRecord,
+    additionalResolvers?: CustomResolvers<TRecord>,
+    options?: EnvironmentBuilderOptions,
+  ) {
+    // Merge resolvers with custom ones taking precedence
+    const mergedResolvers: Resolvers = additionalResolvers
+      ? { ...sstResolvers, ...additionalResolvers }
+      : sstResolvers;
+
+    this.builder = new EnvironmentBuilder(
+      record as Record<string, InputValue>,
+      mergedResolvers,
+      options,
+    );
+  }
+
+  /**
+   * Build environment variables from the input record.
+   *
+   * @returns A record of environment variables
+   */
+  build(): EnvRecord {
+    return this.builder.build();
+  }
+}
+
+// Re-export useful types
+export { environmentCase } from './EnvironmentBuilder';
+export type {
+  EnvRecord,
+  EnvValue,
+  EnvironmentBuilderOptions,
+} from './EnvironmentBuilder';

package/src/__tests__/EnvironmentBuilder.spec.ts

@@ -0,0 +1,274 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { EnvironmentBuilder, environmentCase } from '../EnvironmentBuilder';
+
+describe('environmentCase', () => {
+  it('should convert camelCase to UPPER_SNAKE_CASE', () => {
+    expect(environmentCase('myVariable')).toBe('MY_VARIABLE');
+    expect(environmentCase('apiUrl')).toBe('API_URL');
+    expect(environmentCase('databaseName')).toBe('DATABASE_NAME');
+  });
+
+  it('should handle already snake_case', () => {
+    expect(environmentCase('my_variable')).toBe('MY_VARIABLE');
+    expect(environmentCase('api_url')).toBe('API_URL');
+  });
+
+  it('should remove underscore directly before numbers', () => {
+    // The regex /_\d+/g only removes underscores that are directly followed by digits
+    expect(environmentCase('api_v2')).toBe('API_V2');
+    expect(environmentCase('value_123')).toBe('VALUE123');
+    expect(environmentCase('my_var_2')).toBe('MY_VAR2');
+  });
+
+  it('should handle single words', () => {
+    expect(environmentCase('name')).toBe('NAME');
+    expect(environmentCase('port')).toBe('PORT');
+  });
+});
+
+describe('EnvironmentBuilder', () => {
+  describe('basic functionality', () => {
+    it('should pass through plain string values with key transformation', () => {
+      const env = new EnvironmentBuilder(
+        {
+          appName: 'my-app',
+          nodeEnv: 'production',
+        },
+        {},
+      ).build();
+
+      expect(env).toEqual({
+        APP_NAME: 'my-app',
+        NODE_ENV: 'production',
+      });
+    });
+
+    it('should resolve object values using type-based resolvers', () => {
+      const env = new EnvironmentBuilder(
+        {
+          apiKey: { type: 'secret', value: 'xyz' },
+        },
+        {
+          secret: (key, value: { type: string; value: string }) => ({
+            [key]: value.value,
+          }),
+        },
+      ).build();
+
+      expect(env).toEqual({
+        API_KEY: 'xyz',
+      });
+    });
+
+    it('should transform resolver output keys to UPPER_SNAKE_CASE', () => {
+      const env = new EnvironmentBuilder(
+        {
+          auth: { type: 'auth0', domain: 'example.auth0.com', clientId: 'abc' },
+        },
+        {
+          auth0: (
+            key,
+            value: { type: string; domain: string; clientId: string },
+          ) => ({
+            [`${key}Domain`]: value.domain,
+            [`${key}ClientId`]: value.clientId,
+          }),
+        },
+      ).build();
+
+      expect(env).toEqual({
+        AUTH_DOMAIN: 'example.auth0.com',
+        AUTH_CLIENT_ID: 'abc',
+      });
+    });
+
+    it('should handle mixed string and object values', () => {
+      const env = new EnvironmentBuilder(
+        {
+          appName: 'my-app',
+          apiKey: { type: 'secret', value: 'secret-key' },
+          nodeEnv: 'production',
+        },
+        {
+          secret: (key, value: { type: string; value: string }) => ({
+            [key]: value.value,
+          }),
+        },
+      ).build();
+
+      expect(env).toEqual({
+        APP_NAME: 'my-app',
+        API_KEY: 'secret-key',
+        NODE_ENV: 'production',
+      });
+    });
+  });
+
+  describe('nested values', () => {
+    it('should support nested object values', () => {
+      const env = new EnvironmentBuilder(
+        {
+          database: {
+            type: 'multi-db',
+            primary: 'pg://primary',
+            replica: 'pg://replica',
+          },
+        },
+        {
+          'multi-db': (
+            key,
+            value: { type: string; primary: string; replica: string },
+          ) => ({
+            [key]: {
+              primary: value.primary,
+              replica: value.replica,
+            },
+          }),
+        },
+      ).build();
+
+      expect(env).toEqual({
+        DATABASE: {
+          primary: 'pg://primary',
+          replica: 'pg://replica',
+        },
+      });
+    });
+
+    it('should not transform nested object keys', () => {
+      const env = new EnvironmentBuilder(
+        {
+          config: { type: 'nested', camelCase: 'value', snake_case: 'value2' },
+        },
+        {
+          nested: (
+            key,
+            value: { type: string; camelCase: string; snake_case: string },
+          ) => ({
+            [key]: {
+              camelCase: value.camelCase,
+              snake_case: value.snake_case,
+            },
+          }),
+        },
+      ).build();
+
+      expect(env).toEqual({
+        CONFIG: {
+          camelCase: 'value',
+          snake_case: 'value2',
+        },
+      });
+    });
+  });
+
+  describe('unmatched values', () => {
+    it('should call onUnmatchedValue for objects without matching resolver', () => {
+      const onUnmatchedValue = vi.fn();
+
+      new EnvironmentBuilder(
+        {
+          unknown: { type: 'unknown-type', data: 'test' },
+        },
+        {},
+        { onUnmatchedValue },
+      ).build();
+
+      expect(onUnmatchedValue).toHaveBeenCalledWith('unknown', {
+        type: 'unknown-type',
+        data: 'test',
+      });
+    });
+
+    it('should default to console.warn for unmatched values', () => {
+      const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+
+      new EnvironmentBuilder(
+        {
+          unknown: { type: 'unknown-type', data: 'test' },
+        },
+        {},
+      ).build();
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        'No resolver found for key "unknown":',
+        {
+          value: { type: 'unknown-type', data: 'test' },
+        },
+      );
+
+      warnSpy.mockRestore();
+    });
+  });
+
+  describe('value types', () => {
+    it('should support number values', () => {
+      const env = new EnvironmentBuilder(
+        {
+          port: { type: 'port', value: 3000 },
+        },
+        {
+          port: (key, value: { type: string; value: number }) => ({
+            [key]: value.value,
+          }),
+        },
+      ).build();
+
+      expect(env).toEqual({
+        PORT: 3000,
+      });
+    });
+
+    it('should support boolean values', () => {
+      const env = new EnvironmentBuilder(
+        {
+          enabled: { type: 'flag', value: true },
+        },
+        {
+          flag: (key, value: { type: string; value: boolean }) => ({
+            [key]: value.value,
+          }),
+        },
+      ).build();
+
+      expect(env).toEqual({
+        ENABLED: true,
+      });
+    });
+  });
+
+  describe('multiple resolvers', () => {
+    it('should use the correct resolver for each type', () => {
+      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: { type: string; value: string }) => ({
+            [key]: value.value,
+          }),
+          postgres: (
+            key,
+            value: { type: string; host: string; port: number },
+          ) => ({
+            [`${key}Host`]: value.host,
+            [`${key}Port`]: value.port,
+          }),
+          bucket: (key, value: { type: string; name: string }) => ({
+            [`${key}Name`]: value.name,
+          }),
+        },
+      ).build();
+
+      expect(env).toEqual({
+        SECRET: 'my-secret',
+        DATABASE_HOST: 'localhost',
+        DATABASE_PORT: 5432,
+        BUCKET_NAME: 'my-bucket',
+      });
+    });
+  });
+});