@nejs/basic-extensions 2.20.0 → 2.21.5

package/src/classes/enum.js

@@ -1,5 +1,5 @@
 import { Extension } from '@nejs/extension'
-import { accessor, as, data, isDescriptor } from '../utils/index.js'
+import { accessor, as, data, isDescriptor, redescribe } from '../utils/index.js'
 
 /**
  * Creates an enumeration object with specified values and properties.
@@ -12,54 +12,32 @@ import { accessor, as, data, isDescriptor } from '../utils/index.js'
  * @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`.
-*/
+ * 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 })
-
- /**
+  const enumeration = makeBaseEnum(name)
+
+  if (!Array.isArray(values)) {
+    values = [values]
+  }
+
+  /**
   * 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
@@ -71,25 +49,25 @@ export function Enum(name, values, properties) {
   * 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(
+  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')
@@ -110,8 +88,8 @@ export function Enum(name, values, properties) {
          lName === rName && lType === rType &&
          lReal === rReal && lValue === rValue
        )
-   }, false, true, false),
-   [Symbol.toPrimitive]: data(
+    }, false, true, false),
+    [Symbol.toPrimitive]: data(
      function EnumValueToPrimitive(hint) {
        const original = this.real
        const type = typeof original
@@ -140,9 +118,9 @@ export function Enum(name, values, properties) {
        }
      },
      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.
@@ -151,7 +129,7 @@ export function Enum(name, values, properties) {
   * @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) => {
+  const fromPrimitive = (value) => {
    let valueType = typeof value
 
    switch (valueType) {
@@ -173,17 +151,17 @@ export function Enum(name, values, properties) {
        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 = []
+  // 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) {
+  // 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)
 
@@ -234,14 +212,13 @@ export function Enum(name, values, properties) {
        props[property] = value
      }
     }
- }
+  }
 
- for (const value of values) {
+  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
 
@@ -258,31 +235,31 @@ export function Enum(name, values, properties) {
 
    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
+        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, {
+        const _prop = Object(asString(response))
+        const valueProps = [...kValueProps, ...kCustomPropKeys]
+        const enumResponse = Object.create(_prop, {
          ...makeEnumValue(property, response),
          ...props,
-       })
+        })
 
-       const proxy = new Proxy(_prop, {
+        const proxy = new Proxy(_prop, {
          get(target, _property, receiver) {
            if (_property === 'real')
              return realValue.get()
@@ -317,12 +294,12 @@ export function Enum(name, values, properties) {
 
            return false
          }
-       })
+        })
 
-       Object.setPrototypeOf(proxy, Object.getPrototypeOf(_prop))
-       Object.setPrototypeOf(enumResponse, proxy)
+        Object.setPrototypeOf(proxy, Object.getPrototypeOf(_prop))
+        Object.setPrototypeOf(enumResponse, proxy)
 
-       return enumResponse
+        return enumResponse
      }
    }
 
@@ -336,9 +313,172 @@ export function Enum(name, values, properties) {
    }
 
    Object.defineProperty(enumeration, property, data(dataValue, baseProps))
- }
+  }
+
+  return enumeration
+}
+
+export const EnumExtension = new Extension(Enum)
+
+
+
+/**
+ * Converts a given value to a string representation with additional
+ * options for description and string tag.
+ *
+ * @param {any} value - The value to be converted to a string. This can
+ *   be of any type, including objects, arrays, numbers, etc.
+ * @returns {string} A string representation of the input value, enhanced
+ *   with a description and string tag if applicable.
+ *
+ * @example
+ * // Convert a number to a string with additional options
+ * const result = asString(123)
+ * console.log(result) // Outputs: "123" with description and string tag
+ *
+ * @example
+ * // Convert an object to a string with additional options
+ * const obj = { key: 'value' }
+ * const result = asString(obj)
+ * console.log(result) // Outputs: "[object Object]" with description and
+ *                     // string tag
+ */
+function asString(value) {
+  return as.string(value, { description: true, stringTag: true })
+}
 
