node package manager
Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »



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

Koa v1

For Koa version, use koa-redis-session-sets@1.


const Koa = require('koa')
const client = require('ioredis').createClient()
const app = new Koa()
const Session = require('koa-redis-session-sets')(app, {
  references: {
    user_id: {} // options object for future use, maytbe
app.use(async (ctx, next) => {
  // get the session
  let session = await ctx.session.get()
  // update the session
  await ctx.session.set({
    user_id: 1
  // update the session object with latest keys
  session = await ctx.session.get()
  ctx.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)
try {
  const session_ids = await client.smembers(key)
  await 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.

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(() => {})