• Stars
    star
    162
  • Rank 232,284 (Top 5 %)
  • Language
    JavaScript
  • License
    Apache License 2.0
  • Created about 5 years ago
  • Updated 3 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

A NodeJS client for Event Store

npm Github action CI workflow license

EventStoreDB NodeJS Client

EventStoreDB is the open-source, functional database with Complex Event Processing in Javascript.

This is the repository for the NodeJS client for EventStoreDB 20+ and uses gRPC as the communication protocol.

Installation

# Yarn
$ yarn add @eventstore/db-client

# NPM
$ npm install --save @eventstore/db-client

EventStoreDB Server Compatibility

This client is compatible with version 20.6.1 upwards.

Server setup instructions can be found in the Event Store Docs, follow the docker setup for the simplest configuration.

Documentation

Full documentation can be found in Event Store GRPC Client Docs.

Example

The following snippet showcases a simple example where we form a connection, then append and read events from the server.

Javascript example:
const {
  EventStoreDBClient,
  jsonEvent,
  FORWARDS,
  START,
} = require("@eventstore/db-client");

const client = new EventStoreDBClient({
  endpoint: "localhost:2113",
});

async function simpleTest() {
  const streamName = "es_supported_clients";

  const event = jsonEvent({
    type: "grpc-client",
    data: {
      languages: ["typescript", "javascript"],
      runtime: "NodeJS",
    },
  });

  const appendResult = await client.appendToStream(streamName, [event]);

  const events = client.readStream(streamName, {
    fromRevision: START,
    direction: FORWARDS,
    maxCount: 10,
  });

  for await (const event of events) {
    doSomethingProductive(event);
  }
}
Typescript example:
import {
  EventStoreDBClient,
  jsonEvent,
  FORWARDS,
  START,
  JSONEventType,
} from "@eventstore/db-client";

const client = new EventStoreDBClient({
  endpoint: "localhost:2113",
});

interface Reservation {
  reservationId: string;
  movieId: string;
  userId: string;
  seatId: string;
}

type SeatReservedEvent = JSONEventType<
  "seat-reserved",
  {
    reservationId: string;
    movieId: string;
    userId: string;
    seatId: string;
  }
>;

type SeatChangedEvent = JSONEventType<
  "seat-changed",
  {
    reservationId: string;
    newSeatId: string;
  }
>;

type ReservationEvents = SeatReservedEvent | SeatChangedEvent;

async function simpleTest(): Promise<void> {
  const streamName = "booking-abc123";

  const event = jsonEvent<SeatReservedEvent>({
    type: "seat-reserved",
    data: {
      reservationId: "abc123",
      movieId: "tt0368226",
      userId: "nm0802995",
      seatId: "4b",
    },
  });

  const appendResult = await client.appendToStream(streamName, event);

  const events = client.readStream<ReservationEvents>(streamName, {
    fromRevision: START,
    direction: FORWARDS,
    maxCount: 10,
  });

  const reservation: Partial<Reservation> = {};

  for await (const { event } of events) {
    switch (event.type) {
      case "seat-reserved": {
        reservation.reservationId = event.data.reservationId;
        reservation.movieId = event.data.movieId;
        reservation.seatId = event.data.seatId;
        reservation.userId = event.data.userId;
        break;
      }
      case "seat-changed": {
        reservation.seatId = event.data.newSeatId;
        break;
      }
      default: {
        const _exhaustiveCheck: never = event;
        break;
      }
    }
  }
}

Build from source

This project uses Yarn as a build tool. The following shell command lines should get you started:

$ yarn
$ yarn build

Run tests

Tests are written using Jest and require Docker and Docker Compose to be installed. Then run test with:

$ yarn test

Tests can be filtered by prepending the test file or folder to the command

$ yarn test connection // all connection tests
$ yarn test ReadAll // only the ReadAll tests

To get debug information when running tests use the test:debug command.

$ yarn test:debug // debug all tests
$ yarn test:debug ReadAll // only the ReadAll tests

Specific docker images can be specified via the enviroment variable EVENTSTORE_IMAGE.

$ yarn cross-env EVENTSTORE_IMAGE=77d63f3f0ab3 jest

See Jest documentation for more options.

Debugging

This project uses the debug module internally to log information about connections, options and GRPC requests. To see all the internal logs, set the DEBUG environment variable to esdb:* when launching your app. Logs can be further filtered with glob patterns, for example, only connection logs: esdb:connection, everything but grpc logs: esdb:*,-*:grpc.

You can set a few environment variables that will further change the behavior of the debug logging:

