Session data access and lifecycle management methods available on the Express request object after session middleware is applied.
The session object is automatically attached to the request and provides persistent data storage across requests.
interface SessionData {
/** Session ID (read-only) */
readonly id: string;
/** Associated cookie object */
cookie: Cookie;
/** Custom session data properties */
[key: string]: any;
}Usage Examples:
app.get('/profile', (req, res) => {
// Store user data in session
req.session.userId = 123;
req.session.username = 'alice';
req.session.preferences = {
theme: 'dark',
language: 'en'
};
res.json({ message: 'Profile data saved to session' });
});
app.get('/dashboard', (req, res) => {
// Access session data
if (req.session.userId) {
res.json({
user: req.session.username,
preferences: req.session.preferences
});
} else {
res.status(401).json({ error: 'Not authenticated' });
}
});Methods for managing session state and persistence.
interface SessionLifecycle {
/**
* Regenerate the session ID while preserving session data
* @param callback - Called when regeneration is complete
* @returns Session instance for chaining
*/
regenerate(callback: (err?: Error) => void): Session;
/**
* Destroy the session and remove from store
* @param callback - Called when destruction is complete
* @returns Session instance for chaining
*/
destroy(callback: (err?: Error) => void): Session;
/**
* Reload session data from the store
* @param callback - Called when reload is complete
* @returns Session instance for chaining
*/
reload(callback: (err?: Error) => void): Session;
/**
* Manually save session to store
* @param callback - Called when save is complete
* @returns Session instance for chaining
*/
save(callback: (err?: Error) => void): Session;
/**
* Update session expiration time
* @returns Session instance for chaining
*/
touch(): Session;
/**
* Reset maxAge to originalMaxAge
* @returns Session instance for chaining
*/
resetMaxAge(): Session;
}Regenerate session ID for security purposes while preserving session data.
/**
* Regenerate the session ID while preserving session data
* Used for security after authentication or privilege changes
* @param callback - Callback function called when complete
* @returns Session instance for chaining
*/
req.session.regenerate(callback: (err?: Error) => void): Session;Usage Examples:
// Regenerate session on login for security
app.post('/login', (req, res) => {
// Validate user credentials
const user = validateCredentials(req.body.username, req.body.password);
if (user) {
req.session.regenerate((err) => {
if (err) {
return res.status(500).json({ error: 'Session regeneration failed' });
}
// Store user info in new session
req.session.userId = user.id;
req.session.username = user.username;
req.session.role = user.role;
res.json({ message: 'Login successful' });
});
} else {
res.status(401).json({ error: 'Invalid credentials' });
}
});
// Regenerate session when elevating privileges
app.post('/admin/elevate', (req, res) => {
if (req.session.userId && verifyAdminCredentials(req.body.password)) {
req.session.regenerate((err) => {
if (err) throw err;
req.session.userId = req.session.userId; // Preserve user ID
req.session.isAdmin = true;
req.session.adminElevatedAt = Date.now();
res.json({ message: 'Admin privileges granted' });
});
}
});Completely remove session data and invalidate the session.
/**
* Destroy the session and remove from store
* Unsets req.session and removes from session store
* @param callback - Callback function called when complete
* @returns Session instance for chaining
*/
req.session.destroy(callback: (err?: Error) => void): Session;Usage Examples:
// Logout endpoint
app.post('/logout', (req, res) => {
req.session.destroy((err) => {
if (err) {
return res.status(500).json({ error: 'Logout failed' });
}
res.clearCookie('connect.sid'); // Clear session cookie
res.json({ message: 'Logged out successfully' });
});
});
// Account deletion
app.delete('/account', (req, res) => {
const userId = req.session.userId;
// Delete user account
deleteUserAccount(userId).then(() => {
req.session.destroy((err) => {
if (err) console.error('Session destruction error:', err);
res.json({ message: 'Account deleted' });
});
});
});Reload session data from the store, useful for getting fresh data.
/**
* Reload session data from the store
* Refreshes req.session with latest data from store
* @param callback - Callback function called when complete
* @returns Session instance for chaining
*/
req.session.reload(callback: (err?: Error) => void): Session;Usage Examples:
// Refresh session data
app.get('/refresh-session', (req, res) => {
req.session.reload((err) => {
if (err) {
return res.status(500).json({ error: 'Session reload failed' });
}
res.json({
message: 'Session refreshed',
sessionData: req.session
});
});
});
// Check for session updates from other requests
app.get('/check-updates', (req, res) => {
const lastUpdate = req.session.lastUpdate;
req.session.reload((err) => {
if (err) throw err;
if (req.session.lastUpdate > lastUpdate) {
res.json({ hasUpdates: true, data: req.session });
} else {
res.json({ hasUpdates: false });
}
});
});Manually save session data to the store.
/**
* Manually save session to store
* Usually called automatically, but useful for long-lived connections
* @param callback - Callback function called when complete
* @returns Session instance for chaining
*/
req.session.save(callback: (err?: Error) => void): Session;Usage Examples:
// Manual save before long operation
app.post('/process-data', (req, res) => {
req.session.processingStarted = Date.now();
req.session.save((err) => {
if (err) {
return res.status(500).json({ error: 'Session save failed' });
}
// Start long-running process
processDataAsync(req.body.data)
.then(result => {
req.session.lastProcessResult = result;
res.json({ message: 'Processing complete', result });
});
});
});
// WebSocket session synchronization
io.on('connection', (socket) => {
socket.on('update-session', (data) => {
// Update session data
socket.request.session.socketData = data;
socket.request.session.save((err) => {
if (err) {
socket.emit('error', 'Session save failed');
} else {
socket.emit('session-updated');
}
});
});
});Update session expiration time without modifying data.
/**
* Update session expiration time
* Resets maxAge to prevent session timeout
* @returns Session instance for chaining
*/
req.session.touch(): Session;
/**
* Reset maxAge to originalMaxAge
* Restores the cookie's maxAge to its original value
* @returns Session instance for chaining
*/
req.session.resetMaxAge(): Session;Usage Examples:
// Keep session alive during long operations
app.get('/long-operation', (req, res) => {
req.session.touch(); // Prevent session timeout
performLongOperation()
.then(result => {
res.json({ result });
});
});
// Activity tracking middleware
app.use((req, res, next) => {
if (req.session) {
req.session.touch();
req.session.lastActivity = Date.now();
}
next();
});
// Reset session timeout to original value
app.post('/reset-timeout', (req, res) => {
req.session.resetMaxAge(); // Restore original maxAge
res.json({ message: 'Session timeout reset to original value' });
});Access the current session ID from the session object or request.
interface SessionProperties {
/** Session ID accessible from session object */
req.session.id: string;
/** Session ID accessible from request object */
req.sessionID: string;
}Usage Examples:
app.get('/session-info', (req, res) => {
res.json({
sessionId: req.session.id, // Same as req.sessionID
sessionIdAlt: req.sessionID,
cookieSettings: req.session.cookie
});
});Access the configured session store instance.
interface StoreAccess {
/** Session store instance used by middleware */
req.sessionStore: Store;
}Usage Examples:
app.get('/session-stats', (req, res) => {
// Get session count if store supports it
if (typeof req.sessionStore.length === 'function') {
req.sessionStore.length((err, count) => {
res.json({
totalSessions: count,
currentSessionId: req.sessionID
});
});
} else {
res.json({ currentSessionId: req.sessionID });
}
});