TimingService
katanakit-js / TimingService
Class: TimingService
Section titled “Class: TimingService”Defined in: core/services/timing.service.ts:37
TimingService — Singleton facade for timers, intervals, debounce/throttle and promise races.
Applies the Singleton pattern (one shared instance via
TimingService.getInstance) and the Facade pattern: each public
method hides the setTimeout bookkeeping behind one call. The service holds
no shared state — every timer’s state lives in the closure returned to the
caller — so the instance is safe to share across environments (Node, Bun,
browser, SSR).
Every public method uses the use* prefix per CONTRIBUTING.md; the module
level use* functions below are thin wrappers kept for call-site ergonomics.
Example
Section titled “Example”import { useSetTimeout } from "katanakit-js";
const { promise, cancel } = useSetTimeout(() => 42, 1000);cancel(); // rejects the promise with "Timeout cancelled"Methods
Section titled “Methods”useDebounce()
Section titled “useDebounce()”useDebounce<T>(func, delayMs): (...args) => void;Defined in: core/services/timing.service.ts:204
Returns a debounced version of func that delays invocation until
delayMs milliseconds of quiet.
Type Parameters
Section titled “Type Parameters”| Type Parameter | Description |
|---|---|
T extends (…args) => unknown |
The wrapped function type. |
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
func |
T |
Function to debounce. |
delayMs |
number |
Debounce delay in milliseconds. |
Returns
Section titled “Returns”A debounced function with the same signature.
(…args) => void
Example
Section titled “Example”const debouncedSearch = useDebounce(fetchResults, 300);input.addEventListener("input", () => debouncedSearch(input.value));useDebounceImmediate()
Section titled “useDebounceImmediate()”useDebounceImmediate<T>(func, delayMs): (...args) => void;Defined in: core/services/timing.service.ts:245
Leading-edge debounce: fires immediately on the first call, then ignores
calls until delayMs of quiet. Additional calls during the wait window
schedule a single trailing invocation with the latest arguments.
Type Parameters
Section titled “Type Parameters”| Type Parameter | Description |
|---|---|
T extends (…args) => unknown |
The wrapped function type. |
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
func |
T |
Function to debounce. |
delayMs |
number |
Debounce delay in milliseconds. |
Returns
Section titled “Returns”A debounced function with the same signature.
(…args) => void
Example
Section titled “Example”const save = useDebounceImmediate(submitForm, 500);save("a"); // fires immediatelysave("b"); // queuedsave("c"); // queued (replaces "b")// after 500ms of quiet: fires with "c"useInterval()
Section titled “useInterval()”useInterval( callback, ms, immediate?): IntervalControl;Defined in: core/services/timing.service.ts:146
Repeatedly executes a callback at ms intervals with pause/resume/stop
controls. Uses recursive setTimeout internally to avoid overlap.
Parameters
Section titled “Parameters”| Parameter | Type | Default value | Description |
|---|---|---|---|
callback |
() => void | Promise<void> |
undefined |
Function executed on each tick. |
ms |
number |
undefined |
Interval in milliseconds. |
immediate? |
boolean |
false |
If true, fires the callback immediately before the first interval (defaults to false). |
Returns
Section titled “Returns”An IntervalControl with pause, resume, stop, and
isRunning.
Example
Section titled “Example”const timer = useInterval(() => console.log("tick"), 1000);setTimeout(() => timer.pause(), 3000);setTimeout(() => timer.resume(), 5000);setTimeout(() => timer.stop(), 10000);useRace()
Section titled “useRace()”useRace<T>( promise, timeoutMs, errorMessage?): Promise<T>;Defined in: core/services/timing.service.ts:424
Races a promise against a timeout. Clears the timer when the promise wins so the timeout rejection cannot become an unhandled rejection.
Type Parameters
Section titled “Type Parameters”| Type Parameter | Description |
|---|---|
T |
The promise’s resolved type. |
Parameters
Section titled “Parameters”| Parameter | Type | Default value | Description |
|---|---|---|---|
promise |
Promise<T> |
undefined |
The promise to race. |
timeoutMs |
number |
undefined |
Timeout in milliseconds. |
errorMessage? |
string |
"Operation timed out" |
Error message on timeout (defaults to "Operation timed out"). |
Returns
Section titled “Returns”Promise<T>
The resolved value of the promise.
Throws
Section titled “Throws”If the timeout fires first.
Example
Section titled “Example”try { const data = await useRace(fetch("/api"), 5000);} catch (e) { console.error(e); // "Operation timed out"}useRepeat()
Section titled “useRepeat()”useRepeat( callback, iterations, delayMs?): Promise<void>;Defined in: core/services/timing.service.ts:385
Executes a callback iterations times with an optional delay between
each iteration.
Parameters
Section titled “Parameters”| Parameter | Type | Default value | Description |
|---|---|---|---|
callback |
(iteration) => void | Promise<void> |
undefined |
Function called on each iteration with the current index (0-based). |
iterations |
number |
undefined |
Number of times to repeat. |
delayMs? |
number |
0 |
Delay between iterations in milliseconds (defaults to 0). |
Returns
Section titled “Returns”Promise<void>
Example
Section titled “Example”await useRepeat((i) => console.log(`Attempt ${i + 1}`), 3, 1000);// Attempt 1 ... (1s) ... Attempt 2 ... (1s) ... Attempt 3useSetTimeout()
Section titled “useSetTimeout()”useSetTimeout<T>(callback, ms): TimeoutControl<T>;Defined in: core/services/timing.service.ts:66
Executes a callback after ms milliseconds, returning a cancellable
promise that resolves with the callback’s result.
Type Parameters
Section titled “Type Parameters”| Type Parameter | Description |
|---|---|
T |
The callback’s return type. |
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
callback |
() => T | Promise<T> |
Function to execute after the delay. |
ms |
number |
Delay in milliseconds. |
Returns
Section titled “Returns”A TimeoutControl with promise and cancel().
Example
Section titled “Example”const { promise, cancel } = useSetTimeout(() => 42, 1000);cancel(); // rejects the promise with "Timeout cancelled"useThrottle()
Section titled “useThrottle()”useThrottle<T>(func, limitMs): (...args) => void;Defined in: core/services/timing.service.ts:300
Returns a throttled version of func that fires at most once per
limitMs milliseconds (leading edge).
Type Parameters
Section titled “Type Parameters”| Type Parameter | Description |
|---|---|
T extends (…args) => unknown |
The wrapped function type. |
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
func |
T |
Function to throttle. |
limitMs |
number |
Minimum interval between invocations in milliseconds. |
Returns
Section titled “Returns”A throttled function with the same signature.
(…args) => void
Example
Section titled “Example”const throttledScroll = useThrottle(onScroll, 100);window.addEventListener("scroll", throttledScroll);useThrottleTrailing()
Section titled “useThrottleTrailing()”useThrottleTrailing<T>(func, limitMs): (...args) => void;Defined in: core/services/timing.service.ts:336
Throttle with trailing invocation: fires on the leading edge and also fires once at the end of the throttle window with the latest arguments.
Type Parameters
Section titled “Type Parameters”| Type Parameter | Description |
|---|---|
T extends (…args) => unknown |
The wrapped function type. |
Parameters
Section titled “Parameters”| Parameter | Type | Description |
|---|---|---|
func |
T |
Function to throttle. |
limitMs |
number |
Minimum interval between invocations in milliseconds. |
Returns
Section titled “Returns”A throttled function with the same signature.
(…args) => void
Example
Section titled “Example”const throttledResize = useThrottleTrailing(onResize, 200);window.addEventListener("resize", throttledResize);getInstance()
Section titled “getInstance()”static getInstance(): TimingService;Defined in: core/services/timing.service.ts:44
Returns the shared instance (Singleton).
Returns
Section titled “Returns”TimingService