@nejs/basic-extensions 1.6.1 → 1.7.0

package/src/{descriptor.js → newClasses/descriptor.js}

@@ -1,15 +1,27 @@
 import { Extension } from '@nejs/extension'
-import { ObjectExtensions } from './objectextensions.js'
-import { StringExtensions } from './stringextensions.js'
-import { ReflectExtensions } from './reflectextensions.js'
+import { ObjectExtensions } from '../objectextensions.js'
+import { ReflectExtensions } from '../reflectextensions.js'
 
-const isObject = ObjectExtensions.patchEntries?.isObject?.computed
-const isValidKey = ObjectExtensions.patchEntries?.isValidKey?.computed
-const isString = StringExtensions.patchEntries?.isString?.computed
-const hasSome = ReflectExtensions.patchEntries?.hasSome?.computed
+const { isObject, isValidKey } = ObjectExtensions.patches
+const { hasSome } = ReflectExtensions.patches
 
-class Descriptor {
-  #desc = Descriptor.enigmatic
+export class Descriptor {
+  /**
+   * The default private descriptor value is that of `enigmatic`
+   *
+   * @private
+   * @type {object}
+   */
+  #desc = undefined
+
+  /**
+   * An optionally associated object, usually the parent from which
+   * the descriptor was taken, or undefined if none was able to be
+   * derived.
+   *
+   * @type {object}
+   */
+  #object = undefined
 
   /**
    * Creates a new instance of Descriptor either from another object or
@@ -21,13 +33,21 @@ class Descriptor {
    * on the aforesupplied object.
    */
   constructor(object, key) {
-    this.#desc = object
+    if ((object ?? key) === undefined) {
+      this.#desc = Descriptor.enigmatic
+    }
 
-    if (isObject(object) && isValidKey(key)) {
+    if (Descriptor.isDescriptor(object)) {
+      this.#desc = object
+      this.#object = undefined
+    }
+    else if (isObject(object) && isValidKey(key)) {
       this.#desc = Object.getOwnPropertyDescriptor(object, key)
+      this.#object = object
     }
 
     if (!this.isDescriptor) {
+      console.error('Current descriptor:', this.#desc)
       throw new Error(`Not a valid descriptor:`, this.#desc)
     }
   }
@@ -160,6 +180,18 @@ class Descriptor {
     return this.#desc?.get
   }
 
+  /**
+   * Retrieves the {@link get} function for this accessor and binds it to
+   * the object from which the descriptor was derived, if that value is set.
+   * Otherwise this method is identical to the {@link get} accessor.
+   *
+   * @returns {function} the getter if one is defined. If possible this
+   * getter will be bound the associated and previously set `object`.
+   */
+  get boundGet() {
+    return (isObject(this.#object) ? this.get?.bind(this.#object) : this.get)
+  }
+
   /**
    * Sets the `get` value of this object. If the internal descriptor
    * store is invalid, the value is thrown away
@@ -179,7 +211,19 @@ class Descriptor {
    * is undefined.
    */
   get set() {
-    return this.#desc?.writable
+    return (this.#desc || {}).set
+  }
+
+  /**
+   * Retrieves the {@link set} function for this accessor and binds it to
+   * the object from which the descriptor was derived, if that value is set.
+   * Otherwise this method is identical to the {@link set} accessor.
+   *
+   * @returns {function} the setter if one is defined. If possible this
+   * setter will be bound the associated and previously set `object`.
+   */
+  get boundSet() {
+    return (isObject(this.#object) ? this.set?.bind(this.#object) : this.set)
   }
 
   /**
@@ -192,6 +236,52 @@ class Descriptor {
     (this.#desc || {}).set = value
   }
 
+  /**
+   * The function checks the descriptor's associated object has been set on this
+   * instance of `Descriptor`.
+   *
+   * @returns {boolean} `true` if the `object` property has been set,
+   * `false` otherwise
+   */
+  get hasObject() { return isObject(this.#object) }
+
+  /**
+   * Returns the descriptor's associated `object` value. This is usually the
+   * parent object from which the descriptor was derived. If the value is preset
+   * it will be returned. Undefined will be returned otherwise
+   *
+   * @returns {object} the associated object for this descriptor or undefined
+   * if it has not yet been set.
+   */
+  get object() { return this.#object }
+
+  /**
+   * Sets the descriptor's associated `object` value. This is usually the
+   * parent object from which the descriptor was derived.
+   *
+   * @param {object} value sets the object for which this descriptor is to
+   * be associated with.
+   */
+  set object(value) { this.#object = Object(value) }
+
+  /**
+   * The function returns a string representation of a descriptor object with
+   * additional information about its type when used in the NodeJS repl.
+   *
+   * @param {number} depth - The `depth` parameter is used to specify the
+   * maximum depth to which nested objects and arrays will be formatted. If
+   * the depth is exceeded, the output will be truncated with ellipses.
+   * @param {object} options - The `options` parameter is an object that
+   * contains various configuration options for the `inspect` function.
+   * These options can be used to customize the output of the inspection.
+   * @param {function} inspect - The `inspect` parameter is a function that
+   * is used to convert an object into a string representation. It is
+   * typically used for debugging purposes or when displaying an object's
+   * properties.
+   * @returns a string that represents a descriptor. The string includes the
+   * type of the descriptor (either "Accessor" or "Data") and the result of
+   * inspecting the descriptor object using the provided options and depth.
+   */
   [Symbol.for('nodejs.util.inspect.custom')](depth, options, inspect) {
     const type = this.isAccessor ? ' (Accessor)' : this.isData ? ' (Data)' : ''
     return `Descriptor${type} ${inspect(this.#desc, {...options, depth})}`
@@ -205,12 +295,15 @@ class Descriptor {
    * object to return a descriptor for.
    * @returns an object descriptor for the requested field or null
    */
-  static for(object, key) {
-    if (!isObject(object) && !isValidKey(key)) {
+  static for(object, key, wrap = false) {
+    if (!isObject(object) || !isValidKey(key) || !Reflect.has(object, key)) {
       return null
     }
 
-    return Object.getOwnPropertyDescriptor(object, key)
+    return (wrap
+      ? new Descriptor(Object.getOwnPropertyDescriptor(object, key))
+      : Object.getOwnPropertyDescriptor(object, key)
+    )
   }
 
   /**
@@ -277,29 +370,25 @@ class Descriptor {
    * The function `getData` retrieves the value of a property from an object
    * if it exists and is a data property.
    *
-   * @param object - The "object" parameter is the object from which we want to
-   * retrieve data.
-   * @param property - The `property` parameter is the name of the property that
-   * you want to retrieve the data from.
+   * @param {object} object - The "object" parameter is the object from which
+   * we want to retrieve data.
+   * @param {string|symbol} property - The `property` parameter is the name of
+   * the property that you want to retrieve the data from.
    * @returns either the value of the specified property if it exists and is
    * a data property, or undefined if the property does not exist or is not
    * a data property.
    */
   static getData(object, property) {
-    if (!isObject(object) || !isString(property)) {
-      return null;
+    if (!isObject(object) || !Reflect.has(object, property)) {
+      return undefined;
     }
 
-    const descriptors = Descriptor.all(object)
-    if (descriptors.has(property)) {
-      const descriptor = descriptors.get(property)
-
-      if (Descriptor.isData(descriptor)) {
-        return descriptor.value
-      }
+    const descriptor = Descriptor.for(object, property, true)
+    if (!descriptor.isData) {
+      return null
     }
 
-    return undefined
+    return descriptor.value
   }
 
   /**
@@ -318,41 +407,16 @@ class Descriptor {
    * returns undefined.
    */
   static getAccessor(object, property) {
-    if (!isObject(object))
-    return null
-
-    const [GETTER, SETTER, OBJECT] = [0, 1, 2]
-    const results = [undefined, undefined, undefined]
-    const descriptors = this.all(object)
-    const isDescriptor = Descriptor.isDescriptor(object)
-
-    if (descriptors.has(property) || isDescriptor) {
-      const descriptor = isDescriptor ? object : descriptors.get(property)
-
-      if (Descriptor.isAccessor(descriptor)) {
-        results[OBJECT] = descriptors.object(property)
-        results[GETTER] = descriptor?.get
-        results[SETTER] = descriptor?.set
-
-        Object.assign(results, {
-          get() { this[GETTER].bind(this[OBJECT])() },
-          set(value) { this[SETTER].bind(this[OBJECT])(value) },
-          get accessor() { return true },
-          get descriptor() { return descriptor },
-          get boundDescriptor() {
-            return {
-              ...descriptor,
-              get: descriptor.get?.bind(object),
-              set: descriptor.set?.bind(object),
-            }
-          }
-        })
-
-        return results
-      }
+    if (!isObject(object) || !Reflect.has(object, property)) {
+      return undefined;
+    }
+
+    const descriptor = Descriptor.for(object, property, true)
+    if (!descriptor.isAccessor) {
+      return null
     }
 
-    return undefined
+    return descriptor.get.bind(object)()
   }
 
   /**
@@ -433,8 +497,11 @@ class Descriptor {
   }
 
   /**
-   * The function checks if an object is a valid object descriptor in
-   * JavaScript.
+   * The function checks if an object is a likely an object descriptor in
+   * JavaScript. This is determined as an object with some of the known
+   * descriptor keys (e.g. enumerable, configurable, value, writable, get,
+   * or set). Technically, any object could serve as a descriptor but this
+   * function only returns true if known descriptor keys are found.
    *
    * @param object - The `object` parameter is the object that we want to
    * check if it is a descriptor.
@@ -453,6 +520,8 @@ class Descriptor {
   /**
    * The function checks if a given property or descriptor is a data property.
    *
+   * brie
+   *
    * @param descriptor_orProp - The `descriptor_orProp` parameter can be
    * either a descriptor or a property name.
    * @param object - The `object` parameter is the object that you want to
@@ -472,13 +541,10 @@ class Descriptor {
       : object_orProp
     )
 
-    const { ACCESSOR_KEYS, DATA_KEYS } = this
+    const { DATA_KEYS } = this
     let validData = false
 
-    if (hasSome(descriptor, ACCESSOR_KEYS)) {
-      validData = false
-    }
-    else if (hasSome(descriptor, DATA_KEYS)) {
+    if (hasSome(descriptor, DATA_KEYS)) {
       validData = true
     }
 
@@ -507,13 +573,10 @@ class Descriptor {
       ? Descriptor.for(object_orProp, property)
       : object_orProp)
 
-    const { ACCESSOR_KEYS, DATA_KEYS } = this
+    const { ACCESSOR_KEYS } = this
     let validAccessor = false
 
-    if (hasSome(descriptor, DATA_KEYS)) {
-      validAccessor = false
-    }
-    else if (hasSome(descriptor, ACCESSOR_KEYS)) {
+    if (hasSome(descriptor, ACCESSOR_KEYS)) {
       validAccessor = true
     }
 

package/src/newClasses/iterable.js

@@ -0,0 +1,221 @@
+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)