@pawells/math-extended 1.0.1

package/build/random.spec.js

@@ -0,0 +1,267 @@
+import { RandomInt, RandomFloat, RandomChoice, RandomSample, RandomShuffle, RandomBool, RandomNormal, } from './random.ts';
+describe('Math > Random ', () => {
+    describe('RandomInt', () => {
+        test('Generate a Random Integer within a Positive Range', () => {
+            const min = 1;
+            const max = 10;
+            const result = RandomInt(min, max);
+            expect(result).toBeGreaterThanOrEqual(min);
+            expect(result).toBeLessThanOrEqual(max);
+            expect(Number.isInteger(result)).toBe(true);
+        });
+        test('Generate a Random Integer within a Negative Range', () => {
+            const min = -10;
+            const max = -1;
+            const result = RandomInt(min, max);
+            expect(result).toBeGreaterThanOrEqual(min);
+            expect(result).toBeLessThanOrEqual(max);
+            expect(Number.isInteger(result)).toBe(true);
+        });
+        test('If the minimum value and maximum value are the same, return the minimum value.', () => {
+            const min = 5;
+            const max = 5;
+            const result = RandomInt(min, max);
+            expect(result).toBe(min);
+        });
+        test('If the minimum value is greater than the maximum value, return NaN.', () => {
+            const min = 10;
+            const max = 5;
+            const result = RandomInt(min, max);
+            expect(result).toBeNaN();
+        });
+        test('Should include both min and max values over multiple runs', () => {
+            const min = 1;
+            const max = 3;
+            const results = new Set();
+            // Run enough times to likely hit all values
+            for (let i = 0; i < 100; i++) {
+                results.add(RandomInt(min, max));
+            }
+            expect(results.has(min)).toBe(true);
+            expect(results.has(max)).toBe(true);
+        });
+    });
+    describe('RandomFloat', () => {
+        test('Generate a Random Float within Range', () => {
+            const min = 0;
+            const max = 1;
+            const result = RandomFloat(min, max);
+            expect(result).toBeGreaterThanOrEqual(min);
+            expect(result).toBeLessThan(max);
+            expect(typeof result).toBe('number');
+        });
+        test('Generate a Random Float within Negative Range', () => {
+            const min = -5.5;
+            const max = -1.1;
+            const result = RandomFloat(min, max);
+            expect(result).toBeGreaterThanOrEqual(min);
+            expect(result).toBeLessThan(max);
+        });
+        test('If minimum equals maximum, return NaN', () => {
+            const min = 5.5;
+            const max = 5.5;
+            const result = RandomFloat(min, max);
+            expect(result).toBeNaN();
+        });
+        test('If minimum is greater than maximum, return NaN', () => {
+            const min = 10.5;
+            const max = 5.5;
+            const result = RandomFloat(min, max);
+            expect(result).toBeNaN();
+        });
+        test('Should generate different values over multiple runs', () => {
+            const results = new Set();
+            for (let i = 0; i < 10; i++) {
+                results.add(RandomFloat(0, 1));
+            }
+            // Should have generated different values (very unlikely to get duplicates)
+            expect(results.size).toBeGreaterThan(1);
+        });
+    });
+    describe('RandomChoice', () => {
+        test('Choose from array of numbers', () => {
+            const array = [1, 2, 3, 4, 5];
+            const result = RandomChoice(array);
+            expect(array).toContain(result);
+        });
+        test('Choose from array of strings', () => {
+            const array = ['red', 'green', 'blue'];
+            const result = RandomChoice(array);
+            expect(array).toContain(result);
+        });
+        test('Return undefined for empty array', () => {
+            const array = [];
+            const result = RandomChoice(array);
+            expect(result).toBeUndefined();
+        });
+        test('Return the only element for single-element array', () => {
+            const array = [42];
+            const result = RandomChoice(array);
+            expect(result).toBe(42);
+        });
+        test('Should eventually choose all elements over multiple runs', () => {
+            const array = [1, 2, 3];
+            const results = new Set();
+            for (let i = 0; i < 50; i++) {
+                const choice = RandomChoice(array);
+                if (choice !== undefined) {
+                    results.add(choice);
+                }
+            }
+            expect(results.size).toBe(3);
+        });
+    });
+    describe('RandomSample', () => {
+        test('Sample multiple elements without replacement', () => {
+            const array = [1, 2, 3, 4, 5];
+            const result = RandomSample(array, 3);
+            expect(result).toHaveLength(3);
+            expect(new Set(result).size).toBe(3); // All unique
+            result.forEach((item) => {
+                expect(array).toContain(item);
+            });
+        });
+        test('Sample all elements', () => {
+            const array = [1, 2, 3];
+            const result = RandomSample(array, 3);
+            expect(result).toHaveLength(3);
+            expect(new Set(result).size).toBe(3);
+        });
+        test('Return empty array for invalid inputs', () => {
+            const array = [1, 2, 3];
+            expect(RandomSample(array, 0)).toEqual([]);
+            expect(RandomSample(array, -1)).toEqual([]);
+            expect(RandomSample(array, 5)).toEqual([]); // More than available
+            expect(RandomSample([], 1)).toEqual([]);
+        });
+        test('Sample single element', () => {
+            const array = [1, 2, 3, 4, 5];
+            const result = RandomSample(array, 1);
+            expect(result).toHaveLength(1);
+            expect(array).toContain(result[0]);
+        });
+    });
+    describe('RandomShuffle', () => {
+        test('Shuffle modifies original array by default', () => {
+            const original = [1, 2, 3, 4, 5];
+            const copy = [...original];
+            const result = RandomShuffle(original);
+            expect(result).toBe(original);
+            expect(result).toHaveLength(copy.length);
+            // Should contain all original elements
+            copy.forEach((item) => {
+                expect(result).toContain(item);
+            });
+        });
+        test('Shuffle with clone=true does not modify original array', () => {
+            const original = [1, 2, 3, 4, 5];
+            const copy = [...original];
+            const result = RandomShuffle(original, true);
+            expect(result).not.toBe(original);
+            expect(original).toEqual(copy);
+            expect(result).toHaveLength(original.length);
+            // Should contain all original elements
+            original.forEach((item) => {
+                expect(result).toContain(item);
+            });
+        });
+        test('Shuffle with clone=false modifies original array', () => {
+            const original = [1, 2, 3, 4, 5];
+            const copy = [...original];
+            const result = RandomShuffle(original, false);
+            expect(result).toBe(original);
+            expect(result).toHaveLength(copy.length);
+            // Should contain all original elements
+            copy.forEach((item) => {
+                expect(result).toContain(item);
+            });
+        });
+        test('Shuffle empty array', () => {
+            const array = [];
+            const result = RandomShuffle(array);
+            expect(result).toEqual([]);
+        });
+        test('Shuffle single element array', () => {
+            const array = [42];
+            const result = RandomShuffle(array);
+            expect(result).toEqual([42]);
+        });
+        test('Should eventually produce different arrangements', () => {
+            const arrangements = new Set();
+            for (let i = 0; i < 20; i++) {
+                const array = [1, 2, 3];
+                RandomShuffle(array);
+                arrangements.add(JSON.stringify(array));
+            }
+            // Should have generated at least 2 different arrangements
+            expect(arrangements.size).toBeGreaterThan(1);
+        });
+    });
+    describe('RandomBool', () => {
+        test('Generate random boolean with default probability', () => {
+            const result = RandomBool();
+            expect(typeof result).toBe('boolean');
+        });
+        test('Generate random boolean with custom probability', () => {
+            // Test with very high probability
+            let trueCount = 0;
+            for (let i = 0; i < 100; i++) {
+                if (RandomBool(0.9)) {
+                    trueCount++;
+                }
+            }
+            // Should be mostly true (allowing some variance)
+            expect(trueCount).toBeGreaterThan(70);
+            // Test with very low probability
+            let falseCount = 0;
+            for (let i = 0; i < 100; i++) {
+                if (!RandomBool(0.1)) {
+                    falseCount++;
+                }
+            }
+            // Should be mostly false (allowing some variance)
+            expect(falseCount).toBeGreaterThan(70);
+        });
+        test('Return false for invalid probabilities', () => {
+            expect(RandomBool(-0.1)).toBe(false);
+            expect(RandomBool(1.1)).toBe(false);
+        });
+        test('Return true for probability 1.0', () => {
+            for (let i = 0; i < 10; i++) {
+                expect(RandomBool(1.0)).toBe(true);
+            }
+        });
+        test('Return false for probability 0.0', () => {
+            for (let i = 0; i < 10; i++) {
+                expect(RandomBool(0.0)).toBe(false);
+            }
+        });
+    });
+    describe('RandomNormal', () => {
+        test('Generate random normal distribution with default parameters', () => {
+            const results = [];
+            for (let i = 0; i < 1000; i++) {
+                results.push(RandomNormal());
+            }
+            const mean = results.reduce((sum, val) => sum + val, 0) / results.length;
+            const variance = results.reduce((sum, val) => sum + Math.pow(val - mean, 2), 0) / results.length;
+            // Should be approximately standard normal (mean ≈ 0, variance ≈ 1)
+            expect(Math.abs(mean)).toBeLessThan(0.1);
+            expect(Math.abs(variance - 1)).toBeLessThan(0.2);
+        });
+        test('Generate random normal distribution with custom parameters', () => {
+            const targetMean = 100;
+            const targetStd = 15;
+            const results = [];
+            for (let i = 0; i < 1000; i++) {
+                results.push(RandomNormal(targetMean, targetStd));
+            }
+            const mean = results.reduce((sum, val) => sum + val, 0) / results.length;
+            const variance = results.reduce((sum, val) => sum + Math.pow(val - mean, 2), 0) / results.length;
+            const stdDev = Math.sqrt(variance);
+            // Should be approximately the target distribution			expect(Math.abs(mean - targetMean)).toBeLessThan(2);
+            expect(Math.abs(stdDev - targetStd)).toBeLessThan(2);
+        });
+    });
+});
+//# sourceMappingURL=random.spec.js.map

