npm package: @penner/classic-easing
Description: Classic Penner easing equations with normalized (0-1) signatures
Author: Robert Penner
Latest version: 0.0.3

# @penner/classic-easing

The classic Penner easing equations, ported to TypeScript with normalized `(t: number) => number` signatures.

This is a faithful port of the original ActionScript functions from 2001: the same math and the same names, with a modern API.

## Installation

```bash
npm install @penner/classic-easing
```

## Usage

Every easing function takes a normalized time `t` in [0, 1] and returns a value typically in [0, 1]:

```ts
import {
  easeOutQuad,
  easeInOutCubic,
  easeOutBounce,
} from '@penner/classic-easing';

const progress = easeOutQuad(0.5); // 0.75
const smooth = easeInOutCubic(0.5); // 0.5
const bounced = easeOutBounce(0.8); // ~0.95
```

Use with any animation system that accepts `(t: number) => number`:

```ts
import { easeOutElastic } from '@penner/classic-easing';

element.animate(keyframes, {
  duration: 1000,
  easing: `linear`, // use Web Animations API timing
});

// Or apply the easing manually to a 0-1 progress value
const easedProgress = easeOutElastic(t);
```

## Easing Functions

### Simple Eases

All simple easing functions are exported as ready-to-use `(t: number) => number`:

| Family | In             | Out             | InOut             |
| ------ | -------------- | --------------- | ----------------- |
| Quad   | `easeInQuad`   | `easeOutQuad`   | `easeInOutQuad`   |
| Cubic  | `easeInCubic`  | `easeOutCubic`  | `easeInOutCubic`  |
| Quart  | `easeInQuart`  | `easeOutQuart`  | `easeInOutQuart`  |
| Quint  | `easeInQuint`  | `easeOutQuint`  | `easeInOutQuint`  |
| Sine   | `easeInSine`   | `easeOutSine`   | `easeInOutSine`   |
| Expo   | `easeInExpo`   | `easeOutExpo`   | `easeInOutExpo`   |
| Circ   | `easeInCirc`   | `easeOutCirc`   | `easeInOutCirc`   |
| Bounce | `easeInBounce` | `easeOutBounce` | `easeInOutBounce` |

Plus `linear` — the identity function.

### Back Easing (with overshoot)

Default exports use the classic overshoot strength of 1.70158 (~10% overshoot):

```ts
import { easeInBack, easeOutBack, easeInOutBack } from '@penner/classic-easing';
```

Use factory functions to customize the overshoot strength:

```ts
import {
  createEaseInBack,
  createEaseOutBack,
  createEaseInOutBack,
} from '@penner/classic-easing';

const gentleBack = createEaseOutBack({ strength: 1 });
const aggressiveBack = createEaseOutBack({ strength: 3 });
const cubicNoOvershoot = createEaseInBack({ strength: 0 }); // equivalent to cubic
```

### Elastic Easing (with oscillation)

Default exports use amplitude 1 and period 0.3 (0.45 for InOut):

```ts
import {
  easeInElastic,
  easeOutElastic,
  easeInOutElastic,
} from '@penner/classic-easing';
```

Use factory functions to customize amplitude and period:

```ts
import {
  createEaseOutElastic,
  createEaseInOutElastic,
} from '@penner/classic-easing';

const bouncy = createEaseOutElastic({ amplitude: 1.5, period: 0.2 });
const gentle = createEaseOutElastic({ period: 0.5 });
const inOut = createEaseInOutElastic({ amplitude: 1.2, period: 0.6 });
```

## Types

```ts
import type {
  EasingFn,
  BackConfig,
  ElasticConfig,
} from '@penner/classic-easing';
```

- **`EasingFn`** — `(t: number) => number`
- **`BackConfig`** — `{ strength?: number }`
- **`ElasticConfig`** — `{ amplitude?: number; period?: number }`

## Comparison with @penner/easing

- This package preserves the original 2001 equations and classic naming conventions (`easeInQuad`, `easeOutBounce`).
- The sibling `@penner/easing` package reimagines the same easing families with physics-based parameters — configuring bounce by number of bounces and restitution, elastic by cycles and decay, and so on.
- Use `classic-easing` when you want the exact original formulas with a modern signature.
- Use `@penner/easing` when you want more intuitive, physically meaningful configuration.

## License

MIT