README.md

connect-redis-session

Redis session storage for Express supporting the latest node-redis client.

---

Features:

• Promise-based methods for direct interaction with the sessions store
• Atomic single-key operations (get, set, touch, destroy)
• Batched multi-key operations (all, length, clear) for efficient performance
• Safeguards for handling race conditions caused by concurrent requests
• First class support for Typescript

Compatibility:

• Redis server 2.6.0+
• node-redis 4.0.0+
• express-session 1.17.0+

---

Installation

npm install connect-redis-session # redis@^4 express-session@^1.17

yarn add connect-redis-session # redis@^4 express-session@^1.17 

Usage

Quick Start

const session = require('express-session');
const redis = require('redis');
const { RedisStore } = require('connect-redis-session');

// Create the Redis client
const client = redis.createClient();

// Configure the Redis store
const store = new RedisStore({ client });

// Configure the Express session middleware
app.use(
    session({
        store,
        secret: 'swordfish',
        saveUninitialized: false, // recommended
        resave: false, // recommended
        // ...
    }),
);

Access with Promises

The RedisStore.access field exposes methods for directly interacting with the store using Promises.

const updateSession = async (sid) => {
    // Get a session from the store
    const session = await store.access.get(sid);

    // Create or update a session
    await store.access.set(sid, { ...session, foo: 'bar' })

    // Delete a session
    await store.access.destroy(sid);

    // Get all sessions
    const sessions = await session.access.all();

    // Count all sessions
    const n = await session.access.length();

    // Clear all session keys from the store
    await store.access.clear();
}

Options

const store = new RedisStore({
    client,
    prefix: 'sessions:',
    scanCount: 100,
    ttlSeconds: 86400,
    concurrencyGraceSeconds: 300,
    disableTouch: false,
})

---

client

object | required

An initialized node-redis v4 client.

Prior to server listening, the client's connect method should be called.

example

(async () => {
    await client.connect();
    server.listen(80);
})();

---

prefix

string • 'sessions:'

A prefix used for each key in the session store.

---

scanCount

number • 100

The maximum number of keys batched in Redis SCAN calls. This also helps limit the memory load on subsequent calls using the key batches (e.g. MGET, DEL).

---

ttlSeconds

number | false • 86400 1 day

The fallback duration in seconds after which a created or updated session should be expired.

This field is only used when a session is missing the cookie.expires field.

When set to 0 or false, the store will reject sessions missing the cookie.expires field.

---

concurrencyGraceSeconds

number • 300

The duration in seconds after tombstone records are removed from the store.

Tombstone records are used to prevent a destroyed session from being updated or touched. This lock is retained for the duration specified by this setting.

---

disableTouch

boolean • false

Disables renewing the session's time to live when the session's touch method is used.

Setting this option to true is not recommended and should share the same value as the session's resave option.

---

serializer

object

A custom serializer implementing the following encoding and decoding methods for storing session data as Redis string values:

• stringify: (value: SessionData) => string
• parse: (text: string) => SessionData

Refer to the global JSON object for an example.

---

License

MIT License