@graphty/layout 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [1.2.2](https://github.com/graphty-org/layout/compare/v1.2.1...v1.2.2) (2025-07-13)
+
+
+### Bug Fixes
+
+* numpy linspace error. improve test coverage ([2e820f1](https://github.com/graphty-org/layout/commit/2e820f181bd7242ef251c1833b10533699485209))
+
 ## [1.2.1](https://github.com/graphty-org/layout/compare/v1.2.0...v1.2.1) (2025-07-13)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/layout",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "graph layout algorithms based on networkx",
   "main": "dist/src/index.js",
   "type": "module",

package/src/utils/numpy.ts

@@ -25,6 +25,9 @@ export const np = {
   },
 
   linspace: function (start: number, stop: number, num: number): number[] {
+    if (num === 1) {
+      return [start];
+    }
     const step = (stop - start) / (num - 1);
     return Array.from({ length: num }, (_, i) => start + i * step);
   },

package/test/test-utils.ts

@@ -0,0 +1,34 @@
+/**
+ * Test utilities and helper functions
+ */
+
+import { Graph, Node, Edge } from '../src/types';
+
+/**
+ * Create a simple test graph for testing
+ */
+export function createTestGraph(nodes: Node[], edges: Edge[]): Graph {
+  return {
+    nodes: () => nodes,
+    edges: () => edges,
+    adjacency: function() {
+      const adj = new Map<Node, Map<Node, number>>();
+      
+      // Initialize adjacency for all nodes
+      for (const node of nodes) {
+        adj.set(node, new Map());
+      }
+      
+      // Add edges
+      for (const [source, target] of edges) {
+        if (!adj.has(source)) adj.set(source, new Map());
+        if (!adj.has(target)) adj.set(target, new Map());
+        
+        adj.get(source)!.set(target, 1);
+        adj.get(target)!.set(source, 1);
+      }
+      
+      return adj;
+    }
+  };
+}

package/test/utils-graph.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Tests for graph utility functions
+ */
+
+import { describe, it, expect } from 'vitest';
+import { 
+  getNodesFromGraph, 
+  getEdgesFromGraph, 
+  getNodeDegree, 
+  getNeighbors 
+} from '../src/utils/graph';
+import { createTestGraph } from './test-utils';
+
+describe('Graph Utils', () => {
+  describe('getNodesFromGraph', () => {
+    it('should return array as-is when given array of nodes', () => {
+      const nodes = [1, 2, 3, 'a', 'b'];
+      const result = getNodesFromGraph(nodes);
+      expect(result).toEqual(nodes);
+      expect(result).toBe(nodes); // same reference
+    });
+
+    it('should call nodes() method when given graph object', () => {
+      const graph = createTestGraph([1, 2, 3], [[1, 2], [2, 3]]);
+      const result = getNodesFromGraph(graph);
+      expect(result).toEqual([1, 2, 3]);
+    });
+
+    it('should handle empty array', () => {
+      const result = getNodesFromGraph([]);
+      expect(result).toEqual([]);
+    });
+
+    it('should handle empty graph', () => {
+      const graph = createTestGraph([], []);
+      const result = getNodesFromGraph(graph);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('getEdgesFromGraph', () => {
+    it('should return empty array when given array of nodes', () => {
+      const nodes = [1, 2, 3, 'a', 'b'];
+      const result = getEdgesFromGraph(nodes);
+      expect(result).toEqual([]);
+    });
+
+    it('should call edges() method when given graph object', () => {
+      const edges = [[1, 2], [2, 3], [3, 1]];
+      const graph = createTestGraph([1, 2, 3], edges);
+      const result = getEdgesFromGraph(graph);
+      expect(result).toEqual(edges);
+    });
+
+    it('should handle empty array', () => {
+      const result = getEdgesFromGraph([]);
+      expect(result).toEqual([]);
+    });
+
+    it('should handle graph with no edges', () => {
+      const graph = createTestGraph([1, 2, 3], []);
+      const result = getEdgesFromGraph(graph);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe('getNodeDegree', () => {
+    it('should return 0 for graph without edges method', () => {
+      const graph = { nodes: () => [1, 2, 3] } as any;
+      const result = getNodeDegree(graph, 1);
+      expect(result).toBe(0);
+    });
+
+    it('should calculate degree correctly for connected node', () => {
+      const graph = createTestGraph([1, 2, 3, 4], [[1, 2], [1, 3], [1, 4], [2, 3]]);
+      expect(getNodeDegree(graph, 1)).toBe(3); // connected to 2, 3, 4
+      expect(getNodeDegree(graph, 2)).toBe(2); // connected to 1, 3
+      expect(getNodeDegree(graph, 3)).toBe(2); // connected to 1, 2
+      expect(getNodeDegree(graph, 4)).toBe(1); // connected to 1
+    });
+
+    it('should return 0 for isolated node', () => {
+      const graph = createTestGraph([1, 2, 3], [[1, 2]]);
+      expect(getNodeDegree(graph, 3)).toBe(0);
+    });
+
+    it('should handle self-loops correctly', () => {
+      const graph = createTestGraph([1, 2], [[1, 1], [1, 2]]);
+      expect(getNodeDegree(graph, 1)).toBe(2); // self-loop + edge to 2
+    });
+
+    it('should handle node not in graph', () => {
+      const graph = createTestGraph([1, 2, 3], [[1, 2]]);
+      expect(getNodeDegree(graph, 999)).toBe(0);
+    });
+
+    it('should handle empty graph', () => {
+      const graph = createTestGraph([], []);
+      expect(getNodeDegree(graph, 1)).toBe(0);
+    });
+  });
+
+  describe('getNeighbors', () => {
+    it('should return empty array for graph without edges method', () => {
+      const graph = { nodes: () => [1, 2, 3] } as any;
+      const result = getNeighbors(graph, 1);
+      expect(result).toEqual([]);
+    });
+
+    it('should return neighbors correctly', () => {
+      const graph = createTestGraph([1, 2, 3, 4], [[1, 2], [1, 3], [2, 4], [3, 4]]);
+      
+      const neighbors1 = getNeighbors(graph, 1);
+      expect(neighbors1.sort()).toEqual([2, 3]);
+      
+      const neighbors2 = getNeighbors(graph, 2);
+      expect(neighbors2.sort()).toEqual([1, 4]);
+      
+      const neighbors4 = getNeighbors(graph, 4);
+      expect(neighbors4.sort()).toEqual([2, 3]);
+    });
+
+    it('should return empty array for isolated node', () => {
+      const graph = createTestGraph([1, 2, 3], [[1, 2]]);
+      expect(getNeighbors(graph, 3)).toEqual([]);
+    });
+
+    it('should handle self-loops correctly', () => {
+      const graph = createTestGraph([1, 2], [[1, 1], [1, 2]]);
+      const neighbors = getNeighbors(graph, 1);
+      expect(neighbors.sort()).toEqual([1, 2]); // includes self and neighbor
+    });
+
+    it('should not duplicate neighbors in undirected edges', () => {
+      const graph = createTestGraph([1, 2, 3], [[1, 2], [2, 1], [1, 3]]); // bidirectional edge
+      const neighbors = getNeighbors(graph, 1);
+      expect(neighbors.sort()).toEqual([2, 3]); // should not duplicate node 2
+    });
+
+    it('should handle node not in graph', () => {
+      const graph = createTestGraph([1, 2, 3], [[1, 2]]);
+      expect(getNeighbors(graph, 999)).toEqual([]);
+    });
+
+    it('should handle empty graph', () => {
+      const graph = createTestGraph([], []);
+      expect(getNeighbors(graph, 1)).toEqual([]);
+    });
+
+    it('should work with string node IDs', () => {
+      const graph = createTestGraph(['a', 'b', 'c'], [['a', 'b'], ['b', 'c']]);
+      expect(getNeighbors(graph, 'b').sort()).toEqual(['a', 'c']);
+    });
+  });
+});

package/test/utils-index.test.ts

@@ -0,0 +1,77 @@
+/**
+ * Tests for utils index exports
+ */
+
+import { describe, it, expect } from 'vitest';
+
+describe('Utils Index', () => {
+  it('should export all utility functions from numpy', async () => {
+    const { np } = await import('../src/utils/index');
+    expect(np).toBeDefined();
+    expect(typeof np.zeros).toBe('function');
+    expect(typeof np.ones).toBe('function');
+    expect(typeof np.linspace).toBe('function');
+    expect(typeof np.array).toBe('function');
+    expect(typeof np.repeat).toBe('function');
+    expect(typeof np.mean).toBe('function');
+    expect(typeof np.add).toBe('function');
+    expect(typeof np.subtract).toBe('function');
+    expect(typeof np.max).toBe('function');
+    expect(typeof np.min).toBe('function');
+    expect(typeof np.norm).toBe('function');
+  });
+
+  it('should export RandomNumberGenerator class', async () => {
+    const { RandomNumberGenerator } = await import('../src/utils/index');
+    expect(RandomNumberGenerator).toBeDefined();
+    expect(typeof RandomNumberGenerator).toBe('function');
+    
+    const rng = new RandomNumberGenerator(123);
+    expect(typeof rng.rand).toBe('function');
+  });
+
+  it('should export graph utility functions', async () => {
+    const { getNodesFromGraph, getEdgesFromGraph, getNodeDegree, getNeighbors } = await import('../src/utils/index');
+    expect(typeof getNodesFromGraph).toBe('function');
+    expect(typeof getEdgesFromGraph).toBe('function');
+    expect(typeof getNodeDegree).toBe('function');
+    expect(typeof getNeighbors).toBe('function');
+  });
+
+  it('should export parameter processing functions', async () => {
+    const { _processParams } = await import('../src/utils/index');
+    expect(typeof _processParams).toBe('function');
+  });
+
+  it('should export rescale functions', async () => {
+    const { rescaleLayout, rescaleLayoutDict } = await import('../src/utils/index');
+    expect(typeof rescaleLayout).toBe('function');
+    expect(typeof rescaleLayoutDict).toBe('function');
+  });
+
+  it('should allow importing everything with wildcard', async () => {
+    const utils = await import('../src/utils/index');
+    
+    // Check that key exports are available
+    expect(utils.np).toBeDefined();
+    expect(utils.RandomNumberGenerator).toBeDefined();
+    expect(utils.getNodesFromGraph).toBeDefined();
+    expect(utils._processParams).toBeDefined();
+    expect(utils.rescaleLayout).toBeDefined();
+  });
+
+  it('should work with destructured imports', async () => {
+    // Test that the typical usage patterns work
+    const { np, RandomNumberGenerator, getNodesFromGraph } = await import('../src/utils/index');
+    
+    // Quick functional test
+    expect(np.zeros(3)).toEqual([0, 0, 0]);
+    
+    const rng = new RandomNumberGenerator(42);
+    const value = rng.rand() as number;
+    expect(typeof value).toBe('number');
+    
+    const nodes = getNodesFromGraph([1, 2, 3]);
+    expect(nodes).toEqual([1, 2, 3]);
+  });
+});

package/test/utils-numpy.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Tests for NumPy-like utility functions
+ */
+
+import { describe, it, expect } from 'vitest';
+import { np } from '../src/utils/numpy';
+
+describe('NumPy Utils', () => {
+  describe('zeros', () => {
+    it('should create 1D array of zeros', () => {
+      expect(np.zeros(3)).toEqual([0, 0, 0]);
+      expect(np.zeros(0)).toEqual([]);
+      expect(np.zeros(1)).toEqual([0]);
+    });
+
+    it('should create 1D array from single-element array shape', () => {
+      expect(np.zeros([3])).toEqual([0, 0, 0]);
+      expect(np.zeros([0])).toEqual([]);
+    });
+
+    it('should create 2D array of zeros', () => {
+      expect(np.zeros([2, 3])).toEqual([[0, 0, 0], [0, 0, 0]]);
+      expect(np.zeros([3, 2])).toEqual([[0, 0], [0, 0], [0, 0]]);
+      expect(np.zeros([1, 1])).toEqual([[0]]);
+    });
+
+    it('should create 3D array of zeros', () => {
+      const result = np.zeros([2, 2, 2]) as number[][][];
+      expect(result).toEqual([
+        [[0, 0], [0, 0]],
+        [[0, 0], [0, 0]]
+      ]);
+    });
+  });
+
+  describe('ones', () => {
+    it('should create 1D array of ones', () => {
+      expect(np.ones(3)).toEqual([1, 1, 1]);
+      expect(np.ones(0)).toEqual([]);
+      expect(np.ones(1)).toEqual([1]);
+    });
+
+    it('should create 1D array from single-element array shape', () => {
+      expect(np.ones([3])).toEqual([1, 1, 1]);
+      expect(np.ones([0])).toEqual([]);
+    });
+
+    it('should create 2D array of ones', () => {
+      expect(np.ones([2, 3])).toEqual([[1, 1, 1], [1, 1, 1]]);
+      expect(np.ones([3, 2])).toEqual([[1, 1], [1, 1], [1, 1]]);
+    });
+
+    it('should create 3D array of ones', () => {
+      const result = np.ones([2, 1, 2]) as number[][][];
+      expect(result).toEqual([
+        [[1, 1]],
+        [[1, 1]]
+      ]);
+    });
+  });
+
+  describe('linspace', () => {
+    it('should create linearly spaced array', () => {
+      const result = np.linspace(0, 1, 5);
+      expect(result).toHaveLength(5);
+      expect(result[0]).toBe(0);
+      expect(result[4]).toBe(1);
+      expect(result[2]).toBeCloseTo(0.5);
+    });
+
+    it('should handle single point', () => {
+      expect(np.linspace(5, 5, 1)).toEqual([5]);
+    });
+
+    it('should handle reverse range', () => {
+      const result = np.linspace(10, 0, 3);
+      expect(result).toEqual([10, 5, 0]);
+    });
+
+    it('should handle negative numbers', () => {
+      const result = np.linspace(-1, 1, 3);
+      expect(result).toEqual([-1, 0, 1]);
+    });
+  });
+
+  describe('array', () => {
+    it('should copy arrays', () => {
+      const input = [1, 2, 3];
+      const result = np.array(input);
+      expect(result).toEqual(input);
+      expect(result).not.toBe(input); // different reference
+    });
+
+    it('should wrap non-arrays', () => {
+      expect(np.array(5)).toEqual([5]);
+      expect(np.array('hello')).toEqual(['hello']);
+      expect(np.array(null)).toEqual([null]);
+    });
+
+    it('should handle nested arrays', () => {
+      const input = [[1, 2], [3, 4]];
+      const result = np.array(input);
+      expect(result).toEqual(input);
+      expect(result).not.toBe(input);
+    });
+  });
+
+  describe('repeat', () => {
+    it('should repeat single values', () => {
+      expect(np.repeat(5, 3)).toEqual([5, 5, 5]);
+      expect(np.repeat('a', 2)).toEqual(['a', 'a']);
+    });
+
+    it('should repeat arrays', () => {
+      expect(np.repeat([1, 2], 2)).toEqual([1, 2, 1, 2]);
+      expect(np.repeat([1, 2, 3], 3)).toEqual([1, 2, 3, 1, 2, 3, 1, 2, 3]);
+    });
+
+    it('should handle zero repeats', () => {
+      expect(np.repeat(5, 0)).toEqual([]);
+      expect(np.repeat([1, 2], 0)).toEqual([]);
+    });
+
+    it('should handle single repeat', () => {
+      expect(np.repeat([1, 2, 3], 1)).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe('mean', () => {
+    it('should calculate mean of 1D array', () => {
+      expect(np.mean([1, 2, 3, 4, 5])).toBe(3);
+      expect(np.mean([2, 4, 6])).toBe(4);
+      expect(np.mean([10])).toBe(10);
+    });
+
+    it('should calculate mean of 2D array (flatten)', () => {
+      expect(np.mean([[1, 2], [3, 4]])).toBe(2.5);
+      expect(np.mean([[1, 1], [1, 1]])).toBe(1);
+    });
+
+    it('should calculate mean along axis 0 (columns)', () => {
+      const result = np.mean([[1, 2, 3], [4, 5, 6]], 0) as number[];
+      expect(result).toEqual([2.5, 3.5, 4.5]);
+    });
+
+    it('should calculate mean along axis 1 (rows)', () => {
+      const result = np.mean([[1, 2, 3], [4, 5, 6]], 1) as number[];
+      expect(result).toEqual([2, 5]);
+    });
+
+    it('should handle empty arrays', () => {
+      expect(np.mean([])).toBeNaN();
+    });
+
+    it('should handle nested empty arrays', () => {
+      expect(np.mean([[], []])).toBeNaN();
+    });
+  });
+
+  describe('add', () => {
+    it('should add two numbers', () => {
+      expect(np.add(5, 3)).toBe(8);
+      expect(np.add(-2, 7)).toBe(5);
+    });
+
+    it('should add number to array', () => {
+      expect(np.add(2, [1, 2, 3])).toEqual([3, 4, 5]);
+      expect(np.add([1, 2, 3], 10)).toEqual([11, 12, 13]);
+    });
+
+    it('should add two arrays element-wise', () => {
+      expect(np.add([1, 2, 3], [4, 5, 6])).toEqual([5, 7, 9]);
+      expect(np.add([10, 20], [1, 2])).toEqual([11, 22]);
+    });
+
+    it('should handle negative numbers', () => {
+      expect(np.add([-1, -2], [1, 2])).toEqual([0, 0]);
+      expect(np.add(5, [-3, -7])).toEqual([2, -2]);
+    });
+  });
+
+  describe('subtract', () => {
+    it('should subtract two numbers', () => {
+      expect(np.subtract(8, 3)).toBe(5);
+      expect(np.subtract(-2, 7)).toBe(-9);
+    });
+
+    it('should subtract number from array', () => {
+      expect(np.subtract(10, [1, 2, 3])).toEqual([9, 8, 7]);
+      expect(np.subtract([5, 6, 7], 2)).toEqual([3, 4, 5]);
+    });
+
+    it('should subtract two arrays element-wise', () => {
+      expect(np.subtract([5, 7, 9], [1, 2, 3])).toEqual([4, 5, 6]);
+      expect(np.subtract([10, 20], [3, 5])).toEqual([7, 15]);
+    });
+
+    it('should handle negative results', () => {
+      expect(np.subtract([1, 2], [5, 7])).toEqual([-4, -5]);
+    });
+  });
+
+  describe('max', () => {
+    it('should return single number as-is', () => {
+      expect(np.max(42)).toBe(42);
+      expect(np.max(-5)).toBe(-5);
+    });
+
+    it('should find max in 1D array', () => {
+      expect(np.max([1, 5, 3, 9, 2])).toBe(9);
+      expect(np.max([-10, -5, -20])).toBe(-5);
+      expect(np.max([7])).toBe(7);
+    });
+
+    it('should find max in nested arrays', () => {
+      expect(np.max([[1, 2], [3, 4]])).toBe(4);
+      expect(np.max([[10, 5], [2, 8], [1, 12]])).toBe(12);
+    });
+
+    it('should handle deeply nested arrays', () => {
+      expect(np.max([[[1, 2]], [[3, 4]]])).toBe(4);
+    });
+  });
+
+  describe('min', () => {
+    it('should return single number as-is', () => {
+      expect(np.min(42)).toBe(42);
+      expect(np.min(-5)).toBe(-5);
+    });
+
+    it('should find min in 1D array', () => {
+      expect(np.min([1, 5, 3, 9, 2])).toBe(1);
+      expect(np.min([-10, -5, -20])).toBe(-20);
+      expect(np.min([7])).toBe(7);
+    });
+
+    it('should find min in nested arrays', () => {
+      expect(np.min([[1, 2], [3, 4]])).toBe(1);
+      expect(np.min([[10, 5], [2, 8], [1, 12]])).toBe(1);
+    });
+
+    it('should handle deeply nested arrays', () => {
+      expect(np.min([[[1, 2]], [[3, 4]]])).toBe(1);
+    });
+  });
+
+  describe('norm', () => {
+    it('should calculate Euclidean norm', () => {
+      expect(np.norm([3, 4])).toBe(5); // 3-4-5 triangle
+      expect(np.norm([1, 0])).toBe(1);
+      expect(np.norm([0, 0])).toBe(0);
+    });
+
+    it('should handle negative values', () => {
+      expect(np.norm([-3, 4])).toBe(5);
+      expect(np.norm([-3, -4])).toBe(5);
+    });
+
+    it('should handle single element', () => {
+      expect(np.norm([5])).toBe(5);
+      expect(np.norm([-7])).toBe(7);
+    });
+
+    it('should handle higher dimensions', () => {
+      expect(np.norm([1, 2, 2])).toBeCloseTo(3); // sqrt(1 + 4 + 4) = 3
+    });
+
+    it('should handle empty array', () => {
+      expect(np.norm([])).toBe(0);
+    });
+  });
+});

package/test/utils-params.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Tests for parameter processing utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import { _processParams } from '../src/utils/params';
+import { createTestGraph } from './test-utils';
+
+describe('Parameter Utils', () => {
+  describe('_processParams', () => {
+    it('should use default center when null', () => {
+      const graph = createTestGraph([1, 2], [[1, 2]]);
+      const result = _processParams(graph, null, 2);
+      
+      expect(result.G).toBe(graph);
+      expect(result.center).toEqual([0, 0]);
+    });
+
+    it('should use default center when undefined', () => {
+      const nodes = [1, 2, 3];
+      const result = _processParams(nodes, null, 3);
+      
+      expect(result.G).toBe(nodes);
+      expect(result.center).toEqual([0, 0, 0]);
+    });
+
+    it('should preserve provided center', () => {
+      const graph = createTestGraph([1, 2], [[1, 2]]);
+      const center = [5, 10];
+      const result = _processParams(graph, center, 2);
+      
+      expect(result.G).toBe(graph);
+      expect(result.center).toBe(center);
+    });
+
+    it('should work with array of nodes', () => {
+      const nodes = ['a', 'b', 'c'];
+      const center = [1, 2, 3];
+      const result = _processParams(nodes, center, 3);
+      
+      expect(result.G).toBe(nodes);
+      expect(result.center).toBe(center);
+    });
+
+    it('should throw error when center length does not match dimension', () => {
+      const graph = createTestGraph([1, 2], [[1, 2]]);
+      
+      expect(() => {
+        _processParams(graph, [1, 2], 3); // center has 2 elements, dim is 3
+      }).toThrow('length of center coordinates must match dimension of layout');
+    });
+
+    it('should throw error when center is too long', () => {
+      const nodes = [1, 2, 3];
+      
+      expect(() => {
+        _processParams(nodes, [1, 2, 3, 4], 2); // center has 4 elements, dim is 2
+      }).toThrow('length of center coordinates must match dimension of layout');
+    });
+
+    it('should throw error when center is too short', () => {
+      const graph = createTestGraph([1], []);
+      
+      expect(() => {
+        _processParams(graph, [1], 3); // center has 1 element, dim is 3
+      }).toThrow('length of center coordinates must match dimension of layout');
+    });
+
+    it('should work with 1D layouts', () => {
+      const graph = createTestGraph([1, 2], [[1, 2]]);
+      const result = _processParams(graph, [5], 1);
+      
+      expect(result.center).toEqual([5]);
+    });
+
+    it('should work with high-dimensional layouts', () => {
+      const nodes = [1, 2, 3];
+      const center = [1, 2, 3, 4, 5];
+      const result = _processParams(nodes, center, 5);
+      
+      expect(result.center).toBe(center);
+    });
+
+    it('should handle empty center array for 0D (edge case)', () => {
+      const graph = createTestGraph([1], []);
+      const result = _processParams(graph, [], 0);
+      
+      expect(result.center).toEqual([]);
+    });
+
+    it('should create correct default center for various dimensions', () => {
+      const graph = createTestGraph([1], []);
+      
+      expect(_processParams(graph, null, 1).center).toEqual([0]);
+      expect(_processParams(graph, null, 4).center).toEqual([0, 0, 0, 0]);
+      expect(_processParams(graph, null, 0).center).toEqual([]);
+    });
+  });
+});

package/test/utils-random.test.ts

@@ -0,0 +1,229 @@
+/**
+ * Tests for random number generator utilities
+ */
+
+import { describe, it, expect } from 'vitest';
+import { RandomNumberGenerator } from '../src/utils/random';
+
+describe('Random Utils', () => {
+  describe('RandomNumberGenerator', () => {
+    describe('constructor', () => {
+      it('should use provided seed', () => {
+        const rng = new RandomNumberGenerator(12345);
+        expect(rng['seed']).toBe(12345);
+      });
+
+      it('should generate random seed when none provided', () => {
+        const rng1 = new RandomNumberGenerator();
+        const rng2 = new RandomNumberGenerator();
+        // Seeds should be different (very high probability)
+        expect(rng1['seed']).not.toBe(rng2['seed']);
+      });
+
+      it('should initialize state properly', () => {
+        const rng = new RandomNumberGenerator(42);
+        expect(rng['_state']).toBe(42);
+      });
+
+      it('should handle large seeds', () => {
+        const largeSeed = 999999999;
+        const rng = new RandomNumberGenerator(largeSeed);
+        expect(rng['seed']).toBe(largeSeed);
+      });
+    });
+
+    describe('_next', () => {
+      it('should generate values between 0 and 1', () => {
+        const rng = new RandomNumberGenerator(123);
+        for (let i = 0; i < 100; i++) {
+          const value = rng['_next']();
+          expect(value).toBeGreaterThanOrEqual(0);
+          expect(value).toBeLessThan(1);
+        }
+      });
+
+      it('should be deterministic for same seed', () => {
+        const rng1 = new RandomNumberGenerator(456);
+        const rng2 = new RandomNumberGenerator(456);
+        
+        const sequence1 = Array.from({ length: 10 }, () => rng1['_next']());
+        const sequence2 = Array.from({ length: 10 }, () => rng2['_next']());
+        
+        expect(sequence1).toEqual(sequence2);
+      });
+
+      it('should produce different sequences for different seeds', () => {
+        const rng1 = new RandomNumberGenerator(111);
+        const rng2 = new RandomNumberGenerator(222);
+        
+        const sequence1 = Array.from({ length: 10 }, () => rng1['_next']());
+        const sequence2 = Array.from({ length: 10 }, () => rng2['_next']());
+        
+        expect(sequence1).not.toEqual(sequence2);
+      });
+    });
+
+    describe('rand', () => {
+      it('should return single number when no shape provided', () => {
+        const rng = new RandomNumberGenerator(789);
+        const value = rng.rand() as number;
+        expect(typeof value).toBe('number');
+        expect(value).toBeGreaterThanOrEqual(0);
+        expect(value).toBeLessThan(1);
+      });
+
+      it('should return single number when null shape provided', () => {
+        const rng = new RandomNumberGenerator(789);
+        const value = rng.rand(null) as number;
+        expect(typeof value).toBe('number');
+        expect(value).toBeGreaterThanOrEqual(0);
+        expect(value).toBeLessThan(1);
+      });
+
+      it('should return 1D array when given number shape', () => {
+        const rng = new RandomNumberGenerator(101112);
+        const values = rng.rand(5) as number[];
+        expect(Array.isArray(values)).toBe(true);
+        expect(values).toHaveLength(5);
+        values.forEach(v => {
+          expect(v).toBeGreaterThanOrEqual(0);
+          expect(v).toBeLessThan(1);
+        });
+      });
+
+      it('should return empty array for zero length', () => {
+        const rng = new RandomNumberGenerator(123);
+        expect(rng.rand(0)).toEqual([]);
+      });
+
+      it('should return 1D array when given single-element array shape', () => {
+        const rng = new RandomNumberGenerator(131415);
+        const values = rng.rand([4]) as number[];
+        expect(Array.isArray(values)).toBe(true);
+        expect(values).toHaveLength(4);
+        values.forEach(v => {
+          expect(v).toBeGreaterThanOrEqual(0);
+          expect(v).toBeLessThan(1);
+        });
+      });
+
+      it('should return 2D array when given 2D shape', () => {
+        const rng = new RandomNumberGenerator(161718);
+        const values = rng.rand([2, 3]) as number[][];
+        expect(Array.isArray(values)).toBe(true);
+        expect(values).toHaveLength(2);
+        values.forEach(row => {
+          expect(Array.isArray(row)).toBe(true);
+          expect(row).toHaveLength(3);
+          row.forEach(v => {
+            expect(v).toBeGreaterThanOrEqual(0);
+            expect(v).toBeLessThan(1);
+          });
+        });
+      });
+
+      it('should return 3D array when given 3D shape', () => {
+        const rng = new RandomNumberGenerator(192021);
+        const values = rng.rand([2, 2, 2]) as number[][][];
+        expect(Array.isArray(values)).toBe(true);
+        expect(values).toHaveLength(2);
+        values.forEach(plane => {
+          expect(Array.isArray(plane)).toBe(true);
+          expect(plane).toHaveLength(2);
+          plane.forEach(row => {
+            expect(Array.isArray(row)).toBe(true);
+            expect(row).toHaveLength(2);
+            row.forEach(v => {
+              expect(v).toBeGreaterThanOrEqual(0);
+              expect(v).toBeLessThan(1);
+            });
+          });
+        });
+      });
+
+      it('should handle edge cases with zeros in shape', () => {
+        const rng = new RandomNumberGenerator(222324);
+        expect(rng.rand([0])).toEqual([]);
+        expect(rng.rand([3, 0])).toEqual([[], [], []]);
+        expect(rng.rand([0, 3])).toEqual([]);
+      });
+
+      it('should be deterministic across calls with same seed', () => {
+        const rng1 = new RandomNumberGenerator(252627);
+        const rng2 = new RandomNumberGenerator(252627);
+        
+        const values1 = rng1.rand([2, 3]) as number[][];
+        const values2 = rng2.rand([2, 3]) as number[][];
+        
+        expect(values1).toEqual(values2);
+      });
+
+      it('should handle single element arrays', () => {
+        const rng = new RandomNumberGenerator(282930);
+        const value1D = rng.rand(1) as number[];
+        const value2D = rng.rand([1, 1]) as number[][];
+        
+        expect(value1D).toHaveLength(1);
+        expect(value2D).toHaveLength(1);
+        expect(value2D[0]).toHaveLength(1);
+      });
+
+      it('should produce different values in sequence', () => {
+        const rng = new RandomNumberGenerator(313233);
+        const values = rng.rand(10) as number[];
+        
+        // Check that not all values are the same (very high probability)
+        const uniqueValues = new Set(values);
+        expect(uniqueValues.size).toBeGreaterThan(1);
+      });
+    });
+
+    describe('integration tests', () => {
+      it('should work correctly for layout algorithm use cases', () => {
+        const rng = new RandomNumberGenerator(424344);
+        
+        // Test typical usage patterns in layout algorithms
+        const initialPositions = rng.rand([5, 2]) as number[][];
+        expect(initialPositions).toHaveLength(5);
+        initialPositions.forEach(pos => {
+          expect(pos).toHaveLength(2);
+          expect(pos[0]).toBeGreaterThanOrEqual(0);
+          expect(pos[0]).toBeLessThan(1);
+          expect(pos[1]).toBeGreaterThanOrEqual(0);
+          expect(pos[1]).toBeLessThan(1);
+        });
+      });
+
+      it('should maintain quality of randomness over many calls', () => {
+        const rng = new RandomNumberGenerator(454647);
+        const values: number[] = [];
+        
+        // Generate many values
+        for (let i = 0; i < 1000; i++) {
+          values.push(rng.rand() as number);
+        }
+        
+        // Basic statistical tests
+        const mean = values.reduce((a, b) => a + b) / values.length;
+        expect(mean).toBeGreaterThan(0.4); // Should be around 0.5
+        expect(mean).toBeLessThan(0.6);
+        
+        // Check distribution across range
+        const firstQuartile = values.filter(v => v < 0.25).length;
+        const secondQuartile = values.filter(v => v >= 0.25 && v < 0.5).length;
+        const thirdQuartile = values.filter(v => v >= 0.5 && v < 0.75).length;
+        const fourthQuartile = values.filter(v => v >= 0.75).length;
+        
+        // Each quartile should have roughly 1/4 of values (allow some variance)
+        expect(firstQuartile).toBeGreaterThan(200);
+        expect(firstQuartile).toBeLessThan(300);
+        expect(secondQuartile).toBeGreaterThan(200);
+        expect(secondQuartile).toBeLessThan(300);
+        expect(thirdQuartile).toBeGreaterThan(200);
+        expect(thirdQuartile).toBeLessThan(300);
+        expect(fourthQuartile).toBeGreaterThan(200);
+        expect(fourthQuartile).toBeLessThan(300);
+      });
+    });
+  });
+});