Have ideas to improve npm?Join in the discussion! »

    raf-schd
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/raf-schd package

    4.0.3 • Public • Published

    raf-schd

    A throttle function that uses requestAnimationFrame to limit the rate at which a function is called.

    Build Status dependencies npm SemVer

    For background information on rate limiting functions, see Rate limiting functions from scratch

    import rafSchd from 'raf-schd';
    
    const expensiveFn = arg => {
      //...
      console.log(arg);
    };
    
    const schedule = rafSchd(expensiveFn);
    
    schedule('foo');
    schedule('bar');
    schedule('baz');
    
    // animation frame fires
    
    // => 'baz'

    Why?

    raf-schd supports the use case where you want to limit the rate at which your functions are called based on requestAnimationFrame. Unlike a standard throttle function, raf-schd uses requestAnimationFrame to rate limit, rather than waiting a fixed amount of time. Using requestAnimationFrame for throttling is powerful because the browser will automatically reduce the amount of frames provided based on the available resources. So if the browser only provides 30fps then your throttled function will only be called 30 times.

    raf-schd is an extremely useful performance utility.

    Without raf-schd

    Optimised scroll listener example taken from MDN

    var last_known_scroll_position = 0;
    var ticking = false;
    
    function doSomething(scroll_pos) {
      // do something with the scroll position
    }
    
    window.addEventListener('scroll', function(e) {
      last_known_scroll_position = window.scrollY;
      if (!ticking) {
        window.requestAnimationFrame(function() {
          doSomething(last_known_scroll_position);
          ticking = false;
        });
      }
      ticking = true;
    });

    With raf-schd

    import rafSchd from 'raf-schd';
    
    function doSomething(scroll_pos) {
      // do something with the scroll position
    }
    
    const schedule = rafSchd(doSomething);
    
    window.addEventListener('scroll', function() {
      schedule(window.scrollY);
    });

    At the top level raf-schd accepts any function a returns a new ResultFn (a function that wraps your original function).

    The ResultFn will execute your function with the latest arguments provided to it on the next animation frame.

    Throttled with latest argument

    import rafSchd from 'raf-schd';
    
    const doSomething = () => {...};
    
    const schedule = rafSchd(doSomething);
    
    schedule(1, 2);
    schedule(3, 4);
    schedule(5, 6);
    
    // animation frame fires
    
    // do something called with => '5, 6'

    Cancelling a frame with .cancel

    raf-schd adds a .cancel property to the ResultFn so that it can be easily cancelled. The frame will only be cancelled if it has not yet executed.

    const schedule = rafSchd(doSomething);
    
    schedule('foo');
    
    schedule.cancel();
    
    // now doSomething will not be executed in the next animation frame

    Types

    rafSchedule

    type rafSchedule = (fn: Function) => ResultFn;
    
    // Adding a .cancel property to the WrapperFn
    
    type WrapperFn = (...arg: mixed[]) => void;
    type CancelFn = {|
      cancel: () => void,
    |};
    type ResultFn = WrapperFn & CancelFn;

    Testing your code

    If you want to really ensure that your code is working how you intend it to - use raf-stub to test your animation frame logic.

    Installation

    # yarn
    yarn add raf-schd
    
    # npm
    npm install raf-schd --save

    Module usage

    ES6 module

    import rafSchd from 'raf-schd';

    CommonJS

    If you are in a CommonJS environment (eg Node), then you will need add .default to your import:

    const rafSchd = require('raf-schd').default;

    Install

    npm i raf-schd

    DownloadsWeekly Downloads

    1,113,108

    Version

    4.0.3

    License

    MIT

    Unpacked Size

    10.6 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar