@holoscript/std 2.1.0 → 3.1.1

package/src/__tests__/collections.test.ts

@@ -0,0 +1,182 @@
+import { describe, it, expect } from 'vitest';
+import { List } from '../collections.js';
+
+describe('List', () => {
+  describe('construction', () => {
+    it('should create empty list', () => {
+      const list = new List<number>();
+      expect(list.length).toBe(0);
+      expect(list.isEmpty).toBe(true);
+    });
+
+    it('should create from array', () => {
+      const list = new List([1, 2, 3]);
+      expect(list.length).toBe(3);
+    });
+
+    it('should create with List.of()', () => {
+      const list = List.of(1, 2, 3);
+      expect(list.length).toBe(3);
+    });
+
+    it('should create with List.from()', () => {
+      const list = List.from([1, 2, 3]);
+      expect(list.length).toBe(3);
+    });
+  });
+
+  describe('List.range()', () => {
+    it('should create range with positive step', () => {
+      const list = List.range(0, 5, 1);
+      expect(list.toArray()).toEqual([0, 1, 2, 3, 4]);
+    });
+
+    it('should create range with default step', () => {
+      const list = List.range(0, 3);
+      expect(list.toArray()).toEqual([0, 1, 2]);
+    });
+
+    it('should create range with custom step', () => {
+      const list = List.range(0, 10, 2);
+      expect(list.toArray()).toEqual([0, 2, 4, 6, 8]);
+    });
+
+    it('should create range with negative step', () => {
+      const list = List.range(5, 0, -1);
+      expect(list.toArray()).toEqual([5, 4, 3, 2, 1]);
+    });
+  });
+
+  describe('List.repeat()', () => {
+    it('should create list with repeated values', () => {
+      const list = List.repeat('a', 3);
+      expect(list.toArray()).toEqual(['a', 'a', 'a']);
+    });
+
+    it('should create empty list with count 0', () => {
+      const list = List.repeat('a', 0);
+      expect(list.isEmpty).toBe(true);
+    });
+  });
+
+  describe('accessors', () => {
+    const list = List.of(10, 20, 30, 40, 50);
+
+    it('should get element by positive index', () => {
+      expect(list.get(0)).toBe(10);
+      expect(list.get(2)).toBe(30);
+    });
+
+    it('should get element by negative index', () => {
+      expect(list.get(-1)).toBe(50);
+      expect(list.get(-2)).toBe(40);
+    });
+
+    it('should return undefined for out of bounds', () => {
+      expect(list.get(10)).toBeUndefined();
+    });
+
+    it('should get first element', () => {
+      expect(list.first()).toBe(10);
+    });
+
+    it('should get last element', () => {
+      expect(list.last()).toBe(50);
+    });
+
+    it('should return undefined for first/last on empty list', () => {
+      const empty = new List<number>();
+      expect(empty.first()).toBeUndefined();
+      expect(empty.last()).toBeUndefined();
+    });
+  });
+
+  describe('map', () => {
+    it('should map over elements', () => {
+      const list = List.of(1, 2, 3);
+      const doubled = list.map((x) => x * 2);
+      expect(doubled.toArray()).toEqual([2, 4, 6]);
+    });
+
+    it('should receive index in map callback', () => {
+      const list = List.of('a', 'b', 'c');
+      const indexed = list.map((_, i) => i);
+      expect(indexed.toArray()).toEqual([0, 1, 2]);
+    });
+
+    it('should return new List instance', () => {
+      const list = List.of(1, 2, 3);
+      const mapped = list.map((x) => x);
+      expect(mapped).not.toBe(list);
+    });
+  });
+
+  describe('filter', () => {
+    it('should filter elements', () => {
+      const list = List.of(1, 2, 3, 4, 5);
+      const evens = list.filter((x) => x % 2 === 0);
+      expect(evens.toArray()).toEqual([2, 4]);
+    });
+
+    it('should return empty list when nothing matches', () => {
+      const list = List.of(1, 3, 5);
+      const evens = list.filter((x) => x % 2 === 0);
+      expect(evens.isEmpty).toBe(true);
+    });
+  });
+
+  describe('flatMap', () => {
+    it('should flatMap with arrays', () => {
+      const list = List.of(1, 2, 3);
+      const result = list.flatMap((x) => [x, x * 10]);
+      expect(result.toArray()).toEqual([1, 10, 2, 20, 3, 30]);
+    });
+
+    it('should flatMap with Lists', () => {
+      const list = List.of(1, 2);
+      const result = list.flatMap((x) => List.of(x, x + 1));
+      expect(result.toArray()).toEqual([1, 2, 2, 3]);
+    });
+  });
+
+  describe('reduce', () => {
+    it('should reduce with initial value', () => {
+      const list = List.of(1, 2, 3, 4);
+      const sum = list.reduce((acc, x) => acc + x, 0);
+      expect(sum).toBe(10);
+    });
+  });
+
+  describe('immutability', () => {
+    it('operations should return new List instances', () => {
+      const original = List.of(1, 2, 3);
+      const mapped = original.map((x) => x * 2);
+      const filtered = original.filter((x) => x > 1);
+
+      expect(original.toArray()).toEqual([1, 2, 3]);
+      expect(mapped.toArray()).toEqual([2, 4, 6]);
+      expect(filtered.toArray()).toEqual([2, 3]);
+    });
+  });
+
+  describe('toArray', () => {
+    it('should return array copy', () => {
+      const list = List.of(1, 2, 3);
+      const arr = list.toArray();
+      expect(arr).toEqual([1, 2, 3]);
+      arr.push(4);
+      expect(list.length).toBe(3); // Original unchanged
+    });
+  });
+
+  describe('iteration', () => {
+    it('should be iterable', () => {
+      const list = List.of(1, 2, 3);
+      const result: number[] = [];
+      for (const item of list) {
+        result.push(item);
+      }
+      expect(result).toEqual([1, 2, 3]);
+    });
+  });
+});

