Koa-simple-session NPM

koa-simple-session

Session middleware for koa 2.x, easy use with reids, supports readonly session (use Object.freeze).

This middleware will only set a cookie when a session is manually set. Each time the session is modified (and only when the session is modified), it will reset the cookie and session.

Installation

$ npm install koa-simple-session

Examples

'use strict';
const Koa = require('koa');
const Redis = require('koa-simple-redis');
const session = require('koa-simple-session');
const app = new Koa();

function get(ctx) {
  const session = ctx.session;
  session.count = session.count || 0;
  session.count++;
  ctx.body = session.count;
}

function remove(ctx) {
  ctx.session = null;
  ctx.body = 0;
}

function regenerate(ctx) {
  get(ctx);
  return ctx.regenerateSession().then(() => {
    get(ctx);
  });
}

function freeze(ctx) {
  // the session is not sync to redis
  ctx.session.user = {
    a: 'b'
  };
  Object.freeze(ctx.session);
  ctx.body = ctx.session.user;
}

app.name = 'koa-session-test';
app.outputErrors = true;
app.keys = ['keys', 'keykeys'];
app.proxy = true;

app.use(session({
  store: new Redis(),
}));

app.use(ctx => {
  switch (ctx.path) {
    case '/get':
      get(ctx);
      break;
    case '/remove':
      remove(ctx);
      break;
    case '/freeze':
      freeze(ctx);
      break;
    case '/regenerate':
      return regenerate(ctx);
  }
});

app.listen(3000);

After adding session middleware, you can use this.session to set or get the sessions.
Setting this.session = null; will destroy this session.
Altering this.session.cookie changes the cookie options of this user. Also you can use the cookie options in session the store. Use for example cookie.maxAge as the session store's ttl.
Calling this.regenerateSession will destroy any existing session and generate a new, empty one in its place. The new session will have a different ID.

Options

key: cookie name defaulting to koa.sid
prefix: session prefix for store, defaulting to koa:sess:
ttl: ttl is for sessionStore's expiration time. it is different with cookie.maxAge, default to null(means get ttl from cookie.maxAge).
genSid: default sid was generated by uid2, you can pass a function to replace it
allowEmpty: allow generation of empty sessions
errorHandler(err, type, ctx): Store.get and Store.set will throw in some situation, use errorHandle to handle these errors by yourself. Default will throw.
reconnectTimeout: When store is disconnected, don't throw store unavailable error immediately, wait reconnectTimeout to reconnect, default is 10s.
sessionIdStore: object with get, set, reset methods for passing session id throw requests.
valid: valid(ctx, session), valid session value before use it
beforeSave: beforeSave(ctx, session), hook before save session
store: session store instance. It can be any Object that has the methods set, get, destroy
cookie: session cookie settings, defaulting to
```
{
  httpOnly: true,
  path: '/',
  overwrite: true,
  signed: true,
  maxAge: 24 * 60 * 60 * 1000,
}
```
For a full list of cookie options see expressjs/cookies.
if you setcookie.maxAge to null, meaning no "expires" parameter is set so the cookie becomes a browser-session cookie. When the user closes the browser the cookie (and session) will be removed.
Notice that ttl is different from cookie.maxAge, ttl set the expire time of sessionStore. So if you set cookie.maxAge = null, and ttl=ms('1d'), the session will expired after one day, but the cookie will destroy when the user closes the browser. And mostly you can just ignore options.ttl, koa-simple-session will parse cookie.maxAge as the tll.