- return enumeration
+/**
+ * Creates a base enumeration object with predefined properties and
+ * symbols. This function is used to initialize an enumeration with
+ * specific characteristics, such as a name and various symbolic
+ * properties that enhance its functionality and identification.
+ *
+ * @param {string} name - The name of the enumeration. This name is
+ *   used to identify the enumeration and is stored as a symbol on
+ *   the object.
+ * @returns {Object} A new enumeration object with specific properties
+ *   and symbols set for enhanced functionality and identification.
+ *
+ * @example
+ * // Create a base enum with the name 'Color'
+ * const colorEnum = makeBaseEnum('Color')
+ * console.log(colorEnum[Symbol.for('Enum.name')]) // Outputs: 'Color'
+ */
+export function makeBaseEnum(name) {
+  return Object.create({}, {
+    /**
+     * Defines the `toStringTag` symbol on each enumeration to allow for
+     * type identification and to be consistent in naming conventions.
+     *
+     * @type {string}
+     */
+    [Symbol.toStringTag]: accessor('Enum', false, true, false),
+
+    /**
+     * In addition to the `toStringTag` symbol which defines this enumeration
+     * as an Enum type, the name of the enum is also codified in as a symbol
+     * on the object. It can be found using `Symbol.for('Enum.name')`.
+     *
+     * @type {string|symbol|number}
+     */
+    [Symbol.for('Enum.name')]: accessor(name, false, true, false),
+
+    /**
+     * Knowing which keys of the enum are part of the keys themselves is also
+     * crucial for enumerations. These can always be found on each Enum type
+     * as `Symbol.for('Enum.valueKeys')` as an array, but can also be found
+     * as the `.keys` property if there is no enum value of that name.
+     */
+    [Symbol.for('Enum.valueKeys')]: data([], false, true, false),
+
+    /**
+     * For users of the node.js REPL, this symbol represents enum types in a
+     * more readily readable format. See the docs for node's `util.inspect()`
+     * function for more details.
+     *
+     * @type {(number, object, Function) => string}
+     */
+    [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
+    ),
+
+    /**
+     * This function checks the supplied `possibleEnumValue` to see if it
+     * is an enum value type from this enum.
+     *
+     * @param {any} possibleEnumValue the value to evaluate
+     * @returns {boolean} returns `true` if the value is an enum value type
+     * from this `Enum`, irrespective of any associated value. Returns `false`
+     * otherwise.
+     */
+    isValueOf: data(function isValueOf(possibleEnumValue) {
+      if (!possibleEnumValue || typeof possibleEnumValue !== 'object')
+        return false
+
+      const enumValueType = possibleEnumValue?.type
+      const enumValueName = possibleEnumValue?.name
+
+      const thisEnumName = this[Symbol.for('Enum.name')]
+      const thisEnumKeys = this[Symbol.for('Enum.valueKeys')]
+
+      return (
+        enumValueType === thisEnumName &&
+        thisEnumKeys.includes(enumValueName)
+      )
+    }, false, true, false),
+
+    /**
+     * A simple overload of the `toString()` method to represent the enum
+     * more identifiably when called. The result will be the word enum with
+     * the name of the enum in parenthesis. So a Gender enum might be seen
+     * as `Enum(Gender)` as a result to calling this function.
+     *
+     * @returns {string} a {@link String} representation of this object.
+     */
+    toString: data(function toString() {
+      return `Enum(${name})`
+    }, false, true, false)
+  })
+
+  const applySyntacticSugar = () => {
+    createSymlinks(Symbol.for('Enum.valueKeys'), 'keys')
+    createSymlinks(Symbol.for('Enum.name'), 'name')
+  }
+
+  return [base, applySyntacticSugar]
 }
 
