@nejs/basic-extensions 2.9.0 → 2.11.0

package/src/classes/descriptor.js

@@ -1,5 +1,15 @@
 import { Extension } from '@nejs/extension'
 
+import {
+  accessor as uAccessor,
+  data as uData,
+  isDescriptor as uIsDescriptor,
+  kAccessorDescriptorKeys,
+  kDataDescriptorKeys,
+  kDescriptorKeys,
+  kSharedDescriptorKeys
+} from '../utils/descriptor.utils.js'
+
 export class Descriptor {
   /**
    * The default private descriptor value is that of `enigmatic`
@@ -7,7 +17,7 @@ export class Descriptor {
    * @private
    * @type {object}
    */
-  #desc = undefined
+  _desc = undefined
 
   /**
    * An optionally associated object, usually the parent from which
@@ -16,7 +26,7 @@ export class Descriptor {
    *
    * @type {object}
    */
-  #object = undefined
+  _object = undefined
 
   /**
    * Constructs a Descriptor instance which wraps and manages an object
@@ -35,26 +45,38 @@ export class Descriptor {
    * valid.
    */
   constructor(object, key) {
-    if ((object ?? key) === undefined) {
-      this.#desc = Descriptor.enigmatic
+    if (arguments.length === 0) {
+      this._desc = Descriptor.enigmatic
     }
+
     else if (Descriptor.isDescriptor(object)) {
-      this.#desc = object
-      this.#object = isObject(key) ? key : undefined
+      this._desc = object
+      this._object = isObject(key) ? key : undefined
     }
+
     else if (isObject(object) && isValidKey(key)) {
-      this.#desc = Object.getOwnPropertyDescriptor(object, key)
-      this.#object = object
+      console.log('new Descriptor(%o, %o)', object, key)
+      this._desc = Object.getOwnPropertyDescriptor(object, key)
+      this._object = object
     }
 
     if (!this.isDescriptor) {
+      const objectMsg = object === globalThis
+        ? '[GLOBAL]'
+        : (typeof key === 'object' ? JSON.stringify(object) : String(object));
+
+      const keyMsg = key === globalThis
+        ? '[GLOBAL]'
+        : (typeof key === 'object' ? JSON.stringify(key) : String(key));
+
       console.error(`
-      Descriptor(object,key) FAILED:
-        object:      ${object === globalThis ? '[GLOBAL]' : (typeof key === 'object' ? JSON.stringify(object) : String(object))}
-        key:         ${key === globalThis ? '[GLOBAL]' : (typeof key === 'object' ? JSON.stringify(key) : String(key))}
-        descriptor:  `, this.#desc
+      Descriptor(object: ${object}, key: ${key}) FAILED:
+        object:      ${objectMsg}
+        key:         ${keyMsg}
+        descriptor:  `, this._desc
       )
-      throw new Error(`Not a valid descriptor:`, this.#desc)
+
+      throw new Error(`Not a valid descriptor:`, this._desc)
     }
   }
 
@@ -65,7 +87,7 @@ export class Descriptor {
    * a data descriptor
    */
   get isAccessor() {
-    return Descriptor.isAccessor(this.#desc)
+    return uIsDescriptor(this._desc, true).isAccessor
   }
 
   /**
@@ -75,7 +97,7 @@ export class Descriptor {
    * an accessor descriptor
    */
   get isData() {
-    return Descriptor.isData(this.#desc)
+    return uIsDescriptor(this._desc, true).isData
   }
 
   /**
@@ -84,106 +106,7 @@ export class Descriptor {
    * @returns {boolean} true if this descriptor store is a valid descriptor
    */
   get isDescriptor() {
-    return Descriptor.isDescriptor(this.#desc)
-  }
-
-  /**
-   * Getter around the `configurable` object descriptor property of
-   * this instance of Descriptor.
-   *
-   * @returns {boolean} a boolean value or undefined if the internal
-   * descriptor store is invalid.
-   */
-  get configurable() {
-    return !!this.#desc?.configurable
-  }
-
-  /**
-   * Sets the `configurable` value of this object. If the internal descriptor
-   * store store is invalid, the value is thrown away
-   *
-   * @param {boolean} value the value to set for the `configurable` descriptor
-   * property. If this value is not a `boolean` it will be converted to one
-   */
-  set configurable(value) {
-    (this.#desc || {}).configurable = !!value
-  }
-
-  /**
-   * Getter around the `enumerable` object descriptor property of
-   * this instance of Descriptor.
-   *
-   * @returns {boolean} a boolean value or undefined if the internal
-   * descriptor store is invalid.
-   */
-  get enumerable() {
-    return this.#desc?.enumerable
-  }
-
-  /**
-   * Sets the `enumerable` value of this object. If the internal descriptor
-   * store is invalid, the value is thrown away
-   *
-   * @param {boolean} value the value to set for the `enumerable` descriptor
-   * property. If this value is not a `boolean` it will be converted to one
-   */
-  set enumerable(value) {
-    (this.#desc || {}).enumerable = value
-  }
-
-  /**
-   * Getter around the `writable` object descriptor property of
-   * this instance of Descriptor.
-   *
-   * @returns {boolean} a boolean value or undefined if the internal
-   * descriptor store is invalid.
-   */
-  get writable() {
-    return this.#desc?.writable
-  }
-
-  /**
-   * Sets the `writable` value of this object. If the internal descriptor
-   * store is invalid, the value is thrown away
-   *
-   * @param {boolean} value the value to set for the `writable` descriptor
-   * property. If this value is not a `boolean` it will be converted to one
-   */
-  set writable(value) {
-    (this.#desc || {}).writable = value
-  }
-
-  /**
-   * Getter around the `value` object descriptor property of
-   * this instance of Descriptor.
-   *
-   * @returns {any} any value stored in this descriptor
-   */
-  get value() {
-    return this.#desc?.value
-  }
-
-  /**
-   * Sets the `value` value of this object. If the internal descriptor
-   * store is invalid, the value is thrown away
-   *
-   * @param {any} value the value to set for the `value` descriptor
-   * property.
-   */
-  set value(value) {
-    (this.#desc || {}).value = value
-  }
-
-  /**
-   * Getter around the `get` object descriptor property of
-   * this instance of Descriptor.
-   *
-   * @returns {function} a function if the getter for this descriptor is
-   * defined or `undefined` if the internal descriptor object or the getter
-   * is undefined.
-   */
-  get get() {
-    return this.#desc?.get
+    return uIsDescriptor(this._desc)
   }
 
   /**
@@ -195,29 +118,7 @@ export class Descriptor {
    * 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
-   *
-   * @param {function} value the getter function for this descriptor
-   */
-  set get(value) {
-    (this.#desc || {}).get = value
-  }
-
-  /**
-   * Getter around the `set` object descriptor property of
-   * this instance of Descriptor.
-   *
-   * @returns {function} a function if the setter for this descriptor is
-   * defined or `undefined` if the internal descriptor object or the setter
-   * is undefined.
-   */
-  get set() {
-    return (this.#desc || {}).set
+    return (isObject(this._object) ? this.get?.bind(this._object) : this.get)
   }
 
   /**
@@ -229,17 +130,7 @@ export class Descriptor {
    * setter will be bound the associated and previously set `object`.
    */
   get boundSet() {
-    return (isObject(this.#object) ? this.set?.bind(this.#object) : this.set)
-  }
-
-  /**
-   * Sets the `set` value of this object. If the internal descriptor
-   * store is invalid, the value is thrown away
-   *
-   * @param {function} value the setter function for this descriptor
-   */
-  set set(value) {
-    (this.#desc || {}).set = value
+    return (isObject(this._object) ? this.set?.bind(this._object) : this.set)
   }
 
   /**
@@ -249,7 +140,7 @@ export class Descriptor {
    * @returns {boolean} `true` if the `object` property has been set,
    * `false` otherwise
    */
-  get hasObject() { return isObject(this.#object) }
+  get hasObject() { return isObject(this._object) }
 
   /**
    * Returns the descriptor's associated `object` value. This is usually the
@@ -259,7 +150,7 @@ export class Descriptor {
    * @returns {object} the associated object for this descriptor or undefined
    * if it has not yet been set.
    */
-  get object() { return this.#object }
+  get object() { return this._object }
 
   /**
    * Sets the descriptor's associated `object` value. This is usually the
@@ -268,49 +159,7 @@ export class Descriptor {
    * @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})}`
-  }
-
-  /**
-   * Shorthand for Object.getOwnPropertyDescriptor()
-   *
-   * @param {object} object a non-null object instance
-   * @param {string|symbol} key a symbol or string referencing which key on the
-   * object to return a descriptor for.
-   * @returns an object descriptor for the requested field or null
-   */
-  static for(object, key, wrap = false) {
-    if (!isObject(object) || !isValidKey(key) || !Reflect.has(object, key)) {
-      return null
-    }
-
-    return (wrap
-      ? new Descriptor(Object.getOwnPropertyDescriptor(object, key))
-      : Object.getOwnPropertyDescriptor(object, key)
-    )
-  }
+  set object(value) { this._object = Object(value) }
 
   /**
    * Take the descriptor defined by this objects values and apply them to
@@ -342,7 +191,7 @@ export class Descriptor {
    * a descriptor.
    */
   toObject(bindAccessors = false) {
-    let descriptor = { ...this.#desc }
+    let descriptor = { ...this._desc }
 
     if (bindAccessors && this.isAccessor) {
       if (this.hasObject) {
@@ -364,6 +213,29 @@ export class Descriptor {
     return descriptor
   }
 
+  /**
+   * 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})}`
+  }
+
   /**
    * Converts this descriptor object into a base representation
    *
@@ -375,18 +247,20 @@ export class Descriptor {
     switch (hint) {
       case 'string':
         if (this.isAccessor) {
-          const hasGetter = Reflect.has(this.#desc, 'get') ? `getter` : ''
-          const hasSetter = Reflect.has(this.#desc, 'set') ? `setter` : ''
-          const separator = hasGetter && hasSetter ? ', ' : ''
+          const props = []
 
-          return `Accessor (${hasGetter}${separator}${hasSetter})`
+          if (Reflect.has(this._desc, 'get')) props.push('getter')
+          if (Reflect.has(this._desc, 'set')) props.push('setter')
+
+          return `Accessor (${props.join(', ')})`
         }
         else if (this.isData) {
-          const hasGetter = Reflect.has(this.#desc, 'value') ? `value` : ''
-          const hasSetter = Reflect.has(this.#desc, 'writable') ? `writable` : ''
-          const separator = hasGetter && hasSetter ? ', ' : ''
+          const props = []
+
+          if (Reflect.has(this._desc, 'value')) props.push('value')
+          if (Reflect.has(this._desc, 'writable')) props.push('writable')
 
-          return `Data (${hasGetter}${separator}${hasSetter})`
+          return `Data (${props.join(', ')})`
         }
         break
 
@@ -498,17 +372,8 @@ export class Descriptor {
    * @returns an object with properties "get", "set", "enumerable", and
    * "configurable".
    */
-  static accessor(
-    getter,
-    setter,
-    { enumerable, configurable } = Descriptor.base()
-  ) {
-    return {
-      get: getter,
-      set: setter,
-      enumerable,
-      configurable
-    }
+  static accessor() {
+    return uAccessor(...arguments)
   }
 
   /**
@@ -528,14 +393,28 @@ export class Descriptor {
   static data(
     value,
     writable = true,
-    { enumerable, configurable } = Descriptor.base()
+    { enumerable, configurable } = { configurable: true, enumerable: true }
   ) {
-    return {
-      value,
-      enumerable,
-      writable,
-      configurable
+    return uData(value, writable, enumerable, configurable)
+  }
+
+  /**
+   * Shorthand for Object.getOwnPropertyDescriptor()
+   *
+   * @param {object} object a non-null object instance
+   * @param {string|symbol} key a symbol or string referencing which key on the
+   * object to return a descriptor for.
+   * @returns an object descriptor for the requested field or null
+   */
+  static for(object, key, wrap = false) {
+    if (!isObject(object) || !isValidKey(key) || !Reflect.has(object, key)) {
+      return null
     }
+
+    return (wrap
+      ? new Descriptor(Object.getOwnPropertyDescriptor(object, key))
+      : Object.getOwnPropertyDescriptor(object, key)
+    )
   }
 
   /**
@@ -545,127 +424,113 @@ export class Descriptor {
    * 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.
-   * @returns a boolean value.
+   * @param {any} object - Any value we want to check for being a descriptor.
+   * @param {boolean} returnStatsInstead defaults to false, but if the value
+   * is `true` then an object with reasoning behind the decision of whether
+   * or not the
+   * @returns {IsDescriptorResponse} either a {@link boolean} value or
+   * an object conforming to {@link IsDescriptorStats} if `returnStatsInstead`
+   * is `true`
+   *
+   * @see {@link DescriptorUtils.isDescriptor}
    */
-  static isDescriptor(object) {
-    const knownKeys = [
-      ...Descriptor.SHARED_KEYS,
-      ...Descriptor.ACCESSOR_KEYS,
-      ...Descriptor.DATA_KEYS,
-    ]
-
-    return hasSome(object, knownKeys)
+  static isDescriptor(object, returnStatsInstead = false) {
+    return uIsDescriptor(object, returnStatsInstead)
   }
 
   /**
-   * The function checks if a given property or descriptor is a data property.
-   *
-   * brie
+   * The function checks if a given property descriptor or property of an
+   * object is an accessor.
    *
-   * @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
-   * check for data properties.
-   * @returns a boolean value. It returns `true` if the `descriptor` object
-   * has any keys that match the `DATA_KEYS` array, otherwise it returns
-   * `false`.
+   * @param {object} objectOrDescriptor - The `objectOrDescriptor` parameter
+   * can be either a descriptor object or a property name.
+   * @param {(string|number|symbol)?} property the property name you wish to
+   * check the validity as an accessor descriptor. Only expected if the
+   * `objectOrDescriptor` parameter is the object that would contain this
+   * property.
+   * @returns {@link Boolean} returning `true` if the `descriptor` object
+   * has any keys that match the {@link Descriptor.ACCESSOR_KEYS} array,
+   * otherwise it returns `false`.
    */
-  static isData(object_orProp, property) {
-    const needsDescriptor = (
-      ((typeof object_orProp === 'object') || object_orProp instanceof Object) &&
-      property instanceof String
-    )
-
-    const descriptor = (needsDescriptor
-      ? Descriptor.for(object_orProp, property)
-      : object_orProp
-    )
+  static isAccessor(objectOrDescriptor, property) {
+    const needsDescriptor =
+      objectOrDescriptor &&
+      property &&
+      isObject(objectOrDescriptor) &&
+      isValidKey(property);
 
-    const { DATA_KEYS } = this
-    let validData = false
+    const descriptor = needsDescriptor
+      ? Descriptor.for(objectOrDescriptor, property)
+      : objectOrDescriptor
 
-    if (hasSome(descriptor, DATA_KEYS)) {
-      validData = true
-    }
-
-    return validData
+    return uIsDescriptor(descriptor, true).isAccessor
   }
 
   /**
-   * The function checks if a given property descriptor or property of an
-   * object is an accessor.
+   * The function checks if a given property or descriptor is a data property.
    *
-   * @param object_orProp - The `descriptor_orProp` parameter can be either a
-   * descriptor object or a property name.
-   * @param property - The `object` parameter is the object that you want to
-   * check for accessor properties.
-   * @returns a boolean value. It returns true if the descriptor or property
-   * passed as an argument is an accessor descriptor, and false otherwise.
-   */
-  static isAccessor(object_orProp, property) {
-    const needsDescriptor = (
-      (object_orProp && property) &&
-      ((typeof object_orProp === 'object') || object_orProp instanceof Object) &&
-      (property instanceof String || (typeof property === 'symbol'))
-    )
-
-    const descriptor = (needsDescriptor
-      ? Descriptor.for(object_orProp, property)
-      : object_orProp)
-
-    const { ACCESSOR_KEYS } = this
-    let validAccessor = false
+   * @param {object} objectOrDescriptor - The `objectOrDescriptor` parameter
+   * can be either a descriptor object or a property name.
+   * @param {(string|number|symbol)?} property the property name you wish to
+   * check the validity as an accessor descriptor. Only expected if the
+   * `objectOrDescriptor` parameter is the object that would contain this
+   * property.
+   * @returns {@link Boolean} returning `true` if the `descriptor` object
+   * has any keys that match the {@link Descriptor.DATA_KEYS} array, otherwise
+   * it returns `false`.
+   */
+  static isData(objectOrDescriptor, property) {
+    const needsDescriptor =
+      objectOrDescriptor &&
+      property &&
+      isObject(objectOrDescriptor) &&
+      isValidKey(property);
 
-    if (hasSome(descriptor, ACCESSOR_KEYS)) {
-      validAccessor = true
-    }
+    const descriptor = needsDescriptor
+      ? Descriptor.for(objectOrDescriptor, property)
+      : objectOrDescriptor
 
-    return validAccessor
+    return uIsDescriptor(descriptor, true).isData
   }
 
   /**
    * A base descriptor (new for each read) that is both enumerable and
    * configurable
    *
-   * @returns The method `flexible` is returning the result of calling the
-   * `base` method with the arguments `true` and `true`.
+   * @returns `{ enumerable: true, configurable: true }`
    */
   static get flexible() {
-    return this.base(true, true)
+    return { enumerable: true, configurable: true }
   }
 
   /**
    * A base descriptor (new for each read) that is not enumerable but is
    * configurable
    *
-   * @returns The method `enigmatic` is returning the result of calling
-   * the `base` method with the arguments `false` and `true`.
+   * @returns `{ enumerable: false, configurable: true }`
    */
   static get enigmatic() {
-    return this.base(false, true)
+    return { enumerable: false, configurable: true }
   }
 
   /**
    * A base descriptor (new for each read) that is neither enumerable
-   * nor configurable
+   * nor configurable.
    *
-   * @returns The code is returning the result of calling the `base` method with
-   * the arguments `false` and `false`.
+   * @returns `{ enumerable: false, configurable: false }`
    */
   static get intrinsic() {
-    return this.base(false, false)
+    return { enumerable: false, configurable: false }
   }
 
   /**
-   * A base descriptor (new for each read) that enumerable but not configurable
+   * A base descriptor (new for each read) that is enumerable but
+   * not configurable
    *
-   * @returns The method is returning the result of calling the `base`
-   * method with the arguments `true` and `false`.
+   * @returns `{ enumerable: true, configurable: false }`
    */
   static get transparent() {
-    return this.base(true, false)
+    return { enumerable: true, configurable: false }
   }
 
   /**
@@ -674,7 +539,7 @@ export class Descriptor {
    * @returns An array containing the strings 'configurable' and 'enumerable'.
    */
   static get SHARED_KEYS() {
-    return ['configurable', 'enumerable']
+    return kSharedDescriptorKeys
   }
 
   /**
@@ -683,7 +548,7 @@ export class Descriptor {
    * @returns An array containing the strings 'get' and 'set' is being returned.
    */
   static get ACCESSOR_KEYS() {
-    return ['get', 'set']
+    return kAccessorDescriptorKeys
   }
 
   /**
@@ -693,17 +558,53 @@ export class Descriptor {
    * returned.
    */
   static get DATA_KEYS() {
-    return ['value', 'writable']
+    return kDataDescriptorKeys
+  }
+
+  static {
+    for (const key of kDescriptorKeys) {
+      Object.defineProperties(Descriptor.prototype, {
+        [key]: uAccessor(
+          function getMaker(storage) { return function get() {
+            return this._desc[key]
+          }},
+          function setMaker(storage) { return function set(value) {
+            this._desc[key] = value
+          }},
+        )
+      })
+    }
   }
 }
 
 export const DescriptorExtensions = new Extension(Descriptor)
 
-function isObject(o) { return o && typeof o === 'object' }
-function isValidKey(o) { return ['string','symbol'].some(t => typeof o === t) }
-function hasSome(object, ...keys) {
+function typeOrType(type, Class, notNullish = true) {
+  return (value) => (
+    (!notNullish || (notNullish && value !== null && value !== undefined)) &&
+    (typeof value === type || (value && value instanceof Class))
+  )
+}
+
+function isObject(o) { return typeOrType('object', Object)(o) }
+function isString(o) { return typeOrType('string', String)(o) }
+function isNumber(o) { return typeOrType('number', Number)(o) }
+function isSymbol(o) { return typeOrType('symbol', Symbol)(o) }
+function isFunction(o) { return typeOrType('function', Function)(o) }
+function isValidKey(o) { return isString(o) || isNumber(o) || isSymbol(o) }
+
+function hasAll(object, ...keys) { return hasQuantity('every', object, keys) }
+function hasSome(object, ...keys) { return hasQuantity('some', object, keys) }
+function hasQuantity(quantityFn, object, keys) {
+  return isObject(object) && (keys.flat(Infinity)
+    .map(key => Reflect.has(object, key))
+    [quantityFn](has => has)
+  )
+}
+function hasOne(object, ...keys) {
   return isObject(object) && (keys.flat(Infinity)
     .map(key => Reflect.has(object, key))
-    .some(has => has)
+    .filter(has => has)
+    .length === 1
   )
 }