@time-provider/addon-animation-frame

Time-Provider ~ Animation Frame API Addon

Description

This is the Animation Frame API addon for Time-Provider.
Extends the library by exposing the animation frame API (scheduleFrame) through a dedicated (scheduler.animation) facade.

Just like the plugin packages, this addon is tree-shakable.
It is split into a default (system/real-time) entry point and a deterministic one, so each import pulls in only the code it needs:

• @time-provider/addon-animation-frame - for a system (real time) Time-Provider created via @time-provider/core. scheduler.animation passes through to the real requestAnimationFrame/cancelAnimationFrame or throws a clear error otherwise (e.g. plain Node.js, which has no native equivalent).
• @time-provider/addon-animation-frame/deterministic - for a deterministic Time-Provider (fixed/manual/sequential) created via @time-provider/core/deterministic. scheduler.animation is simulated against that runtime's own clock.
  Registered callbacks fires once this runtime's own "now" has moved forward by at least one simulated frame duration.

Like the native requestAnimationFrame, each callback receives the frame time, on the clock.monotonicNow() timeline.

Usage

import { createTimeProvider } from "@time-provider/core";
import { createTimeProvider as createDeterministicTimeProvider } from "@time-provider/core/deterministic";
import { plugin } from "@time-provider/plugin-native";
import { plugin as deterministicPlugin } from "@time-provider/plugin-native/deterministic";
import { addon } from "@time-provider/addon-animation-frame";
import { addon as deterministicAddon } from "@time-provider/addon-animation-frame/deterministic";

// System: real requestAnimationFrame (or a clear error outside a browser)
const timeProvider = createTimeProvider.for(plugin).use(addon).create();
timeProvider.scheduler.animation.scheduleFrame(() => console.log("Frame!"));

// Deterministic: simulated against the runtime's own clock
const manual = createDeterministicTimeProvider
  .for(deterministicPlugin)
  .use(deterministicAddon)
  .asManual()
  .withInitialTime(0)
  .create();
manual.scheduler.animation.scheduleFrame(() => console.log("Frame!"));
manual.clock.moveBy({ milliseconds: 20 });

You can configure the simulated frame rate by chaining .withHostFramesRate(...) on the builder right after .use(...):

const manual = createDeterministicTimeProvider
  .for(deterministicPlugin)
  .use(deterministicAddon)
  .withHostFramesRate(90) //now simulating an animation frame API with 90 FPS
  .asManual()
  .withInitialTime(0)
  .create();

With the compat addon

Compose @time-provider/addon-compat before this addon and its .compat facade also gets requestAnimationFrame/cancelAnimationFrame, delegating to scheduleFrame and to the handle's dispose(). They are declared as an optional compat? on WithAnimationFrameApi, since they are only there when both addons are composed.

License

MIT