diff options
Diffstat (limited to 'node_modules/connect-mongo/README.md')
| -rw-r--r-- | node_modules/connect-mongo/README.md | 247 |
1 files changed, 0 insertions, 247 deletions
diff --git a/node_modules/connect-mongo/README.md b/node_modules/connect-mongo/README.md deleted file mode 100644 index 0ef13f2..0000000 --- a/node_modules/connect-mongo/README.md +++ /dev/null @@ -1,247 +0,0 @@ -# connect-mongo - -MongoDB session store for [Connect](https://github.com/senchalabs/connect) and [Express](http://expressjs.com/) - -[](https://www.npmjs.com/package/connect-mongo) -[](https://www.npmjs.com/package/connect-mongo) -[](https://travis-ci.org/kcbanner/connect-mongo) -[](https://coveralls.io/github/kcbanner/connect-mongo?branch=master) -[](https://david-dm.org/kcbanner/connect-mongo) - -## Compatibility - -* Support Express up to `5.0` -* Support all Connect versions -* Support [Mongoose](http://mongoosejs.com/index.html) `>= 2.6`, `3.x` and `4.x` -* Support [native MongoDB driver](http://mongodb.github.io/node-mongodb-native/) `>= 1.2`, `2.x` -* Support Node.js `0.10`, `0.12`, `4.x`, `5.x`, `6.x` and all [io.js](https://iojs.org) versions -* Support [MongoDB](https://www.mongodb.com/) up to `3.2` - -For older Node.js versions `0.10`, `0.12` and io.js, please read the [Node.js compatibility section](#old-nodejs-versions-compatibility) - -## Usage - -### Express or Connect integration - -Express `4.x`, `5.0` and Connect `3.x`: - -```js -const session = require('express-session'); -const MongoStore = require('connect-mongo')(session); - -app.use(session({ - secret: 'foo', - store: new MongoStore(options) -})); -``` - -Express `2.x`, `3.x` and Connect `1.x`, `2.x`: - -```js -const MongoStore = require('connect-mongo')(express); - -app.use(express.session({ - secret: 'foo', - store: new MongoStore(options) -})); -``` - -For Connect `1.x` and `2.x`, just replace `express` by `connect`. - -### Connection to MongoDB - -In many circumstances, `connect-mongo` will not be the only part of your application which need a connection to a MongoDB database. It could be interesting to re-use an existing connection. - -Alternatively, you can configure `connect-mongo` to establish a new connection. - -#### Re-use a Mongoose connection - -```js -const mongoose = require('mongoose'); - -// Basic usage -mongoose.connect(connectionOptions); - -app.use(session({ - store: new MongoStore({ mongooseConnection: mongoose.connection }) -})); - -// Advanced usage -const connection = mongoose.createConnection(connectionOptions); - -app.use(session({ - store: new MongoStore({ mongooseConnection: connection }) -})); -``` - -#### Re-use a native MongoDB driver connection (or a promise) - -In this case, you just have to give your `Db` instance to `connect-mongo`. -If the connection is not opened, `connect-mongo` will do it for you. - -```js -/* -** There are many ways to create dbInstance. -** You should refer to the driver documentation. -*/ - -app.use(session({ - store: new MongoStore({ db: dbInstance }) -})); -``` - -Or just give a promise... - -```js -app.use(session({ - store: new MongoStore({ dbPromise: dbInstancePromise }) -})); -``` - -#### Create a new connection from a MongoDB connection string - -[MongoDB connection strings](http://docs.mongodb.org/manual/reference/connection-string/) are __the best way__ to configure a new connection. For advanced usage, [more options](http://mongodb.github.io/node-mongodb-native/driver-articles/mongoclient.html#mongoclient-connect-options) can be configured with `mongoOptions` property. - -```js -// Basic usage -app.use(session({ - store: new MongoStore({ url: 'mongodb://localhost/test-app' }) -})); - -// Advanced usage -app.use(session({ - store: new MongoStore({ - url: 'mongodb://user12345:foobar@localhost/test-app?authSource=admins&w=1', - mongoOptions: advancedOptions // See below for details - }) -})); -``` - -## Events - -A `MongoStore` instance will emit the following events: - -| Event name | Description | Payload -| ----- | ----- | ----- | -| `create` | A session has been created | `sessionId` | -| `touch` | A session has been touched (but not modified) | `sessionId` | -| `update` | A session has been updated | `sessionId` | -| `set` | A session has been created OR updated _(for compatibility purpose)_ | `sessionId` | -| `destroy` | A session has been destroyed | `sessionId` | - -## Old Node.js versions compatibility - -For versions `0.10`, `0.12` and io.js, you must use the ES5 fallback: -```js -var MongoStore = require('connect-mongo/es5')(session); -``` - -## Session expiration - -When the session cookie has an expiration date, `connect-mongo` will use it. - -Otherwise, it will create a new one, using `ttl` option. - -```js -app.use(session({ - store: new MongoStore({ - url: 'mongodb://localhost/test-app', - ttl: 14 * 24 * 60 * 60 // = 14 days. Default - }) -})); -``` - -__Note:__ Each time an user interacts with the server, its session expiration date is refreshed. - -## Remove expired sessions - -By default, `connect-mongo` uses MongoDB's TTL collection feature (2.2+) to have mongod automatically remove expired sessions. But you can change this behavior. - -### Set MongoDB to clean expired sessions (default mode) - -`connect-mongo` will create a TTL index for you at startup. You MUST have MongoDB 2.2+ and administration permissions. - -```js -app.use(session({ - store: new MongoStore({ - url: 'mongodb://localhost/test-app', - autoRemove: 'native' // Default - }) -})); -``` - -__Note:__ If you use `connect-mongo` in a very concurrent environment, you should avoid this mode and prefer setting the index yourself, once! - -### Set the compatibility mode - -You have an older MongoDB version (compatible with connect-mongo) or you can't or don't want to create a TTL index. - -`connect-mongo` will take care of removing expired sessions, using defined interval. - -```js -app.use(session({ - store: new MongoStore({ - url: 'mongodb://localhost/test-app', - autoRemove: 'interval', - autoRemoveInterval: 10 // In minutes. Default - }) -})); -``` - -### Disable expired sessions cleaning - -You are in production environnement and/or you manage the TTL index elsewhere. - -```js -app.use(session({ - store: new MongoStore({ - url: 'mongodb://localhost/test-app', - autoRemove: 'disabled' - }) -})); -``` - -## Lazy session update - - -If you are using [express-session](https://github.com/expressjs/session) >= [1.10.0](https://github.com/expressjs/session/releases/tag/v1.10.0) and don't want to resave all the session on database every single time that the user refresh the page, you can lazy update the session, by limiting a period of time. - -```js -app.use(express.session({ - secret: 'keyboard cat', - saveUninitialized: false, // don't create session until something stored - resave: false, //don't save session if unmodified - store: new mongoStore({ - url: 'mongodb://localhost/test-app', - touchAfter: 24 * 3600 // time period in seconds - }) -})); -``` - -by doing this, setting `touchAfter: 24 * 3600` you are saying to the session be updated only one time in a period of 24 hours, does not matter how many request's are made (with the exception of those that change something on the session data) - -## More options - - - `collection` Collection (default: `sessions`) - - `fallbackMemory` Fallback to `MemoryStore`. Useful if you want to use MemoryStore in some case, like in development environment. - - `stringify` If true, connect-mongo will serialize sessions using `JSON.stringify` before - setting them, and deserialize them with `JSON.parse` when getting them. - (optional, default: true). This is useful if you are using types that - MongoDB doesn't support. - - `serialize` Custom hook for serializing sessions to MongoDB. This is helpful if you need - to modify the session before writing it out. - - `unserialize` Custom hook for unserializing sessions from MongoDB. This can be used in - scenarios where you need to support different types of serializations - (e.g., objects and JSON strings) or need to modify the session before using - it in your app. - - `transformId` (optional) Transform original sessionId in whatever you want to use as storage key. - -## Tests - - npm test - -The tests use a database called `connect-mongo-test`. - -## License - -The MIT License |