Tickerjs

Installation

npm install @projectleo/tickerjs

npm install @projectleo/tickerjs

Examples

Basic example:

import { five, requestAnimationFrames } from '@projectleo/tickerjs'

const cancelAnimationFrames = requestAnimationFrames({
    actionOnFrame() {
        console.log(performance.now())
    },
})

setTimeout(cancelAnimationFrames, five.second)

import { five, requestAnimationFrames } from '@projectleo/tickerjs'

const cancelAnimationFrames = requestAnimationFrames({
    actionOnFrame() {
        console.log(performance.now())
    },
})

setTimeout(cancelAnimationFrames, five.second)

Complicated example:

import {
    twentyFour,
    thirty,
    requestAnimationFrames,
    getStructuredTime,
} from '@projectleo/tickerjs'

/* some code */

const totalTime = thirty.second

const { minute: totalMinutes, second: totalSeconds } = getStructuredTime(
    totalTime,
    'minute',
)

const totalTimeText = ` / ${String(totalMinutes)
    .padStart(2, '0')}:${String(totalSeconds)
    .padStart(2, '0')}`

requestAnimationFrames({
    totalTime,
    frameRate: twentyFour.fps,
    actionOnStart() {
        audioElement.play()
    },
    actionOnFrame({ remainingTime, frameCount }) {
        /* some code */

        const { minute: currentMinutes, second: currentSeconds } =
            getStructuredTime(totalTime - remainingTime, 'minute')

        ctx.drawImage(imageFrames[frameCount - 1], 0, 0)
        ctx.fillText(
            `${String(currentMinutes)
                .padStart(2, '0')}:${String(currentSeconds)
                .padStart(2, '0')}${totalTimeText}`,
            4,
            20,
        )

        /* some code */
    },
    actionOnEnd() {
        audioElement.pause()
    },
})

import {
    twentyFour,
    thirty,
    requestAnimationFrames,
    getStructuredTime,
} from '@projectleo/tickerjs'

/* some code */

const totalTime = thirty.second

const { minute: totalMinutes, second: totalSeconds } = getStructuredTime(
    totalTime,
    'minute',
)

const totalTimeText = ` / ${String(totalMinutes)
    .padStart(2, '0')}:${String(totalSeconds)
    .padStart(2, '0')}`

requestAnimationFrames({
    totalTime,
    frameRate: twentyFour.fps,
    actionOnStart() {
        audioElement.play()
    },
    actionOnFrame({ remainingTime, frameCount }) {
        /* some code */

        const { minute: currentMinutes, second: currentSeconds } =
            getStructuredTime(totalTime - remainingTime, 'minute')

        ctx.drawImage(imageFrames[frameCount - 1], 0, 0)
        ctx.fillText(
            `${String(currentMinutes)
                .padStart(2, '0')}:${String(currentSeconds)
                .padStart(2, '0')}${totalTimeText}`,
            4,
            20,
        )

        /* some code */
    },
    actionOnEnd() {
        audioElement.pause()
    },
})

APIs

Core function

/**
 * @throws {RangeError} `NaN`, `0`, negative numbers and non-integers are not valid for `totalTime` and `frameRate`.
 * @throws {RangeError} `Infinity` is not valid for `frameRate`.
 */
const requestAnimationFrames: (args: {
    totalTime?:⁰ number;
    frameRate?:¹ number;
    actionOnStart?:² () => void;
    actionOnFrame:³ (args: {
        remainingTime:⁴ number;
        frameCount:⁵ number;
        delta:⁶ number;
        time:⁷ number;
    }) =>⁸ void | {
        continueHandleFrames: boolean;
    };
    actionOnEnd?:⁹ () => void;
}) =>¹⁰ (never | (() => void));

/**
 * @throws {RangeError} `NaN`, `0`, negative numbers and non-integers are not valid for `totalTime` and `frameRate`.
 * @throws {RangeError} `Infinity` is not valid for `frameRate`.
 */
const requestAnimationFrames: (args: {
    totalTime?:⁰ number;
    frameRate?:¹ number;
    actionOnStart?:² () => void;
    actionOnFrame:³ (args: {
        remainingTime:⁴ number;
        frameCount:⁵ number;
        delta:⁶ number;
        time:⁷ number;
    }) =>⁸ void | {
        continueHandleFrames: boolean;
    };
    actionOnEnd?:⁹ () => void;
}) =>¹⁰ (never | (() => void));

• ⁰ [totalTime]: Total time of animation, in milliseconds, if it is not specified, its value is Infinity.
• ¹ [frameRate]: Frame rate of animation, if it is not specified, the value of it is usually 60 (fps), but will generally match the display refresh rate in most web browsers as per W3C recommendation.
• ² [actionOnStart]: Called when the animation starts.
• ³ [actionOnFrame]: Called at every valid frames, it means that not every logical frames could call it if the specified frame rate is higher than display refresh rate.
• ⁴ [remainingTime]: Remaining time of animation, in milliseconds.
• ⁵ [frameCount]: Frame counts calculated from one, it doesn't always increase one by one if the specified frame rate is higher than display refresh rate.
• ⁶ [delta]: Delta timing, in seconds, its value is always 0 at the first frame.
• ⁷ [time]: Same as the parameter of callback for requestAnimationFrame.
• ⁸ [actionOnFrame()]: It could return a value to end the animation in advance, and actionOnEnd would be called.
• ⁹ [actionOnEnd]: Called when the animation ends.
• ¹⁰ [requestAnimationFrames()]: It would return a function used to cancel remaining animation frames, if use this function, actionOnEnd would not be called.

Configuration function

