@nejs/basic-extensions 2.6.0 → 2.8.0

package/package.json

@@ -49,7 +49,8 @@
   "name": "@nejs/basic-extensions",
   "scripts": {
     "preinstall": "npx only-allow pnpm",
-    "build": "bin/clean && bin/esbuild && bin/build && npm run documentation",
+    "build": "bin/clean && bin/esbuild && bin/build",
+    "distribute": "bin/clean && bin/esbuild && bin/build && npm run documentation",
     "browser": "bin/esbuild",
     "clean": "bin/clean",
     "jsdoc": "jsdoc -c jsdoc-config.json -p -a all -R README.md",
@@ -59,9 +60,10 @@
     "repl": "npm run build && node --no-warnings repl.bootstrap.js"
   },
   "type": "module",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "dependencies": {
-    "@nejs/extension": "^2.8.0"
+    "@nejs/extension": "^2.15.0",
+    "zod": "^3.22.5"
   },
-  "browser": "dist/@nejs/basic-extensions.bundle.2.5.0.js"
+  "browser": "dist/@nejs/basic-extensions.bundle.2.7.0.js"
 }

package/repl.bootstrap.js

@@ -128,11 +128,28 @@ function overridableGlobal(
   Object.defineProperty(globalThis, property, makeDescriptor());
 }
 
