nestjs-session

NestJS-Session

Idiomatic Session Module for NestJS. Built on top of express-session😎

This module realise session with storing it's data in one of external stores and passing ID of session to client via Cookie/Set-Cookie headers.

If you want to store data directly in Cookie, you can look at nestjs-cookie-session.

Example

Register module:

// app.module.ts
import { Module } from '@nestjs/common';
import { NestSessionOptions, SessionModule } from 'nestjs-session';
import { ViewsController } from './views.controller';

@Module({
  imports: [
    // sync params:

    SessionModule.forRoot({
      session: { secret: 'keyboard cat' },
    }),

    // or async:

    SessionModule.forRootAsync({
      imports: [ConfigModule],
      inject: [Config],
      //              TIP: to get autocomplete in return object
      //                  add `NestSessionOptions` here ↓↓↓
      useFactory: async (config: Config): Promise<NestSessionOptions> => {
        return {
          session: { secret: config.secret },
        };
      },
    }),
  ],
  controllers: [ViewsController],
})
export class AppModule {}

In controllers use NestJS built-in Session decorator:

// views.controller.ts
import { Controller, Get, Session } from '@nestjs/common';

@Controller('views')
export class ViewsController {
  @Get()
  getViews(@Session() session: { views?: number }) {
    session.views = (session.views || 0) + 1;
    return session.views;
  }
}

BE AWARE THAT THIS EXAMPLE IS NOT FOR PRODUCTION! IT USES IN-MEMORY STORE, SO YOUR DATA WILL BE LOST ON RESTART. USE OTHER STORES

See redis-store example in examples folder.

To run examples:

git clone https://github.com/iamolegga/nestjs-session.git
cd nestjs-session
npm i
cd examples/in-memory # or `cd examples/in-memory-async` or `cd examples/redis-store`
npm i
npm start

For redis exmaple you should start redis on localhost:6379. If you have docker you can start redis image by npm run redis.

Install

npm i nestjs-session

or

yarn add nestjs-session

API

SessionModule

SessionModule class has two static methods, that returns DynamicModule, that you need to import:

• SessionModule.forRoot for sync configuration without dependencies
• SessionModule.forRootAsync for sync/async configuration with dependencies

SessionModule.forRoot

Accept NestSessionOptions. Returns NestJS DynamicModule for import.

SessionModule.forRootAsync

Accept NestSessionAsyncOptions. Returns NestJS DynamicModule for import.

NestSessionOptions

NestSessionOptions is interface of all options, has next properties:

• session - required - express-session options.
• forRoutes - optional - same as NestJS buil-in MiddlewareConfigProxy['forRoutes'] See exmaples in official docs. Specify routes, that should have access to session. If forRoutes and exclude will not be set, then sessions will be set to all routes.
• exclude - optional - same as NestJS buil-in MiddlewareConfigProxy['exclude'] See exmaples in official docs. Specify routes, that should not have access to session. If forRoutes and exclude will not be set, then sessions will be set to all routes.
• retries - optional - number - by default if your session store lost connection to database it will return session as undefined, and no errors will be thrown, and then you need to check session in controller. But you can set this property how many times it should retry to get session, and on fail InternalServerErrorException will be thrown. If you don't want retires, but just want to InternalServerErrorException to be throw, then set to 0. Set this option, if you dont't want manualy check session inside controllers.
• retriesStrategy - optional - (attempt: number) => number - function that returns number of ms to wait between next attempt. Not calls on first attempt.

NestSessionAsyncOptions

NestSessionAsyncOptions is interface of options to create session module, that depends on other modules, has next properties:

• imports - optional - modules, that session module depends on. See official docs.
• inject - optional - providers from imports-property modules, that will be passed as arguments to useFactory method.
• useFactory - required - method, that returns NestSessionOptions.

Do you use this library?
Don't be shy to give it a star! ★

Also if you are into NestJS ecosystem you may be interested in one of my other libs:

nestjs-pino

Platform agnostic logger for NestJS based on pino with request context in every log

nestjs-session

Idiomatic session module for NestJS. Built on top of express-session

nestjs-cookie-session

Idiomatic cookie session module for NestJS. Built on top of cookie-session

nestjs-roles

Type safe roles guard and decorator made easy

nest-ratelimiter

Distributed consistent flexible NestJS rate limiter based on Redis

create-nestjs-middleware-module

Create simple idiomatic NestJS module based on Express/Fastify middleware in just a few lines of code with routing out of the box

nestjs-configure-after

Declarative configuration of NestJS middleware order