Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cristobalgvera/nestjs-environment
Environment module configuration library that allows you to easily setup and validate your environment with minimal configuration.
https://github.com/cristobalgvera/nestjs-environment
config environment library nestjs
Last synced: about 5 hours ago
JSON representation
Environment module configuration library that allows you to easily setup and validate your environment with minimal configuration.
- Host: GitHub
- URL: https://github.com/cristobalgvera/nestjs-environment
- Owner: cristobalgvera
- Created: 2023-05-10T12:07:16.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2023-06-21T02:14:26.000Z (over 1 year ago)
- Last Synced: 2024-04-26T23:02:44.426Z (7 months ago)
- Topics: config, environment, library, nestjs
- Language: TypeScript
- Homepage:
- Size: 198 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# NestJS Environment
Environment module configuration library that allows you to easily setup
and validate your environment with minimal configuration.
- Type safe environment usage.
- Complex environments variables (arrays and objects) validation.
## Installation
```bash
npm install @cristobalgvera/nestjs-environment
```
By the moment, the unique accepted source of validation is `Joi` (there are
plans to expand to any source of validation like `Zod`), so, you have to
install it too.
```bash
npm install joi
```
## Usage
The most basic usage possible is the following:
1. Create the `Environment` class. It needs to implements `BaseEnvironment`.
```ts
// environment/environment.model.ts
import { BaseEnvironment } from '@cristobalgvera/nestjs-environment';
export class Environment implements BaseEnvironment {
NODE_ENV: string; // or 'development' | 'test' | 'production'
}
```
1. Create a validation schema for that `Environment` using `Joi`. Remember to
create the test file too.
```ts
// environment/environment.schema.ts
import * as Joi from 'joi';
import { Environment } from './environment.model';
export const environmentSchema = Joi.object({
NODE_ENV: Joi.string().default('development'),
});
```
1. Import the `EnvironmentModule` using the `forRoot` static method and provide
the `Environment` class and the validation schema.
```ts
// app.module.ts
import { EnvironmentModule } from '@cristobalgvera/nestjs-environment';
import { Module } from '@nestjs/common';
import { Environment, environmentSchema } from './environment';
@Module({
imports: [
EnvironmentModule.forRoot({
environmentClass: Environment,
validationSchema: environmentSchema,
}),
],
})
export class AppModule {}
```
1. Use the `EnvironmentService` in any place you want through DI. You need
to provide as generic parameter the `Environment` class previously created
and it will be type-safe.
```ts
// test.service.ts
import { EnvironmentService } from '@cristobalgvera/nestjs-environment';
import { Injectable } from '@nestjs/common';
import { Environment } from './environment';
@Injectable()
export class TestService {
constructor(
private readonly environmentService: EnvironmentService,
) {}
getNodeEnvironment(): string {
const NODE_ENV = this.environmentService.get('NODE_ENV');
// ^? const NODE_ENV: string
return NODE_ENV;
}
}
```
1. Finally, to test it, simply mock it.
```ts
// test.service.spec.ts
import { TestBed } from '@automock/jest';
import { EnvironmentService } from '@cristobalgvera/nestjs-environment';
import { Environment } from './environment';
import { TestService } from './test.service';
describe('TestService', () => {
let underTest: TestService;
let environmentService: EnvironmentService;
beforeEach(() => {
const { unit, unitRef } = TestBed.create(TestService).compile();
underTest = unit;
environmentService = unitRef.get(EnvironmentService);
});
describe('getNodeEnvironment', () => {
const environment = {
NODE_ENV: 'development',
} as Readonly;
beforeEach(() => {
jest
.spyOn(environmentService, 'get')
.mockImplementation((key) => environment[key]);
});
it('should return the node environment', () => {
const expected = environment.NODE_ENV;
const actual = underTest.getNodeEnvironment();
expect(actual).toEqual(expected);
});
});
});
```
### Advance usage
Following the same structure described above, you can create complex
environment variables that can be validated. This complex types can be
arrays or custom objects that has an inner validation too.
The unique change you have to do it the following:
1. Add the `ParseEnvironment` decorator to the complex types.
```ts
// environment/environment.model.ts
import {
BaseEnvironment,
ParseEnvironment,
} from '@cristobalgvera/nestjs-environment';
import { User } from './user.model';
export class Environment implements BaseEnvironment {
NODE_ENV: 'development' | 'test' | 'production';
PORT: number;
IS_SWAGGER_ENABLED: boolean;
@ParseEnvironment() // <-- Use this to parse arrays of primitive values
ALLOWED_IPS: string[];
@ParseEnvironment({ toClass: true }) // <-- Use this to parse classes
INTERNAL_USER: User;
@ParseEnvironment({ toClass: true }) // <-- Use this to parse arrays of classes
EXTERNAL_USERS: User[];
}
```
1. Create the validation schema. Note the usage of a `userSchema` to validate
the users. This way you can easily test each schema separately.
```ts
// environment/environment.schema.ts
import * as Joi from 'joi';
import { Environment } from './environment.model';
import { userSchema } from './user.schema'; // Users can have their own schema
export const environmentSchema = Joi.object({
NODE_ENV: Joi.string()
.valid('development', 'test', 'production')
.default('development'),
PORT: Joi.number().port().default(8080),
IS_SWAGGER_ENABLED: Joi.boolean().default(true),
ALLOWED_IPS: Joi.array().items(Joi.string().ip()).required(),
INTERNAL_USER: userSchema.required(),
EXTERNAL_USERS: Joi.array().items(userSchema).required(),
});
```