@zakkster/lite-ease

🎢 What is lite-ease?

@zakkster/lite-ease is the complete set of Robert Penner easing equations as individual, tree-shakeable ES module exports — plus a small, zero-allocation composition layer.

It gives you:

• 🎢 30 easing functions (10 families × 3 variants)
• 🧮 Pure math: (t: number) => number where t ∈ [0, 1]
• 🔗 Composable: lerp(a, b, easeOutBounce(t))
• 🛡️ clamp01() wrapper for Back/Elastic overshoot
• 🔄 reverse(ease) creates the inverse curve
• 🎼 v1.1: mirror, chain, blend, scale — zero-GC composition factories
• 📖 easings lookup map for string-based access
• 0️⃣ Zero dependencies, pure math, no allocation in hot path
• 🪶 < 1 KB minified (entire library)

Part of the @zakkster/lite-* ecosystem — micro-libraries built for deterministic, cache-friendly game development.

🚀 Install

npm i @zakkster/lite-ease

🕹️ Quick Start

import { easeOutBounce, easeInOutElastic, clamp01, reverse } from '@zakkster/lite-ease';
import { lerp } from '@zakkster/lite-lerp';

// Compose with any interpolation
const y = lerp(startY, endY, easeOutBounce(t));

// Clamp overshoot (Back/Elastic can exceed 1.0)
const safe = lerp(0, 255, clamp01(easeOutBack(t)));

// Create inverse curve
const myEaseOut = reverse(easeInCubic);

// String-based lookup (useful for configs/JSON)
import { easings } from '@zakkster/lite-ease';
const ease = easings[config.easing]; // 'easeOutBounce' → function

📊 Comparison

Library	Size	Functions	Format	Install
bezier-easing	~3 KB	Custom curves	Class	npm i bezier-easing
eases	~2 KB	31	CommonJS	npm i eases
lite-ease	< 1 KB	31 + composition	ESM, tree-shakeable	npm i @zakkster/lite-ease

⚙️ API

10 Families × 3 Variants

Family	easeIn	easeOut	easeInOut
Sine	easeInSine	easeOutSine	easeInOutSine
Quad	easeInQuad	easeOutQuad	easeInOutQuad
Cubic	easeInCubic	easeOutCubic	easeInOutCubic
Quart	easeInQuart	easeOutQuart	easeInOutQuart
Quint	easeInQuint	easeOutQuint	easeInOutQuint
Expo	easeInExpo	easeOutExpo	easeInOutExpo
Circ	easeInCirc	easeOutCirc	easeInOutCirc
Back	easeInBack	easeOutBack	easeInOutBack
Elastic	easeInElastic	easeOutElastic	easeInOutElastic
Bounce	easeInBounce	easeOutBounce	easeInOutBounce

Helpers

• linear(t) — Identity function
• clamp01(t) — Clamp to [0, 1]. Back/Elastic overshoot safely.
• reverse(ease) — Create the inverse: reverse(easeIn) ≈ easeOut
• easings — Record<string, EasingFunction> for dynamic lookup

🎼 Composition Helpers (v1.1)

Each helper is a factory: it pre-computes any constants and returns a closure that does zero allocation per call. The returned function is what you call in your hot path.

⚠️ Build once, call many. Don't put mirror(...), chain(...), blend(...), or scale(...) inside your requestAnimationFrame loop — that allocates a fresh closure every frame and defeats the design. Build the composed easing in init/module scope, then call the returned function each frame.

mirror(ease, clamp?)

Plays the curve forward in the first half, then backward — a seamless ping-pong (0 → 1 → 0).

import { mirror, easeInOutQuad } from '@zakkster/lite-ease';

const pingPong = mirror(easeInOutQuad);
// pingPong(0)   === 0
// pingPong(0.5) ≈ 1
// pingPong(1)   === 0

clamp: true clamps each half to [0, 1] — useful when wrapping easeOutBack or easeOutElastic to suppress overshoot.

chain(easeA, easeB, clamp?)

Sequential chain: easeA drives t ∈ [0, 0.5], easeB drives t ∈ [0.5, 1].

import { chain, easeInQuad, easeOutBounce } from '@zakkster/lite-ease';

const windAndDrop = chain(easeInQuad, easeOutBounce);
// First half: smooth wind-up. Second half: bounce settle.

clamp: true is recommended when either curve overshoots — clamps each half to its [0, 0.5] / [0.5, 1] range so overshoot can't bleed across the midpoint.

blend(easeA, easeB, weight)

Linear crossfade between two curves. weight is clamped to [0, 1] once at init and stored — no per-call clamp cost.

import { blend, linear, easeOutElastic } from '@zakkster/lite-ease';

const subtleElastic = blend(linear, easeOutElastic, 0.3);
// 70% linear + 30% elastic — keeps the bounce flavor without the full overshoot.

scale(ease, fromT, toT, clamp?)

Remaps an easing to a sub-segment of the timeline. Outside the segment, output is locked to the boundary value (pre-computed at init). Throws if toT <= fromT.

import { scale, easeOutBounce } from '@zakkster/lite-ease';

const dropAt40Percent = scale(easeOutBounce, 0.4, 0.9);
// dropAt40Percent(t)  →  0  for t <= 0.4
// dropAt40Percent(t)  →  1  for t >= 0.9
// drops/bounces between 0.4 and 0.9 of the master timeline

Ideal for staggered animation sequences where multiple elements share a master t and each starts/ends at a different point.

🧪 Benchmark

31 easing functions, 1M calls each:
  All functions: < 0.01ms per call (pure arithmetic)
  No allocation, no branching (except Bounce/Elastic)
  Tree-shakeable: unused functions are eliminated by bundlers

Composition helpers (mirror/chain/blend/scale):
  Factory cost paid once at init.
  Returned closure: zero allocation per call, one inner ease() invocation.

📦 TypeScript

Full declarations included in LiteEase.d.ts. The EasingFunction type alias is exported for your own composed easings.

📚 LLM-Friendly Documentation

See llms.txt for AI-optimized metadata and usage examples.

License

MIT