# Framesync

A tiny frame scheduler for performantly batching reads, updates and renders.

Segregating actions that read and write to the DOM will avoid [layout thrashing](https://developers.google.com/web/fundamentals/performance/rendering/avoid-large-complex-layouts-and-layout-thrashing).

It's also a way of ensuring order of execution across a frame. For instance, [Framer Motion](https://github.com/framer/motion) batches animations on the `update` step, and renders on the `render` step, allowing independent animation of `transform` properties.

## Install

```bash
npm install framesync
```

## Usage

Framesync splits a frame into discrete `read`, `update`, `preRender`, `render` and `postRender` steps.

### Scheduling functions

Functions can be scheduled to different parts of the render loop with `sync`.

```javascript
import sync from 'framesync';
```

It provides four functions, one for scheduling a function to run on each part of the frame:

```javascript
sync.update(() => {});
```

### Frame data

Each function is provided data about the current frame:

```javascript
sync.update(({ delta, timestamp }) => {});
```

- `delta`: Time since last frame (in milliseconds)
- `timestamp`: Timestamp of the current frame.

This object is recycled across frames, so values should be destructured if intended to be used asynchronously.

### Keep alive

We can run a function as an ongoing process by passing `true` as the second parameter:

```javascript
let count = 0;

sync.update(() => count++, true);
```

This will keep the process running until it's actively cancelled.

### Run immediately

The third parameter, `immediate`, can be used to sync a function on the **current frame step**.

By default, Framesync will schedule functions to run the next time that frame step is fired:

```javascript
sync.update(({ timestamp }) => {
  // The following function will run on the subsequent frame:
  sync.update((frame) => frame.timestamp !== timestamp);
});
```

By setting `immediate` to `true`, we can add this at the end of the current step:

```javascript
sync.update(({ timestamp }) => {
  // The following function will run on the **current** frame:
  sync.update(
    (frame) => frame.timestamp === timestamp,
    false,
    true
  );
});
```

### Cancelling

Synced processes can be cancelled with the `cancelSync` function:

```javascript
import sync, { cancelSync } from 'framesync';

let count = 0;

const process = sync.render(() => {
  count++;
  if (count >= 10) cancelSync.render(process);
}, true);
```