Kang Timeline

Disclamer : This little project has been made for my personal use but I thougth it could be interesting to share it.

Presentation

Timeline is a Javascript Library for the window.requestAnimationFrame() API. It provides some classes which can give you more controle on the recursives calls made by a requestAnimationFrame (or rAF for short) loop.

Installation

$ npm i -S kang-timeline

Import

You can import the library as an es module :

import Timeline from 'kang-timeline'

Or via the exposed varible Timeline :

<script src="/path/to/timeline.min.js"></script>

const timer = new Timeline()

Classes and Methods

• The Provider TimeProvider
• The Timeline class new Timeline()
  • id
  • speed
  • task
• The Timestamp class Timestamp
• Control Methods
• Key Times methods
  • Timestamp.addKeytime([ Object | Array ])
  • Timestamp.removeKeytimes([ Number | String | Array ])
  • Timestamp.listKeytimes()
• Todolist

The Provider TimeProvider

TimeProvider represents the global time of our system. It is basically a recursive loop made with rAFs and to which are attached utilitary methods.

// Basic rAF loop

const callback = ts => {
	// do something
	return window.requestAnimationFrame(callback)
}

const loop = window.requestAnimationFrame(callback)

All methods are static and so utilitary. To consume the TimeProvider, you need to create a new Timeline.

Methods	Description
subscribe	Add Timelines to the timeSubscribers private property
start	Start the loop
loop	The loop callback

The Timeline class new Timeline()

The Timeline class is actually a subscriber to the TimeProvider. All Timelines share the same loop provided by the TimeProvider class but also have their own current timestamp.

You can add some options to your Timeline by passing an object as argument, or by setting those options afterward via methods.

// by argument
const timer = new Timeline({
	task: () => {
		/* do something */
	}
})

// OR by method
const timer = new Timeline()
timer.setTask(() => {
	/* do something */
})

id

Name	Type	Default
`Number	String`	Date.now()

All Timelines have a unique id which is basically a simple Date.now() in milliseconds but you can specify a one.

const timer = new Timeline({ id: 'timer1' }))

speed

Name	Type	Default
speed	Number	1

The speed define how fast the time should pass. It can be less than 0 or greater than 1 but the current timestamp will obviously be negative and less precise respectively.

const timer = new Timeline({ speed: 0.5 }))

task

Name	Type	default
task	Function | Object | null	null

Task is executed at each loop iterration. It can be a simple function or an object with a function to execute at a given frequency.

const timer = new Timeline({
	task: ts => {
		/* do something */
	}
})

const timer = new Timeline({
    task: {
        frequency: 1000, // each second
        run: timestamp => { /* do something */ }
    }
}))

As you can see, you can retrive the current timestamp and other informations about your Timeline as the argument described further below.

range

Name	Type	default
range	number | [number, number] | null	null

A range between which the timeline will be effective, with the first index being the minimum and the second being the maximum. If set as a number, the range become [0, number] with 0 as minimum.

The Timestamp class Timestamp

Because each Timeline are based on a provided time, you can access to some informations about your Timeline throught the unique parameter of a task.

Properties	Type	Description
currentTime	Number	The current timestamp of your Timeline
globalTime	Number	The global timestamp, offered by the TimeProvider

Control Methods

You can control each Timeline by simple methods, which all can take a delay and a callback as parameters.

Methods	Description
start	Start the Timeline
stop	Stop the Timeline
reset	Reset the Timeline, by stopping it firstly and then reseting all its values.

// Create a new Timeline
const timer = new Timeline()

// One by one :
// 1. start the Timeline
timer.start()
// 2. stop the Timeline after 5 seconds
timer.stop(5000)
// 3. reset the Timeline after 1 second
timer.reset(1000)

// Or in chain :
timer.start().stop(5000).reset(1000)

Usually, the targeted timestamp and the actual execution timestamp have a delta of 17ms. So you can use those same methods under the sync property.

Key Times methods

Timestamp.addKeytime([ Object | Array ])

A key time trigger a callback at a specifed timestamp. You can multiple key times by passing an array to the method.

Properties	Type	Description
id	Number | String	A unique id
timestamp	Number	The targeted timestamp
task	Function	The callback to run

// We create our Timeline instance
const timer = new Timeline()

// And we add a keytime
timer.addKeytime({
  id: 'log-0',
  timestamp: 5000
  task: timestamp => {
    console.log(timestamp)
  }
})

Timestamp.removeKeytimes([ Number | String | Array ])

Remove key times by their id.

// Our "log-0" key time is still there
// Let's remove it
timer.removeKeytime('log-0')

Timestamp.listKeytimes()

Also you can list all your keytimes by this method. They will be listed in order to their timestamp.

const list = timer.listKeytimes()

console.log(list)
/* Output
[
  {
    id: "log-1",
    timestamp: 5000,
    run: ts => { console.log(ts) }
  },
  {
    id: "log-3",
    timestamp: 8000,
    ...
  }
]
*/

Todolist

• Add a demo page
• Add a record solution (method) to extract our timelines and replay, pause, modify them on demand. This could be a good feature for animators
• Add types