@flighthq/math 0.1.0

package/src/randomRange.test.ts

@@ -0,0 +1,99 @@
+import { createRandomSource } from './random';
+import { randomBool, randomInt, randomRange, randomSign } from './randomRange';
+
+const rng = () => createRandomSource(0xabcdef);
+
+describe('randomBool', () => {
+  it('returns only booleans', () => {
+    const random = rng();
+    for (let i = 0; i < 100; i++) {
+      const v = randomBool(random);
+      expect(typeof v).toBe('boolean');
+    }
+  });
+  it('returns true with probability 1', () => {
+    const random = rng();
+    for (let i = 0; i < 10; i++) expect(randomBool(random, 1)).toBe(true);
+  });
+  it('returns false with probability 0', () => {
+    const random = rng();
+    for (let i = 0; i < 10; i++) expect(randomBool(random, 0)).toBe(false);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    for (let i = 0; i < 20; i++) expect(randomBool(a)).toBe(randomBool(b));
+  });
+});
+
+describe('randomInt', () => {
+  it('returns integers within [min, max]', () => {
+    const random = rng();
+    for (let i = 0; i < 200; i++) {
+      const v = randomInt(random, 0, 9);
+      expect(Number.isInteger(v)).toBe(true);
+      expect(v).toBeGreaterThanOrEqual(0);
+      expect(v).toBeLessThanOrEqual(9);
+    }
+  });
+  it('returns min when min equals max', () => {
+    const random = rng();
+    expect(randomInt(random, 5, 5)).toBe(5);
+  });
+  it('throws when min > max', () => {
+    const random = rng();
+    expect(() => randomInt(random, 10, 5)).toThrow(RangeError);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    for (let i = 0; i < 20; i++) expect(randomInt(a, 0, 100)).toBe(randomInt(b, 0, 100));
+  });
+});
+
+describe('randomRange', () => {
+  it('returns values within [min, max)', () => {
+    const random = rng();
+    for (let i = 0; i < 200; i++) {
+      const v = randomRange(random, 5, 10);
+      expect(v).toBeGreaterThanOrEqual(5);
+      expect(v).toBeLessThan(10);
+    }
+  });
+  it('returns min when min equals max', () => {
+    const random = rng();
+    expect(randomRange(random, 3, 3)).toBe(3);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    for (let i = 0; i < 20; i++) expect(randomRange(a, 0, 100)).toBe(randomRange(b, 0, 100));
+  });
+});
+
+describe('randomSign', () => {
+  it('returns only 1 or -1', () => {
+    const random = rng();
+    for (let i = 0; i < 100; i++) {
+      const v = randomSign(random);
+      expect(v === 1 || v === -1).toBe(true);
+    }
+  });
+  it('produces both signs', () => {
+    const random = rng();
+    let sawPositive = false;
+    let sawNegative = false;
+    for (let i = 0; i < 100; i++) {
+      const v = randomSign(random);
+      if (v === 1) sawPositive = true;
+      if (v === -1) sawNegative = true;
+    }
+    expect(sawPositive).toBe(true);
+    expect(sawNegative).toBe(true);
+  });
+  it('is deterministic for the same seed', () => {
+    const a = rng();
+    const b = rng();
+    for (let i = 0; i < 20; i++) expect(randomSign(a)).toBe(randomSign(b));
+  });
+});

package/src/rounding.test.ts

