feat(curry): add leading option for function debounce

test(curry): add test for `leading` option
doc(curry): add description and example of `leading` option

cdn/radash.esm.js

@@ -533,7 +533,7 @@ const memoize = (cache, func, keyFunc, ttl) => {
 const memo = (func, options = {}) => {
   return memoize({}, func, options.key ?? null, options.ttl ?? null);
 };
-const debounce = ({ delay }, func) => {
+const debounce = ({ delay, leading = false }, func) => {
   let timer = void 0;
   let active = true;
   const debounced = (...args) => {
@@ -543,6 +543,10 @@ const debounce = ({ delay }, func) => {
         active && func(...args);
         timer = void 0;
       }, delay);
+      if (leading) {
+        func(...args);
+        leading = false;
+      }
     } else {
       func(...args);
     }

cdn/radash.js

@@ -536,7 +536,7 @@ var radash = (function (exports) {
   const memo = (func, options = {}) => {
     return memoize({}, func, options.key ?? null, options.ttl ?? null);
   };
-  const debounce = ({ delay }, func) => {
+  const debounce = ({ delay, leading = false }, func) => {
     let timer = void 0;
     let active = true;
     const debounced = (...args) => {
@@ -546,6 +546,10 @@ var radash = (function (exports) {
           active && func(...args);
           timer = void 0;
         }, delay);
+        if (leading) {
+          func(...args);
+          leading = false;
+        }
       } else {
         func(...args);
       }

docs/curry/debounce.mdx

@@ -6,15 +6,17 @@ description: Create a debounced callback function
 
 ## Basic usage
 
-Debounce accepts an options object with a `delay` and a source function to call
+Debounce accepts an options object with `delay`, `leading`, and a source function to call
 when invoked. When the returned function is invoked it will only call the source
 function after the `delay` milliseconds of time has passed. Calls that don't result
-in invoking the source reset the delay, pushing off the next invocation.
+in invoking the source reset the delay, pushing off the next invocation. The `leading`
+option decides whether the source function is called on the first invocation of the debounce
+function or not.
 
 ```ts
 import { debounce } from 'radash'
 
-const makeSearchRequest = (event) => {
+const makeSearchRequest = event => {
   api.movies.search(event.target.value)
 }
 
@@ -33,6 +35,28 @@ debounce Invocations: x x x x - - - - - - - - x x x x x x x x x x - - - - - - -
   Source Invocations: - - - - - - - - - - x - - - - - - - - - - - - - - - - - x - - - - -
 ```
 
+## Leading
+
+The `leading` option, `false` by default, will call the source function immediately
+the first time the debounce function is invoked when set to `true`.
+
+```ts
+// hide the header when scroll down and show it when scroll up.
+
+const header = document.getElementById('page-header')
+let lastY = 0
+
+window.addEventListener(
+  'scroll',
+  debounce({ delay: 100, leading: true }, () => {
+    header.style.transform = `translateY(${
+      window.scrollY - lastY > 0 ? '-100%' : '0'
+    })`
+    lastY = window.scrollY
+  })
+)
+```
+
 ### Cancel
 
 The function returned by `debounce` has a `cancel` method that when called will permanently stop the source function from being debounced.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "radash",
-  "version": "12.1.0",
+  "version": "12.1.1",
   "description": "Functional utility library - modern, simple, typed, powerful",
   "main": "dist/cjs/index.cjs",
   "module": "dist/esm/index.mjs",

src/curry.ts

@@ -494,6 +494,19 @@ export type DebounceFunction<TArgs extends any[]> = {
   flush(...args: TArgs): void
 }
 
+export type DebounceConfig = {
+  /**
+   * The time in milliseconds to wait before calling the
+   * source function
+   */
+  delay: number;
+  /**
+   * whether the source function will be called on the first
+   * invocation of the debounce function. `false` by default
+   */
+  leading?: boolean;
+}
+
 export type ThrottledFunction<TArgs extends any[]> = {
   (...args: TArgs): void
   /**
@@ -512,7 +525,7 @@ export type ThrottledFunction<TArgs extends any[]> = {
  * method to invoke them immediately
  */
 export const debounce = <TArgs extends any[]>(
-  { delay }: { delay: number },
+  { delay, leading = false }: DebounceConfig,
   func: (...args: TArgs) => any
 ) => {
   let timer: NodeJS.Timeout | undefined = undefined
@@ -525,6 +538,10 @@ export const debounce = <TArgs extends any[]>(
         active && func(...args)
         timer = undefined
       }, delay)
+      if (leading) {
+        func(...args)
+        leading = false
+      }
     } else {
       func(...args)
     }

src/tests/curry.test.ts

@@ -330,6 +330,14 @@ describe('curry module', () => {
       expect(mockFunc).toHaveBeenCalledTimes(1)
     })
 
+    test('executes the function immediately on the first invocation of the debounce function when set `leading` to true', async () => {
+      func = _.debounce({ delay: 600, leading: true }, mockFunc)
+      runFunc3Times()
+      expect(mockFunc).toHaveBeenCalledTimes(1)
+      await _.sleep(610)
+      expect(mockFunc).toHaveBeenCalledTimes(2)
+    })
+
     test('does not debounce after cancel is called', () => {
       runFunc3Times()
       expect(mockFunc).toHaveBeenCalledTimes(0)