@nejs/basic-extensions 1.4.1 → 1.5.0

package/dist/mjs/globals.js

@@ -3,43 +3,22 @@ import { FunctionExtensions } from './functionextensions.js';
 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 { prototype, toPrimitive } = GenericMask({ ...options, prototype: classPrototype });
@@ -51,8 +30,12 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
         }
         Object.setPrototypeOf(object, proto);
         Object.defineProperties(object, {
-            valueOf: { value() { return String(toPrimitive('default', object)); }, ...base },
-            [Symbol.toPrimitive]: { value(hint) { return toPrimitive(hint, object); }, ...base },
+            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) {
@@ -62,18 +45,19 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
         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.
+     * 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, stringKey, toPrimitive) {
         if (object && Reflect.has(object, stringKey)) {
@@ -82,17 +66,17 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
         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.
+     * 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, numberKey, toPrimitive) {
         if (object && Reflect.has(object, numberKey)) {
@@ -104,8 +88,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 }) {
@@ -113,12 +97,14 @@ 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)) ||
+                let isNum = ((typeof property === 'number' && Number.isFinite(property)) ||
                     (typeof property === 'string' &&
-                        !isNaN(parseFloat(property)) && isFinite(property));
+                        !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;
@@ -128,10 +114,11 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
         return options;
     },
     /**
-     * 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.
      */
@@ -150,10 +137,11 @@ export const GlobalFunctionsAndProps = new Patch(globalThis, {
         return options;
     },
     /**
-     * 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.
      */

package/dist/mjs/index.d.ts

@@ -1,5 +1,7 @@
 export function enableAll(owners: any): void;
+export function enableNetNew(): void;
 export function disableAll(owners: any): void;
+export function disableNetNew(): void;
 export const all: {};
 import { ObjectExtensions } from './objectextensions.js';
 import { FunctionExtensions } from './functionextensions.js';
@@ -8,5 +10,10 @@ import { StringExtensions } from './stringextensions.js';
 import { SymbolExtensions } from './symbolextensions.js';
 import { ArrayPrototypeExtensions } from './arrayextensions.js';
 import { GlobalFunctionsAndProps } from './globals.js';
-import { DescriptorExtension } from './descriptor.js';
-export { ObjectExtensions, FunctionExtensions, ReflectExtensions, StringExtensions, SymbolExtensions, ArrayPrototypeExtensions, GlobalFunctionsAndProps, DescriptorExtension };
+import { DescriptorExtensions } from './descriptor.js';
+import { AsyncIterableExtensions } from './asyncIterable.js';
+import { AsyncIteratorExtensions } from './asyncIterable.js';
+import { IterableExtensions } from './iterable.js';
+import { IteratorExtensions } from './iterable.js';
+import { RefSetExtensions } from './refset.js';
+export { ObjectExtensions, FunctionExtensions, ReflectExtensions, StringExtensions, SymbolExtensions, ArrayPrototypeExtensions, GlobalFunctionsAndProps, DescriptorExtensions, AsyncIterableExtensions, AsyncIteratorExtensions, IterableExtensions, IteratorExtensions, RefSetExtensions };

package/dist/mjs/index.js

@@ -4,8 +4,11 @@ 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';
 const Owners = [
     Object,
@@ -17,7 +20,12 @@ const Owners = [
 ];
 const NetNew = [
     GlobalFunctionsAndProps,
-    DescriptorExtension,
+    DescriptorExtensions,
+    AsyncIterableExtensions,
+    AsyncIteratorExtensions,
+    IterableExtensions,
+    IteratorExtensions,
+    RefSetExtensions,
 ];
 export function enableAll(owners) {
     const list = owners || Owners;
@@ -27,9 +35,10 @@ export function enableAll(owners) {
     list.forEach(owner => {
         Patch.enableFor(owner);
     });
-    NetNew.forEach(extension => {
-        extension.apply();
-    });
+    enableNetNew();
+}
+export function enableNetNew() {
+    NetNew.forEach(extension => { extension.apply(); });
 }
 export function disableAll(owners) {
     const list = owners || Owners;
@@ -39,9 +48,10 @@ export function disableAll(owners) {
     list.forEach(owner => {
         Patch.disableFor(owner);
     });
-    NetNew.forEach(extension => {
-        extension.revert();
-    });
+    disableNetNew();
+}
+export function disableNetNew() {
+    NetNew.forEach(extension => { extension.revert(); });
 }
 export const all = (() => {
     let extensions = [
@@ -52,7 +62,7 @@ export const all = (() => {
         SymbolExtensions,
         ArrayPrototypeExtensions,
         GlobalFunctionsAndProps,
-        DescriptorExtension,
+        DescriptorExtensions,
     ];
     const dest = extensions.reduce((accumulator, extension) => {
         Reflect.ownKeys(extension.patchEntries).reduce((_, key) => {
@@ -63,4 +73,4 @@ export const all = (() => {
     }, {});
     return dest;
 })();
-export { ObjectExtensions, FunctionExtensions, ReflectExtensions, StringExtensions, SymbolExtensions, ArrayPrototypeExtensions, GlobalFunctionsAndProps, DescriptorExtension, };
+export { ObjectExtensions, FunctionExtensions, ReflectExtensions, StringExtensions, SymbolExtensions, ArrayPrototypeExtensions, GlobalFunctionsAndProps, DescriptorExtensions, AsyncIterableExtensions, AsyncIteratorExtensions, IterableExtensions, IteratorExtensions, RefSetExtensions, };

package/dist/mjs/iterable.d.ts

@@ -0,0 +1,3 @@
+export const IterableExtensions: Extension;
+export const IteratorExtensions: Extension;
+import { Extension } from '@nejs/extension';

package/dist/mjs/iterable.js

@@ -0,0 +1,184 @@
+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/dist/mjs/objectextensions.js

@@ -8,6 +8,9 @@ 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
@@ -18,6 +21,12 @@ 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];
     },
     /**

package/dist/mjs/refset.d.ts

@@ -0,0 +1,2 @@
+export const RefSetExtensions: Extension;
+import { Extension } from '@nejs/extension';