@itgorillaz/configify 1.1.0

package/index.js

@@ -0,0 +1,6 @@
+'use strict';
+function __export(m) {
+    for (var p in m) if (!exports.hasOwnProperty(p)) exports[p] = m[p];
+}
+exports.__esModule = true;
+__export(require("./dist"));

package/index.ts

@@ -0,0 +1 @@
+export * from './src';

package/nest-cli.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "https://json.schemastore.org/nest-cli",
+  "collection": "@nestjs/schematics",
+  "sourceRoot": "src",
+  "compilerOptions": {
+    "deleteOutDir": true
+  }
+}

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@itgorillaz/configify",
+  "version": "1.1.0",
+  "description": "NestJS Config on Steroids",
+  "author": "tommelo",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/it-gorillaz/configify.git"
+  },
+  "keywords": [
+    "nestjs",
+    "config",
+    "yml",
+    ".env"
+  ],
+  "bugs": {
+    "url": "https://github.com/it-gorillaz/configify/issues"
+  },
+  "homepage": "https://github.com/it-gorillaz/configify#readme",
+  "scripts": {
+    "build": "nest build",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
+    "test": "jest --config ./test/jest.config.json --coverage --silent=false --verbose --runInBand"
+  },
+  "dependencies": {
+    "dotenv": "^16.3.1",
+    "js-yaml": "^4.1.0"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-secrets-manager": "^3.454.0",
+    "@aws-sdk/client-ssm": "^3.461.0",
+    "@nestjs/common": "^9.0.0 || ^10.0.0",
+    "@nestjs/core": "^9.0.0 || ^10.0.0",
+    "class-validator": "^0.14.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "rxjs": "^7.2.0"
+  },
+  "devDependencies": {
+    "@nestjs/cli": "^10.3.2",
+    "@nestjs/schematics": "^10.1.1",
+    "@nestjs/testing": "^10.3.7",
+    "@types/jest": "29.5.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "20.12.2",
+    "@types/supertest": "^6.0.2",
+    "@typescript-eslint/eslint-plugin": "^7.4.0",
+    "@typescript-eslint/parser": "^7.4.0",
+    "eslint": "^8.0.1",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.1.3",
+    "jest": "29.7.0",
+    "prettier": "^3.2.5",
+    "prettier-plugin-organize-imports": "^3.2.4",
+    "source-map-support": "^0.5.20",
+    "supertest": "^6.1.3",
+    "ts-jest": "29.1.2",
+    "ts-loader": "^9.2.3",
+    "ts-node": "^10.0.0",
+    "tsconfig-paths": "4.2.0",
+    "typescript": "^5.4.3"
+  },
+  "jest": {
+    "moduleFileExtensions": [
+      "js",
+      "json",
+      "ts"
+    ],
+    "rootDir": "src",
+    "testRegex": ".*\\.spec\\.ts$",
+    "transform": {
+      "^.+\\.(t|j)s$": "ts-jest"
+    },
+    "collectCoverageFrom": [
+      "**/*.(t|j)s"
+    ],
+    "coverageDirectory": "../coverage",
+    "testEnvironment": "node"
+  }
+}

package/src/configify.module.ts

