tapeworm 0.4.0 → 0.5.0

package/README.md

@@ -1,4 +1,332 @@
-[![Build Status](https://travis-ci.org/spralle/rec.svg?branch=master)](https://travis-ci.org/spralle/rec)
-# Tapeworm - Tape Write Once Read Many
+Tapeworm
+========
 
-Event sourcing for Node and Browserify
+[Tape Write Once, Read Many](https://github.com/surikaterna/tapeworm) is a library for event sourcing for in Node.
+
+* [Purpose](#purpose)
+* [Installation](#installation)
+* [Usage](#usage)
+  * [In Memory](#in-memory)
+  * [Custom Partition](#custom-partition)
+* [Components](#components)
+  * [EventStore](#eventstore)
+    * [Methods](#methods)
+      * [openPartition](#openpartition)
+    * [EventStorePartition](#eventstorepartition)
+      * [Methods](#methods-1)
+        * [openStream](#openstream)
+        * [append](#append)
+        * [delete](#delete)
+      * [Persistence Partition Wrapper Methods](#persistence-partition-wrapper-methods)
+        * [queryStreamWithSnapshot](#querystreamwithsnapshot)
+        * [storeSnapshot](#storesnapshot)
+        * [loadSnapshot](#loadsnapshot)
+        * [queryStream](#querystream)
+        * [removeSnapshot](#removesnapshot)
+        * [getLatestCommit](#getlatestcommit)
+        * [querySnapshotsByMaxDateTime](#querysnapshotsbymaxdatetime)
+  * [EventStream](#eventstream)
+    * [Methods](#methods-2)
+      * [getVersion](#getversion)
+      * [append](#append-1)
+      * [hasChanges](#haschanges)
+      * [commit](#commit)
+      * [revertChanges](#revertchanges)
+      * [getCommittedEvents](#getcommittedevents)
+      * [getUncommittedEvents](#getuncommittedevents)
+  * [Commit](#commit-1)
+  * [Event](#event)
+
+# Purpose
+
+Tapeworm is an event store, configurable with an external persistence partition. By default it provides its own in
+memory persistence partition, but it can be exchanged by e.g.
+a [MongoDB persistence partition](https://github.com/surikaterna/tapeworm_persistence_store_mongodb) or
+an [IndexedDB persistence partition](https://github.com/surikaterna/tapeworm_persistence_store_indexdb).
+
+# Installation
+
+```shell
+npm install tapeworm
+```
+
+# Usage
+
+## In Memory
+
+```js
+import EventStore from 'tapeworm';
+
+// A singleton Tapeworm EventStore should be instantiated somewhere
+const eventStore = new EventStore();
+
+// Opening the same partition multiple times returns the same Partition instance
+const partition = await eventStore.openPartition('location');
+
+const firstCommit = new Commit('1', 'location', '1', 0, []);
+const secondCommit = new Commit('2', 'location', '1', 1, []);
+const thirdCommit = new Commit('3', 'location', '1', 2, []);
+
+// When all commits have ben persisted, the commits are returned
+const commits = await partition.append([firstCommit, secondCommit]);
+// [firstCommit, secondCommit]
+
+// Single commits are returned as an array of one item
+const addedCommits = await partition.append(thirdCommit);
+// [thirdCommit]
+```
+
+## Custom Partition
+
+This example uses
+the [MongoDB persistence partition](https://github.com/surikaterna/tapeworm_persistence_store_mongodb), but a custom
+persistence partition can be implemented and used as needed.
+
+```js
+const dispatchService = (commit) => {
+  // Commit dispatched from the custom store, handle it as necessary
+}
+
+const eventStore = new EventStore(tapewormMdbStore, dispatchService);
+const partition = await eventStore.openPartition('location');
+
+const commits = [
+  new Commit('1', 'location', '1', 0, []),
+  new Commit('2', 'location', '1', 1, [])
+];
+
+// Will call dispatchService twice, once for each commit when handled by the custom partition
+await partition.append(commits);
+```
+
+# Components
+
+## EventStore
+
+The TapeWORM EventStore is exported as default. It takes an optional custom partition and an optional dispatch service
+and holds a collection of [event store partitions](#eventstorepartition) opened.
+
+```js
+import EventStore from 'tapeworm';
+
+// A singleton TapeWORM EventStore should be instantiated somewhere
+const eventStore = new EventStore();
+```
+
+### Methods
+
+#### openPartition
+
+Resolves an [EventStorePartition](#eventstorepartition) when the persistence store has successfully opened its
+persistence partition.
+
+```js
+const partition = await eventStore.openPartition();
+```
+
+### EventStorePartition
+
+A wrapper around the persistence partition.
+
+### Methods
+
+#### openStream
+
+Resolves an [EventStream](#eventstream) when it has properly loaded all commits.
+
+```js
+const eventStream = await partition.openStream(streamId, writeOnly, callback);
+```
+
+#### append
+
+Takes a commit or a list of commits and appends them on the persistence partition. Will call the dispatch service, if
+provided, once per appended commit.
+
+```js
+const appendedCommits = await partition.append(commits, callback);
+```
+
+#### delete
+
+Commit a stream deleted event to indicate that all related data for the stream shall be removed.
+
+```js
+await partition.delete(streamId, deleteEvent);
+```
+
+### Persistence Partition Wrapper Methods
+
+The EventStorePartition will provide methods for calling the following methods directly on the persistence partition,
+providing the provided arguments.
+
+#### queryStreamWithSnapshot
+
+Has a fallback implementation assuming that the persistence partition used has the [loadSnapshot](#loadsnapshot)
+and [queryStream](#querystream) methods implemented.
+
+#### storeSnapshot
+
+Store a snapshot for a stream and resolve data for the stored snapshot.
+
+```js
+const snapshotData = await partition.storeSnapshot(streamId, snapshot, version, callback);
+// Result: { id, version, snapshot }
+```
+
+#### loadSnapshot
+
+Retrieve the stored snapshot of a stream.
+
+```js
+const snapshotData = await partition.loadSnapshot(streamId, callback);
+// Result: { id, version, snapshot }
+```
+
+#### queryStream
+
+Retrieve the commits for a stream.
+
+```js
+const snapshotData = await partition.queryStream(streamId, fromEventSequence, callback);
+// Result: [{ id, streamId, commitSequence, events }, { id, streamId, commitSequence, events }]
+```
+
+#### removeSnapshot
+
+Remove the stored snapshot of a stream.
+
+```js
+await partition.removeSnapshot(streamId, callback);
+// Result: { id, version, snapshot }
+```
+
+#### getLatestCommit
+
+Retrieve the last stored commit for a stream.
+
+```js
+const commit = await partition.getLatestCommit(streamId, callback);
+// Result: { id, streamId, commitSequence, events }
+```
+
+#### querySnapshotsByMaxDateTime
+
+Retrieve the stored snapshots older than the provided date string.
+
+```js
+const snapshots = await partition.querySnapshotsByMaxDateTime(dateTime, callback);
+// Result: [{ id }, { id }]
+```
+
+## EventStream
+
+### Methods
+
+#### getVersion
+
+Retrieves the current version of the stream.
+
+```js
+const version = eventStream.getVersion();
+```
+
+#### append
+
+Add an [Event](#event) to the streams list of uncommitted (planned) events.
+
+```js
+eventStream.append(event);
+```
+
+#### hasChanges
+
+Returns whether there are uncommitted events on the stream.
+
+```js
+const hasChanges = eventStream.hasChanges();
+```
+
+#### commit
+
+Build a [commit](#commit) from the uncommitted [events](#event) and append it to
+the [event store partition](#eventstorepartition).
+
+```js
+await eventStream.commit(commitId, callback);
+```
+
+#### revertChanges
+
+Remove the uncommitted events from the stream to prevent the changes from being committed.
+
+```js
+eventStream.revertChanges();
+```
+
+#### getCommittedEvents
+
+Returns a copy of the committed events for the stream.
+
+Throws an error if the stream is created as _write only_.
+
+```js
+const events = eventStream.getCommittedEvents();
+```
+
+#### getUncommittedEvents
+
+Returns a copy of the uncommitted events appended to the stream.
+
+```js
+const events = eventStream.getUncommittedEvents();
+```
+
+## Commit
+
+Creates a new Commit instance.
+
+```js
+const commit = new Commit(id, partitionId, streamId, commitSequence, events);
+
+// commit.id: id
+// commit.partitionId: partitionId
+// commit.streamId: streamId
+// commit.commitSequence: commitSequence
+// commit.events: events
+```
+
+## Event
+
+Creates a new Event instance.
+
+```js
+const event = new Event(id, type, data, metadata);
+
+// event.id: id
+// event.type: type
+// event.data: data
+// event.metadata: metadata (defaults to {})
+// event.timestamps: Date (date of creation)
+// event.revision: null (to be updated by the event store when appended)
+```
+
+## Dispatch Service
+
+The Tapeworm event store takes a dispatch service as an optional second argument. If provided, it will be called with
+the commit as payload once it has been processed by the persistence partition.
+
+```js
+function dispatchService(commit, markAsDispatched) {
+  // Distribute information about the processed commit
+  // ...
+
+  markAsDispatched();
+}
+
+const eventStore = new EventStore(null, dispatchService);
+const partition = await eventStore.openPartition('location');
+
+// Will call dispatchService when the commit is processed
+partition.append(new Commit('4', 'location', '1', 3, []));
+```

package/lib/event_stream.js

@@ -82,9 +82,14 @@ EventStream.prototype.hasChanges = function () {
 
 EventStream.prototype.commit = function (commitId, callback) {
   var self = this;
-  
-  if(this._isDeleted) {
-    throw new Error('Stream is deleted, unable to commit: ' + this._uncommittedEvents.map(function(event) {return event.type}) );
+
+  if (this._isDeleted) {
+    throw new Error(
+      'Stream is deleted, unable to commit: ' +
+        this._uncommittedEvents.map(function (event) {
+          return event.type;
+        })
+    );
   }
 
   if (!this.hasChanges()) {
@@ -117,9 +122,7 @@ EventStream.prototype._clearChanges = function () {
 
 EventStream.prototype.revertChanges = function () {
   //trunc the uncomitted events log
-  var arr = this._uncommittedEvents;
   this._uncommittedEvents = [];
-  delete arr;
 };
 
 EventStream.prototype._buildCommit = function (commitId, events) {

package/lib/persistence/inmemory/inmemory_partition.js

@@ -55,11 +55,11 @@ InMemoryPartition.prototype.applyCommitHeader = function (commitId, header, call
 InMemoryPartition.prototype.append = function (commit, callback) {
   commit.isDispatched = false;
   //check for duplicates
-  if (_.contains(this._commitIds, commit.id)) {
+  if (_.includes(this._commitIds, commit.id)) {
     throw new DuplicateCommitError('Duplicate commit of ' + commit.id);
   }
   var concurrencyKey = getConcurrencyKey(commit);
-  if (_.contains(this._commitConcurrencyCheck, concurrencyKey)) {
+  if (_.includes(this._commitConcurrencyCheck, concurrencyKey)) {
     throw new ConcurrencyError('Concurrency error on stream ' + commit.streamId);
   }
   //check concurrency

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tapeworm",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "",
   "main": "index.js",
   "directories": {
@@ -34,13 +34,13 @@
     "eslint-plugin-react": "^3.3.1",
     "istanbul": "^0.3.2",
     "mocha": "^2.0.1",
-    "should": "^4.1.0",
     "prettier": "^2.1.2",
-    "prettier-config-surikaterna": "^1.0.1"
+    "prettier-config-surikaterna": "^1.0.1",
+    "should": "^4.1.0"
   },
   "dependencies": {
     "bluebird": "^2.5.2",
-    "lodash": "^2.4.2",
+    "lodash": "^4.17.21",
     "uuid": "^8.3.2"
   }
 }