Event sourcing library to help developers abstract core concepts
Summary
Instalation
Simply run
NPM:
$ npm install @irontitan/tardisYarn:
$ yarn add @irontitan/tardisUsage
Javascript:
Person.js
const PersonWasCreated = require('./PersonWasCreatedEvent')
const PersonEmailWasAdded = require('./PersonEmailWasAddedEvent')
class Person {
constructor () {
this.name = null
this.email = null
this.updatedAt = null
this.updatedBy = null
}
static create (name, user, email) {
return [
new PersonWasCreated({ name }, user),
new PersonEmailWasAdded({ email }, user)
]
}
get state () {
return { ...this }
}
}
module.exports = PersonPersonWasCreatedEvent.js
const { Event } = require('@irontitan/tardis')
class PersonWasCreated extends Event {
static get eventName () { return 'person-was-created' }
constructor (data, user) {
super(PersonWasCreated.eventName, data)
this.user = user
}
static commit (state, event) {
state.name = event.data.name
state.updatedAt = event.timestamp
state.updatedBy = event.user
return state
}
}
module.exports = PersonWasCreatedPersonEmailWasAddedEvent.js
const { Event } = require('@irontitan/tardis')
class PersonEmailWasAdded extends Event {
static get eventName () { return 'person-email-was-added' }
constructor (data, user) {
super(PersonEmailWasAdded.eventName, data)
this.user = user
}
static commit (state, event) {
state.email = event.data.email
state.updatedAt = event.timestamp
state.updatedBy = event.user
return state
}
}
module.exports = PersonEmailWasAddedindex.js
const { Reducer } = require('@irontitan/tardis')
const Person = require('./Person')
const PersonWasCreated = require('./PersonWasCreatedEvent')
const PersonEmailWasAdded = require('./PersonEmailWasAddedEvent')
const personReducer = new Reducer({
[PersonWasCreated.eventName]: PersonWasCreated.commit,
[PersonEmailWasAdded.eventName]: PersonEmailWasAdded.commit
})
const events = [ ...Person.create('John Doe', 'jdoe', '[email protected]') ]
console.log(events)
/*
[
PersonWasCreated {
id: 'd043fc61a0ab5e088a458b6b',
name: 'person-was-created',
data: { name: 'John Doe' },
timestamp: 2018-10-16T22:10:06.022Z,
user: 'johndoe'
},
PersonEmailWasAdded {
id: 'a2707db386e25529e25ee882',
name: 'person-email-was-added',
data: { email: '[email protected]' },
timestamp: 2018-10-16T22:10:06.022Z,
user: 'johndoe'
}
]
*/
const person = personReducer.reduce(new Person(), events)
console.log(person.state)
/*
{
name: 'John Doe',
email: '[email protected]',
updatedBy: 'johndoe',
updatedAt: 2018-10-16T20:54:57.122Z
}
*/Typescript:
Person.ts
import PersonWasCreated from './PersonWasCreatedEvent'
import PersonEmailWasAdded from './PersonEmailWasAddedEvent'
export default class Person {
name: string | null = null
email: string | null = null
updatedAt: Date | null = null
updatedBy: string | null = null
static create(name: string, user: string, email: string) {
return [
new PersonWasCreated({ name }, user),
new PersonEmailWasAdded({ email }, user)
]
}
public get state() {
return {
name: this.name,
email: this.email,
updatedAt: this.updatedAt,
updatedBy: this.updatedBy
}
}
}PersonWasCreatedEvent.ts
import { Event } from '@irontitan/tardis'
export interface IPersonCreationParams {
name: string
}
export default class PersonWasCreated extends Event<IPersonCreationParams> {
static eventName = 'person-was-created'
user: string
constructor(data: IPersonCreationParams, user: string) {
super(PersonWasCreated.eventName, data)
this.user = user
}
static commit(state: Person, event: PersonWasCreated): Person {
state.name = event.data.name
state.updatedAt = event.timestamp
state.updatedBy = event.user
return state
}
}PersonEmailWasAddedEvent.ts
import { Event } from '@irontitan/tardis'
export default class PersonEmailWasAdded extends Event<any> {
static eventName = 'person-email-was-added'
user: string
constructor(data: { email: string }, user: string) {
super(PersonEmailWasAdded.eventName, data)
this.user = user
}
static commit(state: Person, event: PersonEmailWasAdded): Person {
state.email = event.data.email
state.updatedAt = event.timestamp
state.updatedBy = event.user
return state
}
}index.ts
import { Reducer } from '@irontitan/tardis'
import Person from './Person'
import PersonWasCreated from './PersonWasCreatedEvent'
import PersonEmailWasAdded from './PersonEmailWasAddedEvent'
const personReducer = new Reducer<Person>({
[PersonWasCreated.eventName]: PersonWasCreated.commit,
[PersonEmailWasAdded.eventName]: PersonEmailWasAdded.commit
})
const events = [ ...Person.create('John Doe', 'jdoe', '[email protected]') ]
console.log(events)
/*
[
PersonWasCreated {
id: 'd043fc61a0ab5e088a458b6b',
name: 'person-was-created',
data: { name: 'John Doe' },
timestamp: 2018-10-16T22:10:06.022Z,
user: 'johndoe'
},
PersonEmailWasAdded {
id: 'a2707db386e25529e25ee882',
name: 'person-email-was-added',
data: { email: '[email protected]' },
timestamp: 2018-10-16T22:10:06.022Z,
user: 'johndoe'
}
]
*/
const person = personReducer.reduce(new Person(), events)
console.log(person.state)
/*
{
name: 'John Doe',
email: '[email protected]',
updatedBy: 'johndoe',
updatedAt: 2018-10-16T20:54:57.122Z
}
*/Core concepts
The core idea behind Tardis is to implement a generic and easy-to-use interface to interact with the Event Sourcing architecture.
In this architecture there are two core concepts: The Event and the Reducer, and we'll call anything from our business logic Entity, it can be a car, a person, a ship or anything else.
Event
An event represents something that happened to your entity. For instance "The Person was created at the database", or even "The person has visited Amsterdam" and so on. Every event receives two arguments: The event name string (lowercase and hyphenated, so Person was created becomes person-was-created), and all the data for that event. It also contains a timestamp and an id property which will be automatically generated.
All events must also include a static name property and a static commit method. The commit method is a function with the following signature:
static commit (state, event) {
}The commit method is where the state will be updated and sent back to the reducer.
Let's say we have this entity:
const { PersonWasCreated } = require('../your/path/to/events')
class Person {
constructor () {
this.name = null
this.updatedBy = null
this.updatedAt = null
}
// This method will return every event needed to create the user
static create (name, user) {
return [
new PersonWasCreated({ name }, user)
]
}
get state () {
return { ...this }
}
}So, let's construct an Event:
Typescript:
import { Event } from '@irontitan/tardis'
class PersonWasCreated extends Event { // Our event's class
static eventName = 'person-was-created' // Event name
public user: string // A custom user property belonging to the event itself
// The event constructor takes as many arguments as your event needs
// In our case, we only have two: The data which is related to the entity "Person" and the user who generated the event
constructor (data: { name: string }, user: string) {
super(PersonWasCreated.eventName, data) // Calling the parent class with the name and entity data
this.user = user
}
// Commit method which will update the current received state
// State is an instance of your own entity with all the properties you need
// Our entity has only the property "name"
static commit (state: Person, event: PersonWasCreated) {
// Updating the state
state.name = event.data.name
state.updatedAt = event.timestamp
state.updatedBy = event.user
return state
}
}Javascript
const { Event } = require('@irontitan/tardis')
class PersonWasCreated extends Event {
static get eventName () { return 'person-was-created' }
constructor (data, user) {
super(PersonWasCreated.eventName, data)
this.user = user
}
static commit (state, event) {
state.name = event.data.name
state.updatedAt = event.timestamp
state.updatedBy = event.user
return state
}
}Events with custom ID's
By default, the Event class will generate a MongoDB-Like ObjectID. If you wish to use your own ID function, then it is needed to supply it to the third optional parameter in the super method inside your event:
Typescript
import { Event } from '@irontitan/tardis'
import crypto from 'crypto'
function createId (): string {
return crypto.randomBytes(12).toString('hex')
}
class PersonWasCreated extends Event {
static eventName = 'person-was-created'
public user: string
constructor (data: { name: string }, user: string) {
super(PersonWasCreated.eventName, data, createId())
this.user = user
}
static commit (state: Person, event: PersonWasCreated) {
state.name = event.data.name
state.updatedAt = event.timestamp
state.updatedBy = event.user
return state
}
}Javascript
const crypto = require('crypto')
const { Event } = require('@irontitan/tardis')
function createId () {
return crypto.randomBytes(12).toString('hex')
}
class PersonWasCreated extends Event {
static get eventName () { return 'person-was-created' }
constructor (data, user) {
super(PersonWasCreated.eventName, data, createId())
this.user = user
}
static commit (state, event) {
state.name = event.data.name
state.updatedAt = event.timestamp
state.updatedBy = event.user
return state
}
}Reducer
The reducer is a structure that represents the applied state. It will be the reducer which will receive an initial state and recursively apply all the commit functions present in events, passing the resulting state to the initial state of the next call, essentially, reducing an array of events to a single final event.
All reducers must be instantiated by passing an object of known events and it's respective commit functions, for instance, let's get our Person's events:
Typescript
import { Person } from './your/entity/path'
import { Reducer } from '@irontitan/tardis'
import { PersonWasCreated, PersonWasUpdated } from './your/path/to/events'
const personReducer = new Reducer<Person>({
[PersonWasCreated.eventName]: PersonWasCreated.commit,
[PersonWasUpdated.eventName]: PersonWasUpdated.commit
})Javascript
const { Person } = require('./your/entity/path')
const { Reducer } = require('@irontitan/tardis')
const { PersonWasCreated, PersonWasUpdated } = require('./your/path/to/events')
const personReducer = new Reducer({
[PersonWasCreated.eventName]: PersonWasCreated.commit,
[PersonEmailWasAdded.eventName]: PersonEmailWasAdded.commit
})Now we have an instance of the reducer which will only apply commits to that specific known events. Now we can create an event and pass to it so it will update our entity:
Typescript
import { Person } from './your/entity/path'
import { Reducer } from '@irontitan/tardis'
import { PersonWasCreated, PersonWasUpdated } from './your/path/to/events'
const events = [...Person.create('John Doe', 'jdoe')]
console.log(events)
/*
[
PersonWasCreated {
id: 'd043fc61a0ab5e088a458b6b',
name: 'person-was-created',
data: { name: 'John Doe' },
timestamp: 2018-10-16T22:10:06.022Z,
user: 'jdoe'
}
]
*/
let initialState = new Person()
console.log(initialState.state)
/*
{
name: null
updatedBy: null
updatedAt: null
}
*/
const person = personReducer.reduce(initialState, events)
console.log(person.state)
/*
{
name: 'John Doe',
updatedBy: 'jdoe',
updatedAt: 2018-10-16T20:54:57.122Z
}
*/Javascript
const { Person } = require('./your/entity/path')
const { Reducer } = require('@irontitan/tardis')
const { PersonWasCreated, PersonWasUpdated } = require('./your/path/to/events')
const events = [...Person.create('John Doe', 'jdoe')]
console.log(events)
/*
[
PersonWasCreated {
id: 'd043fc61a0ab5e088a458b6b',
name: 'person-was-created',
data: { name: 'John Doe' },
timestamp: 2018-10-16T22:10:06.022Z,
user: 'jdoe'
}
]
*/
let initialState = new Person()
console.log(initialState.state)
/*
{
name: null
updatedBy: null
updatedAt: null
}
*/
const person = personReducer.reduce(initialState, events)
console.log(person.state)
/*
{
name: 'John Doe',
updatedBy: 'jdoe',
updatedAt: 2018-10-16T20:54:57.122Z
}
*/