@afex-dapps/idle-timer/dist/index.d.cts

Idle Timer library for detecting user inactivity and managing session timeouts

import { RefObject } from 'react';

interface IIdleTimer {
    /**
     * Restore initial state and restart timer.
     *
     * @returns whether the instance was started.
     */
    start(): boolean;
    /**
     * Restore initial state.
     *
     * @returns whether the instance was reset.
     */
    reset(): boolean;
    /**
     * Restore initial state and emit onActive if the user was prompted or idle.
     *
     * @returns whether the instance was activated.
     */
    activate(): boolean;
    /**
     * Store remaining time and stop timer.
     *
     * @returns whether the instance was paused.
     */
    pause(): boolean;
    /**
     * Resumes a paused timer.
     *
     * @returns whether the instance was resumed.
     */
    resume(): boolean;
    /**
     * Broadcast an arbitrary message to all instances of IdleTimer.
     *
     * @param data  Data to emit to `onMessage` callbacks.
     * @param emitOnSelf  Emit the event on the callee instance.
     *
     * @returns whether the message was sent.
     */
    message(data: string | number | object, emitOnSelf?: boolean): boolean;
    /**
    * Returns whether the user is idle.
    *
    * @returns Idle state.
    */
    isIdle(): boolean;
    /**
     * Returns whether the current tab is the leader.
     *
     * @returns Leader state.
     */
    isLeader(): boolean;
    /**
     * Returns whether the prompt is active.
     *
     * @returns Prompted state.
     */
    isPrompted(): boolean;
    /**
     * Returns whether this is the last active tab.
     *
     * @returns Last active state.
     */
    isLastActiveTab(): boolean;
    /**
     * Returns the current tabs id.
     */
    getTabId(): string;
    /**
     * Time remaining before idle or prompt.
     *
     * @returns Number of milliseconds until idle or prompt.
     */
    getRemainingTime(): number;
    /**
     * Time elapsed since last reset.
     *
     * @returns Number of milliseconds since the hook was last reset.
     */
    getElapsedTime(): number;
    /**
     * Time elapsed since mounted.
     *
     * @returns Number of milliseconds since the hook was mounted.
     */
    getTotalElapsedTime(): number;
    /**
     * Last time the user was idle.
     *
     * @returns A Date object that can be formatted.
     */
    getLastIdleTime(): Date | null;
    /**
     * Last time the user was active.
     *
     * @returns A Date object that can be formatted.
     */
    getLastActiveTime(): Date | null;
    /**
     * Time in milliseconds user has been idle since last reset.
     *
     * @returns Time in milliseconds the user has been idle.
     */
    getIdleTime(): number;
    /**
     * Total time in milliseconds user has been idle since the hook mounted.
     *
     * @returns Time in milliseconds the user has been idle.
     */
    getTotalIdleTime(): number;
    /**
     * Total time in milliseconds user has been active since last reset.
     *
     * @returns Time in milliseconds the user has been active.
     */
    getActiveTime(): number;
    /**
     * Total time in milliseconds user has been active since the hook mounted.
     *
     * @returns Time in milliseconds the user has been active.
     */
    getTotalActiveTime(): number;
}

