@rsdk/core 0.14.0

package/src/config/index.ts

@@ -0,0 +1,10 @@
+export * from './parsers';
+export * from './config.module';
+export * from './sources';
+export * from './config.abstract';
+export * from './metadata';
+export * from './types';
+export * from './reload';
+export { AdditionalSourceModule } from './additional-source/additional-source.module';
+export { AdditionalSourceOptions } from './additional-source/additional-source.module';
+export { ConfigPropertyMetadataNotFound } from './exceptions';

package/src/config/metadata/config-metadata.registry.ts

@@ -0,0 +1,76 @@
+import type { Constructor } from '@rsdk/common';
+
+import { IndicatorsRegistry } from '../../health/metadata';
+import type { Config } from '../config.abstract';
+import { ConfigReloadIndicator } from '../config-reload.indicator';
+import type { ConfigSource } from '../sources';
+import type {
+  PropertyMetadata,
+  SectionMetadata,
+  SourceMetadata,
+} from '../types';
+
+import {
+  DuplicatePropertyException,
+  DuplicateSectionException,
+  DuplicateSourceException,
+} from './exceptions';
+
+export class ConfigMetadataRegistry {
+  private static properties = new Map<string, PropertyMetadata>();
+  private static sources = new Map<Constructor<ConfigSource>, SourceMetadata>();
+  private static sections = new Map<Constructor<Config>, SectionMetadata>();
+
+  static registerSource(
+    target: Constructor<ConfigSource>,
+    metadata: SourceMetadata,
+  ): void {
+    if (this.sources.has(target)) {
+      throw new DuplicateSourceException(target);
+    }
+
+    if (
+      metadata.type === 'reloadable' &&
+      !IndicatorsRegistry.isRegistered(ConfigReloadIndicator)
+    ) {
+      IndicatorsRegistry.register(ConfigReloadIndicator, {
+        description: 'Will be "down" if there are problems with config reload',
+        key: 'config-reload',
+        scope: 'common',
+      });
+    }
+
+    this.sources.set(target, metadata);
+  }
+
+  static registerSection(
+    target: Constructor<Config>,
+    metadata: SectionMetadata,
+  ): void {
+    if (this.sections.has(target)) {
+      throw new DuplicateSectionException(target);
+    }
+
+    this.sections.set(target, metadata);
+  }
+
+  static registerProperty(alias: string, metadata: PropertyMetadata): void {
+    if (this.properties.has(alias)) {
+      throw new DuplicatePropertyException(alias);
+    }
+
+    this.properties.set(alias, metadata);
+  }
+
+  static getMetadata(): Readonly<{
+    sources: Map<Constructor<ConfigSource>, SourceMetadata>;
+    sections: Map<Constructor<Config>, SectionMetadata>;
+    properties: Map<string, PropertyMetadata>;
+  }> {
+    return {
+      properties: this.properties,
+      sections: this.sections,
+      sources: this.sources,
+    };
+  }
+}

package/src/config/metadata/decorators/config-section.decorator.ts

@@ -0,0 +1,30 @@
+/* eslint-disable @typescript-eslint/ban-types */
+import type { Constructor } from '@rsdk/common';
+
+import type { SectionMetadata } from '../../types';
+import { ConfigMetadataRegistry } from '../config-metadata.registry';
+
+import { CONFIG_METADATA_KEY } from './property.decorator';
+
+export interface ConfigSectionOptions {
+  name?: string;
+  description?: string;
+}
+
+/**
+ * Sets metadata for Config class
+ * @param options ConfigSectionOptions
+ * @returns ClassDecorator
+ */
+export const ConfigSection = (options?: ConfigSectionOptions): ClassDecorator =>
+  function (target: Function): void {
+    const metadata = Reflect.getMetadata(
+      CONFIG_METADATA_KEY,
+      target,
+    ) as SectionMetadata;
+
+    ConfigMetadataRegistry.registerSection(target as Constructor, {
+      ...metadata,
+      ...(options || {}),
+    });
+  };

package/src/config/metadata/decorators/declare-property.decorator.ts

