managed-timeout
v3.0.3
Published
setTimeout class wrapper with abilities to pause/resume, finish preemptively, and inspection
Downloads
66
Maintainers
Readme
managed-timeout
A setTimeout with extended functionality. Provides the ability to:
- pause/resume timeout.
- execute timeout preemptively, before the delay time passes
- reset or change the delay time
- inspect on whether a timeout is still pending, was canceled or finished normally
- optional promise support
Typescript support. Fully tested.
Installation
npm install --save managed-timeout
Usage
Callback-style
import { Timeout } from "managed-timeout";
// or const { Timeout } = require("managed-timeout");
let to = new Timeout(()=>console.log("Hello World"), 15000);
to.pause();
// do something
to.resume();
if (to.isPending) { /* do another something */ }
to.cancel();
Delayed start
Constructor can be supplied with only delay time. In that case, callback can be supplied to the start() method and the timeout would actually be launched after the call.
let to = new Timeout(3000);
to.start(()=>console.log("to fired"));
Promise-style
If no callback is supplied to the start method, it returns a promise.
Cancellation of a timeout will result in promise rejection.
Consequtive calls to the start method will result in a promise rejection. All the timeout methods should still be called on the timeout instance and not on the promise instance.
Or in simple terms: after a call to the start() method only then/catch/finally and other promise methods can be chained.
let to = new Timeout(3000);
to.start().then(()=>{
// do something
});
to.pause(); // timeout can be paused, continued, cancelled, etc as before
// or async/await style just as a pause
(async () => {
await new Timeout(5000).start();
console.log("called in 5 seconds");
})();
// BAD DON'T DO THIS -- a call on promise, not on the Timeout instance
new Timeout(3000).start().then(()=>{/* ... */}).pause();
API
Constructor
new Timeout(cb: (to: Timeout)=>void, delay: number)
Matches the setTimeout signature. Schedules to call cb function after delay milliseconds. Throws if cb isn't a function or delay isn't an integer or is less than zero
new Timeout(delay: number)
Delayed start timeout. Only creates an instance of a timeout, needs to be armed with a call to the start() method afterwards. Throws if delay isn't a number or is less than zero
Methods
start(): Promise<Timeout>
start(cb: (to: Timeout)=>void, cancelCb?: (to: Timeout, reason: any) => void): boolean
Arms a timeout created without a callback. If the method was called without a callback, then returns a promise, which will be resolved once the delay time is passed (timeout can be paused or resumed as usual).
Optional callback to be called if the timeout was cancelled can be supplied. Both callbacks receive the Timeout instance as their argument.
Consequentive calls with a callback will return false, without a callback will return a rejected promise (previously created promises continue to work as usual).
cancel(reason?: any): boolean
Cancels the timeout completely. Returns true if the timeout was stopped, false if it wasn't pending to begin with. Can recieve an optional reason, that will be passed to either cancelCb or which will be used as the promise rejection value (defaults to AbortError).
execute(): boolean
Execute pending timeout's callback preemptively, without waiting for the delay time and effectively finishing it. Returns true if the timeout was finished, false if it has already finished or has been canceled before.
pause(): boolean
Pauses the timeout. If it was already paused, then does nothing. Returns true if the timeout was paused, false otherwise.
resume(): boolean
Resumes the paused timeout. If the timeout wasn't paused, then does nothing. Returns true if the timeout was resumed, false otherwise.
reset(delay?: number): boolean
Resets the timeout with the previous delay time or with a new delay time. The timeout will be unpaused and set running if it was in the paused state. If called on non-started timeouts simply changes the delay time, without actually starting it. If delay is not supplied, uses the last delay (from the constructor or last reset call). Otherwise uses the new supplied delay, potentially throwing an error if it's not an integer or it is < 0. Returns true if the timeout was reset, false if it has already finished or has been canceled.
Properties
All properties are read-only unless stated otherwise.
state: TimeoutState
export type TimeoutState = "ready" | "pending" | "paused" | "resolved" | "cancelled";
paused: boolean
Status if timeout was paused or not. Writable (the same as calling pause/resume).
isPending: boolean
True if timeout is pending for execution (actively running or paused).
isStarted: boolean
True if timeout was started via the start method or via callback provision to the constructor. Remains true disregarding if timeout is pending, cancelled or finished.
isCanceled: boolean
True if timeout was canceled.
isFinished: boolean
True if timeout was finished (normally or preemptively).
isFinishedPreemptively: boolean
True if timeout was finished preemptively.
timeLeft: number
Time left before the timeout execution. It won't change from call to call when the timeout is paused.
timePassed: number
Number of milliseconds of delay time passed. Basically delay - timeLeft
.
delay: number
Currently set total delay time (from the constructor or consecutive calls to reset).
Contributing
If you have any ideas or suggestions or want to report a bug, feel free to write in the issues section or create a PR.
License
managed-timeout is ISC licensed.