@@ -0,0 +1,81 @@
+import { ceilTo, euclideanMod, floorTo, fract, roundTo } from './rounding';
+
+describe('ceilTo', () => {
+  it('rounds up to the nearest step', () => {
+    expect(ceilTo(7, 5)).toBe(10);
+  });
+  it('leaves an exact multiple unchanged', () => {
+    expect(ceilTo(10, 5)).toBe(10);
+  });
+  it('returns value when step is 0', () => {
+    expect(ceilTo(7, 0)).toBe(7);
+  });
+  it('works with negative values', () => {
+    expect(ceilTo(-7, 5)).toBe(-5);
+  });
+});
+
+describe('euclideanMod', () => {
+  it('returns the remainder for positive inputs', () => {
+    expect(euclideanMod(7, 4)).toBe(3);
+  });
+  it('returns a non-negative result for negative inputs', () => {
+    expect(euclideanMod(-1, 4)).toBe(3);
+    expect(euclideanMod(-5, 4)).toBe(3);
+  });
+  it('returns 0 when value is a multiple of divisor', () => {
+    expect(euclideanMod(8, 4)).toBe(0);
+  });
+  it('throws for a zero divisor', () => {
+    expect(() => euclideanMod(7, 0)).toThrow(RangeError);
+  });
+});
+
+describe('floorTo', () => {
+  it('rounds down to the nearest step', () => {
+    expect(floorTo(7, 5)).toBe(5);
+  });
+  it('leaves an exact multiple unchanged', () => {
+    expect(floorTo(10, 5)).toBe(10);
+  });
+  it('returns value when step is 0', () => {
+    expect(floorTo(7, 0)).toBe(7);
+  });
+  it('works with negative values', () => {
+    expect(floorTo(-7, 5)).toBe(-10);
+  });
+});
+
+describe('fract', () => {
+  it('returns the fractional part of a positive number', () => {
+    expect(fract(3.75)).toBeCloseTo(0.75, 10);
+  });
+  it('returns 0 for an integer', () => {
+    expect(fract(3)).toBe(0);
+  });
+  it('preserves sign for negative numbers', () => {
+    expect(fract(-1.3)).toBeCloseTo(-0.3, 10);
+  });
+  it('returns 0 for 0', () => {
+    expect(fract(0)).toBe(0);
+  });
+});
+
+describe('roundTo', () => {
+  it('rounds to the nearest step', () => {
+    expect(roundTo(7, 5)).toBe(5);
+    expect(roundTo(8, 5)).toBe(10);
+  });
+  it('leaves an exact multiple unchanged', () => {
+    expect(roundTo(10, 5)).toBe(10);
+  });
+  it('returns value when step is 0', () => {
+    expect(roundTo(7, 0)).toBe(7);
+  });
+  it('works with floating-point steps', () => {
+    expect(roundTo(0.3, 0.1)).toBeCloseTo(0.3, 10);
+  });
+  it('works with negative values', () => {
+    expect(roundTo(-7, 5)).toBe(-5);
+  });
+});

package/src/scalar.test.ts

@@ -0,0 +1,58 @@
+import { ceilPowerOfTwo, floorPowerOfTwo, quantize, sign } from './scalar';
+
+describe('ceilPowerOfTwo', () => {
+  it('rounds up to the next power of two', () => {
+    expect(ceilPowerOfTwo(5)).toBe(8);
+    expect(ceilPowerOfTwo(9)).toBe(16);
+  });
+  it('leaves an exact power of two unchanged', () => {
+    expect(ceilPowerOfTwo(8)).toBe(8);
+    expect(ceilPowerOfTwo(256)).toBe(256);
+  });
+});
+
+describe('floorPowerOfTwo', () => {
+  it('rounds down to the previous power of two', () => {
+    expect(floorPowerOfTwo(6)).toBe(4);
+    expect(floorPowerOfTwo(100)).toBe(64);
+  });
+  it('leaves an exact power of two unchanged', () => {
+    expect(floorPowerOfTwo(8)).toBe(8);
+  });
+});
+
+describe('quantize', () => {
+  it('quantizes to the nearest step', () => {
+    expect(quantize(0.7, 4, 0, 1)).toBeCloseTo(0.75, 10);
+  });
+  it('returns min at the lower bound', () => {
+    expect(quantize(0, 4, 0, 1)).toBeCloseTo(0, 10);
+  });
+  it('returns max at the upper bound', () => {
+    expect(quantize(1, 4, 0, 1)).toBeCloseTo(1, 10);
+  });
+  it('returns min when steps is 0', () => {
+    expect(quantize(0.5, 0, 0, 1)).toBe(0);
+  });
+  it('returns min when min equals max', () => {
+    expect(quantize(5, 4, 5, 5)).toBe(5);
+  });
+  it('clamps values outside the range', () => {
+    expect(quantize(-1, 4, 0, 1)).toBeCloseTo(0, 10);
+    expect(quantize(2, 4, 0, 1)).toBeCloseTo(1, 10);
+  });
+});
+
+describe('sign', () => {
+  it('returns 1 for positive values', () => {
+    expect(sign(5)).toBe(1);
+    expect(sign(0.001)).toBe(1);
+  });
+  it('returns -1 for negative values', () => {
+    expect(sign(-5)).toBe(-1);
+    expect(sign(-0.001)).toBe(-1);
+  });
+  it('returns 0 for zero', () => {
+    expect(sign(0)).toBe(0);
+  });
+});