type EventsType = 'abort' | 'afterprint' | 'animationend' | 'animationiteration' | 'animationstart' | 'beforeprint' | 'beforeunload' | 'blur' | 'canplay' | 'canplaythrough' | 'change' | 'click' | 'contextmenu' | 'copy' | 'cut' | 'dblclick' | 'DOMMouseScroll' | 'drag' | 'dragend' | 'dragenter' | 'dragleave' | 'dragover' | 'dragstart' | 'drop' | 'durationchange' | 'ended' | 'error' | 'focus' | 'focusin' | 'focusout' | 'fullscreenchange' | 'fullscreenerror' | 'gotpointercapture' | 'hashchange' | 'input' | 'invalid' | 'keydown' | 'keypress' | 'keyup' | 'load' | 'loadeddata' | 'loadedmetadata' | 'loadstart' | 'lostpointercapture' | 'message' | 'mousedown' | 'mouseenter' | 'mouseleave' | 'mousemove' | 'mouseover' | 'mouseout' | 'mouseup' | 'mousewheel' | 'MSPointerDown' | 'MSPointerMove' | 'offline' | 'online' | 'open' | 'pagehide' | 'pageshow' | 'paste' | 'pause' | 'play' | 'playing' | 'pointercancel' | 'pointerdown' | 'pointerenter' | 'pointerleave' | 'pointermove' | 'pointerout' | 'pointerover' | 'pointerup' | 'popstate' | 'progress' | 'ratechange' | 'resize' | 'reset' | 'scroll' | 'search' | 'seeked' | 'seeking' | 'select' | 'show' | 'stalled' | 'storage' | 'submit' | 'suspend' | 'timeupdate' | 'toggle' | 'touchcancel' | 'touchend' | 'touchmove' | 'touchstart' | 'transitionend' | 'unload' | 'volumechange' | 'waiting' | 'wheel' | 'visibilitychange';

type PresenceType = {
    type: 'idle';
} | {
    type: 'active';
    prompted: boolean;
};

interface ITimers {
    setTimeout(fn: () => void, delay: number): number;
    clearTimeout(id: number): void;
    setInterval(fn: () => void, delay: number): number;
    clearInterval(id: number): void;
}

interface IIdleTimerProps {
    /**
     * IdleTimer ref for class components.
     *
     * @default undefined
     */
    ref?: RefObject<IIdleTimer>;
    /**
     * Activity Timeout in milliseconds.
     *
     * @default 1200000
     */
    timeout?: number;
    /**
     * When the user becomes idle, the onPrompt function is called and
     * after the prompt timeout in milliseconds is reached, the onIdle function
     * is called.
     *
     * @default 0
     * @deprecated use promptBeforeIdle
     */
    promptTimeout?: number;
    /**
     * The amount of milliseconds before timeout to call the onPrompt event handler.
     *
     * @default 0
     */
    promptBeforeIdle?: number;
    /**
     * Element to bind activity listeners to.
     *
     * @default document
     */
    element?: Document | HTMLElement;
    /**
     * DOM events to watch for activity on.
     *
     * @default DefaultEvents
     * @link [default events](https://idletimer.dev/docs/props#events).
     */
    events?: EventsType[];
    /**
     * DOM events that will bypass the timeout and immediately emit onPrompt/onIdle
     * events. The events in this array take precedence over the events array.
     *
     * @default []
     */
    immediateEvents?: EventsType[];
    /**
     * Function to call when the users presence state changes.
     *
     * @default () => {}
     */
    onPresenceChange?: (presence: PresenceType, idleTimer?: IIdleTimer) => void;
    /**
     * When promptTimeout is set, this function is called after the user becomes
     * idle. This is useful for displaying a confirm prompt. If the prompt timeout
     * is reached, onIdle is then called.
     *
     * @default () => {}
     */
    onPrompt?: (event?: Event, idleTimer?: IIdleTimer) => void;
    /**
     * Function to call when user is idle.
     *
     * @default () => {}
     */
    onIdle?: (event?: Event, idleTimer?: IIdleTimer) => void;
    /**
     * Function to call when user becomes active.
     *
     * @default () => {}
     */
    onActive?: (event?: Event, idleTimer?: IIdleTimer) => void;
    /**
     * Function to call on user activity. Can be throttled or debounced using the
     * `throttle` and `debounce` props.
     *
     * @default () => {}
     */
    onAction?: (event?: Event, idleTimer?: IIdleTimer) => void;
    /**
     * Function to call when message is has been emitted.
     *
     * @default () => {}
     */
    onMessage?: (data: any, idleTimer?: IIdleTimer) => void;
    /**
     * Debounce the onAction function by setting delay in milliseconds.
     *
     * @default 0
     */
    debounce?: number;
    /**
     * Throttle the onAction function by setting delay in milliseconds.
     *
     * @default 0
     */
    throttle?: number;
    /**
     * Throttle the activity events. Useful if you are listening to mouse events.
     * Helps to cut down on cpu usage.
     *
     * @default 200
     */
    eventsThrottle?: number;
    /**
     * Start the timer when the hook mounts.
     *
     * @default true
     */
    startOnMount?: boolean;
    /**
     * Require the timer to be started manually.
     *
     * @default false
     */
    startManually?: boolean;
    /**
     * Once the user goes idle the IdleTimer will not reset on user input instead,
     * start() or reset() must be called manually to restart the timer.
     *
     * @default false
     */
    stopOnIdle?: boolean;
    /**
     * Timer interface to use. By default the main thread timers are used to keep
     * the module tree shakeable. If you want to use worker timers, import them
     * and set them here.
     *
     * @default Main Thread Timers
     */
    timers?: ITimers;
    /**
     * Enable cross tab event replication.
     *
     * @default false
     */
    crossTab?: boolean;
    /**
     * Name of this IdleTimer instance. Useful if you are instantiating multiple
     * IdleTimer instances with crossTab enabled.
     */
    name?: string;
    /**
     * Sync the timers across all tabs. The value is the interval in which timers
     * will be synced. Setting it to 0 is equivalent to turning the feature off.
     *
     * @default 0
     */
    syncTimers?: number;
    /**
     * Enables the leader election feature. Leader Election will assign one tab to
     * be the leader. Determine if a tab is leader using the `isLeader` method.
     */
    leaderElection?: boolean;
    /**
     * Disables the timer. Disabling the timer resets the internal state.
     * When the property is set to true (enabled), the timer will be restarted,
     * respecting the `startManually` property. When the timer is disabled
     * the control methods `start`, `reset`, `activate`, `pause` and `resume`
     * will not do anything.
     */
    disabled?: boolean;
}

