@holoscript/std 2.1.0 → 3.1.1

package/src/__tests__/physics.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+import {
+  createBoxCollider,
+  createSphereCollider,
+  createCapsuleCollider,
+  createRigidbody,
+} from '../physics.js';
+import { Vec3 } from '../spatial.js';
+
+describe('createBoxCollider', () => {
+  it('creates a box collider with defaults', () => {
+    const c = createBoxCollider(new Vec3(1, 1, 1));
+    expect(c.shape).toBe('box');
+    expect(c.isTrigger).toBe(false);
+    expect(c.friction).toBe(0.5);
+    expect(c.restitution).toBe(0.0);
+    expect(c.halfExtents).toBeDefined();
+  });
+
+  it('accepts option overrides', () => {
+    const c = createBoxCollider(new Vec3(2, 2, 2), { friction: 0.9, isTrigger: true });
+    expect(c.friction).toBe(0.9);
+    expect(c.isTrigger).toBe(true);
+  });
+});
+
+describe('createSphereCollider', () => {
+  it('creates a sphere collider', () => {
+    const c = createSphereCollider(0.5);
+    expect(c.shape).toBe('sphere');
+    expect(c.radius).toBe(0.5);
+    expect(c.friction).toBe(0.5);
+  });
+
+  it('overrides restitution', () => {
+    const c = createSphereCollider(1.0, { restitution: 0.8 });
+    expect(c.restitution).toBe(0.8);
+  });
+});
+
+describe('createCapsuleCollider', () => {
+  it('creates a capsule collider', () => {
+    const c = createCapsuleCollider(0.3, 1.8);
+    expect(c.shape).toBe('capsule');
+    expect(c.radius).toBe(0.3);
+    expect(c.height).toBe(1.8);
+  });
+});
+
+describe('createRigidbody', () => {
+  it('creates a rigidbody with defaults', () => {
+    const rb = createRigidbody(10);
+    expect(rb.mass).toBe(10);
+    expect(rb.useGravity).toBe(true);
+    expect(rb.linearDamping).toBe(0.0);
+    expect(rb.angularDamping).toBe(0.05);
+    expect(rb.isKinematic).toBe(false);
+    expect(rb.freezePosition).toEqual([false, false, false]);
+    expect(rb.freezeRotation).toEqual([false, false, false]);
+  });
+
+  it('overrides gravity', () => {
+    const rb = createRigidbody(5, { useGravity: false });
+    expect(rb.useGravity).toBe(false);
+  });
+
+  it('overrides kinematic', () => {
+    const rb = createRigidbody(1, { isKinematic: true });
+    expect(rb.isKinematic).toBe(true);
+    expect(rb.mass).toBe(1);
+  });
+
+  it('overrides damping', () => {
+    const rb = createRigidbody(50, { linearDamping: 0.5, angularDamping: 0.8 });
+    expect(rb.linearDamping).toBe(0.5);
+    expect(rb.angularDamping).toBe(0.8);
+  });
+
+  it('overrides freeze axes', () => {
+    const rb = createRigidbody(1, { freezePosition: [true, false, true] });
+    expect(rb.freezePosition).toEqual([true, false, true]);
+  });
+});

package/src/__tests__/spatial.test.ts

