@paymoapp/real-idle

NodeJS library using native modules to detect the real idle state of the system.

Table of Contents

• What this library does
• Getting started
  • Installation
  • Native addon
  • Example
• API
  • Functions
  • Enums
• Platform support
  • Supported functions
  • Supported idle states
  • Default values

What this library does

Sometimes it's not enough to know how long ago the last input event from the user was, to determine the idle state of the system.

This library can detect on mac and linux if there's a background activity running (for example: watching a video or participating in a Zoom meeting) in which case the user shouldn't be treated as idle.

This is done by requesting the IOPM Assertions (on Mac) and using the IsInhibited DBUS function (on Linux).

Getting started

Installation

npm install --save @paymoapp/real-idle

The library requires NodeJS 20 or newer and ships both ESM and CommonJS builds, so you can import it or require() it.

Native addon

This project uses NodeJS Native Addons to function, so you can use this library in any NodeJS or Electron project. There won't be any problem with bundling and code signing.

The project uses prebuildify to supply prebuilt libraries. The prebuilt binaries for all supported platforms are bundled in the npm package and the correct one is picked at runtime by node-gyp-build, so there's no download or compilation step during installation.

The project uses Node-API version 6. You can check this table to see which node versions are supported.

If you want to build the native addon from source, you can run npm run build (which builds both the native addon and the TypeScript sources) — a local build in build/Release takes precedence over the bundled prebuilds.

The library has native addons for Windows, MacOS and Linux.

Example

You can run a demo application by calling npm run demo and you can tweak the parameters in the demo/electron.mjs file. For the demo, it is required to start an electron application since on MacOS a GUI session is required to access some functions (although you might get it working in a console application as well).

import RealIdle from '@paymoapp/real-idle';

setTimeout(() => {
	console.log('System idle state:', RealIdle.getIdleState(300));
	console.log('  - Idle seconds:', RealIdle.getIdleSeconds());
	console.log('  - Is screen locked:', RealIdle.getLocked());
	console.log('  - Is idle prevented:', RealIdle.getIdlePrevented());
}, 5000);

API

Functions

𝑓    getLocked

type getLocked = () => boolean

Returns true if the screen is locked and false if the screen is unlocked or if the function is not available on the current operating system.

Supported on: MacOS

𝑓    getIdleSeconds

type getIdleSeconds = () => number

Returns the system idle time in seconds, or -1 if the library couldn't fetch this value.

Supported on: Windows, MacOS, Linux (X11)

𝑓    getIdlePrevented

type getIdlePrevented = () => boolean

Returns true if the system idle is prevented (the screen would not automatically dim/lock). This is mostly the cause of having a video playing back in the front, attending a meeting, etc. The function returns false if no assertion or inhibitor is set or if the function is not available on the current operating system.

Supported on: MacOS, Linux (X11 and Gnome, but some other desktop environments should work too)

𝑓    getIdleState

type getIdleState = (idleThreshold: number): IdleState

Returns the idle state of the system based on the idle threshold (in seconds). It's supported on all operating systems, but see the Platform support section for the possible return values.

Supported on: Windows, MacOS, Linux (X11 and Gnome, but some other desktop environments should work too)

Enums

📋    IdleState

enum IdleState {
	active = 'active',
	idlePrevented = 'idle-prevented',
	idle = 'idle',
	locked = 'locked',
	unknown = 'unknown'
}

Meaning:

• active: The user is actively using the system.
• idlePrevented: Something (video playback, meeting, etc) is preventing the system from dimming the screen and locking it. The user may not input events into the system, but he/she is probably using it.
• idle: The user is idle.
• locked: The system is locked.
• unknown: We failed to fetch some parameter or the library is not available for the current operating system.

Platform support

Supported functions

| Function / Platform | Windows | MacOS | Linux | |----------------------|---------|-------|-------| | getLocked() | NO | YES | NO | | getIdleSeconds() | YES | YES | YES | | getIdlePrevented() | NO | YES | YES | | getIdleState() | YES* | YES | YES* |

* See supported idle states below

Supported idle states

| State / Platform | Windows | MacOS | Linux | |------------------|---------|-------|-------| | active | YES | YES | YES | | idlePrevented | NO | YES | YES | | idle | YES | YES | YES | | locked | NO | YES | NO | | unknown | YES | YES | YES |

Default values

Even if a function/idle state is unsupported on a specific platform, you can safely call them. They will just return the default value for that function.

| Function | Default value | |----------------------|---------------| | getLocked() | false | | getIdleSeconds() | -1 | | getIdlePrevented() | false | | getIdleState() | 'unknown' |