@hg-ts/cqrs 0.5.16 → 0.5.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hg-ts/cqrs",
-  "version": "0.5.16",
+  "version": "0.5.18",
   "main": "dist/index.js",
   "type": "module",
   "exports": {
@@ -18,11 +18,11 @@
     "test:dev": "vitest watch"
   },
   "devDependencies": {
-    "@hg-ts-config/typescript": "0.5.16",
-    "@hg-ts/exception": "0.5.16",
-    "@hg-ts/linter": "0.5.16",
-    "@hg-ts/tests": "0.5.16",
-    "@hg-ts/types": "0.5.16",
+    "@hg-ts-config/typescript": "0.5.18",
+    "@hg-ts/exception": "0.5.18",
+    "@hg-ts/linter": "0.5.18",
+    "@hg-ts/tests": "0.5.18",
+    "@hg-ts/types": "0.5.18",
     "@nestjs/common": "11.1.0",
     "@nestjs/core": "11.1.0",
     "@nestjs/testing": "11.1.0",
@@ -38,7 +38,7 @@
     "vitest": "4.0.14"
   },
   "peerDependencies": {
-    "@hg-ts/exception": "0.5.16",
+    "@hg-ts/exception": "0.5.18",
     "@nestjs/common": "*",
     "@nestjs/core": "*",
     "reflect-metadata": "*",

package/src/abstracts/base.command-handler.ts

@@ -0,0 +1,6 @@
+import { CommandResult } from '../types.js';
+import { BaseCommand } from './base.command.js';
+
+export abstract class BaseCommandHandler<Command extends BaseCommand<any>> {
+	public abstract execute(command: Command): Promise<CommandResult<Command>>;
+}

package/src/abstracts/base.command.ts

@@ -0,0 +1,5 @@
+const COMMAND_SYMBOL = Symbol('Hyper Graph Command');
+
+export abstract class BaseCommand<Result = void> {
+	protected readonly [COMMAND_SYMBOL]: Nullable<Result> = null;
+}

package/src/abstracts/base.executor.test-suite.ts

@@ -0,0 +1,63 @@
+import { UnknownException } from '@hg-ts/exception';
+import {
+	expect,
+	ExpectException,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+
+import {
+	HandlerAlreadyAddedException,
+	HandlerNotFoundException,
+} from '../exceptions/index.js';
+import {
+	BaseCommandOrQuery,
+	CommonHandler,
+} from '../types.js';
+import { BaseExecutor } from './base.executor.js';
+
+export const INPUT_FOR_EXCEPTION = 'Some special string that will throw an exception';
+
+export abstract class BaseExecutorTestSuite<CommandOrQuery extends BaseCommandOrQuery> extends Suite {
+	private executor: BaseExecutor<CommandOrQuery>;
+
+	@Test()
+	public async successExecute(): Promise<void> {
+		const expectedResult = String(Math.random());
+
+		this.executor['addHandler'](this.getCommandOrQueryCtor(), this.getHandler());
+
+		const result = await this.executor.execute(this.getCommandOrQuery(expectedResult));
+
+		expect(result).toBe(expectedResult);
+	}
+
+	@ExpectException(HandlerAlreadyAddedException)
+	@Test()
+	public async multipleHandlers(): Promise<void> {
+		this.executor['addHandler'](this.getCommandOrQueryCtor(), this.getHandler());
+		this.executor['addHandler'](this.getCommandOrQueryCtor(), this.getHandler());
+	}
+
+	@ExpectException(HandlerNotFoundException)
+	@Test()
+	public async handlerNotFound(): Promise<void> {
+		await this.executor.execute(this.getCommandOrQuery(''));
+	}
+
+	@ExpectException(UnknownException)
+	@Test()
+	public async successPassException(): Promise<void> {
+		this.executor['addHandler'](this.getCommandOrQueryCtor(), this.getHandler());
+		await this.executor.execute(this.getCommandOrQuery(INPUT_FOR_EXCEPTION));
+	}
+
+	public override async beforeEach(): Promise<void> {
+		this.executor = this.getExecutor();
+	}
+
+	protected abstract getExecutor(): BaseExecutor<CommandOrQuery>;
+	protected abstract getHandler(): CommonHandler<CommandOrQuery>;
+	protected abstract getCommandOrQueryCtor(): Class<CommandOrQuery, [string]>;
+	protected abstract getCommandOrQuery(input: string): CommandOrQuery;
+}

package/src/abstracts/base.executor.ts

@@ -0,0 +1,46 @@
+import assert from 'node:assert/strict';
+import {
+	HandlerAlreadyAddedException,
+	HandlerNotFoundException,
+} from '../exceptions/index.js';
+import {
+	CommonHandler,
+	CommonResult,
+} from '../types.js';
+
+import { BaseCommand } from './base.command.js';
+import { BaseQuery } from './base.query.js';
+
+export abstract class BaseExecutor<
+	BaseCommandOrQuery extends BaseQuery<any> | BaseCommand<any>
+> {
+	protected readonly handlers = new Map<Class<BaseCommandOrQuery>, CommonHandler<BaseCommandOrQuery>>();
+
+	public async execute<CommandOrQuery extends BaseCommandOrQuery>(
+		commandOrQuery: CommandOrQuery,
+	): Promise<CommonResult<CommandOrQuery>> {
+		return this.executeHandler(commandOrQuery);
+	}
+
+	protected addHandler<CommandOrQuery extends BaseCommandOrQuery>(
+		command: Class<CommandOrQuery, any[]>,
+		handler: CommonHandler<BaseCommandOrQuery>,
+	): void {
+		const existHandler = this.handlers.get(command);
+
+		assert.ok(!existHandler, new HandlerAlreadyAddedException(command));
+
+		this.handlers.set(command, handler);
+	}
+
+	protected assertHandler(
+		handler: Nullable<CommonHandler<BaseCommandOrQuery>>,
+		commandOrQuery: Class<BaseCommandOrQuery, any[]>,
+	): asserts handler {
+		assert.ok(handler, new HandlerNotFoundException(commandOrQuery));
+	}
+
+	protected abstract executeHandler<CommandOrQuery extends BaseCommandOrQuery>(
+		commandOrQuery: CommandOrQuery,
+	): Promise<CommonResult<CommandOrQuery>>;
+}

package/src/abstracts/base.query-handler.ts

@@ -0,0 +1,6 @@
+import { QueryResult } from '../types.js';
+import { BaseQuery } from './base.query.js';
+
+export abstract class BaseQueryHandler<Query extends BaseQuery<any>> {
+	public abstract execute(query: Query): Promise<QueryResult<Query>>;
+}

package/src/abstracts/base.query.ts

@@ -0,0 +1,5 @@
+const QUERY_SYMBOL = Symbol('Hyper Graph Query');
+
+export abstract class BaseQuery<Result> {
+	protected readonly [QUERY_SYMBOL]: Nullable<Result> = null;
+}

package/src/abstracts/index.ts

@@ -0,0 +1,7 @@
+export * from './base.command.js';
+export * from './base.query.js';
+export * from './base.executor.js';
+export * from './base.query-handler.js';
+export * from './base.command-handler.js';
+export * from './base.executor.js';
+export * from './base.executor.test-suite.js';

package/src/cqrs.module.ts

@@ -0,0 +1,130 @@
+import { WillNeverHappenedException } from '@hg-ts/exception';
+
+import {
+	Global,
+	Inject,
+	Module,
+	OnModuleInit,
+} from '@nestjs/common';
+import {
+	DiscoveryModule,
+	DiscoveryService,
+} from '@nestjs/core';
+
+import assert from 'node:assert/strict';
+import {
+	BaseCommand,
+	BaseCommandHandler,
+	BaseQuery,
+	BaseQueryHandler,
+} from './abstracts/index.js';
+
+import {
+	COMMAND_HANDLER_METADATA,
+	QUERY_HANDLER_METADATA,
+} from './decorators/index.js';
+import {
+	CommandExecutor,
+	QueryExecutor,
+} from './executors/index.js';
+
+@Global()
+@Module({
+	imports: [DiscoveryModule],
+	providers: [
+		CommandExecutor,
+		QueryExecutor,
+	],
+	exports: [
+		CommandExecutor,
+		QueryExecutor,
+	],
+})
+export class CqrsModule implements OnModuleInit {
+	@Inject()
+	private readonly discoveryService: DiscoveryService;
+
+	@Inject()
+	private readonly commandExecutor: CommandExecutor;
+
+	@Inject()
+	private readonly queryExecutor: QueryExecutor;
+
+	public async onModuleInit(): Promise<void> {
+		const providers = this.discoveryService.getProviders()
+			.filter(wrapper => wrapper.instance)
+			.map(wrapper => wrapper.instance);
+
+		providers.forEach(provider => {
+			const handlerCtor = Object.getPrototypeOf(provider)!.constructor;
+
+			const isCommandHandler = this.isCommandHandler(provider);
+			const isQueryHandler = this.isQueryHandler(provider);
+
+			const commandMetadata = this.getCommandMetadata(handlerCtor);
+			const queryMetadata = this.getQueryMetadata(handlerCtor);
+
+			if (isCommandHandler && commandMetadata) {
+				this.commandExecutor['addHandler'](commandMetadata, provider);
+				return;
+			}
+
+			/* v8 ignore next 3 */
+			if (isCommandHandler) {
+				throw new WillNeverHappenedException('Command handler instance provided without CommandHandler decorator');
+			}
+
+			/* v8 ignore next 3 */
+			if (commandMetadata) {
+				throw new WillNeverHappenedException('CommandHandler decorate class that does not extended BaseCommandHandler');
+			}
+
+			if (isQueryHandler && queryMetadata) {
+				this.queryExecutor['addHandler'](queryMetadata, provider);
+				return;
+			}
+
+			/* v8 ignore next 3 */
+			if (isQueryHandler) {
+				throw new WillNeverHappenedException('Query handler instance provided without QueryHandler decorator');
+			}
+
+			/* v8 ignore next 3 */
+			if (queryMetadata) {
+				throw new WillNeverHappenedException('QueryHandler decorate class that does not extended BaseQueryHandler');
+			}
+		});
+	}
+
+	private getCommandMetadata(handlerCtor: Class<any, any[]>): Nullable<Class<BaseCommand, any[]>> {
+		const metadata = Reflect.getMetadata(COMMAND_HANDLER_METADATA, handlerCtor);
+
+		if (!metadata) {
+			return null;
+		}
+
+		assert.ok(metadata.prototype instanceof BaseCommand);
+
+		return metadata;
+	}
+
+	private getQueryMetadata(handlerCtor: Class<any, any[]>): Nullable<Class<BaseQuery<any>, any[]>> {
+		const metadata = Reflect.getMetadata(QUERY_HANDLER_METADATA, handlerCtor);
+
+		if (!metadata) {
+			return null;
+		}
+
+		assert.ok(metadata.prototype instanceof BaseQuery);
+
+		return metadata;
+	}
+
+	private isCommandHandler(provider: any): provider is BaseCommandHandler<BaseCommand<any>> {
+		return provider instanceof BaseCommandHandler;
+	}
+
+	private isQueryHandler(provider: any): provider is BaseQueryHandler<BaseQuery<any>> {
+		return provider instanceof BaseQueryHandler;
+	}
+}

package/src/decorators/command-handler.decorator.ts

@@ -0,0 +1,14 @@
+import {
+	BaseCommand,
+	BaseCommandHandler,
+} from '../abstracts/index.js';
+
+export const COMMAND_HANDLER_METADATA = Symbol('COMMAND_HANDLER_METADATA');
+
+export function CommandHandler<Command extends BaseCommand<any>, Handler extends BaseCommandHandler<Command>>(
+	commandCtor: Class<Command, any[]>,
+): TypedClassDecorator<Class<Handler>> {
+	return (ctor: Class<Handler>) => {
+		Reflect.defineMetadata(COMMAND_HANDLER_METADATA, commandCtor, ctor);
+	};
+}

package/src/decorators/index.ts

@@ -0,0 +1,4 @@
+import 'reflect-metadata';
+
+export * from './query-handler.decorator.js';
+export * from './command-handler.decorator.js';

package/src/decorators/query-handler.decorator.ts

@@ -0,0 +1,14 @@
+import {
+	BaseQuery,
+	BaseQueryHandler,
+} from '../abstracts/index.js';
+
+export const QUERY_HANDLER_METADATA = Symbol('QUERY_HANDLER_METADATA');
+
+export function QueryHandler<Query extends BaseQuery<any>, Handler extends BaseQueryHandler<Query>>(
+	queryCtor: Class<Query, any[]>,
+): TypedClassDecorator<Class<Handler>> {
+	return (ctor: Class<Handler>) => {
+		Reflect.defineMetadata(QUERY_HANDLER_METADATA, queryCtor, ctor);
+	};
+}

package/src/exceptions/handler-already-added.exception.ts

@@ -0,0 +1,8 @@
+import { BaseException } from '@hg-ts/exception';
+import { BaseCommandOrQuery } from '../types.js';
+
+export class HandlerAlreadyAddedException extends BaseException {
+	public constructor(command: Class<BaseCommandOrQuery>) {
+		super(`Handler for command "${command.name}" already added`);
+	}
+}

package/src/exceptions/handler-not-found.exception.ts

@@ -0,0 +1,8 @@
+import { BaseException } from '@hg-ts/exception';
+import { BaseCommandOrQuery } from '../types.js';
+
+export class HandlerNotFoundException extends BaseException {
+	public constructor(command: Class<BaseCommandOrQuery>) {
+		super(`Handler for command "${command.name}" not found`);
+	}
+}

package/src/exceptions/index.ts

@@ -0,0 +1,2 @@
+export * from './handler-already-added.exception.js';
+export * from './handler-not-found.exception.js';

package/src/executors/command.executor.ts

@@ -0,0 +1,18 @@
+import {
+	BaseCommand,
+	BaseExecutor,
+} from '../abstracts/index.js';
+import { CommonResult } from '../types.js';
+
+export class CommandExecutor extends BaseExecutor<BaseCommand<any>> {
+	protected override async executeHandler<Command extends BaseCommand<any>>(
+		command: Command,
+	): Promise<CommonResult<Command>> {
+		const commandCtor = Object.getPrototypeOf(command)!.constructor as Class<Command>;
+		const handler = this.handlers.get(commandCtor) ?? null;
+
+		this.assertHandler(handler, commandCtor);
+
+		return handler.execute(command);
+	}
+}

package/src/executors/index.ts

@@ -0,0 +1,2 @@
+export * from './command.executor.js';
+export * from './query.executor.js';

package/src/executors/query.executor.ts

@@ -0,0 +1,18 @@
+import {
+	BaseExecutor,
+	BaseQuery,
+} from '../abstracts/index.js';
+import { CommonResult } from '../types.js';
+
+export class QueryExecutor extends BaseExecutor<BaseQuery<any>> {
+	protected override async executeHandler<Query extends BaseQuery<any>>(
+		query: Query,
+	): Promise<CommonResult<Query>> {
+		const queryCtor = Object.getPrototypeOf(query)!.constructor as Class<Query>;
+		const handler = this.handlers.get(queryCtor) ?? null;
+
+		this.assertHandler(handler, queryCtor);
+
+		return handler.execute(query);
+	}
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export {
+	BaseQuery,
+	BaseQueryHandler,
+	BaseCommand,
+	BaseCommandHandler,
+} from './abstracts/index.js';
+export * from './exceptions/index.js';
+export * from './executors/index.js';
+export { CommandHandler, QueryHandler } from './decorators/index.js';
+export { CqrsModule } from './cqrs.module.js';

package/src/tests/command-executor.test.ts

@@ -0,0 +1,31 @@
+import { Describe } from '@hg-ts/tests';
+
+import {
+	BaseCommand,
+	BaseCommandHandler,
+	BaseExecutor,
+	BaseExecutorTestSuite,
+} from '../abstracts/index.js';
+import { CommandExecutor } from '../executors/index.js';
+import { TestCommand } from './commands/index.js';
+
+import { TestCommandHandler } from './test-command.handler.js';
+
+@Describe()
+export class CommandExecutorTest extends BaseExecutorTestSuite<BaseCommand<any>> {
+	protected override getCommandOrQuery(input: string): TestCommand {
+		return new TestCommand(input);
+	}
+
+	protected override getExecutor(): BaseExecutor<BaseCommand<any>> {
+		return new CommandExecutor();
+	}
+
+	protected override getHandler(): BaseCommandHandler<BaseCommand<any>> {
+		return new TestCommandHandler();
+	}
+
+	protected override getCommandOrQueryCtor(): Class<BaseCommand<any>, [string]> {
+		return TestCommand;
+	}
+}

package/src/tests/commands/index.ts

@@ -0,0 +1,2 @@
+export * from './unknown.command.js';
+export * from './test.command.js';

package/src/tests/commands/test.command.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../abstracts/index.js';
+
+export class TestCommand extends BaseCommand<string> {
+	public readonly expectedResult: string;
+
+	public constructor(expectedResult: string) {
+		super();
+
+		this.expectedResult = expectedResult;
+	}
+}

package/src/tests/commands/unknown.command.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../abstracts/index.js';
+
+export class UnknownCommand extends BaseCommand<string> {
+	public readonly expectedResult: string;
+
+	public constructor(expectedResult: string) {
+		super();
+
+		this.expectedResult = expectedResult;
+	}
+}

package/src/tests/cqrs-test.module.ts

@@ -0,0 +1,7 @@
+import { Module } from '@nestjs/common';
+import { CqrsModule } from '../cqrs.module.js';
+import { TestCommandHandler } from './test-command.handler.js';
+import { TestQueryHandler } from './test-query.handler.js';
+
+@Module({ imports: [CqrsModule], providers: [TestCommandHandler, TestQueryHandler] })
+export class CqrsTestModule {}

package/src/tests/cqrs.module.test.ts

@@ -0,0 +1,76 @@
+import {
+	Describe,
+	expect,
+	ExpectException,
+	Suite,
+	Test,
+} from '@hg-ts/tests';
+import {
+	Test as TestFactory,
+	TestingModule,
+} from '@nestjs/testing';
+
+import { HandlerNotFoundException } from '../exceptions/index.js';
+import {
+	CommandExecutor,
+	QueryExecutor,
+} from '../executors/index.js';
+import {
+	TestCommand,
+	UnknownCommand,
+} from './commands/index.js';
+import { CqrsTestModule } from './cqrs-test.module.js';
+import {
+	TestQuery,
+	UnknownQuery,
+} from './queries/index.js';
+
+@Describe()
+export class QueryExecutorTest extends Suite {
+	private container: TestingModule;
+	private commandExecutor: CommandExecutor;
+	private queryExecutor: QueryExecutor;
+
+	@Test()
+	public async executorProvides(): Promise<void> {
+		expect(this.commandExecutor).toBeInstanceOf(CommandExecutor);
+		expect(this.queryExecutor).toBeInstanceOf(QueryExecutor);
+	}
+
+	@Test()
+	public async commandSuccess(): Promise<void> {
+		const value = String(Math.random());
+		const result = await this.commandExecutor.execute(new TestCommand(value));
+
+		expect(result).toBe(value);
+	}
+
+	@Test()
+	@ExpectException(HandlerNotFoundException)
+	public async unknownCommand(): Promise<void> {
+		await this.commandExecutor.execute(new UnknownCommand(''));
+	}
+
+	@Test()
+	public async querySuccess(): Promise<void> {
+		const value = String(Math.random());
+		const result = await this.queryExecutor.execute(new TestQuery(value));
+
+		expect(result).toBe(value);
+	}
+
+	@Test()
+	@ExpectException(HandlerNotFoundException)
+	public async unknownQuery(): Promise<void> {
+		await this.queryExecutor.execute(new UnknownQuery(''));
+	}
+
+	public override async beforeEach(): Promise<void> {
+		this.container = await TestFactory.createTestingModule({ imports: [CqrsTestModule] }).compile();
+
+		await this.container.init();
+
+		this.queryExecutor = this.container.get(QueryExecutor);
+		this.commandExecutor = this.container.get(CommandExecutor);
+	}
+}

package/src/tests/queries/index.ts

@@ -0,0 +1,2 @@
+export * from './unknown.query.js';
+export * from './test.query.js';

package/src/tests/queries/test.query.ts

@@ -0,0 +1,11 @@
+import { BaseQuery } from '../../abstracts/index.js';
+
+export class TestQuery extends BaseQuery<string> {
+	public readonly expectedResult: string;
+
+	public constructor(expectedResult: string) {
+		super();
+
+		this.expectedResult = expectedResult;
+	}
+}

package/src/tests/queries/unknown.query.ts

@@ -0,0 +1,11 @@
+import { BaseQuery } from '../../abstracts/index.js';
+
+export class UnknownQuery extends BaseQuery<string> {
+	public readonly expectedResult: string;
+
+	public constructor(expectedResult: string) {
+		super();
+
+		this.expectedResult = expectedResult;
+	}
+}

package/src/tests/query-executor.test.ts

@@ -0,0 +1,30 @@
+import { Describe } from '@hg-ts/tests';
+
+import {
+	BaseExecutor,
+	BaseExecutorTestSuite,
+	BaseQuery,
+	BaseQueryHandler,
+} from '../abstracts/index.js';
+import { QueryExecutor } from '../executors/index.js';
+import { TestQuery } from './queries/index.js';
+import { TestQueryHandler } from './test-query.handler.js';
+
+@Describe()
+export class QueryExecutorTest extends BaseExecutorTestSuite<BaseQuery<any>> {
+	protected override getCommandOrQuery(input: string): TestQuery {
+		return new TestQuery(input);
+	}
+
+	protected override getExecutor(): BaseExecutor<BaseQuery<any>> {
+		return new QueryExecutor();
+	}
+
+	protected override getHandler(): BaseQueryHandler<BaseQuery<any>> {
+		return new TestQueryHandler();
+	}
+
+	protected override getCommandOrQueryCtor(): Class<BaseQuery<any>, [string]> {
+		return TestQuery;
+	}
+}

package/src/tests/test-command.handler.ts

@@ -0,0 +1,17 @@
+import { UnknownException } from '@hg-ts/exception';
+import {
+	BaseCommandHandler,
+	INPUT_FOR_EXCEPTION,
+} from '../abstracts/index.js';
+import { CommandHandler } from '../decorators/index.js';
+import { TestCommand } from './commands/index.js';
+
+@CommandHandler(TestCommand)
+export class TestCommandHandler extends BaseCommandHandler<TestCommand> {
+	public async execute(command: TestCommand): Promise<string> {
+		if (command.expectedResult === INPUT_FOR_EXCEPTION) {
+			throw new UnknownException(command.expectedResult);
+		}
+		return command.expectedResult;
+	}
+}

package/src/tests/test-query.handler.ts

@@ -0,0 +1,18 @@
+import { UnknownException } from '@hg-ts/exception';
+
+import {
+	BaseQueryHandler,
+	INPUT_FOR_EXCEPTION,
+} from '../abstracts/index.js';
+import { QueryHandler } from '../decorators/index.js';
+import { TestQuery } from './queries/index.js';
+
+@QueryHandler(TestQuery)
+export class TestQueryHandler extends BaseQueryHandler<TestQuery> {
+	public async execute(command: TestQuery): Promise<string> {
+		if (command.expectedResult === INPUT_FOR_EXCEPTION) {
+			throw new UnknownException(command.expectedResult);
+		}
+		return command.expectedResult;
+	}
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+import {
+	BaseCommand,
+	BaseCommandHandler,
+	BaseQuery,
+	BaseQueryHandler,
+} from './abstracts/index.js';
+
+export type CommandResult<Command extends BaseCommand<any>> = Command extends BaseCommand<infer Result>
+	? Result
+	: never;
+export type QueryResult<Command extends BaseQuery<any>> = Command extends BaseQuery<infer Result>
+	? Result
+	: never;
+
+export type BaseCommandOrQuery = BaseQuery<any> | BaseCommand<any>;
+
+export type CommonHandler<CommandOrQuery extends BaseCommandOrQuery> =
+	CommandOrQuery extends BaseQuery<any>
+		? BaseQueryHandler<CommandOrQuery>
+		: CommandOrQuery extends BaseCommand<any>
+			? BaseCommandHandler<CommandOrQuery>
+			: never;
+
+export type CommonResult<CommandOrQuery extends BaseCommandOrQuery> =
+	CommandOrQuery extends BaseQuery<any>
+		? QueryResult<CommandOrQuery>
+		: CommandOrQuery extends BaseCommand<any>
+			? CommandResult<CommandOrQuery>
+			: never;