You may use polyfill if you need your application to run in any runtime that doesn't support requestAnimationFrame and cancelAnimationFrame. Tickerjs provides a function to help you to let them work with requestAnimationFrames without affecting the global variable.

const specifyAnimationFrameManager: <T>(args: {
    requestAnimationFrame:⁰ (callback: (time: number) => void) => T;
    cancelAnimationFrame:¹ (handle: T) => void;
}) => void;

const specifyAnimationFrameManager: <T>(args: {
    requestAnimationFrame:⁰ (callback: (time: number) => void) => T;
    cancelAnimationFrame:¹ (handle: T) => void;
}) => void;

• ⁰ [requestAnimationFrame]: Description on MDN Web Docs.
• ¹ [cancelAnimationFrame]: Description on MDN Web Docs.

Utility function

type StructuredTimeWithDayUnit = {
    day: number;
    hour: number;
    minute: number;
    second: number;
    millisecond: number;
};

type StructuredTimeWithHourUnit = {
    hour: number;
    minute: number;
    second: number;
    millisecond: number;
};

type StructuredTimeWithMinuteUnit = {
    minute: number;
    second: number;
    millisecond: number;
};

type StructuredTimes = {
    day: StructuredTimeWithDayUnit;
    hour: StructuredTimeWithHourUnit;
    minute: StructuredTimeWithMinuteUnit;
};

const getStructuredTime:
    <KEY extends keyof StructuredTimes>(totalMilliseconds:⁰ number, highestUnit:¹ KEY) =>²
    StructuredTimes[KEY];

type StructuredTimeWithDayUnit = {
    day: number;
    hour: number;
    minute: number;
    second: number;
    millisecond: number;
};

type StructuredTimeWithHourUnit = {
    hour: number;
    minute: number;
    second: number;
    millisecond: number;
};

type StructuredTimeWithMinuteUnit = {
    minute: number;
    second: number;
    millisecond: number;
};

type StructuredTimes = {
    day: StructuredTimeWithDayUnit;
    hour: StructuredTimeWithHourUnit;
    minute: StructuredTimeWithMinuteUnit;
};

const getStructuredTime:
    <KEY extends keyof StructuredTimes>(totalMilliseconds:⁰ number, highestUnit:¹ KEY) =>²
    StructuredTimes[KEY];

• ⁰ [totalMilliseconds]: Total time to be structured, in milliseconds.
• ¹ [highestUnit]: The highest unit to be used when structuring time, you can only choose one from 'day', 'hour' and 'minute'.
• ² [getStructuredTime()]: It would return an object that contains structured time fields, fields are based on specified highestUnit.

Tickerjs provides a series of commonly used numerical constants:

If you need other specific values for totalTime of requestAnimationFrames, these functions would be useful:

const second: (second: number) => number;
const minute: (minute: number) => number;
const hour: (hour: number) => number;
const day: (day: number) => number;

const second: (second: number) => number;
const minute: (minute: number) => number;
const hour: (hour: number) => number;
const day: (day: number) => number;

Troubleshooting

After I unpacking values from time numbers, some strange errors are thrown.

Time numbers are proxy values, not pure objects, don't use destructuring assignment syntax on them.

Animation sometimes would end before reaching expected frame counts.

If the total time of animation is specified, animation would always end when remaining time is exhausted. Depending on the refresh rate of display, if the specified frame rate is higher than display refresh rate, animation may end before reaching expected frame counts because of the runtime's calculation accuracy error.

When I use tickerjs in some browsers directly, some errors are thrown.

Tickerjs uses some latest JavaScript features in source code, the exported bundle also has not been processed by JavaScript compiler like Babel, you need to handle it yourself.

FAQ

Whether tickerjs has the same behavior with request­AnimationFrame?

Yes, like requestAnimationFrame, tickerjs would be paused in most browsers when running in background tabs or hidden <iframe>s. But the remaining time of animation would always be decreased, you should handle additional logic outside the tickerjs if you need to stop the remaining time being decreased.

If I use tickerjs on animation which has static frame rate and total frames, is there anything I should pay attention to?

Always getting current frame count from the parameter of actionOnFrame would ensure that the expected picture frame can be drawn. Because the actual frame rate is depending on refresh rate of display and busy level of runtime, sometimes the count of animation's total frames couldn't reach the expected maximum value, if you always hope it reaches maximum value, just don't set totalTime, but return one specific value (which means the animation can be over) in actionOnFrame when the expected value is reached.

When would actionOnStart and actionOnEnd be called?

actionOnStart would always be called immediately after requestAnimationFrames is called, tickerjs would ensure that actionOnStart can be called and then call actionOnFrame at least one time. actionOnEnd would always be called immediately when remaining time is exhausted or actionOnFrame returns one value which means the animation can be over, but if the condition of the end of animation is exhaustion of time, actionOnEnd may not be called immediately after last actionOnFrame was called, because the actionOnFrame may not be called at last physical frame.

Whether tickerjs could work with third party animation libraries?

Yes, if the animation library you use needs you to call requestAnimationFrame manually, because the behavior of the two code samples below is almost the same:

// without tickerjs

function callback(time) {
    doSomething(time)

    requestAnimationFrame(callback)
}

requestAnimationFrame(callback)

// with tickerjs

requestAnimationFrames({
    actionOnFrame({ time }) {
        doSomething(time)
    },
})

// without tickerjs

function callback(time) {
    doSomething(time)

    requestAnimationFrame(callback)
}

requestAnimationFrame(callback)

// with tickerjs

requestAnimationFrames({
    actionOnFrame({ time }) {
        doSomething(time)
    },
})

License

Tickerjs is MIT licensed.