@nejs/basic-extensions 2.18.0 → 2.20.0

package/src/classes/enum.js

@@ -0,0 +1,344 @@
+import { Extension } from '@nejs/extension'
+import { accessor, as, data, isDescriptor } from '../utils/index.js'
+
+/**
+ * Creates an enumeration object with specified values and properties.
+ *
+ * @param {string} name - The name of the enumeration.
+ * @param {Array|any} values - The values to be included in the enumeration.
+ *   If not an array, it will be converted into a single-element array.
+ * @param {Object|Map} [properties] - Additional properties to be added to
+ *   the enumeration. Can be an object or a Map.
+ * @returns {Object} The constructed enumeration object.
+ *
+ * @example
+* const colors = Enum('Colors', ['red', 'green', 'blue'])
+* console.log(colors.red) // EnumValue object for 'red'
+*
+* @description
+* The `Enum` function constructs an enumeration object with a given name,
+* values, and optional properties. It supports primitive types, arrays,
+* and objects as values. The function uses a combination of `Object.create`
+* and `Proxy` to define and manage the properties of the enumeration.
+*
+* The enumeration object includes:
+* - A `toString` method that returns the enumeration name.
+* - A `Symbol.toStringTag` for identifying the object as an 'Enum'.
+* - A `Symbol.for('Enum.name')` for storing the enumeration name.
+*
+* For array values, it creates a maker function that returns an
+* `EnumValue` object with properties like `real`, `value`, `type`,
+* `name`, and `compare`.
+*/
+export function Enum(name, values, properties) {
+ const enumeration = Object.create({}, {
+   [Symbol.toStringTag]: accessor('Enum', false, true, false),
+   [Symbol.for('Enum.name')]: accessor(name, false, true, false),
+   [Symbol.for('Enum.valueKeys')]: data([], false, true, false),
+   [Symbol.for('nodejs.util.inspect.custom')]: data(
+     function(depth, options, inspect) {
+       const valueKeys = this[Symbol.for('Enum.valueKeys')] ?? []
+       let valueText = valueKeys
+         .map(key => `\x1b[1;2m${key}\x1b[22m`)
+         .join(', ')
+
+       if (valueText.length)
+         valueText = ` { ${valueText} }`
+
+       return `\x1b[1menum \x1b[22m${name}${valueText}`
+     }, false, true, false
+   ),
+   toString: data(function() {
+     return `Enum(${name})`
+   }, false, true, false)
+ })
+
+ if (!Array.isArray(values)) {
+   values = [values]
+ }
+
+ const asString = o => as.string(o, { description: true, stringTag: true })
+
+ /**
+  * A new base `EnumValue` type object. It contains enough custom symbols and
+  * identifiers to allow things like a `compare(to)` function to also work on
+  * each of the elements. Thing of this as the shared base functionality for
+  * each `Enum` element.
+  *
+  * @param {any} enumValue the value around which an `EnumValue` type is
+  * created.
+  * @returns an object defined by {@link Symbol.toStringTag} as well as some
+  * custom {@link Symbol} keys. The `node.js` custom inspect symbol is also
+  * defined for better REPL representation.
+  */
+ const makeEnumValue = (property, enumValue) => ({
+   toString: data(() => enumValue, false, true, false),
+
+   [Symbol.for('Enum.name')]: data(name, false, true, false),
+   [Symbol.for('Enum.is')]: data(true, false, false, false),
+   [Symbol.for('nodejs.util.inspect.custom')]: data(
+     function(depth, options, inspect) {
+       const _options = { ...(options || {}), colors: true }
+       const _skip = this.value === Symbol.for('Enum.NonAssociatedValue')
+       const _value = _skip
+         ? ''
+         : ` { value: ${inspect(this.value, _options) } }`;
+
+       return `${property}${_value}`
+     },
+     false, true, false
+   ),
+   [Symbol.toStringTag]: accessor('EnumValue', false, true, false),
+   [Symbol.for('compare')]: data(
+     function compareValue(to) {
+       const toObj = (to && typeof to === 'object') ? to : { real: to }
+       const kName = Symbol.for('Enum.name')
+
+       const hasAndIs = o =>
+         (Reflect.has(o, Symbol.for('Enum.is')) && o[Symbol.for('Enum.is')]);
+
+       const isLEnum = hasAndIs(this)
+       const isREnum = hasAndIs(toObj)
+
+       if (!isLEnum || !isREnum)
+         return false
+
+       const {real: lReal, value: lValue, name: lName, type: lType} = this
+       const {real: rReal, value: rValue, name: rName, type: rType} = toObj
+
+       return (
+         lName === rName && lType === rType &&
+         lReal === rReal && lValue === rValue
+       )
+   }, false, true, false),
+   [Symbol.toPrimitive]: data(
+     function EnumValueToPrimitive(hint) {
+       const original = this.real
+       const type = typeof original
+
+       switch (hint) {
+         case 'string':
+           if ('string' === type)
+             return original
+           else
+             return String(original)
+
+         case 'number':
+           if ('number' === type)
+             return original
+           else
+             return NaN
+
+         case 'bigint':
+           if ('bigint' === type)
+             return original
+           else
+             return NaN
+
+         default:
+           return original
+       }
+     },
+     false, true, false),
+ })
+
+ /**
+  * Given a value, determine how to represent it as both a key and a response
+  * or underlying original value. The method for this is dependent on the type
+  * of the value itself.
+  *
+  * @param {any} value the value to be converted
+  * @returns {[string, any]} an array where the first value is the transformed
+  * value as a key and the second element is the originally supplied value.
+  */
+ const fromPrimitive = (value) => {
+   let valueType = typeof value
+
+   switch (valueType) {
+     case 'string':
+     case 'number':
+     case 'bigint':
+     case 'boolean':
+     default:
+       return [String(value), value]
+
+     case 'symbol':
+       return [value.description, value]
+
+     case 'function':
+       return [value.name, value]
+
+     case 'object': {
+       const str = asString(value)
+       return [str, str]
+     }
+   }
+ }
+
+ // Determine the keys that the final proxy should be aware of when computing
+ // the enumeration value itself.
+ const kValueProps = ['real', 'value', 'type', 'name', 'compare', 'isEnum']
+ const kCustomPropKeys = []
+
+ // Capture and calculate any custom properties defined for each element
+ // of the enumeration. Each custom property is appended to `kCustomPropKeys`
+ const props = {}
+ if (properties) {
+    if (Array.isArray(properties)) {
+      const entries = properties.filter(e => Array.isArray(e) && e.length === 2)
+
+      if (entries.length)
+        properties = new Map(entries)
+      else
+        properties = new Map()
+    }
+    else if (typeof properties === 'object') {
+      properties = new Map(
+        Object.entries(Object.getOwnPropertyDescriptors(properties)))
+    }
+
+    if (properties instanceof Map) {
+     const applyPropertiesOf = (object, baseDescriptor) => {
+       const property = {
+         configurable: baseDescriptor?.configurable ?? true,
+         enumerable: baseDescriptor?.enumerable ?? true,
+         writable: baseDescriptor?.writable ?? true,
+       }
+
+       const descriptors = Object.getOwnPropertyDescriptors(object)
+       for (const [key, subvalue] of Object.entries(descriptors)) {
+          const stats = isDescriptor(subvalue, true)
+          const baseStats = isDescriptor(baseDescriptor, true)
+
+          if (stats.isAccessor && baseStats.isValid) {
+            props[key] = { ...subvalue, ...accessor.keys.from(baseDescriptor) }
+          }
+          else if (stats.isData && baseStats.isValid) {
+            props[key] = { ...subvalue, ...data.keys.from(baseDescriptor) }
+          }
+       }
+     }
+
+     let stats = {}
+
+     for (const [property, value] of properties.entries()) {
+       kCustomPropKeys.push(property)
+
+       if (isDescriptor(property)) {
+         if (typeof value === 'object') {
+           applyPropertiesOf(value, property)
+           continue
+         }
+       }
+
+       props[property] = value
+     }
+    }
+ }
+
+ for (const value of values) {
+   const valueType = Array.isArray(value) ? 'array' : typeof value
+
+   let property = undefined
+   let response = undefined
+   let makeNew = undefined
+   let wasArray = false
+   let elements = value
+
+   switch (valueType) {
+     case 'array':
+       if (value.length >= 1) {
+         wasArray = true;
+         ([property, response] = fromPrimitive(elements[0]))
+       }
+
+     default:
+       ([property, response] = fromPrimitive(value))
+   }
+
+   const maker = {
+     [property](initialValue) {
+       const storage = new Map()
+       const key = property
+       const realValue = accessor(response, false, { storage, key })
+
+       let _opts, associatedValue;
+
+       if (wasArray) {
+         _opts = { storage, key: key + '.associated' }
+         associatedValue = elements.length === 1
+           ? accessor(initialValue, true, _opts)
+           : accessor(elements?.[1], elements?.[2], _opts);
+       }
+       else
+         associatedValue = accessor(
+           Symbol.for('Enum.NonAssociatedValue'),
+           false, false, false)
+
+       const _prop = Object(asString(response))
+       const valueProps = [...kValueProps, ...kCustomPropKeys]
+       const enumResponse = Object.create(_prop, {
+         ...makeEnumValue(property, response),
+         ...props,
+       })
+
+       const proxy = new Proxy(_prop, {
+         get(target, _property, receiver) {
+           if (_property === 'real')
+             return realValue.get()
+
+           if (_property === 'value')
+             return associatedValue.get()
+
+           if (_property === 'type')
+             return name
+
+           if (_property === 'name')
+             return property
+
+           if (_property === 'compare')
+             return enumResponse[Symbol.for('compare')]
+
+           if (_property === 'isEnum')
+             return true
+
+           if (!valueProps.includes(_property))
+             return undefined
+         },
+         has(target, _property) {
+           return valueProps.includes(_property)
+         },
+         ownKeys(target) {
+           return valueProps
+         },
+         set(target, _property, value, receiver) {
+           if (_property === 'value' && wasArray)
+             return associatedValue.set(value)
+
+           return false
+         }
+       })
+
+       Object.setPrototypeOf(proxy, Object.getPrototypeOf(_prop))
+       Object.setPrototypeOf(enumResponse, proxy)
+
+       return enumResponse
+     }
+   }
+
+   enumeration[Symbol.for('Enum.valueKeys')].push(property)
+
+   const dataValue = wasArray ? maker[property] : maker[property]()
+   const baseProps = {
+     writable: false,
+     configurable: false,
+     enumerable: true,
+   }
+
+   Object.defineProperty(enumeration, property, data(dataValue, baseProps))
+ }
+
+ return enumeration
+}
+
+export const EnumExtension = new Extension(Enum)

