take-it-ease

Installation

# npm
npm install --save take-it-ease

# yarn
yarn add take-it-ease

# pnpm
pnpm add take-it-ease

Motivation

This library was created to address the limitations of tween.js, such as the silent merging of properties, lack of clear typing and mutating original values.

This library offers better TypeScript compatibility, customizable merging strategies, and improved typing for a more intuitive and reliable animation experience.

Usage

Simple example

import { createController } from "take-it-ease";

const controller = createController();

controller.animate({
  time: 1_000,
  from: { x: 20, y: -10 },
  to: { x: -10, y: 20 },
  include: ["x", "y"], // animation target 🎯
  onUpdate: (updatedObject) => {
    // updatedObject: { x: number; y: number }
  },
});

// prefferable way to call tick, but you can use anything else 😎
const animate = () => {
  controller.tick();

  requestAnimationFrame(animate);
};

requestAnimationFrame(animate);

More advanced example

import { createController, EasingFunctions, Strategies } from "take-it-ease";

const controller = createController();

controller.animate({
  time: 1_000,
  from: { name: "Bob", salary: 21_000 },
  to: { name: "Bob", salary: 37_000, bonus: 500 },
  include: ["salary", "bonus"],
  mergeStrategy: Strategies.MERGE_WITH_LAST_TICK,
  easingFunction: EasingFunctions.CUBIC_OUT,
  onUpdate: (updatedObject) => {
    // updatedObject before last tick: { name: "Bob"; salary: number }
    // last tick: { name: "Bob"; salary: 37_000, bonus: 500 }
  },
});

someApi.on("idle", controller.tick);

Animating arrays

import { createController, EasingFunctions, Strategies } from "take-it-ease";

const controller = createController();

controller.animateArray({
  time: 1_000,
  from: [
    { name: "Bob", salary: 21_000 },
    { name: "Alice", salary: 0 },
  ],
  to: [
    { name: "Bob", salary: 37_000, bonus: 500 },
    { name: "Mark", salary: 42_000 },
  ],
  keyExtractor: (item) => item.name,
  include: ["salary", "bonus"],
  mergeStrategy: Strategies.MERGE_WITH_FIRST_TICK,
  arrayMergeStrategy: Strategies.MERGE_WITH_FIRST_TICK,
  easingFunction: EasingFunctions.CUBIC_OUT,
  onUpdate: (updatedArray) => {
    /*
      updatedObject before last tick:
      [
        { name: "Bob", salary: number },
        { name: "Alice", salary: 0 },
      ]
    */
    /*
      last tick:
      [
        { name: "Bob", salary: 37_000, bonus: 500 },
        { name: "Alice", salary: 0 },
        { name: "Mark", salary: 42_000 },
      ]
    */
  },
});

Strategies

When using a library you can decide when to insert properties that haven't existed before.

Strategies is an object with following properties:

• MERGE_WITH_FIRST_TICK – applies non-existing properties from target with the first tick,
• MERGE_WITH_LAST_TICK – applies non-existing properties from target with the last tick

Strategies can be used to describe both:

• mergeStrategy,
• arrayMergeStrategy