package/build/random.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"random.spec.js","sourceRoot":"","sources":["../src/random.spec.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,SAAS,EACT,WAAW,EACX,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,UAAU,EACV,YAAY,GACZ,MAAM,aAAa,CAAC;AAErB,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC/B,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;QAC1B,IAAI,CAAC,mDAAmD,EAAE,GAAG,EAAE;YAC9D,MAAM,GAAG,GAAG,CAAC,CAAC;YACd,MAAM,GAAG,GAAG,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;YAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;YACxC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,mDAAmD,EAAE,GAAG,EAAE;YAC9D,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC;YAChB,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC;YACf,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;YAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;YACxC,MAAM,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,gFAAgF,EAAE,GAAG,EAAE;YAC3F,MAAM,GAAG,GAAG,CAAC,CAAC;YACd,MAAM,GAAG,GAAG,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,qEAAqE,EAAE,GAAG,EAAE;YAChF,MAAM,GAAG,GAAG,EAAE,CAAC;YACf,MAAM,GAAG,GAAG,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,2DAA2D,EAAE,GAAG,EAAE;YACtE,MAAM,GAAG,GAAG,CAAC,CAAC;YACd,MAAM,GAAG,GAAG,CAAC,CAAC;YACd,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;YAElC,4CAA4C;YAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC9B,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;YAClC,CAAC;YAED,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,aAAa,EAAE,GAAG,EAAE;QAC5B,IAAI,CAAC,sCAAsC,EAAE,GAAG,EAAE;YACjD,MAAM,GAAG,GAAG,CAAC,CAAC;YACd,MAAM,GAAG,GAAG,CAAC,CAAC;YACd,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACrC,MAAM,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;YAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;YACjC,MAAM,CAAC,OAAO,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,+CAA+C,EAAE,GAAG,EAAE;YAC1D,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC;YACjB,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC;YACjB,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACrC,MAAM,CAAC,MAAM,CAAC,CAAC,sBAAsB,CAAC,GAAG,CAAC,CAAC;YAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,uCAAuC,EAAE,GAAG,EAAE;YAClD,MAAM,GAAG,GAAG,GAAG,CAAC;YAChB,MAAM,GAAG,GAAG,GAAG,CAAC;YAChB,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACrC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,gDAAgD,EAAE,GAAG,EAAE;YAC3D,MAAM,GAAG,GAAG,IAAI,CAAC;YACjB,MAAM,GAAG,GAAG,GAAG,CAAC;YAChB,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YACrC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;QAC1B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,qDAAqD,EAAE,GAAG,EAAE;YAChE,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;YAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7B,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAChC,CAAC;YAED,2EAA2E;YAC3E,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;QAC7B,IAAI,CAAC,8BAA8B,EAAE,GAAG,EAAE;YACzC,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAC9B,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,8BAA8B,EAAE,GAAG,EAAE;YACzC,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;YACvC,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QACjC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,kCAAkC,EAAE,GAAG,EAAE;YAC7C,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,CAAC;QAChC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;YAC7D,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;YACnB,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzB,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,0DAA0D,EAAE,GAAG,EAAE;YACrE,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACxB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;YAElC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7B,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;gBACnC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;oBAC1B,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACrB,CAAC;YACF,CAAC;YAED,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;QAC7B,IAAI,CAAC,8CAA8C,EAAE,GAAG,EAAE;YACzD,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAC9B,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACtC,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YAC/B,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa;YACnD,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACvB,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,qBAAqB,EAAE,GAAG,EAAE;YAChC,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACxB,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACtC,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YAC/B,MAAM,CAAC,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QACtC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,uCAAuC,EAAE,GAAG,EAAE;YAClD,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACxB,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC3C,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC5C,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,sBAAsB;YAClE,MAAM,CAAC,YAAY,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACzC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,uBAAuB,EAAE,GAAG,EAAE;YAClC,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YAC9B,MAAM,MAAM,GAAG,YAAY,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;YACtC,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;YAC/B,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,QAAQ,CAAC,eAAe,EAAE,GAAG,EAAE;QAC9B,IAAI,CAAC,4CAA4C,EAAE,GAAG,EAAE;YACvD,MAAM,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACjC,MAAM,IAAI,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;YAC3B,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;YACvC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC9B,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAEzC,uCAAuC;YACvC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACrB,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,wDAAwD,EAAE,GAAG,EAAE;YACnE,MAAM,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACjC,MAAM,IAAI,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;YAC3B,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;YAC7C,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAClC,MAAM,CAAC,QAAQ,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC/B,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YAE7C,uCAAuC;YACvC,QAAQ,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACzB,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;YAC7D,MAAM,QAAQ,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;YACjC,MAAM,IAAI,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;YAC3B,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;YAC9C,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YAC9B,MAAM,CAAC,MAAM,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAEzC,uCAAuC;YACvC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE;gBACrB,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAChC,CAAC,CAAC,CAAC;QACJ,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,qBAAqB,EAAE,GAAG,EAAE;YAChC,MAAM,KAAK,GAAa,EAAE,CAAC;YAC3B,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;YACpC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,8BAA8B,EAAE,GAAG,EAAE;YACzC,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC,CAAC;YACnB,MAAM,MAAM,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;YACpC,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QAC9B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;YAC7D,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;YAEvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7B,MAAM,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;gBACxB,aAAa,CAAC,KAAK,CAAC,CAAC;gBACrB,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;YACzC,CAAC;YAED,0DAA0D;YAC1D,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;QAC9C,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;QAC3B,IAAI,CAAC,kDAAkD,EAAE,GAAG,EAAE;YAC7D,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;YAC5B,MAAM,CAAC,OAAO,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACvC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,iDAAiD,EAAE,GAAG,EAAE;YAC5D,kCAAkC;YAClC,IAAI,SAAS,GAAG,CAAC,CAAC;YAElB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC9B,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACrB,SAAS,EAAE,CAAC;gBACb,CAAC;YACF,CAAC;YACD,iDAAiD;YACjD,MAAM,CAAC,SAAS,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;YAEtC,iCAAiC;YACjC,IAAI,UAAU,GAAG,CAAC,CAAC;YAEnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC9B,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;oBACtB,UAAU,EAAE,CAAC;gBACd,CAAC;YACF,CAAC;YACD,kDAAkD;YAClD,MAAM,CAAC,UAAU,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;QACxC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,wCAAwC,EAAE,GAAG,EAAE;YACnD,MAAM,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrC,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrC,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,iCAAiC,EAAE,GAAG,EAAE;YAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7B,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpC,CAAC;QACF,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,kCAAkC,EAAE,GAAG,EAAE;YAC7C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC7B,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACrC,CAAC;QACF,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,QAAQ,CAAC,cAAc,EAAE,GAAG,EAAE;QAC7B,IAAI,CAAC,6DAA6D,EAAE,GAAG,EAAE;YACxE,MAAM,OAAO,GAAa,EAAE,CAAC;YAE7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC/B,OAAO,CAAC,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;YAC9B,CAAC;YAED,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;YACzE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;YACjG,mEAAmE;YACnE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;YACzC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,4DAA4D,EAAE,GAAG,EAAE;YACvE,MAAM,UAAU,GAAG,GAAG,CAAC;YACvB,MAAM,SAAS,GAAG,EAAE,CAAC;YACrB,MAAM,OAAO,GAAa,EAAE,CAAC;YAE7B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC/B,OAAO,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC;YACnD,CAAC;YAED,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;YACzE,MAAM,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;YACjG,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACnC,yGAAyG;YACzG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;QACtD,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/build/vectors/asserts.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Vector assertion utilities for type safety and runtime validation.
+ * Provides comprehensive validation functions to ensure vector data integrity
+ * and catch errors early in mathematical operations.
+ */
+import { IAssertException, IAssertNumberArgs, IAssertArrayArgs } from '@pawells/typescript-common';
+import { TVector, TVector2, TVector3, TVector4 } from './types.js';
+/**
+ * Configuration options for vector assertion functions.
+ * Allows flexible validation of vector properties and constraints.
+ */
+export type TAssertVectorArgs = IAssertNumberArgs & IAssertArrayArgs;
+/**
+ * Extended configuration for validating multiple vectors.
+ * Includes all single vector options plus multi-vector constraints.
+ */
+interface IAssertVectorsArgs extends TAssertVectorArgs {
+    /**
+     * Minimum vector size allowed.
+     * If specified, vectors must have at least this many components.
+     */
+    minSize?: number;
+    /**
+     * Whether all vectors must have the same size.
+     * Default: true when using individual arguments, configurable when using array syntax.
+     */
+    sameSize?: boolean;
+    /**
+     * Whether all vector elements must be finite numbers.
+     * If true, validates that each element is not Infinity or -Infinity.
+     */
+    finite?: boolean;
+}
+/**
+ * Extended exception interface for vector-specific error information.
+ * Provides additional context about which vector component caused the error.
+ */
+interface IAssertVectorException extends IAssertException {
+    /**
+     * Index of the vector component that caused the validation failure.
+     * Useful for debugging which specific element is invalid.
+     */
+    index?: number;
+}
+type TAssertVectorValueArgs = IAssertNumberArgs;
+/**
+ * Specialized error class for vector-related operations and validations.
+ * Thrown when vector assertions fail or vector operations encounter invalid data.
+ *
+ * @example
+ * try {
+ *   AssertVector("not a vector");
+ * } catch (error) {
+ *   if (error instanceof VectorError) {
+ *     console.log("Vector validation failed:", error.message);
+ *   }
+ * }
+ */
+export declare class VectorError extends Error {
+    /**
+     * Creates a new VectorError instance.
+     *
+     * @param message - Optional error message describing the validation failure
+     */
+    constructor(message?: string);
+}
+/**
+ * Validates that an unknown value is a valid vector (array of numbers).
+ *
+ * Performs comprehensive validation including array structure, size constraints,
+ * and element-level number validation for every component.
+ *
+ * @param vector - The value to validate as a vector
+ * @param args - Validation constraints (size, minSize, maxSize, finite, integer, gt, gte, lt, lte, eq)
+ * @param exception - Custom exception details if validation fails
+ * @throws {VectorError} If the value is not a valid vector meeting all constraints
+ *
+ * @example
+ * ```typescript
+ * // Basic validation — passes silently for a valid vector
+ * AssertVector([1, 2, 3]);
+ *
+ * // Validate with size constraint
+ * AssertVector([1, 2], { size: 2 });
+ *
+ * // Throws VectorError for non-array input
+ * AssertVector("not a vector"); // throws VectorError
+ * ```
+ */
+export declare function AssertVector(vector: unknown, args?: TAssertVectorArgs, exception?: IAssertVectorException): asserts vector is TVector;
+/**
+ * Validates that an unknown value is a valid 2D vector (exactly 2 numeric components).
+ *
+ * @param vector - The value to validate as a 2D vector
+ * @param exception - Custom exception details if validation fails
+ * @throws {VectorError} If the value is not a 2-component vector
+ *
+ * @example
+ * ```typescript
+ * AssertVector2([1, 2]);       // passes
+ * AssertVector2([1, 2, 3]);    // throws — too many components
+ * AssertVector2("not a vec");  // throws
+ * ```
+ */
+export declare function AssertVector2(vector: unknown, exception?: IAssertVectorException): asserts vector is TVector2;
+/**
+ * Validates that an unknown value is a valid 3D vector (exactly 3 numeric components).
+ *
+ * @param vector - The value to validate as a 3D vector
+ * @param exception - Custom exception details if validation fails
+ * @throws {VectorError} If the value is not a 3-component vector
+ *
+ * @example
+ * ```typescript
+ * AssertVector3([1, 2, 3]);    // passes
+ * AssertVector3([1, 2]);       // throws — too few components
+ * AssertVector3(null);         // throws
+ * ```
+ */
+export declare function AssertVector3(vector: unknown, exception?: IAssertVectorException): asserts vector is TVector3;
+/**
+ * Validates that an unknown value is a valid 4D vector (exactly 4 numeric components).
+ *
+ * @param vector - The value to validate as a 4D vector
+ * @param exception - Custom exception details if validation fails
+ * @throws {VectorError} If the value is not a 4-component vector
+ *
+ * @example
+ * ```typescript
+ * AssertVector4([1, 2, 3, 4]); // passes
+ * AssertVector4([1, 2, 3]);    // throws — too few components
+ * AssertVector4(undefined);    // throws
+ * ```
+ */
+export declare function AssertVector4(vector: unknown, exception?: IAssertVectorException): asserts vector is TVector4;
+/**
+ * Validates that an unknown value is a valid vector element (a finite, non-NaN number).
+ *
+ * Supports optional numeric constraints such as range bounds, integer enforcement,
+ * and finiteness checks. Throws `VectorError` with the component index when available.
+ *
+ * @param value - The value to validate as a vector element
+ * @param args - Numeric constraints (finite, integer, gt, gte, lt, lte, eq)
+ * @param exception - Custom exception details, optionally including a component `index`
+ * @throws {VectorError} If the value is not a valid number or violates any constraint
+ *
+ * @example
+ * ```typescript
+ * AssertVectorValue(3.14);                       // passes
+ * AssertVectorValue(3.14, { finite: true });      // passes
+ * AssertVectorValue(Infinity, { finite: true });  // throws
+ * AssertVectorValue(NaN);                         // throws
+ * AssertVectorValue(5, { gte: 0, lte: 10 });     // passes
+ * ```
+ */
+export declare function AssertVectorValue(value: unknown, args?: TAssertVectorValueArgs, exception?: IAssertVectorException): asserts value is number;
+/**
+ * Validates an array of vectors, ensuring each vector is valid and optionally
+ * enforcing that all vectors share the same size.
+ *
+ * @param vectors - The array of vectors to validate (must be non-empty)
+ * @param args - Validation constraints applied to each vector; set `sameSize: true`
+ *   to require all vectors to have identical lengths
+ * @param exception - Custom exception details if validation fails
+ * @throws {VectorError} If the array is empty, any vector is invalid, or sizes
+ *   differ when `sameSize` is `true`
+ *
+ * @example
+ * ```typescript
+ * // Validate an array of 3D vectors
+ * AssertVectors([[1, 2, 3], [4, 5, 6]]);
+ *
+ * // Require all vectors to share the same length
+ * AssertVectors([[1, 2], [3, 4]], { sameSize: true });
+ *
+ * // Throws because vectors have different sizes
+ * AssertVectors([[1, 2], [1, 2, 3]], { sameSize: true }); // throws
+ * ```
+ */
+export declare function AssertVectors(vectors: unknown[], args?: IAssertVectorsArgs, exception?: IAssertVectorException): void;
+export {};
+//# sourceMappingURL=asserts.d.ts.map

package/build/vectors/asserts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asserts.d.ts","sourceRoot":"","sources":["../../src/vectors/asserts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,gBAAgB,EAAuC,MAAM,4BAA4B,CAAC;AACxI,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEnE;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,GAAG,gBAAgB,CAAC;AAErE;;;GAGG;AACH,UAAU,kBAAmB,SAAQ,iBAAiB;IACrD;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AACD;;;GAGG;AACH,UAAU,sBAAuB,SAAQ,gBAAgB;IACxD;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CACf;AACD,KAAK,sBAAsB,GAAG,iBAAiB,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,qBAAa,WAAY,SAAQ,KAAK;IACrC;;;;OAIG;gBACS,OAAO,CAAC,EAAE,MAAM;CAK5B;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,GAAE,iBAAsB,EAAE,SAAS,GAAE,sBAA2B,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CA6C7I;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,GAAE,sBAA2B,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAEjH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,GAAE,sBAA2B,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAEjH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,OAAO,EAAE,SAAS,GAAE,sBAA2B,GAAG,OAAO,CAAC,MAAM,IAAI,QAAQ,CAEjH;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,sBAA2B,EAAE,SAAS,GAAE,sBAA2B,GAAG,OAAO,CAAC,KAAK,IAAI,MAAM,CA8DpJ;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,CAAC,EAAE,kBAAkB,EAAE,SAAS,CAAC,EAAE,sBAAsB,GAAG,IAAI,CA6CrH"}