Hazelcast Node.js Client

Common errors

• Error: Could not connect to any of the cluster members

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

  cause 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

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

Warnings

• breaking 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.
  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.
• breaking The 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()`.
• breaking 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+.
  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.
• gotcha 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.
  Fix: Always install v5.0.1 or a later version (e.g., `npm install hazelcast-client@latest`) instead of v5.0.0.
• gotcha 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.
  Fix: If using Compact Serialization, ensure your Hazelcast server is version 5.2 or newer to guarantee compatibility and stability.

Install

• npm install hazelcast-client npm
• yarn add hazelcast-client yarn
• pnpm add hazelcast-client pnpm

Imports

• Client
  wrong:

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

  correct:

  import { Client } from 'hazelcast-client';

  While `require` works for CJS, modern Node.js and TypeScript projects typically use ESM `import`. Hazelcast Client uses named exports.
• ClientConfig
  wrong:

  import { ClientConfig } from 'hazelcast-client/lib/core';

  correct:

  import { Client, ClientConfig } from 'hazelcast-client';

  Import configuration types directly from the main package entry point. The client ships with TypeScript types.
• IMap
  wrong:

  import { Map } from 'hazelcast-client';

  correct:

  import { IMap } 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.

Quickstart

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);