Infinispan Hot Rod JS Client

Common errors

• Error: connect ECONNREFUSED 127.0.0.1:11222

  cause The Infinispan server is not running, or the client is trying to connect to the wrong host/port.
  fix Verify that your Infinispan server is running and listening on the configured host and port (default is 11222). Check firewall rules. Ensure host/port in `infinispan.client()` call are correct.

• TypeError: infinispan.client is not a function

  cause The `infinispan` module was imported incorrectly, or the `client` method is being accessed before the module is fully loaded or correctly referenced.
  fix Ensure you are using `import infinispan from 'infinispan';` for ESM, and then `await infinispan.client(...)`. For CommonJS, use `const infinispan = require('infinispan');`.

• CacheNotFoundException: Cache 'myCache' not found

  cause The specified cache name does not exist on the Infinispan server.
  fix Ensure the cache `myCache` is created and configured on your Infinispan server. You might need to use the server console or management API to create it, or configure the server for automatic cache creation.

• UnhandledPromiseRejectionWarning: Unhandled promise rejection.

  cause An asynchronous operation (e.g., `put`, `get`, `connect`) failed, and the returned Promise's rejection was not caught.
  fix Always use `.catch()` with Promise chains or `try...catch` blocks with `async/await` to handle potential errors from all client operations.

Warnings

• breaking Older versions of the client (pre-0.6) only supported string keys and values. Native JSON object support was added in version 0.6.0. Using JSON with older clients will result in incorrect serialization.
  Fix: Upgrade to `infinispan` client version 0.6.0 or newer to use native JSON objects for keys and values, or manually serialize/deserialize to strings.
• breaking For Infinispan Server versions 8.2.x to 9.3.x, use `js-client` version 0.7. Later server versions (9.4.x and above) require `js-client` 0.10.0 or later.
  Fix: Ensure the `infinispan` client version is compatible with your Infinispan Server version. Consult the client's installation guide for precise compatibility matrix.
• gotcha The client is under 'heavy development,' implying that API stability between minor versions might not be strictly maintained, and breaking changes could occur in minor or patch releases without explicit major version bumps.
  Fix: Pin your client version (e.g., `~0.13.0` or `0.13.0`) and review release notes thoroughly for any updates before upgrading, especially in production environments. Regular testing is recommended.
• gotcha Infinispan Server enables authentication by default. Connecting without proper authentication configuration will result in connection failures or access denied errors.
  Fix: Configure the client with appropriate `authentication` options including `userName`, `password`, and `saslMechanism` (e.g., 'DIGEST-MD5', 'SCRAM'). Create a user on the Infinispan server if not already done.
• gotcha To perform queries on caches, the `dataFormat` option must be explicitly set to `'application/x-protostream'`. By default, the client treats key/value pairs as `String`.
  Fix: When initializing the client for query operations, include `{ dataFormat: 'application/x-protostream' }` in the client options.

Install

• npm install infinispan npm
• yarn add infinispan yarn
• pnpm add infinispan pnpm

Imports

• infinispan
  wrong:

  import { client } from 'infinispan';

  correct:

  import infinispan from 'infinispan';

  The `infinispan` package exports a default object or function which contains the `client` factory method.
• client
  wrong:

  const client = new infinispan.Client(...);

  correct:

  const client = await infinispan.client({ host: '127.0.0.1', port: 11222 }, { cacheName: 'myCache' });

  The client instance is created via an async factory method, not directly instantiated. Always await its resolution.
• CacheClient

  import type { CacheClient } from 'infinispan';

  For TypeScript users, `CacheClient` is the interface representing the connected client instance.

Quickstart

This example demonstrates how to connect to an Infinispan server, put a key-value pair into a named cache, retrieve it, and check for its existence, then disconnect.

import infinispan from 'infinispan';

async function runClient() {
  let client;
  try {
    // Connect to Infinispan Server on localhost:11222
    // and specify a cache name, e.g., 'myCache'.
    // Ensure an Infinispan server is running and 'myCache' exists or is configured for autostart.
    client = await infinispan.client(
      { host: process.env.INFINISPAN_HOST ?? '127.0.0.1', port: parseInt(process.env.INFINISPAN_PORT ?? '11222', 10) },
      { cacheName: process.env.INFINISPAN_CACHE_NAME ?? 'myCache' }
    );
    console.log('Successfully connected to Infinispan!');

    const key = 'myKey';
    const value = 'myValue';

    // Put an entry into the cache
    await client.put(key, value);
    console.log(`Put: '${key}' -> '${value}'`);

    // Get the entry from the cache
    const retrievedValue = await client.get(key);
    console.log(`Get: '${key}' -> '${retrievedValue}'`);

    // Check if the key exists
    const contains = await client.containsKey(key);
    console.log(`Contains key '${key}': ${contains}`);

  } catch (error) {
    console.error('Error interacting with Infinispan:', error.message);
  } finally {
    if (client) {
      await client.disconnect();
      console.log('Disconnected from Infinispan.');
    }
  }
}

runClient();