@x-oasis/throttle 0.1.37 → 0.1.38

package/.turbo/turbo-build.log

@@ -1,22 +1,16 @@
 
-> @x-oasis/throttle@0.1.37 build /home/runner/work/x-oasis/x-oasis/packages/schedule/throttle
+> @x-oasis/throttle@0.1.38 build /home/runner/work/x-oasis/x-oasis/packages/schedule/throttle
 > tsdx build --tsconfig tsconfig.build.json
 
 @rollup/plugin-replace: 'preventAssignment' currently defaults to false. It is recommended to set this option to `true`, as the next major version will default this option to `true`.
 @rollup/plugin-replace: 'preventAssignment' currently defaults to false. It is recommended to set this option to `true`, as the next major version will default this option to `true`.
 ⠙ Creating entry file
-⠙ Building modules
-✓ Creating entry file 5.5 secs
-⠹ Building modules
+✓ Creating entry file 2.4 secs
+⠙ Building modules
+⠹ Building modules
 ⠸ Building modules
 ⠼ Building modules
-⠴ Building modules
-⠦ Building modules
-⠧ Building modules
-⠇ Building modules
-⠏ Building modules
-⠋ Building modules
 [tsdx]: Your rootDir is currently set to "./". Please change your rootDir to "./src".
 TSDX has deprecated setting tsconfig.compilerOptions.rootDir to "./" as it caused buggy output for declarationMaps and more.
 You may also need to change your include to remove "test", which also caused declarations to be unnecessarily created for test files.
-✓ Building modules 8 secs
+✓ Building modules 3.2 secs

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @x-oasis/throttle
 
+## 0.1.38
+
+### Patch Changes
+
+- f1aae14: bump version
+- Updated dependencies [f1aae14]
+  - @x-oasis/default-boolean-value@0.1.38
+  - @x-oasis/debounce@0.1.38
+
 ## 0.1.37
 
 ### Patch Changes

package/README.md

@@ -1,19 +1,176 @@
 # @x-oasis/throttle
 
+Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds.
+
 ## Installation
 
 ```bash
-$ npm i @x-oasis/throttle
+npm install @x-oasis/throttle
+# or
+pnpm add @x-oasis/throttle
+# or
+yarn add @x-oasis/throttle
 ```
 
-## How to use
+## Usage
+
+### Basic Usage
 
 ```typescript
-import throttle from '@x-oasis/throttle'
+import throttle from '@x-oasis/throttle';
+
+// Avoid excessively updating the position while scrolling.
+const updatePosition = () => {
+  // Update scroll position
+};
+
+const throttled = throttle(updatePosition, 100);
+window.addEventListener('scroll', throttled);
 ```
 
-## How to run test
+### With Options
 
