Event Store Client

Author: Carey Bishop

Connects to an Event Store server over TCP/IP, to send and receive event information.

The Javascript API is intended to mimic the .Net API as closely as possible.

For an example of how to use it, see example.js.

Installation

At the command-line:

npm install event-store-client

In your Node.js application:

var EventStore = require('event-store-client');

A Typescript type definition is available in event-store-client.d.ts. Add this line to the top of your Typescript application:

/// <reference path='node_modules/event-store-client/event-store-client.d.ts'/>

API

Connection object

The core class in this library, represents a single TCP connection to an Event Store server.

new EventStore.Connection(options)

Creates a new Connection object and establishes a binary TCP connection to the Event Store server.

Options is an object containing the following properties:

• host - The domain name or IP address of the Event Store server (string, default: localhost)
• port - The port number to use (number, default: 1113)
• debug - A flag to toggle the output of packets to the console as they're sent and received (boolean, default: false)
• onConnect - A function to be called with no parameters when the connection is established (function, default: no-op)
• onError - A function to be called with a single parameter containing the error that was encountered (function, default: write error to console)
• onClose - A function to be called with a single boolean parameter indicating if a transmission error was encountered (function, default: no-op)

new EventStore.TlsConnection(options)

Creates a new TLS Secured Connection object and establishes a binary TCP connection over SSL to the Event Store server. *** SERVER MUST USE VALID CERTIFICATE ***

Options is an object containing the following properties:

• host - The domain name or IP address of the Event Store server (string, default: localhost)
• port - The port number to use (number, default: 1113)
• debug - A flag to toggle the output of packets to the console as they're sent and received (boolean, default: false)
• onConnect - A function to be called with no parameters when the connection is established (function, default: no-op)
• onError - A function to be called with a single parameter containing the error that was encountered (function, default: write error to console)
• onClose - A function to be called with a single boolean parameter indicating if a transmission error was encountered (function, default: no-op)

Connection.close()

Closes the TCP connection. To re-establish the connection, construct a new Connection object.

Connection.createGuid()

Helper function to generate GUIDs as Buffer objects, for use as the eventId value for new events.

Connection.sendPing()

Sends a ping request to the server.

• callback - The callback function will be invoked when the server responds with a pong.

Connection.subscribeToStream()

Subscribes to a stream to receive notifications as soon as an event is written to the stream.

• streamId - The name of the stream in the Event Store (string)
• resolveLinkTos - True, to resolve links to events in other streams (boolean)
• onEventAppeared - A function to be called each time an event is written to the stream (function, takes in a StoredEvent object)
• onConfirmed - A function to be called when the server has confirmed that the subscription is running (function, takes in an ISubscriptionConfirmation)
• onDropped - A function to be called when the subscription is cancelled (function, takes in an ISubscriptionDropped)
• credentials - The user name and password needed for permission to subscribe to the stream (ICredentials, optional)
• onNotHandled - A function to be called when the request for subscription is not handled (function, takes in an ISubscriptionNotHandled)

Returns a Buffer containing a GUID that identifies the subscription, for use with unsubscribeStream().

Connection.subscribeToStreamFrom()

Executes a catch-up subscription on the given stream, reading events from a given event number, and continuing with a live subscription when all historical events have been read.

• streamId - The name of the stream in the Event Store (string)
• fromEventNumber - Which event number to start after (if null, then from the beginning of the stream.)
• credentials - The user name and password needed for permission to subscribe to the stream.
• onEventAppeared - Callback for each event received (historical or live)
• onLiveProcessingStarted - Callback when historical events have been read and live events are about to be read.
• onDropped - Callback when subscription drops or is dropped.
• settings - Settings for the catch-up subscription.

Returns an instance representing the catch-up subscription (EventStoreStreamCatchUpSubscription).

Connection.readAllEventsBackward() / Connection.readAllEventsForward()

Reads events from across all streams, in order (backward = newest first, forward = oldest first).

• commitPosition - The commit position to start from
• preparePosition - The prepare position to start from
• maxCount - The maximum number of events to return (counting down from fromEventNumber)
• resolveLinkTos - True, if links to events from other streams should be resolved (ie: for events re-published by a projection)
• requireMaster - True, if this request must be processed by the master server in the cluster
• onEventAppeared - The callback to be fired for each event that was written to the stream (can be null)
• credentials - The username and password needed to perform the operation on this stream
• callback - The callback to be fired once all the events have been retrieved

Connection.readStreamEventsBackward() / Connection.readStreamEventsForward()

Reads events from a specific stream, in order (backward = newest first, forward = oldest first).

• streamId - The name of the stream (string)
• fromEventNumber - The number of the event to start at
• maxCount - The maximum number of events to return (counting down from fromEventNumber)
• resolveLinkTos - True, if links to events from other streams should be resolved (ie: for events re-published by a projection)
• requireMaster - True, if this request must be processed by the master server in the cluster
• onEventAppeared - The callback to be fired for each event that was written to the stream (can be null)
• credentials - The username and password needed to perform the operation on this stream (ICredentials, optional)
• callback - The callback to be fired once all the events have been retrieved

Connection.unsubscribeFromStream()

Cancels an existing subscription to a stream.

• correlationId - The GUID identifying the subscription, returned by subscribeToStream (Buffer)
• credentials - The username and password needed to perform the operation on this stream (ICredentials, optional)
• callback - The callback to be fired once the subscription has been cancelled (function, no parameters)

Connection.writeEvents()

Writes one or more events to a stream, creating the stream if it doesn't exist.

• streamId - The name of the stream (string)
• expectedVersion - The expected version of the stream (ie: number of the most recent event) or ExpectedVersion.Any
• requireMaster - True, if this request must be processed by the master server in the cluster
• events - An array of events to be written to the stream (Event[])
• credentials - The username and password need to perform the operation on this stream (ICredentials, optional)
• callback - Invoked once the operation has been completed. Check the result to confirm it was successful.

Event class

Represents an event either before or after it has been stored.

• eventId - A GUID uniquely identifying this event (string)
• eventType - The type of event (string)
• data - An object to be JSON-serialized as the data for the event (object, optional)
• metadata - An object to be JSON-serialized as the metadata for the event (object, optional)

StoredEvent class

Represents an event as it exists on the Event Store server. Inherits from Event and adds the following properties:

• streamId - The name of the Event Store stream that this event was stored in (string)
• eventNumber - The sequence number for this event within the stream (number)
• created - The date that this event was stored in the Event Store (date)
• link - If event was read from a stream using the resolveLinkTos flag, will contain the original link data (from before the event was resolved.) (StoredEvent)

ICredentials interface

An object containing credentials for access to secured resources.

• username - The name of the Event Store user (string)
• password - The clear-text password of the Event Store user (string)

ISubscriptionConfirmation interface

Passed to the onConfirmed callback used by subscribeToStream() when a subscription is successfully created.

• lastCommitPosition - The last commit position within the stream (number)
• lastEventNumber - The last event number within the stream (number)

ISubscriptionDropped interface

Passed to the onDropped callback used by subscribeToStream() when a subscription terminates, or cannot be established.

• reason - The reason why the subscription was dropped (enumeration, 0 = Unsubscribed, 1 = Access Denied)

ISubscriptionNotHandled interface

Passed to the onNotHandled callback used by subscribeToStream() when a request to subscribe fails.

• reason - The reason why the subscription failed (enumeration, 0 = NotReady, 1 = TooBusy, 2 = NotMaster)

CatchUpSubscriptionSettings class

A property bag of settings passed when creating a new catch-up subscription.

• maxLiveQueueSize - The maximum amount to buffer when processing from the live subscription.
• readBatchSize - The number of events to read per batch when reading historical events.
• debug - True if in debug mode.
• resolveLinkTos - Whether or not to resolve link events.

EventStoreStreamCatchUpSubscription class

Represents a catch-up subscription to a single stream.

EventStoreStreamCatchUpSubscription.start()

Initiate start of the catch-up subscription.

EventStoreStreamCatchUpSubscription.stop()

Request to stop the catch-up subscription.

EventStoreStreamCatchUpSubscription.getCorrelationId()

Get the subscription ID of the underlying Event Store subscription, in order to pass it back to the Connection object, for example.