HazelcastStore — Hazelcast distributed in-memory data grid

HazelcastStore — Hazelcast distributed in-memory data grid Overview Hazelcast is a distributed in-memory data grid (IMDG). Its central data structure is the distributed IMap — a partitioned, replicated key/value map spread across cluster members. There is no SQL-shaped query(sql) surface for this key/value access pattern, so HazelcastStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes Hazelcast's distributed-map operations (getMap/put/get/remove/keySet/size) as a typed, promise-based API. Identity: Property | Value | --------- | -------------------- | name | 'hazelcast' | library | 'hazelcast-client' | The store is built on the hazelcast-client npm driver (the official Node.js client). It connects to the cluster via Client.newHazelcastClient(config). Lazy loading — not a hard dependency hazelcast-client is not a hard dependency of this package. The driver is loaded lazily via require() inside connect(), rather than a top-level import. Importing this module therefore does not require the driver to be installed — it is only needed when a Hazelcast store is actually connected. Injected client HazelcastStoreOptions accepts a pre-built client (any object implementing HazelcastClientLike — getMap(name) plus shutdown()). When provided, connect() uses it directly and skips require('hazelcast-client'). This is how the test suite injects a mock client (no driver, no network), and how callers can supply a custom-configured Client. Connection Build a store from connection options and call connect(): Connection options (all optional): Option | Type | Purpose | -------- | -------------------------- | -------------------------------------------------------------------------------------------------------------- | config | Record<string, unknown> | Hazelcast client config passed straight through to Client.newHazelcastClient(config) (cluster name, network member addresses, etc.). Ignored when a pre-built client is supplied. | client | HazelcastClientLike | A pre-built client to use directly (mock or custom config). When set, the driver is not required. | Injected-client form Supply your own client (or a mock) to bypass driver-based client construction: Methods Driver 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 HazelcastMap handle (from getMap) as their first argument. Lifecycle Method | Signature | Behavior | ------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise lazy-requires hazelcast-client and builds a client via Client.newHazelcastClient(config). Idempotent. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | Best-effort client.shutdown(), clears the cached map handles, and resets connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): HazelcastClientLike | Returns the underlying client for operations not wrapped here. Throws ConnectionError if not connected. | Distributed map (IMap) operations Method | Signature | Behavior | ----------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | getMap | getMap(name: string): Promise<HazelcastMap> | Resolves a distributed IMap handle by name via client.getMap(name). Handles are cached by name so repeat calls are idempotent. | mapPut | mapPut(map: HazelcastMap, key: unknown, value: unknown): Promise<unknown> | Puts value under key, returning the previous value (or null). Routes to map.put. | mapGet | mapGet(map: HazelcastMap, key: unknown): Promise<unknown> | Gets the value stored under key (or null if absent). Routes to map.get. | mapRemove | mapRemove(map: HazelcastMap, key: unknown): Promise<unknown> | Removes key, returning the removed value (or null). Routes to map.remove. | mapKeys | mapKeys(map: HazelcastMap): Promise<unknown[]> | Returns all keys currently in the map as an array. Routes to map.keySet. | mapSize | mapSize(map: HazelcastMap): Promise<number> | Returns the number of entries in the map. Routes to map.size. | Example Verification status Unit / mock-verified only. The tests in tests/nosql/hazelcast.test.ts are fully mock-driven: a fake hazelcast-client client (plain jest spies for getMap/shutdown and an IMap with put/get/remove/keySet/size) is injected via HazelcastStoreOptions.client, so the store never loads the real hazelcast-client driver and never touches the network. What this proves: name/library identity, and that the injected client is used without requiring hazelcast-client. Each method routes to the correct IMap call (mapPut → put, mapGet → get, mapRemove → remove, mapKeys → keySet, mapSize → size) and returns the shaped result. getMap caches handles by name (idempotent — a repeated call does not re-invoke client.getMap). Lifecycle: idempotent connect, disconnect() calling shutdown(), and ConnectionError from getClient() / getMap() before connect(). Error handling: driver failures wrapped in DatabaseError. What this does not prove: live execution against a real Hazelcast cluster. The call routing is verified against the driver's documented IMap contract, 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