search

KeisukeYamashita / memcached-node

A Promise-base Memcached client library for Node.js written in Typescript
Apache License 2.0
1 stars 3 forks source link
memcached typescript

readme

memcached-node

[Project status]() npm version Test Package codecov Dependabot License

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

Table of contents

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

ConnectionOptions: Options for each connection

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.

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

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

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

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

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

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.

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:

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

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