node package manager



NPM version Build status Test coverage Dependency Status License Downloads

A redis session for Koa that creates sets for specific values.

Use-case: you want to know all the sessions related to a user so that if the user resets his/her password, you destroy all the sessions.


  • Stores sessions as hash sets
  • Stores cross references as sets
  • Functional API


const app = require('koa')()
const client = require('ioredis').createClient()
const Session = require('koa-redis-session-sets')(app, {
  references: {
    user_id: {} // options object for future use, maytbe 
app.use(function * (next) {
  // get the session 
  let session = yield this.session.get()
  // update the session 
  yield this.session.set({
    user_id: 1
  // update the session object with latest keys 
  session = yield this.session.get()
  this.status = 204

Here's an example of deleting all the sessions associated with user_id: 1. You have to do it yourself because handling it would be too opinionated. Specifically, if this set is possibly large, you'd want to use SSCAN.

const key = Session.getReferenceKey('user_id', 1)
client.smembers(key).then(session_ids => {
  return Promise.all( => {
    // deletes the session and removes the session from all the referenced sets 
}).catch(err => {


const SessionMiddleware = KoaRedisSessionSets(app, options)

Creates a new session middleware instance.


  • client - ioredis client
  • references - fields to reference
  • maxAge - max age of sessions, defaulting to 28 days
  • prefix - optional key prefix
  • byteLength - optional byte length for CSRF tokens


Use the session middleware in your app. Note that this is a very simple function and middleware is not required. Look at the source code to understand how simple it is.


A Koa v2 version of the middleware.

const Session = SessionMiddleware.createSession(context)

Create your own session object from a context.

const key = SessionMiddleware.getReferenceKey(field, value)

Get the key for a redis set that contains all the session ids related to a field:value pair. Use client.smembers(key) to get all the session ids.

const key = Session.getKey()

Session is ctx.session. Get the key for the redis hash for use with client.hgetall(key).

Session.get([fields]).then(session => {})

Get the session, optionally with select fields.

Session.set(values, [maxAge]).then(values => {})

Set specific fields in the session. Does not return the new session.

Session.unset(fields, [maxAge]).then(() => {})

Remove specific fields in the session. Does not return the new session.

Session.touch([maxAge]).then(() => {})

Update the session, updating the cookies and the session expire time.

Session.delete().then(() => {})

Deletes the session. Does not create a new one. Execute const session = await ctx.session.get() to create a new one

Session.createCSRFToken([session]).then(token => {})

Create a CSRF token.

Session.verifyCSRFToken([session], token).then(valid => {})

Returns a boolean of whether a CSRF token is valid.

const Store =

The Store is the underlying redis logic of the session.

const key = Store.getSessionKey(session_id)

const key = Store.getReferenceKey(field, value)

Store.get(session_id, [fields]).then(session => {})

Store.set(session_id, values, [maxAge]).then(values => {})

Store.unset(session_id, fields, [maxAge]).then(() => {})

Store.touch(session_id, [maxAge]).then(() => {})

Store.delete(session_id).then(() => {})