@@ -0,0 +1,37 @@
+import type { ConfigValue, PropertyOptions, PropertyParser } from '../../types';
+import { ConfigMetadataRegistry } from '../config-metadata.registry';
+
+/**
+ * Declares standalone property. Properties declared in this way,
+ * can be injected with @InjectProperty() decorator.
+ *
+ * Main usecase is custom ConfigSources. They are constructed outside of
+ * Nest.js context, so common DI is not available. But @InjectProperty()
+ * works.
+ *
+ * @param alias Property key.
+ * @param parser Class that gets value from config storate
+ * and validates it in some way. Ex: IntParser, BoolParser etc.
+ * @param options Property options, in particular description and
+ * default value if exists
+ * @returns ClassDecorator
+ */
+export const DeclareProperty = <T extends ConfigValue>(
+  /**
+   * Alias is used not only to declare, but also to inject
+   * properties. That's why this string is saved as is, while
+   * key is the same string converted to upper snake case.
+   */
+  alias: string,
+  parser: PropertyParser<T>,
+  options: PropertyOptions<T>,
+): ClassDecorator => {
+  return function (): void {
+    ConfigMetadataRegistry.registerProperty(alias, {
+      expectedInEnv: true,
+      ...options,
+      key: alias,
+      parser,
+    });
+  };
+};

package/src/config/metadata/decorators/index.ts

@@ -0,0 +1,4 @@
+export * from './config-section.decorator';
+export * from './property.decorator';
+export * from './inject-property.decorator';
+export * from './declare-property.decorator';

package/src/config/metadata/decorators/inject-property.decorator.ts

@@ -0,0 +1,29 @@
+import { Inject } from '@nestjs/common';
+
+const TOKEN_PREFIX = 'STANDALONE_CONFIG_PROPERTY_';
+
+export type PropertyToken = `${typeof TOKEN_PREFIX}${string}`;
+
+export const getPropertyToken = (name: string): PropertyToken =>
+  `${TOKEN_PREFIX}${name}`;
+
+export const isPropertyToken = (x: unknown): x is PropertyToken =>
+  typeof x === 'string' && x.startsWith(TOKEN_PREFIX);
+
+export const trimPrefix = (token: PropertyToken): string =>
+  token.slice(TOKEN_PREFIX.length - 1);
+
+/**
+ * Decorator is used for 2 scenarios:
+ *
+ * 1. To inject properties into ConfigSource constructors. In this case
+ * one should add @DeclareProperty() to ConfigSource constructor first.
+ *
+ * 2. To create and inject dynamic properties (ex: @rsdk/grpc-clients).
+ * In this case they should be registered manually using
+ * ConfigMetadataRegistry.registerProperty() method.
+ *
+ * NOTE: don't use it in application code! Only in libraries!
+ */
+export const InjectProperty = (name: string): ParameterDecorator =>
+  Inject(getPropertyToken(name));

package/src/config/metadata/decorators/property.decorator.ts

@@ -0,0 +1,42 @@
+import type {
+  ConfigValue,
+  PropertyOptions,
+  PropertyParser,
+  SectionMetadata,
+} from '../../types';
+
+export const CONFIG_METADATA_KEY = 'CONFIG_METADATA';
+
+/**
+ * Sets metadata that will be used to populate the field
+ * during configuration module bootstrap
+ *
+ * @param key Key of property (with prefix or not)
+ * @param parser Extraction and validation algorithm
+ * @param options Additional options (default value, description etc.)
+ * @returns PropertyDecorator
+ */
+export const Property = <T extends ConfigValue>(
+  key: string,
+  parser: PropertyParser<T>,
+  options: PropertyOptions<T>,
+): PropertyDecorator =>
+  function (target: object, propertyKey: string | symbol): void {
+    const ctor = target.constructor;
+
+    const metadata = (Reflect.getMetadata(
+      CONFIG_METADATA_KEY,
+      ctor,
+    ) as SectionMetadata) || { properties: {} };
+
+    metadata.properties[propertyKey] = {
+      expectedInEnv: false,
+      key,
+      parser,
+      ...options,
+    };
+
+    Reflect.defineMetadata(CONFIG_METADATA_KEY, metadata, ctor);
+  };
+
+// https://stackoverflow.com/questions/42281045/can-typescript-property-decorators-set-metadata-for-the-class