@@ -0,0 +1,241 @@
+import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+import { SSMClient } from '@aws-sdk/client-ssm';
+import { DynamicModule, Module, Provider } from '@nestjs/common';
+import { validateSync } from 'class-validator';
+import * as fs from 'fs';
+import { resolve } from 'path';
+import {
+  AwsSecretsManagerConfigurationResolver,
+  ConfigfyModuleOptions,
+  ConfigurationParserFactory,
+  ConfigurationProviders,
+  ConfigurationRegistry,
+  DefaultConfigfyModuleOptions,
+} from './configuration';
+import { AwsParameterStoreConfigurationResolver } from './configuration/resolvers/aws/parameter-store-configuration.resolver';
+import { Variables } from './interpolation/variables';
+
+/**
+ * The configify module.
+ * A NestJS configuration module on steroids.
+ *
+ * This module provides out of the box configuration files parsing,
+ * remote secrets fetching, variables expansion and configuration validation.
+ *
+ * The lifecycle of the module consists of:
+ * - Reading configuration files
+ * - Resolving remote secrets
+ * - Expanding variables
+ * - Creating object instances decored with Configuration and assigning its values
+ * - Validating the configuration instance
+ *
+ * All the configuration set to the configuration files will be assigned to the process.env object
+ */
+@Module({})
+export class ConfigifyModule {
+  /**
+   * The default configuration files.
+   * If no configuration files are provided this module will
+   * lookup at a .env, application.yml and an application.json files
+   * at the root path of the project.
+   */
+  private static readonly DEFAULT_CONFIG_FILES = [
+    resolve(process.cwd(), '.env'),
+    resolve(process.cwd(), 'application.yml'),
+    resolve(process.cwd(), 'application.json'),
+  ];
+
+  /**
+   * The remote secrets resolvers pipeline.
+   * This module currently supports resolving secrets on
+   * AWS Secrets Manager and AWS Parameters Store.
+   */
+  private static readonly SECRETS_RESOLVER_PIPELINE = [
+    (options: ConfigfyModuleOptions) =>
+      new AwsSecretsManagerConfigurationResolver(
+        options.secretsManagerClient || new SecretsManagerClient(),
+      ),
+
+    (options: ConfigfyModuleOptions) =>
+      new AwsParameterStoreConfigurationResolver(
+        options.ssmClient || new SSMClient(),
+      ),
+  ];
+
+  /**
+   * Creates the configfy dynamic module.
+   *
+   * The module will manage the instance of all classes decorated the Configuration decorator,
+   * meaning, the module will instanciate and associate the value to attributes according to the
+   * keys provided by the Value decorator.
+   *
+   * The configuration key pair values will also be available on process.env object.
+   *
+   * @param   { ConfigfyModuleOptions } options The module config options
+   * @returns { DynamicModule }         module  The configy module
+   */
+  static async forRootAsync(
+    options: ConfigfyModuleOptions = {},
+  ): Promise<DynamicModule> {
+    const settings = { ...options, ...DefaultConfigfyModuleOptions };
+    const files = this.resolveConfigurationFiles(settings.configFilePath);
+
+    const envVars = settings.ignoreEnvVars ? {} : process.env;
+    const fromFile = settings.ignoreConfigFile
+      ? {}
+      : this.parseConfigurationFiles(files);
+
+    const container = { ...envVars, ...fromFile };
+    const secrets = await this.runSecretsResolverPipeline(container, settings);
+    const configuration = { ...container, ...secrets };
+
+    if (settings.expandConfig) {
+      const expanded = Variables.expand(configuration);
+      Object.assign(configuration, expanded);
+    }
+
+    Object.assign(process.env, configuration);
+
+    const { exports, providers } = this.buildConfigurationProviders();
+
+    return {
+      exports,
+      providers,
+      global: true,
+      module: ConfigifyModule,
+    };
+  }
+
+  /**
+   * Runs the secrets resolver pipeline.
+   *
+   * @param   {Record<string, any>}            config the configuration object
+   * @param   {ConfigfyModuleOptions}          options the module options
+   * @returns {Promise<Record<string, any>>}   the resolved secrets
+   */
+  private static async runSecretsResolverPipeline(
+    config: Record<string, any>,
+    options: ConfigfyModuleOptions,
+  ): Promise<Record<string, any>> {
+    const secrets = {};
+    for (const buildResolver of this.SECRETS_RESOLVER_PIPELINE) {
+      const resolver = buildResolver(options);
+      const result = await resolver.resolve(config);
+      Object.assign(secrets, result);
+    }
+    return secrets;
+  }
+
+  /**
+   * Creates the configuration module providers.
+   * It creates the configuration instances, assign its value
+   * and perform the object validation.
+   *
+   * @returns {ConfigurationProviders} the module configuration providers
+   */
+  private static buildConfigurationProviders(): ConfigurationProviders {
+    const exports = [];
+    const providers: Provider[] = [];
+
+    const registry = ConfigurationRegistry.getRegistry();
+    for (const ConfigType of registry) {
+      const instance = new ConfigType();
+
+      const attributes =
+        ConfigurationRegistry.getValueDecoratedAttributes(instance);
+
+      for (const attribute of attributes) {
+        const metadata = ConfigurationRegistry.getValueDecoratedKey(
+          instance,
+          attribute,
+        );
+
+        const parse = metadata.options?.parse;
+        const value = parse
+          ? parse(process.env[metadata.key])
+          : process.env[metadata.key];
+
+        instance[attribute] = value;
+      }
+
+      const errors = validateSync(instance);
+      if (errors && errors.length) {
+        throw new Error(
+          `validation constraints violated:\n${errors
+            .map((e) =>
+              JSON.stringify(
+                { attribute: e.property, constraints: e.constraints },
+                null,
+                2,
+              ),
+            )
+            .join('\n')}`,
+        );
+      }
+
+      exports.push(ConfigType);
+      providers.push({ provide: ConfigType, useValue: instance });
+    }
+
+    return { exports, providers };
+  }
+
+  /**
+   * Flattens a nested object into an one level key value pair object
+   *
+   * @param {object}              source the source object
+   * @param {string[]}            path   the key path
+   * @param {Record<string, any>} target the target object
+   */
+  private static flattenObjectKeys(
+    source: any,
+    path: string[] = [],
+    target: Record<string, any> = {},
+  ) {
+    if (typeof source === 'object') {
+      for (const key in source) {
+        this.flattenObjectKeys(source[key], [...path, key], target);
+      }
+    } else {
+      target[path.join('.')] = source;
+    }
+  }
+
+  /**
+   * Parses configuration files and assign its contents to a configuration object.
+   *
+   * @param   {string[]} files  the configuration file paths
+   * @returns {object}          the object representation of the configuration files
+   */
+  private static parseConfigurationFiles(files: string[]): Record<string, any> {
+    const kv = {};
+    const config = {};
+
+    for (const file of files) {
+      const parser = ConfigurationParserFactory.getParser(file);
+      const parsed = parser.parse(file);
+      Object.assign(config, parsed);
+    }
+
+    this.flattenObjectKeys(config, [], kv);
+
+    return kv;
+  }
+
+  /**
+   * Resolve the path of the configuration files.
+   * It ignores files that does not exist or is not
+   * suppported by the configuration parsers.
+   *
+   * @param   {string | string[]} path  the configuration path
+   * @returns {string[]}                list of configuration files
+   */
+  private static resolveConfigurationFiles(path?: string | string[]): string[] {
+    return []
+      .concat(path, this.DEFAULT_CONFIG_FILES)
+      .filter(
+        (file) =>
+          fs.existsSync(file) && ConfigurationParserFactory.supports(file),
+      );
+  }
+}

