Refactor clamp to follow Math.clamp proposal and improve tests

Author: georapbox

packages/math/clamp/README.md

@@ -2,12 +2,15 @@
 
 ## clamp(value, min, max) ⇒ <code>Number</code>
 Clamps number within the inclusive `min` and `max` bounds, making sure it does not go beyond them on either side.
-If `min` is greater than `max` the parameters are swapped to support inverted ranges.
+
+The mplementation is based on proposal for `Nmuber.prototype.clamp` (originally `Math.clamp`):  
+https://tc39.es/proposal-math-clamp
 
 **Returns**: <code>Number</code> - The clamped number.  
 **Throws**:
 
-- <code>TypeError</code> If one or more of the arguments passed is not a number.
+- <code>TypeError</code> If any of the arguments is not a number.
+- <code>RangeError</code> If `min` is greater than `max`.
 
 
 | Param | Type | Description |
@@ -30,9 +33,6 @@ clamp(-15, 0, 100);
 clamp(120, 0, 100);
 // => 100
 
-clamp(-5, NaN, 5); // If any of lower or upper bound are `NaN`, they will be converted to `0`.
-// => 0
-
-clamp(120, 100, 0); // The order of lower and upper bounds is reversed (100 > 0)
-// => 100
+clamp(NaN, 0, 100);
+// => NaN
 ```

packages/math/clamp/clamp.js

@@ -3,12 +3,15 @@
 /**
  * Clamps number within the inclusive `min` and `max` bounds,
  * making sure it does not go beyond them on either side.
- * If `min` is greater than `max` the parameters are swapped to support inverted ranges.
+ *
+ * The mplementation is based on proposal for `Nmuber.prototype.clamp` (originally `Math.clamp`):
+ * https://tc39.es/proposal-math-clamp
  *
  * @param {Number} value The number to clamp.
  * @param {Number} min The lower bound.
  * @param {Number} max The upper bound.
- * @throws {TypeError} If one or more of the arguments passed is not a number.
+ * @throws {TypeError} If any of the arguments is not a number.
+ * @throws {RnageError} If `min` is greater than `max`.
  * @returns {Number} The clamped number.
  * @example
  *
@@ -24,26 +27,59 @@
  * clamp(120, 0, 100);
  * // => 100
  *
- * clamp(-5, NaN, 5); // If any of lower or upper bound are `NaN`, they will be converted to `0`.
- * // => 0
- *
- * clamp(120, 100, 0); // The order of lower and upper bounds is reversed (100 > 0)
- * // => 100
+ * clamp(NaN, 0, 100);
+ * // => NaN
  */
-const clamp = (value, lower, upper) => {
-  if (typeof value !== 'number' || typeof lower !== 'number' || typeof upper !== 'number') {
-    throw new TypeError('Expected all arguments to be numbers');
+const clamp = (value, min, max) => {
+  if (typeof value !== 'number') {
+    throw new TypeError('value must be a Number');
+  }
+
+  if (typeof min !== 'number') {
+    throw new TypeError('min must be a Number');
+  }
+
+  if (typeof max !== 'number') {
+    throw new TypeError('max must be a Number');
+  }
+
+  if (Number.isNaN(min) || Number.isNaN(max) || Number.isNaN(value)) {
+    return NaN;
+  }
+
+  if (min > max) {
+    throw new RangeError('min cannot be greater than max');
+  }
+
+  if (Object.is(min, max)) {
+    return min;
+  }
+
+  if (Object.is(value, -0) && Object.is(min, +0)) {
+    return +0;
+  }
+
+  if (Object.is(value, +0) && Object.is(min, -0)) {
+    return +0;
+  }
+
+  if (value < min) {
+    return min;
+  }
+
+  if (Object.is(value, -0) && Object.is(max, +0)) {
+    return -0;
   }
 
-  if (lower !== lower) { // lower bound is not `NaN`
-    lower = 0;
+  if (Object.is(value, +0) && Object.is(max, -0)) {
+    return -0;
   }
 
-  if (upper !== upper) { // upper bound is not `NaN`
-    upper = 0;
+  if (value > max) {
+    return max;
   }
 
-  return Math.min(Math.max(value, Math.min(lower, upper)), Math.max(lower, upper));
+  return value;
 };
 
 module.exports = clamp;

packages/math/clamp/test.js

@@ -1,27 +1,73 @@
 const clamp = require('./clamp');
 
 describe('Math/clamp', () => {
-  it('clamps number within the inclusive lower and upper bounds', () => {
-    expect(clamp(5, 0, 10)).toBe(5);
+  it('throws TypeError when value is not a number', () => {
+    expect(() => clamp('5', 1, 10)).toThrow(TypeError);
+    expect(() => clamp(null, 1, 10)).toThrow(TypeError);
+    expect(() => clamp(undefined, 1, 10)).toThrow(TypeError);
+  });
 
-    expect(clamp(10, -5, 5)).toBe(5);
+  it('throws TypeError when min is not a number', () => {
+    expect(() => clamp(5, '1', 10)).toThrow(TypeError);
+  });
 
-    expect(clamp(-10, -5, 5)).toBe(-5);
+  it('throws TypeError when max is not a number', () => {
+    expect(() => clamp(5, 1, '10')).toThrow(TypeError);
+  });
+
+  it('returns NaN when min is NaN', () => {
+    expect(clamp(5, NaN, 10)).toBeNaN();
+  });
 
-    expect(clamp(-15, 0, 100)).toBe(0);
+  it('returns NaN when max is NaN', () => {
+    expect(clamp(5, 1, NaN)).toBeNaN();
+  });
 
-    expect(clamp(120, 0, 100)).toBe(100);
+  it('returns NaN when value is NaN', () => {
+    expect(clamp(NaN, 1, 10)).toBeNaN();
+  });
 
-    expect(clamp(-5, NaN, NaN)).toBe(0);
+  it('throws RangeError when min > max', () => {
+    expect(() => clamp(5, 10, 1)).toThrow(RangeError);
+  });
 
-    expect(clamp(-5, NaN, 5)).toBe(0);
+  it('returns min when min === max', () => {
+    expect(clamp(42, 7, 7)).toBe(7);
+    expect(clamp(-0, +0, +0)).toBe(+0);
+    expect(clamp(+0, -0, -0)).toBe(-0);
+  });
 
-    expect(clamp(-5, 0, NaN)).toBe(0);
+  it('value -0 and min +0 -> +0', () => {
+    const result = clamp(-0, +0, 10);
+    expect(Object.is(result, +0)).toBe(true);
+  });
 
-    expect(clamp(120, 100, 0)).toBe(100);
+  it('value +0 and min -0 -> +0', () => {
+    const result = clamp(+0, -0, 10);
+    expect(Object.is(result, +0)).toBe(true);
+  });
+
+  it('value < min -> min', () => {
+    expect(clamp(-3, 1, 10)).toBe(1);
+  });
+
+  it('value -0 and max +0 -> -0', () => {
+    const result = clamp(-0, -1, +0);
+    expect(Object.is(result, -0)).toBe(true);
+  });
+
+  it('value +0 and max -0 -> -0', () => {
+    const result = clamp(+0, -1, -0);
+    expect(Object.is(result, -0)).toBe(true);
+  });
+
+  it('value > max -> max', () => {
+    expect(clamp(99, 1, 10)).toBe(10);
+  });
 
-    expect(() => {
-      return clamp(10, '-5', '5');
-    }).toThrow(new TypeError('Expected all arguments to be numbers'));
+  it('returns value when within [min, max]', () => {
+    expect(clamp(5, 1, 10)).toBe(5);
+    expect(clamp(1, 1, 10)).toBe(1);
+    expect(clamp(10, 1, 10)).toBe(10);
   });
 });