Registry / database / hazelcast-client

hazelcast-client

JSON →
library5.6.0jsnpmunverified

The Hazelcast Node.js client, currently at version 5.6.0, provides a robust, promise-based API for connecting Node.js applications to a Hazelcast cluster, a distributed computation and storage platform. It enables developers to interact with distributed data structures like Maps, Queues, and Topics, facilitating real-time stream processing and in-memory data grid functionalities. The client supports native JavaScript objects and ships with TypeScript types, ensuring a smooth development experience. Releases are frequent, with significant updates often introducing new features such as stable Compact Serialization in v5.2.0 and SQL JSON support, while maintaining backward compatibility where possible. Its key differentiators include seamless integration with the Hazelcast ecosystem, resilience through data rebalancing and backups across cluster members, and dynamic scalability for handling varying data and computational loads, from edge devices to large cloud deployments.

npm install hazelcast-client
INSTALL
IMPORT
SIG · HAZELCAST-CLIENT
H
hazelcast-client
databasejavascriptv5.6.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Client
import { Client } from 'hazelcast-client';
const { Client } = require('hazelcast-client');
While `require` works for CJS, modern Node.js and TypeScript projects typically use ESM `import`. Hazelcast Client uses named exports.
ClientConfig
import { Client, ClientConfig } from 'hazelcast-client';
import { ClientConfig } from 'hazelcast-client/lib/core';
Import configuration types directly from the main package entry point. The client ships with TypeScript types.
IMap
import { IMap } from 'hazelcast-client';
import { Map } from 'hazelcast-client';
Distributed data structure interfaces like `IMap`, `IQueue`, `ITopic` are commonly used for type-hinting; ensure correct interface name and import from the main package.

Demonstrates connecting to a local Hazelcast cluster, creating/accessing a distributed map, performing put and get operations, and gracefully shutting down the client. Includes basic error handling and TypeScript types.

import { Client, ClientConfig } from 'hazelcast-client'; async function main() { // Basic configuration for connecting to a local Hazelcast cluster // Ensure a Hazelcast instance is running, e.g., via `docker run -p 5701:5701 hazelcast/hazelcast` const config: ClientConfig = { clusterName: 'dev', // Default cluster name for many Hazelcast deployments network: { clusterMembers: ['127.0.0.1:5701'] // Default address for a local cluster } }; let client: Client | undefined; try { console.log('Attempting to connect to Hazelcast cluster...'); client = await Client.newHazelcastClient(config); console.log('Successfully connected to Hazelcast cluster.'); // Get or create a distributed map on the cluster const map = await client.getMap<string, string>('my-distributed-map'); console.log(`Accessed distributed map: '${map.getName()}'`); const key = 'uniqueKey'; const value = `Value at ${new Date().toISOString()}`; // Put a key-value pair into the distributed map await map.put(key, value); console.log(`Put '${key}': '${value}' into the map.`); // Get the value associated with the given key from the cluster const retrievedValue = await map.get(key); console.log(`Retrieved value for '${key}': '${retrievedValue}'`); // Remove the key from the map await map.remove(key); console.log(`Removed key '${key}' from the map.`); } catch (error) { console.error('An error occurred during Hazelcast operations:', error); } finally { if (client) { await client.shutdown(); console.log('Hazelcast client shutdown successfully.'); } } } main().catch(console.error);
Debug
Known issues
breakingThe compact serialization's Rabin fingerprint calculation was fixed in v5.6.0. While typically not causing issues, it's advised to verify production environments before upgrading to ensure data compatibility if compact serialization is heavily used.
fix
Before upgrading to 5.6.0+, thoroughly test compact serialized data reading in a staging environment. If issues arise, ensure consistent client and server versions, or migrate data using a compatible serialization method.
affects: >=5.6.0
breakingThe method `Client.getSqlService()` was renamed to `Client.getSql()` in version 5.0.0. Older code using the deprecated method will fail.
fix
Update all calls from `client.getSqlService()` to `client.getSql()`.
affects: >=5.0.0
breakingFor SQL compatibility with `LocalDate`, `LocalDateTime`, and `OffsetDateTime` types, the year field is now sent as an integer. This requires using a Hazelcast Node.js client v5.0+ with a Hazelcast server v5.0+.
fix
Ensure both your Hazelcast Node.js client and Hazelcast server versions are 5.0 or newer for full SQL compatibility with these date/time types.
affects: >=5.0.0
gotchaHazelcast Node.js Client v5.0.0 was deprecated on npm shortly after release due to an npm-related mistake. Users should avoid installing v5.0.0 directly.
fix
Always install v5.0.1 or a later version (e.g., `npm install hazelcast-client@latest`) instead of v5.0.0.
affects: 5.0.0
gotchaCompact Serialization, introduced as BETA in v5.1.0 and stabilized in v5.2.0, requires a compatible Hazelcast server version (v5.2 or newer) for stable operation. Using an older server version with a client utilizing stable compact serialization may lead to issues.
fix
If using Compact Serialization, ensure your Hazelcast server is version 5.2 or newer to guarantee compatibility and stability.
affects: >=5.1.0
Errors
Common errors & fixes
Error: Could not connect to any of the cluster members
The client could not establish a connection to any specified Hazelcast cluster member. This often indicates no Hazelcast server is running at the configured address/port, or network firewall issues.
fix
Verify that a Hazelcast cluster member is running and accessible at the `clusterMembers` addresses specified in your `ClientConfig`. Common default is `127.0.0.1:5701`. Check firewalls if connecting to a remote server.
TypeError: client.getSqlService is not a function
This error occurs when using a Hazelcast Node.js Client v5.0.0 or newer with code that still calls `getSqlService()`.
fix
Rename `client.getSqlService()` to `client.getSql()` as the method was renamed in version 5.0.0.
TypeError: The 'await' operator can only be used in an async function
You are using `await` outside of an `async` function context. The Hazelcast client API is promise-based and requires `await` calls to be within `async` functions.
fix
Wrap your client initialization and operations in an `async` function, then call that function. For top-level awaiting in modules, ensure your Node.js version supports it and your `package.json` is configured for ESM.
Upgrade
Version history
5.6.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
11 hits · last 30 days
node
10
Amazon
1
Resources