memjs
v1.3.2
Published
A memcache client for node using the binary protocol and SASL authentication
Downloads
627,985
Readme
MemJS
MemJS is a pure Node.js client library for using memcache, in particular, the MemCachier service. It uses the binary protocol and support SASL authentication.
Documentation can be found here: https://memjs.netlify.com/
TOC
Requirements
Supported Node.js versions
MemJS is tested to work with version 0.10 or higher of Node.js.
Installation
MemJS is available from the npm registry:
$ npm install memjs
To install from git:
$ git clone git://github.com/alevy/memjs.git
$ cd memjs
$ npm link
MemJS was designed for the MemCachier memcache service but will work with any memcache server that speaks the binary protocol. Many software repositories have a version of memcached available for installation:
Ubuntu
$ apt-get install memcached
OS X
$ brew install memcached
Configuration
MemJS understands the following environment variables:
MEMCACHIER_SERVERS
- used to determine which servers to connect to. Should be a comma separated list of [hostname:port].MEMCACHIER_USERNAME
- if present withMEMCACHIER_PASSWORD
, MemJS will try to authenticated to the server using SASL.MEMCACHIER_PASSWORD
- if present withMEMCACHIER_USERNAME
, MemJS will try to authenticated to the server using SASL.MEMCACHE_USERNAME
- used ifMEMCACHIER_USERNAME
is not presentMEMCACHE_PASSWORD
- used ifMEMCACHIER_PASSWORD
is not present
Environment variables are only used as a fallback for explicit parameters.
Usage
You can start using MemJS immediately from the node console:
$ var memjs = require('memjs')
$ var client = memjs.Client.create()
$ client.get('hello', function(err, val) { console.log(val); })
If callbacks are not specified, the command calls return promises.
Settings Values
client.set('hello', 'world', {expires:600}, function(err, val) {
});
The set(key, val, options, callback)
function accepts the following parameters.
key
: key to setval
: value to setoptions
: an object of options. Currently supports only the keyexpires
, which is a time interval, in seconds, after which memcached will expire the objectcallback
: a callback invoked after the value is seterr
: errorval
: value retrieved
Getting Values
client.get('hello', function(err, val) {
});
The get(key, callback)
function accepts the following parameters.
Note that values are always returned as Buffer
s, regardless of whether a
Buffer
or String
was passed to set
.
key
: key to retrievecallback
: a callback invoked after the value is retrievederr
: errorval
: value retrieved as aBuffer
Contributing
The best way to contribute to the project is by reporting bugs and testing unpublished
versions. If you have a staging or development app, the easiest way to do this is
using the git repository as your memjs
package dependency---in package.json
:
{
"name": "MyAppName",
...
"dependencies": {
...
"memjs": "git://github.com/alevy/memjs.git#master"
...
}
}
If you find a bug, please report as an issue. If you fix it, please don't hesitate to send a pull request on GitHub or via e-mail.
Feature suggestions are also welcome! These includes suggestions about syntax and interface design.
Finally, a great way to contribute is to implement a feature that's missing and send a pull request. The list below contains some planned features that have not been addressed yet. You can also implement a feature not a list if you think it would be good.
TODOS
- Support flags
- Support multi commands
- Support CAS
- Consistent hashing for keys and/or pluggable hashing algorithm
Copyright
Copyright (c) 2012 Amit Levy, MemCachier. See LICENSE for details.