@@ -0,0 +1,333 @@
+import { describe, it, expect } from 'vitest';
+import {
+  Vec3,
+  Quaternion,
+  Transform,
+  Ray,
+  AABB,
+  distance,
+  lerp,
+  clamp,
+  degToRad,
+  radToDeg,
+} from '../spatial.js';
+
+// =============================================================================
+// Vec3
+// =============================================================================
+
+describe('Vec3', () => {
+  describe('constructors', () => {
+    it('should default to zero', () => {
+      const v = new Vec3();
+      expect(v.x).toBe(0);
+      expect(v.y).toBe(0);
+      expect(v.z).toBe(0);
+    });
+
+    it('should create from values', () => {
+      const v = new Vec3(1, 2, 3);
+      expect(v.x).toBe(1);
+      expect(v.y).toBe(2);
+      expect(v.z).toBe(3);
+    });
+
+    it('static zero()', () => {
+      expect(Vec3.zero().equals(new Vec3(0, 0, 0))).toBe(true);
+    });
+
+    it('static one()', () => {
+      expect(Vec3.one().equals(new Vec3(1, 1, 1))).toBe(true);
+    });
+
+    it('static up()', () => {
+      expect(Vec3.up().y).toBe(1);
+    });
+
+    it('static forward()', () => {
+      expect(Vec3.forward().z).toBe(-1);
+    });
+
+    it('static right()', () => {
+      expect(Vec3.right().x).toBe(1);
+    });
+  });
+
+  describe('arithmetic', () => {
+    it('add', () => {
+      const r = new Vec3(1, 2, 3).add(new Vec3(4, 5, 6));
+      expect(r.equals(new Vec3(5, 7, 9))).toBe(true);
+    });
+
+    it('sub', () => {
+      const r = new Vec3(5, 7, 9).sub(new Vec3(4, 5, 6));
+      expect(r.equals(new Vec3(1, 2, 3))).toBe(true);
+    });
+
+    it('mul', () => {
+      const r = new Vec3(1, 2, 3).mul(2);
+      expect(r.equals(new Vec3(2, 4, 6))).toBe(true);
+    });
+
+    it('div', () => {
+      const r = new Vec3(4, 6, 8).div(2);
+      expect(r.equals(new Vec3(2, 3, 4))).toBe(true);
+    });
+  });
+
+  describe('vector operations', () => {
+    it('dot product', () => {
+      expect(new Vec3(1, 0, 0).dot(new Vec3(0, 1, 0))).toBe(0);
+      expect(new Vec3(1, 0, 0).dot(new Vec3(1, 0, 0))).toBe(1);
+    });
+
+    it('cross product', () => {
+      const r = new Vec3(1, 0, 0).cross(new Vec3(0, 1, 0));
+      expect(r.equals(new Vec3(0, 0, 1))).toBe(true);
+    });
+
+    it('length', () => {
+      expect(new Vec3(3, 4, 0).length()).toBe(5);
+    });
+
+    it('lengthSquared', () => {
+      expect(new Vec3(3, 4, 0).lengthSquared()).toBe(25);
+    });
+
+    it('normalize', () => {
+      const n = new Vec3(3, 0, 0).normalize();
+      expect(n.length()).toBeCloseTo(1);
+      expect(n.x).toBeCloseTo(1);
+    });
+
+    it('normalize zero returns zero', () => {
+      const n = Vec3.zero().normalize();
+      expect(n.length()).toBe(0);
+    });
+
+    it('distanceTo', () => {
+      expect(new Vec3(0, 0, 0).distanceTo(new Vec3(3, 4, 0))).toBe(5);
+    });
+
+    it('lerp', () => {
+      const r = new Vec3(0, 0, 0).lerp(new Vec3(10, 10, 10), 0.5);
+      expect(r.equals(new Vec3(5, 5, 5))).toBe(true);
+    });
+
+    it('lerp at 0 returns start', () => {
+      const a = new Vec3(1, 2, 3);
+      expect(a.lerp(new Vec3(10, 20, 30), 0).equals(a)).toBe(true);
+    });
+
+    it('lerp at 1 returns end', () => {
+      const b = new Vec3(10, 20, 30);
+      expect(new Vec3(1, 2, 3).lerp(b, 1).equals(b)).toBe(true);
+    });
+  });
+
+  describe('conversion', () => {
+    it('toArray', () => {
+      expect(new Vec3(1, 2, 3).toArray()).toEqual([1, 2, 3]);
+    });
+
+    it('fromArray', () => {
+      expect(Vec3.fromArray([4, 5, 6]).equals(new Vec3(4, 5, 6))).toBe(true);
+    });
+
+    it('fromArray handles short arrays', () => {
+      expect(Vec3.fromArray([1]).equals(new Vec3(1, 0, 0))).toBe(true);
+    });
+
+    it('toString', () => {
+      expect(new Vec3(1, 2, 3).toString()).toBe('Vec3(1, 2, 3)');
+    });
+  });
+
+  describe('equals', () => {
+    it('equal vectors', () => {
+      expect(new Vec3(1, 2, 3).equals(new Vec3(1, 2, 3))).toBe(true);
+    });
+
+    it('unequal vectors', () => {
+      expect(new Vec3(1, 2, 3).equals(new Vec3(1, 2, 4))).toBe(false);
+    });
+
+    it('epsilon comparison', () => {
+      expect(new Vec3(1, 2, 3.0000001).equals(new Vec3(1, 2, 3))).toBe(true);
+    });
+  });
+});
+
+// =============================================================================
+// Quaternion
+// =============================================================================
+
+describe('Quaternion', () => {
+  it('identity', () => {
+    const q = Quaternion.identity();
+    expect(q.w).toBe(1);
+    expect(q.x).toBe(0);
+  });
+
+  it('fromEuler and toEuler roundtrip', () => {
+    const q = Quaternion.fromEuler(0.5, 0.3, 0.1);
+    const euler = q.toEuler();
+    expect(euler.x).toBeCloseTo(0.5, 3);
+    expect(euler.y).toBeCloseTo(0.3, 3);
+    expect(euler.z).toBeCloseTo(0.1, 3);
+  });
+
+  it('fromAxisAngle', () => {
+    const q = Quaternion.fromAxisAngle(Vec3.up(), Math.PI / 2);
+    const n = q.normalize();
+    expect(n.w).toBeCloseTo(Math.cos(Math.PI / 4));
+  });
+
+  it('multiply identity is no-op', () => {
+    const q = Quaternion.fromEuler(0.5, 0.3, 0.1);
+    const r = q.multiply(Quaternion.identity());
+    expect(r.x).toBeCloseTo(q.x);
+    expect(r.y).toBeCloseTo(q.y);
+    expect(r.z).toBeCloseTo(q.z);
+    expect(r.w).toBeCloseTo(q.w);
+  });
+
+  it('rotateVec3', () => {
+    const q = Quaternion.fromAxisAngle(Vec3.up(), Math.PI / 2);
+    const v = q.rotateVec3(new Vec3(1, 0, 0));
+    expect(v.x).toBeCloseTo(0, 3);
+    expect(v.z).toBeCloseTo(-1, 3);
+  });
+
+  it('slerp at 0 returns start', () => {
+    const a = Quaternion.identity();
+    const b = Quaternion.fromEuler(1, 0, 0);
+    const r = a.slerp(b, 0);
+    expect(r.w).toBeCloseTo(a.w);
+  });
+
+  it('slerp at 1 returns end', () => {
+    const a = Quaternion.identity();
+    const b = Quaternion.fromEuler(1, 0, 0);
+    const r = a.slerp(b, 1);
+    expect(r.x).toBeCloseTo(b.x, 3);
+    expect(r.w).toBeCloseTo(b.w, 3);
+  });
+
+  it('normalize preserves direction', () => {
+    const q = new Quaternion(0, 0, 0, 2);
+    const n = q.normalize();
+    expect(n.w).toBeCloseTo(1);
+  });
+});
+
+// =============================================================================
+// Transform
+// =============================================================================
+
+describe('Transform', () => {
+  it('identity does nothing', () => {
+    const t = Transform.identity();
+    const p = t.transformPoint(new Vec3(1, 2, 3));
+    expect(p.equals(new Vec3(1, 2, 3))).toBe(true);
+  });
+
+  it('translation', () => {
+    const t = new Transform(new Vec3(10, 0, 0));
+    const p = t.transformPoint(Vec3.zero());
+    expect(p.equals(new Vec3(10, 0, 0))).toBe(true);
+  });
+
+  it('scale', () => {
+    const t = new Transform(Vec3.zero(), Quaternion.identity(), new Vec3(2, 2, 2));
+    const p = t.transformPoint(new Vec3(1, 1, 1));
+    expect(p.equals(new Vec3(2, 2, 2))).toBe(true);
+  });
+
+  it('transformDirection ignores position', () => {
+    const t = new Transform(new Vec3(100, 100, 100));
+    const d = t.transformDirection(new Vec3(1, 0, 0));
+    expect(d.equals(new Vec3(1, 0, 0))).toBe(true);
+  });
+});
+
+// =============================================================================
+// Ray & AABB
+// =============================================================================
+
+describe('Ray', () => {
+  it('pointAt', () => {
+    const r = new Ray(Vec3.zero(), new Vec3(1, 0, 0));
+    expect(r.pointAt(5).equals(new Vec3(5, 0, 0))).toBe(true);
+  });
+});
+
+describe('AABB', () => {
+  const box = new AABB(new Vec3(-1, -1, -1), new Vec3(1, 1, 1));
+
+  it('contains point inside', () => {
+    expect(box.contains(Vec3.zero())).toBe(true);
+  });
+
+  it('does not contain point outside', () => {
+    expect(box.contains(new Vec3(2, 0, 0))).toBe(false);
+  });
+
+  it('intersects overlapping AABB', () => {
+    const other = new AABB(new Vec3(0, 0, 0), new Vec3(2, 2, 2));
+    expect(box.intersects(other)).toBe(true);
+  });
+
+  it('does not intersect non-overlapping AABB', () => {
+    const other = new AABB(new Vec3(5, 5, 5), new Vec3(6, 6, 6));
+    expect(box.intersects(other)).toBe(false);
+  });
+
+  it('center', () => {
+    expect(box.center().equals(Vec3.zero())).toBe(true);
+  });
+
+  it('size', () => {
+    expect(box.size().equals(new Vec3(2, 2, 2))).toBe(true);
+  });
+
+  it('ray intersection hit', () => {
+    const ray = new Ray(new Vec3(-5, 0, 0), new Vec3(1, 0, 0));
+    const t = box.intersectsRay(ray);
+    expect(t).not.toBeNull();
+    expect(t).toBeCloseTo(4);
+  });
+
+  it('ray intersection miss', () => {
+    const ray = new Ray(new Vec3(-5, 5, 0), new Vec3(1, 0, 0));
+    expect(box.intersectsRay(ray)).toBeNull();
+  });
+});
+
+// =============================================================================
+// Utility functions
+// =============================================================================
+
+describe('utility functions', () => {
+  it('distance', () => {
+    expect(distance(Vec3.zero(), new Vec3(3, 4, 0))).toBe(5);
+  });
+
+  it('lerp', () => {
+    expect(lerp(0, 10, 0.5)).toBe(5);
+  });
+
+  it('clamp', () => {
+    expect(clamp(-5, 0, 10)).toBe(0);
+    expect(clamp(15, 0, 10)).toBe(10);
+    expect(clamp(5, 0, 10)).toBe(5);
+  });
+
+  it('degToRad', () => {
+    expect(degToRad(180)).toBeCloseTo(Math.PI);
+  });
+
+  it('radToDeg', () => {
+    expect(radToDeg(Math.PI)).toBeCloseTo(180);
+  });
+});

