infinispan

library1.0.0b2jsnpmunverified

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.

database http-networking workflow

npm install infinispan

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · INFINISPAN

infinispan

databasejavascriptv1.0.0b2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

infinispan

✓ import infinispan from 'infinispan';

✗ import { client } from 'infinispan';

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

client

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

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

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.

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

Debug

Known issues

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

affects: <0.6.0

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

affects: all

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

affects: all

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

affects: all

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

affects: >=0.10.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED 127.0.0.1:11222

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

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

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.

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.

Upgrade

Version history

1.0.0b2latest on npm

Audit

Dependencies

undicirequiredUsed as the underlying HTTP/1.1 client for network communication.

lodashrequiredCommon utility library, likely used for internal data manipulation.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/infinispan/js-client ↗

packagehttps://www.npmjs.com/package/infinispan ↗

homepagehttps://infinispan.org ↗