`iomem`

npm version NPM license npm downloads

Memcached client implementing binary protocol with native multiple keys support.

Features

Binary Memcached protocol implementation
Multiple keys support aka multi-get, multi-set, multi-del, etc..
Async interface
Streams interface
Hashring aka consistent hashing
Failover servers with dynamic swap
Built-in serializer and deserializer
SASL auth with username and password

Installation

yarn add iomem

npm install iomem

Usage

The constructor accepts two optional arguments - servers list and config options.

const Mem = require('iomem')
const iomem = new Mem(['127.0.0.1:11211'], { timeout: 500, retries: 2 })
...

The first argument also accepts a string when you have only one server.

See Custom servers and Options for more details.

Basic usage

const Mem = require('iomem')
const iomem = new Mem()

await iomem.set('test:key', 'hello')
const value = await iomem.get('test:key')

console.log(value)

iomem.end() // call end() when your script or web server exits

Multi-get, multi-set, multi-del, etc..

const Mem = require('iomem')
const iomem = new Mem()

// set the same value for multiple keys
await iomem.set(['test:key1', 'test:key2'], 'test')

// set different values with `key => value` object
await iomem.setk({ 'test:key1': 'hello', 'test:key2': 'world' })

// get values as an array
await iomem.get(['test:key1', 'test:key2'])

// get values as a `key => value` object
await iomem.getk(['test:key1', 'test:key2'])

// delete keys 
await iomem.del(['test:key1', 'test:key2'])

...

iomem.end() // call end() when your script or web server exits

For more details please see Commands section.

Options

{
  stream: false, // set true to force client methods return streams instead of promises
  expiry: 60 * 60 * 24 * 1, // 1 day, time interval in seconds
  maxConnections: 10, // max connections per server
  connectionTimeout: 1000, // connection timeout in milliseconds
  timeout: 500, // request timeout in milliseconds
  retries: 2, // request retries - max retries
  retriesDelay: 100, // request retries - initial delay
  retriesFactor: 2, // request retries - exponential factor
  maxFailures: 10, // max server failures to swap server with a failover server
  failoverServers: [], // failover servers list
  keepAliveInitialDelay: 0 // initial delay in milliseconds for keep-alive functionality
}

Please take a look at Case #2 for a better approach before enabling stream flag.

Custom servers

const Mem = require('iomem')
const iomem = new Mem(['127.0.0.1:11211', '127.0.0.2:11211'])
...
iomem.end() // call end() when your script or web server exits

Supported address formats:

// host
or
// host:port
or
// username:password@host:port
or
// username:password@host
or
// /path/to/memcached.sock

Commands

Please note that the library automatically performs value serialization and deserialization. Here is a list of the possible value types:

Be aware that any value in the below commands list refers to a value of any type specified above.

The following data types for key and expiry must be ensured by the library user:

key: string - storage key, 250 bytes max as defined in Memcached

expiry: unsigned integer - time interval in seconds, defaults to expiry from the config options.

For more details please see Memcached commands.

GET

get(key): value|null - get a value for a single key.

get([key1, ...]): [value, ...] - get an array of values for multiple keys.

getk(key): {key: value}|null - get a key => value object for a single key.

getk([key1, ...]): {key: value, ...} - get a key => value object for multiple keys.

gets(key): cas|null - get cas for a single key.

gets([key1, ...]): {key: cas, ...} - get a key => cas object for multiple keys.

getsv(key): {value, cas}|null - get cas and value for a single key.

getsv([key1, ...]): {key: {value, cas}}, ...} - get a key => { value, cas } object for multiple keys.

SET

Set methods return true when all values were successfully set. Otherwise, when client receives 0x0001 or 0x0002 statuses from Memcached (this is abnormal behavior for set commands), the returned value will be false.

set(key, value, expiry): true|false - set a value for a single key.

set([key1, ...], value, expiry): true|false - set the same value for multiple keys.

setk({key: value, ...}, expiry): true|false - set multiple values with key => value object.

