idle-state

    0.3.0 • Public • Published

    introduce

    A library for detecting idle state of browser. None dependency, size of 4.7kb. With powerful APIs. -- inspired by idle-timeout.

    what I can do

    Running some tasks while browser idling

    install

    using npm or yarn

    npm install idle-state -S
    yarn add idle-state -S

    using cdn

    <script src="https://xxx.xx.xx/idle-state.min.js"></script>

    usage

    just pass a callback

    import idle from 'idle-state'
    
    const foo = () => {
      console.log('do task foo.')
    }
    // just pass a callback, `foo` will be called while browser idling
    idle(foo)

    pass a task-array

    import idle from 'idle-state'
    
    const task1 = () => console.log('do task1.')
    const task2 = () => console.log('do task2.')
    
    // tasks-array, `task1` & `task2` will be called while browser idling
    idle([task1, task2])

    config opitons or both callback & config options

    import idle from 'idle-state'
    
    const task1 = () => console.log('do task1.')
    const task2 = () => console.log('do task2.')
    
    // with config
    idle({
      tasks: [task1, task2],
    })
    
    // both callback & config options
    // in this case task1 & task2 will be converted to an tasks-array [task1, task2]
    idle(task1, { tasks: [task2] })

    document

    The idle function has two arguments

    • callback - can be a function or function-array
      • [Function] - considered a single task
      • [Function-array] - considered a tasks-array
    • options [Object] - configuration of how task running
      • target [Element | Element-Array] - the target would be watched, which determines whether the state is idling
      • tasks [Function-array] - tasks-array
      • timeout [Number] - the duration after the browser enters the idle state, at which time the task begins to execute
      • interval [Number] - interval of task runing
      • loop [Boolean] - should task(s) runs loopy
      • mousemoveDetect [Boolean] - should detect mousemove event. Mousemove events are frequently triggered in the browser, so put it configurable
      • reqeustDetect [Boolean] - should detect requests(ajax or fetch) on browser
      • events [EventName-array] - name of events, which would be concated(merged) with default value (scroll, keydown, touchmove, touchstart, click)
      • onPause [Function] - called on tasks pause
      • onResume [Function] - called on tasks resume
      • onDispose [Function] - called on tasks dispose

    options default value

    const noop = () => {}
    
    const defaultOptions = {
      target: document.body,
      tasks: [],
      timeout: 3000,
      interval: 1000,
      loop: false,
      mousemoveDetect: false,
      reqeustDetect: true,
      events: ['scroll', 'keydown', 'touchmove', 'touchstart', 'click'],
      onPause: noop,
      onResume: noop,
      onDispose: noop,
    }

    methods

    you can get an instance from idle() function

    import idle from 'idle-state'
    
    const instance = idle(() => {})

    instance

    • .pause(callback) - pause tasks running
    • .resume(callback) - resume paused tasks
    • .dispose(callback) - dispose the resource & remove events handler
    • .push(task-function) - push a task in current tasks-array
    • .timeout(time) - set options.timeout the duration after the browser enters the idle state, at which time the task begins to execute (in milliseconds)
    • .interval(time) - set options.interval the tasks running interval (in milliseconds)
    • .loop(boolean) - set options.loop should the tasks runs loopy
    • .isIdle - get current idle state, return a boolean value

    the callback passed by methods ( such as pause(callback) ) has a higher priority than options ( such as options.onPause )

    .pause(callback)

    instnce.pause()
    
    // with callback
    instance.pause(() => console.log('task paused.'))

    .resume(callback)

    instance.resume()
    
    // with callback
    instance.resume(() => console.log('paused task re-running.'))

    .dispose(callback)

    instance.dispose()
    
    // with callback
    instance.dispose(() => console.log('tasks stoped.'))

    .push(task)

    const task = () => console.log('I am a task.')
    // task should be a function
    instance.push(task)

    .timeout(time)

    instance.timeout(2000)

    .interval(time)

    instance.interval(2000)

    .loop(boolean)

    instance.loop(true)

    get current idle state

    import idle from 'idle-state'
    
    const instance = idle(() => {})
    
    // you can get current state by
    instance.isIdle // => get a Boolean value

    it will get false while browser trigger event [scroll, keydown, touchmove, touchstart, click] by default, you can config options.events, which will replace default options.events

    demo

    npm run dev

    build

    npm run build

    Install

    npm i idle-state

    DownloadsWeekly Downloads

    2

    Version

    0.3.0

    License

    MIT

    Unpacked Size

    48.1 kB

    Total Files

    7

    Last publish

    Collaborators

    • cloud_cb