Node.js client for memcached
npm install memcached-node![Project status]()



[![Dependabot][dependabot-badge]][dependabot]

> A Promise-base Memcached client library for Node.js written in Typescript
- 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
``console`
$ npm install memcached-node
or
`console`
$ yarn add memcached-node
`typescript
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.
`typescript
// 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
}
})
`
You can use either connection pool or connection.
`typescript
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.
You can use raw string inputs(default) or 3 ways to serialize・deserialize.
`typescript`
const resp = await connection.set("key", "value")
`typescript
const json = {
value: "hello"
}
const resp = await connection.set("key", json, {mode:"json"})
`
#### 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.
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.
`typescript`
await memcached.createPool()
##### .createConnection: Generates a connection for given server(s).
`typescript`
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.
`typescript`
memcached.clean()
##### .getConnection: Get an idle connection
`typescript`
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).
`typescript`
await connection.connect()
##### .close: Close the connection
`typescript`
connection.close()
##### .isReady: Check if the connection is ready to execute commands
`typescript`
let isReady = connection.isReady()
#### .remove: Remove a server for the connection
`typescript`
connection.remove('localhost:11211')
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
`typescript`
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
`typescript`
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
`typescript`
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
`typescript`
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
`typescript`
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
`typescript`
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)
`typescript`
var resp = await memcached.get('hoge')
var resp = await memcached.get(['hoge'])
##### {memcached,connection}.gets: Get value for key(s) using CAS
`typescript`
var resp = await memcached.gets('hoge')
var resp = await memcached.gets(['hoge'])
#### Deletion
##### {memcached,connection}.delete: Delete the item by key
`typescript`
let resp = await memcached.delete(['hoge'])
#### Touch
##### {memcached,connection}.touch: Update the expiration time of an exisiting item
`typescript`
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
`typescript`
let resp = await memcached.gat(['hoge'])
##### {memcached,connection}.gats: Get value for key(s) and update the expiration time using CAS
`typescript`
let resp = await memcached.gats(['hoge'])
#### Stats
##### {memcached,connection}.stats: Get the stats from your servers
Get stats of your server.
`typescript`
let resp = await memcached.stats()
These are useful events that will be emited when specific event happens on the connection.
#### 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 poolServer
* : the server which droped last
`typescriptConnection closed: error: ${err}, url: ${server.url}
memcached.on('close', (connection, server) => {
console.log()`
})
#### drop: When a server in the connection is closed
`typescriptserver ${server.url} is droped
memcached.on('drop', (connection: Connection, server: Server) => {
console.log()`
})
#### maxConnection: When the number of the connections in the connection pool reaches to poolsize
`typescriptconnection reached the poolsize: ${poolsize}
memcached.on('maxConnection', (poolsize: number) => {
console.log()`
})
Note that this event will note be triggered when memcached initialization.
#### close: When all server is droped is closed
`typescript`
connection.on('close', (connection:Connection) => {
console.log('all server in the connection is closed')
})
#### drop: When a server in the connection is removed
`typescriptserver ${server.url} is droped
connection.on('drop', (connection: Connection, server: Server) => {
console.log()`
})
Memcached supports username/password authentications. When initializing the Memcached, pass the basicAuth option.
`typescript``
let memcached = new Memcached({
'localhost:11211': {
basicAuth: {
username: 'keke',
password: 'piyo'
}
},
'localhost:11212': {
basicAuth: {
username: 'keke',
password: 'huga'
}
}
})
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.
The driver is released under the Apache 2.0 license. See the LICENSE for more information.
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 |
* memcached/protocol.txt
* Official memcached protocol document
[dependabot]: https://dependabot.com
[dependabot-badge]: https://badgen.net/badge/icon/Dependabot?icon=dependabot&label&color=blue