nextframe

Promise for requestAnimationFrame / plus features like nextFrames, frameSequence, delay, throttleFrames, waitFrames

overview

nextFrame

create a Promise that resolves in the next Animationframe @param {...} args - optional values that would be the params of the Promises resolve @return {Promise} which will resolve in the next Animationframe

wait / alias waitFrames

waiting x frames before the Promise will resolve @param {Number} frame - the number of frames the Promise waits before resolving @param {...} args - optional values that would be the params of the Promises resolve @return {Promise} which will resolve after the waiting frames

when

resolve when fn returns a truthy value. @param {Function} fn a function that will be called every frame to check for changes @param {...[type]} args - optional values that would be the params of the Promises resolve @return {Promise} which will resolve after the waiting frames

until

until fn returns a truthy value do not resolve. @param {Function} fn a function that will be called every frame to check for changes @param {...[type]} args - optional values that would be the params of the Promises resolve @return {Promise} which will resolve after the waiting frames

loop

create an animationframe loop that calls a function (callback) in every frame @param {Function} cb - gets called in every frame - for rendering mostly @return {Function} a function which cancels the initialed loop by calling it

throttle / alias throttleFrames

create a throttled animationframe loop that calls a function (callback) in every specified @param {Function} cb gets called in every specified frame @param {Number} throttle in wich interval cb is called @return {Function} a function which cancels the initialed loop by calling it

delay

delays the call to nextFrame with setTimeout @param {Number} ms delay in ms @param {...} args - optional values that would be the params of the Promises resolve @return {Promise} which will resolve after the delayed animationframe

sequence

call a function sequencely every next frame on every iterating position of an array @param {Array} collection keeps all values that will be used as the argument for the function @param {Function} fn will be called with array values as aruments @return {Promise} which will resolve after the sequence

usage

import { nextFrame, loop, sequence, delay, throttleFrames, waitFrames } from 'nextframe';


const now = require('performance-now');
const increment = val => ++val;

const sequenceValues = [1, 2, 3, 4];
let frameCount = 0;
let throttleCount = 0;

const start = now();

/****************************
		nextFrame / frame
****************************/
nextFrame()
	.then(() => {
		console.log('next frame');
	})

/****************************
		delay
****************************/
delay(1000).then(() => {
	console.log('delayed ' + (now() - start) + 'ms');
});

/****************************
		sequence / frameSequence
****************************/
sequence(sequenceValues, increment)
	.then(result => console.log(result));

/****************************
		loop / nextFrames / onEnterFrame
****************************/
const cancelLoop = loop(() => {
	console.log('frame', ++frameCount);
	if (frameCount >= 100) {
		cancelLoop();
	}
});

/****************************
		throttleFrames / throttle
****************************/
const cancelThrottle = throttleFrames(() => {
	console.log('throttle', ++throttleCount);
	if (throttleCount >= 10) {
		cancelThrottle();
	}
}, 10);

/****************************
		waitFrames / wait
****************************/
waitFrames(50).then((count) => {
	console.log(count + ' frames waited');
})

tests

(passing)

import test from 'ava';
import now from 'performance-now';

import nextFrame, { nextFrames, delay, sequence, waitFrames, throttleFrames } from './lib';

test('call next frame with argument', async t => {
	const value = await nextFrame('check');
	t.is(value, 'check');
});

test('delay 1s', async t => {
	const start = now();
	const value = await delay(1000, 'check');
	const duration = now() - start;
	t.is(value, 'check');
	t.truthy(duration >= 1000 && duration <= 1100);
});

test('sequence', async t => {
	const values = [1, 2, 3, 4];
	const increment = val => ++val;
	const result = await sequence(values, increment);
	t.deepEqual(result, [2, 3, 4, 5]);
});

test('nextFrames loop', async t => {
	const p = new Promise(resolve => {
		let i = 0;
		const cancel = nextFrames(() => {
			++i;
			if (i >= 20) {
				cancel();
				resolve(20);
			}
		})
	})
	const result = await p;
	t.is(result, 20);
});

test('wait 50 frames', async t => {
	let i = 0;
	const cancel = nextFrames(() => ++i);

	const result = await waitFrames(50);

	cancel();
	t.is(result, 50);
	t.is(i, 50);
});

test('throttle frames', async t => {
	let i = 0;
	let throttleCount = 0;

	const p = new Promise(resolve => {
		const cancel = nextFrames(() => ++i);

		const cancelThrottle = throttleFrames(() => {
			if (++throttleCount >= 10) {
				cancelThrottle();
				cancel();
				resolve(throttleCount)
			}
		}, 10);
	});
	const result = await p;
	t.is(result, 10);
	t.is(i, 100);
});