MomentoStore — Momento Cache (serverless cache)

MomentoStore — Momento Cache (serverless cache) Overview Momento is a serverless, globally-available cache accessed through the @gomomento/sdk CacheClient. Every operation is scoped to a named cache. Momento has no SQL surface and — importantly — no arbitrary key enumeration, so MomentoStore implements the minimal NoSqlStore marker interface (src/nosql/store.ts) — connection lifecycle plus a getClient() escape hatch — and exposes an edge-KV get/set/del/list/incr surface mapped onto the Momento client. Identity: Property | Value | --------- | ----------------- | name | 'momento' | library | '@gomomento/sdk'| Driver — lazy-loaded Uses @gomomento/sdk (CacheClient). The driver is not a hard dependency: it is loaded lazily via require('@gomomento/sdk') inside connect() (resolving mod.CacheClient ?? mod.default?.CacheClient ?? mod.default), so importing this module never requires @gomomento/sdk to be installed unless a store is actually connected. Injected client MomentoStoreOptions accepts a pre-built client implementing the MomentoCacheClient interface. When provided, connect() uses it directly and skips require('@gomomento/sdk'). This is how the test suite injects a method-spy mock (no driver, no network). Values are serialized before writing: strings are stored verbatim; every other value is JSON.stringify'd. List semantics — list() is not a key scan Momento cannot enumerate cache keys. This store's list() therefore does not list keys — it fetches the elements of a Momento list data structure via listFetch(cacheName, listName). The argument names a list (defaulting to defaultListName), not a key prefix. This is a deliberate divergence from the other edge-KV stores, whose list() returns key names. Connection Build a store from connection options and call connect(): Connection options: Option | Type | Purpose | ------------------- | --------------------- | ------------------------------------------------------------------------------ | cacheName | string | Name of the Momento cache every operation targets (required). | defaultListName | string | Default list name used by list() when none is passed. | configuration | unknown | Momento SDK Configuration (used only when building a real client). | credentialProvider| unknown | Momento CredentialProvider (used only when building a real client). | defaultTtlSeconds | number | Default TTL (seconds) for the constructed client. | client | MomentoCacheClient | Pre-built CacheClient; when set, connect() uses it and skips require. | All options are optional (MomentoStoreOptions = {}); cacheName is required for operations to target a cache (it falls back to '' when unset). Injected-client form Methods Each operation routes to the corresponding CacheClient method, passing the configured cacheName as the first argument. Driver failures are wrapped in a DatabaseError; using any method before connect() (or after disconnect()) throws a ConnectionError. Lifecycle Method | Signature | Behavior | ------------- | ---------------------------------- | -------------------------------------------------------------------------------------------------- | connect | connect(): Promise<void> | Uses an injected client if provided, otherwise lazy-requires @gomomento/sdk and builds a CacheClient. Idempotent. Wraps failures in ConnectionError. | disconnect | disconnect(): Promise<void> | Clears the client and connection state. | isConnected | isConnected(): boolean | true only when connected and a client is present. | getClient | getClient(): MomentoCacheClient | Returns the underlying Momento CacheClient. Throws ConnectionError if not connected. | Key-value operations Each returns the raw Momento response object (e.g. { type: 'Hit', value }, { type: 'Success' }) rather than a normalized value. Method | Signature | Client call | Behavior | ------- | --------------------------------------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------- | get | get(key: string): Promise<any> | client.get(cacheName, key) | Reads a key from the configured cache. Returns the Momento response object. | set | set(key: string, value: unknown, options?: MomentoSetOptions): Promise<any> | client.set(cacheName, key, value, opts?) | Writes value (serialized). options.ttl sets a per-item TTL in seconds ({ ttl }); passes undefined when no TTL. | del | del(key: string): Promise<any> | client.delete(cacheName, key) | Deletes a key from the configured cache. | list | list(listName?: string): Promise<any> | client.listFetch(cacheName, listName) | Fetches the elements of a Momento list, not cache keys. listName defaults to defaultListName. | incr | incr(key: string, by?: number): Promise<any> | client.increment(cacheName, key, by) | Atomically increments the value at key by by (default 1). | MomentoSetOptions Example Verification status Unit / mock-verified only. The tests in tests/nosql/momento.test.ts inject a method-spy mock MomentoCacheClient (get/set/delete/increment/listFetch) via MomentoStoreOptions.client. The real @gomomento/sdk package is not installed and there is no network in the test run. What this proves: Each method routes to the correct client method with the cache name and key: get('cache', 'k'), delete('cache', 'k'), increment('cache', 'c', 3) (and increment('cache', 'c', 1) for the default). set serializes non-strings ({ a: 1 } → '{"a":1}'), stores strings verbatim, and maps ttl → { ttl: 30 } (passing undefined when no TTL). list() calls listFetch(cacheName, listName), defaulting to defaultListName ('mylist') and honoring an explicit list name. Lifecycle: connect/idempotent-connect/disconnect, getClient returning the injected client, and ConnectionError before connect(). Error handling: driver failures wrapped in DatabaseError. What this does not prove: live execution against a real Momento cache. The method/argument mapping is verified against the @gomomento/sdk documented CacheClient surface, 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