-```bash
-$ pnpm test
-```
+```typescript
+import throttle from '@x-oasis/throttle';
+
+const renewToken = () => {
+  // Renew authentication token
+};
+
+// Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.
+const throttled = throttle(renewToken, 300000, {
+  trailing: false
+});
+```
+
+### Cancel and Flush
+
+The throttled function comes with a `cancel` method to cancel delayed `func` invocations and a `flush` method to immediately invoke them.
+
+```typescript
+import throttle from '@x-oasis/throttle';
+
+const throttled = throttle(updatePosition, 100);
+
+// Cancel the trailing throttled invocation.
+throttled.cancel();
+
+// Flush the trailing throttled invocation.
+throttled.flush();
+```
+
+## API
+
+### `throttle(func, wait, options?)`
+
+Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds.
+
+#### Parameters
+
+- `func` (`Function`): The function to throttle.
+- `wait` (`number`, default: `0`): The number of milliseconds to throttle invocations to.
+- `options` (`Object`, optional): The options object.
+  - `leading` (`boolean`, default: `true`): Specify invoking on the leading edge of the timeout.
+  - `trailing` (`boolean`, default: `true`): Specify invoking on the trailing edge of the timeout.
+
+#### Returns
+
+Returns the new throttled function with the following methods:
+
+- `cancel()`: Cancels delayed `func` invocations.
+- `flush()`: Immediately invokes the delayed `func` invocation.
+
+## Examples
+
+### Scroll Handler
+
+```typescript
+import throttle from '@x-oasis/throttle';
+
+const handleScroll = () => {
+  // Update UI based on scroll position
+  console.log('Scroll position:', window.scrollY);
+};
+
+const throttledScroll = throttle(handleScroll, 100);
+
+window.addEventListener('scroll', throttledScroll);
+
+// Cleanup
+window.removeEventListener('scroll', throttledScroll);
+throttledScroll.cancel();
+```
+
+### Mouse Move Handler
+
+```typescript
+import throttle from '@x-oasis/throttle';
+
+const handleMouseMove = (event: MouseEvent) => {
+  // Track mouse position
+  console.log('Mouse position:', event.clientX, event.clientY);
+};
+
+const throttledMouseMove = throttle(handleMouseMove, 50);
+
+document.addEventListener('mousemove', throttledMouseMove);
+```
+
+### Leading and Trailing
+
+```typescript
+import throttle from '@x-oasis/throttle';
+
+const logMessage = (message: string) => {
+  console.log(message);
+};
+
+// Execute immediately on first call, then wait for trailing edge
+const throttled = throttle(logMessage, 1000, {
+  leading: true,
+  trailing: true
+});
+
+throttled('First');  // Executes immediately
+throttled('Second'); // Ignored
+throttled('Third');  // Ignored
+// After 1000ms, 'Third' executes (trailing edge)
+
+// Only execute on trailing edge
+const trailingOnly = throttle(logMessage, 1000, {
+  leading: false,
+  trailing: true
+});
+
+trailingOnly('First');  // Not executed immediately
+trailingOnly('Second'); // Not executed
+trailingOnly('Third');  // Not executed
+// After 1000ms, 'Third' executes
+```
+
+## Differences from Debounce
+
+- **Throttle**: Executes the function at most once per `wait` milliseconds, regardless of how many times it's called.
+- **Debounce**: Delays execution until after `wait` milliseconds have elapsed since the last invocation.
+
+### When to Use Throttle
+
+- Scroll events
+- Mouse move events
+- Window resize events (when you want periodic updates)
+- API calls that should happen at regular intervals
+
+### When to Use Debounce
+
+- Search input (wait for user to stop typing)
+- Button clicks (prevent double-clicks)
+- Window resize events (when you only care about the final size)
+
+## See Also
+
+- [Lodash throttle](https://lodash.com/docs/#throttle)
+- [@x-oasis/debounce](../debounce/README.md) - Creates a debounced function
+
+## License
+
+ISC

package/dist/index.d.ts

@@ -1,3 +1,8 @@
-export default function throttle(fn: Function, threshold?: number, fallbackOptions?: {
-    persistArgs?: (...args: any[]) => any;
-} | boolean): (...args: any[]) => any;
+export declare type ThrottleOptions = {
+    leading?: boolean;
+    trailing?: boolean;
+};
+export default function throttle(func: (...args: any[]) => any, wait?: number, options?: ThrottleOptions): ((...args: any[]) => any) & {
+    cancel: () => void;
+    flush: () => void;
+};

package/dist/throttle.cjs.development.js

@@ -2,27 +2,21 @@
 
 Object.defineProperty(exports, '__esModule', { value: true });
 
-function throttle(fn, threshold, fallbackOptions) {
-  if (threshold === void 0) {
-    threshold = 250;
+function _interopDefault (ex) { return (ex && (typeof ex === 'object') && 'default' in ex) ? ex['default'] : ex; }
+
+var debounce = _interopDefault(require('@x-oasis/debounce'));
+
+function throttle(func, wait, options) {
+  if (wait === void 0) {
+    wait = 0;
   }
-  var last = 0;
-  var _args = [];
-  return function throttled() {
-    var now = Date.now();
-    var persistArgs = typeof fallbackOptions === 'object' ? fallbackOptions.persistArgs : null;
-    for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
-      args[_key] = arguments[_key];
-    }
-    _args = args;
-    if (typeof persistArgs === 'function') {
-      _args = persistArgs(args);
-    }
-    if (now - last > threshold) {
-      last = now;
-      return fn.apply(this, args);
-    }
-  };
+  var leading = (options == null ? void 0 : options.leading) !== undefined ? options.leading : true;
+  var trailing = (options == null ? void 0 : options.trailing) !== undefined ? options.trailing : true;
+  return debounce(func, wait, {
+    leading: leading,
+    trailing: trailing,
+    maxWait: wait
+  });
 }
 
 exports.default = throttle;

package/dist/throttle.cjs.development.js.map

@@ -1 +1 @@
-{"version":3,"file":"throttle.cjs.development.js","sources":["../src/index.ts"],"sourcesContent":["/**\n *\n * @param fn\n * @param threshold\n * @returns\n *\n * trigger first, then trigger on the last\n */\n\nexport default function throttle(\n  fn: Function,\n  threshold = 250,\n  fallbackOptions?:\n    | {\n        persistArgs?: (...args: any[]) => any;\n      }\n    | boolean\n) {\n  let last = 0;\n  let _args = [];\n\n  return function throttled(...args: any[]) {\n    const now = Date.now();\n\n    const persistArgs =\n      typeof fallbackOptions === 'object' ? fallbackOptions.persistArgs : null;\n\n    _args = args;\n\n    if (typeof persistArgs === 'function') {\n      _args = persistArgs(args);\n    }\n\n    if (now - last > threshold) {\n      last = now;\n\n      return fn.apply(this, args);\n    }\n  };\n}\n"],"names":["throttle","fn","threshold","fallbackOptions","last","_args","throttled","now","Date","persistArgs","_len","arguments","length","args","Array","_key","apply"],"mappings":";;;;SASwBA,QAAQA,CAC9BC,EAAY,EACZC,SAAS,EACTC,eAIW;MALXD,SAAS;IAATA,SAAS,GAAG,GAAG;;EAOf,IAAIE,IAAI,GAAG,CAAC;EACZ,IAAIC,KAAK,GAAG,EAAE;EAEd,OAAO,SAASC,SAASA;IACvB,IAAMC,GAAG,GAAGC,IAAI,CAACD,GAAG,EAAE;IAEtB,IAAME,WAAW,GACf,OAAON,eAAe,KAAK,QAAQ,GAAGA,eAAe,CAACM,WAAW,GAAG,IAAI;IAAC,SAAAC,IAAA,GAAAC,SAAA,CAAAC,MAAA,EAJhDC,IAAW,OAAAC,KAAA,CAAAJ,IAAA,GAAAK,IAAA,MAAAA,IAAA,GAAAL,IAAA,EAAAK,IAAA;MAAXF,IAAW,CAAAE,IAAA,IAAAJ,SAAA,CAAAI,IAAA;;IAMtCV,KAAK,GAAGQ,IAAI;IAEZ,IAAI,OAAOJ,WAAW,KAAK,UAAU,EAAE;MACrCJ,KAAK,GAAGI,WAAW,CAACI,IAAI,CAAC;;IAG3B,IAAIN,GAAG,GAAGH,IAAI,GAAGF,SAAS,EAAE;MAC1BE,IAAI,GAAGG,GAAG;MAEV,OAAON,EAAE,CAACe,KAAK,CAAC,IAAI,EAAEH,IAAI,CAAC;;GAE9B;AACH;;;;"}
+{"version":3,"file":"throttle.cjs.development.js","sources":["../src/index.ts"],"sourcesContent":["import debounce from '@x-oasis/debounce';\n\n/**\n * Options for throttle function\n * @see https://lodash.com/docs/#throttle\n */\nexport type ThrottleOptions = {\n  /**\n   * Specify invoking on the leading edge of the timeout.\n   * @default true\n   */\n  leading?: boolean;\n  /**\n   * Specify invoking on the trailing edge of the timeout.\n   * @default true\n   */\n  trailing?: boolean;\n};\n\n/**\n * Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds.\n *\n * The throttled function comes with a `cancel` method to cancel delayed `func` invocations\n * and a `flush` method to immediately invoke them.\n *\n * @param func - The function to throttle\n * @param wait - The number of milliseconds to throttle invocations to\n * @param options - The options object\n * @returns Returns the new throttled function\n *\n * @example\n * ```typescript\n * // Avoid excessively updating the position while scrolling.\n * const throttled = throttle(updatePosition, 100);\n * window.addEventListener('scroll', throttled);\n *\n * // Cancel the trailing throttled invocation.\n * throttled.cancel();\n *\n * // Flush the trailing throttled invocation.\n * throttled.flush();\n * ```\n *\n * @example\n * ```typescript\n * // Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.\n * const throttled = throttle(renewToken, 300000, {\n *   'trailing': false\n * });\n * ```\n *\n * @see https://lodash.com/docs/#throttle\n */\nexport default function throttle(\n  func: (...args: any[]) => any,\n  wait = 0,\n  options?: ThrottleOptions\n): ((...args: any[]) => any) & {\n  cancel: () => void;\n  flush: () => void;\n} {\n  const leading = options?.leading !== undefined ? options.leading : true;\n  const trailing = options?.trailing !== undefined ? options.trailing : true;\n\n  // Throttle is essentially debounce with maxWait set to wait\n  // This ensures the function is invoked at most once per wait period\n  return debounce(func, wait, {\n    leading,\n    trailing,\n    maxWait: wait,\n  });\n}\n"],"names":["throttle","func","wait","options","leading","undefined","trailing","debounce","maxWait"],"mappings":";;;;;;;;SAqDwBA,QAAQA,CAC9BC,IAA6B,EAC7BC,IAAI,EACJC,OAAyB;MADzBD,IAAI;IAAJA,IAAI,GAAG,CAAC;;EAMR,IAAME,OAAO,GAAG,CAAAD,OAAO,oBAAPA,OAAO,CAAEC,OAAO,MAAKC,SAAS,GAAGF,OAAO,CAACC,OAAO,GAAG,IAAI;EACvE,IAAME,QAAQ,GAAG,CAAAH,OAAO,oBAAPA,OAAO,CAAEG,QAAQ,MAAKD,SAAS,GAAGF,OAAO,CAACG,QAAQ,GAAG,IAAI;EAI1E,OAAOC,QAAQ,CAACN,IAAI,EAAEC,IAAI,EAAE;IAC1BE,OAAO,EAAPA,OAAO;IACPE,QAAQ,EAARA,QAAQ;IACRE,OAAO,EAAEN;GACV,CAAC;AACJ;;;;"}

package/dist/throttle.cjs.production.min.js

@@ -1,2 +1,2 @@
-"use strict";Object.defineProperty(exports,"__esModule",{value:!0}),exports.default=function(e,t,r){void 0===t&&(t=250);var n=0;return function(){for(var o=Date.now(),u="object"==typeof r?r.persistArgs:null,f=arguments.length,i=new Array(f),s=0;s<f;s++)i[s]=arguments[s];if("function"==typeof u&&u(i),o-n>t)return n=o,e.apply(this,i)}};
+"use strict";Object.defineProperty(exports,"__esModule",{value:!0});var e,i=(e=require("@x-oasis/debounce"))&&"object"==typeof e&&"default"in e?e.default:e;exports.default=function(e,t,l){return void 0===t&&(t=0),i(e,t,{leading:void 0===(null==l?void 0:l.leading)||l.leading,trailing:void 0===(null==l?void 0:l.trailing)||l.trailing,maxWait:t})};
 //# sourceMappingURL=throttle.cjs.production.min.js.map

package/dist/throttle.cjs.production.min.js.map

@@ -1 +1 @@
-{"version":3,"file":"throttle.cjs.production.min.js","sources":["../src/index.ts"],"sourcesContent":["/**\n *\n * @param fn\n * @param threshold\n * @returns\n *\n * trigger first, then trigger on the last\n */\n\nexport default function throttle(\n  fn: Function,\n  threshold = 250,\n  fallbackOptions?:\n    | {\n        persistArgs?: (...args: any[]) => any;\n      }\n    | boolean\n) {\n  let last = 0;\n  let _args = [];\n\n  return function throttled(...args: any[]) {\n    const now = Date.now();\n\n    const persistArgs =\n      typeof fallbackOptions === 'object' ? fallbackOptions.persistArgs : null;\n\n    _args = args;\n\n    if (typeof persistArgs === 'function') {\n      _args = persistArgs(args);\n    }\n\n    if (now - last > threshold) {\n      last = now;\n\n      return fn.apply(this, args);\n    }\n  };\n}\n"],"names":["fn","threshold","fallbackOptions","last","now","Date","persistArgs","_len","arguments","length","args","Array","_key","apply","this"],"mappings":"6FAUEA,EACAC,EACAC,YADAD,IAAAA,EAAY,KAOZ,IAAIE,EAAO,EAGX,OAAO,WAIsE,IAH3E,IAAMC,EAAMC,KAAKD,MAEXE,EACuB,iBAApBJ,EAA+BA,EAAgBI,YAAc,KAAKC,EAAAC,UAAAC,OAJhDC,MAAWC,MAAAJ,GAAAK,IAAAA,EAAAL,EAAAK,IAAXF,EAAWE,GAAAJ,UAAAI,GAYtC,GAJ2B,mBAAhBN,GACDA,EAAYI,GAGlBN,EAAMD,EAAOF,EAGf,OAFAE,EAAOC,EAEAJ,EAAGa,MAAMC,KAAMJ"}
+{"version":3,"file":"throttle.cjs.production.min.js","sources":["../src/index.ts"],"sourcesContent":["import debounce from '@x-oasis/debounce';\n\n/**\n * Options for throttle function\n * @see https://lodash.com/docs/#throttle\n */\nexport type ThrottleOptions = {\n  /**\n   * Specify invoking on the leading edge of the timeout.\n   * @default true\n   */\n  leading?: boolean;\n  /**\n   * Specify invoking on the trailing edge of the timeout.\n   * @default true\n   */\n  trailing?: boolean;\n};\n\n/**\n * Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds.\n *\n * The throttled function comes with a `cancel` method to cancel delayed `func` invocations\n * and a `flush` method to immediately invoke them.\n *\n * @param func - The function to throttle\n * @param wait - The number of milliseconds to throttle invocations to\n * @param options - The options object\n * @returns Returns the new throttled function\n *\n * @example\n * ```typescript\n * // Avoid excessively updating the position while scrolling.\n * const throttled = throttle(updatePosition, 100);\n * window.addEventListener('scroll', throttled);\n *\n * // Cancel the trailing throttled invocation.\n * throttled.cancel();\n *\n * // Flush the trailing throttled invocation.\n * throttled.flush();\n * ```\n *\n * @example\n * ```typescript\n * // Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.\n * const throttled = throttle(renewToken, 300000, {\n *   'trailing': false\n * });\n * ```\n *\n * @see https://lodash.com/docs/#throttle\n */\nexport default function throttle(\n  func: (...args: any[]) => any,\n  wait = 0,\n  options?: ThrottleOptions\n): ((...args: any[]) => any) & {\n  cancel: () => void;\n  flush: () => void;\n} {\n  const leading = options?.leading !== undefined ? options.leading : true;\n  const trailing = options?.trailing !== undefined ? options.trailing : true;\n\n  // Throttle is essentially debounce with maxWait set to wait\n  // This ensures the function is invoked at most once per wait period\n  return debounce(func, wait, {\n    leading,\n    trailing,\n    maxWait: wait,\n  });\n}\n"],"names":["func","wait","options","debounce","leading","undefined","trailing","maxWait"],"mappings":"qLAsDEA,EACAC,EACAC,GAUA,gBAXAD,IAAAA,EAAO,GAWAE,EAASH,EAAMC,EAAM,CAC1BG,aANmCC,WAArBH,SAAAA,EAASE,UAAwBF,EAAQE,QAOvDE,cANqCD,WAAtBH,SAAAA,EAASI,WAAyBJ,EAAQI,SAOzDC,QAASN"}

package/dist/throttle.esm.js

@@ -1,24 +1,16 @@
-function throttle(fn, threshold, fallbackOptions) {
-  if (threshold === void 0) {
-    threshold = 250;
+import debounce from '@x-oasis/debounce';
+
+function throttle(func, wait, options) {
+  if (wait === void 0) {
+    wait = 0;
   }
-  var last = 0;
-  var _args = [];
-  return function throttled() {
-    var now = Date.now();
-    var persistArgs = typeof fallbackOptions === 'object' ? fallbackOptions.persistArgs : null;
-    for (var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++) {
-      args[_key] = arguments[_key];
-    }
-    _args = args;
-    if (typeof persistArgs === 'function') {
-      _args = persistArgs(args);
-    }
-    if (now - last > threshold) {
-      last = now;
-      return fn.apply(this, args);
-    }
-  };
+  var leading = (options == null ? void 0 : options.leading) !== undefined ? options.leading : true;
+  var trailing = (options == null ? void 0 : options.trailing) !== undefined ? options.trailing : true;
+  return debounce(func, wait, {
+    leading: leading,
+    trailing: trailing,
+    maxWait: wait
+  });
 }
 
 export default throttle;

package/dist/throttle.esm.js.map

@@ -1 +1 @@
-{"version":3,"file":"throttle.esm.js","sources":["../src/index.ts"],"sourcesContent":["/**\n *\n * @param fn\n * @param threshold\n * @returns\n *\n * trigger first, then trigger on the last\n */\n\nexport default function throttle(\n  fn: Function,\n  threshold = 250,\n  fallbackOptions?:\n    | {\n        persistArgs?: (...args: any[]) => any;\n      }\n    | boolean\n) {\n  let last = 0;\n  let _args = [];\n\n  return function throttled(...args: any[]) {\n    const now = Date.now();\n\n    const persistArgs =\n      typeof fallbackOptions === 'object' ? fallbackOptions.persistArgs : null;\n\n    _args = args;\n\n    if (typeof persistArgs === 'function') {\n      _args = persistArgs(args);\n    }\n\n    if (now - last > threshold) {\n      last = now;\n\n      return fn.apply(this, args);\n    }\n  };\n}\n"],"names":["throttle","fn","threshold","fallbackOptions","last","_args","throttled","now","Date","persistArgs","_len","arguments","length","args","Array","_key","apply"],"mappings":"SASwBA,QAAQA,CAC9BC,EAAY,EACZC,SAAS,EACTC,eAIW;MALXD,SAAS;IAATA,SAAS,GAAG,GAAG;;EAOf,IAAIE,IAAI,GAAG,CAAC;EACZ,IAAIC,KAAK,GAAG,EAAE;EAEd,OAAO,SAASC,SAASA;IACvB,IAAMC,GAAG,GAAGC,IAAI,CAACD,GAAG,EAAE;IAEtB,IAAME,WAAW,GACf,OAAON,eAAe,KAAK,QAAQ,GAAGA,eAAe,CAACM,WAAW,GAAG,IAAI;IAAC,SAAAC,IAAA,GAAAC,SAAA,CAAAC,MAAA,EAJhDC,IAAW,OAAAC,KAAA,CAAAJ,IAAA,GAAAK,IAAA,MAAAA,IAAA,GAAAL,IAAA,EAAAK,IAAA;MAAXF,IAAW,CAAAE,IAAA,IAAAJ,SAAA,CAAAI,IAAA;;IAMtCV,KAAK,GAAGQ,IAAI;IAEZ,IAAI,OAAOJ,WAAW,KAAK,UAAU,EAAE;MACrCJ,KAAK,GAAGI,WAAW,CAACI,IAAI,CAAC;;IAG3B,IAAIN,GAAG,GAAGH,IAAI,GAAGF,SAAS,EAAE;MAC1BE,IAAI,GAAGG,GAAG;MAEV,OAAON,EAAE,CAACe,KAAK,CAAC,IAAI,EAAEH,IAAI,CAAC;;GAE9B;AACH;;;;"}
+{"version":3,"file":"throttle.esm.js","sources":["../src/index.ts"],"sourcesContent":["import debounce from '@x-oasis/debounce';\n\n/**\n * Options for throttle function\n * @see https://lodash.com/docs/#throttle\n */\nexport type ThrottleOptions = {\n  /**\n   * Specify invoking on the leading edge of the timeout.\n   * @default true\n   */\n  leading?: boolean;\n  /**\n   * Specify invoking on the trailing edge of the timeout.\n   * @default true\n   */\n  trailing?: boolean;\n};\n\n/**\n * Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds.\n *\n * The throttled function comes with a `cancel` method to cancel delayed `func` invocations\n * and a `flush` method to immediately invoke them.\n *\n * @param func - The function to throttle\n * @param wait - The number of milliseconds to throttle invocations to\n * @param options - The options object\n * @returns Returns the new throttled function\n *\n * @example\n * ```typescript\n * // Avoid excessively updating the position while scrolling.\n * const throttled = throttle(updatePosition, 100);\n * window.addEventListener('scroll', throttled);\n *\n * // Cancel the trailing throttled invocation.\n * throttled.cancel();\n *\n * // Flush the trailing throttled invocation.\n * throttled.flush();\n * ```\n *\n * @example\n * ```typescript\n * // Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.\n * const throttled = throttle(renewToken, 300000, {\n *   'trailing': false\n * });\n * ```\n *\n * @see https://lodash.com/docs/#throttle\n */\nexport default function throttle(\n  func: (...args: any[]) => any,\n  wait = 0,\n  options?: ThrottleOptions\n): ((...args: any[]) => any) & {\n  cancel: () => void;\n  flush: () => void;\n} {\n  const leading = options?.leading !== undefined ? options.leading : true;\n  const trailing = options?.trailing !== undefined ? options.trailing : true;\n\n  // Throttle is essentially debounce with maxWait set to wait\n  // This ensures the function is invoked at most once per wait period\n  return debounce(func, wait, {\n    leading,\n    trailing,\n    maxWait: wait,\n  });\n}\n"],"names":["throttle","func","wait","options","leading","undefined","trailing","debounce","maxWait"],"mappings":";;SAqDwBA,QAAQA,CAC9BC,IAA6B,EAC7BC,IAAI,EACJC,OAAyB;MADzBD,IAAI;IAAJA,IAAI,GAAG,CAAC;;EAMR,IAAME,OAAO,GAAG,CAAAD,OAAO,oBAAPA,OAAO,CAAEC,OAAO,MAAKC,SAAS,GAAGF,OAAO,CAACC,OAAO,GAAG,IAAI;EACvE,IAAME,QAAQ,GAAG,CAAAH,OAAO,oBAAPA,OAAO,CAAEG,QAAQ,MAAKD,SAAS,GAAGF,OAAO,CAACG,QAAQ,GAAG,IAAI;EAI1E,OAAOC,QAAQ,CAACN,IAAI,EAAEC,IAAI,EAAE;IAC1BE,OAAO,EAAPA,OAAO;IACPE,QAAQ,EAARA,QAAQ;IACRE,OAAO,EAAEN;GACV,CAAC;AACJ;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-oasis/throttle",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "description": "throttle function",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -13,6 +13,10 @@
   "devDependencies": {
     "tsdx": "^0.14.1"
   },
+  "dependencies": {
+    "@x-oasis/default-boolean-value": "0.1.38",
+    "@x-oasis/debounce": "0.1.38"
+  },
   "scripts": {
     "build": "tsdx build --tsconfig tsconfig.build.json",
     "clean": "rimraf ./dist",

package/src/index.ts

@@ -1,40 +1,72 @@
+import debounce from '@x-oasis/debounce';
+
+/**
+ * Options for throttle function
+ * @see https://lodash.com/docs/#throttle
+ */
+export type ThrottleOptions = {
+  /**
+   * Specify invoking on the leading edge of the timeout.
+   * @default true
+   */
+  leading?: boolean;
+  /**
+   * Specify invoking on the trailing edge of the timeout.
+   * @default true
+   */
+  trailing?: boolean;
+};
+
 /**
+ * Creates a throttled function that only invokes `func` at most once per every `wait` milliseconds.
+ *
+ * The throttled function comes with a `cancel` method to cancel delayed `func` invocations
+ * and a `flush` method to immediately invoke them.
+ *
+ * @param func - The function to throttle
+ * @param wait - The number of milliseconds to throttle invocations to
+ * @param options - The options object
+ * @returns Returns the new throttled function
+ *
+ * @example
+ * ```typescript
+ * // Avoid excessively updating the position while scrolling.
+ * const throttled = throttle(updatePosition, 100);
+ * window.addEventListener('scroll', throttled);
+ *
+ * // Cancel the trailing throttled invocation.
+ * throttled.cancel();
  *
- * @param fn
- * @param threshold
- * @returns
+ * // Flush the trailing throttled invocation.
+ * throttled.flush();
+ * ```
  *
- * trigger first, then trigger on the last
+ * @example
+ * ```typescript
+ * // Invoke `renewToken` when the click event is fired, but not more than once every 5 minutes.
+ * const throttled = throttle(renewToken, 300000, {
+ *   'trailing': false
+ * });
+ * ```
+ *
+ * @see https://lodash.com/docs/#throttle
  */
-
 export default function throttle(
-  fn: Function,
-  threshold = 250,
-  fallbackOptions?:
-    | {
-        persistArgs?: (...args: any[]) => any;
-      }
-    | boolean
-) {
-  let last = 0;
-  let _args = [];
-
-  return function throttled(...args: any[]) {
-    const now = Date.now();
-
-    const persistArgs =
-      typeof fallbackOptions === 'object' ? fallbackOptions.persistArgs : null;
-
-    _args = args;
-
-    if (typeof persistArgs === 'function') {
-      _args = persistArgs(args);
-    }
-
-    if (now - last > threshold) {
-      last = now;
+  func: (...args: any[]) => any,
+  wait = 0,
+  options?: ThrottleOptions
+): ((...args: any[]) => any) & {
+  cancel: () => void;
+  flush: () => void;
+} {
+  const leading = options?.leading !== undefined ? options.leading : true;
+  const trailing = options?.trailing !== undefined ? options.trailing : true;
 
-      return fn.apply(this, args);
-    }
-  };
+  // Throttle is essentially debounce with maxWait set to wait
+  // This ensures the function is invoked at most once per wait period
+  return debounce(func, wait, {
+    leading,
+    trailing,
+    maxWait: wait,
+  });
 }

package/test/test.spec.ts

@@ -1,5 +1,235 @@
-import { expect, test } from 'vitest';
+import { expect, test, vi, beforeEach, afterEach } from 'vitest';
+import throttle from '../src/index';
 
-test('vitest', async () => {
-  expect('vitest').toBe('vitest');
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+test('throttle basic functionality', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100);
+
+  throttled(1);
+  expect(fn).toHaveBeenCalledTimes(1);
+  expect(fn).toHaveBeenCalledWith(1);
+
+  throttled(2);
+  throttled(3);
+  expect(fn).toHaveBeenCalledTimes(1); // Still only called once
+
+  vi.advanceTimersByTime(100);
+  expect(fn).toHaveBeenCalledTimes(2);
+  expect(fn).toHaveBeenCalledWith(3); // Last call's arguments
+});
+
+test('throttle with leading: false', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100, { leading: false });
+
+  throttled(1);
+  expect(fn).not.toHaveBeenCalled();
+
+  vi.advanceTimersByTime(100);
+  expect(fn).toHaveBeenCalledTimes(1);
+  expect(fn).toHaveBeenCalledWith(1);
+});
+
+test('throttle with trailing: false', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100, { trailing: false });
+
+  throttled(1);
+  expect(fn).toHaveBeenCalledTimes(1);
+  expect(fn).toHaveBeenCalledWith(1);
+
+  throttled(2);
+  throttled(3);
+  expect(fn).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(100);
+  expect(fn).toHaveBeenCalledTimes(1); // No trailing execution
+});
+
+test('throttle with leading: false and trailing: false', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100, {
+    leading: false,
+    trailing: false,
+  });
+
+  throttled(1);
+  throttled(2);
+  throttled(3);
+
+  expect(fn).not.toHaveBeenCalled();
+
+  vi.advanceTimersByTime(100);
+  expect(fn).not.toHaveBeenCalled();
+});
+
+test('throttle cancel', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100);
+
+  throttled(1);
+  expect(fn).toHaveBeenCalledTimes(1);
+
+  throttled(2);
+  throttled.cancel();
+
+  vi.advanceTimersByTime(100);
+  expect(fn).toHaveBeenCalledTimes(1); // Trailing call cancelled
+});
+
+test('throttle flush', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100);
+
+  throttled(1);
+  expect(fn).toHaveBeenCalledTimes(1);
+
+  throttled(2);
+  throttled(3);
+  throttled.flush();
+
+  expect(fn).toHaveBeenCalledTimes(2);
+  expect(fn).toHaveBeenCalledWith(3);
+
+  vi.advanceTimersByTime(100);
+  expect(fn).toHaveBeenCalledTimes(2); // Already flushed
+});
+
+test('throttle preserves this context', () => {
+  const obj = {
+    value: 42,
+    fn(this: any, arg: number) {
+      return this.value + arg;
+    },
+  };
+
+  const throttled = throttle(obj.fn, 100);
+  throttled.call(obj, 10);
+
+  expect(obj.value).toBe(42);
+  // Function executes with correct context
+});
+
+test('throttle multiple calls within wait period', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100);
+
+  throttled(1);
+  expect(fn).toHaveBeenCalledTimes(1);
+  expect(fn).toHaveBeenCalledWith(1);
+
+  vi.advanceTimersByTime(50);
+  throttled(2);
+  expect(fn).toHaveBeenCalledTimes(1); // Still only called once
+
+  vi.advanceTimersByTime(50);
+  // After 100ms total, should execute immediately with latest args
+  expect(fn).toHaveBeenCalledTimes(2);
+  expect(fn).toHaveBeenCalledWith(2);
+
+  vi.advanceTimersByTime(50);
+  throttled(3);
+  expect(fn).toHaveBeenCalledTimes(3);
+  expect(fn).toHaveBeenCalledWith(3);
+});
+
+test('throttle with leading and trailing both true', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100, {
+    leading: true,
+    trailing: true,
+  });
+
+  throttled(1);
+  expect(fn).toHaveBeenCalledTimes(1);
+  expect(fn).toHaveBeenCalledWith(1);
+
+  throttled(2);
+  expect(fn).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(100);
+  expect(fn).toHaveBeenCalledTimes(2);
+  expect(fn).toHaveBeenCalledWith(2);
+});
+
+test('throttle rapid successive calls', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100);
+
+  for (let i = 0; i < 10; i++) {
+    throttled(i);
+    vi.advanceTimersByTime(10);
+  }
+
+  // Should be called multiple times (once per 100ms)
+  expect(fn).toHaveBeenCalled();
+  expect(fn.mock.calls.length).toBeGreaterThan(1);
+});
+
+test('throttle with zero wait time', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 0);
+
+  throttled(1);
+  expect(fn).toHaveBeenCalledTimes(1);
+
+  throttled(2);
+  vi.advanceTimersByTime(0);
+  expect(fn).toHaveBeenCalledTimes(2);
+});
+
+test('throttle cancel after flush', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100);
+
+  throttled(1);
+  expect(fn).toHaveBeenCalledTimes(1);
+
+  throttled(2);
+  throttled.flush();
+  expect(fn).toHaveBeenCalledTimes(2);
+
+  throttled.cancel();
+  vi.advanceTimersByTime(100);
+  expect(fn).toHaveBeenCalledTimes(2); // No additional call
+});
+
+test('throttle maintains last arguments', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100);
+
+  throttled('first');
+  expect(fn).toHaveBeenCalledWith('first');
+
+  throttled('second');
+  throttled('third');
+  expect(fn).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(100);
+  expect(fn).toHaveBeenCalledTimes(2);
+  expect(fn).toHaveBeenCalledWith('third'); // Last call's arguments
+});
+
+test('throttle with multiple arguments', () => {
+  const fn = vi.fn();
+  const throttled = throttle(fn, 100);
+
+  throttled(1, 'a', true);
+  expect(fn).toHaveBeenCalledWith(1, 'a', true);
+
+  throttled(2, 'b', false);
+  throttled(3, 'c', true);
+  expect(fn).toHaveBeenCalledTimes(1);
+
+  vi.advanceTimersByTime(100);
+  expect(fn).toHaveBeenCalledTimes(2);
+  expect(fn).toHaveBeenCalledWith(3, 'c', true);
 });