IgniteStore — Apache Ignite distributed in-memory data grid

IgniteStore — Apache Ignite distributed in-memory data grid Overview Apache Ignite is a distributed in-memory data grid / database. Data lives in distributed key/value caches partitioned across cluster nodes, accessed here via Ignite's thin-client protocol. Although Ignite also speaks SQL, this store targets its distributed-cache (key/value grid) surface, which does not fit the SQL-shaped Dialect interface — so IgniteStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes cache operations (getCache/put/get/removeKey/getKeys/getSize) as a typed, promise-based API. Identity: Property | Value | --------- | ------------------------ | name | 'ignite' | library | 'apache-ignite-client' | The store is built on the apache-ignite-client npm driver (the official Node.js thin client). It connects via new IgniteClient() + client.connect(new IgniteClientConfiguration(...endpoints)). Lazy loading — not a hard dependency apache-ignite-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 an Ignite store is actually connected. Injected client IgniteStoreOptions accepts a pre-built client (any object implementing IgniteClientLike — connect/disconnect/getCache). When provided, connect() uses it directly and skips require('apache-ignite-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 | ----------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------- | endpoints | string[] | One or more host:port thin-client endpoints (default ['127.0.0.1:10800']). Spread into new IgniteClientConfiguration(...). Ignored when a pre-built client is supplied. | client | IgniteClientLike | 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 IgniteCache handle (from getMap) as their first argument. Note the store's common surface names its resolver getMap even though it returns an Ignite cache handle. Lifecycle Method | Signature | Behavior | ------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise lazy-requires apache-ignite-client, builds new IgniteClient(), and calls client.connect(new IgniteClientConfiguration(...endpoints)). Idempotent. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | Best-effort client.disconnect(), clears the cached cache handles, and resets connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): IgniteClientLike | Returns the underlying client for operations not wrapped here. Throws ConnectionError if not connected. | Distributed cache operations Method | Signature | Behavior | ----------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | getMap | getMap(name: string): Promise<IgniteCache> | Resolves a distributed cache handle by name via client.getCache(name). Handles are cached by name so repeat calls are idempotent. | mapPut | mapPut(map: IgniteCache, key: unknown, value: unknown): Promise<unknown> | Puts value under key. Routes to cache.put. | mapGet | mapGet(map: IgniteCache, key: unknown): Promise<unknown> | Gets the value stored under key (or null if absent). Routes to cache.get. | mapRemove | mapRemove(map: IgniteCache, key: unknown): Promise<boolean> | Removes key, returning Ignite's boolean success flag. Routes to cache.removeKey. | mapKeys | mapKeys(map: IgniteCache): Promise<unknown[]> | Returns all keys currently in the cache as an array. Routes to cache.getKeys. | mapSize | mapSize(map: IgniteCache): Promise<number> | Returns the number of entries in the cache. Routes to cache.getSize. | Example Verification status Unit / mock-verified only. The tests in tests/nosql/ignite.test.ts are fully mock-driven: a fake apache-ignite-client client (plain jest spies for getCache/disconnect and a cache with put/get/removeKey/getKeys/getSize) is injected via IgniteStoreOptions.client, so the store never loads the real driver and never touches the network. What this proves: name/library identity, and that the injected client is used without requiring apache-ignite-client. Each method routes to the correct cache call (mapPut → put, mapGet → get, mapRemove → removeKey returning the boolean, mapKeys → getKeys, mapSize → getSize) and returns the shaped result. getMap caches handles by name (idempotent — a repeated call does not re-invoke client.getCache). Lifecycle: idempotent connect, disconnect() calling disconnect(), and ConnectionError from getClient() / getMap() before connect(). Error handling: driver failures wrapped in DatabaseError. What this does not prove: live execution against a real Apache Ignite cluster. The call routing is verified against the thin-client driver's documented cache 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