package/src/config/metadata/exceptions/duplicate-property.exception.ts

@@ -0,0 +1,12 @@
+import { text } from '@rsdk/common';
+
+import { BootstrapException, Exception } from '../../../exceptions';
+
+@Exception({
+  description: text`Duplicate ConfigProperty`,
+})
+export class DuplicatePropertyException extends BootstrapException {
+  constructor(alias: string) {
+    super(`Standalone property with alias ${alias} is already registered`);
+  }
+}

package/src/config/metadata/exceptions/duplicate-section.exception.ts

@@ -0,0 +1,13 @@
+import { Constructor, text } from '@rsdk/common';
+
+import { BootstrapException, Exception } from '../../../exceptions';
+import type { Config } from '../../config.abstract';
+
+@Exception({
+  description: text`Duplicate @ConfigSection with same class name`,
+})
+export class DuplicateSectionException extends BootstrapException {
+  constructor(section: Constructor<Config>) {
+    super(`Config section ${section} is already registered`);
+  }
+}

package/src/config/metadata/exceptions/duplicate-source.exception.ts

@@ -0,0 +1,13 @@
+import { Constructor, text } from '@rsdk/common';
+
+import { BootstrapException, Exception } from '../../../exceptions';
+import type { ConfigSource } from '../../sources';
+
+@Exception({
+  description: text`Duplicate configuration source`,
+})
+export class DuplicateSourceException extends BootstrapException {
+  constructor(source: Constructor<ConfigSource>) {
+    super(`Config source ${source.name} is already registered`);
+  }
+}

package/src/config/metadata/exceptions/index.ts

@@ -0,0 +1,3 @@
+export * from './duplicate-property.exception';
+export * from './duplicate-section.exception';
+export * from './duplicate-source.exception';

package/src/config/metadata/index.ts

@@ -0,0 +1,2 @@
+export * from './decorators';
+export * from './config-metadata.registry';

package/src/config/parsers/array.parser.ts

@@ -0,0 +1,40 @@
+import { Assert, text } from '@rsdk/common';
+
+import type {
+  PropertyParser,
+  RawConfigValue,
+  SingleConfigValue,
+} from '../types';
+
+export class ArrayParser<T extends SingleConfigValue>
+  implements PropertyParser<T[]>
+{
+  constructor(
+    private readonly singleValueParser: PropertyParser<T>,
+    private readonly options = { separator: ',' },
+  ) {}
+
+  type(): string {
+    return `(array)${this.singleValueParser.type()}`;
+  }
+
+  description(): string {
+    return text`
+      Extracts array of values. If raw value is a string
+      <${this.options.separator}> will used as separator. Each value:
+      ${this.singleValueParser.description()}
+    `;
+  }
+
+  parse(value: RawConfigValue): T[] {
+    if (Array.isArray(value)) {
+      return value.map((x) => this.singleValueParser.parse(x));
+    }
+
+    Assert.isString(value);
+
+    return value
+      .split(this.options.separator)
+      .map((x) => this.singleValueParser.parse(x));
+  }
+}

package/src/config/parsers/boolean/bool.parser.ts

@@ -0,0 +1,20 @@
+import { Convert, text } from '@rsdk/common';
+
+import type { PropertyParser, RawConfigValue } from '../../types';
+
+export class BoolParser implements PropertyParser<boolean> {
+  type(): string {
+    return 'boolean';
+  }
+
+  description(): string {
+    return text`
+      Extracts boolean value. Any boolean value or strings
+      'true' and 'false' will pass.
+    `;
+  }
+
+  parse(value: RawConfigValue): boolean {
+    return Convert.boolean(value);
+  }
+}

package/src/config/parsers/boolean/bool.spec.ts

@@ -0,0 +1,4 @@
+describe('BoolParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests for Convert.boolean() in @rsdk/common', () => expect(true).toBe(true))
+})

package/src/config/parsers/boolean/index.ts

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

package/src/config/parsers/enum/enum.parser.ts

