pg-sess

pg-sess is meant to provide a flexible solution to storing session data using PostgreSQL in conjunction with pg-promise.

Install

$ npm i pg-sess

Usage

Importing

const pgSess = require('pg-sess').default;

Initiation

When initiating pg-sess, you must pass your pg-promise pgp, your connection db, the fields you would like to store FIELDS, and the expiration date SLENGTH (default 2 weeks).

Upon initiation, pg-sess will create a table of the following form:

| | sess | | | -- | ---- | ---- | | PK | sess_id | UUID | | | sess_creation_date | TIMESTAMP | | | sess_last_updated | TIMESTAMP | | | sess_expiration | TIMESTAMP |

Any fields passed through FIELDS will be created as well.

FIELDS must be passed as an object of the following form:

const FIELDS = [
    { field, datatype },
    { field, datatype },
    // examples
    { field: username, datatype: 'VARCHAR(255)' },
    { field: user_id, datatype: 'INT' }
]

SLENGTH is an integer that represents a time value in ms that will specify the time following creation that the session will expire. If no SLENGTH value is passed the default 2 weeks (14 * 24 * 60 * 60 * 1000) will be used.

Following this you can initiate pg-sess with:

pgSess.init(pgp, db, FIELDS, SLENGTH?);

If using Express, this can go in your app.js file.

Creating Session

When creating session you can utilize method:

const SINFO = pgSess.createSession(pgp, db, FIELDS);

Where SINFO will return object containing sess_id.

FIELDS must be an object of form:

const FIELDS = [
    { field, value },
    { field, value },
    // examples
    { field: username, value: username }
    { field: user_id, value: 1 }
]

IMPORTANT: This will simply add the session information to the database. For storing session data in browser you can, if using Express, use res.cookie to store sess_id in browser.

Validating Session

If you need to validate if a user has a valid session you can utilize method:

const isValidSession = await pgSess.validateSession(pgp, db, SID);

where SID is the UUID generated upon session creation.

This will return all session data with corresponding sess_id that has not yet expired. If no valid session is found null will be returned.

If you simply need to check for session existence, you can use isValidSession as a boolean that will be truthy when a valid session is found a falsy when no valid session is found.

If you need to utilize the stored fields for further validation, you can call them with isValidSession.field_name.

EXAMPLE:

const isValidSession = await pgSess.validateSession(pgp, db, sess_id);
if (isValidSession) {
    if (isValidSession.user_id === user_id) {
        return next()
    } else {
        return res.status(401).json({ message: 'Unauthorized.' });
    }
} else {
    return res.redirect('/login');
}

Extending Session

If you would like to extend a session's expiration data, you can utilize method:

await pgSess.extendSession(pgp, db, SID);

This will update sess_last_updated to current datetime and update sess_expiration based on initial SLENGTH value set on initiation.

Destroying Session

To destroy a session you can utilize method:

await pgSess.destroySession(pgp, db, SID);

IMPORTANT: This will simply remove the entry from the database. If using in conjunction with Express and res.cookie, you will still have to call res.clearCookie to remove session data from browser.

Version History

pg-sess V0.7.5 [current]

Features:

• Initiate session by creating sess_table
  • Accept user inputted FIELDS
  • Accept most PostgreSQL datatypes
  • Accept custom expiration length
• Create sessions
  • Auto generate sess_id, sess_creation_date, sess_last_updated, sess_expiration
  • Input into user created FIELDS
• Validate sessions
• Extend sessions
• Destroy sessions

Future Plans:

• Automatically refresh sess_id at user inputted interval with default if unspecified
• Automatically prune expired sessions
• Support for all PostgreSQL datatypes