gearshaft

Gearshaft

An Event Sourcing toolkit for Node.js based on the Eventide project for Ruby.

Status: Pre-Release (due to lack of documentation, see Roadmap)

Getting Started

The best way to get started is to dive into the Gearshaft example project.

Development

• Run a Postgres instance for use by the automated tests
• Provision a message store database for the automated tests
• Configure the test suite to use the appropriate Postgres credentials
• Run the tests

Running Postgres

Use Docker to run Postgres or install Postgres from scratch. The automated tests expect the following defaults which can be overriden:

• HOST: localhost
• PORT: 5432 (Postgres default)
• USER: postgres
• PASS: NInAN5t3kJo8d7I3

You can run Postgres with docker as follows:

docker run --name pg -d -p 5432:5432 -e POSTGRES_PASSWORD=NInAN5t3kJo8d7I3 postgres:12

Terminate Postgres and delete all data as follow:

docker rm -fv pg

Provisioning Message Store Database

• Install the Postgres client (psql)

  Ubuntu: sudo apt install postgresql-client Mac: brew install libpq && brew link --force libpq

• (Re)create the message store database and user credentials

  If you are using the default (compromised) credentials, simply run: npm run recreate; otherwise, customize the following commands as necessary:

  • Create the message_store database:

    PGHOST=localhost \
      PGUSER=postgres \
      PGPASSWORD=NInAN5t3kJo8d7I3 \
      ./gems/bin/evt-pg-recreate-db
    

  • Assign the message_store user a password:

    PGHOST=localhost \
      PGUSER=postgres \
      PGPASSWORD=NInAN5t3kJo8d7I3 \
      psql -c "alter role message_store with password 'NInAN5t3kJo8d7I3';"
    

Configuring Test Suite Postgres Credentials

The Test Suite configuration is managed using the rc module. Create a .gearshaft_testsrc file in the project root directory with the following fields to customize the Postgres connection settings:

{
  "db": {
    "host": "some-host-name",
    "user": "some-pg-user",
    "password": "some-pg-pass",
    "database": "some-pg-database"
  }
}

What's with the name?

The project is named after the concept of a physical gearshaft: a machine engineered to precisely actuate components.

Acknowledgements

Gearshaft builds on the hard-fought design learnings of the Eventide's Ruby implemention. The module boundaries and many test-cases have Eventide equivalents making the Eventide Documentation a great resource for getting started. Gearshaft relies on the Message DB for Postgres schema and functions.