@flighthq/easing 0.1.0

package/src/easePiecewise.test.ts

@@ -0,0 +1,58 @@
+import { easeInCubic } from './easeCubic';
+import { easeLinear } from './easeLinear';
+import { easePiecewise } from './easePiecewise';
+
+describe('easePiecewise', () => {
+  it('throws on an empty segments array', () => {
+    expect(() => easePiecewise([])).toThrow();
+  });
+  it('throws when total weight is zero', () => {
+    expect(() => easePiecewise([{ ease: easeLinear, weight: 0 }])).toThrow();
+  });
+  it('single segment is equivalent to the wrapped function', () => {
+    const fn = easePiecewise([{ ease: easeInCubic }]);
+    expect(fn(0)).toBeCloseTo(easeInCubic(0));
+    expect(fn(0.5)).toBeCloseTo(easeInCubic(0.5));
+    expect(fn(1)).toBeCloseTo(easeInCubic(1));
+  });
+  it('two equal-weight segments split the range at t=0.5', () => {
+    // First half uses easeLinear (identity), second half uses constant 0.
+    const fn = easePiecewise([{ ease: easeLinear }, { ease: () => 0 }]);
+    // At t=0.25 → in first segment, local t=0.5, easeLinear(0.5) = 0.5
+    expect(fn(0.25)).toBeCloseTo(0.5);
+    // At t=0.75 → in second segment, localT = 0.5, constant 0
+    expect(fn(0.75)).toBeCloseTo(0);
+  });
+  it('respects weights: a segment with weight=2 gets twice the range', () => {
+    // Segment 0: weight=1, range [0, 1/3]
+    // Segment 1: weight=2, range [1/3, 1]
+    const fn = easePiecewise([
+      { ease: easeLinear, weight: 1 },
+      { ease: () => 1, weight: 2 },
+    ]);
+    // t=1/6 is midpoint of segment 0 → easeLinear(0.5) = 0.5
+    expect(fn(1 / 6)).toBeCloseTo(0.5);
+    // t=2/3 is midpoint of segment 1 → constant 1
+    expect(fn(2 / 3)).toBeCloseTo(1);
+  });
+  it('returns 0 at t=0 and uses the last segment at t=1', () => {
+    const fn = easePiecewise([{ ease: easeLinear }, { ease: easeInCubic }]);
+    expect(fn(0)).toBeCloseTo(0);
+    expect(fn(1)).toBeCloseTo(1);
+  });
+  it('is boundary-safe for t=0 and t=1', () => {
+    const fn = easePiecewise([{ ease: easeInCubic }, { ease: easeLinear }]);
+    expect(fn(0)).toBeCloseTo(0);
+    expect(fn(1)).toBeCloseTo(1);
+  });
+  it('default weight (undefined) is treated as 1', () => {
+    const explicit = easePiecewise([
+      { ease: easeLinear, weight: 1 },
+      { ease: easeInCubic, weight: 1 },
+    ]);
+    const implicit = easePiecewise([{ ease: easeLinear }, { ease: easeInCubic }]);
+    for (let i = 0; i <= 10; i++) {
+      expect(implicit(i / 10)).toBeCloseTo(explicit(i / 10), 10);
+    }
+  });
+});

package/src/easePower.test.ts