package/src/classes/index.js

@@ -9,6 +9,9 @@ export * from './deferred.js'
 import { Descriptor } from './descriptor.js'
 export * from './descriptor.js'
 
+import { Enum } from './enum.js'
+export * from './enum.js'
+
 import { Introspector } from './introspector.js'
 export * from './introspector.js'
 
@@ -41,6 +44,7 @@ export const NewClassesExtension = new Patch(globalThis, {
   AsyncIterator,
   Deferred,
   Descriptor,
+  Enum,
   Introspector,
   Iterable,
   Iterator,

package/src/index.js

@@ -14,6 +14,7 @@ import { SymbolExtensions, SymbolPrototypeExtensions } from './symbol.extensions
 
 import { DeferredExtension } from './classes/deferred.js'
 import { DescriptorExtensions, Descriptor } from './classes/descriptor.js'
+import { EnumExtension, Enum } from './classes/enum.js'
 import { IntrospectorExtensions } from './classes/introspector.js'
 import { IteratorExtensions, IterableExtensions } from './classes/iterable.js'
 import { ParamParserExtensions } from './classes/param.parser.js'
@@ -74,6 +75,7 @@ const Extensions = {
   [AsyncIteratorExtensions.key]: AsyncIteratorExtensions,
   [DeferredExtension.key]: DeferredExtension,
   [DescriptorExtensions.key]: DescriptorExtensions,
+  [EnumExtension.key]: EnumExtension,
   [IntrospectorExtensions.key]: IntrospectorExtensions,
   [IterableExtensions.key]: IterableExtensions,
   [IteratorExtensions.key]: IteratorExtensions,
@@ -93,7 +95,6 @@ for (const extension of Object.values(Extensions)) {
   Classes[fnOrClass.name] = fnOrClass
 }
 
-
 const Controls = {}
 
 Object.assign(Controls, {

package/src/utils/descriptor.utils.js

@@ -335,7 +335,32 @@ export const DescriptorUtils = {
     }
 
     Object.defineProperty(accessor, 'keys', {
-      get() { return ['get', 'set', 'configurable', 'enumerable'] },
+      get() { return Object.defineProperties(
+        ['get', 'set', 'configurable', 'enumerable'],
+        {
+          from: {
+            value: function extractKeysFrom(object) {
+              const response = {
+                get: undefined,
+                set: undefined,
+                configurable: undefined,
+                enumerable: undefined,
+              }
+
+              if (!object || !(object instanceof Object))
+                return response
+
+              for (const key of DescriptorUtils.accessor.keys) {
+                if (Reflect.has(object, key))
+                  response[key] = object[key]
+              }
+            },
+            writable: false,
+            configurable: false,
+            enumerable: false
+          }
+        }
+      ) },
       configurable: true,
       enumerable: false,
     })
@@ -468,7 +493,32 @@ export const DescriptorUtils = {
     }
 
     Object.defineProperty(data, 'keys', {
-      value: ['value', 'writable', 'configurable', 'enumerable'],
+      value: Object.defineProperties(
+        ['value', 'writable', 'configurable', 'enumerable'],
+        {
+          from: {
+            value: function extractKeysFrom(object) {
+              const response = {
+                value: undefined,
+                writable: undefined,
+                configurable: undefined,
+                enumerable: undefined,
+              }
+
+              if (!object || !(object instanceof Object))
+                return response
+
+              for (const key of DescriptorUtils.data.keys) {
+                if (Reflect.has(object, key))
+                  response[key] = object[key]
+              }
+            },
+            writable: false,
+            configurable: false,
+            enumerable: false,
+          }
+        }
+      ),
       writable: false,
       configurable: true,
       enumerable: false
@@ -502,9 +552,6 @@ export const DescriptorUtils = {
    * stats block.
    */
   isDescriptor(value, returnStats = false, strict = true) {
-    if (!value || typeof value !== 'object' || !(value instanceof Object))
-      return false
-
     const areBools = (...props) => props.flat().every(
       prop => boolTypes.includes(typeof value[prop])
     );
@@ -532,6 +579,9 @@ export const DescriptorUtils = {
       isValid: false,
     }
 
+    if (!value || typeof value !== 'object' || !(value instanceof Object))
+      return returnStats ? stats : false;
+
     let score = 0
 
     if (value && typeof value === 'object') {