expressjs-session 1.0.0 → 2.0.0

package/README.md

@@ -0,0 +1,207 @@
+# expressjs-session
+
+Lightweight, secure session middleware for Express.js applications.
+
+![npm](https://img.shields.io/npm/v/expressjs-session)
+![Node](https://img.shields.io/node/v/expressjs-session)
+![License](https://img.shields.io/npm/l/expressjs-session)
+
+---
+
+## Table of Contents
+
+- [Introduction](#introduction)  
+- [Features](#features)  
+- [Installation](#installation)  
+- [Quick Start](#quick-start)  
+- [API](#api)  
+- [Configuration Options](#configuration-options)  
+- [Examples](#examples)  
+- [Error Handling](#error-handling)  
+- [Security Considerations](#security-considerations)  
+- [Contributing](#contributing)  
+- [License](#license)  
+
+---
+
+## Introduction
+
+`expressjs-session` provides a simple, pluggable session middleware for Express applications. It stores session data server-side (in memory, Redis, MongoDB, etc.) and manages a secure cookie containing the session ID. Think of it as the receptionist at a hotel: it hands out room keys (session IDs) and looks up your data when you come back.
+
+---
+
+## Features
+
+- **Simple API** — plug into any Express app in one line  
+- **Multiple stores** — in-memory, Redis, MongoDB, and custom stores  
+- **Secure cookies** — HTTP-only, signed, optional encryption  
+- **Automatic rotation** — prevent fixation attacks by regenerating IDs  
+- **Built-in TTL** — sessions expire automatically after configured timeout  
+- **Promise support** — async/await–friendly store interface  
+
+---
+
+## Installation
+
+```bash
+npm install expressjs-session
+```
+
+---
+
+## Quick Start
+
+```js
+const express = require('express');
+const session = require('expressjs-session');
+
+const app = express();
+
+app.use(session({
+  secret: 'keyboard cat',
+  resave: false,
+  saveUninitialized: true,
+  cookie: { maxAge: 60000 }
+}));
+
+app.get('/', (req, res) => {
+  if (req.session.views) {
+    req.session.views++;
+    res.send(`Welcome back! You’ve visited ${req.session.views} times.`);
+  } else {
+    req.session.views = 1;
+    res.send('Hello, first time visitor!');
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Server running on http://localhost:3000');
+});
+```
+
+---
+
+## API
+
+### `session(options)`
+
+Returns an Express middleware function.
+
+- **options.secret** _(string, required)_  
+  A string (or array of strings) used to sign the session ID cookie.
+
+- **options.store** _(Store instance, optional)_  
+  A compatible session store (default: in-memory).
+
+- **options.resave** _(boolean, default: true)_  
+  Forces the session to be saved back to the session store, even if it wasn’t modified.
+
+- **options.saveUninitialized** _(boolean, default: true)_  
+  Forces a session that is “uninitialized” to be saved to the store.
+
+- **options.cookie** _(object, optional)_  
+  Cookie settings (path, domain, maxAge, secure, httpOnly, sameSite).
+
+- **options.name** _(string, default: `connect.sid`)_  
+  Name of the session ID cookie.
+
+- **options.genid** _(function, optional)_  
+  Custom function to generate session IDs.
+
+---
+
+## Configuration Options
+
+```js
+{
+  secret: 'your secret',
+  name: 'sessionId',
+  resave: false,
+  saveUninitialized: false,
+  cookie: {
+    maxAge: 24 * 60 * 60 * 1000, // 1 day
+    secure: true,
+    httpOnly: true,
+    sameSite: 'lax'
+  },
+  store: new RedisStore({ /* ... */ }),
+  genid: () => crypto.randomUUID()
+}
+```
+
+---
+
+## Examples
+
+### Using Redis as a Session Store
+
+```js
+const Redis = require('ioredis');
+const RedisStore = require('expressjs-session').RedisStore;
+
+app.use(session({
+  secret: 'keyboard cat',
+  store: new RedisStore({
+    client: new Redis(),
+    ttl: 86400 // 1 day
+  }),
+  cookie: { secure: true }
+}));
+```
+
+### Regenerating a Session
+
+```js
+app.post('/login', (req, res, next) => {
+  // Authenticate user...
+  req.session.regenerate(err => {
+    if (err) return next(err);
+    req.session.userId = user.id;
+    res.redirect('/dashboard');
+  });
+});
+```
+
+---
+
+## Error Handling
+
+If your store emits errors, they’ll be passed to `next(err)` in Express:
+
+```js
+app.use((err, req, res, next) => {
+  console.error('Session error:', err);
+  res.status(500).send('Internal Server Error');
+});
+```
+
+---
+
+## Security Considerations
+
+- **Rotate secrets** regularly and use a strong, unguessable string.  
+- **Use HTTPS** so cookies marked `secure` aren’t sent over plain HTTP.  
+- **Limit cookie scope** via `domain`, `path`, and `sameSite` as needed.  
+- **Avoid memory store** in production—it does not scale and leaks memory.
+
+---
+
+## Contributing
+
+1. Fork the repo  
+2. Create your feature branch (`git checkout -b feature/foo`)  
+3. Commit your changes (`git commit -am 'Add foo'`)  
+4. Push to the branch (`git push origin feature/foo`)  
+5. Open a Pull Request
+
+Please run tests with:
+
+```bash
+npm test
+```
+
+---
+
+## License
+
+[MIT](LICENSE)

package/package.json

@@ -1,14 +1,15 @@
 {
   "name": "expressjs-session",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "description": "This is a Node.js module available through the npm registry",
   "main": "index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
   "repository": {
-    "url": "https://github.com/expressjs/express"
+    "url": "https://github.com/expressjs/session"
   },
+  "icon": "icons/icon.png",
   "author": "npm",
   "license": "ISC"
 }