@nejs/basic-extensions 1.2.0 → 1.4.0

package/dist/mjs/objectextensions.js

@@ -9,16 +9,45 @@ import { Patch } from '@nejs/extension';
  */
 export const ObjectExtensions = new Patch(Object, {
     /**
-     * Checks if the given value is a valid key for an object. In JavaScript, a valid
-     * key can be either a string or a symbol. This method is useful for validating
-     * object keys before using them in operations like setting or getting object properties.
+     * Retrieves the string tag of an object. The string tag is a representation of
+     * the object's type, as defined by its `Object.prototype.toString` method. This
+     * utility method is helpful for getting a more descriptive type of an object than
+     * what is returned by the `typeof` operator, especially for custom objects.
      *
-     * @param {*} value - The value to be checked.
-     * @returns {boolean} - Returns `true` if the value is a valid object key (string or symbol),
-     *                      otherwise `false`.
+     * @param {*} value - The object whose string tag is to be retrieved.
+     * @returns {string} - The string tag of the object, indicating its type.
      */
-    isValidKey(value) {
-        return (typeof value === 'string' || typeof value === 'symbol');
+    getStringTag(value) {
+        return /\s(.+)]/.exec(Object.prototype.toString.call(value))[1];
+    },
+    /**
+     * Determines the type of the given value based on its string tag. This method
+     * uses `Object.getStringTag` to obtain the string tag of the value, which
+     * represents its more specific type (e.g., Array, Map, Set) rather than just
+     * 'object'. The method then maps this string tag to the corresponding type
+     * present in the provided `owner` object, which defaults to `globalThis`.
+     * This utility method is especially useful for identifying the specific
+     * constructor or class of an object, beyond the basic types identified by
+     * the `typeof` operator.
+     *
+     * @param {any} value - The value whose type is to be determined.
+     * @param {object} [owner=globalThis] - The object in which to look up the
+     * constructor corresponding to the string tag. Defaults to `globalThis`, which
+     * covers global constructors like `Array`, `Object`, etc.
+     * @returns {Function|object|null|undefined} - Returns the constructor or type
+     * of the value based on its string tag. For 'Null' and 'Undefined', it returns
+     * `null` and `undefined`, respectively. For other types, it returns the
+     * corresponding constructor (e.g., `Array` for arrays) if available in the
+     * `owner` object.
+     */
+    getType(value, owner = globalThis) {
+        const stringTag = Object.getStringTag(value);
+        switch (stringTag) {
+            case 'Null': return null;
+            case 'Undefined': return undefined;
+            default:
+                return owner[stringTag];
+        }
     },
     /**
      * Determines if the provided value is an object. This method checks whether the
@@ -33,16 +62,42 @@ export const ObjectExtensions = new Patch(Object, {
         return value && (value instanceof Object || typeof value === 'object');
     },
     /**
-     * Retrieves the string tag of an object. The string tag is a representation of
-     * the object's type, as defined by its `Object.prototype.toString` method. This
-     * utility method is helpful for getting a more descriptive type of an object than
-     * what is returned by the `typeof` operator, especially for custom objects.
+     * Checks to see if the supplied value is a primitive value.
      *
-     * @param {*} value - The object whose string tag is to be retrieved.
-     * @returns {string} - The string tag of the object, indicating its type.
+     * @param {any} value the value to test to see if it is a primitive value type
+     * @returns true if the object is considered widely to be a primitive value,
+     * false otherwise.
      */
-    getStringTag(value) {
-        return /\s(.+)]/.exec(Object.prototype.toString.call(value))[1];
+    isPrimitive(value) {
+        // Check for null as a special case because typeof null
+        // is 'object'
+        if (value === null) {
+            return true;
+        }
+        // Check for other primitives
+        switch (typeof value) {
+            case 'string':
+            case 'number':
+            case 'bigint':
+            case 'boolean':
+            case 'undefined':
+            case 'symbol':
+                return true;
+            default:
+                return false;
+        }
+    },
+    /**
+     * Checks if the given value is a valid key for an object. In JavaScript, a valid
+     * key can be either a string or a symbol. This method is useful for validating
+     * object keys before using them in operations like setting or getting object properties.
+     *
+     * @param {*} value - The value to be checked.
+     * @returns {boolean} - Returns `true` if the value is a valid object key (string or symbol),
+     *                      otherwise `false`.
+     */
+    isValidKey(value) {
+        return (typeof value === 'string' || typeof value === 'symbol');
     },
     /**
      * Strips an object down to only the keys specified. Optionally, any
@@ -80,33 +135,4 @@ export const ObjectExtensions = new Patch(Object, {
         }
         return result;
     },
-    /**
-     * Determines the type of the given value based on its string tag. This method
-     * uses `Object.getStringTag` to obtain the string tag of the value, which
-     * represents its more specific type (e.g., Array, Map, Set) rather than just
-     * 'object'. The method then maps this string tag to the corresponding type
-     * present in the provided `owner` object, which defaults to `globalThis`.
-     * This utility method is especially useful for identifying the specific
-     * constructor or class of an object, beyond the basic types identified by
-     * the `typeof` operator.
-     *
-     * @param {any} value - The value whose type is to be determined.
-     * @param {object} [owner=globalThis] - The object in which to look up the
-     * constructor corresponding to the string tag. Defaults to `globalThis`, which
-     * covers global constructors like `Array`, `Object`, etc.
-     * @returns {Function|object|null|undefined} - Returns the constructor or type
-     * of the value based on its string tag. For 'Null' and 'Undefined', it returns
-     * `null` and `undefined`, respectively. For other types, it returns the
-     * corresponding constructor (e.g., `Array` for arrays) if available in the
-     * `owner` object.
-     */
-    getType(value, owner = globalThis) {
-        const stringTag = Object.getStringTag(value);
-        switch (stringTag) {
-            case 'Null': return null;
-            case 'Undefined': return undefined;
-            default:
-                return owner[stringTag];
-        }
-    },
 });

