
#########
Debouncer
#########

.. js:class:: ui.Debouncer

   A utility class that delays the execution of a callback function until after a specified delay period has elapsed since the last time it was invoked. This is useful for optimizing performance by limiting the rate at which a function executes, such as handling rapid user input events.
   
   The debouncer returns a Promise that resolves with the callback's return value or rejects if the callback throws an error or if the debounced call is cancelled.
   
   .. rubric:: Examples
   
   
   .. code-block:: typescript
   
      // Basic usage with synchronous callback
      const debouncer = new Debouncer((value: string) => {
        console.log('Search for:', value);
        return value.toUpperCase();
      });
      
      const result = await debouncer.debounce(500, 'hello');
      console.log(result); // 'HELLO'
   
   .. code-block:: typescript
   
      // Handling search input with async callback
      const searchDebouncer = new Debouncer(async (query: string) => {
        const response = await fetch(`/api/search?q=${query}`);
        return response.json();
      });
      
      inputElement.addEventListener('input', async (e) => {
        try {
          const results = await searchDebouncer.debounce(300, e.target.value);
          displayResults(results);
        } catch (error) {
          if (error.message !== 'Debounced call was cancelled') {
            console.error('Search failed:', error);
          }
        }
      });
   
   .. code-block:: typescript
   
      // Error handling
      const debouncer = new Debouncer((value: number) => {
        if (value < 0) throw new Error('Value must be positive');
        return value * 2;
      });
      
      try {
        await debouncer.debounce(500, -5);
      } catch (error) {
        console.error('Callback error:', error.message);
      }
   
   .. rubric:: Since
   
   
   ``2025.9.0``
   
   
   Index
   =====
   
   .. rubric:: Constructors
   
   
   .. rst-class:: api-xref-list
   
   
   * :js:func:`~ui.Debouncer.constructor`
   
   .. rubric:: Properties
   
   
   .. rst-class:: api-xref-list
   
   
   * :js:data:`~ui.Debouncer.callback`
   
   .. rubric:: Accessors
   
   
   .. rst-class:: api-xref-list
   
   
   * :js:func:`~ui.Debouncer.isPending`
   
   .. rubric:: Methods
   
   
   .. rst-class:: api-xref-list
   
   
   * :js:meth:`~ui.Debouncer.clear`
   * :js:meth:`~ui.Debouncer.debounce`
   
   



.. rst-class:: kind-group kind-constructors

.. rubric:: Constructors
   :class: kind-group-title


.. js:method:: ui.Debouncer.constructor

      .. rst-class:: sig-pretty-signature
      
         | Debouncer(**callback**\ : (**args**\ : TArgs) => TReturn): :js:class:`Debouncer <ui.Debouncer>`\ <TArgs, TReturn>
      
      Creates a new Debouncer instance with the specified callback function.
      
      **Parameters**
      
      
         **callback**\ : (**args**\ : TArgs) => TReturn
      
      
            The function to debounce. Can be synchronous or asynchronous.
      
      
      
      **Returns**\ : :js:class:`Debouncer <ui.Debouncer>`\ <TArgs, TReturn>
      
      .. rubric:: Examples
      
      
      .. code-block:: typescript
      
         const debouncer = new Debouncer((x: number, y: number) => x + y);
      



.. rst-class:: kind-group kind-properties

.. rubric:: Properties
   :class: kind-group-title


.. js:data:: ui.Debouncer.callback

      .. rst-class:: sig-pretty-signature
      
         | callback: (**args**\ : TArgs) => TReturn
      
      The callback function to be executed after the debounce delay. This can be updated dynamically to change the debounced behavior.
      



.. rst-class:: kind-group kind-accessors

.. rubric:: Accessors
   :class: kind-group-title


.. js:method:: ui.Debouncer.isPending

      .. rst-class:: sig-pretty-signature
      
         | *get* isPending(): *boolean*
      
      Indicates whether a debounced callback is currently waiting to execute.
      
      **Returns**\ : *boolean*
      
      
         ``true`` if a callback is scheduled to execute, ``false`` otherwise
      
      
      .. rubric:: Examples
      
      
      .. code-block:: typescript
      
         const debouncer = new Debouncer(() => console.log('Execute'));
         
         console.log(debouncer.isPending); // false
         
         debouncer.debounce(500);
         console.log(debouncer.isPending); // true
         
         await new Promise(resolve => setTimeout(resolve, 500));
         console.log(debouncer.isPending); // false
      



.. rst-class:: kind-group kind-methods

.. rubric:: Methods
   :class: kind-group-title


.. js:method:: ui.Debouncer.clear

      .. rst-class:: sig-pretty-signature
      
         | clear(): *void*
      
      Cancels any pending debounced execution. If a debounced callback is waiting to execute, it will be cancelled and the associated Promise will reject with no error.
      
      This method is safe to call multiple times and can be called even when no execution is pending.
      
      **Returns**\ : *void*
      
      .. rubric:: Examples
      
      
      .. code-block:: typescript
      
         const debouncer = new Debouncer(() => console.log('Execute'));
         
         const promise = debouncer.debounce(500);
         debouncer.clear(); // Cancels the pending execution
         
         try {
           await promise;
         } catch (error) {
           console.log('Execution was cancelled');
         }
      



.. js:method:: ui.Debouncer.debounce

      .. rst-class:: sig-pretty-signature
      
         | debounce(**delay**\ : *number*\ , **args**\ : TArgs): *Promise*
      
      Schedules the callback to execute after the specified delay. If called again before the delay elapses, the previous call is cancelled and a new delay period begins.
      
      **Parameters**
      
      
         **delay**\ : *number*
      
      
            The number of milliseconds to wait before executing the callback
      
      
         **args**\ : TArgs
      
      
            Arguments to pass to the callback function
      
      
      
      **Returns**\ : *Promise*
      
      
         A Promise that resolves with the callback's return value or rejects if:
      
      
      - The callback throws an error
      - The debounced call is cancelled via ``clear()`` or another ``debounce()`` call
      
      
      .. rubric:: Examples
      
      
      .. code-block:: typescript
      
         const debouncer = new Debouncer((text: string) => text.toUpperCase());
         
         // Only the last call executes after 500ms
         debouncer.debounce(500, 'first');  // Cancelled
         debouncer.debounce(500, 'second'); // Cancelled
         const result = await debouncer.debounce(500, 'third'); // Executes
         console.log(result); // 'THIRD'
      




