183 lines
5.2 KiB
Markdown
183 lines
5.2 KiB
Markdown
# node-eventstore-client
|
||
A port of the EventStore .Net ClientAPI to Node.js
|
||
|
||
## Learning
|
||
|
||
If you want to learn more about EventSourcing/EventModeling, you can join one of the monthly virtual workshops offered by my employer Adaptech Group, see info at [https://adaptechgroup.com/#workshop](https://adaptechgroup.com/#workshop).
|
||
|
||
## Status
|
||
|
||
### Missing features:
|
||
|
||
- Set system settings
|
||
|
||
### Areas to improve
|
||
|
||
- Errors
|
||
- Use codes or types to differentiate between errors
|
||
- Performance
|
||
- Performance hasn't been tested yet
|
||
- Tests
|
||
- Can always do with more tests
|
||
|
||
## Getting started
|
||
|
||
Install using `npm install node-eventstore-client`
|
||
|
||
### Dependencies
|
||
|
||
- Node.js >= 4.0
|
||
- Modules: [long](https://www.npmjs.org/package/long), [protobufjs](https://www.npmjs.org/package/protobufjs), [uuid](https://www.npmjs.org/package/uuid), [strict-event-emitter-types](https://www.npmjs.com/package/strict-event-emitter-types) (installed via `npm install`)
|
||
|
||
### Install and run an Eventstore on localhost
|
||
|
||
See https://eventstore.org/docs/introduction/4.1.0/
|
||
|
||
*Note: If you are using a version of EventStore prior to 3.9.4, you need to use version 0.1.x of this package `npm install node-eventstore-client@^0.1`.*
|
||
|
||
|
||
### API Documentation
|
||
|
||
#### Offline
|
||
|
||
The offline documentation can be found in the module folder `./node_modules/node-eventstore-client/docs`.
|
||
|
||
#### Online
|
||
|
||
The online documentation can be found at [https://dev.nicdex.com/node-eventstore-client/docs/](https://dev.nicdex.com/node-eventstore-client/docs/)
|
||
|
||
### Example: Storing an event
|
||
|
||
Save to ```app.js:```
|
||
|
||
```javascript
|
||
var esClient = require('node-eventstore-client');
|
||
var uuid = require('uuid');
|
||
|
||
var streamName = "testStream";
|
||
/*
|
||
Connecting to a single node using "tcp://localhost:1113"
|
||
- to connect to a cluster via dns discovery use "discover://my.host:2113"
|
||
- to connect to a cluster via gossip seeds use
|
||
[
|
||
new esClient.GossipSeed({host: '192.168.1.10', port: 2113}),
|
||
new esClient.GossipSeed({host: '192.168.1.11', port: 2113}),
|
||
new esClient.GossipSeed({host: '192.168.1.12', port: 2113})
|
||
]
|
||
*/
|
||
var connSettings = {}; // Use defaults
|
||
var esConnection = esClient.createConnection(connSettings, "tcp://localhost:1113");
|
||
esConnection.connect();
|
||
esConnection.once('connected', function (tcpEndPoint) {
|
||
console.log('Connected to eventstore at ' + tcpEndPoint.host + ":" + tcpEndPoint.port);
|
||
});
|
||
|
||
var eventId = uuid.v4();
|
||
var eventData = {
|
||
a : Math.random(),
|
||
b: uuid.v4()
|
||
};
|
||
var event = esClient.createJsonEventData(eventId, eventData, null, 'testEvent');
|
||
console.log("Appending...");
|
||
esConnection.appendToStream(streamName, esClient.expectedVersion.any, event)
|
||
.then(function(result) {
|
||
console.log("Stored event:", eventId);
|
||
console.log("Look for it at: http://localhost:2113/web/index.html#/streams/testStream");
|
||
esConnection.close();
|
||
})
|
||
.catch(function(err) {
|
||
console.log(err);
|
||
});
|
||
```
|
||
|
||
Run:
|
||
|
||
```json
|
||
npm install uuid
|
||
npm install node-eventstore-client
|
||
node app.js
|
||
```
|
||
|
||
### Example: Subscribing to events
|
||
|
||
```cd samples```
|
||
|
||
To subscribe to all events from now on (includes example of a filter which ignores events which we aren't interested in):
|
||
|
||
```node subscribe-all-events.js```
|
||
|
||
To catch up on all events ever and subscribe to all new ones from now on:
|
||
|
||
```node subscribe-catchup-all-events.js```
|
||
|
||
To generate a test event, open a separate console and run:
|
||
|
||
```node store-event.js```
|
||
|
||
## Running the tests
|
||
|
||
### Local testing
|
||
|
||
To run the tests it is recommended that you use an in-memory instance of the eventstore so you don't pollute your dev instance.
|
||
|
||
EventStore.ClusterNode.exe --run-projections=all --memdb –certificate-file=yourcert.pfx
|
||
or
|
||
./run-node.sh --run-projections=all --memdb –certificate-file=yourcert.p12
|
||
|
||
You can also use docker-compose :
|
||
|
||
```bash
|
||
# start the single node cluster
|
||
npm run compose:single:start
|
||
# if you want to wait for the cluster to be available
|
||
npm run compose:wait
|
||
# run the tests
|
||
npm run test
|
||
# to cleanup (stop containres, delete volumes)
|
||
npm run compose:single:stop
|
||
```
|
||
|
||
For SSL setup see:
|
||
|
||
https://eventstore.org/docs/server/setting_up_ssl/
|
||
or
|
||
https://eventstore.org/docs/server/setting_up_ssl_linux/
|
||
|
||
To execute the tests suites simply run
|
||
|
||
npm test
|
||
|
||
### Isolated environment
|
||
|
||
To be able to run the tests for different connection types (tcp, gossip, cluster) docker-compose files are available to setup the environment and run the tests.
|
||
|
||
#### Prerequisites
|
||
|
||
* docker
|
||
* docker-compose
|
||
|
||
#### Run
|
||
|
||
To execute the tests suites for single node cluster (tcp connection) simply run
|
||
|
||
npm run test:single
|
||
|
||
To execute the tests suites for multiple nodes cluster (gossip connection) simply run
|
||
|
||
npm run test:gossip
|
||
|
||
To execute the tests suites for multiple nodes cluster (dns discovery connection) simply run
|
||
|
||
npm run test:cluster
|
||
|
||
## Porting .Net Task to Node.js
|
||
|
||
Any async commands returns a [Promise](https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Promise) object in replacement of .Net Task.
|
||
|
||
|
||
## License
|
||
|
||
Ported code is released under the MIT license, see [LICENSE](https://github.com/nicdex/node-eventstore-client/blob/master/LICENSE).
|
||
|
||
Original code is released under the EventStore license and can be found at https://github.com/eventstore/eventstore.
|