@nejs/basic-extensions 2.4.0 → 2.6.0

package/package.json

@@ -55,12 +55,13 @@
     "jsdoc": "jsdoc -c jsdoc-config.json -p -a all -R README.md",
     "documentation": "documentation build src/** -f html --github -o docs && documentation readme src/index.js --section=API",
     "module": "bin/build",
-    "test": "jest"
+    "test": "jest",
+    "repl": "npm run build && node --no-warnings repl.bootstrap.js"
   },
   "type": "module",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "dependencies": {
-    "@nejs/extension": "^2.7.2"
+    "@nejs/extension": "^2.8.0"
   },
-  "browser": "dist/@nejs/basic-extensions.bundle.2.3.0.js"
+  "browser": "dist/@nejs/basic-extensions.bundle.2.5.0.js"
 }

package/src/arrayextensions.js

@@ -9,66 +9,67 @@ import { Patch } from '@nejs/extension'
  * operations on arrays and makes code more expressive and concise.
  */
 export const ArrayPrototypeExtensions = new Patch(Array.prototype, {
-  /**
-   * Sometimes defining even a short function for the invocation of `find`
-   * can be troublesome. This helper function performs that job for you. If
-   * the specified element is in the array, `true` will be returned.
-   *
-   * @param {*} value the value to search for. This value must triple equals
-   * the array element in order to return true.
-   * @returns true if the exact element exists in the array, false otherwise
-   */
-  contains(value) {
-    return !!this.find(entry => entry === value)
-  },
+  [Patch.kMutablyHidden]: {
+    /**
+     * Sometimes defining even a short function for the invocation of `find`
+     * can be troublesome. This helper function performs that job for you. If
+     * the specified element is in the array, `true` will be returned.
+     *
+     * @param {*} value the value to search for. This value must triple equals
+     * the array element in order to return true.
+     * @returns true if the exact element exists in the array, false otherwise
+     */
+    contains(value) {
+      return !!this.find(entry => entry === value)
+    },
 
-  /**
-   * The `findEntry` function searches the entries of the object and returns
-   * the `[index, value]` entry array for the first matching value found.
-   *
-   * @param {function} findFn a function that takes the element to be checked
-   * and returns a boolean value
-   * @returns if `findFn` returns `true`, an array with two elements, the first
-   * being the index, the second being the value, is returned.
-   */
-  findEntry(findFn) {
-    const entries = this.entries()
-    const VALUE = 1
+    /**
+     * The `findEntry` function searches the entries of the object and returns
+     * the `[index, value]` entry array for the first matching value found.
+     *
+     * @param {function} findFn a function that takes the element to be checked
+     * and returns a boolean value
+     * @returns if `findFn` returns `true`, an array with two elements, the first
+     * being the index, the second being the value, is returned.
+     */
+    findEntry(findFn) {
+      const entries = this.entries()
+      const VALUE = 1
 
-    for (let entry of entries) {
-      if (findFn(entry[VALUE])) {
-        return entry
+      for (let entry of entries) {
+        if (findFn(entry[VALUE])) {
+          return entry
+        }
       }
-    }
 
-    return undefined
-  },
+      return undefined
+    },
 
-  /**
-   * A getter property that returns the first element of the array. If the
-   * array is empty, it returns `undefined`. This property is useful for
-   * scenarios where you need to quickly access the first item of an array
-   * without the need for additional checks or method calls.
-   *
-   * @returns {*} The first element of the array or `undefined` if the array
-   * is empty.
-   */
-  get first() {
-    return this[0];
-  },
+    /**
+     * A getter property that returns the first element of the array. If the
+     * array is empty, it returns `undefined`. This property is useful for
+     * scenarios where you need to quickly access the first item of an array
+     * without the need for additional checks or method calls.
+     *
+     * @returns {*} The first element of the array or `undefined` if the array
+     * is empty.
+     */
+    get first() {
+      return this[0];
+    },
 
-  /**
-   * A getter property that returns the last element of the array. It
-   * calculates the last index based on the array's length. If the array is
-   * empty, it returns `undefined`. This property is beneficial when you need
-   * to access the last item in an array, improving code readability and
-   * avoiding manual index calculation.
-   *
-   * @returns {*} The last element of the array or `undefined` if the
-   * array is empty.
-   */
-  get last() {
-    return this[this.length - 1];
+    /**
+     * A getter property that returns the last element of the array. It
+     * calculates the last index based on the array's length. If the array is
+     * empty, it returns `undefined`. This property is beneficial when you need
+     * to access the last item in an array, improving code readability and
+     * avoiding manual index calculation.
+     *
+     * @returns {*} The last element of the array or `undefined` if the
+     * array is empty.
+     */
+    get last() {
+      return this[this.length - 1];
+    },
   },
-
 })

package/src/functionextensions.js

@@ -134,90 +134,92 @@ export const FunctionExtensions = new Patch(Function, {
 })
 
 export const FunctionPrototypeExtensions = new Patch(Function.prototype, {
-  /**
-   * Determines if a given value is an asynchronous function. It checks if the
-   * value is an instance of `Function` and if its string representation
-   * includes the keyword 'Async'. This method is particularly useful for
-   * identifying async functions.
-   *
-   * @returns {boolean} Returns `true` if the value is an async function,
-   * otherwise `false`.
-   */
-  get isAsync() {
-    return Function.isAsync(this)
-  },
-
-  /**
-   * The function checks if a given value is an async generator function
-   *
-   * @returns {boolean} `true` if the value is an instance of a function and
-   * its string tag is 'AsyncGeneratorFunction', otherwise it returns `false`.
-   */
-  get isAsyncGenerator() {
-    return Function.isAsyncGenerator(this)
-  },
-
-  /**
-   * Checks if a given value is an arrow function. It verifies if the value is
-   * an instance of `Function`, if its string representation includes the '=>'
-   * symbol, and if it lacks a prototype, which is a characteristic of arrow
-   * functions in JavaScript.
-   *
-   * @returns {boolean} Returns `true` if the value is an arrow function,
-   * otherwise `false`.
-   */
-  get isBigArrow() {
-    return Function.isBigArrow(this)
-  },
-
-  /**
-   * Determines if a given value is a bound function. Bound functions are
-   * created using the `Function.prototype.bind` method, which allows setting
-   * the `this` value at the time of binding. This method checks if the value
-   * is an instance of `Function`, if its string representation starts with
-   * 'bound', and if it lacks a `prototype` property. These characteristics
-   * are indicative of bound functions in JavaScript.
-   *
-   * @returns {boolean} Returns `true` if the value is a bound function,
-   * otherwise `false`. Bound functions have a specific format in their
-   * string representation and do not have their own `prototype` property.
-   */
-  get isBound() {
-    return Function.isBound(this)
-  },
-
-  /**
-   * Determines if a given value is a class. It checks if the value is an
-   * instance of `Function` and if its string representation includes the
-   * keyword 'class'. This method is useful for distinguishing classes from
-   * other function types in JavaScript.
-   *
-   * @returns {boolean} Returns `true` if the value is a class, otherwise
-   * `false`.
-   */
-  get isClass() {
-    return Function.isClass(this)
-  },
-
-  /**
-   * Checks if a given value is a regular function. This method verifies if
-   * the value is an instance of `Function`, which includes regular functions,
-   * classes, and async functions but excludes arrow functions.
-   *
-   * @returns {boolean} Returns `true` if the value is a regular function,
-   * otherwise `false`.
-   */
-  get isFunction() {
-    return Function.isFunction(this)
-  },
-
-  /**
-   * The function checks if a given value is a generator function
-   *
-   * @returns {boolean} `true` if the value is an instance of a function and
-   * its string tag is 'GeneratorFunction', otherwise it returns `false`.
-   */
-  get isGenerator() {
-    return Function.isGenerator(this)
+  [Patch.kMutablyHidden]: {
+    /**
+     * Determines if a given value is an asynchronous function. It checks if the
+     * value is an instance of `Function` and if its string representation
+     * includes the keyword 'Async'. This method is particularly useful for
+     * identifying async functions.
+     *
+     * @returns {boolean} Returns `true` if the value is an async function,
+     * otherwise `false`.
+     */
+    get isAsync() {
+      return Function.isAsync(this)
+    },
+
+    /**
+     * The function checks if a given value is an async generator function
+     *
+     * @returns {boolean} `true` if the value is an instance of a function and
+     * its string tag is 'AsyncGeneratorFunction', otherwise it returns `false`.
+     */
+    get isAsyncGenerator() {
+      return Function.isAsyncGenerator(this)
+    },
+
+    /**
+     * Checks if a given value is an arrow function. It verifies if the value is
+     * an instance of `Function`, if its string representation includes the '=>'
+     * symbol, and if it lacks a prototype, which is a characteristic of arrow
+     * functions in JavaScript.
+     *
+     * @returns {boolean} Returns `true` if the value is an arrow function,
+     * otherwise `false`.
+     */
+    get isBigArrow() {
+      return Function.isBigArrow(this)
+    },
+
+    /**
+     * Determines if a given value is a bound function. Bound functions are
+     * created using the `Function.prototype.bind` method, which allows setting
+     * the `this` value at the time of binding. This method checks if the value
+     * is an instance of `Function`, if its string representation starts with
+     * 'bound', and if it lacks a `prototype` property. These characteristics
+     * are indicative of bound functions in JavaScript.
+     *
+     * @returns {boolean} Returns `true` if the value is a bound function,
+     * otherwise `false`. Bound functions have a specific format in their
+     * string representation and do not have their own `prototype` property.
+     */
+    get isBound() {
+      return Function.isBound(this)
+    },
+
+    /**
+     * Determines if a given value is a class. It checks if the value is an
+     * instance of `Function` and if its string representation includes the
+     * keyword 'class'. This method is useful for distinguishing classes from
+     * other function types in JavaScript.
+     *
+     * @returns {boolean} Returns `true` if the value is a class, otherwise
+     * `false`.
+     */
+    get isClass() {
+      return Function.isClass(this)
+    },
+
+    /**
+     * Checks if a given value is a regular function. This method verifies if
+     * the value is an instance of `Function`, which includes regular functions,
+     * classes, and async functions but excludes arrow functions.
+     *
+     * @returns {boolean} Returns `true` if the value is a regular function,
+     * otherwise `false`.
+     */
+    get isFunction() {
+      return Function.isFunction(this)
+    },
+
+    /**
+     * The function checks if a given value is a generator function
+     *
+     * @returns {boolean} `true` if the value is an instance of a function and
+     * its string tag is 'GeneratorFunction', otherwise it returns `false`.
+     */
+    get isGenerator() {
+      return Function.isGenerator(this)
+    },
   },
 })

package/src/mapextensions.js

@@ -1,30 +1,32 @@
 import { Patch } from '@nejs/extension';
 
 export const MapPrototypeExtensions = new Patch(Map.prototype, {
-  /**
-   * The function `getKey` returns the key associated with a given value
-   * in a map.
-   *
-   * @param {any} value - The value parameter is the value that you want to
-   * find the corresponding key for in the map.
-   * @param [strict=true] - The "strict" parameter is a boolean value that
-   * determines whether strict equality (===) or loose equality (==) should
-   * be used when comparing the "value" parameter with the values in the
-   * entries of the object. If "strict" is set to true, strict equality will
-   * be used.
-   * @returns the key associated with the given value. If a matching key is
-   * found, it is returned. If no matching key is found, null is returned.
-   */
-  getKey(value, strict = true) {
-    for (const [key, entryValue] of this) {
-      if (
-        (strict && value === entryValue) &&
-        (!strict && value == entryValue)
-      ) {
-        return key
-      }
+  [Patch.kMutablyHidden]: {
+    /**
+     * The function `getKey` returns the key associated with a given value
+     * in a map.
+     *
+     * @param {any} value - The value parameter is the value that you want to
+     * find the corresponding key for in the map.
+     * @param [strict=true] - The "strict" parameter is a boolean value that
+     * determines whether strict equality (===) or loose equality (==) should
+     * be used when comparing the "value" parameter with the values in the
+     * entries of the object. If "strict" is set to true, strict equality will
+     * be used.
+     * @returns the key associated with the given value. If a matching key is
+     * found, it is returned. If no matching key is found, null is returned.
+     */
+    getKey(value, strict = true) {
+      for (const [key, entryValue] of this) {
+        if (
+          (strict && value === entryValue) &&
+          (!strict && value == entryValue)
+        ) {
+          return key
+        }
 
-      return null
-    }
+        return null
+      }
+    },
   },
 })

package/src/objectextensions.js

@@ -200,22 +200,57 @@ export const ObjectExtensions = new Patch(Object, {
   },
 });
 
+const staticPatches = ObjectExtensions.patches;
+
 export const ObjectPrototypeExtensions = new Patch(Object.prototype, {
-  /**
-   * Strips an object down to only the keys specified. Optionally, any
-   * accessors can be made to retain their context on the source object.
-   * This is a passthrough to the static {@link Object.stripTo} function
-   *
-   * @param {Array<string|symbol>} keys the keys that should appear in the
-   * final reduced object
-   * @param {boolean} [bindAccessors = true] if this value is true then any
-   * accessors from the source object will continue to have their `this`
-   * value bound to the source. If the getter or setter on that object is
-   * defined using an arrow function, this will not work as intended.
-   * @returns {object} an object containing only the keys and symbols
-   * specified in the `keys` parameter.
-   */
-  stripTo(keys, bindAccessors = true) {
-    return Object.stripTo(this, keys, bindAccessors)
-  }
+  [Patch.kMutablyHidden](store) {
+    return {
+      /**
+       * Checks to see if the supplied `value` is both an object, and has the
+       * appropriate symbol defined.
+       *
+       * @param {any} value the value to determine if it contains a defined
+       * `Symbol.toStringTag` defined.
+       * @returns true if the symbol is defined, false otherwise
+       */
+      get hasStringTag() {
+        return staticPatches.hasStringTag(this)
+      },
+
+      /**
+       * Retrieves the string tag of an object. The string tag is a representation
+       * of the object's type, as defined by its `Object.prototype.toString`
+       * method. This utility method is helpful for getting a more descriptive
+       * type of an object than what is returned by the `typeof` operator,
+       * especially for custom objects.
+       *
+       * @param {*} value - The object whose string tag is to be retrieved.
+       * @param {boolean} strict - if this is set to true, undefined will be
+       * returned whenever a supplied object does not have a
+       * `Symbol.toStringTag` defined, period. if false, the default,
+       * @returns {string} - The string tag of the object, indicating its type.
+       */
+      getStringTag(strict = false) {
+        return staticPatches.getStringTag(this, strict)
+      },
+
+      /**
+       * Strips an object down to only the keys specified. Optionally, any
+       * accessors can be made to retain their context on the source object.
+       * This is a passthrough to the static {@link Object.stripTo} function
+       *
+       * @param {Array<string|symbol>} keys the keys that should appear in the
+       * final reduced object
+       * @param {boolean} [bindAccessors = true] if this value is true then any
+       * accessors from the source object will continue to have their `this`
+       * value bound to the source. If the getter or setter on that object is
+       * defined using an arrow function, this will not work as intended.
+       * @returns {object} an object containing only the keys and symbols
+       * specified in the `keys` parameter.
+       */
+      stripTo(keys, bindAccessors = true) {
+        return Object.stripTo(this, keys, bindAccessors)
+      }
+    }
+  },
 })