Near Caching with the JavaScript Client

What You Will Learn

How to enable client-side near caching to dramatically improve read performance for frequently accessed entries, and how near cache entries are automatically invalidated when server-side data changes.

Prerequisites

Node.js 22+
An Infinispan Server running on localhost:11222

Start an Infinispan Server with Docker or Podman:

docker run -it --rm -p 11222:11222 -e USER=admin -e PASS=password quay.io/infinispan/server:latest

Tip	You can replace `docker` with `podman` in the command above if you use Podman.

Step 1: Create Two Clients

Create a normal client and a near-cache-enabled client for comparison:

const remoteClient = await ispn.client({port: 11222, host: '127.0.0.1'}, {
    authentication: { ... }
});

const nearClient = await ispn.client({port: 11222, host: '127.0.0.1'}, {
    authentication: { ... },
    nearCache: {maxEntries: 20}
});

Step 2: Populate and Warm the Cache

Add entries and read them once to populate the near cache:

for (let i = 0; i < 20; i++) {
    await remoteClient.put('key-' + i, 'value-' + i);
}

for (let i = 0; i < 20; i++) {
    await nearClient.get('key-' + i);
}

console.log('Near cache size: ' + nearClient.nearCacheSize());

Step 3: Compare Performance

Read entries in a loop and compare timing:

const remoteStart = Date.now();
for (let i = 0; i < 10000; i++) {
    await remoteClient.get('key-' + (i % 20));
}
const remoteTime = Date.now() - remoteStart;

Near cache reads are served from local memory without a network round-trip.

Step 4: Run the Tutorial

npm run near-cache

You should see output like:

Populating 20 entries...
Near cache size: 20

=== Performance comparison (10000 reads) ===
Remote reads:     1250 ms
Near cache reads: 35 ms
Speedup: 35.7x

Actual speedup depends on network latency and hardware.

What’s Next

Basic cache operations for standard remote caching
Cache event listeners for reacting to cache changes