Node.js Memcached Client

Common errors

• Error: spawn zstd ENOENT

  cause 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'.

  cause 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

  cause 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.

Warnings

• gotcha Enabling 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.
• gotcha When 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.
• gotcha By 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.

Install

• npm install memcache-client npm
• yarn add memcache-client yarn
• pnpm add memcache-client pnpm

Imports

• MemcacheClient
  wrong:

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

  correct:

  import { MemcacheClient } from 'memcache-client';

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

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

  correct:

  import { MultiRetrievalResponse } from '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)
  wrong:

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

  correct:

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

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

Quickstart

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();