https://github.com/brainhubeu/sqrs

🚌SQRS is a JavaScript library for implementing CQRS pattern.
https://github.com/brainhubeu/sqrs

command cqrs cqs dependency-injection inversify javascript jest lerna query typedoc typescript

Last synced: 3 days ago
JSON representation

🚌SQRS is a JavaScript library for implementing CQRS pattern.

• Host: GitHub
• URL: https://github.com/brainhubeu/sqrs
• Owner: brainhubeu
• License: mit
• Created: 2019-02-03T18:19:25.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2024-11-02T00:34:49.000Z (19 days ago)
• Last Synced: 2024-11-06T10:02:51.625Z (14 days ago)
• Topics: command, cqrs, cqs, dependency-injection, inversify, javascript, jest, lerna, query, typedoc, typescript
• Language: TypeScript
• Homepage: https://brainhub.eu/
• Size: 1.24 MB
• Stars: 32
• Watchers: 4
• Forks: 3
• Open Issues: 57
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        





  sqrs





  A JavaScript library for implementing CQRS pattern.





  

    Hire us

  





  [![Travis](https://api.travis-ci.org/brainhubeu/sqrs.svg?branch=master)](https://travis-ci.org/github/brainhubeu/sqrs)

  [![Last commit](https://img.shields.io/github/last-commit/brainhubeu/sqrs.svg)](https://github.com/brainhubeu/sqrs/commits/master)

  [![license](https://img.shields.io/npm/l/@brainhubeu/sqrs.svg)](https://github.com/brainhubeu/sqrs/blob/master/LICENSE)

  [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)

  [![Renovate enabled](https://img.shields.io/badge/renovate-enabled-brightgreen.svg)](https://renovatebot.com/)

  [![Downloads](https://img.shields.io/npm/dm/@brainhubeu/sqrs?color=blue)](https://www.npmjs.com/package/@brainhubeu/sqrs)

  [![Activity](https://img.shields.io/github/commit-activity/m/brainhubeu/sqrs.svg)](https://github.com/brainhubeu/sqrs/commits/master)

  [![Minified](https://img.shields.io/bundlephobia/min/@brainhubeu/sqrs?label=minified)](https://www.npmjs.com/package/@brainhubeu/sqrs)

  [![npm](https://img.shields.io/npm/v/@brainhubeu/sqrs.svg)](https://www.npmjs.com/package/@brainhubeu/sqrs)

  [![Contributors](https://img.shields.io/github/contributors/brainhubeu/sqrs?color=blue)](https://github.com/brainhubeu/sqrs/graphs/contributors)



Best used with TypeScript as it exposes interfaces for Commands, CommandHandlers, Queries, QueryHandlers and more.

When paired with a dependency injection framework it provides a fully-fledged inversion of control experience in JavaScript.

# Installation

To install sqrs run

`npm install @brainhubeu/sqrs` or `yarn add @brainhubeu/sqrs`

the packages comes with it's own TypeScript types.

ES2015 execution environment is required. For NodeJS that means at least Node 8 LTS.

# Getting started

## Introduction to CQRS

In short, CQRS is a pattern that differentiates between read operations and write operations. Write operations are achieved via commands that represent intent to change the system's state, and read operations are achieved via queries that read the system's state. The distinction between the to comes from the principle that asking a question shouldn't change the response.

You can read more about CQRS here:

- https://www.martinfowler.com/bliki/CQRS.html

- http://www.cqrs.nu

## Using the library

[See the longer guide for getting started](/docs/usage.md)

### Short version

Writing commands (note you don't have to use classes, you can also use object factories):

```ts

import { Command } from '@brainhubeu/sqrs';

export class AddNoteCommand implements Command {

  public type = 'add-note';

  public text: string;

  constructor (text: string) {

    this.text = text;

  }

}

```

Writing command handlers:

```ts

import { CommandHandler } from '@brainhubeu/sqrs';

class AddNoteCommandHandler implements CommandHandler {

  public handle (command: AddNoteCommand) {

    // do something with the command

  }

}

```

Writing queries:

```ts

import { Query } from '@brainhubeu/sqrs';

export class GetNotesQuery implements Query {

  public queryName = 'GetNotes';

}

```

Writing query handlers:

```ts

import { QueryHandler } from '@brainhubeu/sqrs';

export class GetNotesQueryHandler implements QueryHandler {

  execute (query: GetNotesQuery): Promise {

    // get notes from somewhere

  }

}

```

Final usage:

```ts

import { DefaultCommandBus, CommandBus, DefaultQueryExecutor, QueryExecutor } from '@brainhubeu/sqrs';

const commandBus: CommandBus = new DefaultCommandBus(

  // created somewhere else

  commandHandlerProvider,

  commandValidatorProvider

);

const queryExecutor: QueryExecutor = new DefaultQueryExecutor(

  // created somewhere else

  queryHandlerProvider

);

const addNoteCommand = new AddNoteCommand('hello');

await commandBus.dispatch(addNoteCommand);

const getNotesQuery = new GetNotesQuery();

const notes = await queryExecutor.execute(getNotesQuery);

```

# API reference

API reference generated from JSDoc comment can be found [here](/docs/api)

# Example project

Example project created using this library can be found [here](/packages/example-project)