Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/koajs/session
Simple session middleware for koa
https://github.com/koajs/session
koa koa-session session
Last synced: 3 days ago
JSON representation
Simple session middleware for koa
- Host: GitHub
- URL: https://github.com/koajs/session
- Owner: koajs
- License: mit
- Created: 2013-11-06T22:33:49.000Z (about 11 years ago)
- Default Branch: master
- Last Pushed: 2024-04-23T22:36:27.000Z (9 months ago)
- Last Synced: 2024-10-29T15:22:58.563Z (3 months ago)
- Topics: koa, koa-session, session
- Language: JavaScript
- Homepage:
- Size: 240 KB
- Stars: 903
- Watchers: 13
- Forks: 113
- Open Issues: 54
-
Metadata Files:
- Readme: Readme.md
- Changelog: History.md
- License: LICENSE
Awesome Lists containing this project
- awesome-humanscape - koa-session - session 관리를 위한 middleware (Node.js, koa / Utilites)
- awesome-koa - session - Simple cookie-based session middleware (Middleware)
- awesome-koa - koa-session - 简单基于Cookie的Session中间件。   (仓库 / 中间件)
- stars - session
- stars - session
README
# koa-session
[![NPM version][npm-image]][npm-url]
[](https://github.com/koajs/session/actions/workflows/nodejs.yml)
[![Test coverage][codecov-image]][codecov-url]
[![Known Vulnerabilities][snyk-image]][snyk-url]
[![npm download][download-image]][download-url]
[](https://nodejs.org/en/download/)
[](https://makeapullrequest.com)
[npm-image]: https://img.shields.io/npm/v/koa-session.svg?style=flat-square
[npm-url]: https://npmjs.org/package/koa-session
[codecov-image]: https://codecov.io/gh/koajs/session/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/koajs/session
[snyk-image]: https://snyk.io/test/npm/koa-session/badge.svg?style=flat-square
[snyk-url]: https://snyk.io/test/npm/koa-session
[download-image]: https://img.shields.io/npm/dm/koa-session.svg?style=flat-square
[download-url]: https://npmjs.org/package/koa-session
Simple session middleware for Koa. Defaults to cookie-based sessions and supports external stores.
## Installation
```bash
npm install koa-session
```
## Notice
7.x has a breaking change: drop Node.js < 18.19.0 support. And it support CommonJS and ESM both.
6.x changed the default cookie key from `koa:sess` to `koa.sess` to ensure `set-cookie` value valid with HTTP spec.
[See issue](https://github.com/koajs/session/issues/28).
If you want to be compatible with the previous version, you can manually set `config.key` to `koa:sess`.
## Example
View counter example:
```js
import Koa from 'koa';
import session from 'koa-session';
const app = new Koa();
app.keys = ['some secret hurr'];
const 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,
autoCommit: true, /** (boolean) automatically commit headers (default true) */
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)*/
secure: true, /** (boolean) secure cookie*/
sameSite: null, /** (string) session cookie sameSite options (default null, don't set it) */
};
app.use(session(CONFIG, app));
// or if you prefer all default config, just use => app.use(session(app));
app.use(ctx => {
// ignore favicon
if (ctx.path === '/favicon.ico') return;
let n = ctx.session.views || 0;
ctx.session.views = ++n;
ctx.body = n + ' views';
});
app.listen(3000);
console.log('listening on port 3000');
```
## 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
The session is stored in a cookie by default, but it has some disadvantages:
- Session is stored on client side unencrypted
- [Browser cookies always have length limits](http://browsercookielimits.squawky.net/)
You can store the session content in external stores (Redis, MongoDB or other DBs) by passing `options.store` with three methods (these need to be async functions):
- `get(key, maxAge, { rolling, ctx })`: get session object by key
- `set(key, sess, maxAge, { rolling, changed, ctx })`: set session object for key, with a `maxAge` (in ms)
- `destroy(key, {ctx})`: destroy session for key
Once you pass `options.store`, session storage is dependent on your external store -- you can't access the session if your external store is down. **Use external session stores only if necessary, avoid using session as a cache, keep the session lean, and store it in a cookie if possible!**
The way of generating external session id is controlled by the `options.genid(ctx)`, which defaults to `uuid.v4()`.
If you want to add prefix for all external session id, you can use `options.prefix`, it will not work if `options.genid(ctx)` present.
If your session store requires data or utilities from context, `opts.ContextStore` is also 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.
### Custom External Key
External key is used the cookie by default, but you can use `options.externalKey` to customize your own external key methods. `options.externalKey` with two methods:
- `get(ctx)`: get the external key
- `set(ctx, value)`: set the external key
### Session#isNew
Returns **true** if the session is new.
```js
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.
### Session#externalKey
Get session external key, only exist when external session store present.
### Session#save()
Save this session no matter whether it is populated.
### Session#manuallyCommit()
Session headers are auto committed by default. Use this if `autoCommit` is set to `false`.
### Destroying a session
To destroy a session simply set it to `null`:
```js
this.session = null;
```
## License
[MIT](LICENSE)
## Contributors
[](https://github.com/koajs/session/graphs/contributors)
Made with [contributors-img](https://contrib.rocks).