interface UseIdleTimer {
    /**
     * Remaining time in seconds before the user is considered idle.
     */
    remainingTime: number;
    /**
     * Callback to continue the user session, typically called when the user interacts with the prompt.
     */
    continueUserSession: () => void;
    /**
     * Whether to show the idle timer prompt.
     */
    showIdleTimerPrompt: boolean;
    /**
     * The idle timer instance used for managing idle state.
     */
    idleTimer: IIdleTimer;
}

/**
 * Custom hook to manage idle timeout functionality
 *
 * @param config Configuration object for idle timer
 * @returns Object containing remaining time, continueUserSession function, and idle timer instance
 */
declare function useIdleTimeout(config?: IIdleTimerProps): UseIdleTimer;

/**
 * Debug hook for idle timer - logs timer state at regular intervals
 *
 * @param timer The idle timer instance to debug
 * @param enabled Whether debugging is enabled (default: false)
 */
declare const useIdleTimerDebug: (idleTimer: IIdleTimer, enabled?: boolean) => {
    isIdle: boolean;
    isPrompted: boolean;
    remainingTime: number;
    elapsedTime: number;
    totalActiveTime: number;
    totalIdleTime: number;
    totalElapsedTime: number;
};

/**
 * Formats time in milliseconds to a readable countdown format (MM:SS or H:MM:SS)
 *
 * @param ms Time in milliseconds to format
 * @returns Formatted time string (e.g., "05:30" or "1:05:30")
 */
declare const formatTime: (ms: number) => string;

/**
 * Formats milliseconds to seconds
 * @param milliseconds Time in milliseconds
 * @returns Time in seconds
 */
declare const millisecondsToSeconds: (milliseconds: number) => number;

/**
 * Formats seconds to milliseconds
 * @param seconds Time in seconds
 * @returns Time in milliseconds
 */
declare const secondsToMilliseconds: (seconds: number) => number;

export { formatTime, millisecondsToSeconds, secondsToMilliseconds, useIdleTimeout, useIdleTimerDebug };