@hg-ts/config-loader 0.5.17 → 0.5.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hg-ts/config-loader",
-  "version": "0.5.17",
+  "version": "0.5.19",
   "main": "dist/index.js",
   "type": "module",
   "exports": {
@@ -18,12 +18,12 @@
     "test:dev": "vitest watch"
   },
   "devDependencies": {
-    "@hg-ts-config/typescript": "0.5.17",
-    "@hg-ts/exception": "0.5.17",
-    "@hg-ts/execution-mode": "0.5.17",
-    "@hg-ts/linter": "0.5.17",
-    "@hg-ts/tests": "0.5.17",
-    "@hg-ts/types": "0.5.17",
+    "@hg-ts-config/typescript": "0.5.19",
+    "@hg-ts/exception": "0.5.19",
+    "@hg-ts/execution-mode": "0.5.19",
+    "@hg-ts/linter": "0.5.19",
+    "@hg-ts/tests": "0.5.19",
+    "@hg-ts/types": "0.5.19",
     "@nestjs/common": "11.1.0",
     "@types/node": "22.19.1",
     "@vitest/coverage-v8": "4.0.14",
@@ -37,8 +37,8 @@
     "vitest": "4.0.14"
   },
   "peerDependencies": {
-    "@hg-ts/exception": "0.5.17",
-    "@hg-ts/execution-mode": "0.5.17",
+    "@hg-ts/exception": "0.5.19",
+    "@hg-ts/execution-mode": "0.5.19",
     "@nestjs/common": "*",
     "reflect-metadata": "*",
     "rxjs": "*",
@@ -46,6 +46,6 @@
     "vitest": "*"
   },
   "dependencies": {
-    "@hg-ts/validation": "0.5.17"
+    "@hg-ts/validation": "0.5.19"
   }
 }

package/src/config-loader.ts

@@ -0,0 +1,5 @@
+import { ZodDto } from '@hg-ts/validation';
+
+export abstract class ConfigLoader {
+	public abstract load<ConfigType extends object>(schema: ZodDto<ConfigType>, name: string): Promise<ConfigType>;
+}

package/src/config.module.ts

@@ -0,0 +1,30 @@
+import {
+	ExecutionMode,
+	ExecutionModeModule,
+} from '@hg-ts/execution-mode';
+import {
+	Global,
+	Module,
+} from '@nestjs/common';
+import { ConfigLoader } from './config-loader.js';
+import { FileConfigLoader } from './file.config-loader.js';
+
+@Global()
+@Module({
+	imports: [ExecutionModeModule],
+	providers: [
+		{
+			provide: ConfigLoader,
+			useFactory(env: ExecutionMode): ConfigLoader {
+				return new FileConfigLoader({
+					envBuilder: true,
+					configDir: 'config',
+					overrideEnv: env,
+				});
+			},
+			inject: [ExecutionMode],
+		},
+	],
+	exports: [ConfigLoader],
+})
+export class ConfigModule {}

package/src/exceptions/index.ts

@@ -0,0 +1 @@
+export * from './no-base-config.exception.js';

package/src/exceptions/no-base-config.exception.ts

@@ -0,0 +1,7 @@
+import { BaseException } from '@hg-ts/exception';
+
+export class NoBaseConfigException extends BaseException {
+	public constructor(configName: string) {
+		super(`Base config with name ${configName} not found`);
+	}
+}

package/src/file.config-loader.ts

