feat: add modulo function (#255)

workspace/mauss/src/math/index.spec.ts

@@ -4,6 +4,7 @@ import * as math from './index.js';
 
 const suites = {
 	'average/': suite('math/average'),
+	'modulo/': suite('math/modulo'),
 };
 
 suites['average/']('average base cases', () => {
@@ -14,4 +15,19 @@ suites['average/']('average numbers', () => {
 	assert.equal(math.average([10, 20, 30, 40, 50]), 30);
 });
 
+suites['modulo/']('modulo numbers', () => {
+	assert.equal(math.modulo(10, 0), NaN);
+
+	assert.equal(math.modulo(10, 3), 1);
+	assert.equal(math.modulo(-10, 3), 2);
+	assert.equal(math.modulo(10, -3), -2);
+	assert.equal(math.modulo(-10, -3), -1);
+	assert.equal(math.modulo(10, 5), 0);
+	assert.equal(math.modulo(-10, 5), 0);
+	assert.equal(math.modulo(10, -5), 0);
+	assert.equal(math.modulo(-10, -5), 0);
+	assert.equal(math.modulo(10, 1), 0);
+	assert.equal(math.modulo(10, 10), 0);
+});
+
 Object.values(suites).forEach((v) => v.run());

workspace/mauss/src/math/index.ts

@@ -20,3 +20,19 @@ export function average(numbers: number[]): number {
 export function clamp(min: number, max: number) {
 	return (value: number) => Math.max(min, Math.min(value, max));
 }
+
+/**
+ * The `%` is a remainder operator, this function computes the modulo operation and ensures a non-negative number for a non-negative divisor.
+ *
+ * @example
+ * ```javascript
+ * // returns 1
+ * modulo(5, 2);
+ *
+ * // returns 1
+ * modulo(-3, 2);
+ * ```
+ */
+export function modulo(a: number, n: number): number {
+	return ((a % n) + n) % n;
+}