-export const EnumExtension = new Extension(Enum)
+/**
+ * Creates a symlink for a property from an existing key to a new key on
+ * the specified object. This function checks if the new key already
+ * exists on the object and, if not, it creates a new property with the
+ * same descriptor as the old key.
+ *
+ * Since this method creates the new link through the use of property
+ * descriptors, computed getters and setters also are mapped properly.
+ *
+ * @param {Object} on - The target object on which the symlink is to be
+ * created.
+ * @param {string|symbol} oldKey - The existing key whose property
+ * descriptor will be used for the new key.
+ * @param {string|symbol} newKey - The new key under which the property
+ * will be accessible.
+ *
+ * @example
+ * const obj = { a: 1 }
+ * createSymlink(obj, 'a', 'b')
+ * console.log(obj.b) // Outputs: 1
+ */
+function createSymlinks(on, oldKey, ...newKeys) {
+  redescribe(on, oldKey, {}, { alsoAs: newKeys })
+}

package/src/index.js

@@ -4,6 +4,7 @@ import { FunctionExtensions, FunctionPrototypeExtensions } from './function.exte
 import { GlobalFunctionsAndProps } from './global.this.js'
 import { JSONExtensions } from './json.extensions.js'
 import { MapExtensions, MapPrototypeExtensions } from './map.extensions.js'
+import { MathExtensions } from './math.extension.js'
 import { NumberExtensions, NumberPrototypeExtensions } from './number.extension.js'
 import { ObjectExtensions, ObjectPrototypeExtensions } from './object.extensions.js'
 import { ReflectExtensions } from './reflect.extensions.js'
@@ -29,6 +30,15 @@ import { RefSetExtensions } from './classes/refset.js'
 import { SymkeysExtension } from './classes/symkeys.js'
 import { TypeExtensions } from './classes/type.js'
 
+export * from './utils/stdout.js'
+import {
+  StringConsole,
+  StdoutGlobalPatches,
+  StringConsoleExtension,
+
+  captureStdout,
+} from './utils/stdout.js'
+
 export * from './utils/copy.object.js'
 export * from './utils/toolkit.js'
 export * from './utils/descriptor.utils.js'
