@nejs/basic-extensions 1.6.1 → 1.7.0

package/dist/mjs/newClasses/descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.js","sourceRoot":"","sources":["../../../src/newClasses/descriptor.js"],"names":[],"mappings":"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"}

package/dist/mjs/newClasses/iterable.d.ts

@@ -0,0 +1,125 @@
+/**
+ * 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.
+ */
+export class Iterable {
+    /**
+     * 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: any): boolean;
+    /**
+     * 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: Iterable | any, ...moreElements: any[]);
+    /**
+     * 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(): any[];
+    /**
+     * 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](): Generator;
+    /**
+     * 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](): string;
+    #private;
+}
+/**
+ * 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.
+ */
+export class Iterator {
+    /**
+     * Creates a new `Iterator` object instance.
+     *
+     * @param {object} iterable any object that has a `[Symbol.iterator]`
+     * property assigned to a generator function.
+     * @param {function} mapEach when provided `mapEach` is a callback that
+     * takes an entry as input and receives one as output.
+     */
+    constructor(iterable: object, mapEach: Function);
+    /**
+     * 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(): array;
+    /**
+     * Returns the actual iterable object passed to the constructor that
+     * created this instance.
+     *
+     * @returns {object} the object containing the `[Symbol.iterator]`
+     */
+    get iterable(): object;
+    /**
+     * 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(): any;
+    /**
+     * Resets the iterator to the beginning allowing it to be
+     * iterated over again.
+     */
+    reset(): void;
+    /**
+     * 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](): Iterator;
+    /**
+     * 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](): string;
+    #private;
+}
+export const IterableExtensions: Extension;
+export const IteratorExtensions: Extension;
+import { Extension } from '@nejs/extension';

package/dist/mjs/newClasses/iterable.js

@@ -0,0 +1,199 @@
+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.
+ */
+export 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;
+    }
+    /**
+     * 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]';
+    }
+}
+/**
+ * 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.
+ */
+export class Iterator {
+    /**
+     * A private function that when provided has the following signature:
+     * `function mapEach(entry) -> entry`. This allows any changes to be made
+     * to each element, conditionally and programmatically, as needed before
+     * they are returned to the called code.
+     */
+    #mapEach = undefined;
+    /**
+     * Creates a new `Iterator` object instance.
+     *
+     * @param {object} iterable any object that has a `[Symbol.iterator]`
+     * property assigned to a generator function.
+     * @param {function} mapEach when provided `mapEach` is a callback that
+     * takes an entry as input and receives one as output.
+     */
+    constructor(iterable, mapEach) {
+        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]();
+        this.#mapEach = typeof mapEach === 'function' ? mapEach : undefined;
+    }
+    /**
+     * 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 input = this.#iterator.next();
+        let output = input;
+        if (output.done) {
+            return { value: undefined, done: true };
+        }
+        else {
+            if (this.#mapEach && typeof this.#mapEach === 'function') {
+                output.value = this.#mapEach(input.value);
+            }
+            return { value: output.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;
+}
+export const IterableExtensions = new Extension(Iterable);
+export const IteratorExtensions = new Extension(Iterator);
+//# sourceMappingURL=iterable.js.map

package/dist/mjs/newClasses/iterable.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"iterable.js","sourceRoot":"","sources":["../../../src/newClasses/iterable.js"],"names":[],"mappings":"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"}

package/dist/mjs/newClasses/refmap.d.ts

@@ -0,0 +1,238 @@
+/**
+ * RefMap class extends the standard Map object to manage a collection of
+ * WeakRef values mapped to strong keys. It provides additional functionality
+ * such as objectification of values and various utility methods.
+ *
+ * Unlike standard Maps or Objects, RefMap stores weak references to objects,
+ * allowing them to be garbage-collected if there are no other references to
+ * them. This behavior is different from Maps and standard Objects, which
+ * maintain strong references to their elements.
+ *
+ * @extends Map
+ */
+export class RefMap extends Map<any, any> {
+    constructor(...args: any[]);
+    /**
+     * Method to control whether the RefMap should objectify its values. When
+     * objectifying, primitive values (number, string, boolean, bigint) are
+     * converted to their respective object types, which allows them to be used as
+     * WeakRef targets.
+     *
+     * @param {boolean} setObjectification - Flag to enable or disable
+     * objectification.
+     * @returns {RefMap} - The current RefMap instance to allow method chaining.
+     */
+    objectifying(setObjectification?: boolean): RefMap;
+    /**
+     * Setting this value to true, will cause all set values to the Map to
+     * be analyzed for validity as a candidate to be wrapped in a `WeakRef`
+     * object. If true, and if possible, the object will be turned into an
+     * `Object` variant first.
+     *
+     * @param {boolean} value - The new state to set for objectifyValues.
+     */
+    set objectifyValues(value: boolean);
+    /**
+     * Returns the state indicating whether or not `RefMap` will attempt to
+     * convert non-valid primitives into targets that are valid input for
+     * new `WeakRef` object instances. If this value is `false` then no
+     * *objectification* will occur.
+     *
+     * @returns {boolean} The current state of objectifyValues.
+     */
+    get objectifyValues(): boolean;
+    /**
+     * The function converts a JavaScript Map object into a regular JavaScript
+     * object, handling invalid keys by converting them to strings.
+     *
+     * @returns {object} an object; keys that are not either a `String` or a
+     * `Symbol` will be converted to a string.
+     */
+    asObject(): object;
+    /**
+     * The `get` function retrieves a value from a map and returns it, or returns a
+     * default value if the value is null or undefined. The actual retrieved value
+     * is a dereferenced `WeakRef`. If the result is `undefined` and this is not the
+     * expected response, it is likely the value has been garbage collected.
+     *
+     * @param {any} key - The key parameter is the key of the value you want to
+     * retrieve from the data structure.
+     * @param {any} defaultValue - The `defaultValue` parameter is the value that
+     * will be returned if the key does not exist in the map or if the value
+     * associated with the key has been garbage collected (i.e., it no longer
+     * exists).
+     * @returns The method is returning the value associated with the given key.
+     * If the value is not found or if it has been garbage collected (deref()
+     * returns null), then the defaultValue is returned.
+     */
+    get(key: any, defaultValue: any): any;
+    /**
+     * Overrides the set method of `Map`. Adds a value to the `RefMap`,
+     * converting it to a `WeakRef`. Throws an error if the value is not a
+     * valid `WeakRef` target (e.g., `null`, `undefined`, or a registered
+     * `symbol`). If {@link objectifyValues} is enabled, an attempt to convert
+     * primitives to their object variants will be made. These are `numbers`,
+     * `strings`, `boolean` values and `bigint`s.
+     *
+     * @param {*} key - The `key` to be set on the `RefMap`
+     * @param {*} value - The value to be associated with the `key`
+     * @throws {TypeError} If the value is not a valid WeakRef target.
+     */
+    set(key: any, value: any): void;
+    /**
+     * Sets multiple values at a single time. The format is an array of array
+     * or rather an array of {@link Object.entries} (for example,
+     * `[[key1,value1], [key2,value2]]`). For each entry pair, if the length
+     * is not 2, either missing a key or value, it will be skipped.
+     *
+     * @param {Iterable} values - An iterable of values to add to the RefMap.
+     * @throws {TypeError} If the supplied values are falsey or non-iterable.
+     * @returns {RepMap} returns `this` to allow for chaining
+     */
+    setAll(entries: any): RepMap;
+    /**
+     * Removes all elements from the RefMap that have been garbage collected
+     * (i.e., their WeakRef no longer points to an object).
+     *
+     * @returns {RefMap} - The current RefMap instance to allow method chaining.
+     */
+    clean(): RefMap;
+    /**
+     * Executes a provided function once for each value in the RefMap. The callback
+     * function receives the dereferenced value, the value again (as RefMap doesn't
+     * use keys), and the RefMap itself. This method provides a way to iterate over
+     * and apply operations to the values stored in the RefMap, taking into account
+     * that they are weak references and may have been garbage-collected.
+     *
+     * @param {Function} forEachFn - Function to execute for each element. It
+     * takes three arguments: element, element (again, as RefMap has no key), and
+     * the RefMap itself.
+     * @param {*} thisArg - Value to use as `this` when executing `forEachFn`.
+     */
+    entries(): Iterator;
+    /**
+     * Iterate over the items in the map and pass them to the supplied
+     * function ala `Map.prototype.forEach`. Note however, there are no
+     * indexes on Maps and as such, the index parameter of the callback
+     * will always be the value's key. Subsequently the `array` or third
+     * parameter will receive the map instance rather than an array.
+     *
+     * @param {function} forEachFn the function to use for each element in
+     * the set.
+     * @param {object} thisArg the `this` argument to be applied to each
+     * invocation of the `forEachFn` callback. Note, this value is unable
+     * to be applied if the `forEachFn` is a big arrow function
+     */
+    forEach(forEachFn: Function, thisArg: object): void;
+    /**
+     * Returns an iterator for the values in the RefMap. Each value is
+     * dereferenced from its WeakRef before being returned. This method allows
+     * iterating over he set's values, similar to how one would iterate over
+     * values in a standard Map or Array, but with the understanding that the
+     * values are weakly referenced and may no longer exist (in which case
+     * they are skipped).
+     *
+     * @returns {Iterator} An iterator for the values.
+     */
+    values(): Iterator;
+    /**
+     * Determines whether an element with the specified value exists in the
+     * `RefMap`. For non-objectified sets, this method checks if the dereferenced
+     * values of the map include the specified value.
+     *
+     * For objectified sets, strict is set to false which uses loose
+     * equality to allow for things like `Object(5)` to equal `5`. This is important
+     * because otherwise primitives could not be weakly referenced. In the grand
+     * scheme of things, this is only useful if the objectified value is the
+     * one being referenced.
+     *
+     * @param {*} value - The value to check for presence in the RefMap.
+     * @param {boolean} strict - if `true`, the default, then the supplied value
+     * is hard compared to the dereferenced value (`===`). If `false`, then a
+     * loose comparison is used (`==`)
+     * @returns {boolean} - True if an element with the specified value exists
+     * in the RefMap, false otherwise.
+     */
+    hasValue(value: any, strict?: boolean): boolean;
+    /**
+     * The `filter` function filters the entries of a `RefMap` object based on
+     * a given filter function. The dereferenced entries of the values of the map
+     * will be passed to the function rather than a `WeakRef` itself.
+     *
+     * A new resulting entry set will be generated and a new `RefMap` will be made
+     * from these entries and returned. Note that this function never returns
+     * `null`
+     *
+     * @param {function} filterFn - The `filterFn` parameter is a function that
+     * will be used to filter the entries in the `RefMap`. It will be called with
+     * three arguments: the value of the current entry, the key of the current
+     * entry, and the `RefMap` itself. The function should return `true`
+     * @param {object} thisArg - The `thisArg` parameter is an optional argument
+     * that specifies the value to be used as `this` when executing the
+     * `filterFn` function. It allows you to explicitly set the context in which
+     * the `filterFn` function is called. If `thisArg` is not provided, `this
+     * @returns {array} The `filter` method is returning an array of filtered map
+     * entries
+     */
+    filter(filterFn: Function, thisArg: object): array;
+    /**
+     * The `find` function iterates over a map and calls a given function on
+     * each value, returning the first value for which the function returns
+     * a truthy value.
+     *
+     * The function signature of `findFn` is
+     * ```
+     * function findFn(value, key, map)
+     * ```
+     * 'value' is passed to findFn up to two times; first with the `WeakRef`
+     * value, second with the result of {@link WeakRef.deref}. If `findFn`
+     * returns true for either of these the dereferenced value will be
+     * returned from the call to {@link RefMap.find}.
+     * `key` represents the key object that the value is mapped to.
+     * `map` is simply a reference to `this` map.
+     *
+     * @param findFn - `findFn` is a function that will be called for each
+     * element in the map. It takes three arguments: `ref`, `key`, and `map`;
+     * where `ref` is the value of the current element in the map, `key` is
+     * the key of the current element, and `map` is a reference to the instance
+     * being searched.
+     * @param thisArg - The `thisArg` parameter is the value to be used as
+     * the `this` value when executing the `findFn` function. It allows you
+     * to specify the context in which the `findFn` function should be called.
+     * @returns the first dereferenced value that satisfies the condition
+     * specified by the `findFn` function. If no value satisfies the condition,
+     * it returns `null`.
+     */
+    find(findFn: any, thisArg: any): any;
+    /**
+     * Creates a new array or `RefMap` with the results of calling a provided
+     * function on every element in the calling `RefMap`. This method dereferences
+     * each value, applies the `mapFn`, and collects the results. If `toRefMap` is
+     * `true`, a new `RefMap` is returned; otherwise, an array. This method
+     * differs from `Array.map` in handling weak references and the potential to
+     * return a new `RefMap` instead of an array.
+     *
+     * @param {Function} mapFn - Function that produces an element of the new
+     * array or `RefMap`, taking three arguments.
+     * @param {*} thisArg - Value to use as this when executing mapFn.
+     * @param {boolean} toRefMap - Determines if the output should be a new
+     * `RefMap` (`true`) or an array (`false`).
+     * @param {boolean} mirrorObjectification - If `true` and `toRefMap` is
+     * `true`, the new `RefMap` mirrors the objectification setting of the
+     * original.
+     * @returns {Array|RefMap} - A new array or `RefMap` with each element being
+     * the result of the `mapFn`.
+     */
+    map(mapFn: Function, thisArg: any, toRefMap: boolean, mirrorObjectification: boolean): any[] | RefMap;
+    /**
+     * The function returns an iterator that iterates over the entries of an object,
+     * dereferencing any weak references.
+     *
+     * @returns {Iterator} A new iterator object is being returned.
+     */
+    [Symbol.iterator](): Iterator;
+    #private;
+}
+export const RefMapExtensions: Extension;
+import { Iterator } from './iterable.js';
+import { Extension } from '@nejs/extension';