hazelcast-client

Hazelcast Node.js Client

---

What is Hazelcast?

Hazelcast is a distributed computation and storage platform for consistently low-latency querying,
aggregation and stateful computation against event streams and traditional data sources. It allows you to quickly build
resource-efficient, real-time applications. You can deploy it at any scale from small edge devices to a large cluster of
cloud instances.

A cluster of Hazelcast nodes share both the data storage and computational load which can dynamically scale up and down.
When you add new nodes to the cluster, the data is automatically rebalanced across the cluster, and currently running
computational tasks (known as jobs) snapshot their state and scale with processing guarantees.

For more info, check out Hazelcast repository.

What is Hazelcast Node.js Client?

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

Installation

$3

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

A Hazelcast 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 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.

``bash
docker run -p 5701:5701 hazelcast/hazelcast
`

This command fetches the latest Hazelcast version. You can find all available tags
here.

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

$3

`bash
npm install hazelcast-client
`

Overview

$3

`js
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
await client.shutdown();
`

> **NOTE: For the sake of brevity we are going to omit boilerplate parts in the above code snippet.
> Refer to this code sample
> to see the complete code.**

If you are using Hazelcast 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.

$3

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

// Initialize the client with the given configuration
const client = await Client.newHazelcastClient({
clusterName: 'cluster-name',
network: {
clusterMembers: [
'10.90.0.2:5701',
'10.90.0.3:5701'
]
},
lifecycleListeners: [
(state) => {
console.log('Lifecycle Event >>> ' + state);
}
]
});

console.log('Connected to cluster');
await client.shutdown();
`

Refer to the documentation to learn more about supported configuration options.

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
* Distributed concurrency primitives from CP Subsystem such as FencedLock, Semaphore, AtomicLong
* 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:

* GitHub repository
* Complete documentation
* API documentation
* Slack
* Google Groups
* Stack Overflow

Contributing

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

$3

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

* Hazelcast 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.

$3

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:

`bash
npm test
`

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

In order to run specific tests, you can give a pattern to the test command like the following:

`bash
npm test pattern
`

This command will only run the tests matching the pattern. The pattern can be a string or regex in the same form
grep` command accepts.

License

Apache 2.0 License.

Copyright

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

Visit www.hazelcast.com for more information.