package/src/__tests__/events.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi } from 'vitest';
+import { EventBus } from '../events.js';
+
+describe('EventBus', () => {
+  describe('on / emit', () => {
+    it('calls handler on emit', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.on('test', fn);
+      bus.emit('test', 42);
+      expect(fn).toHaveBeenCalledWith(42);
+    });
+
+    it('calls handler multiple times', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.on('x', fn);
+      bus.emit('x');
+      bus.emit('x');
+      bus.emit('x');
+      expect(fn).toHaveBeenCalledTimes(3);
+    });
+
+    it('handles multiple listeners on same event', () => {
+      const bus = new EventBus();
+      const fn1 = vi.fn();
+      const fn2 = vi.fn();
+      bus.on('e', fn1);
+      bus.on('e', fn2);
+      bus.emit('e', 'data');
+      expect(fn1).toHaveBeenCalledWith('data');
+      expect(fn2).toHaveBeenCalledWith('data');
+    });
+
+    it('does not call unrelated listeners', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.on('a', fn);
+      bus.emit('b');
+      expect(fn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('once', () => {
+    it('calls handler only once', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.once('x', fn);
+      bus.emit('x', 1);
+      bus.emit('x', 2);
+      expect(fn).toHaveBeenCalledTimes(1);
+      expect(fn).toHaveBeenCalledWith(1);
+    });
+  });
+
+  describe('off', () => {
+    it('removes a listener', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.on('x', fn);
+      bus.off('x', fn);
+      bus.emit('x');
+      expect(fn).not.toHaveBeenCalled();
+    });
+
+    it('returns unsubscribe function', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      const unsub = bus.on('x', fn);
+      unsub();
+      bus.emit('x');
+      expect(fn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('onAny', () => {
+    it('receives all events', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      bus.onAny(fn);
+      bus.emit('a', 1);
+      bus.emit('b', 2);
+      expect(fn).toHaveBeenCalledTimes(2);
+      expect(fn).toHaveBeenCalledWith({ event: 'a', data: 1 });
+      expect(fn).toHaveBeenCalledWith({ event: 'b', data: 2 });
+    });
+
+    it('returns unsubscribe function', () => {
+      const bus = new EventBus();
+      const fn = vi.fn();
+      const unsub = bus.onAny(fn);
+      unsub();
+      bus.emit('x');
+      expect(fn).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('clear', () => {
+    it('removes all listeners', () => {
+      const bus = new EventBus();
+      const fn1 = vi.fn();
+      const fn2 = vi.fn();
+      bus.on('a', fn1);
+      bus.onAny(fn2);
+      bus.clear();
+      bus.emit('a');
+      expect(fn1).not.toHaveBeenCalled();
+      expect(fn2).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('listenerCount', () => {
+    it('counts specific event listeners', () => {
+      const bus = new EventBus();
+      bus.on('a', () => {});
+      bus.on('a', () => {});
+      bus.on('b', () => {});
+      expect(bus.listenerCount('a')).toBe(2);
+      expect(bus.listenerCount('b')).toBe(1);
+      expect(bus.listenerCount('c')).toBe(0);
+    });
+
+    it('counts all listeners', () => {
+      const bus = new EventBus();
+      bus.on('a', () => {});
+      bus.on('b', () => {});
+      bus.onAny(() => {});
+      expect(bus.listenerCount()).toBe(3);
+    });
+
+    it('empty bus has 0 listeners', () => {
+      expect(new EventBus().listenerCount()).toBe(0);
+    });
+  });
+});

package/src/__tests__/materials.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { MATERIAL_PRESETS, createPBRMaterial } from '../materials.js';
+import type { PBRMaterial } from '../materials.js';
+
+describe('MATERIAL_PRESETS', () => {
+  it('should have at least 10 presets', () => {
+    expect(Object.keys(MATERIAL_PRESETS).length).toBeGreaterThanOrEqual(10);
+  });
+
+  it('metal preset should be highly metallic', () => {
+    expect(MATERIAL_PRESETS.metal.metallic).toBe(1.0);
+    expect(MATERIAL_PRESETS.metal.roughness).toBeLessThan(0.5);
+  });
+
+  it('wood preset should not be metallic', () => {
+    expect(MATERIAL_PRESETS.wood.metallic).toBe(0.0);
+    expect(MATERIAL_PRESETS.wood.roughness).toBeGreaterThan(0.7);
+  });
+
+  it('glass preset should have low roughness and ior', () => {
+    expect(MATERIAL_PRESETS.glass.roughness).toBeLessThan(0.2);
+    expect(MATERIAL_PRESETS.glass.ior).toBeCloseTo(1.5);
+    expect(MATERIAL_PRESETS.glass.opacity).toBeLessThan(1.0);
+  });
+
+  it('water preset should have correct ior', () => {
+    expect(MATERIAL_PRESETS.water.ior).toBeCloseTo(1.33);
+  });
+
+  it('chrome preset should be fully metallic with low roughness', () => {
+    expect(MATERIAL_PRESETS.chrome.metallic).toBe(1.0);
+    expect(MATERIAL_PRESETS.chrome.roughness).toBeLessThan(0.1);
+  });
+
+  it('skin preset should have subsurface scattering', () => {
+    expect(MATERIAL_PRESETS.skin.subsurface).toBeGreaterThan(0);
+  });
+
+  it('all presets should have roughness defined', () => {
+    for (const [name, preset] of Object.entries(MATERIAL_PRESETS)) {
+      expect(preset.roughness, `${name} missing roughness`).toBeDefined();
+    }
+  });
+
+  it('all presets should have metallic defined', () => {
+    for (const [name, preset] of Object.entries(MATERIAL_PRESETS)) {
+      expect(preset.metallic, `${name} missing metallic`).toBeDefined();
+    }
+  });
+});
+
+describe('createPBRMaterial', () => {
+  it('creates material with defaults', () => {
+    const mat = createPBRMaterial('Test');
+    expect(mat.name).toBe('Test');
+    expect(mat.baseColor).toBe('#ffffff');
+    expect(mat.roughness).toBe(0.5);
+    expect(mat.metallic).toBe(0.0);
+  });
+
+  it('applies preset', () => {
+    const mat = createPBRMaterial('Steel', 'metal');
+    expect(mat.metallic).toBe(1.0);
+    expect(mat.roughness).toBe(0.2);
+  });
+
+  it('overrides preset values', () => {
+    const mat = createPBRMaterial('CustomMetal', 'metal', { roughness: 0.8 });
+    expect(mat.metallic).toBe(1.0);
+    expect(mat.roughness).toBe(0.8);
+  });
+
+  it('creates material without preset', () => {
+    const mat = createPBRMaterial('Plain', undefined, { baseColor: '#ff0000' });
+    expect(mat.baseColor).toBe('#ff0000');
+    expect(mat.roughness).toBe(0.5);
+  });
+
+  it('preserves name through preset', () => {
+    const mat = createPBRMaterial('Gold', 'gold');
+    expect(mat.name).toBe('Gold');
+    expect(mat.baseColor).toBe('#ffd700');
+  });
+});

package/src/__tests__/math.test.ts

@@ -0,0 +1,246 @@
+import { describe, it, expect } from 'vitest';
+import {
+  PI,
+  TAU,
+  HALF_PI,
+  DEG_TO_RAD,
+  RAD_TO_DEG,
+  EPSILON,
+  clamp,
+  lerp,
+  inverseLerp,
+  remap,
+  smoothstep,
+  smootherstep,
+  degToRad,
+  radToDeg,
+  mod,
+  fract,
+  sign,
+  step,
+} from '../math.js';
+
+describe('Math Constants', () => {
+  it('PI should be Math.PI', () => {
+    expect(PI).toBe(Math.PI);
+  });
+
+  it('TAU should be 2 * PI', () => {
+    expect(TAU).toBe(Math.PI * 2);
+  });
+
+  it('HALF_PI should be PI / 2', () => {
+    expect(HALF_PI).toBe(Math.PI / 2);
+  });
+
+  it('DEG_TO_RAD should convert degrees to radians', () => {
+    expect(DEG_TO_RAD).toBe(Math.PI / 180);
+  });
+
+  it('RAD_TO_DEG should convert radians to degrees', () => {
+    expect(RAD_TO_DEG).toBe(180 / Math.PI);
+  });
+
+  it('EPSILON should be a small value for float comparison', () => {
+    expect(EPSILON).toBe(1e-6);
+  });
+});
+
+describe('clamp', () => {
+  it('should return min when value is below min', () => {
+    expect(clamp(-5, 0, 10)).toBe(0);
+  });
+
+  it('should return max when value is above max', () => {
+    expect(clamp(15, 0, 10)).toBe(10);
+  });
+
+  it('should return value when within range', () => {
+    expect(clamp(5, 0, 10)).toBe(5);
+  });
+
+  it('should handle edge cases at boundaries', () => {
+    expect(clamp(0, 0, 10)).toBe(0);
+    expect(clamp(10, 0, 10)).toBe(10);
+  });
+
+  it('should work with negative ranges', () => {
+    expect(clamp(-5, -10, -1)).toBe(-5);
+    expect(clamp(-15, -10, -1)).toBe(-10);
+  });
+});
+
+describe('lerp', () => {
+  it('should return a when t is 0', () => {
+    expect(lerp(0, 10, 0)).toBe(0);
+  });
+
+  it('should return b when t is 1', () => {
+    expect(lerp(0, 10, 1)).toBe(10);
+  });
+
+  it('should return midpoint when t is 0.5', () => {
+    expect(lerp(0, 10, 0.5)).toBe(5);
+  });
+
+  it('should extrapolate when t > 1', () => {
+    expect(lerp(0, 10, 2)).toBe(20);
+  });
+
+  it('should work with negative values', () => {
+    expect(lerp(-10, 10, 0.5)).toBe(0);
+  });
+});
+
+describe('inverseLerp', () => {
+  it('should return 0 when value equals a', () => {
+    expect(inverseLerp(0, 10, 0)).toBe(0);
+  });
+
+  it('should return 1 when value equals b', () => {
+    expect(inverseLerp(0, 10, 10)).toBe(1);
+  });
+
+  it('should return 0.5 when value is midpoint', () => {
+    expect(inverseLerp(0, 10, 5)).toBe(0.5);
+  });
+
+  it('should work with negative ranges', () => {
+    expect(inverseLerp(-10, 10, 0)).toBe(0.5);
+  });
+});
+
+describe('remap', () => {
+  it('should remap 0-1 to 0-100', () => {
+    expect(remap(0.5, 0, 1, 0, 100)).toBe(50);
+  });
+
+  it('should remap between different ranges', () => {
+    expect(remap(5, 0, 10, 100, 200)).toBe(150);
+  });
+
+  it('should handle inverted output ranges', () => {
+    expect(remap(0, 0, 10, 100, 0)).toBe(100);
+    expect(remap(10, 0, 10, 100, 0)).toBe(0);
+  });
+});
+
+describe('smoothstep', () => {
+  it('should return 0 when x <= edge0', () => {
+    expect(smoothstep(0, 1, -0.5)).toBe(0);
+    expect(smoothstep(0, 1, 0)).toBe(0);
+  });
+
+  it('should return 1 when x >= edge1', () => {
+    expect(smoothstep(0, 1, 1)).toBe(1);
+    expect(smoothstep(0, 1, 1.5)).toBe(1);
+  });
+
+  it('should return smooth interpolation in between', () => {
+    const mid = smoothstep(0, 1, 0.5);
+    expect(mid).toBe(0.5);
+  });
+});
+
+describe('smootherstep', () => {
+  it('should return 0 when x <= edge0', () => {
+    expect(smootherstep(0, 1, 0)).toBe(0);
+  });
+
+  it('should return 1 when x >= edge1', () => {
+    expect(smootherstep(0, 1, 1)).toBe(1);
+  });
+
+  it('should return smooth interpolation at midpoint', () => {
+    const mid = smootherstep(0, 1, 0.5);
+    expect(mid).toBe(0.5);
+  });
+});
+
+describe('degToRad', () => {
+  it('should convert 0 degrees to 0 radians', () => {
+    expect(degToRad(0)).toBe(0);
+  });
+
+  it('should convert 180 degrees to PI radians', () => {
+    expect(degToRad(180)).toBeCloseTo(Math.PI);
+  });
+
+  it('should convert 360 degrees to 2*PI radians', () => {
+    expect(degToRad(360)).toBeCloseTo(2 * Math.PI);
+  });
+
+  it('should convert 90 degrees to PI/2 radians', () => {
+    expect(degToRad(90)).toBeCloseTo(Math.PI / 2);
+  });
+});
+
+describe('radToDeg', () => {
+  it('should convert 0 radians to 0 degrees', () => {
+    expect(radToDeg(0)).toBe(0);
+  });
+
+  it('should convert PI radians to 180 degrees', () => {
+    expect(radToDeg(Math.PI)).toBeCloseTo(180);
+  });
+
+  it('should convert 2*PI radians to 360 degrees', () => {
+    expect(radToDeg(2 * Math.PI)).toBeCloseTo(360);
+  });
+});
+
+describe('mod', () => {
+  it('should handle positive modulo', () => {
+    expect(mod(7, 3)).toBe(1);
+  });
+
+  it('should handle negative values correctly (always positive result)', () => {
+    expect(mod(-1, 3)).toBe(2);
+    expect(mod(-4, 3)).toBe(2);
+  });
+
+  it('should return 0 for exact multiples', () => {
+    expect(mod(6, 3)).toBe(0);
+  });
+});
+
+describe('fract', () => {
+  it('should return fractional part of positive numbers', () => {
+    expect(fract(3.7)).toBeCloseTo(0.7);
+  });
+
+  it('should return 0 for integers', () => {
+    expect(fract(5)).toBe(0);
+  });
+
+  it('should handle negative numbers', () => {
+    expect(fract(-3.3)).toBeCloseTo(0.7);
+  });
+});
+
+describe('sign', () => {
+  it('should return 1 for positive numbers', () => {
+    expect(sign(5)).toBe(1);
+    expect(sign(0.001)).toBe(1);
+  });
+
+  it('should return -1 for negative numbers', () => {
+    expect(sign(-5)).toBe(-1);
+    expect(sign(-0.001)).toBe(-1);
+  });
+
+  it('should return 0 for zero', () => {
+    expect(sign(0)).toBe(0);
+  });
+});
+
+describe('step', () => {
+  it('should return 0 when x < edge', () => {
+    expect(step(0.5, 0.3)).toBe(0);
+  });
+
+  it('should return 1 when x >= edge', () => {
+    expect(step(0.5, 0.5)).toBe(1);
+    expect(step(0.5, 0.7)).toBe(1);
+  });
+});