MemcachedStore

MemcachedStore Overview Memcached is a distributed in-memory key-value cache. It has no query language, no secondary indexes and no persistence, so it does not fit this ORM's SQL-shaped Dialect interface. Instead, MemcachedStore implements the minimal NoSqlStore marker interface (connection lifecycle plus a getClient() escape hatch) and exposes Memcached's real operations (set/get/delete/add/replace/increment/decrement/flush) as a typed, promise-based API. Key facts (from src/nosql/memcached/index.ts): Class: MemcachedStore implements NoSqlStore name = 'memcached' library = 'memjs' Driver: memjs, lazily loaded via require('memjs') inside connect(). Importing this module never requires memjs to be installed unless a store is actually connected. An already-built client may be injected via the client constructor option, which skips the lazy require('memjs') entirely (used by tests to inject a mock, and by callers who manage the client themselves). Connection Real connection The constructor accepts MemcachedStoreOptions: All constructor options are optional; new MemcachedStore() is valid and lets memjs fall back to its own defaults. Injected client Supply a pre-built client to bypass the lazy require('memjs') — the store uses it as-is: Connection behavior connect() is idempotent: if already connected with a live client, it returns immediately. Failures during connect are wrapped in a ConnectionError (database: 'memcached'). An ECONNREFUSED error is reported as 'Connection refused'; other errors as Unable to connect to Memcached: .... Calling any operation (or getClient()) before connect() throws a ConnectionError with message 'Not connected to Memcached'. Methods Lifecycle connect() — Loads/uses the client as described above and marks the store connected. Idempotent. disconnect() — Closes the underlying client. Prefers the client's close(); if absent, falls back to quit(). Then clears the client and marks the store disconnected. quit() — Alias for disconnect(), mirroring memjs's own quit()/close() naming. isConnected() — Returns true only when connected and the client is non-null. getClient() — Returns the underlying memjs client for anything not wrapped here. Throws ConnectionError if not connected. Value serialization and decoding Writes (set/add/replace): strings and Buffers are stored verbatim; every other value (numbers, booleans, objects, arrays) is JSON.stringify-ed before being sent to memjs. For example set('n', 42) stores the string '42', and set('obj', { a: 1 }) stores '{"a":1}'. Reads (get): by default returns the raw Buffer exactly as memjs read it. Pass { decode } to decode: - 'buffer' (default): the raw Buffer. - 'string': value.toString('utf8'). - 'json': JSON.parse(value.toString('utf8')) — the inverse of the automatic JSON serialization that writes apply. Write options are the per-operation MemcachedWriteOptions, forwarded unchanged to memjs (e.g. expires, a TTL in seconds where 0 means never expire): Key-value operations Store value under key, overwriting any existing value. Serializes non-string/ Buffer values to JSON. Returns memjs's boolean success flag. Errors are wrapped in DatabaseError (Memcached SET failed: ...). Read key. Returns null if the key is missing (either memjs returns no result, or its value is null/undefined). Otherwise returns the value decoded per options.decode (raw Buffer by default). Errors wrapped as Memcached GET failed: .... Delete key. Returns memjs's boolean success flag. Errors wrapped as Memcached DELETE failed: .... Store value under key only if the key does not already exist (Memcached add). Returns false if the key was already present. Serializes like set. Errors wrapped as Memcached ADD failed: .... Store value under key only if the key already exists (Memcached replace). Returns false if the key was missing. Serializes like set. Errors wrapped as Memcached REPLACE failed: .... Atomically increment the numeric value at key by amount. Returns memjs's { value, success } result. Errors wrapped as Memcached INCREMENT failed: .... Atomically decrement the numeric value at key by amount. Returns memjs's { value, success } result. Errors wrapped as Memcached DECREMENT failed: .... Flush (delete) all keys across every configured server. Returns memjs's raw result. Errors wrapped as Memcached FLUSH failed: .... All operations require a live connection; calling one before connect() throws ConnectionError. Example Verification status Unit / mock-verified only. The tests in tests/nosql/memcached.test.ts are pure unit tests: a mock memjs client (plain jest spies) is injected via the client constructor option, so the store never loads the real memjs driver and never touches the network. memjs is not installed as a hard dependency. The tests assert that each method routes to the correct memjs call with correctly serialized arguments, and cover: name/library reporting, isConnected(), injected-client use, idempotent connect(), disconnect()/quit() via close(), pre-connect ConnectionErrors, string/Buffer/object/number serialization on set, all three get decode modes plus null-handling, delete, add/replace with option forwarding, increment/decrement results, and flush. No integration test against a real Memcached server is included, so real-network behavior (actual TTL expiry, server-side atomicity, multi-server flush) is not verified here. Related reading All data stores — the full catalogue, grouped by purpose Database types — where this sits among the 22 categories