Visit Session Persist

Visit Session Persist is a lightweight JavaScript library that manages cross-tab session data on the same visit. It uses localStorage combined with a heartbeat mechanism to track active tabs, ensuring that session data persists while at least one tab is open and is automatically cleared when all tabs are closed. This behavior forces re‑authentication on subsequent visits.

The library also handles modern browser background throttling and sleep states by listening for the Page Visibility API as well as experimental freeze/resume events.

Features

• Cross-Tab Session Persistence:
  Session data is shared across tabs on the same visit.

• Automatic Session Expiration:
  When the last active tab is closed (or its heartbeat stops), the session data is cleared automatically.

• Customizable Timing:
  Configure the heartbeat interval and stale threshold to suit your application and browser behavior.

• Modern Browser Compatibility:
  Uses visibilitychange, and experimental freeze/resume events to keep sessions updated even when tabs are throttled or suspended.

• Easy Integration:
  Plug directly into your existing state persistence solution (such as Redux Persist, Vuex Persist, or NgRx) with minimal configuration.

Installation

Install via npm:

npm install visit-session-persist

Or via Yarn:

yarn add visit-session-persist

Usage

Basic Integration

Import and create an instance of the storage adapter with custom options if desired:

import { createVisitSessionStorage } from 'visit-session-persist';

// Create an instance with custom options (optional)
const visitSessionStorage = createVisitSessionStorage({
  heartbeatInterval: 3000, // Heartbeat every 3 seconds
  staleThreshold: 7000,    // Mark a tab as stale if no heartbeat in 7 seconds
});

// Use the API directly
visitSessionStorage.setSessionData('user', { name: 'Alice' });
const user = visitSessionStorage.getSessionData('user');
console.log(user);

Integration with State Persistence Libraries

Redux Persist

import { createVisitSessionStorage } from 'visit-session-persist';
import storage from 'redux-persist/lib/storage';

const visitSessionStorage = createVisitSessionStorage();

const persistConfig = {
  key: 'root',
  storage: visitSessionStorage,
  // additional Redux Persist config...
};

// Then pass persistConfig to persistReducer in your Redux store setup.

Vuex Persist

import VuexPersistence from 'vuex-persist';
import { createVisitSessionStorage } from 'visit-session-persist';

const visitSessionStorage = createVisitSessionStorage();

const vuexLocal = new VuexPersistence({
  key: 'my-app',
  storage: visitSessionStorage,
});

// Include vuexLocal.plugin in your Vuex store plugins.

API

The library exposes the following methods:

• setSessionData(key, value):
  Stores a value (JSON-stringified) under the given key.

• getSessionData(key):
  Retrieves the value stored under the given key.

• removeSessionData(key):
  Removes the specified key from session storage.

• clearSession():
  Clears all session data.

In addition, the library automatically handles heartbeat updates and synchronization across tabs.

How It Works

1. Heartbeat Mechanism:
   Each tab updates its unique heartbeat in localStorage at the configured interval. Tabs that have not updated within the stale threshold are removed from the active tabs list.

2. Event Listeners for Throttling:

   • visibilitychange: Immediately updates the heartbeat when a tab becomes visible.
   • freeze/resume: Experimental events (supported in some browsers) that trigger updates when a tab is suspended or resumed.
   • pagehide/pageshow: Provide additional hooks for handling cache and suspension scenarios.

3. Session Cleanup:
   When all tabs are closed (i.e., no active heartbeat remains), the session data is cleared automatically, ensuring a fresh session on the next visit.

Contributing

Contributions are welcome! Please fork this repository, create your feature branch, and submit a pull request. For major changes, please open an issue first to discuss what you would like to change.

License

This project is licensed under the MIT License.