Magic Debunce

This lib is a debounce utility that simplifies the control of function execution timing, preventing unnecessary calls and improving performance.

Downloads

Statistics of this lib on NPM.

TotalWeeklyMonthlyYearly
npmnpmnpmnpm

How to install?

CDN
Unpkg JS
  https://unpkg.com/@vlalg-nimbus/magic-debunce/dist/bundle.min.umd.js
To install
YARN
  yarn add @vlalg-nimbus/magic-debunce
NPM
  npm i @vlalg-nimbus/magic-debunce

How to use?

Basic use

import MagicDebounce from '@vlalg-nimbus/magic-debounce'

const { debouncedFunction, cancel } = MagicDebounce({
  wait: 288,
  callback: () => console.log('Executed!'),
  firstClickOnly: true
});

debouncedFunction();

cancel();

Options

The debounce function accepts a single parameter: an options object that configures the behavior of your debounce instance. These options allow you to control how and when the callback is triggered, making it perfect for performance optimization in UI interactions and API requests.

nametyperequireddefault
callbackFunctionYes() => {}
waitNumberNo1000 (milliseconds)
firstClickOnlyBooleanNofalse

callback

The main function to be executed after the delay. This function is "debounced" — meaning it will only be called after a certain amount of inactivity.

It can be synchronous or asynchronous and can receive any number of arguments, which are passed when you call debouncedFunction(...).

wait

Specifies how many milliseconds to wait after the last call before executing the callback. Each new call resets the timer.

This is especially useful for limiting the frequency of actions such as typing, resizing, or clicking.

firstClickOnly

If set to true, only the first call within the debounce window will be executed, and all other calls will be ignored until the delay ends.

It is helpful when you want to prevent a function from being called multiple times in a short period — for example, to prevent duplicate form submissions.

Functions

debouncedFunction

debouncedFunction(...args)

Executes the provided callback after the specified delay. If called again before the delay expires, the timer is reset. Useful for controlling how frequently a function runs — such as handling user input, search queries, or resize events.

Each call to the debounce factory returns a separate instance, so timers and state are not shared across usages.

Accepts any arguments and passes them directly to the original callback function. These arguments are stored internally and used when the debounced delay completes.

This allows you to use debouncedFunction exactly like the original function you passed in, with full support for dynamic parameters.

const debounced = debounce({
  wait: 500,
  callback: (value) => console.log('Value:', value)
});

// After 500ms: logs "Value: Hello!"
debounced.debouncedFunction('Hello!');

cancel

cancel()

Cancels any scheduled execution of the debounced callback. Use this to prevent the function from running if it's still waiting.

This method only affects the specific instance it belongs to.

Other ways to use

JS (Vanilla and/or Node)

Save function only
  const debounced = MagicDebounce({
    wait: 298,
    callback: () => {
      console.log('Hello!');
    }
  }).debouncedFunction;

  debounced();
async e await
  const callback = async (value) => {
    await new Promise(resolve => setTimeout(resolve, 1000));
    return `Result for ${value}`;
  };

  const { debouncedFunction } = MagicDebounce({
    wait: 304,
    callback
  });

  const result = await debouncedFunction('search');
  console.log(result);
async e await 2
  const debounceRun = await debounce({
    wait: 2000,
    callback: customAsyncFunction,
    firstClickOnly: false
  });

  debounceRun().then(result => {
    console.log('result -> ', result);
    results.value = result;
    searching.value = false;
  });

Vue

v-model
  <input v-model="searchQuery" @input="debouncedSearch(searchQuery)" />

  const searchQuery = ref('');
  const { debouncedFunction } = MagicDebounce({
    wait: 500,
    callback: fetchResults
  });

  const debouncedSearch = (value: string) => {
    debouncedFunction(value);
  };
composable
  // composables/useDebouncedFunction.js
  import { ref, onBeforeUnmount } from 'vue'
  import MagicDebounce from '@vlalg-nimbus/magic-debounce'

  export function useDebouncedFunction(options) {
    const isWaiting = ref(false)

    const { debouncedFunction, cancel } = MagicDebounce({
      wait: options.wait,
      callback: async (...args) => {
        isWaiting.value = true
        const result = await options.callback(...args)
        isWaiting.value = false
        return result
      },
      firstClickOnly: options.firstClickOnly
    })

    onBeforeUnmount(() => {
      cancel()
    })

    return {
      run: debouncedFunction,
      cancel,
      isWaiting
    }
  }


  // Vue file
  <script setup>
    import { ref } from 'vue'
    import { useDebouncedFunction } from '~/composables/useDebouncedFunction'

    const query = ref('')
    const results = ref([])
    const searching = ref(false)

    const fetchResults = async (text) => {
      searching.value = true
      await new Promise((resolve) => setTimeout(resolve, 1000))
      results.value = [`Result for "${text}"`]
      searching.value = false
    }

    const { run: debouncedSearch } = useDebouncedFunction({
      wait: 800,
      callback: fetchResults
    })
  <script>

  <template>
    <input v-model="query" @input="debouncedSearch(query)" placeholder="Buscar..." />
    <ul>
      <li v-for="item in results" :key="item">{{ item }}</li>
    </ul>
  </template>

Nuxt

Composable
  // composables/useDebouncedFunction.ts
  export default function useDebouncedFunction({ wait = 1000, callback, firstClickOnly = false }) {
    let timerId = null

    const cancel = () => {
      if (timerId) {
        clearTimeout(timerId)
        timerId = null
      }
    }

    const run = (...args) => {
      if (typeof callback !== 'function') {
        console.warn('Callback must be a function')
        return
      }

      if (firstClickOnly && timerId) return

      clearTimeout(timerId)

      return new Promise((resolve) => {
        timerId = setTimeout(() => {
          const result = callback(...args)
          resolve(result)
        }, wait)
      })
    }

    return {
      run,
      cancel
    }
  }

  // Vue file
  <script setup>
    const searchQuery = ref('')
    const results = ref([])
    const searching = ref(false)

    const fetchResults = async (query) => {
      searching.value = true
      await new Promise((resolve) => setTimeout(resolve, 1000))
      results.value = [`Result for "${query}"`]
      searching.value = false
    }

    const { run: debouncedSearch } = useDebouncedFunction({
      wait: 800,
      callback: fetchResults
    })

    const handleInput = () => {
      debouncedSearch(searchQuery.value)
    }
  <script>

  <template>
    <input v-model="searchQuery" @input="handleInput" />
    <ul>
      <li v-for="item in results" :key="item">{{ item }}</li>
    </ul>
  </template>
Plugin
  // plugins/debounce.client.ts
  export default defineNuxtPlugin(() => {
    const debounce = ({ wait = 1000, callback, firstClickOnly = false }) => {
      let timerId: ReturnType<typeof setTimeout> | null = null

      const cancel = () => {
        if (timerId) {
          clearTimeout(timerId)
          timerId = null
        }
      }

      const run = (...args: any[]) => {
        if (typeof callback !== 'function') return

        if (firstClickOnly && timerId) return

        clearTimeout(timerId!)

        return new Promise((resolve) => {
          timerId = setTimeout(() => {
            const result = callback(...args)
            resolve(result)
          }, wait)
        })
      }

      return { run, cancel }
    }

    return {
      provide: {
        debounce
      }
    }
  })

  // Vue file
  const { debounce } = useNuxtApp()
  const fetchResults = async (query) => {
    await new Promise((resolve) => setTimeout(resolve, 1000))
    console.log('Fetched:', query)
  }

  const { run: debouncedFetch } = debounce({
    wait: 800,
    callback: fetchResults
  })

  debouncedFetch('Some search')
Table of Contents