Clients

Hazelcast Node.js Client

Hazelcast enables you to accelerate your Node.js applications and work with native Javascript objects or JSON. You can:

  • Build a multi-layer cache for your applications with Hazelcast Map, a distributed & replicated key-value store.
  • Query JSON data at speeds far surpassing traditional document stores.
  • Use the Hazelcast Near Cache feature to store frequently read data in your Node.js process. This provides faster read speeds than popular caching solutions.
  • Enable pub-sub communication between application instances.
  • Deal with high load for view or like events by using a conflict-free replicated counter.
  • Prevent races when accessing 3rd-party services by using Lock and other distributed concurrency primitives available in Hazelcast CP Subsystem, powered by the Raft consensus algorithm.

Quick Start + Download

Quick Start

Available on NPM: npmjs.com/package/hazelcast-client

npm install hazelcast-client --save

Downloads
Version Downloads Documentation
Hazelcast IMDG NodeJS Client 5.2.0 (latest)
12/16/2022
Hazelcast IMDG NodeJS Client 5.1.0
04/29/2022
Hazelcast IMDG NodeJS Client 5.0.4
02/25/2022
Hazelcast IMDG NodeJS Client 5.0.3
01/05/2022

For all downloads please see the Download Archives

Previous Releases

Code Samples

'use strict';

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

