Framesync

Common errors

• TypeError: framesync__WEBPACK_IMPORTED_MODULE_0__.default.update is not a function

  cause Attempting to use CommonJS `require` or an incorrect import statement with a bundler that doesn't handle ESM default exports properly, leading to `sync` being an object with a `default` property, not the `sync` object itself.
  fix Ensure you are using `import sync from 'framesync';` for the default export. If using CommonJS, try `const sync = require('framesync').default;` (though this is not recommended for pure ESM libraries).

• Uncaught TypeError: cancelSync.render is not a function

  cause `cancelSync` is a named export, and its methods (`.read`, `.update`, `.render`, etc.) are functions. This error often occurs if `cancelSync` itself is not correctly imported as a named export.
  fix Ensure `cancelSync` is imported as a named export: `import { cancelSync } from 'framesync';`

Warnings

• gotcha The `FrameData` object (containing `delta` and `timestamp`) passed to scheduled functions is recycled across frames for performance. If you need to use `delta` or `timestamp` asynchronously (e.g., in a `setTimeout` or `Promise`), you must destructure or copy its values, otherwise, they may change unexpectedly.
  Fix: Destructure the `FrameData` object immediately: `sync.update(({ delta, timestamp }) => { const currentDelta = delta; // use currentDelta asynchronously })`
• gotcha By default, `sync` functions schedule execution for the *next* time that frame step is fired. To execute a function on the *current* frame step, you must explicitly pass `true` as the third parameter for `immediate` execution.
  Fix: Use `sync.step(callback, keepAlive, true)` to run on the current frame step. For example: `sync.update(() => console.log('now!'), false, true);`
• gotcha When using the `keepAlive: true` option, a scheduled function will run indefinitely on every frame until it is explicitly cancelled using `cancelSync.<step>(process)`. Forgetting to cancel can lead to memory leaks and unnecessary CPU usage.
  Fix: Always ensure there's a clear condition to call `cancelSync.step(yourProcessFunction)` when using `keepAlive: true`.

Install

• npm install framesync npm
• yarn add framesync yarn
• pnpm add framesync pnpm

Imports

• sync
  wrong:

  const sync = require('framesync');

  correct:

  import sync from 'framesync';

  Framesync uses an ESM default export for the main `sync` object. CommonJS `require` will result in accessing `sync.default` if supported by your build system, or an error in a pure ESM environment.
• cancelSync
  wrong:

  const { cancelSync } = require('framesync');

  correct:

  import { cancelSync } from 'framesync';

  Named exports like `cancelSync` are provided. CommonJS `require` for named exports will fail in pure ESM environments and may behave unexpectedly in others.
• FrameData

  import type { FrameData } from 'framesync';

  Use a type import for the `FrameData` interface (containing `delta` and `timestamp`) when working with TypeScript.

Quickstart

Demonstrates scheduling a function to run on the `update` step of the render loop, accessing frame data, and canceling the process once a condition is met. It also shows an immediate render call.

import sync, { cancelSync } from 'framesync';

let animationProgress = 0;
const targetProgress = 100;

console.log('Starting framesync animation...');

const updateFunction = ({ delta, timestamp }) => {
  // In a real app, 'delta' would be used to calculate frame-rate independent updates.
  // For this example, we'll just increment.
  animationProgress += 1; 

  // Simulate some DOM read operation (e.g., getBoundingClientRect)
  const elementWidth = document.body?.clientWidth || 0; 
  console.log(`[Frame ${timestamp.toFixed(2)}] Delta: ${delta.toFixed(2)}ms, Progress: ${animationProgress}, Width: ${elementWidth}`);

  if (animationProgress >= targetProgress) {
    cancelSync.update(updateFunction);
    console.log('Animation complete!');
  }
};

sync.update(updateFunction, true); // Schedule to run indefinitely on the update step

// Simulate an immediate render call for some initial setup
sync.render(() => {
  // This would typically update DOM properties
  // For example: document.body.style.transform = `translateX(${animationProgress}px)`;
  console.log('Initial render step executed immediately.');
}, false, true);