@analytics/session-utils — Tiny session utility library. One of the small, focused utility packages that power the analytics library, usable standalone.

Full documentation, synced from the package README:

A tiny session utility library in 820 bytes.

Exposes sessionData, getSession, setSession, extendSession, removeSession, getTabSession, setTabSession, getPageSession, & setPageSession functions.

This library will work with analytics or as a standalone import in your code.

There are three flavors of session:

• Persisted Sessions - saved as a cookie for 30min (getSession/setSession)
• Tab Sessions - saved until the tab/window is closed (getTabSession/setTabSession)
• Page Sessions - saved until the page changes (getPageSession/setPageSession)

See live demo.

How to install

Install @analytics/session-utils from npm.

npm install @analytics/session-utils

API

Below is the api for @analytics/session-utils. You can import only what you need & the rest will be tree-shaken out of your bundle.

sessionData

Generate a fresh session object with a unique id and creation timestamps. Does not persist anything.

import { sessionData } from '@analytics/session-utils'

const data = sessionData()
console.log('data', data)
/*
{
  id: 'xxxx-xxxx-xxxx-xxxx',
  created: 1600000000000,
  createdAt: '2020-09-13T12:26:40.000Z'
}
*/

getSession

Get the current persisted session from the cookie. If no session cookie exists, a new persisted session is created. Pass minutes to control the session timeout (default 30).

import { getSession } from '@analytics/session-utils'

const currentSession = getSession()
console.log('currentSession', currentSession)

// Get session with a custom timeout in minutes
const customSession = getSession(60)

setSession

Create & persist a new session as a cookie. Pass minutes for the timeout (default 30) and an optional extra object to merge additional data into the session.

import { setSession } from '@analytics/session-utils'

const newSessionInfo = setSession()
console.log('newSessionInfo', newSessionInfo)

// Set session with custom timeout & extra data
const sessionWithData = setSession(60, { plan: 'pro' })

extendSession

Extend the current persisted session, refreshing its expiration window. Pass minutes for the timeout and an optional extra object to merge in additional data.

import { extendSession } from '@analytics/session-utils'

const extended = extendSession()
console.log('extended', extended)

removeSession

Remove the persisted session cookie.

import { removeSession } from '@analytics/session-utils'

removeSession()

getTabSession

Get the current tab session. Tab sessions are stored in sessionStorage and persist until the browser tab/window is closed.

import { getTabSession } from '@analytics/session-utils'

const tabSession = getTabSession()
console.log('tabSession', tabSession)

setTabSession

Create & persist a new tab session in sessionStorage.

import { setTabSession } from '@analytics/session-utils'

const tabSession = setTabSession()
console.log('tabSession', tabSession)

getPageSession

Get the current page session. Page sessions are kept in memory and persist until the page changes.

import { getPageSession } from '@analytics/session-utils'

const pageSession = getPageSession()
console.log('pageSession', pageSession)

setPageSession

Create & persist a new page session in memory.

import { setPageSession } from '@analytics/session-utils'

const pageSession = setPageSession()
console.log('pageSession', pageSession)

About

Sessions are nested. A persisted session can span multiple tab sessions, and each tab session can span multiple page sessions.

┌─────────────────────────────────────────────────────────────────┐
│                        Persisted Session                        │
│                                                                 │
│   ┌──────────────────────────┐    ┌──────────────────────────┐  │
│   │       Tab Session        │    │       Tab Session        │  │
│   │                          │    │                          │  │
│   │  ┌────────────────────┐  │    │  ┌────────────────────┐  │  │
│   │  │    Page Session    │  │    │  │    Page Session    │  │  │
│   │  │                    │  │    │  │                    │  │  │
│   │  │                    │  │    │  │                    │  │  │
│   │  │                    │  │    │  │                    │  │  │
│   │  │                    │  │    │  │                    │  │  │
│   │  │                    │  │    │  │                    │  │  │
│   │  │                    │  │    │  │                    │  │  │
│   │  │                    │  │    │  │                    │  │  │
│   │  │                    │  │    │  │                    │  │  │
│   │  └────────────────────┘  │    │  └────────────────────┘  │  │
│   └──────────────────────────┘    └──────────────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