@nejs/basic-extensions 1.6.0 → 1.7.0

package/src/objectextensions.js

@@ -1,14 +1,26 @@
 import { Patch } from '@nejs/extension';
 
 /**
- * `ObjectExtensions` is a patch for the JavaScript built-in `Object` class. It
- * adds utility methods to the `Object` class without modifying the global namespace
- * directly. This patch includes methods for key validation, object type checking,
- * and retrieving the string tag of an object. These methods are useful for
- * enhancing the capabilities of the standard `Object` class with additional
- * utility functions.
+ * `ObjectExtensions` is a patch for the JavaScript built-in `Object` class.
+ * It adds utility methods to the `Object` class without modifying the global
+ * namespace directly. This patch includes methods for key validation, object
+ * type checking, and retrieving the string tag of an object. These methods
+ * are useful for enhancing the capabilities of the standard `Object` class
+ * with additional utility functions.
  */
 export const ObjectExtensions = new Patch(Object, {
+  /**
+   * The function checks if a value is either `undefined` or `null`.
+   *
+   * @param {any} value - The parameter "value" is a variable that can hold
+   * any value.
+   * @returns {boolean} `true` if the value is either `undefined` or `null`,
+   * and `false` otherwise.
+   */
+  isNullDefined(value) {
+    return value === undefined || value === null
+  },
+
   /**
    * Checks to see if the supplied `value` is both an object, and has the
    * appropriate symbol defined.
@@ -22,19 +34,27 @@ export const ObjectExtensions = new Patch(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.
+   * 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 object whose string tag is to be retrieved.
+   * @param {boolean} strict - if this is set to true, undefined will be
+   * returned whenever a supplied object does not have a
+   * `Symbol.toStringTag` defined, period. if false, the default,
    * @returns {string} - The string tag of the object, indicating its type.
    */
-  getStringTag(value) {
+  getStringTag(value, strict = false) {
     if (Object.hasStringTag(value)) {
       return value[Symbol.toStringTag]
     }
 
+    if (strict) {
+      return undefined
+    }
+
     if (value && (typeof value === 'function')) {
       return value.name
     }
@@ -54,13 +74,13 @@ export const ObjectExtensions = new Patch(Object, {
    *
    * @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.
+   * 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)
@@ -74,13 +94,14 @@ export const ObjectExtensions = new Patch(Object, {
   },
 
   /**
-   * Determines if the provided value is an object. This method checks whether the
-   * value is an instance of `Object` or if its type is 'object'. It's a utility
-   * method for type-checking, ensuring that a value is an object before performing
-   * operations that are specific to objects.
+   * Determines if the provided value is an object. This method checks whether
+   * the value is an instance of `Object` or if its type is 'object'. It's a
+   * utility method for type-checking, ensuring that a value is an object
+   * before performing operations that are specific to objects.
    *
    * @param {*} value - The value to be checked.
-   * @returns {boolean} - Returns `true` if the value is an object, otherwise `false`.
+   * @returns {boolean} - Returns `true` if the value is an object,
+   * otherwise `false`.
    */
   isObject(value) {
     return value && (value instanceof Object || typeof value === 'object');
@@ -115,13 +136,14 @@ 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.
+   * 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`.
+   * @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');
@@ -134,37 +156,66 @@ export const ObjectExtensions = new Patch(Object, {
    * @param {object} object the object to pare down
    * @param {Array<string|symbol>} keys the keys that should appear in the
    * final reduced object
-   * @param {boolean} [bindAccessors = true] if this value is true
-   * then any accessors from the source object will continue to have their
-   * `this` value bound to the source. If the getter or setter on that object
-   * is defined using an arrow function, this will not work as intended.
-   * @returns {object} an object containing only the keys and symbols specified
-   * in the `keys` parameter.
+   * @param {boolean} [bindAccessors = true] if this value is true then any
+   * accessors from the source object will continue to have their `this`
+   * value bound to the source. If the getter or setter on that object is
+   * defined using an arrow function, this will not work as intended.
+   * @returns {object} an object containing only the keys and symbols
+   * specified in the `keys` parameter.
    */
   stripTo(object, keys, bindAccessors = true) {
-    const result = {}
+    if (!object || typeof object !== 'object') {
+      throw new TypeError(
+        'Object.stripTo requires an object to strip. Received',
+        object
+      );
+    }
+
+    const result = {};
 
     if (!Array.isArray(keys)) {
-      return result
+      return result;
     }
 
     for (let key of keys) {
       if (Reflect.has(object, key)) {
-        const descriptor = Object.getOwnPropertyDescriptor(object, key)
-        if (Reflect.has(descriptor, 'get') || Reflect.has(descriptor, 'set')) {
+        const originalDescriptor = Object.getOwnPropertyDescriptor(object, key);
+        const descriptor = { ...originalDescriptor };
+
+        if (
+          typeof descriptor.get === 'function' ||
+          typeof descriptor.set === 'function'
+        ) {
           if (bindAccessors) {
-            descriptor.get = descriptor?.get?.bind(object)
-            descriptor.set = descriptor?.set?.bind(object)
+            descriptor.get = descriptor.get?.bind(object);
+            descriptor.set = descriptor.set?.bind(object);
           }
-          Object.defineProperty(result, descriptor)
-        }
-        else {
-          Object.defineProperty(result, descriptor)
         }
+
+        Object.defineProperty(result, key, descriptor);
       }
     }
 
-    return result
+    return result;
   },
-
 });
+
+export const ObjectPrototypeExtensions = new Patch(Object.prototype, {
+  /**
+   * Strips an object down to only the keys specified. Optionally, any
+   * accessors can be made to retain their context on the source object.
+   * This is a passthrough to the static {@link Object.stripTo} function
+   *
+   * @param {Array<string|symbol>} keys the keys that should appear in the
+   * final reduced object
+   * @param {boolean} [bindAccessors = true] if this value is true then any
+   * accessors from the source object will continue to have their `this`
+   * value bound to the source. If the getter or setter on that object is
+   * defined using an arrow function, this will not work as intended.
+   * @returns {object} an object containing only the keys and symbols
+   * specified in the `keys` parameter.
+   */
+  stripTo(keys, bindAccessors = true) {
+    return Object.stripTo(this, keys, bindAccessors)
+  }
+})

package/src/reflectextensions.js

@@ -1,6 +1,8 @@
 import { Patch } from '@nejs/extension'
 import { ObjectExtensions } from './objectextensions.js'
 
+const { isObject } = ObjectExtensions.patches
+
 /**
  * The `ReflectExtensions` class is a patch applied to the built-in JavaScript
  * `Reflect` object. It extends `Reflect` with additional utility methods that
@@ -31,20 +33,22 @@ export const ReflectExtensions = new Patch(Reflect, {
     )
   },
 
+  /**
+   * Fetches all descriptors of an object, including those mapped to a
+   * symbol descriptor value.
+   *
+   * @param {object} object the object from whose descriptors need to be
+   * retrieved.
+   * @returns {object} with keys mapped to object descriptors
+   * @throws {TypeError} if the supplied `object` is null or not an object
+   * a TypeError exception will be thrown
+   */
   ownDescriptors(object) {
-    const result = {}
-    const revertOnDone = () => revertOnDone.doIt ? ObjectExtensions.revert() : ''
-    revertOnDone.doIt = false
-
-    if (!Object.isObject) {
-      revertOnDone.doIt = true
-      ObjectExtensions.apply()
+    if (!isObject(object)) {
+      throw new TypeError('The supplied object must be non-null and an object')
     }
 
-    if (!Object.isObject(object)) {
-      revertOnDone()
-      return {}
-    }
+    const result = {}
 
     const keys = Reflect.ownKeys(object)
 
@@ -52,8 +56,6 @@ export const ReflectExtensions = new Patch(Reflect, {
       result[key] = Object.getOwnPropertyDescriptor(key)
     }
 
-    revertOnDone()
-
     return result
   },
 
@@ -69,7 +71,7 @@ export const ReflectExtensions = new Patch(Reflect, {
    * at least one of the keys provided as arguments exists in the given object.
    */
   hasSome(object, ...keys) {
-    return Object.isObject(object) && (keys.flat(Infinity)
+    return isObject(object) && (keys.flat(Infinity)
       .map(key => Reflect.has(object, key))
       .some(has => has)
     )

package/src/symbolextensions.js

@@ -60,7 +60,8 @@ export const SymbolExtensions = new Patch(Symbol, {
    * spec static symbols (`toStringTag`, `iterator`, etc...), and any symbols
    * created by passing a value directly to the `Symbol` function, such as
    * `Symbol('name')`
-   * @returns
+   * @returns true if the `value` in question is both a `symbol` and has
+   * returns `undefined` if passed to `Symbol.keyFor`
    */
   isNonRegistered(value, allowOnlySymbols = false) {
     return !Symbol.isRegistered(value, allowOnlySymbols)

package/tests/index.test.js

@@ -1,4 +1,4 @@
-const { enableAll, disableAll } = require('../dist/cjs/index.js')
+const { Controls: { enableAll, disableAll } } = require('../dist/cjs/index.js')
 
 describe('Enabled extensions', () => {
   beforeEach(() => {

package/tests/{asyncIterable.test.js → newClasses/asyncIterable.test.js}

@@ -1,9 +1,8 @@
-const { enableAll, disableAll } = require('../dist/cjs/index.js')
+const { Extensions } = require('../../dist/cjs/index.js')
+const AsyncIterable = Extensions.AsyncIterable.class
+const Iterable = Extensions.Iterable.class
 
 describe('AsyncIterable', () => {
-  beforeAll(() => { enableAll() })
-  afterAll(() => { disableAll() })
-
   test('should create an async iterable from an array of promises', async () => {
     const promises = [Promise.resolve(1), Promise.resolve(2), Promise.resolve(3)];
     const asyncIterable = new AsyncIterable(promises);

package/tests/newClasses/descriptor.test.js

@@ -0,0 +1,252 @@
+const { Extensions } = require('../../dist/cjs/index.js')
+const Descriptor = Extensions.Descriptor.class
+
+describe('Descriptor', () => {
+  describe('constructor', () => {
+    test('should create a Descriptor from a property descriptor', () => {
+      const obj = { a: 1 };
+      const desc = new Descriptor(Object.getOwnPropertyDescriptor(obj, 'a'));
+      expect(desc.isData).toBe(true);
+      expect(desc.value).toBe(1);
+    });
+
+    test('should throw an error for invalid descriptors', () => {
+      expect(() => new Descriptor(5)).toThrow();
+    });
+  });
+
+  describe('isAccessor', () => {
+    test('should return true for accessor descriptors', () => {
+      const getter = () => {};
+      const setter = (value) => {};
+      const obj = {};
+      Object.defineProperty(obj, 'prop', { get: getter, set: setter });
+      const desc = new Descriptor(obj, 'prop');
+      expect(desc.isAccessor).toBe(true);
+    });
+
+    test('should return false for data descriptors', () => {
+      const obj = { a: 1 };
+      const desc = new Descriptor(obj, 'a');
+      expect(desc.isAccessor).toBe(false);
+    });
+  });
+
+  describe('isData', () => {
+    test('should return true for data descriptors', () => {
+      const obj = { a: 1 };
+      const desc = new Descriptor(obj, 'a');
+      expect(desc.isData).toBe(true);
+    });
+
+    test('should return false for accessor descriptors', () => {
+      const obj = {};
+      Object.defineProperty(obj, 'prop', {
+        get: () => {},
+        set: (value) => {}
+      });
+      const desc = new Descriptor(obj, 'prop');
+      expect(desc.isData).toBe(false);
+    });
+  });
+
+  describe('isDescriptor', () => {
+    test('should return true for valid descriptors', () => {
+      const desc = new Descriptor({ value: 10 });
+      expect(desc.isDescriptor).toBe(true);
+    });
+
+    test('should throw an error for invalid descriptors', () => {
+      expect(() => new Descriptor({})).toThrow()
+    });
+  });
+
+  describe('getters and setters', () => {
+    let desc;
+
+    beforeEach(() => {
+      desc = new Descriptor({ value: 10, writable: true, enumerable: true, configurable: true });
+    });
+
+    test('configurable getter and setter', () => {
+      expect(desc.configurable).toBe(true);
+      desc.configurable = false;
+      expect(desc.configurable).toBe(false);
+    });
+
+    test('enumerable getter and setter', () => {
+      expect(desc.enumerable).toBe(true);
+      desc.enumerable = false;
+      expect(desc.enumerable).toBe(false);
+    });
+
+    test('writable getter and setter', () => {
+      expect(desc.writable).toBe(true);
+      desc.writable = false;
+      expect(desc.writable).toBe(false);
+    });
+
+    test('value getter and setter', () => {
+      expect(desc.value).toBe(10);
+      desc.value = 20;
+      expect(desc.value).toBe(20);
+    });
+  });
+
+  describe('applyTo', () => {
+    test('should apply descriptor to an object', () => {
+      const obj = {};
+      const desc = new Descriptor({
+        configurable: true,
+        enumerable: true,
+        value: 10,
+        writable: true
+      });
+      desc.applyTo(obj, 'a');
+      expect(obj.a).toBe(10);
+    });
+
+    test('should throw error for non-object or invalid key', () => {
+      const desc = new Descriptor({ value: 10 });
+      expect(() => desc.applyTo(123, 'a')).toThrow();
+      expect(() => desc.applyTo({}, null)).toThrow();
+    });
+  });
+
+  describe('static methods', () => {
+    describe('getData', () => {
+      test('should return the value of a data property', () => {
+        const obj = { a: 10 };
+        expect(Descriptor.getData(obj, 'a')).toBe(10);
+      });
+
+      test('should return undefined for non-data properties', () => {
+        const obj = {};
+        Object.defineProperty(obj, 'prop', {
+          get: () => 20,
+          set: (value) => {}
+        });
+        expect(Descriptor.getData(obj, 'prop')).toBeNull();
+      });
+    });
+
+    describe('getAccessor', () => {
+      test('should return value of getter', () => {
+        const obj = {
+          get prop() { return 20 }
+        };
+        const accessedValue = Descriptor.getAccessor(obj, 'prop');
+        expect(accessedValue).toBe(20)
+      });
+
+      test('should return value getter when dependent on an adajcent value', () => {
+        const obj = {
+          age: 21,
+          get canDrink() { return this.age >= 21 }
+        };
+        const accessedValue = Descriptor.getAccessor(obj, 'canDrink');
+        expect(accessedValue).toBe(true)
+      });
+
+      test('should return null for non-accessor properties', () => {
+        const obj = { a: 10 };
+        expect(Descriptor.getAccessor(obj, 'a')).toBeNull();
+      });
+    });
+
+    describe('for', () => {
+      test('should return a descriptor for a given object property', () => {
+        const obj = { a: 10 };
+        const descriptor = Descriptor.for(obj, 'a');
+        expect(descriptor.value).toBe(10);
+        expect(descriptor.writable).toBe(true);
+        expect(descriptor.enumerable).toBe(true);
+        expect(descriptor.configurable).toBe(true);
+      });
+
+      test('should return null for invalid inputs', () => {
+        expect(Descriptor.for(null, 'a')).toBeNull();
+        expect(Descriptor.for({}, Symbol())).toBeNull();
+      });
+    });
+
+    describe('accessor', () => {
+      test('should create an accessor descriptor', () => {
+        const getter = () => 'get';
+        const setter = (value) => { /* Do nothing */ };
+        const descriptor = Descriptor.accessor(getter, setter);
+        expect(descriptor.get).toBe(getter);
+        expect(descriptor.set).toBe(setter);
+        expect(descriptor.enumerable).toBe(false);
+        expect(descriptor.configurable).toBe(false);
+      });
+
+      // Additional tests for variations in enumerable and configurable
+    });
+
+    describe('data', () => {
+      test('should create a data descriptor', () => {
+        const value = 10;
+        const descriptor = Descriptor.data(value);
+        expect(descriptor.value).toBe(value);
+        expect(descriptor.writable).toBe(true);
+        expect(descriptor.enumerable).toBe(false);
+        expect(descriptor.configurable).toBe(false);
+      });
+
+      // Additional tests for variations in writable, enumerable, and configurable
+    });
+
+  });
+
+  describe('Symbol methods', () => {
+    test('Symbol.for("nodejs.util.inspect.custom") should return custom inspect info', () => {
+      const desc = new Descriptor({ value: 10 });
+      expect(typeof desc[Symbol.for('nodejs.util.inspect.custom')]).toBe('function');
+    });
+
+    test('Symbol.toPrimitive should handle different hints', () => {
+      const dataDesc = new Descriptor({ value: 10 });
+      const accessorDesc = new Descriptor({
+        age: 18,
+        get canDrink() { return this.age >= 21 },
+        set canDrink(value) {
+          if (value)
+            this.age = Math.max(21, this.age)
+          else
+            this.age = Math.min(20, this.age)
+        },
+      }, 'canDrink')
+
+      expect(dataDesc[Symbol.toPrimitive]('string')).toBe('Data (value)');
+      dataDesc.writable = true
+      expect(dataDesc[Symbol.toPrimitive]('string')).toBe('Data (value, writable)')
+      expect(isNaN(dataDesc[Symbol.toPrimitive]('number'))).toBe(true);
+
+      expect(accessorDesc[Symbol.toPrimitive]('string')).toBe(
+        'Accessor (getter, setter)'
+      )
+      expect(accessorDesc[Symbol.toPrimitive]('number')).toBe(NaN)
+      expect(accessorDesc.boundGet()).toBe(false)
+      expect(accessorDesc.hasObject).toBe(true)
+      expect(accessorDesc.set).toBeTruthy()
+      accessorDesc.boundSet?.(true)
+      expect(accessorDesc.boundGet()).toBe(true)
+    });
+  });
+
+  describe('static properties', () => {
+    test('SHARED_KEYS should contain expected keys', () => {
+      expect(Descriptor.SHARED_KEYS).toEqual(['configurable', 'enumerable']);
+    });
+
+    test('ACCESSOR_KEYS should contain expected keys', () => {
+      expect(Descriptor.ACCESSOR_KEYS).toEqual(['get', 'set']);
+    });
+
+    test('DATA_KEYS should contain expected keys', () => {
+      expect(Descriptor.DATA_KEYS).toEqual(['value', 'writable']);
+    });
+  });
+
+});

package/tests/{iterable.test.js → newClasses/iterable.test.js}

@@ -1,9 +1,7 @@
-const { enableAll, disableAll } = require('../dist/cjs/index.js')
+const { Extensions } = require('../../dist/cjs/index.js')
+const Iterable = Extensions.Iterable.class
 
 describe('Iterable', () => {
-  beforeAll(() => { enableAll() })
-  afterAll(() => { disableAll() })
-
   test('should create an iterable from an array', () => {
     const array = [1, 2, 3];
     const iterable = new Iterable(array);

package/tests/newClasses/refmap.test.js

@@ -0,0 +1,69 @@
+const { Extensions } = require('../../dist/cjs/index.js')
+const RefMap = Extensions.RefMap.class
+
+describe('RefMap', () => {
+  let refMap;
+
+  beforeEach(() => {
+    refMap = new RefMap();
+  });
+
+  // Test the constructor
+  test('should create an empty RefMap', () => {
+    expect(refMap.size).toBe(0);
+  });
+
+  // Test objectifying behavior
+  test('should toggle objectify values', () => {
+    refMap.objectifying(true);
+    expect(refMap.objectifyValues).toBe(true);
+    refMap.objectifying(false);
+    expect(refMap.objectifyValues).toBe(false);
+  });
+
+  // Test set and get methods
+  test('should set and get weakly referenced values', () => {
+    const obj = {};
+    refMap.set('key', obj);
+    expect(refMap.get('key')).toBe(obj);
+    expect(refMap.size).toBe(1);
+  });
+
+  // Test handling of primitives
+  test('should handle primitives when objectifying is true', () => {
+    refMap.objectifying(true);
+    refMap.set('number', 123);
+    expect(typeof refMap.get('number')).toBe('object');
+  });
+
+  // Test error handling
+  test('should throw error for invalid values in set', () => {
+    expect(() => refMap.set('key', undefined)).toThrow(TypeError);
+  });
+
+  // Test asObject method
+  test('asObject should return a regular object', () => {
+    const obj = {};
+    refMap.set('key', obj);
+    const regularObject = refMap.asObject();
+    expect(typeof regularObject).toBe('object');
+    expect(regularObject.key).toBe(obj);
+  });
+
+  // Test hasValue method
+  test('hasValue should correctly determine the presence of a value', () => {
+    const obj = {};
+    refMap.set('key', obj);
+    expect(refMap.hasValue(obj)).toBe(true);
+    expect(refMap.hasValue({})).toBe(false);
+  });
+
+  // Test forEach method
+  test('forEach should iterate over values', () => {
+    const mockCallback = jest.fn();
+    const obj = {};
+    refMap.set('key', obj);
+    refMap.forEach(mockCallback);
+    expect(mockCallback.mock.calls.length).toBe(1);
+  });
+});

package/tests/{refset.test.js → newClasses/refset.test.js}

@@ -1,9 +1,7 @@
-const { enableAll, disableAll } = require('../dist/cjs/index.js')
+const { Extensions } = require('../../dist/cjs/index.js')
+const RefSet = Extensions.RefSet.class
 
 describe('RefSet', () => {
-  beforeAll(() => { enableAll() })
-  afterAll(() => { disableAll() })
-
   let refSet;
 
   beforeEach(() => {