@@ -0,0 +1,82 @@
+import { easeInOutCubic } from './easeCubic';
+import { easeInOutPower, easeInPower, easeOutPower } from './easePower';
+import { easeInQuadratic, easeOutQuadratic } from './easeQuadratic';
+import { easeInQuintic } from './easeQuintic';
+
+describe('easeInOutPower', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    const fn = easeInOutPower(3);
+    expect(fn(0)).toBeCloseTo(0);
+    expect(fn(1)).toBeCloseTo(1);
+  });
+  it('passes through 0.5 at t=0.5', () => {
+    const fn = easeInOutPower(3);
+    expect(fn(0.5)).toBeCloseTo(0.5);
+  });
+  it('matches easeInOutCubic at exponent=3', () => {
+    const fn = easeInOutPower(3);
+    expect(fn(0.3)).toBeCloseTo(easeInOutCubic(0.3), 10);
+    expect(fn(0.7)).toBeCloseTo(easeInOutCubic(0.7), 10);
+  });
+  it('is symmetric: f(t) + f(1-t) = 1', () => {
+    const fn = easeInOutPower(4);
+    expect(fn(0.3) + fn(0.7)).toBeCloseTo(1);
+    expect(fn(0.1) + fn(0.9)).toBeCloseTo(1);
+  });
+});
+
+describe('easeInPower', () => {
+  it('returns 0 at t=0 and 1 at t=1 for any exponent', () => {
+    for (const exp of [0.5, 1, 2, 3, 5]) {
+      const fn = easeInPower(exp);
+      expect(fn(0)).toBeCloseTo(0);
+      expect(fn(1)).toBeCloseTo(1);
+    }
+  });
+  it('matches easeInQuadratic at exponent=2', () => {
+    const fn = easeInPower(2);
+    expect(fn(0.5)).toBeCloseTo(easeInQuadratic(0.5), 10);
+    expect(fn(0.3)).toBeCloseTo(easeInQuadratic(0.3), 10);
+  });
+  it('matches easeInQuintic at exponent=5', () => {
+    const fn = easeInPower(5);
+    expect(fn(0.5)).toBeCloseTo(easeInQuintic(0.5), 10);
+    expect(fn(0.7)).toBeCloseTo(easeInQuintic(0.7), 10);
+  });
+  it('sub-linear at exponent < 1', () => {
+    const fn = easeInPower(0.5);
+    // sqrt(0.25) = 0.5, so output should be 0.5 at t=0.25
+    expect(fn(0.25)).toBeCloseTo(0.5, 10);
+  });
+  it('is monotonically increasing', () => {
+    const fn = easeInPower(2.5);
+    let prev = fn(0);
+    for (let i = 1; i <= 20; i++) {
+      const v = fn(i / 20);
+      expect(v).toBeGreaterThan(prev);
+      prev = v;
+    }
+  });
+});
+
+describe('easeOutPower', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    const fn = easeOutPower(2);
+    expect(fn(0)).toBeCloseTo(0);
+    expect(fn(1)).toBeCloseTo(1);
+  });
+  it('matches easeOutQuadratic at exponent=2', () => {
+    const fn = easeOutPower(2);
+    expect(fn(0.5)).toBeCloseTo(easeOutQuadratic(0.5), 10);
+    expect(fn(0.8)).toBeCloseTo(easeOutQuadratic(0.8), 10);
+  });
+  it('is monotonically increasing', () => {
+    const fn = easeOutPower(3);
+    let prev = fn(0);
+    for (let i = 1; i <= 20; i++) {
+      const v = fn(i / 20);
+      expect(v).toBeGreaterThan(prev);
+      prev = v;
+    }
+  });
+});

package/src/easeQuadratic.test.ts

@@ -0,0 +1,34 @@
+import { easeInOutQuadratic, easeInQuadratic, easeOutQuadratic } from './easeQuadratic';
+
+describe('easeInOutQuadratic', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeInOutQuadratic(0)).toBe(0);
+    expect(easeInOutQuadratic(1)).toBe(1);
+  });
+
+  it('is symmetric at midpoint', () => {
+    expect(easeInOutQuadratic(0.5)).toBeCloseTo(0.5);
+  });
+});
+
+describe('easeInQuadratic', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeInQuadratic(0)).toBe(0);
+    expect(easeInQuadratic(1)).toBe(1);
+  });
+
+  it('is slow at start (value below 0.5 at midpoint)', () => {
+    expect(easeInQuadratic(0.5)).toBeLessThan(0.5);
+  });
+});
+
+describe('easeOutQuadratic', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeOutQuadratic(0)).toBe(0);
+    expect(easeOutQuadratic(1)).toBe(1);
+  });
+
+  it('is fast at start (value above 0.5 at midpoint)', () => {
+    expect(easeOutQuadratic(0.5)).toBeGreaterThan(0.5);
+  });
+});