@@ -0,0 +1,23 @@
+import type { EnumLike, EnumValue } from '@rsdk/common';
+import { Convert, Enum, text } from '@rsdk/common';
+
+import type { PropertyParser, RawConfigValue } from '../../types';
+
+export class EnumParser<E extends EnumValue> implements PropertyParser<E> {
+  constructor(private readonly enumeration: EnumLike) {}
+
+  type(): string {
+    return `string|number(enum_value)`;
+  }
+
+  description(): string {
+    return text`
+      Extracts strings or numbers and ensures it is one of:
+      ${Enum.values(this.enumeration).join(', ')}
+    `;
+  }
+
+  parse(value: RawConfigValue): E {
+    return Convert.enum<E>(value, this.enumeration);
+  }
+}

package/src/config/parsers/enum/enum.spec.ts

@@ -0,0 +1,5 @@
+describe('EnumParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests for Convert.enum() in @rsdk/common', () =>
+    expect(true).toBe(true));
+});

package/src/config/parsers/enum/index.ts

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

package/src/config/parsers/index.ts

@@ -0,0 +1,10 @@
+export * from './boolean';
+export * from './enum';
+export * from './int';
+export * from './number';
+export * from './path';
+export * from './size';
+export * from './string';
+export * from './timespan';
+export * from './url';
+export * from './array.parser';

package/src/config/parsers/int/index.ts

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

package/src/config/parsers/int/int.parser.ts

@@ -0,0 +1,20 @@
+import { Convert, text } from '@rsdk/common';
+
+import type { PropertyParser, RawConfigValue } from '../../types';
+
+export class IntParser implements PropertyParser<number> {
+  type(): string {
+    return 'number(int)';
+  }
+
+  description(): string {
+    return text`
+      Extracts valid integer (uses parseInt under the hood).
+      Floating point numbers, NaN, Infinity will be rejected.
+    `;
+  }
+
+  parse(value: RawConfigValue): number {
+    return Convert.int(value);
+  }
+}

package/src/config/parsers/int/int.spec.ts

@@ -0,0 +1,5 @@
+describe('IntParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests for Convert.int() in @rsdk/common', () =>
+    expect(true).toBe(true));
+});

package/src/config/parsers/number/index.ts

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

package/src/config/parsers/number/number.parser.ts

@@ -0,0 +1,23 @@
+import { Convert, text } from '@rsdk/common';
+
+import type { PropertyParser, RawConfigValue } from '../../types';
+
+export class NumberParser implements PropertyParser<number> {
+  type(): string {
+    return 'number';
+  }
+
+  description(): string {
+    return text`
+      Extracts numeric value (uses parseFloat under the hood).
+      NaN and Infinity will be rejected.
+
+      NOTE: Use correct decimal delimiter according to locale. See
+      https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl
+    `;
+  }
+
+  parse(value: RawConfigValue): number {
+    return Convert.number(value);
+  }
+}

package/src/config/parsers/number/number.spec.ts

@@ -0,0 +1,5 @@
+describe('NumberParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests for Convert.number() in @rsdk/common', () =>
+    expect(true).toBe(true));
+});

package/src/config/parsers/path/fspath.parser.ts

@@ -0,0 +1,65 @@
+import { accessSync, existsSync, lstatSync } from 'fs';
+import { isAbsolute, join } from 'path';
+import { cwd } from 'process';
+
+import { Assert, text } from '@rsdk/common';
+
+import type { PropertyParser, RawConfigValue } from '../../types';
+
+export class FsPathParser implements PropertyParser<string> {
+  constructor(private readonly objectType: 'file' | 'dir') {}
+
+  type(): string {
+    return 'string(fs_path)';
+  }
+
+  description(): string {
+    return text`
+      Extracts path to file or directory. Checks that object exists on
+      file system and that application has access to it.
+    `;
+  }
+
+  parse(value: RawConfigValue): string {
+    Assert.isString(value);
+
+    const wasRelative = !isAbsolute(value);
+    const absolutePath = wasRelative ? join(cwd(), value) : value;
+
+    if (!existsSync(absolutePath)) {
+      const warning = wasRelative
+        ? ' Since you have used relative path, check you current working directory is repos root.'
+        : '';
+
+      throw new Error(
+        `File or directory <${absolutePath}> not found!${warning}`,
+      );
+    }
+
+    try {
+      accessSync(absolutePath);
+    } catch (error) {
+      throw new Error(`Can't access <${absolutePath}>!`);
+    }
+
+    const stat = lstatSync(absolutePath);
+
+    /**
+     * Otherwise we'll have problems with IsNotDirectoryException
+     * when using symlinks.
+     */
+    if (stat.isSymbolicLink()) {
+      return absolutePath;
+    }
+
+    if (this.objectType === 'dir' && !stat.isDirectory()) {
+      throw new Error(`<${absolutePath}> is not a directory!`);
+    }
+
+    if (this.objectType === 'file' && !stat.isFile()) {
+      throw new Error(`<${absolutePath}> is not a file!`);
+    }
+
+    return absolutePath;
+  }
+}

