InfinispanStore — Infinispan distributed in-memory data grid

InfinispanStore — Infinispan distributed in-memory data grid Overview Infinispan is a distributed in-memory key/value data grid. Data lives in named caches; there is no SQL-shaped query(sql) surface for this key/value access, so InfinispanStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes Infinispan's distributed-cache operations (getMap/put/get/remove/keys/size) as a typed, promise-based API. Identity: Property | Value | --------- | -------------- | name | 'infinispan' | library | 'fetch' | Transport: the Infinispan REST API over fetch (not the node driver) Infinispan does publish an infinispan npm client, but that driver binds a client to a single cache at connect time (client.get/put/remove) and offers no per-name getMap. That does not map onto this store's common surface, where getMap(name) must resolve an arbitrary named cache. The Infinispan REST API does map cleanly — every cache/key is addressable as /rest/v2/caches/<cache>/<key> — so this store talks REST over the global fetch. library is therefore 'fetch', and no npm driver is required. A tiny internal fetch client is built at connect() time (from baseURL + headers) unless one is injected. Endpoints wrapped: Method | HTTP request | ----------- | ---------------------------------------------- | mapPut | PUT /rest/v2/caches/<cache>/<key> | mapGet | GET /rest/v2/caches/<cache>/<key> | mapRemove | DELETE /rest/v2/caches/<cache>/<key> | mapKeys | GET /rest/v2/caches/<cache>?action=keys | mapSize | GET /rest/v2/caches/<cache>?action=size | Injected client InfinispanStoreOptions accepts a pre-built client implementing InfinispanHttpClient (get/put/delete). When provided it is used verbatim and baseURL is ignored. This is how the test suite injects a mock HTTP client (no network), and how callers can supply a custom transport. Connection Build a store from connection options and call connect(): Connection options (all optional): Option | Type | Purpose | --------- | ---------------------------- | ----------------------------------------------------------------------------------------- | baseURL | string | Base URL of the Infinispan server. Defaults to http://localhost:11222. | client | InfinispanHttpClient | Pre-built HTTP client; when given it is used verbatim and baseURL is ignored. | headers | Record<string, string> | Extra HTTP headers sent with every internal-client request (e.g. auth). | The default REST base URL is also exported as DEFAULTINFINISPANBASEURL. The internal fetch client factory is exported as createFetchClient(baseURL, headers?). Injected-client form Supply your own client (or a mock) to bypass the internal fetch client: Methods Client failures are wrapped in a DatabaseError (preserving the original error); using getMap() or getClient() before connect() (or after disconnect()) throws a ConnectionError. The map methods take a resolved InfinispanMap handle (from getMap) as their first argument. Cache and key path segments are URL-encoded. Lifecycle Method | Signature | Behavior | ------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise builds an internal fetch client from baseURL + headers. Idempotent. | disconnect | disconnect(): Promise<void> | Clears the client, the cached map handles, and connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): InfinispanHttpClient | Returns the underlying (internal or injected) HTTP client. Throws ConnectionError if not connected. | Distributed cache operations Method | Signature | Behavior | ----------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | getMap | getMap(name: string): Promise<InfinispanMap> | Resolves (and caches) a named-cache handle { name }. Requires a live connection. Idempotent per name. | mapPut | mapPut(map: InfinispanMap, key: string, value: unknown): Promise<void> | PUTs JSON.stringify(value) to /rest/v2/caches/<cache>/<key>. | mapGet | mapGet(map: InfinispanMap, key: string): Promise<any> | GETs /rest/v2/caches/<cache>/<key>; returns the parsed body, or null if absent (404). | mapRemove | mapRemove(map: InfinispanMap, key: string): Promise<any> | DELETEs /rest/v2/caches/<cache>/<key>. | mapKeys | mapKeys(map: InfinispanMap): Promise<any[]> | GETs /rest/v2/caches/<cache>?action=keys; normalizes the body to an array (wraps a non-array, [] on null). | mapSize | mapSize(map: InfinispanMap): Promise<number> | GETs /rest/v2/caches/<cache>?action=size; coerces the body to a number (0 on falsy). | Example Verification status Unit / mock-verified only. The tests in tests/nosql/infinispan.test.ts are fully mock-driven: an in-memory HTTP client implementing InfinispanHttpClient is injected via InfinispanStoreOptions.client. It records every request (method + path + body) and returns canned bodies, so there is no network in the test run. What this proves: name/library identity ('infinispan' / 'fetch'). Each method issues the correct REST request — verified against the recorded (method, path, body): mapPut → PUT /rest/v2/caches/<cache>/<key> with the serialized body; mapGet → GET .../<key> returning the parsed body; mapRemove → DELETE .../<key>; mapKeys → GET ...?action=keys normalized to an array; mapSize → GET ...?action=size coerced to a number. getMap caches handles by name (a === b, a.name === 'users'). Lifecycle: not connected before connect(), idempotent connect, clean disconnect(), injected client exposed via getClient(), and ConnectionError from getClient() / getMap() before connect(). Error handling: client failures wrapped in DatabaseError. What this does not prove: live execution against a real Infinispan REST server. The request shapes are verified against the REST API's documented paths, but end-to-end execution over the wire has not been exercised here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories