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?

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

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