(async () => {
    try {
        // Start the Hazelcast Client and connect to an already running
        // Hazelcast Cluster on 127.0.0.1
        const hz = await Client.newHazelcastClient();
        // Get the Distributed Map from Cluster
        const map = await hz.getMap('my-distributed-map');
        // Standard Put and Get
        await map.put('key', 'value');
        await map.get('key');
        // Concurrent Map methods, optimistic updating
        await map.putIfAbsent('somekey', 'somevalue');
        await map.replace('key', 'value', 'newvalue');
        // Shutdown this Hazelcast client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
Get this code sample on Github
'use strict';

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

(async () => {
    try {
        // Start the Hazelcast Client and connect to an already running
        // Hazelcast Cluster on 127.0.0.1
        const hz = await Client.newHazelcastClient();
        // Get a Replicated Map called 'my-replicated-map'
        const map = await hz.getReplicatedMap('my-replicated-map');
        // Put and Get a value from the Replicated Map
        // (key/value is replicated to all members)
        const replacedValue = await map.put('key', 'value');
        // Will print 'Replaced value: null' as it's the first update
        console.log('Replaced value:', replacedValue);
        const value = await map.get('key');
        // The value is retrieved from a random member in the cluster
        console.log('Value for key:', value);
        // Shutdown this Hazelcast client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
Get this code sample on Github
'use strict';

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

(async () => {
    try {
        // Start the Hazelcast Client and connect to an already running
        // Hazelcast Cluster on 127.0.0.1
        const hz = await Client.newHazelcastClient();
        // Get the Distributed MultiMap from Cluster
        const multiMap = await hz.getMultiMap('my-distributed-multimap');
        // Put values in the map against the same key
        await multiMap.put('my-key', 'value1');
        await multiMap.put('my-key', 'value2');
        await multiMap.put('my-key', 'value3');
        // Print out all the values for associated with key called 'my-key'
        const values = await multiMap.get('my-key');
        for (const value of values) {
            console.log(value);
        }
        // remove specific key/value pair
        await multiMap.remove('my-key', 'value2');
        // Shutdown this Hazelcast client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
Get this code sample on Github
'use strict';

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

(async () => {
    try {
        // Start the Hazelcast Client and connect to an already running
        // Hazelcast Cluster on 127.0.0.1
        const hz = await Client.newHazelcastClient();
        // Get the Distributed Set from Cluster
        const set = await hz.getSet('my-distributed-set');
        // Add items to the set with duplicates
        await set.add('item1');
        await set.add('item1');
        await set.add('item2');
        await set.add('item2');
        await set.add('item2');
        await set.add('item3');
        // Get the items. Note that there are no duplicates
        const items = await set.toArray();
        console.log(items);
        // Shutdown this Hazelcast client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
Get this code sample on Github
'use strict';

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

(async () => {
    try {
        // Start the Hazelcast Client and connect to an already running
        // Hazelcast Cluster on 127.0.0.1
        const hz = await Client.newHazelcastClient();
        // Get the Distributed List from Cluster
        const list = await hz.getList('my-distributed-list');
        // Add elements to the list
        await list.add('item1');
        await list.add('item2');
        //Remove the first element
        const value = await list.removeAt(0);
        console.log('Removed:', value);
        // There is only one element left
        const len = await list.size();
        console.log('Current size is', len);
        // Clear the list
        await list.clear();
        // Shutdown this Hazelcast client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
Get this code sample on Github
'use strict';

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

(async () => {
    try {
        // Start the Hazelcast Client and connect to an already running
        // Hazelcast Cluster on 127.0.0.1
        const hz = await Client.newHazelcastClient();
        // Get a Queue called 'my-distributed-queue'
        const queue  = await hz.getQueue('my-distributed-queue');
        // Offer a string into the Distributed Queue
        await queue.offer('item');
        // Poll the Distributed Queue and return the string
        await queue.poll();
        // Timed-restricted operations
        await queue.offer('anotheritem', 500);
        await queue.poll(5000);
        // Indefinitely-waiting operations
        await queue.put('yetanotheritem');
        const item = await await queue.take();
        console.log(item);
        // Shutdown this Hazelcast Client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
Get this code sample on Github
'use strict';

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

(async () => {
    try {
        // Start the Hazelcast Client and connect to an already running
        // Hazelcast Cluster on 127.0.0.1
        const hz = await Client.newHazelcastClient();
        // Get a Topic called 'my-distributed-topic'
        const topic = await hz.getReliableTopic('my-distributed-topic');
        // Add a Listener to the Topic
        topic.addMessageListener((message) => {
            console.log(message);
        });
        // Publish a message to the Topic
        await topic.publish('Hello to distributed world');
        // Shutdown this Hazelcast Client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
Get this code sample on Github
'use strict';

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

class User {
    constructor(username, age, active) {
        this.username = username;
        this.age = age;
        this.active = active;
        this.factoryId = 1;
        this.classId = 1;
    }

    readPortable(reader) {
        this.username = reader.readUTF('username');
        this.age = reader.readInt('age');
        this.active = reader.readBoolean('active');
    }

    writePortable(writer) {
        writer.writeUTF('username', this.username);
        writer.writeInt('age', this.age);
        writer.writeBoolean('active', this.active);
    }
}

function portableFactory(classId) {
    if (classId === 1) {
        return new User();
    }
    return null;
}

async function generateUsers(usersMap) {
    await usersMap.put('Rod', new User('Rod', 19, true));
    await usersMap.put('Jane', new User('Jane', 20, true));
    await usersMap.put('Freddy', new User('Freddy', 23, true));
}

(async () => {
    try {
        // Start the Hazelcast Client and connect to an already running
        // Hazelcast Cluster on 127.0.0.1
        const hz = await Client.newHazelcastClient({
            serialization: {
                portableFactories: {
                    1: portableFactory
                }
            }
        });
        const usersMap = await hz.getMap('users');
        // Add some users to the Distributed Map
        await generateUsers(usersMap);
        // Create a Predicate from a String (a SQL like Where clause)
        const sqlQuery = Predicates.sql('active AND age BETWEEN (18 AND 21)');
        // Creating the same Predicate as above but with a builder
        const criteriaQuery = Predicates.and(
            Predicates.equal('active', true),
            Predicates.between('age', 18, 21)
        );
        // Get result collections using the two different Predicates
        const result1 = await usersMap.values(sqlQuery);
        const result2 = await usersMap.values(criteriaQuery);
        // Print out the results
        console.log(result1.toArray());
        console.log(result2.toArray());
        // Shutdown this Hazelcast client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
Get this code sample on Github
'use strict';

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

(async () => {
    try {
        // Start the Hazelcast Client and connect to an already running
        // Hazelcast Cluster on 127.0.0.1
        const hz = await Client.newHazelcastClient();
        // Get the Distributed Lock from CP Subsystem
        const lock = await hz.getCPSubsystem().getLock('my-distributed-lock');
        // Now acquire the lock and execute some guarded code
        const fence = await lock.lock();
        console.log('Fence token:', fence);
        try {
            // Guarded code goes here
        } finally {
            await lock.unlock(fence);
        }
        // Shutdown this Hazelcast client
        await hz.shutdown();
    } catch (err) {
        console.error('Error occurred:', err);
    }
})();
Get this code sample on Github

Features Implemented for this Client

Data Structures
Node.js Client

Map

Queue

Set

List

MultiMap

Replicated Map

Ring Buffer

Topic

Reliable Topic

JCache

N/A

Cardinality Estimator

Concurrency Primitives
Node.js Client

Lock

Condition

Semaphore

AtomicLong

AtomicReference

ID Generator

CountDownLatch

CRDT PN Counter

Flake ID Generator

Distributed Processing
Node.js Client

Distributed Executor Service

Event Listeners

Sub-Listener Interfaces for Map Listener

Entry Processor

Transactions
Node.js Client

TxnMap

TxnMultiMap

TxnQueue

TxnList

TxnSet

Query
Node.js Client

Query (SQL)

Query (Predicates)

Paging Predicates

Partition Predicates

Built-in Predicates

Continuous Query Caching

N/A

Listener with Predicate

Projections

Fast Aggregations

Near Cache
Node.js Client

Near Cache Support

HD Memory

N/A

Preload Cache from Last Used

Eventual Consistency Control

Configuration
Node.js Client

Declarative Configuration (XML/JSON/YAML)

JSON

Programmatic Configuration

Client Configuration Import

Fail Fast on Invalid Configuration

Security
Node.js Client

SSL Support

XA Transactions

Mutual Authentication

Authorization

Custom Authentication Modules

Management Center
Node.js Client

Management Center Integration / Awareness

Client Near Cache Stats

Client Runtime Stats

Client Operating System Stats

Cloud
Node.js Client

Hazelcast Viridian services

Management Center Integration / Awareness

Kubernetes

AWS

Azure

Google Cloud Platform

Pivotal Cloud Foundry

Docker

Apache jclouds

Consul

etcd

Eureka

Heroku

Zookeeper

Infrastructure
Node.js Client

Open Client Protocol

Smart Client

Unisocket Client

Lifecycle Service

HeartBeat

Backup Acknowledgement to Client

Diagnostics

Serialization
Node.js Client

DataSerializable

N/A

IdentifiedDataSerializable

Portable Serialization

Custom Serialization

Global Serialization

Client Connectivity
Node.js Client

Connection Strategy

Connection Retry

Blue/Green Deployments and Disaster Recovery