@orria-labs/cqrs

Лёгкая библиотека для реализации паттерна CQRS и message-driven медиаторов в TypeScript/JavaScript. Предоставляет базовые абстракции для сообщений и обработчиков, а также надстройку CQRS (команды, события, запросы) с единой системой CqrsSystem.

Описание проекта

• Message-driven основа:
  • IMessage, IMessageHandler, MessageMediator — регистрация обработчиков по классу сообщения и отправка сообщений через медиатор.
  • Единый механизм отправки и обработки с корректной обработкой ошибок (CqrsHandlerNotFoundError, CqrsExecuteError).
• CQRS надстройка:
  • Абстракции ICommand, IEvent, IQuery и соответствующие обработчики ICommandHandler, IEventHandler, IQueryHandler.
  • CqrsSystem агрегирует медиаторы и предоставляет операции send (команда), publish (событие), ask (запрос) с удобной привязкой обработчиков к системе.
• Совместимость:
  • Готовые сборки для CJS (./dist/index.cjs) и ESM (./dist/index.mjs), типы (./dist/index.d.ts).
  • Экспорты централизованы в src/index.ts.

Требования для установки

• TypeScript: ^5 (peer dependency).
• Среда выполнения JS с поддержкой CJS/ESM:
  • Node.js (рекомендуется современная версия).
  • Для локального запуска примера используется Bun (опционально для пользователей библиотеки).

Установка

С использованием npm:

npm i @orria-labs/cqrs

С использованием pnpm:

pnpm add @orria-labs/cqrs

С использованием Bun:

bun add @orria-labs/cqrs

Инструкции по запуску (локально)

Запуск демонстрационного примера (требуется установленный Bun):

bun run dev

Сборка пакета:

bun run build

Доступные скрипты:

• dev — запускает example/index.ts с --watch в Bun.
• build — собирает пакет через unbuild в каталог dist.
• format, lint, check — форматирование и линтинг через Biome.
• release — генерация релиза через changelogen.
• push:tags — пушит git-теги.

Примеры использования

Message-driven: базовая отправка сообщения через медиатор

import { IMessage, IMessageHandler, MessageMediator } from "@orria-labs/cqrs";

class HiMessage extends IMessage<string> {}

class HiMessageHandler extends IMessageHandler<HiMessage, void> {
  async execute({ payload }: HiMessage) {
    console.log(`Hi, ${payload}`);
  }
}

const mediator = new MessageMediator()
  .register(HiMessage, new HiMessageHandler());

await mediator.send(new HiMessage("World"));

CQRS: запросы и команды через CqrsSystem

import {
  CqrsSystem,
  IQuery,
  IQueryHandler,
  ICommand,
  ICommandHandler,
} from "@orria-labs/cqrs";

// Запрос
class GetUserQuery extends IQuery<{ userId: string }> {}
interface GetUserQueryResult {
  id: string;
  name: string;
}
class GetUserQueryHandler extends IQueryHandler<GetUserQuery, GetUserQueryResult> {
  async execute({ payload }: GetUserQuery) {
    return { id: payload.userId, name: "Test" };
  }
}

// Команда
class SendMessageToUserCommand extends ICommand<{ userId: string }> {}
class SendMessageToUserCommandHandler extends ICommandHandler<SendMessageToUserCommand, void> {
  async execute({ payload }: SendMessageToUserCommand) {
    const user = await this.cqrs.ask<GetUserQueryResult>(new GetUserQuery({ userId: payload.userId }));
    console.log(`Send message to user: ${user.name} - ${user.id}`);
  }
}

// Система CQRS
const cqrs = new CqrsSystem({
  queries: [[GetUserQuery, new GetUserQueryHandler()]],
  commands: [[SendMessageToUserCommand, new SendMessageToUserCommandHandler()]],
});

// Отправка команды
await cqrs.send(new SendMessageToUserCommand({ userId: "123" }));

Экспортируемые сущности

Импортируйте из корневого пакета:

import {
  CommandMediator,
  ICommand,
  ICommandHandler,
  CqrsSystem,
  EventMediator,
  IEvent,
  IEventHandler,
  IQuery,
  IQueryHandler,
  QueryMediator,
  CqrsError,
  CqrsExecuteError,
  CqrsHandlerNotFoundError,
  IMessage,
  IMessageHandler,
  MessageMediator,
} from "@orria-labs/cqrs";

Лицензия

• Лицензия: ORRIA PUBLIC LICENSE (OPL-1.0). Полный текст доступен в файле LICENSE.
• Авторские права: © 2025 Orria.ru
• Репозиторий: https://github.com/orria-labs/cqrs

ПО предоставляется «как есть», без каких-либо гарантий. При распространении рекомендуется сохранять ссылку на лицензию и репозиторий. Рекомендуется (но не обязательно) указывать атрибуцию использования open-source разработки Orria Labs.