package/src/statistics.test.ts

@@ -0,0 +1,74 @@
+import { mean, median, standardDeviation, variance, weightedAverage } from './statistics';
+
+describe('mean', () => {
+  it('returns the arithmetic mean', () => {
+    expect(mean([1, 2, 3, 4, 5])).toBe(3);
+  });
+  it('returns the single element for a one-element array', () => {
+    expect(mean([42])).toBe(42);
+  });
+  it('returns NaN for an empty array', () => {
+    expect(mean([])).toBeNaN();
+  });
+  it('handles negative values', () => {
+    expect(mean([-2, 0, 2])).toBe(0);
+  });
+});
+
+describe('median', () => {
+  it('returns the middle value for an odd-length array', () => {
+    expect(median([3, 1, 2])).toBe(2);
+  });
+  it('returns the average of the two middle values for an even-length array', () => {
+    expect(median([1, 2, 3, 4])).toBe(2.5);
+  });
+  it('returns NaN for an empty array', () => {
+    expect(median([])).toBeNaN();
+  });
+  it('does not mutate the input', () => {
+    const values = [5, 3, 1, 4, 2];
+    const original = values.slice();
+    median(values);
+    expect(values).toEqual(original);
+  });
+});
+
+describe('standardDeviation', () => {
+  it('returns 0 for a single-element array', () => {
+    expect(standardDeviation([5])).toBe(0);
+  });
+  it('returns NaN for an empty array', () => {
+    expect(standardDeviation([])).toBeNaN();
+  });
+  it('computes the population standard deviation', () => {
+    expect(standardDeviation([2, 4, 4, 4, 5, 5, 7, 9])).toBeCloseTo(2, 5);
+  });
+});
+
+describe('variance', () => {
+  it('returns 0 for a single-element array', () => {
+    expect(variance([5])).toBe(0);
+  });
+  it('returns NaN for an empty array', () => {
+    expect(variance([])).toBeNaN();
+  });
+  it('computes the population variance', () => {
+    expect(variance([2, 4, 4, 4, 5, 5, 7, 9])).toBeCloseTo(4, 5);
+  });
+});
+
+describe('weightedAverage', () => {
+  it('returns the weighted average', () => {
+    expect(weightedAverage([1, 2, 3], [1, 1, 1])).toBeCloseTo(2, 10);
+    expect(weightedAverage([0, 10], [1, 3])).toBeCloseTo(7.5, 10);
+  });
+  it('returns NaN for an empty array', () => {
+    expect(weightedAverage([], [])).toBeNaN();
+  });
+  it('returns NaN when all weights are 0', () => {
+    expect(weightedAverage([1, 2, 3], [0, 0, 0])).toBeNaN();
+  });
+  it('throws when arrays have different lengths', () => {
+    expect(() => weightedAverage([1, 2], [1])).toThrow(RangeError);
+  });
+});