@nejs/basic-extensions 1.4.1 → 1.5.0

package/src/globals.js

@@ -5,51 +5,22 @@ const { isClass, isFunction } = FunctionExtensions.patchEntries.isClass.computed
 const CustomInspect = Symbol.for('nodejs.util.inspect.custom')
 
 export const GlobalFunctionsAndProps = new Patch(globalThis, {
-  asBigIntObject(
-    bigIntPrimitive
-  ) {
-    const base = { configurable: true, enumerable: false }
-    const object = { value: bigIntPrimitive }
-
-    Object.defineProperties(object, {
-      // @ts-ignore
-      [Symbol.toPrimitive]: { value: function() { return bigIntPrimitive }, ...base },
-      [Symbol.toStringTag]: { value: BigInt.name, ...base },
-      [Symbol.species]: { get() { return BigInt }, ...base },
-      [CustomInspect]: { ...base, value(depth, opts, inspect) {
-        return inspect(this[Symbol.toPrimitive](), { ...opts, depth })
-      }}
-    })
-
-    Object.setPrototypeOf(object, BigInt.prototype)
-
-    Reflect.ownKeys(BigInt.prototype).forEach(key => {
-      if (typeof object[key] !== 'function') {
-        return
-      }
-
-      object[key] = (function (...args) {
-        return BigInt.prototype[key].apply(this, args)
-      }).bind(object.value)
-    })
-
-    return object
-  },
-
   /**
-   * 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.
+   * 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.
+   * @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 {
@@ -67,9 +38,12 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
 
     Object.setPrototypeOf(object, proto)
     Object.defineProperties(object, {
-      valueOf: { value() { return String(toPrimitive('default', object)) }, ...base },
+      valueOf: {
+        value() { return String(toPrimitive('default', object)) }, ...base },
 
-      [Symbol.toPrimitive]: { value(hint) { return toPrimitive(hint, 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) {
@@ -81,18 +55,19 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
   },
 
   /**
-   * 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.
+   * 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.
+   * @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,
@@ -107,17 +82,17 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
   },
 
   /**
-   * 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.
+   * 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 {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.
+   * 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,
@@ -135,8 +110,8 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
    * 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.
+   * @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 }) {
@@ -145,14 +120,18 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
     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)
-                    );
+        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 'string':
+            return isNum ? String(property) : (property ?? String(object));
+          case 'number':
+            return isNum ? Number(property) : NaN;
           case 'default':
           default:
             return isNum ? Number(property) : property;
@@ -164,10 +143,11 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
   },
 
   /**
-   * Generates options for string masking of an object, providing a default toPrimitive
-   * function if not specified.
+   * 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 {string} targetKey - The object property key for string
+   * representation.
    * @param {Function} toPrimitive - Custom function for primitive conversion.
    * @returns {Object} Options for string masking.
    */
@@ -189,10 +169,11 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
   },
 
   /**
-   * Generates options for number masking of an object, providing a default toPrimitive
-   * function if not specified.
+   * 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 {string} targetKey - The object property key for number
+   * representation.
    * @param {Function} toPrimitive - Custom function for primitive conversion.
    * @returns {Object} Options for number masking.
    */
@@ -212,5 +193,4 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
 
     return options
   },
-
 })

package/src/index.js

@@ -4,8 +4,19 @@ import { ReflectExtensions } from './reflectextensions.js'
 import { StringExtensions } from './stringextensions.js'
 import { SymbolExtensions } from './symbolextensions.js'
 import { ArrayPrototypeExtensions } from './arrayextensions.js'
-import { DescriptorExtension } from './descriptor.js'
+import { DescriptorExtensions } from './descriptor.js'
 import { GlobalFunctionsAndProps } from './globals.js'
+import { RefSetExtensions } from './refset.js'
+
+import {
+  AsyncIteratorExtensions,
+  AsyncIterableExtensions
+} from './asyncIterable.js'
+
+import {
+  IteratorExtensions,
+  IterableExtensions
+} from './iterable.js'
 
 import { Patch } from '@nejs/extension'
 