@@ -0,0 +1,127 @@
+import {
+	ZodDto,
+	ZodType,
+} from '@hg-ts/validation';
+import assert from 'node:assert/strict';
+import fs from 'node:fs/promises';
+import { ConfigLoader } from './config-loader.js';
+
+import { NoBaseConfigException } from './exceptions/index.js';
+import {
+	PathBuilder,
+	PathBuilderOptions,
+} from './path-builder.js';
+
+export type ConfigLoaderOptions = PathBuilderOptions & {
+	recursive?: boolean;
+	cache?: boolean;
+};
+
+type CacheItem = {
+	schema: ZodType<object>;
+	config: object;
+};
+
+export class FileConfigLoader implements ConfigLoader {
+	private readonly pathBuilder: PathBuilder;
+	private readonly options: ConfigLoaderOptions;
+	private readonly cacheMap = new Map<string, CacheItem>();
+
+	public constructor(options: ConfigLoaderOptions = {}) {
+		this.pathBuilder = new PathBuilder(options);
+		this.options = this.pathBuilder.options;
+	}
+
+	public async load<ConfigType extends object>(dto: ZodDto<ConfigType>, name: string): Promise<ConfigType> {
+		const { schema } = dto;
+		if (this.cacheMap.has(name)) {
+			const cacheItem = this.cacheMap.get(name)!;
+
+			assert.ok(cacheItem.schema === schema, `cached instance of config "${name}" has another schema`);
+
+			return cacheItem.config as ConfigType;
+		}
+
+		const rawConfig = await this.loadRawConfig(name);
+
+		const config = await this.validate(schema, rawConfig);
+
+		if (this.cacheEnabled) {
+			this.cacheMap.set(name, { schema, config });
+		}
+
+		return config;
+	}
+
+	protected async loadRawConfig(name: string): Promise<unknown> {
+		const paths = this.pathBuilder.build(name);
+
+		const configs = await Promise.all(paths.map(async path => this.loadConfigFile(path)));
+
+		if (!configs[0]) {
+			throw new NoBaseConfigException(name);
+		}
+
+		return this.mergeConfigs(configs);
+	}
+
+	/**
+	 *
+	 * @todo Add options to add custom loaders with own ext names (for example yaml)
+	 * @param {string} path
+	 * @protected
+	 */
+	protected async loadConfigFile(path: string): Promise<unknown> {
+		try {
+			const content = await fs.readFile(path, { encoding: 'utf-8' });
+
+			return JSON.parse(content) as unknown;
+		} catch (error: unknown) {
+			return null;
+		}
+	}
+
+	protected mergeConfigs(configs: unknown[]): Record<string, unknown> {
+		return configs
+			.filter(config => config !== null)
+			.filter((config): config is Record<string, unknown> => typeof config === 'object')
+			.reduce((merged, next) => {
+				if (this.isRecursive && merged[this.recursiveRootKey] === true) {
+					return merged;
+				}
+				return {
+					...merged,
+					...next,
+				};
+			});
+	}
+
+	protected async validate<ConfigType>(
+		schema: ZodType<ConfigType>,
+		config: unknown,
+	): Promise<ConfigType> {
+		return schema.parseAsync(config);
+	}
+
+	protected get cacheEnabled(): boolean {
+		if (this.options.cache) {
+			return true;
+		}
+
+		return false;
+	}
+
+	protected get isRecursive(): boolean {
+		if (this.options.recursive) {
+			return true;
+		}
+
+		return false;
+	}
+
+	// TODO: Get field name from options
+	// eslint-disable-next-line @typescript/class-literal-property-style
+	protected get recursiveRootKey(): string {
+		return 'root';
+	}
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './config-loader.js';
+export * from './file.config-loader.js';
+export * from './mock.config-loader.js';
+export * from './config.module.js';

package/src/mock.config-loader.ts

@@ -0,0 +1,16 @@
+import { ZodDto } from '@hg-ts/validation';
+import { ConfigLoader } from './config-loader.js';
+
+export class MockConfigLoader implements ConfigLoader {
+	private readonly configMap: Map<string, unknown>;
+
+	public constructor(configMap: Map<string, unknown>) {
+		this.configMap = configMap;
+	}
+
+	public async load<ConfigType extends object>(dto: ZodDto<ConfigType>, name: string): Promise<ConfigType> {
+		const config = this.configMap.get(name);
+
+		return dto.schema.parse(config);
+	}
+}

package/src/path-builder.ts

@@ -0,0 +1,158 @@
+import type { ExecutionMode } from '@hg-ts/execution-mode';
+import {
+	dirname,
+	resolve,
+} from 'path';
+
+export type PathBuilderOptions = {
+
+	/**
+	 *
+	 * Override default app path
+	 * @default process.cwd()
+	 */
+	appPath?: string;
+
+	/**
+	 *
+	 * Additional directory to appPath
+	 * @default null
+	 */
+	configDir?: Nullable<string>;
+
+	/**
+	 *
+	 * Use environment variable for build config.
+	 * Get base config, apply ${env} config and, after, apply local config
+	 * @default false
+	 */
+	envBuilder?: boolean;
+
+	/**
+	 *
+	 * Override injected env
+	 * Uses only with envBuilder: true
+	 */
+	overrideEnv?: Nullable<ExecutionMode>;
+
+	/**
+	 *
+	 * Used for loading root package config. Useful with overridePostfix option
+	 * @default null
+	 * @todo Implement
+	 */
+	basePostfix?: Nullable<string>;
+
+	/**
+	 *
+	 * Useful with basePostfix.
+	 * For example:
+	 * You can specify configName to 'hg', basePostfix to 'config' and overridePostfix to 'override'.
+	 * In this case will be loaded 'bg.config.{ext}' and overrode by 'hg.override.{ext}'.
+	 * Similar scheme used by many tools like 'docker-compose'.
+	 * @default null
+	 * @todo Implement
+	 */
+	overridePostfix?: Nullable<string>;
+
+	/**
+	 * Apply all configs from `appDir` to `/` until `root` field won't be specified
+	 * @default false
+	 * @todo Implement
+	 */
+	recursive?: boolean;
+};
+
+export class PathBuilder {
+	public readonly options: Required<PathBuilderOptions>;
+	private paths: string[];
+
+	public constructor(options: PathBuilderOptions = {}) {
+		this.options = {
+			appPath: process.cwd(),
+			configDir: null,
+			envBuilder: false,
+			overrideEnv: null,
+			overridePostfix: null,
+			basePostfix: null,
+			recursive: false,
+			...options,
+		};
+		this.paths = [];
+	}
+
+	public build(name: string): string[] {
+		return this.prepareBasePaths()
+			.addEnvFolders()
+			.addConfigName(name)
+			.paths;
+	}
+
+	protected prepareBasePaths(): this {
+		const { appPath, configDir, recursive } = this.options;
+		if (recursive) {
+			let nextPath = appPath;
+			const basePaths: string[] = [appPath];
+
+			while (nextPath !== '/') {
+				nextPath = dirname(nextPath);
+				basePaths.push(nextPath);
+			}
+
+			this.paths = basePaths;
+
+			if (configDir) {
+				this.mergePaths([configDir]);
+			}
+		} else {
+			this.paths = [this.buildPathToConfig([appPath, configDir])];
+		}
+
+		return this;
+	}
+
+	protected addEnvFolders(): this {
+		const { envBuilder, overrideEnv } = this.options;
+		const envFolders: string[] = [];
+
+		if (!envBuilder) {
+			return this;
+		}
+
+		envFolders.push('base');
+
+		if (overrideEnv) {
+			envFolders.push(overrideEnv.getValue());
+		}
+
+		envFolders.push('local');
+
+		return this.mergePaths(envFolders);
+	}
+
+	protected addConfigName(configName: string): this {
+		const { overridePostfix, basePostfix } = this.options;
+		const baseName = basePostfix ? `${configName}.${basePostfix}.json` : `${configName}.json`;
+		const overrideName = overridePostfix ? `${configName}.${overridePostfix}.json` : null;
+
+		const names = [baseName];
+
+		if (overrideName) {
+			names.push(overrideName);
+		}
+
+		return this.mergePaths(names);
+	}
+
+	private mergePaths(additionalParts: string[]): this {
+		this.paths = this.paths.flatMap(path => additionalParts.map(part => this.buildPathToConfig([path, part])));
+
+		return this;
+	}
+
+	private buildPathToConfig(parts: Nullable<string>[]): string {
+		const filteredParts = parts.filter((part): part is string => part !== null);
+
+		return resolve(...filteredParts);
+	}
+}

package/src/tests/config-loader.test.ts

@@ -0,0 +1,202 @@
+import {
+	Describe,
+	expect,
+	ExpectException,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+import zod, { z } from '@hg-ts/validation';
+import fs from 'node:fs/promises';
+import { vi } from 'vitest';
+import { NoBaseConfigException } from '../exceptions/index.js';
+
+import { FileConfigLoader } from '../file.config-loader.js';
+
+@Describe()
+export class ConfigLoaderTest extends Suite {
+	@Test()
+	public async simple(): Promise<void> {
+		const loader = new FileConfigLoader();
+
+		const merged = loader['mergeConfigs']([
+			{
+				a: 'a',
+				b: 'b',
+			},
+			{
+				a: 'aa',
+				c: 'c',
+			},
+		]);
+
+		expect(merged['a']).toBe('aa');
+		expect(merged['b']).toBe('b');
+		expect(merged['c']).toBe('c');
+	}
+
+	@Test()
+	public async recursive(): Promise<void> {
+		const loader = new FileConfigLoader({ recursive: true });
+
+		const merged = loader['mergeConfigs']([
+			{
+				a: 'a',
+				b: 'b',
+			},
+			{
+				a: 'aa',
+				c: 'c',
+				root: true,
+			},
+			{
+				a: 'aaa',
+				b: 'bbb',
+				c: 'ccc',
+			},
+		]);
+
+		expect(merged['a']).toBe('aa');
+		expect(merged['b']).toBe('b');
+		expect(merged['c']).toBe('c');
+	}
+
+	@Test()
+	public async enforceEnv(): Promise<void> {
+		const loader = new FileConfigLoader();
+		const configSchema = zod.object({
+			number: zod.union([
+				zod.number(),
+				zod.string(),
+			])
+				.enforceEnv('SOME_NUMERIC_ENV')
+				.transform(value => Number(value))
+				.pipe(zod.number()),
+			bool: zod.union([
+				zod.string(),
+				zod.boolean(),
+			])
+				.enforceEnv('SOME_BOOLEAN_ENV')
+				.transformBooleanString(),
+		});
+
+		process.env['SOME_NUMERIC_ENV'] = '10';
+		process.env['SOME_BOOLEAN_ENV'] = 'false';
+
+		const config = { number: 1, bool: true };
+
+		const transformed = await loader['validate'](configSchema, config);
+
+		expect(transformed.number).toBe(10);
+		expect(transformed.bool).toBe(false);
+	}
+
+	@Test()
+	public async fullLoadSuccessWithCache(): Promise<void> {
+		const schema = z.object({
+			a: z.string(),
+			b: z.string(),
+			c: z.string(),
+			d: z.string(),
+		});
+		const loader = new FileConfigLoader({ recursive: true, cache: true });
+
+		const loadFileSpy = vi.spyOn(fs, 'readFile');
+		const reults = [
+			{
+				a: 'a',
+				b: 'b',
+				c: 'c',
+			},
+			{
+				a: 'a',
+				b: 'd',
+				d: 'b',
+			},
+			'sdfsdfsdfsdfsdfsdfsdfsdfsdfsdfsdfsdfsdf',
+		];
+		loadFileSpy.mockImplementation(async() => JSON.stringify(reults.shift()!));
+
+		const result = await loader.load(schema.toClass(), 'test');
+
+		expect(result).toMatchObject({
+			a: 'a',
+			b: 'd',
+			c: 'c',
+			d: 'b',
+		});
+
+		const cached = await loader.load(schema.toClass(), 'test');
+
+		expect(cached).toMatchObject(result);
+	}
+
+
+	@Test()
+	public async fullLoadSuccessWithoutCache(): Promise<void> {
+		const schema = z.object({
+			a: z.string(),
+			b: z.string(),
+			c: z.string(),
+			d: z.string(),
+		});
+		const loader = new FileConfigLoader({ recursive: true, cache: false });
+
+		const loadFileSpy = vi.spyOn(fs, 'readFile');
+		const expects: any[] = [
+			{
+				a: 'a',
+				b: 'b',
+				c: 'c',
+			},
+			{
+				a: 'a',
+				b: 'd',
+				d: 'b',
+			},
+			'sdfsdfsdfsdfsdfsdfsdfsdfsdfsdfsdfsdfsdf',
+		];
+		loadFileSpy.mockImplementation(async() => JSON.stringify(expects.shift()));
+
+		const result = await loader.load(schema.toClass(), 'test');
+
+		expects.push({
+			a: 'a',
+			b: 'b',
+			c: 'c',
+		},
+		{
+			a: 'a',
+			d: 'd',
+		});
+
+		expect(result).toMatchObject({
+			a: 'a',
+			b: 'd',
+			c: 'c',
+			d: 'b',
+		});
+
+		const cached = await loader.load(schema.toClass(), 'test');
+
+		expect(cached).not.toMatchObject(result);
+	}
+
+	@Test()
+	@ExpectException(NoBaseConfigException)
+	public async failOnNoBaseConfig(): Promise<void> {
+		const schema = z.object({
+			a: z.string(),
+			b: z.string(),
+			c: z.string(),
+			d: z.string(),
+		});
+		const loader = new FileConfigLoader({ recursive: true, cache: true });
+
+		const loadFileSpy = vi.spyOn(fs, 'readFile');
+		loadFileSpy.mockImplementation(() => {
+			throw new Error('file not found');
+		});
+
+		await loader.load(schema.toClass(), 'test');
+	}
+}

package/src/tests/path-builder.test.ts

@@ -0,0 +1,133 @@
+import {
+	ExecutionModeVariants,
+	MockExecutionMode,
+} from '@hg-ts/execution-mode';
+import {
+	Describe,
+	expect,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+
+import {
+	PathBuilder,
+	PathBuilderOptions,
+} from '../path-builder.js';
+
+@Describe()
+export class PathBuilderTest extends Suite {
+	@Test()
+	public async simple(): Promise<void> {
+		const paths = this.getPaths();
+
+		expect(paths).toHaveLength(1);
+		expect(paths[0]).toBe('/tmp/example.json');
+	}
+
+	@Test()
+	public async recursive(): Promise<void> {
+		const paths = this.getPaths({ recursive: true });
+
+		expect(paths).toHaveLength(2);
+		expect(paths[0]).toBe('/tmp/example.json');
+		expect(paths[1]).toBe('/example.json');
+	}
+
+	@Test()
+	public async full(): Promise<void> {
+		const paths = this.getPaths({
+			recursive: true,
+			overridePostfix: 'override',
+			basePostfix: 'config',
+			envBuilder: true,
+			overrideEnv: new MockExecutionMode(ExecutionModeVariants.DEMO),
+			configDir: 'config',
+		});
+
+		let index = 0;
+
+		expect(paths).toHaveLength(12);
+		expect(paths[index++]).toBe('/tmp/config/base/example.config.json');
+		expect(paths[index++]).toBe('/tmp/config/base/example.override.json');
+		expect(paths[index++]).toBe('/tmp/config/demo/example.config.json');
+		expect(paths[index++]).toBe('/tmp/config/demo/example.override.json');
+		expect(paths[index++]).toBe('/tmp/config/local/example.config.json');
+		expect(paths[index++]).toBe('/tmp/config/local/example.override.json');
+
+		expect(paths[index++]).toBe('/config/base/example.config.json');
+		expect(paths[index++]).toBe('/config/base/example.override.json');
+		expect(paths[index++]).toBe('/config/demo/example.config.json');
+		expect(paths[index++]).toBe('/config/demo/example.override.json');
+		expect(paths[index++]).toBe('/config/local/example.config.json');
+		expect(paths[index++]).toBe('/config/local/example.override.json');
+	}
+
+	@Test()
+	public async configDir(): Promise<void> {
+		const paths = this.getPaths({ configDir: 'config' });
+
+		expect(paths).toHaveLength(1);
+		expect(paths[0]).toBe('/tmp/config/example.json');
+	}
+
+	@Test()
+	public async envBuilder(): Promise<void> {
+		const paths = this.getPaths({ envBuilder: true });
+
+		expect(paths).toHaveLength(2);
+		expect(paths[0]).toBe('/tmp/base/example.json');
+		expect(paths[1]).toBe('/tmp/local/example.json');
+	}
+
+	@Test()
+	public async envBuilderWithOverrideProd(): Promise<void> {
+		const paths = this.getPaths({ envBuilder: true, overrideEnv: new MockExecutionMode(ExecutionModeVariants.PROD) });
+
+		expect(paths).toHaveLength(3);
+		expect(paths[0]).toBe('/tmp/base/example.json');
+		expect(paths[1]).toBe('/tmp/prod/example.json');
+		expect(paths[2]).toBe('/tmp/local/example.json');
+	}
+
+	@Test()
+	public async envBuilderWithOverrideDev(): Promise<void> {
+		const paths = this.getPaths({ envBuilder: true, overrideEnv: new MockExecutionMode(ExecutionModeVariants.DEV) });
+
+		expect(paths).toHaveLength(3);
+		expect(paths[0]).toBe('/tmp/base/example.json');
+		expect(paths[1]).toBe('/tmp/dev/example.json');
+		expect(paths[2]).toBe('/tmp/local/example.json');
+	}
+
+	@Test()
+	public async basePostfix(): Promise<void> {
+		const paths = this.getPaths({ basePostfix: 'config' });
+
+		expect(paths).toHaveLength(1);
+		expect(paths[0]).toBe('/tmp/example.config.json');
+	}
+
+	@Test()
+	public async basePostfixWithOverridePostfix(): Promise<void> {
+		const paths = this.getPaths({ basePostfix: 'config', overridePostfix: 'override' });
+
+		expect(paths).toHaveLength(2);
+		expect(paths[0]).toBe('/tmp/example.config.json');
+		expect(paths[1]).toBe('/tmp/example.override.json');
+	}
+
+	@Test()
+	public async overridePostfix(): Promise<void> {
+		const paths = this.getPaths({ overridePostfix: 'override' });
+
+		expect(paths).toHaveLength(2);
+		expect(paths[0]).toBe('/tmp/example.json');
+		expect(paths[1]).toBe('/tmp/example.override.json');
+	}
+
+	private getPaths(options: Omit<PathBuilderOptions, 'appPath'> = {}): string[] {
+		const builder = new PathBuilder({ appPath: '/tmp', ...options });
+
+		return builder.build('example');
+	}
+}