memcached-node

A Promise-base Memcached client library for Node.js written in Typescript

Table of contents

• Install
• Setting up the client
• Pooling connections vs Single connection
  • Serialize・Deserialize
  • 0. String
  • 1. JSON
  • Options
    • MemcachedOptions: Options for Memcached
    • ConnectionOptions: Options for each connection
• API
  • Methods
    • Memcached
      • .createPool: Generates connections for the given server(s).
      • .createConnection: Generates a connection for given server(s).
      • .clean: Close all connections in the pool
      • .getConnection: Get an idle connection
    • Connection
      • .connect: Generates connection for the given servers(s).
      • .close: Close the connection
      • .isReady: Check if the connection is ready to execute commands
    • .remove: Remove a server for the connection
  • Commands
    • Storage commmands
      • {memcached,connection}.set: Store the data
      • {memcached,connection}.add: Store the data only if the server doesn't already hold data for this key
      • {memcached,connection}.replace: Store the data only if the server does hold data for this key
      • {memcached,connection}.append: Add the data to existing key after existing data
      • {memcached,connection}.prepend: Add the data to existing key before existing data
      • {memcached,connection}.cas: Store the data only if no one elese has updated since I last fetched it
    • Retrieval commands
      • {memcached,connection}.get: Get value for key(s)
      • {memcached,connection}.gets: Get value for key(s) using CAS
    • Deletion
      • {memcached,connection}.delete: Delete the item by key
    • Touch
      • {memcached,connection}.touch: Update the expiration time of an exisiting item
    • Get and Touch
      • {memcached,connection}.gat: Get value for key(s) and update the expiration time
      • {memcached,connection}.gats: Get value for key(s) and update the expiration time using CAS
    • Stats
      • {memcached,connection}.stats: Get the stats from your servers
• Event listening
  • Memcached
    • close: When a connection is closed
    • drop: When a server in the connection is closed
    • maxConnection: When the number of the connections in the connection pool reaches to poolsize
  • Connection
    • close: When all server is droped is closed
    • drop: When a server in the connection is removed
• Authentication
• Contribution
• Author
• LICENSE
• Other libraries
• Futher readings

Install

$ npm install memcached-node

or

$ yarn add memcached-node

Setting up the client

import {Memcached} from 'memcached-node'

let memcached = new Memcached('localhost:11211')

You can either use these types for configuring the servers.

1. String: For single running instance.
2. Array: For cluster of Memcached servers.
3. Object: For cluster of Memcached servers with user options. See details of the Options for detail.

// 1. String
let memcached = new Memcached('localhost:11211')

// 2. Array
let memcached = new Memcached(['localhost:11211', 'localhost:11212'])

// 3. Object
let memcached = new Memcached({
    'localhost:11211': 200,
    'localhost:11212': {
        weight: 200
    },
    'localhost: 11213': {
        vnode: 400,
        timeout: 300
    }
})

Pooling connections vs Single connection

You can use either connection pool or connection.

let memcached = new Memcached('localhost:11211')
await memcached.createPool()
await memcached.get('keke')

// or use single connection

let connection = Memcached.createConnection('localhost:11211')
await connection.connect()
await connection.get('keke')

Because the connection will take cost, I recommend to use the connection pool and share the connection between clients. Each time, you run a command by Memcached method, it will grab a idle connection and release it after the command is done.

Serialize・Deserialize

You can use raw string inputs(default) or 3 ways to serialize・deserialize.

0. String

const resp = await connection.set("key", "value")

1. JSON

const json = {
  value: "hello"
}

const resp = await connection.set("key", json, {mode:"json"})

Options

MemcachedOptions: Options for Memcached

• initSize: 1, the size of the init connection.
• poolSize: 10, maximun size of the connection pool.
• removeDeadServer: true, remove if the server is dead or closed.
• wait: false, if wait to get connection available.
• waitTimeout: 1000, the time to wait for available connection.

ConnectionOptions: Options for each connection

• basicAuth: undefined, username/password authentication. See the details in Authentication section.
• timeout: 3000, the time after which Memcached sends a connection timeout(in milliseconds).
• vnode: undefined, Virtual node in the hashring.
• weight: undefined, the weight of the node in the hashring.

API

Methods

These are essential methods that you should know when operating with memcached.

Memcached

.createPool: Generates connections for the given server(s).

Connect to the servers given when instanting.

await memcached.createPool()

.createConnection: Generates a connection for given server(s).

let connection = await memcached.createConnection()

If you want to create a connection directly without using the connection pool, use Connection.createConnection().

.clean: Close all connections in the pool

Close all connections to the given servers.

memcached.clean()

.getConnection: Get an idle connection

let connection = memcached.getConnection()

Don't forget to .close() your connection after you finish your execution.

Connection