package/src/__tests__/string-decoupled.test.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+
+// Auto-generated test for string-decoupled
+// Source: packages/std/src/string.ts
+
+describe('string-decoupled', () => {
+  it('should be defined', () => {
+    // TODO: Import and test string-decoupled
+    expect(true).toBe(true);
+  });
+
+  it('should have basic functionality', () => {
+    // TODO: Add meaningful tests for string-decoupled
+    expect(true).toBe(true);
+  });
+});

package/src/__tests__/string.test.ts

@@ -0,0 +1,164 @@
+import { describe, it, expect } from 'vitest';
+import {
+  isBlank,
+  isNotBlank,
+  capitalize,
+  titleCase,
+  camelCase,
+  pascalCase,
+  snakeCase,
+  kebabCase,
+  constantCase,
+} from '../string.js';
+
+describe('isBlank', () => {
+  it('should return true for empty string', () => {
+    expect(isBlank('')).toBe(true);
+  });
+
+  it('should return true for whitespace only', () => {
+    expect(isBlank('   ')).toBe(true);
+    expect(isBlank('\t\n')).toBe(true);
+  });
+
+  it('should return false for non-empty string', () => {
+    expect(isBlank('hello')).toBe(false);
+    expect(isBlank(' hello ')).toBe(false);
+  });
+});
+
+describe('isNotBlank', () => {
+  it('should return false for empty string', () => {
+    expect(isNotBlank('')).toBe(false);
+  });
+
+  it('should return false for whitespace only', () => {
+    expect(isNotBlank('   ')).toBe(false);
+  });
+
+  it('should return true for non-empty string', () => {
+    expect(isNotBlank('hello')).toBe(true);
+  });
+});
+
+describe('capitalize', () => {
+  it('should capitalize first letter', () => {
+    expect(capitalize('hello')).toBe('Hello');
+  });
+
+  it('should handle empty string', () => {
+    expect(capitalize('')).toBe('');
+  });
+
+  it('should handle already capitalized', () => {
+    expect(capitalize('Hello')).toBe('Hello');
+  });
+
+  it('should handle single character', () => {
+    expect(capitalize('a')).toBe('A');
+  });
+});
+
+describe('titleCase', () => {
+  it('should capitalize each word', () => {
+    expect(titleCase('hello world')).toBe('Hello World');
+  });
+
+  it('should handle multiple spaces', () => {
+    expect(titleCase('hello  world')).toBe('Hello World');
+  });
+
+  it('should handle single word', () => {
+    expect(titleCase('hello')).toBe('Hello');
+  });
+});
+
+describe('camelCase', () => {
+  it('should convert space-separated to camelCase', () => {
+    expect(camelCase('hello world')).toBe('helloWorld');
+  });
+
+  it('should convert kebab-case to camelCase', () => {
+    expect(camelCase('hello-world')).toBe('helloWorld');
+  });
+
+  it('should convert snake_case to camelCase', () => {
+    expect(camelCase('hello_world')).toBe('helloWorld');
+  });
+
+  it('should lowercase first letter of PascalCase', () => {
+    expect(camelCase('HelloWorld')).toBe('helloWorld');
+  });
+
+  it('should handle empty string', () => {
+    expect(camelCase('')).toBe('');
+  });
+});
+
+describe('pascalCase', () => {
+  it('should convert space-separated to PascalCase', () => {
+    expect(pascalCase('hello world')).toBe('HelloWorld');
+  });
+
+  it('should convert kebab-case to PascalCase', () => {
+    expect(pascalCase('hello-world')).toBe('HelloWorld');
+  });
+
+  it('should convert snake_case to PascalCase', () => {
+    expect(pascalCase('hello_world')).toBe('HelloWorld');
+  });
+
+  it('should handle empty string', () => {
+    expect(pascalCase('')).toBe('');
+  });
+});
+
+describe('snakeCase', () => {
+  it('should convert space-separated to snake_case', () => {
+    expect(snakeCase('hello world')).toBe('hello_world');
+  });
+
+  it('should convert camelCase to snake_case', () => {
+    expect(snakeCase('helloWorld')).toBe('hello_world');
+  });
+
+  it('should convert PascalCase to snake_case', () => {
+    expect(snakeCase('HelloWorld')).toBe('hello_world');
+  });
+
+  it('should convert kebab-case to snake_case', () => {
+    expect(snakeCase('hello-world')).toBe('hello_world');
+  });
+});
+
+describe('kebabCase', () => {
+  it('should convert space-separated to kebab-case', () => {
+    expect(kebabCase('hello world')).toBe('hello-world');
+  });
+
+  it('should convert camelCase to kebab-case', () => {
+    expect(kebabCase('helloWorld')).toBe('hello-world');
+  });
+
+  it('should convert PascalCase to kebab-case', () => {
+    expect(kebabCase('HelloWorld')).toBe('hello-world');
+  });
+
+  it('should convert snake_case to kebab-case', () => {
+    expect(kebabCase('hello_world')).toBe('hello-world');
+  });
+});
+
+describe('constantCase', () => {
+  it('should convert to SCREAMING_SNAKE_CASE', () => {
+    expect(constantCase('hello world')).toBe('HELLO_WORLD');
+  });
+
+  it('should convert camelCase to SCREAMING_SNAKE_CASE', () => {
+    expect(constantCase('helloWorld')).toBe('HELLO_WORLD');
+  });
+
+  it('should convert kebab-case to SCREAMING_SNAKE_CASE', () => {
+    expect(constantCase('hello-world')).toBe('HELLO_WORLD');
+  });
+});