Name Purpose
DEBUG Enables/disables specific debugging namespaces.
DEBUG_COLORS Whether or not to use colors in the debug output.
DEBUG_DEPTH Object inspection depth.
DEBUG_FD File descriptor to write debug output to.
DEBUG_SHOW_HIDDEN Shows hidden properties on inspected objects.

Note: The environment variables beginning with DEBUG_ end up being converted into an Options object that gets used with %o/%O formatters. See the Node.js documentation for util.inspect() for the complete list.

Support

Information on support can be found on our website: Event Store Support

Community

We have a community discussion space at Event Store Discuss.

Contributing

Development is done on the master branch. We attempt to do our best to ensure that the history remains clean and to do so, we generally ask contributors to squash their commits into a set or single logical commit.

More Repositories

1

EventStore

EventStoreDB, the event-native database. Designed for Event Sourcing, Event-Driven, and Microservices architectures
C#
5,021
star
2

EventStore.JVM

Event Store JVM Client
Scala
222
star
3

EventStore-Client-Dotnet

Dotnet Client SDK for the Event Store gRPC Client API written in C#
C#
131
star
4

eventstore-docker

Event Store Docker Container
Dockerfile
84
star
5

EventStore-Client-Go

Go Client for Event Store version 20 and above.
Go
81
star
6

EventStore.Akka.Persistence

Event Store Journal for Akka Persistence
Scala
74
star
7

EventStoreDB-Client-Java

Official Asynchronous Java 8+ Client Library for EventStoreDB 20.6+
Java
60
star
8

samples

Samples showing practical aspect of EventStoreDB, Event Sourcing
Java
59
star
9

EventStore.UI

The user interface for Event Store
JavaScript
56
star
10

ClientAPI.NetCore

.NET Core Client
C#
45
star
11

Sklaida

Sample application using Event Store
C#
42
star
12

EventStore.Charts

EventStore official Helm Charts
Shell
29
star
13

csharp-ldap

GitHub mirror of Novell's C# LDAP library (Novell.Directory.Ldap)
C#
23
star
14

replicator

Real-time replication tool
C#
19
star
15

training-advanced-go

Go
19
star
16

buffer-manager

A straightforward way to not make the GC angry in .NET and Mono
C#
17
star
17

training-advanced-dotnet

C#
17
star
18

Webinars

C#
16
star
19

esdb-tui

EventStoreDB Adminstration Tool.
Rust
10
star
20

training-advanced-java

Java
9
star
21

terraform-provider-eventstorecloud

Terraform Provider for Event Store Cloud
Go
8
star
22

esc

Event Store Cloud CLI
Rust
7
star
23

documentation

Next-gen documentation website
JavaScript
7
star
24

eventstore.org

CSS
6
star
25

Automations

Gathers GitHub actions used across the organization.
JavaScript
5
star
26

es-gencert-cli

Event Store Certificate Generation CLI
Go
4
star
27

training-introduction-nodejs

Introduction training material ( TypeScript)
TypeScript
4
star
28

training-introduction-java

Java
4
star
29

training-2021-09

C#
3
star
30

EventStore-Client-gRPC-TestData

Server container with pre-populated data set for testing Event Store gRPC Client SDKs
Dockerfile
3
star
31

training-introduction-dotnet

C#
3
star
32

eventstore-packer-templates

Shell
2
star
33

idsrv4

idsrv4
SCSS
2
star
34

nexus

Rust
2
star
35

eventstore-orleans

C#
2
star
36

Downloads

HTML
2
star
37

pulumi-eventstorecloud

Pulumi provider for Event Store Cloud
Python
2
star
38

HostStat.NET

.NET Library for collecting operating system metrics for Event Store https://www.eventstore.com
C#
2
star
39

Design-System

Event Store component library and frontend utilities
TypeScript
2
star
40

EventStoreDB-From-Scratch-.NET

This repo is for developers to read and write events to and from EventStoreDB. It is designed for individuals new to EventStoreDB, who want an easy on ramp to the platform. As a template repository, you can easily run the sample code in GitHub Codespaces and clone to start your own projects with EventStoreDB.
C#
2
star
41

esquery

C#
1
star
42

HashChecker

C#
1
star
43

training-simple-examples

Introductory examples on aggregates and read models
C#
1
star
44

download.geteventstore.com

Downloadable files and binaries
HTML
1
star
45

EventStoreDB-Client-Dotnet-Legacy

C#
1
star
46

EventStoreDB-From-Scratch-Python

This repo is for developers to read and write events to and from EventStoreDB. It is designed for individuals new to EventStoreDB, who want an easy on ramp to the platform. As a template repository, you can easily run the sample code in GitHub Codespaces and clone to start your own projects with EventStoreDB.
Shell
1
star