package/src/easeQuartic.test.ts

@@ -0,0 +1,34 @@
+import { easeInOutQuartic, easeInQuartic, easeOutQuartic } from './easeQuartic';
+
+describe('easeInOutQuartic', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeInOutQuartic(0)).toBe(0);
+    expect(easeInOutQuartic(1)).toBe(1);
+  });
+
+  it('is symmetric at midpoint', () => {
+    expect(easeInOutQuartic(0.5)).toBeCloseTo(0.5);
+  });
+});
+
+describe('easeInQuartic', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeInQuartic(0)).toBe(0);
+    expect(easeInQuartic(1)).toBe(1);
+  });
+
+  it('is slow at start (value below 0.5 at midpoint)', () => {
+    expect(easeInQuartic(0.5)).toBeLessThan(0.5);
+  });
+});
+
+describe('easeOutQuartic', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeOutQuartic(0)).toBe(0);
+    expect(easeOutQuartic(1)).toBe(1);
+  });
+
+  it('is fast at start (value above 0.5 at midpoint)', () => {
+    expect(easeOutQuartic(0.5)).toBeGreaterThan(0.5);
+  });
+});

package/src/easeQuintic.test.ts

@@ -0,0 +1,34 @@
+import { easeInOutQuintic, easeInQuintic, easeOutQuintic } from './easeQuintic';
+
+describe('easeInOutQuintic', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeInOutQuintic(0)).toBe(0);
+    expect(easeInOutQuintic(1)).toBe(1);
+  });
+
+  it('is symmetric at midpoint', () => {
+    expect(easeInOutQuintic(0.5)).toBeCloseTo(0.5);
+  });
+});
+
+describe('easeInQuintic', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeInQuintic(0)).toBe(0);
+    expect(easeInQuintic(1)).toBe(1);
+  });
+
+  it('is slow at start (value below 0.5 at midpoint)', () => {
+    expect(easeInQuintic(0.5)).toBeLessThan(0.5);
+  });
+});
+
+describe('easeOutQuintic', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeOutQuintic(0)).toBe(0);
+    expect(easeOutQuintic(1)).toBe(1);
+  });
+
+  it('is fast at start (value above 0.5 at midpoint)', () => {
+    expect(easeOutQuintic(0.5)).toBeGreaterThan(0.5);
+  });
+});

package/src/easeSine.test.ts

@@ -0,0 +1,34 @@
+import { easeInOutSine, easeInSine, easeOutSine } from './easeSine';
+
+describe('easeInOutSine', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeInOutSine(0)).toBeCloseTo(0);
+    expect(easeInOutSine(1)).toBeCloseTo(1);
+  });
+
+  it('is symmetric at midpoint', () => {
+    expect(easeInOutSine(0.5)).toBeCloseTo(0.5);
+  });
+});
+
+describe('easeInSine', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeInSine(0)).toBeCloseTo(0);
+    expect(easeInSine(1)).toBeCloseTo(1);
+  });
+
+  it('is slow at start (value below 0.5 at midpoint)', () => {
+    expect(easeInSine(0.5)).toBeLessThan(0.5);
+  });
+});
+
+describe('easeOutSine', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeOutSine(0)).toBeCloseTo(0);
+    expect(easeOutSine(1)).toBeCloseTo(1);
+  });
+
+  it('is fast at start (value above 0.5 at midpoint)', () => {
+    expect(easeOutSine(0.5)).toBeGreaterThan(0.5);
+  });
+});

package/src/easeSmoothstep.test.ts

