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
• [x] Add types