package/src/configuration/configuration-options.interface.ts

@@ -0,0 +1,51 @@
+import { SecretsManagerClient } from '@aws-sdk/client-secrets-manager';
+import { SSMClient } from '@aws-sdk/client-ssm';
+
+/**
+ * The configuration options interface
+ */
+export interface ConfigfyModuleOptions {
+  /**
+   * Ignores any config file.
+   * The default value is false;
+   */
+  ignoreConfigFile?: boolean;
+
+  /**
+   * Ignores environment variables
+   * The default value is false;
+   */
+  ignoreEnvVars?: boolean;
+
+  /**
+   * The path of the configuration files
+   */
+  configFilePath?: string | string[];
+
+  /**
+   * Expands variables
+   * The default value is true
+   */
+  expandConfig?: boolean;
+
+  /**
+   * The AWS Secrets Manager Client
+   * If no client is provided, the module will create one.
+   */
+  secretsManagerClient?: SecretsManagerClient;
+
+  /**
+   * The AWS Systems Manager Client
+   * If no client is provided, the module will create one.
+   */
+  ssmClient?: SSMClient;
+}
+
+/**
+ * The default module options
+ */
+export const DefaultConfigfyModuleOptions: ConfigfyModuleOptions = {
+  ignoreConfigFile: false,
+  ignoreEnvVars: false,
+  expandConfig: true,
+};

