SessionEngine: Browser Session and Cache Lifecycle Tools

SessionEngine helps browser applications manage local session cache safely: TTL storage envelopes, corrupted-entry cleanup, prefix clearing, ownership markers, cross-tab logout signals, stale-session validation, and auth-aware fetch behavior.

It is designed for developers building authenticated SPAs, dashboards, account portals, or hybrid apps that cache user/session data in browser storage. Use it when you need to avoid stale auth state, cross-user cache leaks, inconsistent logout behavior across tabs, and repeated 401/429 fetch handling.

🤖 Ask your coding assistant

"Audit my codebase to see if adding the session-engine package on npm is beneficial. If so, explain why and draft an integration plan identifying session validation, ownership markers, cache prefixes, cross-tab logout behavior, and unauthorized/rate-limit handlers using the package README and source code."

---

Why use SessionEngine?

Feature	Without SessionEngine	With SessionEngine
TTL Cache Entries	Expiration metadata is duplicated and inconsistently parsed.	⏳ TTL Envelopes. createStorageCache() stores versioned TTL envelopes.
Corrupted Storage	Bad JSON can break app startup or hooks.	🧹 Automatic Cleanup. Corrupted entries are removed and treated as misses.
User Ownership	Cached data can survive account switches.	👤 Ownership Markers. Ownership markers clear cache when the user changes.
Cross-Tab Logout	One tab logs out while others keep stale state.	🔄 Cross-Tab Sync. Logout signals notify other tabs through storage events.
Fetch Behavior	Every callsite handles 401 and 429 differently.	⚡ Auth-Aware Fetch. createAuthFetch() centralizes unauthorized and rate-limit hooks.

---

Installation

Install SessionEngine via your preferred package manager:

# npm
npm install session-engine

# pnpm
pnpm add session-engine

# bun
bun add session-engine

# yarn
yarn add session-engine

---

Quick Start

import { SessionEngine } from "session-engine";

const session = new SessionEngine({
  namespace: "myapp",
  getCurrentUserId: () => currentUser.id,
  validateSession: async () => {
    const response = await fetch("/api/session");
    if (response.status === 401) return "invalid";
    if (!response.ok) return "inconclusive";
    return "valid";
  },
  onAuthCleared: (reason) => {
    window.location.assign("/login");
  },
});

session.start();

Validation callbacks can return true/"valid", false/"invalid", or "inconclusive". Invalid results clear auth state and can broadcast logout. Inconclusive results, such as transient network or 5xx failures, return false from validateSession() without clearing local auth caches.

---

Practical Examples

Use TTL storage

import { createStorageCache } from "session-engine";

const cache = createStorageCache({
  storage: window.localStorage,
});

cache.save("profile", { name: "Ada" }, { ttl: 5 * 60 * 1000 });
const profile = cache.get<{ name: string }>("profile");

Clear cache by prefix

import { clearStorageByPrefix } from "session-engine";

clearStorageByPrefix("account:", { storage: window.localStorage });

Handle auth-aware fetches

import { createAuthFetch } from "session-engine";

const authFetch = createAuthFetch({
  fetch: window.fetch.bind(window),
  onUnauthorized: () => session.signalLogout(),
  onRateLimit: async (response) => {
    console.warn("Rate limited", response.status);
  },
});

const response = await authFetch("/api/account");

Validate ownership

const session = new SessionEngine({
  namespace: "dashboard",
  getCurrentUserId: () => currentUser.id,
  clearUserCaches: () => {
    console.warn("Cleared cache for previous user");
  },
});

await session.validateOwnership();

---

API Reference

Export	Purpose
SessionEngine	Coordinates session validation, ownership markers, cache clearing, and logout signals.
createStorageCache(options)	Creates typed TTL cache helpers over localStorage-like storage.
createAuthFetch(options)	Wraps fetch with 401 and 429 hooks.
getFromStorage(key, ttl?, options?)	Reads a versioned TTL storage envelope from options.storage.
saveToStorage(key, value, storageOptions?, options?)	Saves a value to options.storage with TTL/version metadata.
removeFromStorage(key, options?)	Removes one key from options.storage.
clearStorageByPrefix(prefix, options?)	Removes all keys with a prefix from options.storage.
getStorageAge(key, options?)	Returns entry age in milliseconds, or null.

---

Development

To build the package and generate TypeScript declarations:

bun run build

To run the package unit tests:

bun run test

To run the package type check:

bun run typecheck

After building, verify the published runtime exports:

bun run test:smoke

---

Related Packages

• rate-engine for policy-driven rate limiting.
• boundary-engine for safe HTTP route boundaries.
• redact-engine for sensitive data redaction and safe logging.
• secret-engine for context-bound encryption and secret handling.

---

License

MIT © Christian Paul