fast-bezier-easing

A high-performance TypeScript implementation of cubic Bezier easing curves with analytical solutions. Provides the same API as the popular bezier-easing NPM package but with superior performance through mathematical optimization.

Features

• 🚀 Fast Performance: Uses analytical solutions instead of iterative methods
• 🔄 Drop-in Replacement: Compatible with bezier-easing API
• 📐 Accurate Results: Maintains mathematical precision
• 🎯 TypeScript Native: Written in TypeScript with full type support
• 📦 Zero Dependencies: No external runtime dependencies
• 🧪 Well Tested: Comprehensive test suite with performance benchmarks

Installation

npm install @penner/fast-bezier-easing

Usage

Basic Usage

import bezierEasing from '@penner/fast-bezier-easing';

// Create an easing function with control points
const easing = bezierEasing(0.25, 0.1, 0.25, 1.0);

// Use the easing function
console.log(easing(0)); // 0
console.log(easing(0.5)); // ~0.5
console.log(easing(1)); // 1

Creating Common Easing Curves

import bezierEasing from '@penner/fast-bezier-easing';

// CSS equivalent curves
const ease = bezierEasing(0.25, 0.1, 0.25, 1.0); // ease
const easeIn = bezierEasing(0.42, 0, 1, 1); // ease-in
const easeOut = bezierEasing(0, 0, 0.58, 1); // ease-out
const easeInOut = bezierEasing(0.42, 0, 0.58, 1); // ease-in-out

API

bezierEasing(x1, y1, x2, y2)

Creates a cubic Bezier easing function.

Parameters:

• x1 (number): First control point X coordinate (must be in [0, 1])
• y1 (number): First control point Y coordinate (can be outside [0, 1])
• x2 (number): Second control point X coordinate (must be in [0, 1])
• y2 (number): Second control point Y coordinate (can be outside [0, 1])

Returns:

• Function that takes a time value t (0 to 1) and returns the interpolated value

Type Definitions

export type EasingFunction = (t: number) => number;
export default function bezierEasing(
  x1: number,
  y1: number,
  x2: number,
  y2: number,
): EasingFunction;
export { bezierEasing }; // Named export for compatibility

Performance

This library is designed for high-performance applications where easing functions are called frequently. It uses analytical solutions to the cubic Bezier equation rather than iterative numerical methods.

Benchmarks

Performance benchmarks can be run from the source repository:

# Clone the repository and install dependencies
git clone https://github.com/robertpenner/penner.git
cd penner/packages/fast-bezier-easing
npm install

# Run professional benchmarks using Benchmark.js
npm run benchmark

# Run simple performance demo
npm run demo

Typical performance improvements over bezier-easing:

• 2-5x faster for standard easing curves
• Consistent performance across different curve shapes
• Lower memory usage due to optimized algorithm

Migration from bezier-easing

This library is designed as a drop-in replacement for bezier-easing:

// Before
import BezierEasing from 'bezier-easing';
const easing = BezierEasing(0.25, 0.1, 0.25, 1);

// After
import bezierEasing from '@penner/fast-bezier-easing';
const easing = bezierEasing(0.25, 0.1, 0.25, 1);

Algorithm

This implementation uses analytical solutions for cubic Bezier curve evaluation, based on Łukasz Izdebski's approach from EasingCubicBezier. The algorithm classifies curves into different mathematical types and applies the most efficient analytical method for each:

Curve Classification

The algorithm pre-analyzes the cubic Bezier curve and classifies it into one of six mathematical cases:

1. Linear (P3): When higher-order coefficients are zero
2. Quadratic (X2): When the cubic coefficient is zero
3. Cubic with zero discriminant (X3P0): Special cubic case
4. Trigonometric (X3COS): Uses cosine-based solutions
5. Hyperbolic sine (X3SINH): Uses hyperbolic sine solutions
6. Hyperbolic cosine (X3COSH): Uses hyperbolic cosine solutions

Key Optimizations

• Pre-computed coefficients: All curve parameters are calculated once during function creation
• Type-specific evaluation: Each curve type uses its optimal mathematical solution
• Fast transcendental functions: Custom implementations of sinh, cosh, acos, etc., optimized for common CSS easing ranges
• Polynomial pre-transformation: Converts Bezier control points to polynomial coefficients upfront
• Branch-free evaluation: Minimal conditional logic during evaluation

Contributing

We welcome contributions! Please see our Contributing Guide for detailed instructions on:

• Setting up the development environment
• Running tests and benchmarks
• Code style guidelines
• Performance considerations
• Pull request process

Quick start for contributors:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT License - see the LICENSE file for details.

Credits

This implementation is based on the analytical cubic Bézier algorithm from:

• EasingCubicBezier by Łukasz Izdebski (MIT License)

Additional acknowledgments:

• API Design: Compatible with François Romain's bezier-easing package
• TypeScript Port: Robert Penner

Related Projects

• bezier-easing - The original JavaScript implementation
• EasingCubicBezier - C++ source implementation