package/package.json

@@ -46,9 +46,9 @@
     "test": "jest"
   },
   "type": "module",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "dependencies": {
     "@nejs/extension": "^1.2.1"
   },
-  "browser": "dist/@nejs/basic-extensions.bundle.1.0.0.js"
+  "browser": "dist/@nejs/basic-extensions.bundle.1.3.0.js"
 }

package/src/descriptor.js

@@ -1,11 +1,12 @@
 import { Extension } from '@nejs/extension'
 import { ObjectExtensions } from './objectextensions.js'
+import { StringExtensions } from './stringextensions.js'
 import { ReflectExtensions } from './reflectextensions.js'
 
-const isObject = ObjectExtensions.patchEntries.isObject.computed
-const isValidKey = ObjectExtensions.patchEntries.isValidKey.computed
-const isString = ObjectExtensions.patchEntries.isString.computed
-const hasSome = ReflectExtensions.patchEntries.hasSome.computed
+const isObject = ObjectExtensions.patchEntries?.isObject?.computed
+const isValidKey = ObjectExtensions.patchEntries?.isValidKey?.computed
+const isString = StringExtensions.patchEntries?.isString?.computed
+const hasSome = ReflectExtensions.patchEntries?.hasSome?.computed
 
 class Descriptor {
   #desc = Descriptor.enigmatic
@@ -22,15 +23,44 @@ class Descriptor {
   constructor(object, key) {
     this.#desc = object
 
-    if (object && key) {
+    if (isObject(object) && isValidKey(key)) {
       this.#desc = Object.getOwnPropertyDescriptor(object, key)
     }
 
-    if (!Descriptor.isDescriptor(this.#desc)) {
+    if (!this.isDescriptor) {
       throw new Error(`Not a valid descriptor:`, this.#desc)
     }
   }
 
+  /**
+   * Detects whether or not this instance is an accessor object descriptor
+   *
+   * @returns {boolean} true if this object has a getter or setter and is not
+   * a data descriptor
+   */
+  get isAccessor() {
+    return Descriptor.isAccessor(this.#desc)
+  }
+
+  /**
+   * Detects whether or not this instance is an data object descriptor
+   *
+   * @returns {boolean} true if this object has a value property and is not
+   * an accessor descriptor
+   */
+  get isData() {
+    return Descriptor.isData(this.#desc)
+  }
+
+  /**
+   * Detects whether or not this instance is a valid object 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.
@@ -39,7 +69,7 @@ class Descriptor {
    * descriptor store is invalid.
    */
   get configurable() {
-    return !!this.#desc?.configurable ?? undefined
+    return !!this.#desc?.configurable
   }
 
   /**
@@ -162,6 +192,22 @@ class Descriptor {
     (this.#desc || {}).set = value
   }
 
+  /**
+   * 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) {
+    if (!isObject(object) && !isValidKey(key)) {
+      return null
+    }
+
+    return Object.getOwnPropertyDescriptor(object, key)
+  }
+
   /**
    * Take the descriptor defined by this objects values and apply them to
    * the specified object using the specified key.
@@ -175,7 +221,7 @@ class Descriptor {
       throw new Error(`Cannot apply descriptor to non-object or invalid key`)
     }
 
-    Object.defineProperty(object, forKey, this.#desc)
+    return Object.defineProperty(object, forKey, this.#desc)
   }
 
   /**
@@ -383,13 +429,7 @@ class Descriptor {
       ...Descriptor.DATA_KEYS,
     ]
 
-    let isa = (hasSome(knownKeys) && (
-      Descriptor.isAccessor(object) ||
-      Descriptor.isData(object)
-      )
-    )
-
-    return isa
+    return hasSome(object, knownKeys)
   }
 
   /**
@@ -423,7 +463,7 @@ class Descriptor {
       validData = true
     }
 
-    return false
+    return validData
   }
 
   /**

package/src/functionextensions.js

@@ -18,7 +18,7 @@ export const FunctionExtensions = new Patch(Function, {
    * @returns {boolean} Returns `true` if the value is a class, otherwise `false`.
    */
   isClass(value) {
-    return value instanceof Function && String(value).includes('class');
+    return value instanceof Function && !!/^class\s/.exec(String(value))
   },
 
   /**

package/src/globals.js

@@ -0,0 +1,216 @@
+import { Patch } from '@nejs/extension'
+import { FunctionExtensions } from './functionextensions.js'
+
+const { isClass, isFunction } = FunctionExtensions.patchEntries.isClass.computed
+const CustomInspect = Symbol.for('nodejs.util.inspect.custom')
+
+export const GlobalFunctionsAndProps = new Patch(globalThis, {
+  asBigIntObject(
+    bigIntPrimitive
+  ) {
+    const base = { configurable: true, enumerable: false }
+    const object = { value: bigIntPrimitive }
+
+    Object.defineProperties(object, {
+      // @ts-ignore
+      [Symbol.toPrimitive]: { value: function() { return bigIntPrimitive }, ...base },
+      [Symbol.toStringTag]: { value: BigInt.name, ...base },
+      [Symbol.species]: { get() { return BigInt }, ...base },
+      [CustomInspect]: { ...base, value(depth, opts, inspect) {
+        return inspect(this[Symbol.toPrimitive](), { ...opts, depth })
+      }}
+    })
+
+    Object.setPrototypeOf(object, BigInt.prototype)
+
+    Reflect.ownKeys(BigInt.prototype).forEach(key => {
+      if (typeof object[key] !== 'function') {
+        return
+      }
+
+      object[key] = (function (...args) {
+        return BigInt.prototype[key].apply(this, args)
+      }).bind(object.value)
+    })
+
+    return object
+  },
+
+  /**
+   * Transforms an object to mimic a specified prototype, altering its type conversion
+   * and inspection behaviors. This function is especially useful for creating objects
+   * that need to behave like different primitive types under various operations.
+   *
+   * @param {Object} object - The object to be transformed.
+   * @param {Function|Object} [prototype=String.prototype] - The prototype or class to
+   * emulate. If a function is provided, its prototype is used. Defaults to
+   * String.prototype.
+   * @param {Function} [toPrimitive=(hint, val) => String(val)] - A function defining how
+   * the object should be converted to a primitive value. It receives a type hint
+   * ('number', 'string', or 'default') and the object, returning the primitive value.
+   * @returns {Object|null} The transformed object, or null if neither a class nor a
+   * prototype could be derived from the provided prototype parameter.
+   */
+  maskAs(object, classPrototype, options) {
+    const {
+      prototype,
+      toPrimitive
+    } = GenericMask({...options, prototype: classPrototype})
+
+    const base = { configurable: true, enumerable: false }
+    const proto = isFunction(prototype) ? prototype.prototype : prototype
+    const klass = isClass(prototype) ? prototype : proto?.constructor
+
+    if (!klass && !proto) {
+      return null
+    }
+
+    Object.setPrototypeOf(object, proto)
+    Object.defineProperties(object, {
+      valueOf: { value() { return String(toPrimitive('default', object)) }, ...base },
+
+      [Symbol.toPrimitive]: { value(hint) { return toPrimitive(hint, object) }, ...base },
+      [Symbol.toStringTag]: { value: klass.name, ...base },
+      [Symbol.species]: { get() { return klass }, ...base },
+      [CustomInspect]: { ...base, value(depth, opts, inspect) {
+        return inspect(this[Symbol.toPrimitive](), { ...opts, depth })
+      }}
+    })
+
+    return object
+  },
+
+  /**
+   * Masks an object as a string-like object by setting its prototype to String and
+   * defining how it converts to primitive types. This is particularly useful when an
+   * object needs to behave like a string in certain contexts, such as type coercion or
+   * logging.
+   *
+   * @param {Object} object - The object to be masked as a string.
+   * @param {string} [stringKey='value'] - The object property key used for the string
+   * representation. Defaults to 'value'.
+   * @param {Function} [toPrimitive] - Optional custom function for primitive conversion.
+   * If omitted, a default function handling various conversion hints is used.
+   * @returns {Object|null} The string-masked object, or null if the object doesn't have
+   * the specified stringKey property.
+   */
+  maskAsString(
+    object,
+    stringKey,
+    toPrimitive
+  ) {
+    if (object && Reflect.has(object, stringKey)) {
+      return maskAs(object, StringMask(stringKey ?? 'value', toPrimitive))
+    }
+
+    return null
+  },
+
+  /**
+   * Masks an object as a number-like object. This allows the object to behave like a
+   * number in operations like arithmetic and type coercion. It sets the prototype to
+   * Number and defines custom conversion behavior.
+   *
+   * @param {Object} object - The object to be masked as a number representation.
+   * Defaults to 'value'.
+   * @param {Function} [toPrimitive] - Optional custom function for primitive
+   * conversion. If not provided, a default function handling different conversion
+   * hints is used.
+   * @returns {Object|null} The number-masked object, or null if the object doesn't
+   * have the specified numberKey property.
+   */
+  maskAsNumber(
+    object,
+    numberKey,
+    toPrimitive
+  ) {
+    if (object && Reflect.has(object, numberKey)) {
+      return maskAs(object, NumberMask(numberKey ?? 'value', toPrimitive))
+    }
+
+    return null
+  },
+
+  /**
+   * Generates options for generic masking of an object, providing defaults for
+   * prototype and toPrimitive function if not specified.
+   *
+   * @param {Object} options - The options object including prototype, targetKey,
+   * and toPrimitive function.
+   * @returns {Object} The options object with defaults applied as necessary.
+   */
+  GenericMask({ prototype, targetKey = 'value', toPrimitive }) {
+    const options = { targetKey, toPrimitive, prototype };
+
+    if (!isFunction(toPrimitive)) {
+      options.toPrimitive = (hint, object) => {
+        let property = object[targetKey];
+        let isNum = (typeof property === 'number' && Number.isFinite(property)) ||
+                    (typeof property === 'string' &&
+                    !isNaN(parseFloat(property)) && isFinite(property)
+                    );
+
+        switch (hint) {
+          case 'string': return isNum ? String(property) : (property ?? String(object));
+          case 'number': return isNum ? Number(property) : NaN;
+          case 'default':
+          default:
+            return isNum ? Number(property) : property;
+        }
+      }
+    }
+
+    return options;
+  },
+
+  /**
+   * Generates options for string masking of an object, providing a default toPrimitive
+   * function if not specified.
+   *
+   * @param {string} targetKey - The object property key for string representation.
+   * @param {Function} toPrimitive - Custom function for primitive conversion.
+   * @returns {Object} Options for string masking.
+   */
+  StringMask(targetKey, toPrimitive) {
+    const options = { targetKey, toPrimitive, prototype: String.prototype }
+
+    if (!isFunction(toPrimitive)) {
+      options.toPrimitive = function toPrimitive(hint, object) {
+        switch (hint) {
+          case 'default': return object[targetKey]
+          case 'number': return parseInt(object[targetKey], 36)
+          case 'string': return String(object[targetKey])
+          default: return object
+        }
+      }
+    }
+
+    return options
+  },
+
+  /**
+   * Generates options for number masking of an object, providing a default toPrimitive
+   * function if not specified.
+   *
+   * @param {string} targetKey - The object property key for number representation.
+   * @param {Function} toPrimitive - Custom function for primitive conversion.
+   * @returns {Object} Options for number masking.
+   */
+  NumberMask(targetKey, toPrimitive) {
+    const options = { targetKey, toPrimitive, prototype: Number.prototype }
+
+    if (!isFunction(toPrimitive)) {
+      options.toPrimitive = function toPrimitive(hint, object) {
+        switch (hint) {
+          case 'default': return object[targetKey]
+          case 'number': return Number(object[targetKey])
+          case 'string': return String(object[targetKey])
+          default: return object
+        }
+      }
+    }
+
+    return options
+  },
+
+})

package/src/index.js

@@ -5,6 +5,7 @@ import { StringExtensions } from './stringextensions.js'
 import { SymbolExtensions } from './symbolextensions.js'
 import { ArrayPrototypeExtensions } from './arrayextensions.js'
 import { DescriptorExtension } from './descriptor.js'
+import { GlobalFunctionsAndProps } from './globals.js'
 
 import { Patch } from '@nejs/extension'
 
@@ -19,29 +20,68 @@ const Owners = [
 ]
 
 const NetNew = [
+  GlobalFunctionsAndProps,
   DescriptorExtension,
 ]
 
 export function enableAll(owners) {
-  (owners || Owners).forEach(owner => {
+  const list = owners || Owners
+
+  if (!list) {
+    throw new Error('Unable to enable features without owners list')
+  }
+
+  list.forEach(owner => {
     Patch.enableFor(owner)
   })
 
-  (NetNew).forEach(extension => {
+  NetNew.forEach(extension => {
     extension.apply()
   })
 }
 
 export function disableAll(owners) {
-  (owners || Owners).forEach(owner => {
+  const list = owners || Owners
+
+  if (!list) {
+    throw new Error('Unable to disable features without owners list')
+  }
+
+  list.forEach(owner => {
     Patch.disableFor(owner)
   })
 
-  (NetNew).forEach(extension => {
+  NetNew.forEach(extension => {
     extension.revert()
   })
 }
 
+export const all = (() => {
+  let extensions = [
+    ObjectExtensions,
+    FunctionExtensions,
+    ReflectExtensions,
+    StringExtensions,
+    SymbolExtensions,
+    ArrayPrototypeExtensions,
+
+    GlobalFunctionsAndProps,
+    DescriptorExtension,
+  ]
+
+  const dest = extensions.reduce((accumulator, extension) => {
+    Reflect.ownKeys(extension.patchEntries).reduce((_, key) => {
+      accumulator[key] = extension.patchEntries[key].computed
+      return accumulator
+    }, accumulator)
+
+    return accumulator
+  }, {})
+
+  return dest
+})()
+
+
 export {
   ObjectExtensions,
   FunctionExtensions,
@@ -49,4 +89,7 @@ export {
   StringExtensions,
   SymbolExtensions,
   ArrayPrototypeExtensions,
+
+  GlobalFunctionsAndProps,
+  DescriptorExtension,
 }