@nodiator/core

Nodiator

Flexible mediator pattern implementation for TypeScript.

Table of contents

• Idea
• Usage
• Installation
• Quick Start
• Messages documentation
• Providers scope
• Extensions
• License

💡 Idea

When application grows in size it becomes more and more complicated to control dataflow between objects / modules. Modifying one of them may lead to unwanted "shotgun surgery" resulting in breaking other features of the application.

Other problem are extra intermediate actions like logging or caching moved directly to eg. business parts of code effectively preventing us from easily unplugging any of the middle actions from application.

Nodiator aims to address this problem by providing configurable mediator object serving as a communication hub.

Usage

Mediator handles objects called messages. You can think of them as simple dtos as they role is to transport data in given context. They are then passed to providers - handlers, pipelines and other pieces of code interested in given message.

Installation

npm i @nodiator/core
# or
yarn add @nodiator/core

Quick Start

Events

// Declaration
class SomeEvent {}

@EventHandler(SomeEvent)
export class SomeEventHandler implements IEventHandler<SomeEvent> {
  async handle(event: SomeEvent) {
    console.log('SomeEvent handled');
  }
}

const mediator = MediatorFactory.create({ providers: [SomeEventHandler] });

// Execution
mediator.publish(new SomeEvent()).subscribe((result) => {
  console.log(result); // output: SomeEvent handled
});

Requests

// Declaration
type ExampleRequestResponse = string;

class ExampleRequest {
  readonly [ResponseType]?: ExampleRequestResponse;
  constructor(readonly msg: string) {}
}

@RequestHandler(ExampleRequest)
export class ExampleRequestHandler implements IRequestHandler<ExampleRequest> {
  async handle(request: ExampleRequest) {
    return request.msg;
  }
}

const mediator = MediatorFactory.create({ providers: [ExampleRequestHandler] });

// Execution
mediator.request(new ExampleRequest('ok')).subscribe((result) => {
  console.log(result); // output: ok
});

console.log(await firstValueFrom(mediator.request(new ExampleRequest('async ok')))); // output: async ok

📖 Messages documentation

• Events
• Requests

Providers scope

Each provider is lazy-created upon it's first call by default.

One that's done the its instance is saved internally for application lifetime. This behaviour can be changed into instatiting provider for each seperate call by setting scoped flag in given provider's decorator.

@RequestHandler({ request: ExampleRequest, scoped: true })
export class ExampleRequestHandler implements IRequestHandler<ExampleRequest> {
  ...
}

Custom providers instantiator can be defined as mediator configuration as well.

const mediator = MediatorFactory.create({
  providers: [ExampleRequestHandler, SomeEventHandler],
  providersInstantiator: (ProviderType) => new ProviderType(),
});

Extensions

Mediator exposes bus property which is an observable emitting messages processings. It allows to easily extended default behavior. To add an extension to mediator's instance go with

const mediator = MediatorFactory.create();
mediator.use(new MediatorExtension());

For operating example look at logger extension.

License

This project is licensed under the MIT License - see the LICENSE file for details.