.connect: Generates connection for the given servers(s).

await connection.connect()

.close: Close the connection

connection.close()

.isReady: Check if the connection is ready to execute commands

let isReady = connection.isReady()

.remove: Remove a server for the connection

connection.remove('localhost:11211')

Commands

These are API's that both Memcached and Connection uses.

Storage commmands

These are command to store an item. Replace memcached to connection if you are running the method on a connection.

{memcached,connection}.set: Store the data

let resp = await memcached.set('keke', 'pupu')

Also you can pass these arguments too.

• Compressed: boolean.
• Expiration time: number.

{memcached,connection}.add: Store the data only if the server doesn't already hold data for this key

let resp = await memcached.add('keke', 'pupu')

Also you can pass these arguments too.

• Compressed: boolean.
• Expiration time: number.

{memcached,connection}.replace: Store the data only if the server does hold data for this key

let resp = await memcached.replace('keke', 'pupu')

Also you can pass these arguments too.

• Compressed: boolean.
• Expiration time: number.

{memcached,connection}.append: Add the data to existing key after existing data

let resp = await memcached.append('keke', 'pupu')

Also you can pass these arguments too.

• Compressed: boolean.
• Expiration time: number.

{memcached,connection}.prepend: Add the data to existing key before existing data

let resp = await memcached.prepend('keke', 'pupu')

Also you can pass these arguments too.

• Compressed: boolean.
• Expiration time: number.

{memcached,connection}.cas: Store the data only if no one elese has updated since I last fetched it

let resp = await memcached.cas('keke', 'id')

Also you can pass these arguments too.

• Compressed: boolean.
• Expiration time: number.

Retrieval commands

These are command to restrieve an item.

{memcached,connection}.get: Get value for key(s)

var resp = await memcached.get('hoge')
var resp = await memcached.get(['hoge'])

{memcached,connection}.gets: Get value for key(s) using CAS

var resp = await memcached.gets('hoge')
var resp = await memcached.gets(['hoge'])

Deletion

{memcached,connection}.delete: Delete the item by key

let resp = await memcached.delete(['hoge'])

Touch

{memcached,connection}.touch: Update the expiration time of an exisiting item

let resp = await memcached.touch(['hoge'])

Also you can pass these arguments too.

• Expiration time: number.

Get and Touch

{memcached,connection}.gat: Get value for key(s) and update the expiration time

let resp = await memcached.gat(['hoge'])

{memcached,connection}.gats: Get value for key(s) and update the expiration time using CAS

let resp = await memcached.gats(['hoge'])

Stats

{memcached,connection}.stats: Get the stats from your servers

Get stats of your server.

let resp = await memcached.stats()

Event listening

These are useful events that will be emited when specific event happens on the connection.

Memcached

close: When a connection is closed

Emitted when a socket connecting or connection has an error.

Arguments:

• Connection: the connection which closed in the connection pool
• Server: the server which droped last

memcached.on('close', (connection, server) => {
    console.log(`Connection closed: error: ${err}, url: ${server.url}`)
})

drop: When a server in the connection is closed

memcached.on('drop', (connection: Connection, server: Server) => {
  console.log(`server ${server.url} is droped`)
})

maxConnection: When the number of the connections in the connection pool reaches to poolsize

memcached.on('maxConnection', (poolsize: number) => {
  console.log(`connection reached the poolsize: ${poolsize}`)
})

Note that this event will note be triggered when memcached initialization.

Connection

close: When all server is droped is closed

connection.on('close', (connection:Connection) => {
  console.log('all server in the connection is closed')
})

drop: When a server in the connection is removed

connection.on('drop', (connection: Connection, server: Server) => {
  console.log(`server ${server.url} is droped`)
})

Authentication

Memcached supports username/password authentications. When initializing the Memcached, pass the basicAuth option.

let memcached = new Memcached({
    'localhost:11211': {
        basicAuth: {
            username: 'keke',
            password: 'piyo'
        }
    },
    'localhost:11212': {
        basicAuth: {
            username: 'keke',
            password: 'huga'
        }
    }
})

Contribution

I welcome and contribution. Please open an Issue or a Pull Request.

Creating an Issue before sending a Pull request is desirable so make sure that the implementation is surely needed. Thank you in advance.

Author

• KeisukeYamashita

LICENSE

The driver is released under the Apache 2.0 license. See the LICENSE for more information.

Other libraries

List of other memcached JS libraries(2020/04/20).

| Repository | stars | Notes |:----:|:----:|:---:| | 3rd-Eden/memcached | 1.2k | Defacto standard memcached library | | electrode-io/memcache | 21 | From Facebook | | googleapi/nodejs-memcache | 4 | From Google. Born in 2020/04/01 |

Futher readings

• memcached/protocol.txt
  • Official memcached protocol document