Module: Philiprehberger::Debounce

Defined in:
lib/philiprehberger/debounce.rb,
lib/philiprehberger/debounce/mixin.rb,
lib/philiprehberger/debounce/batcher.rb,
lib/philiprehberger/debounce/version.rb,
lib/philiprehberger/debounce/coalescer.rb,
lib/philiprehberger/debounce/debouncer.rb,
lib/philiprehberger/debounce/throttler.rb,
lib/philiprehberger/debounce/rate_limiter.rb,
lib/philiprehberger/debounce/keyed_debouncer.rb

Overview

Debounce and throttle decorators for Ruby method calls

Defined Under Namespace

Modules: Mixin Classes: Batcher, Coalescer, Debouncer, Error, KeyedDebouncer, RateLimiter, Throttler

Constant Summary collapse

VERSION = 
'0.10.0'

Class Method Summary collapse

Class Method Details

.batcher(size:, max_wait:, on_error: nil) {|Array| ... } ⇒ Batcher

Create a new size-and-time-triggered batcher.

Items pushed via ‘<<` or `push` are buffered until either `size` items accumulate or `max_wait` seconds elapse since the first buffered item, at which point the block is invoked with the buffered array.

Parameters:

  • size (Integer) —

    flush after this many items accumulate

  • max_wait (Numeric) —

    flush after this many seconds since the first item

  • on_error (Proc, nil) (defaults to: nil) —

    callback when the block raises

Yields:

  • (Array) —

    the buffered items

Returns:



103
104
105
 
# File 'lib/philiprehberger/debounce.rb', line 103

def self.batcher(size:, max_wait:, on_error: nil, &block)
  Batcher.new(size: size, max_wait: max_wait, on_error: on_error, &block)
end

.coalesce(wait:, on_error: nil) {|Array| ... } ⇒ Coalescer

Create a new coalescer that batches arguments into a single invocation.

Parameters:

  • wait (Numeric) —

    delay in seconds before flushing the batch

Yields:

  • (Array) —

    receives an array of argument arrays from all queued calls

Returns:



88
89
90
 
# File 'lib/philiprehberger/debounce.rb', line 88

def self.coalesce(wait:, on_error: nil, &block)
  Coalescer.new(wait: wait, on_error: on_error, &block)
end

.debounce(wait:, leading: false, trailing: true, max_wait: nil, on_execute: nil, on_cancel: nil, on_flush: nil, on_error: nil) {|*args| ... } ⇒ Debouncer

Create a new debouncer that delays execution until the wait period elapses without new calls.

Parameters:

  • wait (Float) —

    delay in seconds

  • leading (Boolean) (defaults to: false) —

    fire on the leading edge (default: false)

  • trailing (Boolean) (defaults to: true) —

    fire on the trailing edge (default: true)

  • max_wait (Float, nil) (defaults to: nil) —

    maximum time to wait before forcing execution

  • on_execute (Proc, nil) (defaults to: nil) —

    callback after block executes, receives return value

  • on_cancel (Proc, nil) (defaults to: nil) —

    callback when cancel is invoked

  • on_flush (Proc, nil) (defaults to: nil) —

    callback when flush is invoked

Yields:

  • (*args) —

    the block to execute after the debounce period

Returns:



29
30
31
32
33
34
 
# File 'lib/philiprehberger/debounce.rb', line 29

def self.debounce(wait:, leading: false, trailing: true, max_wait: nil, on_execute: nil, on_cancel: nil, on_flush: nil, on_error: nil, &block)
  Debouncer.new(
    wait: wait, leading: leading, trailing: trailing, max_wait: max_wait,
    on_execute: on_execute, on_cancel: on_cancel, on_flush: on_flush, on_error: on_error, &block
  )
end

.keyed(wait:, leading: false, trailing: true, max_wait: nil, max_keys: nil, on_execute: nil, on_cancel: nil, on_flush: nil, on_error: nil) {|*args| ... } ⇒ KeyedDebouncer

Create a new keyed debouncer that manages per-key debouncers.

Parameters:

  • wait (Float) —

    delay in seconds

  • leading (Boolean) (defaults to: false) —

    fire on the leading edge (default: false)

  • trailing (Boolean) (defaults to: true) —

    fire on the trailing edge (default: true)

  • max_wait (Float, nil) (defaults to: nil) —

    maximum time to wait before forcing execution

  • max_keys (Integer, nil) (defaults to: nil) —

    maximum number of keys to hold; oldest key is evicted when exceeded

  • on_execute (Proc, nil) (defaults to: nil) —

    callback after block executes, receives return value

  • on_cancel (Proc, nil) (defaults to: nil) —

    callback when cancel is invoked

  • on_flush (Proc, nil) (defaults to: nil) —

    callback when flush is invoked

Yields:

  • (*args) —

    the block to execute after the debounce period

Returns:



65
66
67
68
69
70
71
72
 
# File 'lib/philiprehberger/debounce.rb', line 65

def self.keyed(wait:, leading: false, trailing: true, max_wait: nil, # rubocop:disable Metrics/ParameterLists
               max_keys: nil, on_execute: nil, on_cancel: nil, on_flush: nil,
               on_error: nil, &block)
  KeyedDebouncer.new(
    wait: wait, leading: leading, trailing: trailing, max_wait: max_wait, max_keys: max_keys,
    on_execute: on_execute, on_cancel: on_cancel, on_flush: on_flush, on_error: on_error, &block
  )
end

.rate_limiter(limit:, window:) ⇒ RateLimiter

Create a new sliding window rate limiter.

Parameters:

  • limit (Integer) —

    maximum number of requests per window

  • window (Numeric) —

    window size in seconds

Returns:



79
80
81
 
# File 'lib/philiprehberger/debounce.rb', line 79

def self.rate_limiter(limit:, window:)
  RateLimiter.new(limit: limit, window: window)
end

.throttle(interval:, leading: true, trailing: false, on_execute: nil, on_cancel: nil, on_flush: nil, on_error: nil) {|*args| ... } ⇒ Throttler

Create a new throttler that limits execution to at most once per interval.

Parameters:

  • interval (Float) —

    minimum time between executions in seconds

  • leading (Boolean) (defaults to: true) —

    fire on the leading edge (default: true)

  • trailing (Boolean) (defaults to: false) —

    fire on the trailing edge (default: false)

  • on_execute (Proc, nil) (defaults to: nil) —

    callback after block executes, receives return value

  • on_cancel (Proc, nil) (defaults to: nil) —

    callback when cancel is invoked

  • on_flush (Proc, nil) (defaults to: nil) —

    callback when flush is invoked

Yields:

  • (*args) —

    the block to execute

Returns:



46
47
48
49
50
51
 
# File 'lib/philiprehberger/debounce.rb', line 46

def self.throttle(interval:, leading: true, trailing: false, on_execute: nil, on_cancel: nil, on_flush: nil, on_error: nil, &block)
  Throttler.new(
    interval: interval, leading: leading, trailing: trailing,
    on_execute: on_execute, on_cancel: on_cancel, on_flush: on_flush, on_error: on_error, &block
  )
end