express-socket.io-session - npm Package Compare versions

Comparing version 1.2.5 to 1.2.6

example/index.js

@@ -57,2 +57,3 @@ var debug = require("debug")("express-socket.io-session:example"),
     socket.handshake.session.save();
+    //emit logged_in for debugging purposes of this example
     socket.emit("logged_in", socket.handshake.session);
@@ -64,2 +65,3 @@ });
     socket.handshake.session.save();
+    //emit logged_out for debugging purposes of this example
     socket.emit("logged_out", socket.handshake.session);
@@ -70,2 +72,2 @@ });
 
-server.listen(3000);
+server.listen(3000);

package.json

 {
   "name": "express-socket.io-session",
-  "version": "1.2.5",
+  "version": "1.2.6",
   "description": "Share a cookie-based express-session middleware with socket.io",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -8,11 +8,22 @@ express-socket.io-session
 
-**Please help me notice errors or ask me for improvements [creating an issue](https://github.com/oskosk/express-socket.io-session/issues/new)**.
+**Help me notice errors or ask me for improvements [creating an issue](https://github.com/oskosk/express-socket.io-session/issues/new)**.
 
 ## Overview
 
-On every socket connection, you'll have `socket.handshake.session` pointing to
-the same `req.session` you would expect in any express app handler that uses
-the `express-session` middleware module.
+On every socket connection, you'll have the session object at 
+**socket.handshake.session** 
+That is the same session object `req.session` you get in your route middleware when your app
+uses `express-session`.
 
 
+### Modifying session data inside socket.io event handlers
+
+Don't rely on **session data autosaving** if you use an [async store](https://github.com/expressjs/session#compatible-session-stores) for **express-session**. 
+
+Use [Session.reload()](https://github.com/expressjs/session#sessionreload) and [Session.save()](https://github.com/expressjs/session#sessionsave)
+on the `socket.handshake.session` object inside your socket.io event handlers.
+
+**Please, see [More about updating and getting session data](more-about-updating-and-getting-session-data) for better understanding
+of how to read and update session data inside your socket.io event handlers**.
+
 ## Installation
@@ -23,5 +34,6 @@
 ```
+
 ## Usage
 
-    var session require("express-session")({
+    var session = require("express-session")({
         secret: "my-secret",
@@ -31,7 +43,8 @@ resave: true,
     });
-    // Use sessions with express
-    app.use(session);
-    //Share the express' session with socket.io
-    io.use(require("express-socket.io-session")(session));
+    var sharedsession = require("express-socket.io-session")(session);
+    
 
+    app.use(session); // Use express-session middleware for express
+    
+    io.use(sharedsession(session)); // use shared session middleware for socket.io
 
@@ -48,3 +61,5 @@ **Sharing session data with a namespaced socket**
     ...
-    io.use(require("express-socket.io-session")(session, cookieParser({/* your params to cookie-parser* /})));
+    io.use(sharedsession(session, cookieParser({
+        /* your params to cookie-parser* /
+    }));
 
@@ -54,6 +69,3 @@ ## Example
 ```
-# Install express, socket.io and express-session 
-$ npm install express socket.io express-session 
-# Install this module
-$ npm install express-socket.io-session
+$ npm install express socket.io express-session express-socket.io-session
 ```
@@ -82,13 +94,44 @@
 
+    io.on("connection", function(socket) {
+        // Accept a login event with user's data
+        socket.on("login", function(userdata) {
+            socket.handshake.session.userdata = userdata;
+            socket.handshake.session.save();
+        });
+        socket.on("logout", function(userdata) {
+            if (socket.handshake.session.userdata) {
+                delete socket.handshake.session.userdata;
+                // Save the data to the session store
+            socket.handshake.session.save();
+            }
+        });        
+    });
+
     server.listen(3000);
 
- 
 
+## More about updating and getting session data
 
+You may be used to `express-session` behaviour by which, you just
+modify the `session` properties and its value gets updated (even with
+using asynchronous stores like mongodb or redis). **express-session** achieves that
+by monkeypatching (and overloading) `req.end`. 
+
+The case here is that **socket.io middleware is run only once**. On connection handshake.
+The event handlers you define can't trigger the middleware. 
+
+So if you get used to accessing and saving session data **inside
+your event handlers**, with the `.reload()` 
+and `.save()` from the session object you'll do just fine.
+
+By using **express-socket.io-session** you'll find these methods in `socket.handshake.session.get()` and `socket.handshake.session.save()`
+when handling an event.
+
+
 ## API
 
-This module exports  a **socket.io**'s middleware for using with `io.use()`
-You get a *shared session* middleware by requiring the module.
+This module exports a middleware function for **socket.io**.
+This  **sharedsession** function can be used with the `io.use()` method.
 
-**require("express-socket.io-session")( express_session_middleware, [cookieparser_instance] )**
+**sharedsession( express_session_middleware, [cookieparser_instance] )**
 
@@ -103,3 +146,3 @@ * `express_session_middleware` is **required** and must be an express middleware function created with the  [express-session](https://www.npmjs.org/package/express-session) module that allows cookie-based sessions.
 
-Although there are a couple of modules that allow to share session objects between express and socket.io,
+Although there are a couple of modules that allow you to share session objects between express and socket.io,
 I wanted to be able to share the modules without affecting regular `express-session` instantiation.
@@ -106,0 +149,0 @@

No alert changes

Improved metrics

Total package byte prevSize

15226

increased by22.52%

Number of package files

10

increased by11.11%

Lines of code

91

increased by1.11%

Number of lines in readme file

173

increased by33.08%

No dependency changes