@nejs/basic-extensions 2.21.0 → 2.21.5

package/src/big.int.extension.js

@@ -15,52 +15,126 @@ import { Patch } from '@nejs/extension'
  * // Now the `BigInt` class has additional methods available
  */
 export const BigIntExtensions = new Patch(BigInt, {
-  /**
-   * Determines if the supplied `value` is a `BigInt`. This check is
-   * performed by first checking the `typeof` the `value` and then
-   * checking to see if the `value` is an `instanceof` `BigInt`
-   *
-   * @param {*} value The value that needs to be checked to determine
-   * if it is a `BigInt` or not
-   * @returns {boolean} `true` if the supplied `value` is a `BigInt`,
-   * `false` otherwise
-   *
-   * @example
-   * const bigInt = 1234567890123456789012345678901234567890n
-   * isBigInt(bigInt) // true
-   * isBigInt(1234567890123456789012345678901234567890) // false
-   * isBigInt('1234567890123456789012345678901234567890') // false
-   * isBigInt(BigInt('1234567890123456789012345678901234567890')) // true
-   */
-  isBigInt(value) {
-    return typeof value === 'bigint' || value instanceof BigInt
-  },
+  [Patch.kMutablyHidden]: {
+    /**
+     * Checks if all or some of the supplied values are numbers.
+     *
+     * This method uses the `Array.prototype.every` or `Array.prototype.some`
+     * method to check if all or some of the supplied values are numbers,
+     * respectively. The method to use is determined by the `which` parameter.
+     *
+     * @param {string} [which='every'] - Determines the method to use for the
+     * check. Can be either 'every' or 'some'. Defaults to 'every'.
+     * @param {...*} values - The values to check.
+     * @returns {boolean} - Returns `true` if all or some of the values are
+     * numbers (based on the `which` parameter), `false` otherwise.
+     *
+     * @example
+     * areNumbers('every', 1, 2, 3) // true
+     * areNumbers('some', 1, '2', 3) // true
+     * areNumbers('every', 1, '2', 3) // false
+     */
+    areBigInts(which = ['every', 'some'][0], ...values) {
+      if (which !== 'every' && which !== 'some') {
+        return false
+      }
 
-  /**
-   * Conditionally returns a value based on whether the supplied
-   * `value` is a `BigInt` or not. If the `value` is a `BigInt`,
-   * the `thenValue` will be returned. If it is not a `BigInt`,
-   * the `elseValue` will be returned instead.
-   *
-   * @param {any} value The value to check to determine if it is a
-   * `BigInt`
-   * @param {any} thenValue The value to return if the supplied
-   * `value` is a `BigInt`
-   * @param {any} elseValue The value to return if the supplied
-   * `value` is not a `BigInt`
-   * @returns {any} Either the `thenValue` or `elseValue` depending
-   * on if the supplied `value` is a `BigInt`
-   *
-   * @example
-   * const bigInt = 1234567890123456789012345678901234567890n
-   * const num = 42
-   * ifBigInt(bigInt, 'is a BigInt', 'not a BigInt')
-   * // 'is a BigInt'
-   * ifBigInt(num, 'is a BigInt', 'not a BigInt')
-   * // 'not a BigInt'
-   */
-  ifBigInt(value, thenValue, elseValue) {
-    return isThenElse(this.isBigInt(value), thenValue, elseValue)
+      return values[which](num => this.isBigInt(num))
+    },
+
+    /**
+     * Determines if the supplied `value` is a `BigInt`. This check is
+     * performed by first checking the `typeof` the `value` and then
+     * checking to see if the `value` is an `instanceof` `BigInt`
+     *
+     * @param {*} value The value that needs to be checked to determine
+     * if it is a `BigInt` or not
+     * @returns {boolean} `true` if the supplied `value` is a `BigInt`,
+     * `false` otherwise
+     *
+     * @example
+     * const bigInt = 1234567890123456789012345678901234567890n
+     * isBigInt(bigInt) // true
+     * isBigInt(1234567890123456789012345678901234567890) // false
+     * isBigInt('1234567890123456789012345678901234567890') // false
+     * isBigInt(BigInt('1234567890123456789012345678901234567890')) // true
+     */
+    isBigInt(value) {
+      return typeof value === 'bigint' || value instanceof BigInt
+    },
+
+    /**
+     * Conditionally returns a value based on whether the supplied
+     * `value` is a `BigInt` or not. If the `value` is a `BigInt`,
+     * the `thenValue` will be returned. If it is not a `BigInt`,
+     * the `elseValue` will be returned instead.
+     *
+     * @param {any} value The value to check to determine if it is a
+     * `BigInt`
+     * @param {any} thenValue The value to return if the supplied
+     * `value` is a `BigInt`
+     * @param {any} elseValue The value to return if the supplied
+     * `value` is not a `BigInt`
+     * @returns {any} Either the `thenValue` or `elseValue` depending
+     * on if the supplied `value` is a `BigInt`
+     *
+     * @example
+     * const bigInt = 1234567890123456789012345678901234567890n
+     * const num = 42
+     * ifBigInt(bigInt, 'is a BigInt', 'not a BigInt')
+     * // 'is a BigInt'
+     * ifBigInt(num, 'is a BigInt', 'not a BigInt')
+     * // 'not a BigInt'
+     */
+    ifBigInt(value, thenValue, elseValue) {
+      return isThenElse(this.isBigInt(value), thenValue, elseValue)
+    },
+
+    /**
+     * The Math.min() static method returns the smallest of the numbers given
+     * as input parameters, or Infinity if there are no parameters.
+     *
+     * @param {bigint|number} values value1, …, valueN – Zero or more numbers
+     * among which the lowest value will be selected and returned.
+     * @returns {bigint|number|Infinity} The smallest of the given numbers.
+     * Returns Infinity if no parameters are provided.
+     */
+    min(...values) {
+      const sorter = (l,r) => l < r ? -1 : l > r ? 1 : 0
+
+      if (!values.length)
+        return Infinity
+
+      if (values.every(n => typeof n === 'bigint')) {
+        return values.toSorted(sorter).at(0)
+      }
+      else {
+        throw new TypeError('All supplied values must be of type bigint')
+      }
+    },
+
+    /**
+     * The Math.max() static method returns the largest of the numbers given
+     * as input parameters, or Infinity if there are no parameters.
+     *
+     * @param {bigint|number} values value1, …, valueN – Zero or more numbers
+     * among which the largest value will be selected and returned.
+     * @returns {bigint|number|Infinity} The largest of the given numbers.
+     * Returns Infinity if no parameters are provided.
+     */
+    max(...values) {
+      const sorter = (l,r) => l < r ? -1 : l > r ? 1 : 0
+
+      if (!values.length)
+        return Infinity
+
+      if (values.every(n => typeof n === 'bigint')) {
+        return values.toSorted(sorter).at(-1)
+      }
+      else {
+        throw new TypeError('All supplied values must be of type bigint')
+      }
+    },
   },
 })
 
@@ -81,6 +155,36 @@ const { isBigInt: pIsBigInt, ifBigInt: pIfBigInt } = BigIntExtensions.patches
  * // Now the `BigInt` prototype has additional methods available
  */
 export const BigIntPrototypeExtensions = new Patch(BigInt.prototype, {
+  /**
+   * Clamps a value between a minimum and maximum value.
+   *
+   * This method checks if the provided value and the min and max bounds are
+   * numbers. If they are not, it returns the original value. If they are,
+   * it ensures that the value does not go below the minimum value or above
+   * the maximum value.
+   *
+   * @param {bigint} [minValue=BigInt(-Number.MAX_VALUE)] - The minimum value.
+   * Defaults to BigInt(-Number.MAX_VALUE).
+   * @param {bigint} [maxValue=BigInt(Number.MAX_VALUE)] - The maximum value.
+   * Defaults to BigInt(Number.MAX_VALUE).
+   * @returns {bigint} - Returns the clamped value if all parameters are
+   * big integers.
+   *
+   * @example
+   * (10n).clamp(1n, 5n) // returns 5n
+   * (-10n).clamp(1n, 5n) // returns 1n
+   * (3n).clamp(1n, 5n) // returns 3n
+   */
+  clamp(
+    minValue = BigInt(-Number.MAX_VALUE),
+    maxValue = BigInt(Number.MAX_VALUE)
+  ) {
+    if (typeof minValue !== 'bigint' || typeof maxValue !== 'bigint')
+      throw new TypeError('All values must be big integers')
+
+    return BigInt.max(minValue, BigInt.min(maxValue, this))
+  },
+
   /**
    * A getter method that returns an object representation of the BigInt
    * instance.
@@ -149,6 +253,28 @@ export const BigIntPrototypeExtensions = new Patch(BigInt.prototype, {
   ifBigInt(thenValue, elseValue) {
     return pIfBigInt(this, thenValue, elseValue)
   },
+
+  /**
+   * Provides a way when dealing with numbers to determine if
+   * a given number is within a range of values. By default, if
+   * no parameters are supplied, it always returns true since
+   * the default range is -Infinity to +Infinity. Additionally,
+   * by default, the number will always be less than the supplied
+   * max unless inclusive is set to true.
+   *
+   * @param min the lower range value, defaults to -Infinity
+   * @param max the upper range value, defaults to +Infinity
+   * @param inclusive defaults to false, set to true if you
+   * want the max value to less than and equals to
+   * @returns {boolean} true if within the range, false otherwise
+   */
+  within(
+    min = BigInt(-Infinity),
+    max = BigInt(Infinity),
+    inclusive = false
+  ) {
+    return this >= min && (inclusive ? this <= max : this < max)
+  }
 })
 
 // NOTE to self; this is repeated here otherwise a circular reference from

package/src/index.js

@@ -4,6 +4,7 @@ import { FunctionExtensions, FunctionPrototypeExtensions } from './function.exte
 import { GlobalFunctionsAndProps } from './global.this.js'
 import { JSONExtensions } from './json.extensions.js'
 import { MapExtensions, MapPrototypeExtensions } from './map.extensions.js'
+import { MathExtensions } from './math.extension.js'
 import { NumberExtensions, NumberPrototypeExtensions } from './number.extension.js'
 import { ObjectExtensions, ObjectPrototypeExtensions } from './object.extensions.js'
 import { ReflectExtensions } from './reflect.extensions.js'
@@ -53,6 +54,7 @@ const StaticPatches = [
   [Function, FunctionExtensions, Function.name],
   [JSON, JSONExtensions, 'JSON'],                // Missing a .name property
   [Map, MapExtensions, Map.name],
+  [Math, MathExtensions, 'Math'],
   [Number, NumberExtensions, Number.name],
   [Object, ObjectExtensions, Object.name],
   [Reflect, ReflectExtensions, 'Reflect'],       // Missing a .name property

package/src/math.extension.js

@@ -0,0 +1,73 @@
+import { Patch } from '@nejs/extension'
+
+/**
+ * `Math` extensions. Building better worlds...actually just
+ * providing some parity between Number and BigInt types for
+ * now, but later, better worlds.
+ *
+ * @type {Patch}
+ * @example
+ * import { MathExtensions } from 'math.extension.js'
+ *
+ * MathExtensions.apply()
+ * // Now the `Math` class has additional methods available
+ */
+export const MathExtensions = new Patch(Math, {
+  [Patch.kMutablyHidden]: {
+    /**
+     * The Math.min() static method returns the smallest of the numbers given
+     * as input parameters, or Infinity if there are no parameters.
+     *
+     * @param {bigint|number} values value1, …, valueN – Zero or more numbers
+     * among which the lowest value will be selected and returned.
+     * @returns {bigint|number|NaN|Infinity} The smallest of the given numbers.
+     * Returns NaN if any of the parameters is or is converted into NaN or if
+     * the types of numbers are mismatched (i.e., bigint vs. number types).
+     * Returns Infinity if no parameters are provided.
+     */
+    min(...values) {
+      const sorter = (l,r) => l < r ? -1 : l > r ? 1 : 0
+
+      if (!values.length)
+        return Infinity
+
+      if (values.every(n => typeof n === 'bigint')) {
+        return values.toSorted(sorter).at(0)
+      }
+      else if (values.every(n => typeof n === 'number')) {
+        return values.toSorted(sorter).at(0)
+      }
+      else {
+        return NaN
+      }
+    },
+
+    /**
+     * The Math.max() static method returns the largest of the numbers given
+     * as input parameters, or Infinity if there are no parameters.
+     *
+     * @param {bigint|number} values value1, …, valueN – Zero or more numbers
+     * among which the largest value will be selected and returned.
+     * @returns {bigint|number|NaN|Infinity} The largest of the given numbers.
+     * Returns NaN if any of the parameters is or is converted into NaN or if
+     * the types of numbers are mismatched (i.e., bigint vs. number types).
+     * Returns Infinity if no parameters are provided.
+     */
+    max(...values) {
+      const sorter = (l,r) => l < r ? -1 : l > r ? 1 : 0
+
+      if (!values.length)
+        return Infinity
+
+      if (values.every(n => typeof n === 'bigint')) {
+        return values.toSorted(sorter).at(-1)
+      }
+      else if (values.every(n => typeof n === 'number')) {
+        return values.toSorted(sorter).at(-1)
+      }
+      else {
+        return NaN
+      }
+    },
+  },
+})

package/src/number.extension.js

@@ -258,6 +258,24 @@ export const NumberPrototypeExtensions = new Patch(Number.prototype, {
     ifNumber(thenValue, elseValue) {
       return pIfNumber(this, thenValue, elseValue)
     },
+
+    /**
+     * Provides a way when dealing with numbers to determine if
+     * a given number is within a range of values. By default, if
+     * no parameters are supplied, it always returns true since
+     * the default range is -Infinity to +Infinity. Additionally,
+     * by default, the number will always be less than the supplied
+     * max unless inclusive is set to true.
+     *
+     * @param min the lower range value, defaults to -Infinity
+     * @param max the upper range value, defaults to +Infinity
+     * @param inclusive defaults to false, set to true if you
+     * want the max value to less than and equals to
+     * @returns {boolean} true if within the range, false otherwise
+     */
+    within(min = -Infinity, max = Infinity, inclusive = false) {
+      return this >= min && (inclusive ? this <= max : this < max)
+    }
   }
 })