+/**
+ * Generates a snapshot of the current REPL state, categorizing global objects
+ * into classes, functions, properties, symbols, and descriptors. This function
+ * is designed to capture and organize the current state for inspection or
+ * modification purposes. It temporarily disables invocation to safely enumerate
+ * global objects, capturing their descriptors and categorizing them accordingly.
+ * If invocation is already disabled, it returns the current state without
+ * modification. Skipped properties during enumeration are tracked but not
+ * processed further.
+ *
+ * @returns {Object} An object representing the current REPL state, with
+ * properties for classes, functions, properties, symbols, and descriptors
+ * (further divided into accessors and data descriptors). Each category is an
+ * object with keys as the global identifiers and values containing the key,
+ * value, and descriptor of the item.
+ */
 function generateState() {
   const replState = {
     classes: {},
     functions: {},
     properties: {},
+    symbols: {},
     descriptors: {
       accessors: {},
       data: {},
@@ -161,6 +178,10 @@ function generateState() {
         replState.properties[key] = {key, value, descriptor};
       }
 
+      if (typeof key === 'symbol') {
+        replState.symbols[key] = { key, value, descriptor };
+      }
+
       if (Reflect.has(descriptor, 'get') || Reflect.has(descriptor, 'set')) {
         replState.descriptors.accessors[key] = { key, descriptor };
       }

package/src/array.extensions.js

@@ -0,0 +1,322 @@
+import { Patch } from '@nejs/extension'
+
+/**
+ * `ArrayExtensions` is a constant that applies a patch to the global
+ * `Array` constructor. This patch extends the `Array` with additional
+ * methods and properties, enhancing its functionality.
+ *
+ * The `Patch` function takes two arguments: the target object to be patched
+ * (in this case, `Array`), and an object containing the methods and
+ * properties to be added to the target object.
+ *
+ * @example
+ * // Using a method added by ArrayExtensions
+ * const arr = [1, 2, 3];
+ * console.log(Array.ifArray(arr, 'Array', 'Not Array')); // Output: 'Array'
+ *
+ * @const
+ * @type {Patch}
+ * @memberof module:array.extensions
+ */
+export const ArrayExtensions = new Patch(Array, {
+  /**
+   * Checks if the provided value is an array and returns one of two
+   * provided values based on the result. This function is a convenience
+   * method for performing conditional operations based on the type of
+   * the provided value.
+   *
+   * @name ifArray
+   * @type {function}
+   * @memberof ArrayExtensions
+   * @param {any} value - The value to be checked.
+   * @param {function | any} thenValue - The value to be returned if the
+   * provided value is an array.
+   * @param {function | any} elseValue - The value to be returned if the
+   * provided value is not an array.
+   * @returns {any} Returns `thenValue` if the provided value is an array,
+   * otherwise returns `elseValue`.
+   *
+   * @example
+   * const arr = [1, 2, 3];
+   * console.log(ArrayExtensions.ifArray(arr, 'Array', 'Not Array'));
+   * // Output: 'Array'
+   *
+   * const notArr = "I'm not an array";
+   * console.log(ArrayExtensions.ifArray(notArr, 'Array', 'Not Array'));
+   * // Output: 'Not Array'
+   */
+  ifArray(value, thenValue, elseValue) {
+    return isThenElse(Array.isArray(value), thenValue, elseValue)
+  },
+})
+
+const { ifArray: pIfArray } = ArrayExtensions.patches
+
+/**
+ * `ArrayPrototypeExtensions` is a constant that applies a patch to the
+ * Array prototype. This patch extends the Array prototype with additional
+ * methods and properties, enhancing its functionality.
+ *
+ * The `Patch` function takes two arguments: the target object to be patched
+ * (in this case, `Array.prototype`), and an object containing the methods
+ * and properties to be added to the target object.
+ *
+ * @example
+ * // Using a method added by ArrayPrototypeExtensions
+ * const arr = [1, 2, 3];
+ * console.log(arr.ifArray('Array', 'Not Array')); // Output: 'Array'
+ *
+ * @const
+ * @type {Patch}
+ * @memberof module:array.extensions
+ */
+export const ArrayPrototypeExtensions = new Patch(Array.prototype, {
+  [Patch.kMutablyHidden]: {
+    /**
+     * Sometimes defining even a short function for the invocation of `find`
+     * can be troublesome. This helper function performs that job for you. If
+     * the specified element is in the array, `true` will be returned.
+     *
+     * @param {*} value the value to search for. This value must triple equals
+     * the array element in order to return true.
+     * @returns true if the exact element exists in the array, false otherwise
+     */
+    contains(value) {
+      return !!this.find(entry => entry === value)
+    },
+
+    /**
+     * The `findEntry` function searches the entries of the object and returns
+     * the `[index, value]` entry array for the first matching value found.
+     *
+     * @param {function} findFn a function that takes the element to be checked
+     * and returns a boolean value
+     * @returns if `findFn` returns `true`, an array with two elements, the first
+     * being the index, the second being the value, is returned.
+     */
+    findEntry(findFn) {
+      const entries = this.entries()
+      const VALUE = 1
+
+      for (let entry of entries) {
+        if (findFn(entry[VALUE])) {
+          return entry
+        }
+      }
+
+      return undefined
+    },
+
+    /**
+     * A getter property that returns the first element of the array. If the
+     * array is empty, it returns `undefined`. This property is useful for
+     * scenarios where you need to quickly access the first item of an array
+     * without the need for additional checks or method calls.
+     *
+     * @returns {*} The first element of the array or `undefined` if the array
+     * is empty.
+     */
+    get first() {
+      return this[0];
+    },
+
+    /**
+     * A getter property that checks if the current context (`this`) is an
+     * array. This is a convenience method that wraps the native
+     * `Array.isArray` function.
+     *
+     * @name isArray
+     * @type {function}
+     * @memberof Array.prototype
+     * @returns {boolean} `true` if the current context is an array,
+     * `false` otherwise.
+     *
+     * @example
+     * const arr = [1, 2, 3];
+     * console.log(arr.isArray); // Output: true
+     *
+     * const notArr = "I'm not an array";
+     * console.log(notArr.isArray); // Output: false
+     */
+    get isArray() {
+      return Array.isArray(this)
+    },
+
+    /**
+     * Checks if the current context (`this`) is an array and returns one of
+     * two provided values based on the result. This function is a convenience
+     * method for performing conditional operations based on the type of
+     * the current context.
+     *
+     * @name ifArray
+     * @type {function}
+     * @memberof Array.prototype
+     * @param {function | any} thenValue - The value to be returned if the
+     * current context is an array.
+     * @param {function | any} elseValue - The value to be returned if the
+     * current context is not an array.
+     * @returns {*} Returns `thenValue` if the current context is an array,
+     * otherwise returns `elseValue`.
+     *
+     * @example
+     * const arr = [1, 2, 3];
+     * console.log(arr.ifArray('Array', 'Not Array')); // Output: 'Array'
+     *
+     * const notArr = "I'm not an array";
+     * console.log(notArr.ifArray('Array', 'Not Array')); // Output: 'Not Array'
+     */
+    ifArray(thenValue, elseValue) {
+      return pIfArray(this, thenValue, elseValue)
+    },
+
+    /**
+     * Checks if at least one element in the array is equal to the provided
+     * value. This method uses the `Array.prototype.some` function to iterate
+     * over the array and compare each element with the provided value.
+     *
+     * @name oneIs
+     * @type {function}
+     * @memberof Array.prototype
+     * @param {*} value - The value to be compared with the array elements.
+     * @param {boolean} [doubleEqualsOkay=true] - A flag indicating whether to
+     * use loose equality (`==`) or strict equality (`===`) for the comparison.
+     * If `true`, loose equality is used. If `false`, strict equality is used.
+     * @returns {boolean} Returns `true` if at least one element in the array
+     * is equal to the provided value, otherwise `false`.
+     *
+     * @example
+     * const arr = [1, 2, 3];
+     * console.log(arr.oneIs(2)); // Output: true
+     *
+     * const arr2 = ['1', '2', '3'];
+     * console.log(arr2.oneIs(2, false)); // Output: false
+     */
+    oneIs(value, doubleEqualsOkay = true) {
+      return this.some(element => (
+        doubleEqualsOkay ? element == value : element === value
+      ))
+    },
+
+    /**
+     * Checks if some elements in the array are included in the provided values.
+     * This method uses the `Array.prototype.some` function to iterate over the
+     * array and checks if any of the elements are included in the provided values.
+     *
+     * @name someAre
+     * @type {function}
+     * @memberof Array.prototype
+     * @param {...*} values - The values to be checked against the array elements.
+     * @returns {boolean} Returns `true` if at least one element in the array
+     * is included in the provided values, otherwise `false`.
+     *
+     * @example
+     * const arr = [1, 2, 3];
+     * console.log(arr.someAre(2, 4)); // Output: true
+     *
+     * const arr2 = ['1', '2', '3'];
+     * console.log(arr2.someAre(4, 5)); // Output: false
+     */
+    someAre(...values) {
+      return this.some(element => !!~values.indexOf(element))
+    },
+
+    /**
+     * Checks if all elements in the array are equal to the provided value.
+     * This method uses the `Array.prototype.every` function to iterate over
+     * the array and compare each element with the provided value.
+     *
+     * @name allAre
+     * @type {function}
+     * @memberof Array.prototype
+     * @param {*} value - The value to be compared with the array elements.
+     * @param {boolean} [doubleEqualsOkay=true] - A flag indicating whether to
+     * use loose equality (`==`) or strict equality (`===`) for the comparison.
+     * If `true`, loose equality is used. If `false`, strict equality is used.
+     * @returns {boolean} Returns `true` if all elements in the array are equal
+     * to the provided value, otherwise `false`.
+     *
+     * @example
+     * const arr = [2, 2, 2];
+     * console.log(arr.allAre(2)); // Output: true
+     *
+     * const arr2 = ['2', '2', '2'];
+     * console.log(arr2.allAre(2, false)); // Output: false
+     */
+    allAre(value, doubleEqualsOkay = true) {
+      return this.every(element => (
+        doubleEqualsOkay ? element == value : element === value
+      ))
+    },
+
+   /**
+     * A getter property that returns the last element of the array. It
+     * calculates the last index based on the array's length. If the array is
+     * empty, it returns `undefined`. This property is beneficial when you need
+     * to access the last item in an array, improving code readability and
+     * avoiding manual index calculation.
+     *
+     * @returns {*} The last element of the array or `undefined` if the
+     * array is empty.
+     */
+    get last() {
+      return this[this.length - 1];
+    },
+
+    // expected usage:
+    // function example(name, age) {
+    //   const variants = [{name}, {age}].variants()
+    //   if (typeof name === 'object')
+    // }
+    variants() {
+      const keys = this.map(o => Object.keys(o)?.[0])
+      const entries = this.map(o => Object.entries(o)?.[0])
+      const object = entries.reduce((acc,[key, value]) => {
+        acc[key] = value;
+        return acc;
+      }, {})
+
+      const result = {
+        order: keys,
+        entries: entries,
+        object: object,
+      }
+
+      Object.defineProperty(result, 'check', {
+        value(position) {
+          if (
+            typeof position !== 'number' &&
+            position >= 0 &&
+            position < this.order.length
+          ) {
+            return false
+          }
+
+          const value = this.entries[position][1]
+
+          if (typeof value === 'object' && value) {
+            if (Object.keys(value).every(key => ~this.order.indexOf(key))) {
+              return true
+            }
+          }
+
+          return false
+        },
+        enumerable: false,
+        configurable: true
+      })
+
+      return result
+    },
+  },
+})
+
+// NOTE to self; this is repeated here otherwise a circular reference from
+// Object<->Function<->Global occurs. See original source in global.this.js
+// {@see globalThis.isThenElse}
+function isThenElse(bv, tv, ev) {
+  if (arguments.length > 1) {
+    var _then = isFunction(tv) ? tv(bv) : tv; if (arguments.length > 2) {
+      var _else = isFunction(ev) ? tv(bv) : ev; return bv ? _then : _else
+    } return bv || _then;
+  } return bv
+}

package/src/big.int.extension.js

@@ -0,0 +1,163 @@
+import { Patch } from '@nejs/extension'
+
+/**
+ * `BigIntExtensions` is a patch for the JavaScript built-in `BigInt` class.
+ * It adds utility methods to the `BigInt` class without modifying the global
+ * namespace directly. This patch includes methods for checking if a value is
+ * a `BigInt` and conditionally returning a value based on whether the supplied
+ * value is a `BigInt` or not.
+ *
+ * @type {Patch}
+ * @example
+ * import { BigIntExtensions } from 'big.int.extension.js'
+ *
+ * BigIntExtensions.apply()
+ * // Now the `BigInt` class has additional methods available
+ */
+export const BigIntExtensions = new Patch(BigInt, {
+  /**
+   * Determines if the supplied `value` is a `BigInt`. This check is
+   * performed by first checking the `typeof` the `value` and then
+   * checking to see if the `value` is an `instanceof` `BigInt`
+   *
+   * @param {*} value The value that needs to be checked to determine
+   * if it is a `BigInt` or not
+   * @returns {boolean} `true` if the supplied `value` is a `BigInt`,
+   * `false` otherwise
+   *
+   * @example
+   * const bigInt = 1234567890123456789012345678901234567890n
+   * isBigInt(bigInt) // true
+   * isBigInt(1234567890123456789012345678901234567890) // false
+   * isBigInt('1234567890123456789012345678901234567890') // false
+   * isBigInt(BigInt('1234567890123456789012345678901234567890')) // true
+   */
+  isBigInt(value) {
+    return typeof value === 'bigint' || value instanceof BigInt
+  },
+
+  /**
+   * Conditionally returns a value based on whether the supplied
+   * `value` is a `BigInt` or not. If the `value` is a `BigInt`,
+   * the `thenValue` will be returned. If it is not a `BigInt`,
+   * the `elseValue` will be returned instead.
+   *
+   * @param {any} value The value to check to determine if it is a
+   * `BigInt`
+   * @param {any} thenValue The value to return if the supplied
+   * `value` is a `BigInt`
+   * @param {any} elseValue The value to return if the supplied
+   * `value` is not a `BigInt`
+   * @returns {any} Either the `thenValue` or `elseValue` depending
+   * on if the supplied `value` is a `BigInt`
+   *
+   * @example
+   * const bigInt = 1234567890123456789012345678901234567890n
+   * const num = 42
+   * ifBigInt(bigInt, 'is a BigInt', 'not a BigInt')
+   * // 'is a BigInt'
+   * ifBigInt(num, 'is a BigInt', 'not a BigInt')
+   * // 'not a BigInt'
+   */
+  ifBigInt(value, thenValue, elseValue) {
+    return isThenElse(this.isBigInt(value), thenValue, elseValue)
+  },
+})
+
+const { isBigInt: pIsBigInt, ifBigInt: pIfBigInt } = BigIntExtensions.patches
+
+/**
+ * `BigIntPrototypeExtensions` is a patch for the JavaScript built-in
+ * `BigInt.prototype`. It adds utility methods to the `BigInt` prototype
+ * without modifying the global namespace directly. This patch includes
+ * methods for checking if a value is a BigInt and conditionally returning
+ * a value based on whether the supplied value is a BigInt or not.
+ *
+ * @type {Patch}
+ * @example
+ * import { BigIntPrototypeExtensions } from 'big.int.extension.js'
+ *
+ * BigIntPrototypeExtensions.apply()
+ * // Now the `BigInt` prototype has additional methods available
+ */
+export const BigIntPrototypeExtensions = new Patch(BigInt.prototype, {
+  /**
+   * A getter method that returns an object representation of the BigInt
+   * instance.
+   *
+   * This method wraps the BigInt instance in an object, allowing it to be
+   * treated as an object. The returned object is created using the `Object()`
+   * constructor, which takes the BigInt instance as its argument.
+   *
+   * @type {Object}
+   * @readonly
+   *
+   * @example
+   * const bigInt = 1234567890123456789012345678901234567890n
+   * console.log(typeof bigInt)           // 'bigint'
+   * console.log(typeof bigInt.instance)  // 'object'
+   */
+  get instance() {
+    return Object(this)
+  },
+
+  /**
+   * A getter method that checks if the current instance is a BigInt.
+   *
+   * This method uses the `pIsBigInt` function from the `BigIntExtensions`
+   * patch to determine if the current instance (`this`) is a BigInt.
+   *
+   * @type {boolean}
+   * @readonly
+   *
+   * @example
+   * const bigInt = 1234567890123456789012345678901234567890n
+   * console.log(bigInt.isBigInt) // Output: true
+   *
+   * const notBigInt = 42
+   * console.log(notBigInt.isBigInt) // Output: false
+   */
+  get isBigInt() {
+    return pIsBigInt(this)
+  },
+
+  /**
+   * Checks if the current object is a BigInt and returns the corresponding
+   * value based on the result.
+   *
+   * This method uses the `pIfBigInt` function from the `BigIntExtensions`
+   * patch to determine if the current object (`this`) is a BigInt. If it is
+   * a BigInt, the `thenValue` is returned. Otherwise, the `elseValue` is
+   * returned.
+   *
+   * @param {any} thenValue - The value to return if the current object
+   * is a BigInt.
+   * @param {any} elseValue - The value to return if the current object
+   * is not a BigInt.
+   * @returns {any} The `thenValue` if the current object is a BigInt, or
+   * the `elseValue` if it is not a BigInt.
+   *
+   * @example
+   * const bigInt = 1234567890123456789012345678901234567890n
+   * // 'Is a BigInt'
+   * console.log(bigInt.ifBigInt('Is a BigInt', 'Not a BigInt'))
+   *
+   * const notBigInt = 42
+   * // 'Not a BigInt'
+   * console.log(notBigInt.ifBigInt('Is a BigInt', 'Not a BigInt'))
+   */
+  ifBigInt(thenValue, elseValue) {
+    return pIfBigInt(this, thenValue, elseValue)
+  },
+})
+
+// NOTE to self; this is repeated here otherwise a circular reference from
+// Object<->Function<->Global occurs. See original source in global.this.js
+// {@see globalThis.isThenElse}
+function isThenElse(bv, tv, ev) {
+  if (arguments.length > 1) {
+    var _then = isFunction(tv) ? tv(bv) : tv; if (arguments.length > 2) {
+      var _else = isFunction(ev) ? tv(bv) : ev; return bv ? _then : _else
+    } return bv || _then;
+  } return bv
+}

package/src/{newClasses → classes}/descriptor.js

@@ -1,9 +1,4 @@
 import { Extension } from '@nejs/extension'
-import { ObjectExtensions } from '../objectextensions.js'
-import { ReflectExtensions } from '../reflectextensions.js'
-
-const { isObject, isValidKey } = ObjectExtensions.patches
-const { hasSome } = ReflectExtensions.patches
 
 export class Descriptor {
   /**
@@ -36,7 +31,7 @@ export class Descriptor {
    * is to be created. This parameter is ignored if `object` is a Descriptor
    * instance. If `key` is an object and `object` is a valid descriptor, `key`
    * is treated as the associated object.
-   * @throws {Error} Throws an error if the constructed descriptor is not 
+   * @throws {Error} Throws an error if the constructed descriptor is not
    * valid.
    */
   constructor(object, key) {
@@ -46,7 +41,7 @@ export class Descriptor {
     else if (Descriptor.isDescriptor(object)) {
       this.#desc = object
       this.#object = isObject(key) ? key : undefined
-    } 
+    }
     else if (isObject(object) && isValidKey(key)) {
       this.#desc = Object.getOwnPropertyDescriptor(object, key)
       this.#object = object
@@ -327,7 +322,7 @@ export class Descriptor {
    */
   applyTo(object, forKey, bindAccessors = false) {
     if (!isObject(object) || !isValidKey(forKey)) {
-      throw new Error(`Cannot apply descriptor to non-object or invalid key`)
+      throw new Error( `Cannot apply descriptor to non-object or invalid key`)
     }
 
     return Object.defineProperty(object, forKey, this.toObject(bindAccessors))
@@ -337,7 +332,7 @@ export class Descriptor {
    * Converts this Descriptor class instance into a basic object descriptor
    * that is accepted by all the standard JavaScript runtime methods that
    * deal with object descriptors.
-   * 
+   *
    * @param {boolean|object} bindAccessors if `true`, a non-fatal attempt to
    * bind accessor getter and setter methods is made before returning the
    * object. If `bindAccessors` is truthy and is also an object, this is the
@@ -351,8 +346,8 @@ export class Descriptor {
 
     if (bindAccessors && this.isAccessor) {
       if (this.hasObject) {
-        descriptor = { 
-          ...descriptor, 
+        descriptor = {
+          ...descriptor,
           get: this.boundGet,
           set: this.boundSet
         }
@@ -702,4 +697,13 @@ export class Descriptor {
   }
 }
 
-export const DescriptorExtensions = new Extension(Descriptor)
+export const DescriptorExtensions = new Extension(Descriptor)
+
+function isObject(o) { return o && typeof o === 'object' }
+function isValidKey(o) { return ['string','symbol'].some(t => typeof o === t) }
+function hasSome(object, ...keys) {
+  return isObject(object) && (keys.flat(Infinity)
+    .map(key => Reflect.has(object, key))
+    .some(has => has)
+  )
+}

package/src/classes/index.js

@@ -0,0 +1,51 @@
+import { Patch } from '@nejs/extension'
+
+import { AsyncIterable, AsyncIterator } from './asyncIterable.js'
+export * from './asyncIterable.js'
+
+import { Deferred } from './deferred.js'
+export * from './deferred.js'
+
+import { Descriptor } from './descriptor.js'
+export * from './descriptor.js'
+
+import { Introspector } from './introspector.js'
+export * from './introspector.js'
+
+import {Iterable, Iterator } from './iterable.js'
+export * from './iterable.js'
+
+import { ParamParser } from './param.parser.js'
+export * from './param.parser.js'
+
+import { PluggableProxy, ProxyHandler } from './pluggable.proxy.js'
+export * from './pluggable.proxy.js'
+
+import { RefMap  } from './refmap.js'
+export * from './refmap.js'
+
+import { RefSet } from './refset.js'
+export * from './refset.js'
+
+import { Symkeys } from './symkeys.js'
+export * from './symkeys.js'
+
+import { Type } from './type.js'
+export * from './type.js'
+
+export const NewClassesExtension = new Patch(globalThis, {
+  AsyncIterable,
+  AsyncIterator,
+  Deferred,
+  Descriptor,
+  Introspector,
+  Iterable,
+  Iterator,
+  ParamParser,
+  PluggableProxy,
+  ProxyHandler,
+  RefMap,
+  RefSet,
+  Symkeys,
+  Type,
+})