Getting Started with the Hazelcast Node.js Client

What You’ll Learn

This tutorial will get you started with the Hazelcast Node.js client.

Before you Begin

A text editor or IDE
Docker
Node.js 10.4+

Start a Hazelcast Member

We will use the 4.2 version of Hazelcast for this tutorial.

In this tutorial, we will use Docker for simplicity. You can find the different installation methods here.

docker run -p 5701:5701 hazelcast/hazelcast:4.2

This will start a new Hazelcast member at port 5701. Now, we have a Hazelcast cluster with just one member.

Install Hazelcast Node.js Client

Create a new folder and navigate to it:

mkdir nodejs-client-getting-started
cd nodejs-client-getting-started

Initialize a new npm package:

npm init

Install Hazelcast Node.js client’s latest version:

npm install --save hazelcast-client

Start Node.js Client

Create a JavaScript file named “index.js” and put the following code inside it:

const { Client } = require('hazelcast-client');
(async () => {
    const client = await Client.newHazelcastClient();
})().catch(err => {
    console.log(`An error occured: ${err}`);
});

To run this Node.js script, use the following command:

node index.js

The majority of the client methods return promises, so we used the async/await syntax here, but you can use the regular then / catch syntax, too.

The following line creates and starts a new Hazelcast client with the default configuration.

const client = await Client.newHazelcastClient();

The client automatically connects to the Hazelcast member available on the local machine.

Use Map

A Hazelcast map is a distributed key-value store, similar to JavaScript Map class or plain objects. You can store key-value pairs in a map. In the following example, we will work with map entries where the keys are session ids and the values are emails.

const { Client } = require('hazelcast-client');

(async () => {
    const client = await Client.newHazelcastClient();
    const map = await client.getMap('someMap');
    await map.set('sid12345', 'example1@email.com');
    await map.set('sid12346', 'example2@email.com');
    console.log(await map.get('sid12345'));
    console.log(await map.get('sid12346'));
})().catch(err => {
    console.log(`An error occured: ${err}`);
});

The output of this snippet is given below:

example1@email.com
example2@email.com

The following line returns a map proxy object for the 'someMap' map:

const map = await client.getMap('someMap');

If the map called “someMap” does not exist in the Hazelcast cluster, it will be automatically created. All the clients that connect to the same cluster will have access to the same map.

With these two lines, the Node.js client adds data to the map. The first parameter is the key of the entry, the second one is the value:

 await map.set('sid12345', 'example1@email.com');
 await map.set('sid12346', 'example2@email.com');

Finally, we get the values we added to the map with the get method:

console.log(await map.get('sid12345'));
console.log(await map.get('sid12346'));

Add a Listener to the Map

You can add an entry listener using the “addEntryListener” method available on map proxy object. This will allow you to listen to certain events that happen in the map across the cluster.

The first argument to the “addEntryListener” method is an object that is used to define listeners. In this example, we registered listeners for the “added”, “removed" and “updated” events.

The second argument in the addEntryListener method is key. It stands for the key to listen for. When it is set to “undefined” (or omitted, which is the same), the listener will be fired for all entries in the map. In this example, we will set it to “undefined” to listen to events from all keys.

The third argument in the addEntryListener method is includeValue. It is a boolean parameter, and if it is true, the entry event contains the entry value. In this example, it will be true.

const { Client } = require('hazelcast-client');

(async () => {
    const client = await Client.newHazelcastClient();
    const map = await client.getMap('someMap');
    map.addEntryListener({
        added: (event) => {
            console.log(`Entry added. Key: ${event.key} Value: ${event.value}`)
        },
        removed: (event) => {
            console.log(`Entry removed. Key: ${event.key}`);
        },
        updated: (event) => {
            console.log(`Entry updated. Key: ${event.key} Value change: ${event.oldValue} -> ${event.value}`)
        },
    }, undefined, true);

    await map.clear();

    await map.set('sid12345', 'example1@email.com');
    await map.set('sid12346', 'example2@email.com');

    let email1 = await map.get('sid12345');
    let email2 = await map.get('sid12346');

    console.log(`Email1: ${email1}`);
    console.log(`Email2: ${email2}`);

    await map.delete('sid12345');
    await map.set('sid12346', 'example1@email.com');

    email1 = await map.get('sid12345');
    email2 = await map.get('sid12346');

    console.log(`Email1: ${email1}`);
    console.log(`Email2: ${email2}`);
})().catch(err => {
    console.log(`An error occured: ${err}`);
});

First, the map is cleared to fire events even if there are some entries in the map. Then, two session entries are added, and they are logged. After that, we remove one of the entries and update the other one. Then, we log the session entries again.

The output is as follows:

Entry added. Key: sid12345 Value: example1@email.com
Entry added. Key: sid12346 Value: example2@email.com
Email1: example1@email.com
Email2: example2@email.com
Entry removed. Key: sid12345
Entry updated. Key: sid12346 Value change: example2@email.com -> example1@email.com
Email1: null
Email2: example1@email.com

The value of the first entry becomes “null” since it is removed.

Summary

In this tutorial, you learned how to get started with Hazelcast Node.js Client using a distributed map.