{"id":16087,"library":"infinispan","title":"Infinispan Hot Rod JS Client","description":"The `infinispan` package provides an asynchronous, event-driven JavaScript client for Node.js applications to interact with Infinispan data grids using the Hot Rod protocol. Currently at version 0.13.0, it leverages Promises for all asynchronous operations, simplifying error handling and chaining. The client offers comprehensive CRUD capabilities, compare-and-swap operations, expiration management with flexible time units, bulk operations (putAll, getAll, clear), and advanced features like remote cache listeners, server-side script execution, and statistics retrieval. A key differentiator is its robust cluster awareness, supporting consistent hashing for key-based operations, dynamic topology discovery for nodes joining or leaving, and automatic multi-site failover with manual switching capabilities. It's under active development, indicating ongoing feature additions and improvements.","status":"active","version":"0.13.0","language":"javascript","source_language":"en","source_url":"https://github.com/infinispan/js-client","tags":["javascript","infinispan","cache","client","cluster","failover","hashing","nosql","typescript"],"install":[{"cmd":"npm install infinispan","lang":"bash","label":"npm"},{"cmd":"yarn add infinispan","lang":"bash","label":"yarn"},{"cmd":"pnpm add infinispan","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used as the underlying HTTP/1.1 client for network communication.","package":"undici"},{"reason":"Common utility library, likely used for internal data manipulation.","package":"lodash"}],"imports":[{"note":"The `infinispan` package exports a default object or function which contains the `client` factory method.","wrong":"import { client } from 'infinispan';","symbol":"infinispan","correct":"import infinispan from 'infinispan';"},{"note":"The client instance is created via an async factory method, not directly instantiated. Always await its resolution.","wrong":"const client = new infinispan.Client(...);","symbol":"client","correct":"const client = await infinispan.client({ host: '127.0.0.1', port: 11222 }, { cacheName: 'myCache' });"},{"note":"For TypeScript users, `CacheClient` is the interface representing the connected client instance.","symbol":"CacheClient","correct":"import type { CacheClient } from 'infinispan';"}],"quickstart":{"code":"import infinispan from 'infinispan';\n\nasync function runClient() {\n  let client;\n  try {\n    // Connect to Infinispan Server on localhost:11222\n    // and specify a cache name, e.g., 'myCache'.\n    // Ensure an Infinispan server is running and 'myCache' exists or is configured for autostart.\n    client = await infinispan.client(\n      { host: process.env.INFINISPAN_HOST ?? '127.0.0.1', port: parseInt(process.env.INFINISPAN_PORT ?? '11222', 10) },\n      { cacheName: process.env.INFINISPAN_CACHE_NAME ?? 'myCache' }\n    );\n    console.log('Successfully connected to Infinispan!');\n\n    const key = 'myKey';\n    const value = 'myValue';\n\n    // Put an entry into the cache\n    await client.put(key, value);\n    console.log(`Put: '${key}' -> '${value}'`);\n\n    // Get the entry from the cache\n    const retrievedValue = await client.get(key);\n    console.log(`Get: '${key}' -> '${retrievedValue}'`);\n\n    // Check if the key exists\n    const contains = await client.containsKey(key);\n    console.log(`Contains key '${key}': ${contains}`);\n\n  } catch (error) {\n    console.error('Error interacting with Infinispan:', error.message);\n  } finally {\n    if (client) {\n      await client.disconnect();\n      console.log('Disconnected from Infinispan.');\n    }\n  }\n}\n\nrunClient();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<0.6.0"},{"fix":"Ensure the `infinispan` client version is compatible with your Infinispan Server version. Consult the client's installation guide for precise compatibility matrix.","message":"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.","severity":"breaking","affected_versions":"all"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"Infinispan Server enables authentication by default. Connecting without proper authentication configuration will result in connection failures or access denied errors.","severity":"gotcha","affected_versions":"all"},{"fix":"When initializing the client for query operations, include `{ dataFormat: 'application/x-protostream' }` in the client options.","message":"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`.","severity":"gotcha","affected_versions":">=0.10.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The Infinispan server is not running, or the client is trying to connect to the wrong host/port.","error":"Error: connect ECONNREFUSED 127.0.0.1:11222"},{"fix":"Ensure you are using `import infinispan from 'infinispan';` for ESM, and then `await infinispan.client(...)`. For CommonJS, use `const infinispan = require('infinispan');`.","cause":"The `infinispan` module was imported incorrectly, or the `client` method is being accessed before the module is fully loaded or correctly referenced.","error":"TypeError: infinispan.client is not a function"},{"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.","cause":"The specified cache name does not exist on the Infinispan server.","error":"CacheNotFoundException: Cache 'myCache' not found"},{"fix":"Always use `.catch()` with Promise chains or `try...catch` blocks with `async/await` to handle potential errors from all client operations.","cause":"An asynchronous operation (e.g., `put`, `get`, `connect`) failed, and the returned Promise's rejection was not caught.","error":"UnhandledPromiseRejectionWarning: Unhandled promise rejection."}],"ecosystem":"npm"}