Function throttleAndTrail

a throttle function, similar to throttle, that also insures that the final call (aka trailing call) made to the throttled function always resolves eventually.
this is useful in cases where it is of utmost importance that the throttled function is called one last time with before a prolonged delay.
the following visual illustration shows the difference between the regular throttle, and throttleAndTrail functions:

  • throttleAndTrail: fn throttled with trailing_time_ms = 1500, and delta_time_ms = 1000. as you can see below, the trailing calls to the throttled function do get resolved eventually
│time    │         ╭╶╶╮ 1.2            2.7   3.3            4.8 5.2         
├────────│       ╭╶┤  │ ┌───(delayed)──┐     ┌───(delayed)──┐   (rejected)  
│        │    ╭╶╶┤ │  │ │              ▼   ╭╶┤              ▼   ╭╶╶╶╶╶╶╶╮   
│resolved│  o ▼  ▼ ▼  o │              o o ▼ │              o o ▼       o   
│rejected│  │ x  x x  │ │                │ x │                │ x       │   
│calls───┼──┴─┴──┴─┴──┴─┴────────────────┴─┴─┴────────────────┴─┴───────┴──►
│time    │  0         1         2         3         4         5         6
  • throttle: fn throttled with delta_time_ms = 1000. as you can see below, the final call to the throttled function gets rejected, because it was called too quickly
│resolved│  o         o                  o                      
│rejected│  │ x  x x  │ x                │ x x                  
│calls───├──┴─┴──┴─┴──┴─┴────────────────┴─┴─┴─────────────────►
│time    │  0         1         2         3         4         5
  • throttleAndTrail<T, ARGS, REJ>(trailing_time_ms, delta_time_ms, fn, rejection_value?): ((...args: ARGS) => Promise<T>)

  • Type Parameters

    • T extends unknown
    • ARGS extends any[]
    • REJ

    Parameters

    • trailing_time_ms: number

      the time in milliseconds after which a trailing (pending) call to the function gets resolved if no other calls are made during that time interval. you would definitely want this to be some value greater than delta_time_ms, otherwise it will be weird because if this value is smaller, then trailing_time_ms will become the "effective" throttling time interval, but also one that always resolved later rather than immediately.

    • delta_time_ms: number

      the time interval in milliseconds for throttling

    • fn: ((...args: ARGS) => T)

      the function to be throttled

        • (...args): T

        • Parameters

          Returns T

    • Optionalrejection_value: REJ

      if a rejection value is provided, then old unresolved pending promises will be rejected with the given value, when a new call to the throttled function is made within the trailing_time_ms waiting period

    Returns ((...args: ARGS) => Promise<T>)

    a function (that takes arguments intended for fn) that returns a Promise to the value of fn if it is resolved (i.e. not throttled or when trailing), otherwise if throttled, then that promise will either be never be resolved, or rejected based on if a rejection_value was provided.

      • (...args): Promise<T>

      • Parameters

        Returns Promise<T>

Settings

Member Visibility