@@ -0,0 +1,76 @@
+import { easeSmootherstep, easeSmoothstep, easeSmoothstepRange } from './easeSmoothstep';
+
+describe('easeSmootherstep', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeSmootherstep(0)).toBe(0);
+    expect(easeSmootherstep(1)).toBe(1);
+  });
+
+  it('is symmetric about the midpoint', () => {
+    expect(easeSmootherstep(0.5)).toBeCloseTo(0.5);
+  });
+
+  it('is monotonically increasing', () => {
+    let prev = easeSmootherstep(0);
+    for (let i = 1; i <= 20; i++) {
+      const value = easeSmootherstep(i / 20);
+      expect(value).toBeGreaterThanOrEqual(prev);
+      prev = value;
+    }
+  });
+
+  it('approaches endpoints more gently than smoothstep', () => {
+    // Higher-order flattening means a smaller value near the start.
+    expect(easeSmootherstep(0.25)).toBeLessThan(easeSmoothstep(0.25));
+  });
+});
+
+describe('easeSmoothstep', () => {
+  it('returns 0 at t=0 and 1 at t=1', () => {
+    expect(easeSmoothstep(0)).toBe(0);
+    expect(easeSmoothstep(1)).toBe(1);
+  });
+
+  it('is symmetric about the midpoint', () => {
+    expect(easeSmoothstep(0.5)).toBeCloseTo(0.5);
+  });
+
+  it('matches the known cubic value at t=0.25', () => {
+    expect(easeSmoothstep(0.25)).toBeCloseTo(0.15625);
+  });
+
+  it('is monotonically increasing', () => {
+    let prev = easeSmoothstep(0);
+    for (let i = 1; i <= 20; i++) {
+      const value = easeSmoothstep(i / 20);
+      expect(value).toBeGreaterThanOrEqual(prev);
+      prev = value;
+    }
+  });
+});
+
+describe('easeSmoothstepRange', () => {
+  it('returns 0 at edge0 and 1 at edge1', () => {
+    const fn = easeSmoothstepRange(10, 20);
+    expect(fn(10)).toBe(0);
+    expect(fn(20)).toBe(1);
+  });
+
+  it('clamps below edge0 to 0 and above edge1 to 1', () => {
+    const fn = easeSmoothstepRange(10, 20);
+    expect(fn(5)).toBe(0);
+    expect(fn(25)).toBe(1);
+  });
+
+  it('applies smoothstep at the midpoint', () => {
+    const fn = easeSmoothstepRange(0, 100);
+    expect(fn(50)).toBeCloseTo(0.5);
+  });
+
+  it('matches easeSmoothstep when range is [0, 1]', () => {
+    const fn = easeSmoothstepRange(0, 1);
+    for (const t of [0, 0.25, 0.5, 0.75, 1]) {
+      expect(fn(t)).toBeCloseTo(easeSmoothstep(t));
+    }
+  });
+});

package/src/easeSteps.test.ts

@@ -0,0 +1,65 @@
+import { easeSteps } from './easeSteps';
+
+describe('easeSteps', () => {
+  it('jumpEnd holds at 0 first and reaches 1 only at t=1', () => {
+    const ease = easeSteps(4, 'jumpEnd');
+    expect(ease(0)).toBe(0);
+    expect(ease(0.1)).toBe(0);
+    expect(ease(0.25)).toBeCloseTo(0.25);
+    expect(ease(0.6)).toBeCloseTo(0.5);
+    expect(ease(0.99)).toBeCloseTo(0.75);
+    expect(ease(1)).toBe(1);
+  });
+
+  it('jumpEnd is the default position', () => {
+    const explicit = easeSteps(4, 'jumpEnd');
+    const implicit = easeSteps(4);
+    for (let i = 0; i <= 10; i++) {
+      expect(implicit(i / 10)).toBe(explicit(i / 10));
+    }
+  });
+
+  it('jumpStart jumps immediately and reaches 1 before t=1', () => {
+    const ease = easeSteps(4, 'jumpStart');
+    expect(ease(0)).toBeCloseTo(0.25);
+    expect(ease(0.1)).toBeCloseTo(0.25);
+    expect(ease(0.5)).toBeCloseTo(0.75);
+    expect(ease(0.99)).toBe(1);
+    expect(ease(1)).toBe(1);
+  });
+
+  it('jumpNone spans the closed range 0..1 with count-1 jumps', () => {
+    const ease = easeSteps(4, 'jumpNone');
+    expect(ease(0)).toBe(0);
+    expect(ease(0.25)).toBeCloseTo(1 / 3);
+    expect(ease(0.5)).toBeCloseTo(2 / 3);
+    expect(ease(0.99)).toBe(1);
+    expect(ease(1)).toBe(1);
+  });
+
+  it('jumpNone with count=1 yields NaN, matching the CSS-forbidden steps(1, jump-none)', () => {
+    const ease = easeSteps(1, 'jumpNone');
+    expect(Number.isNaN(ease(0))).toBe(true);
+    expect(Number.isNaN(ease(0.5))).toBe(true);
+    expect(Number.isNaN(ease(1))).toBe(true);
+  });
+
+  it('jumpBoth never outputs 0 at the start, with interior 1/(n+1) steps', () => {
+    const ease = easeSteps(4, 'jumpBoth');
+    expect(ease(0)).toBeCloseTo(0.2);
+    expect(ease(0.1)).toBeCloseTo(0.2);
+    expect(ease(0.25)).toBeCloseTo(0.4);
+    expect(ease(0.99)).toBeCloseTo(0.8);
+    expect(ease(1)).toBe(1);
+  });
+
+  it('is monotonically non-decreasing for jumpEnd', () => {
+    const ease = easeSteps(5, 'jumpEnd');
+    let prev = ease(0);
+    for (let i = 1; i <= 50; i++) {
+      const value = ease(i / 50);
+      expect(value).toBeGreaterThanOrEqual(prev);
+      prev = value;
+    }
+  });
+});

package/src/getEasingDerivative.test.ts

@@ -0,0 +1,37 @@
+import { easeInCubic, easeOutCubic } from './easeCubic';
+import { easeLinear } from './easeLinear';
+import { getEasingDerivative } from './getEasingDerivative';
+
+describe('getEasingDerivative', () => {
+  it('returns ~1 everywhere for easeLinear (slope is constant 1)', () => {
+    for (const t of [0, 0.25, 0.5, 0.75, 1]) {
+      expect(getEasingDerivative(easeLinear, t)).toBeCloseTo(1, 4);
+    }
+  });
+  it('returns 0 at t=0 for easeInCubic (zero slope at start)', () => {
+    // easeInCubic = t^3, derivative = 3t^2 → 0 at t=0
+    expect(getEasingDerivative(easeInCubic, 0)).toBeCloseTo(0, 3);
+  });
+  it('returns 3 at t=1 for easeInCubic (derivative = 3t² = 3 at t=1)', () => {
+    expect(getEasingDerivative(easeInCubic, 1)).toBeCloseTo(3, 3);
+  });
+  it('returns 3 at t=0 for easeOutCubic (derivative = 3(1-t)² = 3 at t=0)', () => {
+    expect(getEasingDerivative(easeOutCubic, 0)).toBeCloseTo(3, 3);
+  });
+  it('returns 0 at t=1 for easeOutCubic (zero slope at end)', () => {
+    expect(getEasingDerivative(easeOutCubic, 1)).toBeCloseTo(0, 3);
+  });
+  it('uses centered difference at interior points', () => {
+    // At t=0.5, easeInCubic derivative = 3*(0.5)^2 = 0.75
+    expect(getEasingDerivative(easeInCubic, 0.5)).toBeCloseTo(0.75, 3);
+  });
+  it('accepts a custom epsilon', () => {
+    expect(getEasingDerivative(easeLinear, 0.5, 1e-4)).toBeCloseTo(1, 3);
+  });
+  it('handles the left boundary without throwing', () => {
+    expect(() => getEasingDerivative(easeInCubic, 0)).not.toThrow();
+  });
+  it('handles the right boundary without throwing', () => {
+    expect(() => getEasingDerivative(easeInCubic, 1)).not.toThrow();
+  });
+});