@@ -21,7 +32,12 @@ const Owners = [
 
 const NetNew = [
   GlobalFunctionsAndProps,
-  DescriptorExtension,
+  DescriptorExtensions,
+  AsyncIterableExtensions,
+  AsyncIteratorExtensions,
+  IterableExtensions,
+  IteratorExtensions,
+  RefSetExtensions,
 ]
 
 export function enableAll(owners) {
@@ -35,9 +51,11 @@ export function enableAll(owners) {
     Patch.enableFor(owner)
   })
 
-  NetNew.forEach(extension => {
-    extension.apply()
-  })
+  enableNetNew()
+}
+
+export function enableNetNew() {
+  NetNew.forEach(extension => { extension.apply() })
 }
 
 export function disableAll(owners) {
@@ -51,9 +69,11 @@ export function disableAll(owners) {
     Patch.disableFor(owner)
   })
 
-  NetNew.forEach(extension => {
-    extension.revert()
-  })
+  disableNetNew()
+}
+
+export function disableNetNew() {
+  NetNew.forEach(extension => { extension.revert() })
 }
 
 export const all = (() => {
@@ -66,7 +86,7 @@ export const all = (() => {
     ArrayPrototypeExtensions,
 
     GlobalFunctionsAndProps,
-    DescriptorExtension,
+    DescriptorExtensions,
   ]
 
   const dest = extensions.reduce((accumulator, extension) => {
@@ -91,5 +111,10 @@ export {
   ArrayPrototypeExtensions,
 
   GlobalFunctionsAndProps,
-  DescriptorExtension,
+  DescriptorExtensions,
+  AsyncIterableExtensions,
+  AsyncIteratorExtensions,
+  IterableExtensions,
+  IteratorExtensions,
+  RefSetExtensions,
 }

package/src/iterable.js

@@ -0,0 +1,203 @@
+import { Extension } from '@nejs/extension'
+
+/**
+ * The Iterable class is designed to provide a convenient way to create synchronous
+ * iterable objects. It can be initialized with either an array or individual elements.
+ * This class implements the iterable protocol, allowing instances to be used with
+ * `for...of` loops and other standard JavaScript iteration mechanisms.
+ */
+class Iterable {
+  /**
+   * Private field to store the elements of the iterable.
+   * @private
+   */
+  #elements = [];
+
+  /**
+   * Constructs an instance of Iterable. It can be initialized with either an
+   * iterable object (such as an array, Set, Map, string, or any object
+   * implementing the iterable protocol) or individual elements. If the first
+   * argument is an iterable, the class instance is initialized with the
+   * elements from the iterable, followed by any additional arguments. If the
+   * first argument is not an iterable, all arguments are treated as individual
+   * elements.
+   *
+   * @param {Iterable|*} elementsOrFirstElement - An iterable object or the
+   * first element.
+   * @param {...*} moreElements - Additional elements if the first argument is
+   * not an iterable.
+   */
+  constructor(elementsOrFirstElement, ...moreElements) {
+    if (
+      elementsOrFirstElement != null &&
+      typeof elementsOrFirstElement[Symbol.iterator] === 'function'
+    ) {
+      this.#elements = [...elementsOrFirstElement, ...moreElements];
+    } else {
+      this.#elements = [elementsOrFirstElement, ...moreElements];
+    }
+  }
+
+  /**
+   * Implements the iterable protocol. When an instance of Iterable is used
+   * in a `for...of` loop or spread syntax, this generator function is invoked
+   * to yield the elements one by one in a synchronous manner.
+   *
+   * @returns {Generator} A generator that yields each element of the iterable.
+   */
+  *[Symbol.iterator]() {
+    for (const element of this.#elements) {
+      yield element;
+    }
+  }
+
+  /**
+   * Provides access to the elements as a standard array. Useful for scenarios
+   * where array methods and behaviors are needed.
+   *
+   * @returns {Array} An array containing all the elements of the iterable.
+   */
+  get asArray() {
+    return this.#elements;
+  }
+
+  /**
+   * Ensures that the constructor of this object instance's name
+   * is returned if the string tag for this instance is queried
+   *
+   * @returns {string} the name of the class
+   */
+  get [Symbol.toStringTag]() {
+    return this.constructor.name
+  }
+
+  /**
+   * Being able to create a compliant `Iterator` around any type of iterable
+   * object. This can be wrapped around any type of object that has a
+   * `[Symbol.iterator]` property assigned to a generator function.
+   */
+  static Iterator = class Iterator {
+    /**
+     * Creates a new `Iterator` object instance.
+     *
+     * @param {object} iterable any object that has a `[Symbol.iterator]`
+     * property assigned to a generator function.
+     */
+    constructor(iterable) {
+      if (!iterable || !Reflect.has(iterable, Symbol.iterator)) {
+        throw new TypeError(
+          'Value used to instantiate Iterator is not iterable'
+        );
+      }
+
+      this.#iterable = iterable;
+      this.#iterator = iterable[Symbol.iterator]();
+    }
+
+    /**
+     * Returns a new `Array` derived from the iterable this object
+     * wraps.
+     *
+     * @returns {array} a new `Array` generated from the wrapped
+     * iterable. The method is generated from `Array.from()`
+     */
+    get asArray() {
+      return Array.from(this.#iterable)
+    }
+
+    /**
+     * Returns the actual iterable object passed to the constructor that
+     * created this instance.
+     *
+     * @returns {object} the object containing the `[Symbol.iterator]`
+     */
+    get iterable() {
+      return this.#iterable
+    }
+
+    /**
+     * The function retrieves the next value in the iterator. If the
+     * the iterator has run its course, `reset()` can be invoked to
+     * reset the pointer to the beginning of the iteration.
+     *
+     * @returns {any} the next value
+     */
+    next() {
+      const result = this.#iterator.next();
+      if (result.done) {
+        return { value: undefined, done: true };
+      } else {
+        return { value: result.value, done: false };
+      }
+    }
+
+    /**
+     * Resets the iterator to the beginning allowing it to be
+     * iterated over again.
+     */
+    reset() {
+      this.#iterator = this.#iterable[Symbol.iterator]();
+    }
+
+    /**
+     * The existence of this symbol on the object instances, indicates that
+     * it can be used in `for(.. of ..)` loops and its values can be
+     * extracted from calls to `Array.from()`
+     *
+     * @returns {Iterator} this is returned since this object is already
+     * conforming to the expected JavaScript Iterator interface
+     */
+    [Symbol.iterator]() {
+      return this;
+    }
+
+    /**
+     * Ensures that the constructor of this object instance's name
+     * is returned if the string tag for this instance is queried
+     *
+     * @returns {string} the name of the class
+     */
+    get [Symbol.toStringTag]() {
+      return this.constructor.name
+    }
+
+    /**
+     * The object from which its iterator functionality is derived.
+     *
+     * @type {object}
+     * @private
+     */
+    #iterable = null;
+
+    /**
+     * The results of a call to the iterable's `[Symbol.iterator]`
+     * generator function.
+     *
+     * @type {object}
+     * @private
+     */
+    #iterator = null;
+  }
+
+  /**
+   * Checks if a given value is an iterable. This method determines if the
+   * provided value has a `Symbol.iterator` property that is a generator
+   * function. It's a precise way to identify if the value conforms to the
+   * iterable protocol using a generator function.
+   *
+   * Note: This method specifically checks for generator functions. Some
+   * iterables might use regular functions that return an iterator, which
+   * this method won't identify.
+   *
+   * @param {*} value - The value to be checked for iterability.
+   * @returns {boolean} - Returns true if the value is an iterable implemented
+   * using a generator function, false otherwise.
+   */
+  static isIterable(value) {
+    const type = Object.prototype.toString.call(value?.[Symbol.iterator]);
+    return type === '[object GeneratorFunction]';
+  }
+}
+
+export const IterableExtensions = new Extension(Iterable)
+export const IteratorExtensions = new Extension(Iterable.Iterator)

package/src/objectextensions.js

@@ -9,6 +9,10 @@ import { Patch } from '@nejs/extension';
  * utility functions.
  */
 export const ObjectExtensions = new Patch(Object, {
+  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
@@ -19,6 +23,14 @@ export const ObjectExtensions = new Patch(Object, {
    * @returns {string} - The string tag of the object, indicating its type.
    */
   getStringTag(value) {
+    if (Object.hasStringTag(value)) {
+      return value[Symbol.toStringTag]
+    }
+
+    if (value && (typeof value === 'function')) {
+      return value.name
+    }
+
     return /\s(.+)]/.exec(Object.prototype.toString.call(value))[1];
   },