@nejs/basic-extensions 2.7.0 → 2.8.0

package/src/arrayextensions.js

@@ -1,75 +0,0 @@
-import { Patch } from '@nejs/extension'
-
-/**
- * The `ArrayPrototypeExtensions` patch extends the prototype of the built-in
- * JavaScript `Array` with additional properties for convenience and improved
- * readability. By applying this patch, all array instances gain new getter
- * properties `first` and `last`, which provide quick access to the first and
- * last elements of the array, respectively. This enhancement simplifies common
- * operations on arrays and makes code more expressive and concise.
- */
-export const ArrayPrototypeExtensions = new Patch(Array.prototype, {
-  [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
-
-      for (let entry of entries) {
-        if (findFn(entry[VALUE])) {
-          return entry
-        }
-      }
-
-      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 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

@@ -1,225 +0,0 @@
-import { Patch } from '@nejs/extension'
-import { ObjectExtensions } from './objectextensions.js'
-
-const { getStringTag } = ObjectExtensions.patches
-
-/**
- * The `FunctionExtensions` class is a patch applied to the built-in JavaScript
- * `Function` constructor. It extends `Function` with additional utility methods
- * for determining the specific type or nature of function-like objects. These
- * methods allow developers to distinguish between classes, regular functions,
- * async functions, and arrow functions in a more intuitive and straightforward
- * manner. This class is part of the `@nejs/extension` library and enhances the
- * capabilities of function handling and introspection in JavaScript.
- */
-export const FunctionExtensions = new Patch(Function, {
-  /**
-   * 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.
-   *
-   * @param {*} value - The value to be checked.
-   * @returns {boolean} Returns `true` if the value is an async function,
-   * otherwise `false`.
-   */
-  isAsync(value) {
-    const stringTag = /(\w+)]/g.exec(Object.prototype.toString.call(value))[1]
-    return (
-      value instanceof Function &&
-      stringTag.includes('Async')
-    )
-  },
-
-  /**
-   * The function checks if a given value is an async generator function
-   *
-   * @param {any} value - The `value` parameter is the value that we want to
-   * check if it is a generator function.
-   * @returns {boolean} `true` if the value is an instance of a function and
-   * its string tag is 'AsyncGeneratorFunction', otherwise it returns `false`.
-   */
-  isAsyncGenerator(value) {
-    const stringTag = getStringTag(value)
-
-    return (
-      value instanceof Function &&
-      stringTag == 'AsyncGeneratorFunction'
-    )
-  },
-
-  /**
-   * 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.
-   *
-   * @param {*} value - The value to be checked.
-   * @returns {boolean} Returns `true` if the value is an arrow function,
-   * otherwise `false`.
-   */
-  isBigArrow(value) {
-    return (
-      value instanceof Function &&
-      String(value).includes('=>') &&
-      !String(value).startsWith('bound') &&
-      !Reflect.has(value, 'prototype')
-    );
-  },
-
-  /**
-   * 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.
-   *
-   * @param {*} value - The value to be checked, typically a function.
-   * @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.
-   */
-  isBound(value) {
-    return (
-      value instanceof Function &&
-      String(value).startsWith('bound') &&
-      !Reflect.has(value, 'prototype')
-    )
-  },
-
-  /**
-   * 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.
-   *
-   * @param {*} value - The value to be checked.
-   * @returns {boolean} Returns `true` if the value is a class, otherwise
-   * `false`.
-   */
-  isClass(value) {
-    return value instanceof Function && !!/^class\s/.exec(String(value))
-  },
-
-  /**
-   * 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.
-   *
-   * @param {*} value - The value to be checked.
-   * @returns {boolean} Returns `true` if the value is a regular function,
-   * otherwise `false`.
-   */
-  isFunction(value) {
-    return value instanceof Function && !Function.isClass(value);
-  },
-
-  /**
-   * The function checks if a given value is a generator function
-   *
-   * @param {any} value - The `value` parameter is the value that we want to
-   * check if it 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`.
-   */
-  isGenerator(value) {
-    const stringTag = getStringTag(value)
-
-    return (
-      value instanceof Function &&
-      stringTag == 'GeneratorFunction'
-    )
-  },
-})
-
-export const FunctionPrototypeExtensions = new Patch(Function.prototype, {
-  [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/globals.js

@@ -1,196 +0,0 @@
-import { Patch } from '@nejs/extension'
-import { FunctionExtensions } from './functionextensions.js'
-
-const { isClass, isFunction } = FunctionExtensions.patches
-const CustomInspect = Symbol.for('nodejs.util.inspect.custom')
-
-export const GlobalFunctionsAndProps = new Patch(globalThis, {
-  /**
-   * Transforms an object to mimic a specified prototype, altering its type
-   * conversion and inspection behaviors. This function is especially useful
-   * for creating objects that need to behave like different primitive types
-   * under various operations.
-   *
-   * @param {Object} object - The object to be transformed.
-   * @param {Function|Object} [prototype=String.prototype] - The prototype or
-   * class to emulate. If a function is provided, its prototype is used.
-   * Defaults to String.prototype.
-   * @param {Function} [toPrimitive=(hint, val) => String(val)] - A function
-   * defining how the object should be converted to a primitive value. It
-   * receives a type hint ('number', 'string', or 'default') and the object,
-   * returning the primitive value.
-   * @returns {Object|null} The transformed object, or null if neither a class
-   * nor a prototype could be derived from the provided prototype parameter.
-   */
-  maskAs(object, classPrototype, options) {
-    const {
-      prototype,
-      toPrimitive
-    } = GenericMask({...options, prototype: classPrototype})
-
-    const base = { configurable: true, enumerable: false }
-    const proto = isFunction(prototype) ? prototype.prototype : prototype
-    const klass = isClass(prototype) ? prototype : proto?.constructor
-
-    if (!klass && !proto) {
-      return null
-    }
-
-    Object.setPrototypeOf(object, proto)
-    Object.defineProperties(object, {
-      valueOf: {
-        value() { return String(toPrimitive('default', object)) }, ...base },
-
-      [Symbol.toPrimitive]: {
-        value(hint) { return toPrimitive(hint, object) }, ...base
-      },
-      [Symbol.toStringTag]: { value: klass.name, ...base },
-      [Symbol.species]: { get() { return klass }, ...base },
-      [CustomInspect]: { ...base, value(depth, opts, inspect) {
-        return inspect(this[Symbol.toPrimitive](), { ...opts, depth })
-      }}
-    })
-
-    return object
-  },
-
-  /**
-   * Masks an object as a string-like object by setting its prototype to
-   * String and defining how it converts to primitive types. This is
-   * particularly useful when an object needs to behave like a string in
-   * certain contexts, such as type coercion or logging.
-   *
-   * @param {Object} object - The object to be masked as a string.
-   * @param {string} [stringKey='value'] - The object property key used for
-   * the string representation. Defaults to 'value'.
-   * @param {Function} [toPrimitive] - Optional custom function for primitive
-   * conversion. If omitted, a default function handling various conversion
-   * hints is used.
-   * @returns {Object|null} The string-masked object, or null if the object
-   * doesn't have the specified stringKey property.
-   */
-  maskAsString(
-    object,
-    stringKey,
-    toPrimitive
-  ) {
-    if (object && Reflect.has(object, stringKey)) {
-      return maskAs(object, StringMask(stringKey ?? 'value', toPrimitive))
-    }
-
-    return null
-  },
-
-  /**
-   * Masks an object as a number-like object. This allows the object to
-   * behave like a number in operations like arithmetic and type coercion.
-   * It sets the prototype to Number and defines custom conversion behavior.
-   *
-   * @param {Object} object - The object to be masked as a number
-   * representation. Defaults to 'value'.
-   * @param {Function} [toPrimitive] - Optional custom function for primitive
-   * conversion. If not provided, a default function handling different
-   * conversion hints is used.
-   * @returns {Object|null} The number-masked object, or null if the object
-   * doesn't have the specified numberKey property.
-   */
-  maskAsNumber(
-    object,
-    numberKey,
-    toPrimitive
-  ) {
-    if (object && Reflect.has(object, numberKey)) {
-      return maskAs(object, NumberMask(numberKey ?? 'value', toPrimitive))
-    }
-
-    return null
-  },
-
-  /**
-   * Generates options for generic masking of an object, providing defaults for
-   * prototype and toPrimitive function if not specified.
-   *
-   * @param {Object} options - The options object including prototype,
-   * targetKey, and toPrimitive function.
-   * @returns {Object} The options object with defaults applied as necessary.
-   */
-  GenericMask({ prototype, targetKey = 'value', toPrimitive }) {
-    const options = { targetKey, toPrimitive, prototype };
-
-    if (!isFunction(toPrimitive)) {
-      options.toPrimitive = (hint, object) => {
-        let property = object[targetKey];
-        let isNum = (
-          (typeof property === 'number' && Number.isFinite(property)) ||
-          (typeof property === 'string' &&
-            !isNaN(parseFloat(property)) && isFinite(property)
-          )
-        );
-
-        switch (hint) {
-          case 'string':
-            return isNum ? String(property) : (property ?? String(object));
-          case 'number':
-            return isNum ? Number(property) : NaN;
-          case 'default':
-          default:
-            return isNum ? Number(property) : property;
-        }
-      }
-    }
-
-    return options;
-  },
-
-  /**
-   * Generates options for string masking of an object, providing a default
-   * toPrimitive function if not specified.
-   *
-   * @param {string} targetKey - The object property key for string
-   * representation.
-   * @param {Function} toPrimitive - Custom function for primitive conversion.
-   * @returns {Object} Options for string masking.
-   */
-  StringMask(targetKey, toPrimitive) {
-    const options = { targetKey, toPrimitive, prototype: String.prototype }
-
-    if (!isFunction(toPrimitive)) {
-      options.toPrimitive = function toPrimitive(hint, object) {
-        switch (hint) {
-          case 'default': return object[targetKey]
-          case 'number': return parseInt(object[targetKey], 36)
-          case 'string': return String(object[targetKey])
-          default: return object
-        }
-      }
-    }
-
-    return options
-  },
-
-  /**
-   * Generates options for number masking of an object, providing a default
-   * toPrimitive function if not specified.
-   *
-   * @param {string} targetKey - The object property key for number
-   * representation.
-   * @param {Function} toPrimitive - Custom function for primitive conversion.
-   * @returns {Object} Options for number masking.
-   */
-  NumberMask(targetKey, toPrimitive) {
-    const options = { targetKey, toPrimitive, prototype: Number.prototype }
-
-    if (!isFunction(toPrimitive)) {
-      options.toPrimitive = function toPrimitive(hint, object) {
-        switch (hint) {
-          case 'default': return object[targetKey]
-          case 'number': return Number(object[targetKey])
-          case 'string': return String(object[targetKey])
-          default: return object
-        }
-      }
-    }
-
-    return options
-  },
-})

package/src/mapextensions.js

@@ -1,32 +0,0 @@
-import { Patch } from '@nejs/extension';
-
-export const MapPrototypeExtensions = new Patch(Map.prototype, {
-  [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
-      }
-    },
-  },
-})