@penner/fast-bezier-easing/README.md

A fast TypeScript implementation of cubic Bezier easing with analytical solutions, providing the same API as bezier-easing but with superior performance

# 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

```bash
npm install @penner/fast-bezier-easing
```

## Usage

### Basic Usage

```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
```

### Creating Common Easing Curves

```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
```

## 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

```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
```

## 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:

```bash
# 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`:

```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:

### 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](CONTRIBUTING.md) 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](LICENSE) file for details.

## Credits

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

- **[EasingCubicBezier](https://github.com/jurgus/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](https://www.npmjs.com/package/bezier-easing) - The original JavaScript implementation
- [EasingCubicBezier](https://github.com/jurgus/EasingCubicBezier) - C++ source implementation