No Partying Mariachis

    tm-timer

    1.0.0 • Public • Published

    TM-Timer

    License: MIT Build Status

    A simple count-down Timer class, based on TM-Ticker (no GUI)

    Installation

    $ npm install tm-timer
    import Timer from 'tm-timer';
    // or
    const Timer = require('tm-timer');

    TL;DR

    Jump to API

    Create:

    // construct & config
    const t = new Timer(duration, finalCallback)
     
    // or just construct (and config later)
    const t = new Timer()

    Config:

    t.set(duration)
    t.whenDone(finalCallback)
    t.onTick(tickHandler)

    Use:

    now is optional

     t.start(now)
     t.getTimeLeft()
     t.stop(now)
     t.reset(now)
     t.destroy()

    API


    Constructor

    const t = new Timer(duration, finalCallback);
    • duration [number, optional*]
      * Required to start. optional at construction.
      Countdown in milliseconds. Pass null to set the callback alone.

    • finalCallback [function, optional]
      The function you want to call when countdown is over.

    Example:

    const fiveMinutes = 5 * 60 * 1000;
     
    const t = new Timer(fiveMinutes, () => {
        console.log('Game Over');
    });

    Configuration

    A Timer instance won't tick unless it has a duration.

    You can set the timer's duration and final callback on construction or later with the following methods which are very self explanatory:

    const myTimer = new Timer();
     
    myTimer.set(fiveMinutes)
    myTimer.whenDone(finalCallback)
    myTimer.onTick(myTickHandler)

    .set(duration)

    • duration [number, required]
      Set the total time in milliseconds to count down to.
    const fiveMinutes = 5 * 60 * 1000;
     
    myTimer.set(fiveMinutes);

    .whenDone(finalCallback)

    • finalCallback [function, required]
      Runs when timer finishes. Gets no arguments.
    myTimer.whenDone(() => {
        console.log("Time's Up!");
    });

    .onTick(callback)

    As the timer counts down, it ticks every 500ms (twice every second).
    Use when you can bind a tick handler function.
    The first tick happens on start, synchronously, before any timeout.

    • callback [function, optional]
      The callback function recieves two arguments:
      1. isBigTick [boolean]
        Equals true on "big" ticks (a whole second: 0, 1000, 2000, 3000 etc.)
        Equals false on "small" ticks (half a second: 500, 1500, 2500, 3500 etc.)
        For example, you could update your clock's digits on big ticks and blink the clock's colons on small ticks (04:20).

      2. timeLeft [number]
        Time left in milliseconds.

    Example:

    myTimer.onTick((isBigTick, timeLeft) => {
        console.log(isBigTick); //  | true | false | true | false |...
        console.log(timeLeft);  //  | 5000 | 4500  | 4000 | 3500  |...
     
        /*
        * NOTE:
        * The following functions are made up and are not part of TM-Timer.
        */
        if (isBigTick) {
            updateClock(timeLeft)
            showColons() // (04:20)
        }
        else {
            hideColons() // (04 20)
        }
    });

    Methods

    All methods can get called with a timestamp argument. Pass in a current timestamp when you need to sync time with other modules.

    • timestamp (ms, number, optional) - The timestamp to be considered as the method's execution time.

    .start()

    Start counting down.

    Calls the first tick (if a tick handler is set with .onTick(fn)).
    When called after a .stop() it acts as a "resume" function. There will be no start-tick in this case.

    // optional
    const timestamp = Date.now()
     
    myTimer.start(timestamp)

    .getTimeLeft()

    Returns how many milliseconds left.

    const myTimer = new Timer(3000, callback)
     
    myTimer.start()
     
    // after 2480 ms (for example)
    myTimer.getTimeLeft() // --> 520

    .stop()

    Stop/Pause counting down.

    Run .start() to resume.

    const myTimer = new Timer(fiveMinutes, gameOver)
     
    myTimer.start()
     
    // Take a break
    myTimer.stop()
     
    // Resume
    myTimer.start()

    .reset()

    Reset the countdown with full original duration.

    Can be called whether the timer is running or not. When called while running, it acts like a "restart" and doesn't stop the timer.

    const myTimer = new Timer(fiveMinutes, gameOver)
     
    myTimer.start()
     
    /* after 2 minutes */
    myTimer.reset() // re-start counting down five minutes. No stop.
    const myTimer = new Timer(fiveMinutes, gameOver)
     
    myTimer.start()
     
    /* after 2 minutes */
    myTimer.stop()
    myTimer.reset()
    myTimer.start() // start counting down five minutes.

    .destroy()

    Destroy the timer. Removes duration and bound callbacks.

    Cannot be used again unless re-configured.

    const myTimer = new Timer(fiveMinutes, gameOver)
     
    myTimer.start()
    myTimer.destroy()
     
    myTimer.set(fiveMinutes)
    myTimer.whenDone(gameOver)

    Playground


    $ npm run playground

    Install

    npm i tm-timer

    DownloadsWeekly Downloads

    6

    Version

    1.0.0

    License

    MIT

    Unpacked Size

    36.8 kB

    Total Files

    22

    Last publish

    Collaborators

    • taitulism