[!NOTE] Why Zep()? Because Zep() allows you to create time-invoked callbacks but with deferred execution! Zep() does debouncing in a very efficient manner by only creating 1 Timer * - provided by setInterval. Some use cases are: when you are processing user input but want to wait until they have finished typing or you are using a 3rd-party API that calls an event handler too often - you can throttle those calls or when your event handler does intensive computing and you want to minimize workload. It limits the rate at which a function/handler can be fired/triggered, thus increasing performance/responsiveness of your product.

* other debounce functions/modules create dozens, even hundreds of Timers in order to provide the same functionality.

🕵🏼 Usage

Install it by executing:

npm i "@igor.dvlpr/zep"

🤹🏼 API

Types

type ZepCallback = (...args: any[]) => void

Used as a type for the callback provided in the constructor.

type ZepErrorHandler = (error: unknown) => void

Used as a type for the callback used in handling errors.

type ZepEventHandler = () => void

Used as a type for Zep events.

Methods

constructor(callback: ZepCallback, time?: number): Zep

Creates a new instance of Zep.

• callback - the function/callback to debounce.
• time - the time limit (in ms) for the debouncing.

example.ts

import { Zep } from '@igor.dvlpr/zep'

// pass an arrow function
const zep: Zep = new Zep((value: string) => {
  // code to limit its execution rate
}, 1500)

function myFunction(value: string) {
  /* some code */
}

// or an existing function
const zep: Zep = new Zep(myFunction, 1500)

//  You can have as many arguments in your callback function as you want.

onCancelled(handler: ZepEventHandler): Zep

A handler to call when the execution of Zep.run() has been cancelled.
See also Zep.cancel().

onAborted(handler: ZepEventHandler): Zep

A handler to call when the execution of Zep.run() has been aborted.
See also Zep.abort().

onBeforeRun(handler: ZepEventHandler): Zep

A handler to call before each call to your callback.

onAfterRun(handler: ZepEventHandler): Zep

A handler to call after each call to your callback.

onCompleted(handler: ZepEventHandler): Zep

A handler to call after Zep() has finished running, i.e. no more calls to the Zep.run() method have been issued in the given time-frame.

onError(handler: ZepEventHandler, error: Error): Zep

A handler to call when an error has occurred during execution.

abort(): void

Aborts the execution, stops Zep completely and - if applicable - the currently running Timer without waiting for it to finish its execution. See also Zep.cancel().

cancel(): void

Stops the execution but NOT the current running Timer - if applicable. See also Zep.abort().

run(...args): void

Runs the callback defined in the constructor if necessary or else debounces it.

writeStats(): void

Writes Zep() statistical information to the console, sample output,

[Zep]: invocations: 500, callback executions: 32, saving of 93.60% calls.

☝ Means that the event was triggered 500 times but Zep() debounced it and only executed its handler 32 times instead, the handler was called 93.60% less than without using Zep().

Properties

executionCount: number

Returns the number of callback executions.

isWaiting: boolean

Indicates whether Zep() is waiting for a Timer to finish its execution, if true, Zep.run() won't create new Timers when called.

isRunning: boolean

Indicates whether a Timer is currently running the callback provided in the constructor.

wasCancelled: boolean

Indicates whether the execution of Zep.run() was cancelled. Execution can be cancelled by calling Zep.cancel().

wasAborted: boolean

Indicates whether the execution of Zep.run() was aborted. Execution can be aborted by calling Zep.abort().

✨ Example

zep.ts

import { Zep } from '@igor.dvlpr/zep'


// pass an arrow function
const zep: Zep = new Zep((value: string) => {
  // code to limit its execution rate
}, 1500)

// then pass Zep's run() method to the event instead the original function

// code
const picker = vscode.window.createQuickPick()

// this is by default triggered each time a user types a character inside the QuickPick
 picker.onDidChangeValue((e: string) => {
	 zep.run(e)
 }

// due to the nature of JavaScript the following WON'T WORK,
// when you pass a class method as a parameter that
// method will get detached from the class and lose its track of <this>,
// which will be globalThis/undefined, thus resulting in an error,
 picker.onDidChangeValue(zep.run)

 // but you could use any of the 2 techniques

 // ****
 function changeHandler(): void {
	 zep.run()
 }

 // and then use that wrapper-function
 picker.onDidChangeValue(changeHandler)
  // ****

	// or

// ****
const changeHandler: Function = zep.run.bind(zep)
 picker.onDidChangeValue(changeHandler)
  // ****

 // by using Zep we can wait for the user to finish their input
 // if they haven't typed a single letter = the onDidChangeValue wasn't
 // triggered for 1500ms (1.5s) we assume they finished typing

// more code

📝 Changelog

✨ Changelog is available here: CHANGELOG.md.

🪪 License

Licensed under the MIT license which is available here, MIT license.

🧬 Related

@igor.dvlpr/scrollend-polyfill

🛴 A performant and light (< 1KB) JavaScript polyfill for the scrollend Event. ⛸️

@igor.dvlpr/extendable-string

🦀 ExtendableString allows you to create strings on steroids that have custom transformations applied to them, unlike common, plain strings.. 🪀

@igor.dvlpr/zing

🐌 Zing is a C# style String formatter for JavaScript that empowers Strings with positional arguments - composite formatting. 🚀

@igor.dvlpr/node-clone-js

🧬 A lightweight JavaScript utility allowing deep copy-by-value of nested objects, arrays and arrays of objects. 🪁

@igor.dvlpr/upath

🎍 Provides a universal way of formatting file-paths in Unix-like and Windows operating systems as an alternative to the built-in path.normalize(). 🧬

Provided by Igor Dimitrijević (@igorskyflyer).