CoherenceStore — Oracle Coherence distributed in-memory data grid

CoherenceStore — Oracle Coherence distributed in-memory data grid Overview Oracle Coherence is a distributed in-memory data grid. Data lives in named caches — its distributed maps. There is no SQL-shaped query(sql) surface for this key/value access, so CoherenceStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes Coherence's cache operations (getMap/put/get/remove/keys/size) as a typed, promise-based API. Identity: Property | Value | --------- | -------------- | name | 'coherence' | library | 'fetch' | Transport: the Coherence REST API over fetch Coherence exposes a language-neutral REST API rather than a canonical Node.js driver, so this store talks to it with 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. The cache name is the first path segment. Endpoints wrapped: Method | HTTP request | ----------- | -------------------------- | mapPut | PUT /<cache>/<key> | mapGet | GET /<cache>/<key> | mapRemove | DELETE /<cache>/<key> | mapKeys | GET /<cache>/keys | mapSize | GET /<cache>/count | Injected client CoherenceStoreOptions accepts a pre-built client implementing CoherenceHttpClient (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 Coherence REST server. Defaults to http://localhost:8080. | client | CoherenceHttpClient | 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 DEFAULTCOHERENCEBASEURL. 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 CoherenceCache 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 cache handles, and connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): CoherenceHttpClient | Returns the underlying (internal or injected) HTTP client. Throws ConnectionError if not connected. | Distributed cache operations Method | Signature | Behavior | ----------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | getMap | getMap(name: string): Promise<CoherenceCache> | Resolves (and caches) a named-cache handle { name }. Requires a live connection. Idempotent per name. | mapPut | mapPut(map: CoherenceCache, key: string, value: unknown): Promise<void> | PUTs JSON.stringify(value) to /<cache>/<key>. | mapGet | mapGet(map: CoherenceCache, key: string): Promise<any> | GETs /<cache>/<key>; returns the parsed body, or null if absent (404). | mapRemove | mapRemove(map: CoherenceCache, key: string): Promise<any> | DELETEs /<cache>/<key>. | mapKeys | mapKeys(map: CoherenceCache): Promise<any[]> | GETs /<cache>/keys; normalizes the body to an array (bare array, { keys: [...] }, or wraps a scalar). | mapSize | mapSize(map: CoherenceCache): Promise<number> | GETs /<cache>/count; coerces the body to a number (0 on falsy). | Example Verification status Unit / mock-verified only. The tests in tests/nosql/coherence.test.ts are fully mock-driven: an in-memory HTTP client implementing CoherenceHttpClient is injected via CoherenceStoreOptions.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 ('coherence' / 'fetch'). Each method issues the correct REST request — verified against the recorded (method, path, body): mapPut → PUT /<cache>/<key> with the serialized body; mapGet → GET /<cache>/<key> returning the parsed body; mapRemove → DELETE /<cache>/<key>; mapKeys → GET /<cache>/keys returning an array; mapSize → GET /<cache>/count coerced to a number. getMap caches handles by name (a === b, a.name === 'sessions'). 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 Oracle Coherence 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