Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/x-cubed/event-store-client

JS client library for connecting to Event Store over TCP/IP
https://github.com/x-cubed/event-store-client

event-store nodejs

Last synced: about 1 month ago
JSON representation

JS client library for connecting to Event Store over TCP/IP

Awesome Lists containing this project

README 

        
Event Store Client

==================

Author: Carey Bishop



Connects to an [Event Store](http://geteventstore.com) 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](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](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](#storedevent-class) object)

* onConfirmed - A function to be called when the server has confirmed that the subscription is running (function, takes in an [ISubscriptionConfirmation]((#isubscriptionconfirmation-interface)))

* onDropped - A function to be called when the subscription is cancelled (function, takes in an [ISubscriptionDropped](#isubscriptiondropped-interface))

* credentials - The user name and password needed for permission to subscribe to the stream ([ICredentials](#icredentials-interface), optional)

* onNotHandled - A function to be called when the request for subscription is not handled (function, takes in an [ISubscriptionNotHandled](#isubscriptionnothandled-interface))



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](#icredentials-interface), 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](#icredentials-interface), 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](#event)[])

* credentials - The username and password need to perform the operation on this stream ([ICredentials](#icredentials-interface), 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.