npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

events-sourcing

v1.0.0

Published

Event sourcing library. Just a workaround to play with event sourcing and learn more about it.

Downloads

7

Readme

Event sourcing library.

This library allow you to create projection object that result from a list of events. You can also revert events and time travels at any point in time.

To compute your events you need to attach reducer for each event types. Your reducer must be pure and return an object that reflect the update that you want to apply to your projection.

CreateProjection(events, state, reducers) :

  • events: optional array of events. Default value: [].
  • state: optional object. Default value: { sequence: 0, values:{} }
  • reducers: optional array. Default value: []
const evsc = require('events-sourcing');

const state = { sequence: 0, balance: 0 };

const events = [
  {
    // Event1
    sequence: 1 // Beware if you try to add a sequence number which is not the current state sequence + 1 this will throw an error.
    type: 'add:money',
    payload: { amount: 10 },
  },
];

const reducers = [{
  event: 'add:money',
  reducer: (payload, state) => {
    return { balance: state.balance + payload.amount };
  },
}];

const projection = evsc.createProjection(events, state, reducers);
projection.sequence(); // => 1
projection.values(); // => { balance: 10 }
projection.events(); // => [ Event1 ]

This will return a projection object which is the results of all events that compose an entity. A projection will expose these functions :

  • addReducer(eventType, reducer): Will attach a reducer function to an event type.
  • addEvent(eventType, payload): Will add a new event to the projection and refresh his state. Throw an error if no reducer is found.
  • goTo(n): Go to the entity at the time of the event n.
  • revert(n): Revert n events on the projection.
  • apply(n): Apply n next events on the projection.
  • sequence(): Return the current sequence number of the projection.
  • values(): Return the current state values.
  • events(): Return the events list of the projection.
  • reducers(): Return the reducers object map.

Projection.addReducer(eventType, reducer) :

This method will attach a reducer function to an event type.

  • EventType is a string
  • Reducer must be a pure function

You can replace a reducer by a new version but in this case you will need to replay all events to get the state computed with your new reducer implementation

const evsc = require('events-sourcing');

const projection = evsc.createProjection([], { balance: 0 });

projection.addReducer('add:money', (payload, state) => {
  return {
    balance: state.balance + payload.amount,
  };
});

projection.addEvent('add:money', { amount: 10 });
projection.values(); // { balance: 10 }
projection.sequence(); // 1

Projection.addEvent(eventType, payload) :

This method will create an event push it in the projection events array and apply it to the projection.

  • Warning: You must have registered a reducer for that kind of event. Otherwise an error will be throw.
const evsc = require('events-sourcing');

const events = [event1, event2, event3, event4];

const projection = evsc.createProjection(events, state); // state is optional
projection.sequence(); // => 4
projection.values(); // => State of the projection after event4.
projection.events(); // => [ event1, event2, event3, event4 ]

projection.addEvent('user:updated', { firstName: 'John' });
projection.sequence(); // => 5
projection.values(); // => { firstName: 'John', ...rest }
projection.events(); // => [ event1, event2, event3, event4, event5 ]

Projection.goTo(targetSequence) :

This method will revert or apply events until matching the targetSequence

const evsc = require('events-sourcing');

const events = [event1, event2, event3, event4];
const projection = evsc.createProjection(events, state);

projection.goTo(2);
projection.sequence(); // => 2
projection.values(); // => State of the projection after event sequence 2.

Projection.apply(n) :

This method will apply n events from the projection

const evsc = require('events-sourcing');

const events = [event1, event2, event3, event4];
const projection = evsc.createProjection(events, state);

projection.goTo(2);
projection.sequence(); // 2

projection.apply(2); // Will reapply the event 3 and 4
projection.sequence(); // => 4

Projection.revert(n) :

This method will revert n events from the projection

const evsc = require('events-sourcing');

const events = [event1, event2, event3, event4];
const projection = evsc.createProjection(events, state);

projection.revert(2); // Will revert event 3 and 4
projection.sequence(); // => 2
projection.values(); // => State of the projection after event sequence 2.

Events sequences

  • The default state has the sequence 0.
  • All events must have a consecutive sequence number. If not an error will be thrown : with error.code === 'APPLY_EVENT_OUT_OF_SEQUENCE'

Remove a key :

To remove a key from a state make you reducer return this key undefined.

projection.values(); // => { firstName: 'John', lastName: 'Snow' }

projection.addReducer('user:remove:firstname', () => {
  return {
    firstname: undefined,
  };
});
projection.addEvent('user:remove:firstname', {});
projection.values(); // => { lastName: 'Snow' }

Nested objects :

evsc support nested objects. It use deepmerge for that.

projection.values(); // => { user : { firstName: 'John' } }
projection.addEvent('user:updated', { user: { lastName: 'Snow' } });
projection.values(); // => { user: { firstName: 'John', lastName: 'Snow' }  }