package/src/configuration/configuration-parser.interface.ts

@@ -0,0 +1,15 @@
+/**
+ * The configuraion parser interface.
+ * This interface is implemented by all
+ * the supported configuration parsers.
+ */
+export interface ConfigurationParser {
+  /**
+   * Reads a file and assign its values
+   * to an object representation;
+   *
+   * @param   {string}              file the configuration file path
+   * @returns {Record<string, any>}      the object representation of the configuration file
+   */
+  parse(file: string): Record<string, any>;
+}

package/src/configuration/configuration-providers.interface.ts

@@ -0,0 +1,9 @@
+import { Provider } from '@nestjs/common';
+
+/**
+ * The configuration providers interface
+ */
+export interface ConfigurationProviders {
+  exports: any[];
+  providers: Provider[];
+}

package/src/configuration/configuration.registry.ts

@@ -0,0 +1,70 @@
+import {
+  ValueDecoratedKey,
+  VALUE_METADATA,
+  VALUE_PROPERTIES_METADATA,
+} from '../decorators';
+
+/**
+ * The configuration registry.
+ *
+ * The registry keeps track of all classes decorated
+ * with Configuration decorator.
+ */
+export class ConfigurationRegistry {
+  private static readonly registry = [];
+
+  /**
+   * Registers a type.
+   *
+   * @param {any} type the class type
+   */
+  static registerTarget(type: any): void {
+    this.registry.push(type);
+  }
+
+  /**
+   * Registers a class attribute.
+   *
+   * @param {any}    target    the class target
+   * @param {string} attribute the attribute name
+   */
+  static registerAttribute(target: any, attribute: string): void {
+    (
+      target[VALUE_PROPERTIES_METADATA] ||
+      (target[VALUE_PROPERTIES_METADATA] = [])
+    ).push(attribute);
+  }
+
+  /**
+   * Returns the configuration registry.
+   *
+   * @returns {any[]} the configuration registry
+   */
+  static getRegistry(): any[] {
+    return this.registry;
+  }
+
+  /**
+   * Returns the class attribute names decorated with Decorated decorator
+   *
+   * @param   {any}      target the instance target;
+   * @returns {string[]} the list of attribute names
+   */
+  static getValueDecoratedAttributes(target: any): string[] {
+    return target[VALUE_PROPERTIES_METADATA];
+  }
+
+  /**
+   * Returns the value of the decorated key.
+   *
+   * @param   {any}               instance  the target instance
+   * @param   {string}            attribute the attribute name
+   * @returns {ValueDecoratedKey}           the value decorated key
+   */
+  static getValueDecoratedKey(
+    instance: any,
+    attribute: string,
+  ): ValueDecoratedKey {
+    return Reflect.getMetadata(VALUE_METADATA, instance, attribute);
+  }
+}

package/src/configuration/index.ts

@@ -0,0 +1,6 @@
+export * from './configuration-options.interface';
+export * from './configuration-parser.interface';
+export * from './configuration-providers.interface';
+export * from './configuration.registry';
+export * from './parsers';
+export * from './resolvers';

package/src/configuration/parsers/configuration-parser.factory.ts

