Miss any of our Open RFC calls?Watch the recordings here! »

hazelcast-client

3.12.3 • Public • Published

Hazelcast Node.js Client

NPM version Chat on Gitter Follow on Twitter


Hazelcast is an open-source distributed in-memory data store and computation platform that provides a wide variety of distributed data structures and concurrency primitives.

Hazelcast Node.js client is a way to communicate to Hazelcast IMDG clusters and access the cluster data. The client provides a Promise-based API with a builtin support for native JavaScript objects.

Installation

Hazelcast

Hazelcast Node.js client requires a working Hazelcast IMDG cluster to run. This cluster handles the storage and manipulation of the user data.

A Hazelcast IMDG cluster consists of one or more cluster members. These members generally run on multiple virtual or physical machines and are connected to each other via the network. Any data put on the cluster is partitioned to multiple members transparent to the user. It is therefore very easy to scale the system by adding new members as the data grows. Hazelcast IMDG cluster also offers resilience. Should any hardware or software problem causes a crash to any member, the data on that member is recovered from backups and the cluster continues to operate without any downtime.

The quickest way to start a single member cluster for development purposes is to use our Docker images.

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

You can also use our ZIP or TAR distributions as described here.

Make sure to use Hazelcast IMDG 3.x versions as the work to support 4.x versions is in progress.

Client

npm install hazelcast-client

Overview

Usage

const { Client } = require('hazelcast-client');
 
// Connect to Hazelcast cluster
const client = await Client.newHazelcastClient();
 
// Get or create the 'distributed-map' on the cluster
const map = await client.getMap('distributed-map');
 
// Put 'key', 'value' pair into the 'distributed-map'
await map.put('key', 'value');
 
// Get the value associated with the given key from the cluster
const value = await map.get('key');
console.log(value); // Outputs 'value'
 
// Shutdown the client
client.shutdown();

If you are using Hazelcast IMDG and the Node.js client on the same machine, the default configuration should work out-of-the-box. However, you may need to configure the client to connect to cluster nodes that are running on different machines or to customize client properties.

Configuration

const { Client, Config } = require('hazelcast-client');
 
// Create a configuration object
const clientConfig = new Config.ClientConfig();
 
// Customize the client configuration
clientConfig.groupConfig.name = 'cluster-name';
clientConfig.networkConfig.addresses.push('10.90.0.2:5701');
clientConfig.networkConfig.addresses.push('10.90.0.3:5701');
 
// Initialize the client with the given configuration
const client = await Client.newHazelcastClient(clientConfig);
 
console.log('Connected to cluster');
client.shutdown();

You can also configure the client declaratively using a JSON file.

Features

  • Distributed, partitioned and queryable in-memory key-value store implementation, called Map
  • Eventually consistent cache implementation to store a subset of the Map data locally in the memory of the client, called Near Cache
  • Additional data structures and simple messaging constructs such as Set, MultiMap, Queue, Topic
  • Cluster-wide unique ID generator, called FlakeIdGenerator
  • Distributed, CRDT based counter, called PNCounter
  • Primitives for distributed computing such as Lock, Semaphore, Atomic Long
  • Integration with Hazelcast Cloud
  • Support for serverless and traditional web service architectures with Unisocket and Smart operation modes
  • Ability to listen client lifecycle, cluster state and distributed data structure events
  • and many more.

Getting Help

You can use the following channels for your questions and development/usage issues:

Contributing

We encourage any type of contribution in the form of issue reports or pull requests.

Issue Reports

For issue reports, please share the following information with us to quickly resolve the problems.

  • Hazelcast IMDG and the client version that you use
  • General information about the environment and the architecture you use like Node.js version, cluster size, number of clients, Java version, JVM parameters, operating system etc.
  • Logs and stack traces, if any.
  • Detailed description of the steps to reproduce the issue.

Pull Requests

Contributions are submitted, reviewed and accepted using the pull requests on GitHub. For an enhancement or larger feature, create a GitHub issue first to discuss.

Development

  1. Clone the GitHub repository.
  2. Run npm install to automatically download and install all the required modules.
  3. Do the work.
  4. Hazelcast Node.js client developed using TypeScript. Run npm run compile to compile TypeScript files to JavaScript.
  5. To have a consistent code style across the code base, Hazelcast Node.js client uses a style checker. Run npm run lint and fix the reported issues, if any.

Testing

In order to test Hazelcast Node.js client locally, you will need the following:

  • Java 8 or newer
  • Maven

Following command starts the tests:

npm test

Test script automatically downloads hazelcast-remote-controller and Hazelcast IMDG. The script uses Maven to download those.

License

Apache 2 License.

Copyright

Copyright (c) 2008-2020, Hazelcast, Inc. All Rights Reserved.

Visit www.hazelcast.com for more information.

Install

npm i hazelcast-client

DownloadsWeekly Downloads

1,319

Version

3.12.3

License

Apache-2.0

Unpacked Size

3.09 MB

Total Files

1109

Last publish

Collaborators

  • avatar