@nejs/basic-extensions 2.7.0 → 2.8.0

package/src/objectextensions.js

@@ -1,256 +0,0 @@
-import { Patch } from '@nejs/extension';
-
-/**
- * `ObjectExtensions` is a patch for the JavaScript built-in `Object` class.
- * It adds utility methods to the `Object` class without modifying the global
- * namespace directly. This patch includes methods for key validation, object
- * type checking, and retrieving the string tag of an object. These methods
- * are useful for enhancing the capabilities of the standard `Object` class
- * with additional utility functions.
- */
-export const ObjectExtensions = new Patch(Object, {
-  /**
-   * The function checks if a value is either `undefined` or `null`.
-   *
-   * @param {any} value - The parameter "value" is a variable that can hold
-   * any value.
-   * @returns {boolean} `true` if the value is either `undefined` or `null`,
-   * and `false` otherwise.
-   */
-  isNullDefined(value) {
-    return value === undefined || value === null
-  },
-
-  /**
-   * 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
-   */
-  hasStringTag(value) {
-    return Object.isObject(value) && Reflect.has(value, Symbol.toStringTag)
-  },
-
-  /**
-   * 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(value, strict = false) {
-    if (Object.hasStringTag(value)) {
-      return value[Symbol.toStringTag]
-    }
-
-    if (strict) {
-      return undefined
-    }
-
-    if (value && (typeof value === 'function')) {
-      return value.name
-    }
-
-    return /\s(.+)]/.exec(Object.prototype.toString.call(value))[1];
-  },
-
-  /**
-   * Determines the type of the given value based on its string tag. This method
-   * uses `Object.getStringTag` to obtain the string tag of the value, which
-   * represents its more specific type (e.g., Array, Map, Set) rather than just
-   * 'object'. The method then maps this string tag to the corresponding type
-   * present in the provided `owner` object, which defaults to `globalThis`.
-   * This utility method is especially useful for identifying the specific
-   * constructor or class of an object, beyond the basic types identified by
-   * the `typeof` operator.
-   *
-   * @param {any} value - The value whose type is to be determined.
-   * @param {object} [owner=globalThis] - The object in which to look up the
-   * constructor corresponding to the string tag. Defaults to `globalThis`,
-   * which covers global constructors like `Array`, `Object`, etc.
-   * @returns {Function|object|null|undefined} - Returns the constructor or
-   * type of the value based on its string tag. For 'Null' and 'Undefined',
-   * it returns `null` and `undefined`, respectively. For other types, it
-   * returns the corresponding constructor (e.g., `Array` for arrays) if
-   * available in the `owner` object.
-   */
-  getType(value, owner = globalThis) {
-    const stringTag = Object.getStringTag(value)
-
-    switch (stringTag) {
-      case 'Null': return null
-      case 'Undefined': return undefined
-      default:
-        return owner[stringTag]
-    }
-  },
-
-  /**
-   * Determines if the provided value is an object. This method checks whether
-   * the value is an instance of `Object` or if its type is 'object'. It's a
-   * utility method for type-checking, ensuring that a value is an object
-   * before performing operations that are specific to objects.
-   *
-   * @param {*} value - The value to be checked.
-   * @returns {boolean} - Returns `true` if the value is an object,
-   * otherwise `false`.
-   */
-  isObject(value) {
-    return value && (value instanceof Object || typeof value === 'object');
-  },
-
-  /**
-   * Checks to see if the supplied value is a primitive value.
-   *
-   * @param {any} value the value to test to see if it is a primitive value type
-   * @returns true if the object is considered widely to be a primitive value,
-   * false otherwise.
-   */
-  isPrimitive(value) {
-    // Check for null as a special case because typeof null
-    // is 'object'
-    if (value === null) {
-      return true;
-    }
-
-    // Check for other primitives
-    switch (typeof value) {
-      case 'string':
-      case 'number':
-      case 'bigint':
-      case 'boolean':
-      case 'undefined':
-      case 'symbol':
-        return true;
-      default:
-        return false;
-    }
-  },
-
-  /**
-   * Checks if the given value is a valid key for an object. In JavaScript, a
-   * valid key can be either a string or a symbol. This method is useful for
-   * validating object keys before using them in operations like setting or
-   * getting object properties.
-   *
-   * @param {*} value - The value to be checked.
-   * @returns {boolean} - Returns `true` if the value is a valid object key
-   * (string or symbol), otherwise `false`.
-   */
-  isValidKey(value) {
-    return (typeof value === 'string' || typeof value === 'symbol');
-  },
-
-  /**
-   * Strips an object down to only the keys specified. Optionally, any
-   * accessors can be made to retain their context on the source object.
-   *
-   * @param {object} object the object to pare down
-   * @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(object, keys, bindAccessors = true) {
-    if (!object || typeof object !== 'object') {
-      throw new TypeError(
-        'Object.stripTo requires an object to strip. Received',
-        object
-      );
-    }
-
-    const result = {};
-
-    if (!Array.isArray(keys)) {
-      return result;
-    }
-
-    for (let key of keys) {
-      if (Reflect.has(object, key)) {
-        const originalDescriptor = Object.getOwnPropertyDescriptor(object, key);
-        const descriptor = { ...originalDescriptor };
-
-        if (
-          typeof descriptor.get === 'function' ||
-          typeof descriptor.set === 'function'
-        ) {
-          if (bindAccessors) {
-            descriptor.get = descriptor.get?.bind(object);
-            descriptor.set = descriptor.set?.bind(object);
-          }
-        }
-
-        Object.defineProperty(result, key, descriptor);
-      }
-    }
-
-    return result;
-  },
-});
-
-const staticPatches = ObjectExtensions.patches;
-
-export const ObjectPrototypeExtensions = new Patch(Object.prototype, {
-  [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)
-      }
-    }
-  },
-})

package/src/reflectextensions.js

@@ -1,118 +0,0 @@
-import { Patch } from '@nejs/extension'
-import { ObjectExtensions } from './objectextensions.js'
-
-const { isObject } = ObjectExtensions.patches
-
-/**
- * The `ReflectExtensions` class is a patch applied to the built-in JavaScript
- * `Reflect` object. It extends `Reflect` with additional utility methods that
- * enhance its capabilities. These methods provide more advanced ways of
- * interacting with object properties, such as checking for the presence of
- * multiple keys at once (`hasAll`) or verifying if at least one specified key
- * exists in an object (`hasSome`). This class is part of the `@nejs/extension`
- * library and is designed to offer these extended functionalities in a way
- * that is consistent with the existing `Reflect` API, making it intuitive for
- * developers who are already familiar with standard reflection methods in
- * JavaScript.
- */
-export const ReflectExtensions = new Patch(Reflect, {
-  /**
-   * The function checks if an object has all the specified keys.
-   *
-   * @param object - The `object` parameter is the object that we want to
-   * check if it has all the specified keys.
-   * @param keys - The `keys` parameter is a rest parameter, which means
-   * it can accept any number of arguments. In this case, it is expected
-   * to receive multiple keys as arguments.
-   * @returns a boolean value.
-   */
-  hasAll(object, ...keys) {
-    return Object.isObject(object) && (keys.flat(Infinity)
-      .map(key => Reflect.has(object, key))
-      .every(has => has)
-    )
-  },
-
-  /**
-   * Fetches all descriptors of an object, including those mapped to a
-   * symbol descriptor value.
-   *
-   * @param {object} object the object from whose descriptors need to be
-   * retrieved.
-   * @returns {object} with keys mapped to object descriptors
-   * @throws {TypeError} if the supplied `object` is null or not an object
-   * a TypeError exception will be thrown
-   */
-  ownDescriptors(object) {
-    if (!isObject(object)) {
-      throw new TypeError('The supplied object must be non-null and an object')
-    }
-
-    const result = {}
-
-    const keys = Reflect.ownKeys(object)
-
-    for (const key of keys) {
-      result[key] = Object.getOwnPropertyDescriptor(key)
-    }
-
-    return result
-  },
-
-  /**
-   * The function checks if an object has at least one of the specified keys.
-   *
-   * @param object - The `object` parameter is the object that we want to check
-   * for the presence of certain keys.
-   * @param keys - The `keys` parameter is a rest parameter, which means it can
-   * accept any number of arguments. These arguments are the keys that we want
-   * to check if they exist in the `object`.
-   * @returns The function `hasSome` returns a boolean value indicating whether
-   * at least one of the keys provided as arguments exists in the given object.
-   */
-  hasSome(object, ...keys) {
-    return isObject(object) && (keys.flat(Infinity)
-      .map(key => Reflect.has(object, key))
-      .some(has => has)
-    )
-  },
-
-  /**
-   * Retrieves an array of [key, descriptor] pairs for each property of the
-   * provided object. This method is akin to `Object.entries` but includes
-   * property descriptors instead of the property values. It's useful for cases
-   * where you need detailed information about properties, including their
-   * configurability, enumerability, and accessors.
-   *
-   * @param {object} object - The object whose property entries are to be
-   * retrieved.
-   * @returns {Array} An array of [key, descriptor] pairs, where each pair
-   * consists of the property name (key) and its descriptor. Returns an empty
-   * array if the input is not a valid object.
-   */
-  entries(object) {
-    if (!object || typeof object !== 'object') { return [] }
-
-    return Reflect.ownKeys(object).map(key => [
-      key, Object.getOwnPropertyDescriptor(object, key)
-    ])
-  },
-
-  /**
-   * Retrieves an array of values from the property descriptors of the given
-   * object. This method works similarly to `Object.values` but operates on
-   * property descriptors instead. It's useful when you need the values of
-   * properties including getters, setters, and other descriptor-specific
-   * attributes.
-   *
-   * @param {object} object - The object whose property values are to be
-   * retrieved.
-   * @returns {Array} An array of values extracted from the object's property
-   * descriptors. The values correspond to the `value` attribute in each
-   * property's descriptor. Returns an empty array if the input is not a valid
-   * object.
-   */
-  values(object) {
-    return Reflect.entries.map(([,value]) => value)
-  }
-})

package/src/stringextensions.js

@@ -1,166 +0,0 @@
-import { Patch } from '@nejs/extension';
-
-const parenthesisPair = ['(', ')'];
-
-/**
- * `StringExtensions` is a patch for the JavaScript built-in `String` class. It
- * adds utility methods to the `String` class without modifying the global namespace
- * directly. This patch includes methods for key validation, object type checking,
- * and retrieving the string tag of an object. These methods are useful for
- * enhancing the capabilities of the standard `String` class with additional
- * utility functions.
- */
-export const StringExtensions = new Patch(String, {
-  /**
-   * The `isString` method does exactly what one would it expect. It returns
-   * true if the string matches typeof or instanceof as a string.
-   *
-   * @param {*} value checks to see if the `value` is a string
-   * @returns {boolean} `true` if it is a `String`, `false` otherwise
-   */
-  isString(value) {
-    if (value && (typeof value === 'string' || value instanceof String)) {
-      return value.length > 0
-    }
-    return false
-  },
-
-  /**
-   * A getter property that returns a pair of parentheses as an array.
-   * This property can be used when operations require a clear distinction
-   * between the opening and closing parentheses, such as parsing or
-   * matching balanced expressions in strings.
-   *
-   * @returns {[string, string]} An array containing a pair of strings: the
-   * opening parenthesis '(' as the first element, and the closing parenthesis
-   * ')' as the second element.
-   */
-  get parenthesisPair() {
-    return ['(', ')'];
-  },
-
-  /**
-   * A getter property that returns a pair of square brackets as an array.
-   * This property is particularly useful for operations that require a clear
-   * distinction between the opening and closing square brackets, such as
-   * parsing arrays in strings or matching balanced expressions within
-   * square brackets.
-   *
-   * @returns {[string, string]} An array containing a pair of strings: the
-   * opening square bracket '[' as the first element, and the closing square
-   * bracket ']' as the second element.
-   */
-  get squareBracketsPair() {
-    return ['[', ']'];
-  },
-
-  /**
-   * A getter property that returns a pair of curly brackets as an array.
-   * This property is particularly useful for operations that require a clear
-   * distinction between the opening and closing curly brackets, such as
-   * parsing objects in strings or matching balanced expressions within
-   * curly brackets. The returned array consists of the opening curly bracket
-   * '{' as the first element, and the closing curly bracket '}' as the
-   * second element.
-   *
-   * @returns {[string, string]} An array containing a pair of strings: the
-   * opening curly bracket '{' as the first element, and the closing curly
-   * bracket '}' as the second element.
-   */
-  get curlyBracketsPair() {
-    return ['{', '}'];
-  },
-});
-
-/**
- * `StringPrototypeExtensions` provides a set of utility methods that are
- * added to the `String` prototype. This allows all string instances to
- * access new functionality directly, enhancing their capabilities beyond
- * the standard `String` class methods. These extensions are applied using
- * the `Patch` class from '@nejs/extension', ensuring that they do not
- * interfere with the global namespace or existing properties.
- *
- * The extensions include methods for extracting substrings based on
- * specific tokens, checking the presence of certain patterns, and more,
- * making string manipulation tasks more convenient and expressive.
- */
-export const StringPrototypeExtensions = new Patch(String.prototype, {
-  [Patch.kMutablyHidden]: {
-    /**
-     * Extracts a substring from the current string, starting at a given offset
-     * and bounded by specified opening and closing tokens. This method is
-     * particularly useful for parsing nested structures or quoted strings,
-     * where the level of nesting or the presence of escape characters must
-     * be considered.
-     *
-     * @param {number} offset The position in the string from which to start the
-     * search for the substring.
-     * @param {[string, string]} tokens An array containing two strings: the
-     * opening and closing tokens that define the boundaries of the substring
-     * to be extracted.
-     * @returns {Object} An object with two properties: `extracted`, the
-     * extracted substring, and `newOffset`, the position in the original
-     * string immediately after the end of the extracted substring. If no
-     * substring is found, `extracted` is `null` and `newOffset` is the same
-     * as the input offset.
-     */
-    extractSubstring(offset = 0, tokens = parenthesisPair) {
-      let [openToken, closeToken] = tokens;
-      let depth = 0;
-      let start = -1;
-      let end = -1;
-      let leadingToken = '';
-      let firstToken = 0;
-
-      for (let i = offset; i < this.length; i++) {
-        const char = this[i];
-
-        if (char === openToken) {
-          depth++;
-          if (start === -1)
-            start = i;
-        }
-        else if (char === closeToken) {
-          depth--;
-          if (depth === 0) {
-            end = i;
-            break;
-          }
-        }
-      }
-
-      let lRange = [
-        Math.max(0, start - 100),
-        start
-      ];
-      let leading = [...this.substring(lRange[0], lRange[1])].reverse().join('')
-      let reversedLeadingToken;
-
-      try {
-        reversedLeadingToken = /([^ \,\"\'\`]+)/.exec(leading)[1] ?? '';
-        leadingToken = [...reversedLeadingToken].reverse().join('');
-      }
-      catch(ignored) { }
-
-      if (start !== -1 && end !== -1) {
-        const sliceRange = [start, end + 1];
-        const extracted = this.slice(sliceRange[0], sliceRange[1]);
-
-        return {
-          extracted,
-          range: [start, end],
-          newOffset: end + 1,
-          leadingToken,
-        };
-      }
-      else {
-        return {
-          extracted: null,
-          range: [start, end],
-          newOffset: offset,
-          leadingToken,
-        };
-      }
-    },
-  },
-})

package/src/symbolextensions.js

@@ -1,69 +0,0 @@
-import { Patch } from '@nejs/extension';
-
-/**
- * `SymbolExtensions` is a patch for the JavaScript built-in `Symbol` class. It
- * adds utility methods to the `Symbol` class without modifying the global namespace
- * directly. This patch includes methods for key validation, object type checking,
- * and retrieving the string tag of an object. These methods are useful for
- * enhancing the capabilities of the standard `Symbol` class with additional
- * utility functions.
- */
-export const SymbolExtensions = new Patch(Symbol, {
-  /**
-   * The `isSymbol` method does exactly what one would it expect. It returns
-   * true if the string matches typeof or instanceof as a symbol.
-   *
-   * @param {*} value checks to see if the `value` is a string
-   * @returns {boolean} `true` if it is a `Symbol`, `false` otherwise
-   */
-  isSymbol(value) {
-    return value && (typeof value === 'symbol');
-  },
-
-  /**
-   * Returns true if the supplied value is a Symbol created using
-   * `Symbol.for()`.
-   *
-   * @param {any} value assumption is that the supplied value is of type
-   * 'symbol' however, unless `allowOnlySymbols` is set to `true`, `false`
-   * will be returned for any non-symbol values.
-   * @param {boolean} allowOnlySymbols true if an error should be thrown
-   * if the supplied value is not of type 'symbol'
-   * @returns true if the symbol is registered, meaning, none of the spec
-   * static symbols (`toStringTag`, `iterator`, etc...), and no symbols
-   * created by passing a value directly to the Symbol function, such as
-   * `Symbol('name')`
-   */
-  isRegistered(value, allowOnlySymbols = false) {
-    if (!Symbol.isSymbol(value)) {
-      if (allowOnlySymbols) {
-        throw new TypeError('allowOnlySymbols specified; value is not a symbol')
-      }
-      return false
-    }
-
-    return Symbol.keyFor(value) !== undefined
-  },
-
-  /**
-   * A function that returns true if the symbol is not registered, meaning,
-   * any of the spec static symbols (`toStringTag`, `iterator`, etc...), and
-   * any symbols created by passing a value directly to the `Symbol` function,
-   * such as `Symbol('name')`.
-   *
-   * @param {any} value assumption is that the supplied value is of type
-   * 'symbol' however, unless allowOnlySymbols is set to true, false will
-   * be returned for any non-symbol values.
-   * @param {boolean} allowOnlySymbols true if an error should be thrown
-   * if the supplied value is not of type 'symbol'
-   * @returns true if the symbol is not registered, meaning, any of the
-   * spec static symbols (`toStringTag`, `iterator`, etc...), and any symbols
-   * created by passing a value directly to the `Symbol` function, such as
-   * `Symbol('name')`
-   * @returns true if the `value` in question is both a `symbol` and has
-   * returns `undefined` if passed to `Symbol.keyFor`
-   */
-  isNonRegistered(value, allowOnlySymbols = false) {
-    return !Symbol.isRegistered(value, allowOnlySymbols)
-  },
-});