koa-session-local

Local session storage for Koa sessions using async/await v1.0.4

This is an implementation of the koa-session storage in local system memory. This is intended to be used as in-memory session storage for testing/development purposes, as none of the data is persisted to permanent storage.

Table of Contents

• Install
• Usage
  • Basic
• Options
  • Garbage collection
• License
• Contributors

Install

npm:

npm install --save koa-session-local

yarn:

yarn add koa-session-local

Usage

koa-session-local works with koa-session (a simple session middleware for Koa), and requires Node >= 7.6 for async/await support.

Basic

const koa = require('koa');
const session = require('koa-session');
const store = require('koa-session-local');
 
const app = koa();
app.keys = ['keys', 'keykeys'];
app.use(session({
    store: new store(),
    ...
}));
 
app.use(async ctx => {
    const { session } = ctx;
    let n = session.views || 0;
    session.views = ++n;
    ctx.body = `${n} view(s)`;
});
 
app.listen(3000);

Options

The module will use the default, or user provided values for age and maxAge parameters, as well as verify whether a session is a rolling session, force save session, or otherwise.

Garbage collection

Garbage collection is an important feature of many session management implementations in NodeJS and other platforms. In this module, we're provided options for you to control the frequency and other properties of the garbage collection.

Garbage collection is performed on session.get, so there may be a slight request delay when the session garbage collection has been initiated.

When a session is loaded, a mathematical check is performed against the probability value to determine if there should be a garbage collection cycle. If the generated number is less than the 'probability' value, then the sessions in the store are scanned for deletion. If the expiry date for an offer is passed, along with the 'maxlifetime' value, the sessions are removed.

Note: Using this function with a sufficiently low maxlifetime value, in conjunction with other koa-session settings may remove active or recently expired sessions that are not normally ready for garbage collection.

Options

• gc (bool): Enable or disable session garbage collection (gc)
• probability (float): The probability for which session gc will be triggered, higher is more frequently
• maxlifetime (int): The is the maximum lifetime in milliseconds after the session expiry a session can live, before it is removed
• debug (fn()): A reference to a function to generate log information (optional)

Defaults:

const defaults = {
    gc: false,
    probability: 0.05, /* 5% chance per session.get call */
    maxlifetime: 60 * 1000 /* 60s in ms */
}

To use:

Enable gc and use the default values with no debugging:

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

Enable gc and configure other properties:

app.use(session({
    store: new store({
         gc: true,
         probability: 0.05, /* 5% change */
         maxlifetime: 60 * 1000, /* 60 seconds */
         debug: console.log /* debug messages will be sent to console.log */
     }),
    ...
}));

License

MIT © Justin Mitchell (2019)

Contributors