modules/utils/timing.js

  1. /*
  2.  * Copyright (c) 2017-2018 Thomas Otterson
  3.  *
  4.  * Permission is hereby granted, free of charge, to any person obtaining a copy of
  5.  * this software and associated documentation files (the "Software"), to deal in
  6.  * the Software without restriction, including without limitation the rights to
  7.  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
  8.  * the Software, and to permit persons to whom the Software is furnished to do so,
  9.  * subject to the following conditions:
  10.  *
  11.  * The above copyright notice and this permission notice shall be included in all
  12.  * copies or substantial portions of the Software.
  13.  *
  14.  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15.  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
  16.  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
  17.  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
  18.  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  19.  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  20.  */
  22. /**
  23.  * A set of channel utilities for changing the timing of inputs being put onto the input channel.
  24.  *
  25.  * @module cispy/utils/timing
  26.  * @private
  27.  */
  29. const { chan, timeout, close, CLOSED } = require('../channel');
  30. const { put, alts } = require('../ops');
  32. function isNumber(x) {
  33.   return Object.prototype.toString.call(x) === '[object Number]' && isFinite(x);
  34. }
  36. /**
  37.  * **Debounces an input channel.**
  38.  *
  39.  * Debouncing is the act of turning several input values into one. For example, debouncing a channel driven by a
  40.  * `mousemove` event would cause only the final `mousemove` event to be put onto the channel, dropping all of the other
  41.  * ones. This can be desirable because `mousemove` events come in bunches, being produced continually while the mouse is
  42.  * moving, and often all that we really care about is to learn where the mouse ended up.
  43.  *
  44.  * This function does this by controlling which values that have been put onto the source channel are made available on
  45.  * the destination channel, and when.
  46.  *
  47.  * The `delay` parameter determines the debounce threshold. Once the first value is put onto the source channel,
  48.  * debouncing is in effect until the number of milliseconds in `delay` passes without any other value being put onto
  49.  * that channel. In other words, the delay will be refreshed if another value is put onto the source channel before the
  50.  * delay elapses. After a full delay interval passes without a value being placed on the source channel, the last value
  51.  * put becomes available on the destination channel.
  52.  *
  53.  * This behavior can be modified through four options: `leading`, `trailing`, `maxDelay`, and `cancel`.
  54.  *
  55.  * If both `leading` and `trailing` are `true`, values will not be duplicated. The first value put onto the source
  56.  * channel will be put onto the destination channel immediately (per `leading`) and the delay will begin, but a value
  57.  * will only be made available on the destination channel at the end of the delay (per `trailing`) if *another* input
  58.  * value was put onto the source channel before the delay expired.
  59.  *
  60.  * @memberOf module:cispy/utils~CispyUtils
  61.  * @param {module:cispy/channel~Channel} src The source channel.
  62.  * @param {(number|module:cispy/buffers~Buffer)} [buffer=0] A buffer used to create the destination channel. If
  63.  *     this is a number, a {@link module:cispy/buffers~FixedBuffer|FixedBuffer} of that size will be used. If this is
  64.  *     `0` or not present, the channel will be unbuffered.
  65.  * @param {number} delay The debouncing delay, in milliseconds.
  66.  * @param {Object} [options={}] A set of options to further configure the debouncing.
  67.  * @param {boolean} [options.leading=false] Instead of making a value available on the destination channel after the
  68.  *     delay passes, the first value put onto the source channel is made available *before* the delay begins. No value
  69.  *     is available on the destination channel after the delay has elapsed (unless `trailing` is also `true`).
  70.  * @param {boolean} [options.trailing=true] The default behavior, where a value is not made available on the destination
  71.  *     channel until the entire delay passes without a new value being put on the source channel.
  72.  * @param {number} [options.maxDelay=0] The maximum delay allowed before a value is put onto the destination channel.
  73.  *     Debouncing can, in theory, go on forever as long as new input values continue to be put onto the source channel
  74.  *     before the delay expires. Setting this option to a positive number sets the maximum number of milliseconds that
  75.  *     debouncing can go on before it's forced to end, even if in the middle of a debouncing delay. Having debouncing
  76.  *     end through the max delay operates exactly as if it had ended because of lack of input; the last input is made
  77.  *     available on the destination channel (if `trailing` is `true`), and the next input will trigger another debounce
  78.  *     operation.
  79.  * @param {module:cispy/channel~Channel} [options.cancel] A channel used to signal a cancellation of the
  80.  *     debouncing. Any value put onto this channel will cancel the current debouncing operation, closing the output
  81.  *     channel and discarding any values that were waiting for the debounce threshold timer to be sent to the output.
  82.  * @return {module:cispy/channel~Channel} The newly-created destination channel, where all of the values will be
  83.  *     debounced from the source channel.
  84.  */
  85. function debounce(src, buffer, delay, options) {
  86.   const defaults = { leading: false, trailing: true, maxDelay: 0, cancel: chan() };
  87.   const buf = isNumber(delay) ? buffer : 0;
  88.   const del = isNumber(delay) ? delay : buffer;
  89.   const opts = Object.assign(defaults, (isNumber(delay) ? options : delay) || {});
  91.   const dest = chan(buf);
  92.   const { leading, trailing, maxDelay, cancel } = opts;
  94.   async function loop() {
  95.     let timer = chan();
  96.     let max = chan();
  97.     let current = CLOSED;
  99.     for (;;) {
  100.       const { value, channel } = await alts([src, timer, max, cancel]);
  102.       if (channel === cancel) {
  103.         close(dest);
  104.         break;
  105.       }
  106.       if (channel === src) {
  107.         if (value === CLOSED) {
  108.           close(dest);
  109.           break;
  110.         }
  112.         const timing = timer.timeout;
  113.         timer = timeout(del);
  115.         if (!timing && maxDelay > 0) {
  116.           max = timeout(maxDelay);
  117.         }
  119.         if (leading) {
  120.           if (!timing) {
  121.             await put(dest, value);
  122.           } else {
  123.             current = value;
  124.           }
  125.         } else if (trailing) {
  126.           current = value;
  127.         }
  128.       } else {
  129.         timer = chan();
  130.         max = chan();
  131.         if (trailing && current !== CLOSED) {
  132.           await put(dest, current);
  133.           current = CLOSED;
  134.         }
  135.       }
  136.     }
  137.   }
  139.   loop();
  140.   return dest;
  141. }
  143. /**
  144.  * **Throttles an input channel.**
  145.  *
  146.  * Throttling is the act of ensuring that something only happens once per time interval. In this case, it means that a
  147.  * value put onto the source channel is only made available to the destination channel once per a given number of
  148.  * milliseconds. An example usage would be with window scroll events; these events are nearly continuous as scrolling is
  149.  * happening, and perhaps we don't want to call an expensive UI updating function every time a scroll event is fired. We
  150.  * can throttle the input channel and make it only offer up the scroll events once every 100 milliseconds, for instance.
  151.  *
  152.  * Throttling is effected by creating a new channel as a throttled destination for values put onto the source channel.
  153.  * Values will only appear on that destination channel once per delay interval; other values that are put onto the
  154.  * source channel in the meantime are discarded.
  155.  *
  156.  * The `delay` parameter controls how often a value can become available on the destination channel. When the first
  157.  * value is put onto the source channel, it is immediately put onto the destination channel as well and the delay
  158.  * begins. Any further values put onto the source channel during that delay are *not* passed through; only when the
  159.  * delay expires is the last input value made available on the destination channel. The delay then begins again, so that
  160.  * further inputs are squelched until *that* delay passes. Throttling continues, only allowing one value through per
  161.  * interval, until an entire interval passes without input.
  162.  *
  163.  * This behavior can be modified by three options: `leading`, `trailing`, and `cancel`.
  164.  *
  165.  * If both `leading` and `trailing` are `true`, values will not be duplicated. The first value put onto the source
  166.  * channel will be put onto the destination channel immediately (per `leading`) and the delay will begin, but a value
  167.  * will only be made available on the destination channel at the end of the delay (per `trailing`) if *another* input
  168.  * value was put onto the source channel before the delay expired.
  169.  *
  170.  * @memberOf module:cispy/utils~CispyUtils
  171.  * @param {module:cispy/channel~Channel} src The source channel.
  172.  * @param {(number|module:cispy/buffers~Buffer)} [buffer=0] A buffer used to create the destination channel. If
  173.  *     this is a number, a {@link module:cispy/buffers~FixedBuffer|FixedBuffer} of that size will be used. If this is
  174.  *     `0` or not present, the channel will be unbuffered.
  175.  * @param {number} delay The throttling delay, in milliseconds.
  176.  * @param {Object} [options={}] A set of options to further configure the throttling.
  177.  * @param {boolean} [options.leading=true] Makes the value that triggered the throttling immediately available on the
  178.  *     destination channel before beginning the delay. If this is `false`, the first value will not be put onto the
  179.  *     destination channel until a full delay interval passes.
  180.  * @param {boolean} [options.trailing=true] Makes the last value put onto the source channel available on the
  181.  *     destination channel when the delay expires. If this is `false`, any inputs that come in during the delay are
  182.  *     ignored, and the next value is not put onto the destination channel until the first input *after* the delay
  183.  *     expires.
  184.  * @param {module:cispy/channel~Channel} [options.cancel] A channel used to signal a cancellation of the
  185.  *     throttling. Any value put onto this channel will cancel the current throttling operation, closing the output
  186.  *     channel and discarding any values that were waiting for the throttle threshold timer to be sent to the output.
  187.  * @return {module:cispy/channel~Channel}} The newly-created destination channel, where all of the values will be
  188.  *     throttled from the source channel.
  189.  */
  190. function throttle(src, buffer, delay, options) {
  191.   const defaults = { leading: true, trailing: true, cancel: chan() };
  192.   const buf = isNumber(delay) ? buffer : 0;
  193.   const del = isNumber(delay) ? delay : buffer;
  194.   const opts = Object.assign(defaults, (isNumber(delay) ? options : delay) || {});
  196.   const dest = chan(buf);
  197.   const { leading, trailing, cancel } = opts;
  199.   async function loop() {
  200.     let timer = chan();
  201.     let current = CLOSED;
  203.     for (;;) {
  204.       const { value, channel } = await alts([src, timer, cancel]);
  206.       if (channel === cancel) {
  207.         close(dest);
  208.         break;
  209.       } else if (channel === src) {
  210.         if (value === CLOSED) {
  211.           close(dest);
  212.           break;
  213.         }
  215.         const timing = timer.timeout;
  216.         if (!timing) {
  217.           timer = timeout(del);
  218.         }
  220.         if (leading) {
  221.           if (!timing) {
  222.             await put(dest, value);
  223.           } else if (trailing) {
  224.             current = value;
  225.           }
  226.         } else if (trailing) {
  227.           current = value;
  228.         }
  229.       } else if (trailing && current !== CLOSED) {
  230.         timer = timeout(del);
  231.         await put(dest, current);
  232.         current = CLOSED;
  233.       } else {
  234.         timer = chan();
  235.       }
  236.     }
  237.   }
  239.   loop();
  240.   return dest;
  241. }
  243. module.exports = {
  244.   debounce,
  245.   throttle
  246. };