@@ -44,6 +54,7 @@ const StaticPatches = [
   [Function, FunctionExtensions, Function.name],
   [JSON, JSONExtensions, 'JSON'],                // Missing a .name property
   [Map, MapExtensions, Map.name],
+  [Math, MathExtensions, 'Math'],
   [Number, NumberExtensions, Number.name],
   [Object, ObjectExtensions, Object.name],
   [Reflect, ReflectExtensions, 'Reflect'],       // Missing a .name property
@@ -68,6 +79,9 @@ const InstancePatches = [
 const Patches = new Map([
   ...StaticPatches,
   ...InstancePatches,
+
+  [globalThis, GlobalFunctionsAndProps, 'globalThis'], // Missing .name property
+  [globalThis, StdoutGlobalPatches, 'globalThis'],     // Missing .name property
 ])
 
 const Extensions = {
@@ -85,6 +99,7 @@ const Extensions = {
   [PropertyExtensions.key]: PropertyExtensions,
   [RefMapExtensions.key]: RefMapExtensions,
   [RefSetExtensions.key]: RefSetExtensions,
+  [StringConsoleExtension.key]: StringConsoleExtension,
   [SymkeysExtension.key]: SymkeysExtension,
   [TypeExtensions.key]: TypeExtensions,
 }
@@ -121,7 +136,6 @@ Object.assign(Controls, {
 
   enableExtensions() {
     Object.values(Extensions).forEach((extension) => { extension.apply() })
-    GlobalFunctionsAndProps.apply()
   },
 
   disableAll() {
@@ -147,7 +161,6 @@ Object.assign(Controls, {
 
   disableExtensions() {
     Object.values(Extensions).forEach((extension) => { extension.revert() })
-    GlobalFunctionsAndProps.revert()
   },
 })
 
@@ -193,7 +206,9 @@ export const all = (() => {
     .reduce(entriesReducer, dest.classes)
   )
 
-  for (const [key, entry] of GlobalFunctionsAndProps) {
+  const globals = [...GlobalFunctionsAndProps].concat([...StdoutGlobalPatches])
+
+  for (const [key, entry] of globals) {
     const descriptor = new Descriptor(entry.descriptor, entry.owner)
     Object.defineProperty(dest.global, key, descriptor.toObject(true))
   }
@@ -203,15 +218,16 @@ export const all = (() => {
 
 const results = {
   ...Controls,
+  all,
+  Controls,
   Extensions,
-  Patches,
+  extensions: Extensions,
   GlobalFunctionsAndProps,
-  StaticPatches,
   InstancePatches,
-  Controls,
-  extensions: Extensions,
+  Patches,
   patches: Patches,
-  all,
+  StaticPatches,
+  StdoutGlobalPatches,
 }
 
 export default results

package/src/math.extension.js

@@ -0,0 +1,73 @@
+import { Patch } from '@nejs/extension'
+
+/**
+ * `Math` extensions. Building better worlds...actually just
+ * providing some parity between Number and BigInt types for
+ * now, but later, better worlds.
+ *
+ * @type {Patch}
+ * @example
+ * import { MathExtensions } from 'math.extension.js'
+ *
+ * MathExtensions.apply()
+ * // Now the `Math` class has additional methods available
+ */
+export const MathExtensions = new Patch(Math, {
+  [Patch.kMutablyHidden]: {
+    /**
+     * The Math.min() static method returns the smallest of the numbers given
+     * as input parameters, or Infinity if there are no parameters.
+     *
+     * @param {bigint|number} values value1, …, valueN – Zero or more numbers
+     * among which the lowest value will be selected and returned.
+     * @returns {bigint|number|NaN|Infinity} The smallest of the given numbers.
+     * Returns NaN if any of the parameters is or is converted into NaN or if
+     * the types of numbers are mismatched (i.e., bigint vs. number types).
+     * Returns Infinity if no parameters are provided.
+     */
+    min(...values) {
+      const sorter = (l,r) => l < r ? -1 : l > r ? 1 : 0
+
+      if (!values.length)
+        return Infinity
+
+      if (values.every(n => typeof n === 'bigint')) {
+        return values.toSorted(sorter).at(0)
+      }
+      else if (values.every(n => typeof n === 'number')) {
+        return values.toSorted(sorter).at(0)
+      }
+      else {
+        return NaN
+      }
+    },
+
+    /**
+     * The Math.max() static method returns the largest of the numbers given
+     * as input parameters, or Infinity if there are no parameters.
+     *
+     * @param {bigint|number} values value1, …, valueN – Zero or more numbers
+     * among which the largest value will be selected and returned.
+     * @returns {bigint|number|NaN|Infinity} The largest of the given numbers.
+     * Returns NaN if any of the parameters is or is converted into NaN or if
+     * the types of numbers are mismatched (i.e., bigint vs. number types).
+     * Returns Infinity if no parameters are provided.
+     */
+    max(...values) {
+      const sorter = (l,r) => l < r ? -1 : l > r ? 1 : 0
+
+      if (!values.length)
+        return Infinity
+
+      if (values.every(n => typeof n === 'bigint')) {
+        return values.toSorted(sorter).at(-1)
+      }
+      else if (values.every(n => typeof n === 'number')) {
+        return values.toSorted(sorter).at(-1)
+      }
+      else {
+        return NaN
+      }
+    },
+  },
+})

package/src/number.extension.js

@@ -258,6 +258,24 @@ export const NumberPrototypeExtensions = new Patch(Number.prototype, {
     ifNumber(thenValue, elseValue) {
       return pIfNumber(this, thenValue, elseValue)
     },
+
+    /**
+     * Provides a way when dealing with numbers to determine if
+     * a given number is within a range of values. By default, if
+     * no parameters are supplied, it always returns true since
+     * the default range is -Infinity to +Infinity. Additionally,
+     * by default, the number will always be less than the supplied
+     * max unless inclusive is set to true.
+     *
+     * @param min the lower range value, defaults to -Infinity
+     * @param max the upper range value, defaults to +Infinity
+     * @param inclusive defaults to false, set to true if you
+     * want the max value to less than and equals to
+     * @returns {boolean} true if within the range, false otherwise
+     */
+    within(min = -Infinity, max = Infinity, inclusive = false) {
+      return this >= min && (inclusive ? this <= max : this < max)
+    }
   }
 })