@projectleo/tickerjs

v1.2.1

Published

2 months ago

A more easier way to request animation frames.

Downloads

0High
0Medium
0Low

alengyuan

ticker requestAnimationFrame esm

Tickerjs @ProjectLeo ·

Tickerjs provides a more easier way to request animation frames.

Installation

npm install @projectleo/tickerjs

Examples

Basic example:

import { requestAnimationFrames } from '@projectleo/tickerjs'

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

setTimeout(cancelAnimationFrames, 5000)

Complicated example:

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

/* some code */

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

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

        const { minute: remainingMinutes, second: remainingSeconds } =
            getStructuredTime(remainingTime, 'minute')

        ctx.drawImage(imageFrames[frameCount], 0, 0)
        ctx.fillText(
            `${remainingMinutes}:${remainingSeconds} / ${totalMinutes}:${totalSeconds}`,
            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;
        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.
⁶ [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: (args: {
    requestAnimationFrame:⁰ (callback: (time: number) => void) => number;
    cancelAnimationFrame:¹ (handle: number) => 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:
    <T extends keyof StructuredTimes>(totalMilliseconds:⁰ number, highestUnit:¹ T) =>²
    StructuredTimes[T];

⁰ [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;

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

// without tickerjs

function callback(time) {
    doSomething(time)

    requestAnimationFrame(callback)
}

requestAnimationFrame(callback)

// with tickerjs

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

License

Tickerjs is MIT licensed.