package/src/config/parsers/path/index.ts

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

package/src/config/parsers/size/index.ts

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

package/src/config/parsers/size/size.parser.ts

@@ -0,0 +1,22 @@
+import { Assert, Size, SIZE_STRING_PATTERN, text } from '@rsdk/common';
+
+import type { PropertyParser, RawConfigValue } from '../../types';
+
+export class SizeParser implements PropertyParser<Size> {
+  type(): string {
+    return 'Timespan';
+  }
+
+  description(): string {
+    return text`
+      Parses string in size format into Timespan instance.
+      Format is: ${SIZE_STRING_PATTERN}. For example: 8b, 10kb, 2gb.
+    `;
+  }
+
+  parse(value: RawConfigValue): Size {
+    Assert.isString(value);
+
+    return Size.parse(value);
+  }
+}

package/src/config/parsers/size/size.spec.ts

@@ -0,0 +1,4 @@
+describe('SizeParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests in @rsdk/common', () => expect(true).toBe(true))
+})

package/src/config/parsers/string/index.ts

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

package/src/config/parsers/string/string.parser.ts

@@ -0,0 +1,19 @@
+import { Assert } from '@rsdk/common';
+
+import type { PropertyParser, RawConfigValue } from '../../types';
+
+export class StringParser implements PropertyParser<string> {
+  type(): string {
+    return 'string';
+  }
+
+  description(): string {
+    return 'Extract arbitrary string.';
+  }
+
+  parse(value: RawConfigValue): string {
+    Assert.isString(value);
+
+    return value;
+  }
+}

package/src/config/parsers/timespan/index.ts

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

package/src/config/parsers/timespan/timespan.parser.ts

@@ -0,0 +1,27 @@
+import {
+  Assert,
+  text,
+  Timespan,
+  TIMESPAN_STRING_PATTERN,
+} from '@rsdk/common';
+
+import type { PropertyParser, RawConfigValue } from '../../types';
+
+export class TimespanParser implements PropertyParser<Timespan> {
+  type(): string {
+    return 'Timespan';
+  }
+
+  description(): string {
+    return text`
+      Parses string in timespan format into Timespan instance.
+      Format is: ${TIMESPAN_STRING_PATTERN}. For example: 1s, 2h, 4d.
+    `;
+  }
+
+  parse(value: RawConfigValue): Timespan {
+    Assert.isString(value);
+
+    return Timespan.parse(value);
+  }
+}

package/src/config/parsers/timespan/timespan.spec.ts

@@ -0,0 +1,4 @@
+describe('TimespanParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests for Timespan class in @rsdk/common', () => expect(true).toBe(true))
+})

package/src/config/parsers/url/index.ts

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

package/src/config/parsers/url/url.parser.ts

@@ -0,0 +1,19 @@
+import { Assert } from '@rsdk/common';
+
+import type { PropertyParser, RawConfigValue } from '../../types';
+
+export class UrlParser implements PropertyParser<URL> {
+  type(): string {
+    return 'URL';
+  }
+
+  description(): string {
+    return 'Parses string into instance of URL';
+  }
+
+  parse(value: RawConfigValue): URL {
+    Assert.isString(value);
+
+    return new URL(value);
+  }
+}