ADD

Add commands set a key only when it is not set yet (a key does not exist in the Memcached). The methods will return false when at least one key was not successfully set (meaning a key was already set with some value, so it was not set with the value you provided with a command).

add(key, value, expiry): true|false - add a value for a single key.

add([key1, ...], value, expiry): true|false - add the same value for multiple keys.

addk({key: value, ...}, expiry): true|false - add multiple values with key => value object.

REPLACE

Replace commands set a new value for a key only when it is already set with some value (a key does exist in the Memcached). The methods will return false when at least one key was not successfully set (meaning a key did not exist in the Memcached when you ran a command).

replace(key, value, expiry): true|false - replace a value for a single key.

replace([key1, ...], value, expiry): true|false - replace the same value for multiple keys.

replacek({key: value, ...}, expiry): true|false - replace multiple values with key => value object.

CAS

The cas command sets a key with a new value only when cas parameter matches cas value stored in a key. To retrieve the current cas value for a key please see GET commands.

cas(key, value, cas, expiry): true|false - set a value if the cas matches.

DEL

Delete commands delete a key only when it exists. The methods will return false when at least one key does not exist.

del(key): true|false - delete a key.

del([key1, ...]): true|false - delete multiple keys.

INCERMENT AND DECREMENT

Increment and decrement commands will add or substract the specified delta value from the current counter value initialized with initial value. You can use SET, ADD, REPLACE commands to set a counter value.

incr(key, initial, delta, expiry): value|null - increment counter and returns its value.

incr([key1, ...], initial, delta, expiry): [value, ...] - increment counter and returns its value for multiple keys.

decr(key, initial, delta, expiry): value|null - decrement counter and returns its value.

decr([key1, ...], initial, delta, expiry): [value, ...] - decrement counter and returns its value for multiple keys.

Parameters:

initial: BigInt - initial counter value

delta: BigInt - amount to add or substruct from a counter

expiry - see Commands

If you want to get the current value from a counter without changing its value, use GET commands and manually deserialize the response buffer.

...
const FLAGS = require('iomem/src/flags')
const { deserialize } = require('iomem/src/serializer')

deserialize(await iomem.get('test:foo'), FLAGS.bigint)
...

FLUSH, QUIT, NOOP, VERSION

NOTE: all the following commands will make request only to active servers. This meaning if you have servers A, B, and C and failover server D the request will be performed on servers A, B, and C, but if you have server B failed and so replaced with failover server D, then the request will be performed on servers A, D, and C.

flush() - flush cached items on all servers.

flush(expiry) - flush cached items on all servers in expiry seconds.

quit() - closes connection that query hits (either existing or a new one) on all servers. Useless in multi-connection and multi-server environment.

noop() - sends empty packet to all servers and returns true on success, may be useful for pinging.

version(): {<hostname>: <version>, ...} - get Memcached version string from all servers and return hostname => version object.

APPEND AND PREPEND

Append and prepend commands either append or prepend a string value to an existing value stored by a key.

Append methods

append(key, value): true|false - append value to a stored value

append([key1, ...], value): true|false - append value to a stored value for multiple keys

appends(key, value): cas|null - append value and return new cas.

appends([key1, ...], value): [cas1, ...] - append value to multiple keys and return cas array.

appendk({key: value, ...}): true|false - append by key => value pairs.

appendks({key: value, ...}): [cas1, ...] - append by key => value pairs and return cas array.

Prepend methods

prepend(key, value): true|false - prepend value to a stored value

prepend([key1, ...], value): true|false - prepend value to a stored value for multiple keys

prepends(key, value): cas|null - prepend value and return new cas.

prepends([key1, ...], value): [cas1, ...] - prepend value to multiple keys and return cas array.

prependk({key: value, ...}): true|false - prepend by key => value object.

prependks({key: value, ...}): [cas1, ...] - prepend by key => value object and return cas arra

Iomem

Install / Use

README