{"id":17246,"library":"hazelcast-client","title":"Hazelcast Node.js Client","description":"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.","status":"active","version":"5.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/hazelcast/hazelcast-nodejs-client","tags":["javascript","hazelcast","real-time","stream processing","node","nodejs","node.js","client","typescript"],"install":[{"cmd":"npm install hazelcast-client","lang":"bash","label":"npm"},{"cmd":"yarn add hazelcast-client","lang":"bash","label":"yarn"},{"cmd":"pnpm add hazelcast-client","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While `require` works for CJS, modern Node.js and TypeScript projects typically use ESM `import`. Hazelcast Client uses named exports.","wrong":"const { Client } = require('hazelcast-client');","symbol":"Client","correct":"import { Client } from 'hazelcast-client';"},{"note":"Import configuration types directly from the main package entry point. The client ships with TypeScript types.","wrong":"import { ClientConfig } from 'hazelcast-client/lib/core';","symbol":"ClientConfig","correct":"import { Client, ClientConfig } from 'hazelcast-client';"},{"note":"Distributed data structure interfaces like `IMap`, `IQueue`, `ITopic` are commonly used for type-hinting; ensure correct interface name and import from the main package.","wrong":"import { Map } from 'hazelcast-client';","symbol":"IMap","correct":"import { IMap } from 'hazelcast-client';"}],"quickstart":{"code":"import { Client, ClientConfig } from 'hazelcast-client';\n\nasync function main() {\n    // Basic configuration for connecting to a local Hazelcast cluster\n    // Ensure a Hazelcast instance is running, e.g., via `docker run -p 5701:5701 hazelcast/hazelcast`\n    const config: ClientConfig = {\n        clusterName: 'dev', // Default cluster name for many Hazelcast deployments\n        network: {\n            clusterMembers: ['127.0.0.1:5701'] // Default address for a local cluster\n        }\n    };\n\n    let client: Client | undefined;\n    try {\n        console.log('Attempting to connect to Hazelcast cluster...');\n        client = await Client.newHazelcastClient(config);\n        console.log('Successfully connected to Hazelcast cluster.');\n\n        // Get or create a distributed map on the cluster\n        const map = await client.getMap<string, string>('my-distributed-map');\n        console.log(`Accessed distributed map: '${map.getName()}'`);\n\n        const key = 'uniqueKey';\n        const value = `Value at ${new Date().toISOString()}`;\n\n        // Put a key-value pair into the distributed map\n        await map.put(key, value);\n        console.log(`Put '${key}': '${value}' into the map.`);\n\n        // Get the value associated with the given key from the cluster\n        const retrievedValue = await map.get(key);\n        console.log(`Retrieved value for '${key}': '${retrievedValue}'`);\n\n        // Remove the key from the map\n        await map.remove(key);\n        console.log(`Removed key '${key}' from the map.`);\n\n    } catch (error) {\n        console.error('An error occurred during Hazelcast operations:', error);\n    } finally {\n        if (client) {\n            await client.shutdown();\n            console.log('Hazelcast client shutdown successfully.');\n        }\n    }\n}\n\nmain().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"The 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.","severity":"breaking","affected_versions":">=5.6.0"},{"fix":"Update all calls from `client.getSqlService()` to `client.getSql()`.","message":"The method `Client.getSqlService()` was renamed to `Client.getSql()` in version 5.0.0. Older code using the deprecated method will fail.","severity":"breaking","affected_versions":">=5.0.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.","message":"For 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+.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Always install v5.0.1 or a later version (e.g., `npm install hazelcast-client@latest`) instead of v5.0.0.","message":"Hazelcast 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.","severity":"gotcha","affected_versions":"5.0.0"},{"fix":"If using Compact Serialization, ensure your Hazelcast server is version 5.2 or newer to guarantee compatibility and stability.","message":"Compact 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.","severity":"gotcha","affected_versions":">=5.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: Could not connect to any of the cluster members"},{"fix":"Rename `client.getSqlService()` to `client.getSql()` as the method was renamed in version 5.0.0.","cause":"This error occurs when using a Hazelcast Node.js Client v5.0.0 or newer with code that still calls `getSqlService()`.","error":"TypeError: client.getSqlService is not a function"},{"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.","cause":"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.","error":"TypeError: The 'await' operator can only be used in an async function"}],"ecosystem":"npm","meta_description":null}