A fast TypeScript implementation of cubic Bezier easing with analytical solutions, providing the same API as bezier-easing but with superior performance
npm install @penner/fast-bezier-easingA 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.
- 🚀 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
``bash`
npm install @penner/fast-bezier-easing
`typescript
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
`
`typescript
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
`
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
`typescript`
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
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.
Performance benchmarks can be run from the source repository:
`bashClone the repository and install dependencies
git clone https://github.com/robertpenner/penner.git
cd penner/packages/fast-bezier-easing
npm install
Typical performance improvements over
:- 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:`typescript
// 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:
$3
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
$3
- 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
, 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 evaluationContributing
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 RequestLicense
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- bezier-easing - The original JavaScript implementation
- EasingCubicBezier - C++ source implementation