https://github.com/stevenmhunt/setidle
Monitors your JS application for when the user is idle and triggers events.
https://github.com/stevenmhunt/setidle
Last synced: 3 months ago
JSON representation
Monitors your JS application for when the user is idle and triggers events.
- Host: GitHub
- URL: https://github.com/stevenmhunt/setidle
- Owner: stevenmhunt
- License: mit
- Created: 2016-09-01T01:19:42.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2016-09-06T05:13:11.000Z (almost 9 years ago)
- Last Synced: 2025-04-23T22:04:52.737Z (3 months ago)
- Language: JavaScript
- Size: 22.5 KB
- Stars: 58
- Watchers: 6
- Forks: 2
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# setIdle()
Monitors your JS application for when the user is idle and triggers events.
var idle = setIdle(() => doSomething('awesome'));
## Installation
### NPM
> npm install setidle
### Bower
> bower install setidle
### The old-fashioned way
## Background
Does your JavaScript front-end send back telemetry or do other activities that aren't time sensitive?
If so, then a simple way to improve the performance of your application is to queue up those requests
until the application is "idle", for example if a user is reading something and not causing the UI to
process anything. This can help to ensure that your complex interactions remain smooth, and that you're
only running code when you absolutely have the resources to do so, especially on mobile.
[[Giphy](http://gph.is/1nF4c0i)]
## Features
- Simple no-nonsense browser implementation based on `window.setTimeout`.
- Class constructor which wraps event emitters with reasonable duck-typing support.
- Can be configured to work on a specific HTML element or the entire document.
## Examples
### CommonJS/Node
var SetIdle = require('setidle');
var idle = new SetIdle(emitter);
idle.start(() => doSomething('awesome'));
### RequireJS
require(['setidle'], function (SetIdle) {
var idle = new SetIdle(emitter);
idle.start(() => doSomething('awesome'));
});
### Browser
var element = document.getElementById('panelStuff');
var idle = new SetIdle(new SetIdle.DOMEventEmitter(element));
idle.start(() => doSomething('awesome'));
## Usage
### SetIdle (emitter)
- Constructs an idle monitor.
- The `SetIdle` constructor expects a single parameter *emitter*, which has either an `on()` or `addListener()` method, and an `off()` or `removeListener()` method.
- It is compatible with the [NodeJS EventEmitter class in the *events* API](https://nodejs.org/api/events.html#events_class_eventemitter).
### SetIdle.start (fnIdle, [fnActive], [config])
- Starts monitoring of the given event emitter.
- The `fnIdle` callback will be triggered when the application is idle.
- The `fnActive` callback will be triggered when the application is active again.
- The `config` object is expected to take the following form. These are defaults if no config is provided:
```javascript
{
/**
* How long to wait for event silence before declaring the application as idle.
*/
interval: 3000,
/**
* A list of events to use in order to determine when the system is in use.
*/
events: [
// The user is interacting with the page.
'change',
'click',
'dblclick',
'scroll',
'touchstart',
'touchend',
// watch for indications that the browser is having to re-paint the page.
'resize',
'mutated' // this is a virtual event, we're using MutationObserver under the hood.
]
}
```
### SetIdle.stop()
- Stops all monitoring activity.
### window.setIdle (fnIdle, [fnActive], [interval])
- Modeled after `window.setTimeout`
- The `fnIdle` callback will be triggered when the application is idle.
- The `fnActive` callback will be triggered when the application is active again.
- The interval defines how many milliseconds of inactivity constitutes "idleness". The default is 3000 milliseconds.
- Note that the procedural version automatically passes `window.document` to the `DOMEventEmitter` constructor.
- Returns an instance of the SetIdle object used to start monitoring.
### window.clearIdle (idle)
- Modeled after `window.clearTimeout`
- Stops the given SetIdle instance by calling the `SetIdle.stop` method.
## Contributing
Contributions and pull requests are welcome! If you see a feature that you want, add it to our issue tracker. If you find a bug, definitely report back to us.