extract Math.clamp to a separate proposal

Author: zloirock

CHANGELOG.md

@@ -12,6 +12,12 @@
     - `DataView.prototype.setFloat16`
   - Moved to stable ES, [February 2025 TC39 meeting](https://github.com/tc39/proposals/commit/b81fa9bccf4b51f33de0cbe797976a84d05d4b76)
   - Added `es.` namespace modules, `/es/` and `/stable/` namespaces entries
+- [`Math.clamp` stage 1 proposal](https://github.com/CanadaHonk/proposal-math-clamp):
+  - Built-ins:
+    - `Math.clamp`
+  - Extracted from [old `Math` extensions proposal](https://github.com/rwaldron/proposal-math-extensions)
+  - Added arguments validation
+  - Added new entries
 - Compat data improvements:
   - [`DisposableStack`, `AsyncDisposableStack`, `SuppressedError` and `Iterator.prototype[@@dispose]`](https://github.com/tc39/proposal-explicit-resource-management) marked as [shipped from V8 ~ Chromium 134](https://issues.chromium.org/issues/42203506#comment24)
   - [`Error.isError`](https://github.com/tc39/proposal-is-error) added and marked as supported from V8 ~ Chromium 134

README.md

@@ -186,6 +186,7 @@ structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])
       - [`Array` filtering](#array-filtering)
       - [`Array` deduplication](#array-deduplication)
       - [`DataView` get / set `Uint8Clamped` methods](#dataview-get-set-iint8clamped-methods)
+      - [`Math.clamp`](#mathclamp)
       - [`Number.fromString`](#numberfromstring)
       - [`String.cooked`](#stringcooked)
       - [`String.prototype.codePoints`](#stringprototypecodepoints)
@@ -3154,6 +3155,25 @@ view.setUint8Clamped(0, 100500);
 console.log(view.getUint8Clamped(0)); // => 255
 ```
 
+##### [`Math.clamp`](https://github.com/CanadaHonk/proposal-math-clamp)[⬆](#index)
+Module [`esnext.math.clamp`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.math.clamp.js)
+```ts
+class Math {
+  clamp(value: number, min: number, max: number): number;
+}
+```
+[*CommonJS entry points:*](#commonjs-api)
+```
+core-js/proposals/math-clamp
+core-js(-pure)/full/math/clamp
+```
+[*Example*](https://tinyurl.com/2ayyqr8j):
+```js
+Math.clamp(5, 0, 10); // => 5
+Math.clamp(-5, 0, 10); // => 0
+Math.clamp(15, 0, 10); // => 10
+````
+
 ##### [`Number.fromString`](https://github.com/tc39/proposal-number-fromstring)[⬆](#index)
 Module [`esnext.number.from-string`](https://github.com/zloirock/core-js/blob/master/packages/core-js/modules/esnext.number.from-string.js)
 ```ts

packages/core-js/internals/a-number.js

@@ -0,0 +1,7 @@
+'use strict';
+var $TypeError = TypeError;
+
+module.exports = function (argument) {
+  if (typeof argument == 'number') return argument;
+  throw new $TypeError('Argument is not a number');
+};

packages/core-js/modules/esnext.math.clamp.js

@@ -1,13 +1,21 @@
 'use strict';
 var $ = require('../internals/export');
+var aNumber = require('../internals/a-number');
+var notANaN = require('../internals/not-a-nan');
+var sameValue = require('../internals/same-value');
 
-var min = Math.min;
-var max = Math.max;
+var $RangeError = RangeError;
+var $min = Math.min;
+var $max = Math.max;
 
 // `Math.clamp` method
 // https://rwaldron.github.io/proposal-math-extensions/
 $({ target: 'Math', stat: true, forced: true }, {
-  clamp: function clamp(x, lower, upper) {
-    return min(upper, max(lower, x));
+  clamp: function clamp(value, min, max) {
+    aNumber(value);
+    notANaN(aNumber(min));
+    notANaN(aNumber(max));
+    if ((sameValue(min, 0) && sameValue(max, -0)) || min > max) throw new $RangeError('`min` should be smaller than `max`');
+    return $min(max, $max(min, value));
   }
 });

packages/core-js/proposals/math-clamp.js

@@ -0,0 +1,3 @@
+'use strict';
+// https://github.com/CanadaHonk/proposal-math-clamp
+require('../modules/esnext.math.clamp');

packages/core-js/stage/1.js

@@ -8,6 +8,7 @@ require('../proposals/collection-methods');
 require('../proposals/collection-of-from');
 require('../proposals/data-view-get-set-uint8-clamped');
 require('../proposals/keys-composition');
+require('../proposals/math-clamp');
 require('../proposals/math-extensions');
 require('../proposals/math-signbit');
 require('../proposals/number-from-string');

tests/codespell/runner.mjs

@@ -7,6 +7,7 @@ const skip = [
 ];
 
 const ignoreWords = [
+  'aNumber',
   'larg',
   'outLow',
   'statics',

tests/entries/unit.mjs

@@ -946,6 +946,7 @@ for (PATH of ['core-js-pure', 'core-js']) {
   load('proposals/map-upsert');
   load('proposals/map-upsert-stage-2');
   load('proposals/map-upsert-v4');
+  load('proposals/math-clamp');
   load('proposals/math-extensions');
   load('proposals/math-signbit');
   load('proposals/math-sum');

tests/unit-global/esnext.math.clamp.js

@@ -1,24 +1,26 @@
-import { createConversionChecker } from '../helpers/helpers.js';
-
 QUnit.test('Math.clamp', assert => {
   const { clamp } = Math;
   assert.isFunction(clamp);
   assert.name(clamp, 'clamp');
   assert.arity(clamp, 3);
   assert.looksNative(clamp);
   assert.nonEnumerable(Math, 'clamp');
+
   assert.same(clamp(2, 4, 6), 4);
   assert.same(clamp(4, 2, 6), 4);
   assert.same(clamp(6, 2, 4), 4);
 
-  const checker1 = createConversionChecker(2);
-  const checker2 = createConversionChecker(4);
-  const checker3 = createConversionChecker(5);
-  assert.same(clamp(checker1, checker2, checker3), 4, 'object wrapper');
-  assert.same(checker1.$valueOf, 1, 'checker1 valueOf calls');
-  assert.same(checker1.$toString, 0, 'checker1 toString calls');
-  assert.same(checker2.$valueOf, 1, 'checker2 valueOf calls');
-  assert.same(checker2.$toString, 0, 'checker2 toString calls');
-  assert.same(checker3.$valueOf, 1, 'checker3 valueOf calls');
-  assert.same(checker3.$toString, 0, 'checker3 toString calls');
+  assert.same(clamp(NaN, 4, 6), NaN, 'If value is NaN, return NaN.');
+  assert.same(clamp(-0, 0, 1), 0, 'If value is -0𝔽 and min is +0𝔽, return +0𝔽.');
+  assert.same(clamp(0, -0, 1), 0, 'If value is +0𝔽 and min is -0𝔽, return +0𝔽.');
+  assert.same(clamp(-0, -1, 0), -0, 'If value is -0𝔽 and max is +0𝔽, return -0𝔽.');
+  assert.same(clamp(0, -1, -0), -0, 'If value is +0𝔽 and max is -0𝔽, return -0𝔽.');
+
+  assert.throws(() => clamp(Object(2), 1, 3), TypeError, 'If value is not a Number, throw a TypeError exception.');
+  assert.throws(() => clamp(2, Object(1), 3), TypeError, 'If min is not a Number, throw a TypeError exception.');
+  assert.throws(() => clamp(2, NaN, 3), RangeError, 'If min is NaN, throw a RangeError exception.');
+  assert.throws(() => clamp(2, 1, Object(3)), TypeError, 'If max is not a Number, throw a TypeError exception.');
+  assert.throws(() => clamp(2, 1, NaN), RangeError, 'If max is NaN, throw a RangeError exception.');
+  assert.throws(() => clamp(2, 0, -0), RangeError, 'If min is +0𝔽 and max is -0𝔽, throw a RangeError exception.');
+  assert.throws(() => clamp(2, 3, 1), RangeError, 'If min > max, throw a RangeError exception.');
 });

tests/unit-pure/esnext.math.clamp.js

@@ -1,22 +1,24 @@
-import { createConversionChecker } from '../helpers/helpers.js';
-
 import clamp from 'core-js-pure/full/math/clamp';
 
 QUnit.test('Math.clamp', assert => {
   assert.isFunction(clamp);
   assert.arity(clamp, 3);
+
   assert.same(clamp(2, 4, 6), 4);
   assert.same(clamp(4, 2, 6), 4);
   assert.same(clamp(6, 2, 4), 4);
 
-  const checker1 = createConversionChecker(2);
-  const checker2 = createConversionChecker(4);
-  const checker3 = createConversionChecker(5);
-  assert.same(clamp(checker1, checker2, checker3), 4, 'object wrapper');
-  assert.same(checker1.$valueOf, 1, 'checker1 valueOf calls');
-  assert.same(checker1.$toString, 0, 'checker1 toString calls');
-  assert.same(checker2.$valueOf, 1, 'checker2 valueOf calls');
-  assert.same(checker2.$toString, 0, 'checker2 toString calls');
-  assert.same(checker3.$valueOf, 1, 'checker3 valueOf calls');
-  assert.same(checker3.$toString, 0, 'checker3 toString calls');
+  assert.same(clamp(NaN, 4, 6), NaN, 'If value is NaN, return NaN.');
+  assert.same(clamp(-0, 0, 1), 0, 'If value is -0𝔽 and min is +0𝔽, return +0𝔽.');
+  assert.same(clamp(0, -0, 1), 0, 'If value is +0𝔽 and min is -0𝔽, return +0𝔽.');
+  assert.same(clamp(-0, -1, 0), -0, 'If value is -0𝔽 and max is +0𝔽, return -0𝔽.');
+  assert.same(clamp(0, -1, -0), -0, 'If value is +0𝔽 and max is -0𝔽, return -0𝔽.');
+
+  assert.throws(() => clamp(Object(2), 1, 3), TypeError, 'If value is not a Number, throw a TypeError exception.');
+  assert.throws(() => clamp(2, Object(1), 3), TypeError, 'If min is not a Number, throw a TypeError exception.');
+  assert.throws(() => clamp(2, NaN, 3), RangeError, 'If min is NaN, throw a RangeError exception.');
+  assert.throws(() => clamp(2, 1, Object(3)), TypeError, 'If max is not a Number, throw a TypeError exception.');
+  assert.throws(() => clamp(2, 1, NaN), RangeError, 'If max is NaN, throw a RangeError exception.');
+  assert.throws(() => clamp(2, 0, -0), RangeError, 'If min is +0𝔽 and max is -0𝔽, throw a RangeError exception.');
+  assert.throws(() => clamp(2, 3, 1), RangeError, 'If min > max, throw a RangeError exception.');
 });