Version 1.0.0 - Production Release 🎉

View on npmjs.com

Table of Contents

• Table of Contents
• About
• Features
• Installation
• Quick Start
  • Basic Auto-Logout
  • Save Draft on Idle
• API Reference
  • Constructor
  • Time Formats
  • Methods
    • start()
    • stop()
    • reset()
    • isIdle()
    • isRunning()
    • getIdleTime()
    • getRemainingTime()
    • setTimeout(timeout)
    • getInfo()
    • destroy()
  • Events
• Examples
  • Auto-Logout with Warning
  • Video Player Whitelist
  • Activity Dashboard
  • Countdown Timer
• Browser Compatibility
• Contributing
  • Development Setup
  • Development Commands
• License
• Changelog
• Support

About

Luminexis is a lightweight, zero-dependency library for detecting user idle state in web applications. It monitors user activity (mouse, keyboard, touch) and triggers events when the user becomes idle. Built with TypeScript from the ground up, it provides type-safe idle detection for modern web applications.

Features

• Human-Readable Time: Use formats like '30s', '5m', '1h', '2d' instead of milliseconds
• Warning System: Fire events before idle trigger to warn users
• Whitelist: Ignore activity from specific elements (e.g., video players)
• Events: idle, active, warning, tick events for reactive programming
• TypeScript Support: Full type definitions included
• Cross-Tab Sync: Synchronize idle state across browser tabs
• Dynamic Configuration: Change timeout on the fly
• Zero Dependencies: Pure TypeScript implementation

Installation

npm install luminexis
# or
yarn add luminexis
# or
pnpm add luminexis
# or
bun add luminexis

Quick Start

Basic Auto-Logout

import Luminexis from "luminexis";

const idle = new Luminexis({
  timeout: "15m",
  warning: "1m",
  immediate: true,
});

idle.on("warning", () => {
  showNotification("You will be logged out in 1 minute due to inactivity");
});

idle.on("idle", () => {
  logout();
  window.location.href = "/login";
});

Save Draft on Idle

import Luminexis from "luminexis";

const idle = new Luminexis({ timeout: "30s" });

idle.on("idle", () => {
  saveDraft();
  showNotification("Draft auto-saved");
});

idle.on("active", () => {
  console.log("User is back");
});

idle.start();

API Reference

Constructor

new Luminexis(options?: LuminexisOptions)

Constructor Options:

| Option | Type | Default | Description | | ----------- | ------------------ | -------------- | -------------------------------------------- | | timeout | string \| number | '5m' | Idle timeout duration (e.g., '5m', '1h') | | warning | string \| number | null | Warning time before idle trigger | | events | string[] | Default events | Events that reset idle timer | | whitelist | string[] | [] | CSS selectors for elements to ignore | | immediate | boolean | false | Start monitoring immediately |

Time Formats

• '30s' - 30 seconds
• '5m' - 5 minutes
• '1h' - 1 hour
• '1d' - 1 day
• '1w' - 1 week
• '1h30m' - 1 hour 30 minutes
• '2d12h' - 2 days 12 hours

Methods

start()

Begin monitoring user activity.

const idle = new Luminexis({ timeout: "10m" });
idle.start();

stop()

Pause monitoring without resetting state.

idle.stop();

reset()

Manually reset the idle timer.

document.getElementById("custom-btn").addEventListener("click", () => {
  idle.reset();
});

isIdle()

Check if user is currently idle.

if (idle.isIdle()) {
  console.log("User is AFK");
}

isRunning()

Check if monitoring is active.

console.log(idle.isRunning()); // true or false

getIdleTime()

Get how long user has been idle (in milliseconds).

const idleMs = idle.getIdleTime();
console.log(`Idle for ${idleMs / 1000} seconds`);

getRemainingTime()

Get time remaining until idle trigger (in milliseconds).

const remainingMs = idle.getRemainingTime();
console.log(`Idle in ${remainingMs / 1000} seconds`);

setTimeout(timeout)

Dynamically change the timeout.

idle.setTimeout("30m"); // Extend to 30 minutes

getInfo()

Get current configuration and state.

const info = idle.getInfo();
console.log(info);
// {
//   timeout: 300000,
//   timeoutFormatted: '5m',
//   warning: 60000,
//   warningFormatted: '1m',
//   isIdle: false,
//   isRunning: true,
//   idleTime: 0,
//   remainingTime: 240000,
//   events: [...],
//   whitelist: [...]
// }

destroy()

Complete cleanup for SPA navigation.

window.addEventListener("beforeunload", () => {
  idle.destroy();
});

Events

| Event | Callback | Description | | --------- | ------------------------------- | ------------------------------------ | | idle | () => void | Fired when user becomes idle | | active | () => void | Fired when user returns from idle | | warning | (remainingMs: number) => void | Fired when warning threshold reached | | tick | (idleTime: number) => void | Fired every second while idle |

Examples

Auto-Logout with Warning

const idle = new Luminexis({
  timeout: "15m",
  warning: "1m",
  immediate: true,
});

idle.on("warning", () => {
  showModal("Your session will expire in 1 minute. Click to stay logged in.");
});

idle.on("idle", () => {
  logout();
  window.location.href = "/login";
});

Video Player Whitelist

const idle = new Luminexis({
  timeout: "5m",
  whitelist: [".video-player", ".live-stream", "[data-idle-ignore]"],
  immediate: true,
});

// User watching video won't trigger idle
// But clicking outside the player will reset the timer

Activity Dashboard

const idle = new Luminexis({ timeout: "1h" });

idle.on("tick", (idleTime) => {
  const minutes = Math.floor(idleTime / 1000 / 60);
  document.getElementById("idle-timer").textContent = `Idle: ${minutes}m`;
});

idle.on("active", () => {
  document.getElementById("status").textContent = "Active";
  document.getElementById("status").className = "badge green";
});

idle.on("idle", () => {
  document.getElementById("status").textContent = "Away";
  document.getElementById("status").className = "badge gray";
});

idle.start();

Countdown Timer

const idle = new Luminexis({ timeout: "5m" });

function updateCountdown() {
  const remaining = idle.getRemainingTime();
  const seconds = Math.ceil(remaining / 1000);
  document.getElementById("countdown").textContent = `${seconds}s`;
}

setInterval(updateCountdown, 1000);
idle.start();

Browser Compatibility

| Browser | Minimum Version | | ------- | --------------- | | Chrome | 90+ | | Firefox | 88+ | | Safari | 14+ | | Edge | 90+ |

Contributing

Contributions are welcome! Please see AGENTS.md for guidelines.

Development Setup

git clone https://github.com/dotjumpdot/luminexis.git
cd luminexis
bun install

Development Commands

bun run build          # Build TypeScript
bun run test           # Run tests
bun run test:watch     # Run tests in watch mode
bun run test:coverage  # Run tests with coverage
bun run lint           # Run linter

License

MIT License - Copyright (c) 2026 DotJumpDot

Changelog

See CHANGELOG.md for version history.

Support

• GitHub Issues: Report a bug
• Documentation: Full API Reference
• npm Package: luminexis

Made with ❤️ by DotJumpDot

⬆ Back to Top