@@ -0,0 +1,53 @@
+import { ConfigurationParser } from '../configuration-parser.interface';
+import { DotEnvConfigurationParser } from './dotenv-configuration.parser';
+import { JsonConfigurationParser } from './json-configuration.parser';
+import { YamlConfigurationParser } from './yaml-configuration.parser';
+
+/**
+ * The configuration parser factory.
+ * This factory class contains all the supported
+ * file configuration parsers.
+ */
+export class ConfigurationParserFactory {
+  /**
+   * The supported file configuration parsers
+   */
+  private static readonly parsers = {
+    env: new DotEnvConfigurationParser(),
+    yml: new YamlConfigurationParser(),
+    yaml: new YamlConfigurationParser(),
+    json: new JsonConfigurationParser(),
+  };
+
+  /**
+   * Gets the file configuration parser based
+   * on the file extension.
+   * @param   {string}              file the configuration file name
+   * @returns {ConfigurationParser}      the configuration parser
+   */
+  static getParser(file: string): ConfigurationParser {
+    const ext = this.getFileExt(file);
+    return this.parsers[ext];
+  }
+
+  /**
+   * Checks if the given file has a parser registered.
+   *
+   * @param   {string} file the configuration file name
+   * @returns {boolean}     true if a parser is found, false otherwise
+   */
+  static supports(file: string): boolean {
+    const ext = this.getFileExt(file);
+    return this.parsers.hasOwnProperty(ext);
+  }
+
+  /**
+   * Returns the file extension.
+   *
+   * @param   {string} file the file name
+   * @returns {string}      the file extension
+   */
+  private static getFileExt(file: string): string {
+    return file.split('.').pop();
+  }
+}

package/src/configuration/parsers/dotenv-configuration.parser.ts

@@ -0,0 +1,18 @@
+import * as dotenv from 'dotenv';
+import * as fs from 'fs';
+import { ConfigurationParser } from '../configuration-parser.interface';
+
+/**
+ * Dotenv configuration parser.
+ */
+export class DotEnvConfigurationParser implements ConfigurationParser {
+  /**
+   * Reads the configuration file and assign
+   * its contents to an object.
+   * @param   {string}              file the configuration file
+   * @returns {Record<string, any>}      an object representation of the configuration file
+   */
+  public parse(file: string): Record<string, any> {
+    return dotenv.parse(fs.readFileSync(file));
+  }
+}

package/src/configuration/parsers/index.ts

@@ -0,0 +1,4 @@
+export * from './configuration-parser.factory';
+export * from './dotenv-configuration.parser';
+export * from './json-configuration.parser';
+export * from './yaml-configuration.parser';

package/src/configuration/parsers/json-configuration.parser.ts

@@ -0,0 +1,17 @@
+import * as fs from 'fs';
+import { ConfigurationParser } from '../configuration-parser.interface';
+
+/**
+ * JSON configuration parser
+ */
+export class JsonConfigurationParser implements ConfigurationParser {
+  /**
+   * Reads the configuration file and assign
+   * its contents to an object.
+   * @param   {string}              file the configuration file
+   * @returns {Record<string, any>}      an object representation of the configuration file
+   */
+  public parse(file: string): Record<string, any> {
+    return JSON.parse(fs.readFileSync(file, 'utf-8'));
+  }
+}

package/src/configuration/parsers/yaml-configuration.parser.ts

@@ -0,0 +1,18 @@
+import * as fs from 'fs';
+import * as yaml from 'js-yaml';
+import { ConfigurationParser } from '../configuration-parser.interface';
+
+/**
+ * YAML configuration parser
+ */
+export class YamlConfigurationParser implements ConfigurationParser {
+  /**
+   * Reads the configuration file and assign
+   * its contents to an object.
+   * @param   {string}              file the configuration file
+   * @returns {Record<string, any>}      an object representation of the configuration file
+   */
+  public parse(file: string): Record<string, any> {
+    return yaml.load(fs.readFileSync(file, 'utf-8'));
+  }
+}

package/src/configuration/resolvers/aws/index.ts

@@ -0,0 +1,2 @@
+export * from './parameter-store-configuration.resolver';
+export * from './secrets-manager-configuration.resolver';