package/src/__tests__/time.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { now, hrTime, sleep, withTimeout } from '../time.js';
+
+describe('now', () => {
+  it('should return current timestamp in milliseconds', () => {
+    const before = Date.now();
+    const result = now();
+    const after = Date.now();
+
+    expect(result).toBeGreaterThanOrEqual(before);
+    expect(result).toBeLessThanOrEqual(after);
+  });
+
+  it('should return a number', () => {
+    expect(typeof now()).toBe('number');
+  });
+});
+
+describe('hrTime', () => {
+  it('should return high-resolution timestamp', () => {
+    const result = hrTime();
+    expect(typeof result).toBe('number');
+    expect(result).toBeGreaterThanOrEqual(0);
+  });
+
+  it('should increase over time', async () => {
+    const t1 = hrTime();
+    await sleep(10);
+    const t2 = hrTime();
+    expect(t2).toBeGreaterThan(t1);
+  });
+});
+
+describe('sleep', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should return a promise', () => {
+    const result = sleep(100);
+    expect(result).toBeInstanceOf(Promise);
+    vi.runAllTimers();
+  });
+
+  it('should resolve after specified time', async () => {
+    let resolved = false;
+    const promise = sleep(1000).then(() => {
+      resolved = true;
+    });
+
+    expect(resolved).toBe(false);
+
+    vi.advanceTimersByTime(500);
+    await Promise.resolve();
+    expect(resolved).toBe(false);
+
+    vi.advanceTimersByTime(500);
+    await promise;
+    expect(resolved).toBe(true);
+  });
+});
+
+describe('withTimeout', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('should resolve if function completes before timeout', async () => {
+    const fn = async () => {
+      await sleep(50);
+      return 'success';
+    };
+
+    const promise = withTimeout(fn, 1000);
+    vi.advanceTimersByTime(50);
+    await vi.runAllTimersAsync();
+
+    const result = await promise;
+    expect(result).toBe('success');
+  });
+
+  it('should reject with Timeout error if function takes too long', async () => {
+    const fn = async () => {
+      await sleep(2000);
+      return 'success';
+    };
+
+    const promise = withTimeout(fn, 100);
+    vi.advanceTimersByTime(100);
+
+    await expect(promise).rejects.toThrow('Timeout');
+  });
+});
+
+describe('time utilities - real timers', () => {
+  it('sleep should actually wait (short duration)', async () => {
+    const start = Date.now();
+    await sleep(50);
+    const elapsed = Date.now() - start;
+    expect(elapsed).toBeGreaterThanOrEqual(40); // Allow some tolerance
+  });
+});