Node.js Pure JavaScript ZooKeeper Client

Common errors

• Failed to create node: %s due to: %s. (KeeperErrorCode = NodeExists)

  cause Attempting to create a znode at a path where a node already exists.
  fix Before creating a node, use `client.exists(path, callback)` to check if it already exists. Handle the `NODE_EXISTS` exception explicitly if creating an existing node is an expected scenario.

• ZooKeeper client encountered an error: Error: Connection refused

  cause The client could not establish a connection to the specified ZooKeeper server. This often indicates the server is not running, is on a different host/port, or a firewall is blocking the connection.
  fix Verify that the ZooKeeper server process is running and accessible from the Node.js application's host and port. Check firewall rules and the `connectionString` passed to `createClient`.

• WARN Session 0x0 for server null, unexpected error, closing socket connection and attempting reconnect java.net.ConnectException: Connection refused

  cause Similar to 'Connection refused', this warning (often seen in ZK logs or client output) indicates the client lost connection to the server or couldn't initially connect, often due to network issues, incorrect host/port, or the server being down.
  fix Ensure the ZooKeeper ensemble is healthy and accessible. Review network configuration and verify the `connectionString`. Also, check ZooKeeper server logs for issues on the server side.

• The lib will segfault if you try to use a ZooKeeper instance after the on_closed event is delivered (possibly as a result of session timeout etc.) YOU MAY NOT re-use the closed ZooKeeper instance.

  cause Attempting to perform operations on a `Client` instance after its session has expired or the connection has been explicitly closed, leading to undefined behavior or crashes.
  fix Upon receiving a 'disconnected' or 'close' event, dispose of the current `Client` instance. If a new connection is needed, create an entirely new client instance using `zookeeper.createClient()`.

Warnings

• breaking This package (node-zookeeper-client by alexguan) is effectively abandoned, with the last publish over four years ago. It only supports ZooKeeper server versions up to 3.4.*, which is severely outdated. For modern ZooKeeper versions (3.5.x+) and active development, consider the `zookeeper` package (yfinkelstein/node-zookeeper) which uses the C client bindings.
  Fix: Migrate to `zookeeper` package for active maintenance and support for newer ZooKeeper server versions.
• breaking Older versions of this package (1.0.0, 1.1.0, 1.1.1) have known 'severe vulnerabilities exploited'. While the latest 1.1.3 might implicitly fix some, the lack of active maintenance means new vulnerabilities are unlikely to be addressed. It's not recommended for production use due to security risks.
  Fix: Upgrade to the latest available version (1.1.3) within this package if forced to use it, but strongly consider migrating to the actively maintained `zookeeper` package for better security posture.
• gotcha This client primarily uses callback-based asynchronous patterns, typical for older Node.js modules. It does not natively support Promises or async/await syntax, which can lead to callback hell in complex applications.
  Fix: Wrap callback-based functions with `util.promisify` or custom Promise wrappers if modern async/await syntax is desired, or migrate to a more modern client like `zookeeper`.
• gotcha The client handles ZooKeeper connection state changes and watcher events through an event emitter API. Developers must explicitly listen for the 'connected', 'disconnected', and 'error' events to manage the client lifecycle and react to network issues or session expirations.
  Fix: Ensure event listeners are set up for 'connected', 'disconnected', and 'error' on the client instance to correctly manage connection state and handle failures. For example: `client.once('connected', ...)` and `client.on('error', ...)`.

Install

• npm install node-zookeeper-client npm
• yarn add node-zookeeper-client yarn
• pnpm add node-zookeeper-client pnpm

Imports

• createClient
  wrong:

  const createClient = require('node-zookeeper-client').createClient;

  correct:

  import { createClient } from 'node-zookeeper-client';

  While CommonJS is the primary usage, modern bundlers may allow named ESM import. The main export is the `zookeeper` object, which has `createClient` as a property.
• zookeeper
  wrong:

  import zookeeper from 'node-zookeeper-client';

  correct:

  const zookeeper = require('node-zookeeper-client');

  This package is primarily CommonJS. Direct `import zookeeper from 'node-zookeeper-client'` (default ESM import) is unlikely to work without specific Node.js configuration or a transpiler, and even then, `zookeeper.createClient` would be the correct access pattern.
• Event
  wrong:

  import { Event } from 'node-zookeeper-client';

  correct:

  const { Event } = require('node-zookeeper-client');
  // or
  const zookeeper = require('node-zookeeper-client');
  const Event = zookeeper.Event;

  Event (and other utility classes like State, Transaction, Exception) are exposed as properties of the main module object.

Quickstart

This example connects to a local ZooKeeper instance, creates an ephemeral node with data, and then attempts to retrieve its data with a watcher, handling potential 'node exists' errors.

const zookeeper = require('node-zookeeper-client');

const client = zookeeper.createClient('localhost:2181');
const path = '/my-test-node'; // Using a fixed path for a runnable example
const data = Buffer.from('Hello ZooKeeper');

client.once('connected', function () {
    console.log('Connected to the ZooKeeper server.');

    client.create(path, data, zookeeper.ACL.OPEN_ACL_UNSAFE, zookeeper.CreateMode.EPHEMERAL, function (error) {
        if (error) {
            if (error.getCode() === zookeeper.Exception.NODE_EXISTS) {
                console.log('Node %s already exists, skipping creation.', path);
            } else {
                console.error('Failed to create node: %s due to: %s.', path, error);
                client.close();
                return;
            }
        } else {
            console.log('Node: %s is successfully created with data: %s.', path, data.toString());
        }

        // Example of getting data
        client.getData(path, function (event) {
            console.log('Watcher triggered for %s: %s', path, event);
        }, function (error, data, stat) {
            if (error) {
                console.error('Failed to get data from %s due to: %s.', path, error);
            } else {
                console.log('Data of %s is: %s (version: %d).', path, data.toString(), stat.version);
            }
            client.close();
        });
    });
});

client.on('error', function (error) {
    console.error('ZooKeeper client encountered an error: %s', error.stack);
});

client.connect();