@burnett01/c2b-session v1.0.8

c2b-session

A legacy yet minimalist session-manager for Node.js. Supports Node.js/IO.js from version 0.10 onwards.

Unit-Tests are included.

Table of contents

• API
• Setup
• Set a timeout for sessions (optional)
• Create a session
• Retrieve a session
• Create or retrieve a session
• Test whether session exist
• Test whether session is connected
• Get all sessions
• Get online sessions
• Destroy a session
• Session Handling
  • Connect a session
  • Disconnect a session
  • Test status
  • Store session-data
  • Query session-data
• Examples
  • Example 1
  • Example 2 (recommended)
• How to install
• Unit-Tests
  • Make
  • NPM
• Use-case
• Contributing
• License

API

Methods (fn) of the module:

* setTimeout(time <minutes>, callback <function>(ident, time)) Fn
* create(config <object>, callback <function>(err, session)) Fn
* retrieve(ident <string>, callback <function>(err, session)) Fn
* createOrRetrieve(config <object>, callback <function>(err, session, state)) Fn
* exists(ident <string>) Boolean
* is_connected(ident <string>) Boolean
* getAll() Object
* getOnline() Array
* destroy() Void

Methods (fn) of a session-object:

* connect(callback <function>(err)) Fn
* disconnect(callback <function>(err)) Fn
* online() Boolean
* put(callback <function>(err)) Fn
* get([key <string> (optional)], callback <function>(err, result)) Fn

Default template of session-object:

{
    t_connect: Date.now(),      //timestamp of a sessions initial connection
    t_last_action: Date.now(),  //timestamp of a sessions last action, eg. put() [required]
    connected: false,           //state of a sessions connection [required]
    ident: '',                  //ident of a session [required]
    data: {}                    //storage of session data [required]
}

Setup

var sessionManager = require('@burnett01/c2b-session');

Set a timeout for sessions (optional)

//Optionally set a timeout (min) for sessions...
sessionManager.setTimeout(1);

//as of version 0.0.3 you can pass a function too
sessionManager.setTimeout(1, function(ident, time){
    console.log(`[SESSION] ID ${ident} timed-out (${time})`);
});

Create a session

sessionManager.create({
    ident: "my-session-name"

}, function(err, session){
    if(err){ return console.log(err); };

    console.log("[SESSION] Successfully created!");
    console.log(session);
});

//You may also pass some default data to your session

sessionManager.create({
    ident: "my-session-name",
    data: {
        A: "Data 1",
        B: "Data 2",
        C: "Data 3"
    }

}, function(err, session){
    if(err){ return console.log(err); };

    console.log("[SESSION] Successfully created!");
    console.log(session);
});

Retrieve a session

sessionManager.retrieve("my-session-name", function(err, session){
    if(err){ return console.log(err); };

    console.log("[SESSION] Successfully retrieved!");
    console.log(session);
});

Create or retrieve a session

sessionHandler.createOrRetrieve({
    ident: "my-session-name"

}, function(err, session, state){
    if(err){ return console.log(err); };

    if(state == 1){ console.log("Successfully created!"); }
    if(state == 2){ console.log("Successfully retrieved!"); }
    
    console.log(session);
});

Test whether session exist

if(sessionManager.exists("my-session-name")){
    console.log("[SESSION] Exist!");
}else{
    console.log("[SESSION] Invalid session!");
}

Test whether session is connected

if(sessionManager.is_connected("my-session-name")){
    console.log("[SESSION] Online!");
}else{
    console.log("[SESSION] Offline!");
}

Get all sessions

sessionManager.getAll();

//or
sessionManager.sessions;

Get online sessions

sessionManager.getOnline();

Destroy a session

sessionManager.destroy("my-session-name");

Session Handling

A session-object is returned by the modules create and retrieve methods.

Connect a session

session.connect(function(err){
    if(err){ return console.log(err); };

    console.log("[SESSION] Successfully connected!");
});

Disconnect a session

session.disconnect(function(err){
    if(err){ return console.log(err); };

    console.log("[SESSION] Successfully disconnected!");
});

Test status

if(session.online()){
    console.log("[SESSION] Online!");
}else{
    console.log("[SESSION] Offline!");
}

Store session-data

session.put({ 
    D: "Data 4",
    E: "Data 5",
    F: "Data 6"

}, function(err){
    if(err){ return console.log(err); };

    console.log("[SESSION] Successfully stored the data!");
});

Query session-data

//Query by key
session.get("E", function(err, result){
    if(err){ return console.log(err); };
    
    console.log("[SESSION] Successfully fetched the data!");
    console.log(result);
});

//Query all
session.get(function(err, result){
    if(err){ return console.log(err); };

    console.log("[SESSION] Successfully fetched the data!");
    console.log(result);
});

Example 1

Create a session if it does not exist, otherwise retrieve the exisiting session:

if(!sessionHandler.exists("my-session-name")){

    sessionHandler.create({
        ident: "my-session-name"

    }, function(err, session){
        if(err){ return console.log(err); };
        console.log("[SESSION] Successfully created!");
        console.log(session);

        //You may now connect via session.connect(...)
    });

}else{

    sessionHandler.retrieve("my-session-name", function(err, session){
        if(err){ return console.log(err); };
        console.log("[SESSION] Successfully retrieved!");
        console.log(session);

        //You may now connect via session.connect(...)
    });
}

Example 2 (recommended)

This example is the recommended approach.

sessionHandler.createOrRetrieve({
    ident: "my-session-name"

}, function(err, session, state){
    if(err){ return console.log(err); };

    if(state == 1){ console.log("Successfully created!"); }
    if(state == 2){ console.log("Successfully retrieved!"); }

    if(!session.online()){
        session.connect(function(err){
            if(err){ return console.log(err); };
            console.log("Successfully connected!");
        });
    }

});

How to install:

Use npm install @burnett01/c2b-session

Unit-Tests

The testing-framework used by this module is Mocha with the BDD / TDD assertion library Chai.

• test/test.default.js Performs 13 tests | Source

Simply run those tests as you please:

Make

make test

NPM

npm test

Use-case:

This module is used for a Twitch-like channel application.

Contributing

You're very welcome and free to contribute. Thank you.

License

MIT