memcache-client

library1.0.5jsnpmunverified

memcache-client is a high-performance Node.js client designed for interacting with Memcached servers, focusing on efficient ASCII protocol parsing through direct Node.js Buffer APIs. Originally developed and heavily used at WalmartLabs for powering the walmart.com e-commerce platform, it offers robust features crucial for large-scale applications. These include optional data compression, automatic reconnection on network errors, support for arbitrary Memcached commands, and the ability to store various data types like Buffer, string, numeric, and JSON. The library provides a flexible API supporting both traditional Node.js callbacks and modern Promise-based operations, alongside features like fire-and-forget requests, multiple connections, and TLS support. It is currently at version 1.0.5 and appears to be in a maintenance or stable release state, with a focus on reliability and performance in demanding environments.

database

npm install memcache-client

github ↗package ↗

INSTALL

IMPORT

SIG · MEMCACHE-CLIENT

memcache-client

databasejavascriptv1.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

MemcacheClient

✓ import { MemcacheClient } from 'memcache-client';

✗ const MemcacheClient = require('memcache-client').MemcacheClient;

The package is primarily designed for ES Modules. When using CommonJS `require`, access `MemcacheClient` as a named export.

MultiRetrievalResponse

✓ import { MultiRetrievalResponse } from 'memcache-client';

✗ const { MultiRetrievalResponse } = require('memcache-client');

This is a TypeScript type helper, essential for correctly typing results from multi-key `get` or `gets` operations to avoid `unknown` types. It's an ESM named export.

client.set (Promise)

✓ client.set('key', 'data').then((r) => console.log(r));

✗ client.set('key', 'data'); // Fire and forget without handling result or error

Methods support both Promise-based and callback-based usage. For reliability, always handle the Promise resolution or callback result.

This quickstart demonstrates creating a MemcacheClient, setting and retrieving single keys using Promises, concurrently setting multiple keys, and performing a typed multi-key retrieval. It also shows an example of using a callback for deletion.

import { MemcacheClient, MultiRetrievalResponse } from 'memcache-client'; import assert from 'node:assert'; const server = 'localhost:11211'; // Create a client with default settings (maxConnections = 1) const client = new MemcacheClient({ server }); async function runMemcacheExample() { try { // Set a key-value pair using Promises const setResult = await client.set('myKey', 'myValue'); assert.deepEqual(setResult, ['STORED']); console.log('Set "myKey":', setResult); // Get the value of 'myKey' using Promises, with type assertion const getData = await client.get<string>('myKey'); assert.equal(getData?.value, 'myValue'); console.log('Got "myKey":', getData?.value); // Set multiple keys concurrently await Promise.all([ client.set('key1', 'data1'), client.set('key2', 'data2') ]); console.log('Set "key1" and "key2".'); // Get multiple keys with correct TypeScript typing const multiResults = await client.get<MultiRetrievalResponse<string>>(['key1', 'key2']); assert.equal(multiResults['key1'].value, 'data1'); assert.equal(multiResults['key2'].value, 'data2'); console.log('Got multiple keys:', multiResults); // Example with callback for 'delete' (optional pattern) client.delete('myKey', (err, result) => { if (err) { console.error('Delete error:', err); } else { assert.deepEqual(result, ['DELETED']); console.log('Deleted "myKey":', result); } }); } catch (error) { console.error('An error occurred:', error); } finally { // It's good practice to close connections if not needed anymore, though auto-reconnect handles many cases // client.disconnect(); // (Assuming a disconnect method exists or client handles it internally) } } runMemcacheExample();

Debug

Known issues

gotchaEnabling compression features (e.g., `compress: true` in `set` options) requires the `zstd` executable to be installed and available in the system's PATH. If `zstd` is not found, compression will fail, potentially leading to errors or unexpected behavior.

fix

Install `zstd` on your operating system (e.g., `sudo apt install zstd` on Debian/Ubuntu, `brew install zstd` on macOS) or avoid using the compression option.

affects: >=1.0.0

gotchaWhen retrieving multiple keys using methods like `client.get(['key1', 'key2'])` or `client.gets(['key1', 'key2'])` in TypeScript, it is crucial to apply the `MultiRetrievalResponse` or `MultiCasRetrievalResponse` generic type. Failing to do so will result in `unknown` types for the retrieved values, diminishing type safety.

fix

Use `client.get<MultiRetrievalResponse<YourValueType>>(['key1', 'key2'])` to ensure correct type inference for the returned object.

affects: >=1.0.0

gotchaBy default, the client does not ignore `NOT_STORED` responses from the Memcached server. If integrating with specific Memcached proxy configurations, such as McRouter in AllAsync mode, you might need to instantiate `MemcacheClient` with `{ ignoreNotStored: true }` to prevent these responses from being treated as errors.

fix

When creating the client, pass `{ server: 'localhost:11211', ignoreNotStored: true }` in the options object.

affects: >=1.0.0

Errors

Common errors & fixes

Error: spawn zstd ENOENT

The `zstd` executable is not found in the system's PATH when compression is enabled for data storage.

fix

Install the `zstd` command-line utility on your operating system (e.g., `sudo apt install zstd` or `brew install zstd`). Ensure it's accessible in the environment where your Node.js application runs.

Property 'value' does not exist on type 'unknown'.

Attempting to access properties like `value` on results from `get` or `gets` operations when TypeScript cannot infer the type, typically during multi-key retrievals without using `MultiRetrievalResponse`.

fix

For single-key `get`, use a generic: `client.get<string>('key')`. For multi-key `get` or `gets`, use the appropriate type helper: `client.get<MultiRetrievalResponse<string>>(['key1', 'key2'])`.

TypeError: MemcacheClient is not a constructor

This error often occurs when attempting to use CommonJS `require()` to import an ES Module (ESM) package incorrectly, or when the `MemcacheClient` class is not directly exported as a default.

fix

If using CommonJS, ensure you're destructuring the named export: `const { MemcacheClient } = require('memcache-client');`. For new projects, it is recommended to use ESM `import { MemcacheClient } from 'memcache-client';` in a `type: "module"` Node.js environment.

Upgrade

Version history

1.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

9 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/electrode-io/memcache ↗

packagehttps://www.npmjs.com/package/memcache-client ↗