feat: Add EnvModule to help with loading and handling environment variables

Author: spuxx-dev

apps/nest/src/app.controller.spec.ts

@@ -0,0 +1,24 @@
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { TestContainer, Supertest } from '@spuxx/nest-utils';
+
+describe('AppController', () => {
+  let supertest: Supertest;
+
+  beforeEach(async () => {
+    const container = await TestContainer.create({
+      controllers: [AppController],
+      providers: [AppService],
+      enableEndToEnd: true,
+    });
+    supertest = container.supertest;
+  });
+
+  describe('root', () => {
+    it('should be successful', async () => {
+      const response = await supertest.get('/');
+      expect(response.statusCode).toBe(200);
+      expect(response.text).toContain('Hello!');
+    });
+  });
+});

apps/nest/src/app.controller.test.ts

@@ -1,10 +1,12 @@
 import { Module } from '@nestjs/common';
 import { AppController } from './app.controller';
 import { AppService } from './app.service';
-import { NestUtilsModule } from '@spuxx/nest-utils';
+import { EnvModule } from './env/env.module';
 
 @Module({
-  imports: [NestUtilsModule],
+  imports: [
+    EnvModule,
+  ],
   controllers: [AppController],
   providers: [AppService],
 })

apps/nest/src/app.module.ts

@@ -1,11 +1,9 @@
 import { Injectable } from '@nestjs/common';
-import { NestUtilsService } from '@spuxx/nest-utils';
+import { EnvModule } from './env/env.module';
 
 @Injectable()
 export class AppService {
-  constructor(private readonly utils: NestUtilsService) {}
-
   getHello(): string {
-    return this.utils.getHello();
+    return `Hello! The application is running since ${EnvModule.get('START_TIME')}.`;
   }
 }

apps/nest/src/app.service.ts

@@ -0,0 +1,9 @@
+import { IsDate, IsString } from 'class-validator';
+
+export class Environment {
+  @IsString()
+  APP_NAME: string = 'nest';
+
+  @IsDate()
+  START_TIME: Date;
+}

apps/nest/src/env/env.definiton.ts

@@ -0,0 +1,4 @@
+import { EnvModuleMixin } from '@spuxx/nest-utils';
+import { Environment } from './env.definiton';
+
+export class EnvModule extends EnvModuleMixin<Environment>(Environment) {}

apps/nest/src/env/env.module.ts

@@ -0,0 +1,76 @@
+import { IsBooleanString, IsDate, IsNumber, IsString } from 'class-validator';
+import { TestContainer } from '../testing/container';
+import { EnvModuleMixin } from './env.module-mixin';
+
+describe('registration', () => {
+  class Env {
+    @IsString()
+    SOME_STRING: string;
+  }
+  class EnvModule extends EnvModuleMixin<Env>(Env) {}
+
+  it('should properly load the environment variables and module', async () => {
+    vi.stubEnv('SOME_STRING', 'foo');
+    const container = await TestContainer.create({
+      imports: [EnvModule],
+    });
+    const module = container.module.get<EnvModule>(EnvModule);
+    expect(module).toBeDefined();
+    expect(EnvModule.get('SOME_STRING')).toBe('foo');
+  });
+});
+
+describe('validation', () => {
+  it('should throw an error due to a missing environment variable', () => {
+    vi.unstubAllEnvs();
+    class Env {
+      @IsString()
+      SOME_STRING: string;
+    }
+    class EnvModule extends EnvModuleMixin<Env>(Env) {}
+    expect(
+      TestContainer.create({
+        imports: [EnvModule],
+      }),
+    ).rejects.toThrowError(`An instance of Env has failed the validation:
+ - property SOME_STRING has failed the following constraints: isString`);
+  });
+
+  it('should throw an error due to a type mismatch', () => {
+    vi.stubEnv('SOME_BOOLEAN', 'foo');
+    class Env {
+      @IsBooleanString()
+      SOME_BOOLEAN: 'true' | 'false';
+    }
+    class EnvModule extends EnvModuleMixin<Env>(Env) {}
+    expect(
+      TestContainer.create({
+        imports: [EnvModule],
+      }),
+    ).rejects.toThrowError(`An instance of Env has failed the validation:
+ - property SOME_BOOLEAN has failed the following constraints: isBooleanString`);
+  });
+
+  it('should implicitly perform certain conversions', async () => {
+    vi.stubEnv('SOME_DATE', '2024-08-13T17:34:00Z');
+    vi.stubEnv('SOME_NUMBER', '123');
+    class Env {
+      @IsDate()
+      SOME_DATE: Date;
+      @IsNumber()
+      SOME_NUMBER: number;
+    }
+    class EnvModule extends EnvModuleMixin<Env>(Env) {}
+    await TestContainer.create({
+      imports: [EnvModule],
+    });
+    expect(EnvModule.get('SOME_DATE')).toEqual(new Date('2024-08-13T17:34:00Z'));
+    expect(EnvModule.get('SOME_NUMBER')).toBe(123);
+  });
+});
+
+describe('decorators', () => {
+  it('should work with decorators', () => {
+    vi.stubEnv('HELLO_ROUTE', '/hello');
+  });
+});

packages/nest-utils/src/env/env.module-mixin.test.ts

@@ -0,0 +1,46 @@
+import { Logger, Module } from '@nestjs/common';
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+
+export function EnvModuleMixin<TEnv extends object>(env: new (...args: unknown[]) => TEnv) {
+  @Module({})
+  class EnvModule {
+    static get env(): TEnv {
+      return plainToInstance(env, process.env, {
+        enableImplicitConversion: true,
+      });
+    }
+
+    constructor() {
+      EnvModule.validate();
+    }
+
+    /**
+     * Validates the currently stored instance of the environment class.
+     */
+    static validate(): void {
+      const errors = validateSync(this.env, {
+        skipMissingProperties: false,
+      });
+
+      if (errors.length > 0) {
+        Logger.error(
+          'Failed to validate environment variables. Did you forget to provide some that are required?',
+          this.constructor.name,
+        );
+        throw new Error(errors.toString());
+      }
+    }
+
+    /**
+     * Returns the value of the environment variable with the given key.
+     * @param key The key of the environment variable.
+     * @returns The value of the environment variable.
+     */
+    static get<TKey extends keyof TEnv>(key: TKey): TEnv[TKey] {
+      return EnvModule.env[key];
+    }
+  }
+
+  return EnvModule;
+}

packages/nest-utils/src/env/env.module-mixin.ts

@@ -0,0 +1 @@
+export * from './env.module-mixin';

packages/nest-utils/src/env/index.ts

@@ -1,4 +1,4 @@
-export * from './nest-utils.module';
+export * from './env';
 export * from './nest-utils.service';
 
 // As long as NestJS does not support TypeScript's newer resolution algorithms like 'Node16',