pulse-gate
v1.1.1
Published
Metronome but to lock function calls
Maintainers
cabbit-kheemaReadme
pulse-gate
A lightweight utility to throttle function calls to a rhythmic interval, like a metronome for your code. pulse-gate ensures a function is only executed once per specified time window, ignoring additional calls until the next "pulse."
Installation
Install via npm:
npm install pulse-gateUsage
pulseGate takes a function and an interval (in milliseconds) and returns a wrapped version of that function. The wrapped function will only execute when the interval "pulse" allows it, based on the system clock.
Example
import pulseGate from 'pulse-gate';
// A simple greeting function
const logHello = (name) => console.log(`Hello, ${name}!`);
const gatedLog = pulseGate(logHello, 1000); // 1-second pulse
gatedLog("Alice"); // Logs: "Hello, Alice!"
gatedLog("Bob"); // Ignored (within the same 1s pulse)
setTimeout(() => gatedLog("Charlie"), 1000); // Logs: "Hello, Charlie!"Real-world scenario
import pulseGate from 'pulse-gate';
// Real-world: Weather station telemetry
const sendTemperature = (temp) => fetch('/api/telemetry', {
method: 'POST',
body: JSON.stringify({ temperature: temp })
});
const gatedTempSend = pulseGate(sendTemperature, 5 * 60 * 1000); // 5-minute pulse
// Simulate noisy sensor readings
gatedTempSend(23.5); // Sends: 23.5°C to server
gatedTempSend(23.6); // Ignored (within same 5-min window)
setTimeout(() => gatedTempSend(24.0), 1000); // Ignored (still too soon)
setTimeout(() => gatedTempSend(24.2), 5 * 60 * 1000); // Sends: 24.2°C after 5 minHow It Works
- The
intervaldefines the length of each "pulse" window (e.g., 1000ms = 1 second). - The first call in a pulse window executes the function immediately and locks further calls until the next window.
- Pulse windows are aligned to the system clock (e.g., for a 1000ms interval, windows might start at 0ms, 1000ms, 2000ms, etc.).
- Subsequent calls within the same window are silently ignored.
API
pulseGate(func, interval)
func: The function to gate (can take any arguments).interval: Minimum time (in milliseconds) between allowed executions.- Returns: A wrapped function that respects the pulse timing.
Use Cases
- Rate-limiting API calls or events (e.g., button clicks, sensor triggers).
- Synchronizing repetitive tasks to a consistent beat.
- Preventing spam or accidental rapid-fire function calls.
Notes
- The gating is stateless and relies on
Date.now()for timing. - It’s not a debouncer or throttler in the traditional sense—it’s stricter, aligning to fixed intervals rather than trailing or leading edges.
Contributing
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.
If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!
Fork the Project
Create your Feature Branch (
git checkout -b feature/AmazingFeature)Commit your Changes (
git commit -m 'feat(new thing): Added some AmazingFeature')Commit message format to be followed: semantic-release | commit-message-format
<type>(<scope>): <short summary> │ │ │ │ │ └─⫸ Summary in present tense. Not capitalized. No period at the end. │ │ │ └─⫸ Commit Scope: animations|bazel|benchpress|common|compiler|compiler-cli|core| │ elements|forms|http|language-service|localize|platform-browser| │ platform-browser-dynamic|platform-server|router|service-worker| │ upgrade|zone.js|packaging|changelog|docs-infra|migrations| │ devtools │ └─⫸ Commit Type: build|ci|docs|feat|fix|perf|refactor|testPush to the Branch (
git push origin feature/AmazingFeature)Open a Pull Request
Please submit all pull requests to the
nextbranch for review.
Top contributors:
License
MIT
Contact
Prajwal K - @CabbitKheema - [email protected] - HackerRank
Project Link: https://github.com/CabbitKheema/pulse-gate