@nejs/basic-extensions 1.3.0 → 1.4.0

package/dist/cjs/objectextensions.js

@@ -12,16 +12,45 @@ const extension_1 = require("@nejs/extension");
  */
 exports.ObjectExtensions = new extension_1.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
@@ -36,16 +65,42 @@ exports.ObjectExtensions = new extension_1.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
@@ -83,33 +138,4 @@ exports.ObjectExtensions = new extension_1.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/dist/mjs/descriptor.js

@@ -171,6 +171,20 @@ class Descriptor {
     set set(value) {
         (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.

package/dist/mjs/functionextensions.js

@@ -17,7 +17,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));
     },
     /**
      * Checks if a given value is a regular function. This method verifies if the value is

package/dist/mjs/globals.d.ts

@@ -0,0 +1,2 @@
+export const GlobalFunctionsAndProps: Patch;
+import { Patch } from '@nejs/extension';

package/dist/mjs/globals.js

@@ -0,0 +1,174 @@
+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/dist/mjs/index.d.ts

@@ -1,9 +1,12 @@
 export function enableAll(owners: any): void;
 export function disableAll(owners: any): void;
+export const all: {};
 import { ObjectExtensions } from './objectextensions.js';
 import { FunctionExtensions } from './functionextensions.js';
 import { ReflectExtensions } from './reflectextensions.js';
 import { StringExtensions } from './stringextensions.js';
 import { SymbolExtensions } from './symbolextensions.js';
 import { ArrayPrototypeExtensions } from './arrayextensions.js';
-export { ObjectExtensions, FunctionExtensions, ReflectExtensions, StringExtensions, SymbolExtensions, ArrayPrototypeExtensions };
+import { GlobalFunctionsAndProps } from './globals.js';
+import { DescriptorExtension } from './descriptor.js';
+export { ObjectExtensions, FunctionExtensions, ReflectExtensions, StringExtensions, SymbolExtensions, ArrayPrototypeExtensions, GlobalFunctionsAndProps, DescriptorExtension };

package/dist/mjs/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';
 const Owners = [
     Object,
@@ -15,6 +16,7 @@ const Owners = [
     Array.prototype,
 ];
 const NetNew = [
+    GlobalFunctionsAndProps,
     DescriptorExtension,
 ];
 export function enableAll(owners) {
@@ -41,4 +43,24 @@ export function disableAll(owners) {
         extension.revert();
     });
 }
-export { ObjectExtensions, FunctionExtensions, ReflectExtensions, StringExtensions, SymbolExtensions, ArrayPrototypeExtensions, };
+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, ReflectExtensions, StringExtensions, SymbolExtensions, ArrayPrototypeExtensions, GlobalFunctionsAndProps, DescriptorExtension, };

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.3.0",
+  "version": "1.4.0",
   "dependencies": {
     "@nejs/extension": "^1.2.1"
   },
-  "browser": "dist/@nejs/basic-extensions.bundle.1.2.0.js"
+  "browser": "dist/@nejs/basic-extensions.bundle.1.3.0.js"
 }

package/src/descriptor.js

@@ -192,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.

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))
   },
 
   /**