Proposal for safer and clearer debounce/throttle edges option

[DominikSerafin]

Problem

Both es-toolkit and lodash allow users to disable leading and trailing options at the same time on the debounce and throttle functions.

This effectively makes the functions no-ops (with a certain exception in lodash's throttle).

Neither library documents this behavior, and I cannot think of any use case for this. There's also this related lodash issue.

On top of that, I also find the DX of the edges options in both libraries a bit unintuitive because of the way they're set through objects/arrays.

Reproduction

The following code will not log anything to the console:

import {debounce, throttle} from 'es-toolkit';
import {debounce as compatDebounce, throttle as compatThrottle} from 'es-toolkit/compat';

const debounced = debounce(
  () => console.log('debounced'),
  1000,
  {edges: []}
);

const throttled = throttle(
  () => console.log('throttled'),
  1000,
  {edges: []}
);

const compatDebounced = compatDebounce(
  () => console.log('compatDebounced'),
  1000,
  {leading: false, trailing: false}
);

const compatThrottled = compatThrottle(
  () => console.log('compatThrottled'),
  1000,
  {leading: false, trailing: false}
);

debounced(); 
compatDebounced();

throttled(); 
compatThrottled(); 

The only case where something gets executed is in the case of subsequent lodash throttle calls after initial wait time:

const compatThrottled = compatThrottle(
  () => console.log('compatThrottled'),
  1000,
  {leading: false, trailing: false}
);

compatThrottled(); 
setTimeout(compatThrottled, 1000 + 1);

Solution

Redesign the way edges are configured by allowing only one of the following: trailing, leading, or both.

Rough outline/usage:

type Edges = 'leading' | 'trailing' | 'both'; 

debounce(fn, ms, {edges: 'leading'});
debounce(fn, ms, {edges: 'trailing'});
debounce(fn, ms, {edges: 'both'});

Maybe the edges could also be renamed to a more suitable name that works better with mixed singular and plural values, e.g. mode, trigger, activation, invokeOn, callTiming, or something else along these lines.

[dayongkr]

Since es-toolkit/compat follows lodash's types and behavior, we're not making additional improvements to it separately.

However, allowing both to be disabled in the original functions does seem meaningless. There's obviously no use case for wanting to disable both. We'll consider requiring at least one of them to be enabled in a es-toolkit original function. Thank you!

[DominikSerafin]

Good to hear :)

My suggestion for the API change was only for the es-toolkit function. I agree the compat version should stay as-is. I mentioned the lodash behavior mainly to illustrate that its API design might not necessarily be a perfect reference point.

[dayongkr]

After thinking about it more, since this is a breaking change, it seems difficult to apply immediately.

I'll make sure to include it in the next major update.