koa-session
Koa cookie session middleware
Last updated 6 years ago by dead_horse .
MIT · Repository · Bugs · Original npm · Tarball · package.json
$ npm install koa-session 
SYNC missed versions from official npm registry.

koa-session

NPM version build status Test coverage Gittip David deps iojs version node version npm download

Simple session middleware for Koa. Defaults to cookie-based sessions and supports external stores.

Requires Node 7.6 or greater for async/await support

Installation

$ npm install koa-session

Example

View counter example:

var session = require('koa-session');
var koa = require('koa');
var app = koa();

app.keys = ['some secret hurr'];

var CONFIG = {
  key: 'koa:sess', /** (string) cookie key (default is koa:sess) */
  /** (number || 'session') maxAge in ms (default is 1 days) */
  /** 'session' will result in a cookie that expires when session/browser is closed */
  /** Warning: If a session cookie is stolen, this cookie will never expire */
  maxAge: 86400000,
  overwrite: true, /** (boolean) can overwrite or not (default true) */
  httpOnly: true, /** (boolean) httpOnly or not (default true) */
  signed: true, /** (boolean) signed or not (default true) */
  rolling: false, /** (boolean) Force a session identifier cookie to be set on every response. The expiration is reset to the original maxAge, resetting the expiration countdown. (default is false) */
  renew: false, /** (boolean) renew session when session is nearly expired, so we can always keep user logged in. (default is false)*/
};

app.use(session(CONFIG, app));
// or if you prefer all default config, just use => app.use(session(app));

app.use(function *(){
  // ignore favicon
  if (this.path === '/favicon.ico') return;

  var n = this.session.views || 0;
  this.session.views = ++n;
  this.body = n + ' views';
})

app.listen(3000);
console.log('listening on port 3000');

For Koa 2, use koa-convert to convert the session middleware :

const koa = require('koa');
const session = require('koa-session')
const convert = require('koa-convert');

const app = new koa();
app.use(convert(session(app)));

// codes

API

Options

The cookie name is controlled by the key option, which defaults to "koa:sess". All other options are passed to ctx.cookies.get() and ctx.cookies.set() allowing you to control security, domain, path, and signing among other settings.

Custom encode/decode Support

Use options.encode and options.decode to customize your own encode/decode methods.

Hooks

  • valid(): valid session value before use it
  • beforeSave(): hook before save session

External Session Stores

Session will store in cookie by default, but it has some disadvantages:

You can store the session content in external stores(redis, mongodb or other DBs) by pass options.store with three methods(need to be generator function or async function):

  • get(key, maxAge, { rolling }): get session object by key
  • set(key, sess, maxAge, { rolling, changed }): set session object for key, with a maxAge (in ms)
  • destroy(key): destroy session for key

Once you passed options.store, session is strong dependent on your external store, you can't access session if your external store is down. Use external session stores only if necessary, avoid use session as a cache, keep session lean and stored by cookie!

The way of generating external session id is controlled by the options.genid, which defaults to Date.now() + '-' + uid.sync(24).

If you want to add prefix for all external session id, you can use options.prefix, it will not work if options.genid present.

If your session store requires data or utilities from context, opts.ContextStore is alse supported. ContextStore must be a class which claims three instance methods demonstrated above. new ContextStore(ctx) will be executed on every request.

Events

koa-session will emit event on app when session expired or invalid:

  • session:missed: can't get session value from external store.
  • session:invalid: session value is invalid.
  • session:expired: session value is expired.

Session#isNew

Returns true if the session is new.

if (this.session.isNew) {
  // user has not logged in
} else {
  // user has already logged in
}

Session#maxAge

Get cookie's maxAge.

Session#maxAge=

Set cookie's maxAge.

Destroying a session

To destroy a session simply set it to null:

this.session = null;

License

MIT

Current Tags

  • 6.4.0                                ...           latest (2 years ago)
  • 2.0.1                                ...           latest-2 (6 years ago)
  • 4.8.1                                ...           latest-4 (6 years ago)
  • 4.8.1                                ...           v4 (6 years ago)

55 Versions

  • 6.4.0                                ...           2 years ago
  • 6.3.1                                ...           2 years ago
  • 6.3.0                                ...           2 years ago
  • 6.2.0                                ...           4 years ago
  • 6.1.0                                ...           4 years ago
  • 6.0.0                                ...           5 years ago
  • 5.13.1                                ...           5 years ago
  • 5.13.0                                ...           5 years ago
  • 5.12.3                                ...           5 years ago
  • 5.12.2                                ...           5 years ago
  • 5.12.1                                ...           5 years ago
  • 5.12.0                                ...           6 years ago
  • 5.11.0                                ...           6 years ago
  • 5.10.1                                ...           6 years ago
  • 4.8.1                                ...           6 years ago
  • 5.10.0                                ...           6 years ago
  • 2.0.1                                ...           6 years ago
  • 5.9.0                                ...           6 years ago
  • 5.8.3                                ...           6 years ago
  • 5.8.2                                ...           6 years ago
  • 4.8.0                                ...           7 years ago
  • 5.8.1                                ...           7 years ago
  • 5.8.0                                ...           7 years ago
  • 5.7.1                                ...           7 years ago
  • 4.7.1                                ...           7 years ago
  • 5.7.0                                ...           7 years ago
  • 4.7.0                                ...           7 years ago
  • 4.6.0                                ...           7 years ago
  • 5.6.0                                ...           7 years ago
  • 5.5.1                                ...           7 years ago
  • 5.5.0                                ...           7 years ago
  • 4.5.0                                ...           7 years ago
  • 5.4.0                                ...           7 years ago
  • 4.4.0                                ...           7 years ago
  • 5.3.0                                ...           8 years ago
  • 4.3.0                                ...           8 years ago
  • 5.2.0                                ...           8 years ago
  • 4.2.0                                ...           8 years ago
  • 5.1.0                                ...           8 years ago
  • 4.1.0                                ...           8 years ago
  • 5.0.0                                ...           8 years ago
  • 4.0.1                                ...           8 years ago
  • 4.0.0                                ...           8 years ago
  • 3.4.0                                ...           8 years ago
  • 3.3.1                                ...           9 years ago
  • 3.3.0                                ...           9 years ago
  • 3.2.0                                ...           10 years ago
  • 3.1.1                                ...           10 years ago
  • 3.1.0                                ...           10 years ago
  • 3.0.0                                ...           10 years ago
  • 2.0.0                                ...           11 years ago
  • 1.2.1                                ...           11 years ago
  • 1.2.0                                ...           11 years ago
  • 1.1.0                                ...           11 years ago
  • 1.0.0                                ...           11 years ago
Downloads
Total 3
Today 1
This Week 1
This Month 1
Last Day 0
Last Week 0
Last Month 0
Dependencies (5)
Dev Dependencies (9)
Dependents (1)

© 2010 - cnpmjs.org x YWFE | Home | YWFE