@nejs/basic-extensions 2.7.0 → 2.8.0

package/dist/cjs/symbol.extensions.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SymbolPrototypeExtensions = exports.SymbolExtensions = void 0;
+const extension_1 = require("@nejs/extension");
+const symkeys_js_1 = require("./classes/symkeys.js");
+const json_extensions_js_1 = require("./json.extensions.js");
+const { extractFrom, mightContain } = json_extensions_js_1.JSONExtensions.patches;
+/**
+ * `SymbolExtensions` is a patch for the JavaScript built-in `Symbol` class. It
+ * adds utility methods to the `Symbol` 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 `Symbol` class with additional
+ * utility functions.
+ */
+exports.SymbolExtensions = new extension_1.Patch(Symbol, {
+    /**
+     * Creates a new Symbol with the given name and optional data. If data
+     * is provided, it will be stringified and appended to the symbol's
+     * name. This method is useful for creating unique symbols that carry
+     * additional metadata.
+     *
+     * @param {string} name The name of the symbol.
+     * @param {*} [data] Optional data to be associated with the symbol.
+     * @returns {symbol} A new symbol created with Symbol.for(), using the
+     * provided name and stringified data (if provided).
+     *
+     * @example
+     * const symbolWithData = Symbol.withData('mySymbol', { foo: 'bar' })
+     * console.log(symbolWithData.toString())
+     * // Output: "Symbol(mySymbol {"foo":"bar"})"
+     *
+     * @example
+     * const symbolWithoutData = Symbol.withData('mySymbol')
+     * console.log(symbolWithoutData.toString())
+     * // Output: "Symbol(mySymbol)"
+     */
+    withData(name, data) {
+        return data !== undefined
+            ? Symbol.for(`${name} ${JSON.stringify(data)}`)
+            : Symbol.for(name);
+    },
+    /**
+     * The `isSymbol` method does exactly what one would it expect. It returns
+     * true if the string matches typeof or instanceof as a symbol.
+     *
+     * @param {*} value checks to see if the `value` is a string
+     * @returns {boolean} `true` if it is a `Symbol`, `false` otherwise
+     */
+    isSymbol(value) {
+        return value && (typeof value === 'symbol');
+    },
+    /**
+     * Returns true if the supplied value is a Symbol created using
+     * `Symbol.for()`.
+     *
+     * @param {any} value assumption is that the supplied value is of type
+     * 'symbol' however, unless `allowOnlySymbols` is set to `true`, `false`
+     * will be returned for any non-symbol values.
+     * @param {boolean} allowOnlySymbols true if an error should be thrown
+     * if the supplied value is not of type 'symbol'
+     * @returns true if the symbol is registered, meaning, none of the spec
+     * static symbols (`toStringTag`, `iterator`, etc...), and no symbols
+     * created by passing a value directly to the Symbol function, such as
+     * `Symbol('name')`
+     */
+    isRegistered(value, allowOnlySymbols = false) {
+        if (!Symbol.isSymbol(value)) {
+            if (allowOnlySymbols) {
+                throw new TypeError('allowOnlySymbols specified; value is not a symbol');
+            }
+            return false;
+        }
+        return Symbol.keyFor(value) !== undefined;
+    },
+    /**
+     * A function that returns true if the symbol is not registered, meaning,
+     * any of the spec static symbols (`toStringTag`, `iterator`, etc...), and
+     * any symbols created by passing a value directly to the `Symbol` function,
+     * such as `Symbol('name')`.
+     *
+     * @param {any} value assumption is that the supplied value is of type
+     * 'symbol' however, unless allowOnlySymbols is set to true, false will
+     * be returned for any non-symbol values.
+     * @param {boolean} allowOnlySymbols true if an error should be thrown
+     * if the supplied value is not of type 'symbol'
+     * @returns true if the symbol is not registered, meaning, any of the
+     * spec static symbols (`toStringTag`, `iterator`, etc...), and any symbols
+     * created by passing a value directly to the `Symbol` function, such as
+     * `Symbol('name')`
+     * @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);
+    },
+    /**
+     * `keys` is an instance of the `Symkeys` class, initialized with the
+     * domain 'nejs'. The `Symkeys` class provides a way to easily generate
+     * Symbol.for elements that follow particular pattern. Symkeys also
+     * allows associated data storage with each generated key.
+     *
+     * @type {Symkeys}
+     * @see {@link SymKeys}
+     * @example
+     * // Returns something like Symbol.for('@nejs.prototype #rwiy2o905d')
+     * const kOriginal = Symbol.keys.add('prototypes')
+     *
+     * // Which can be used to retrieve and fetch data associated with that key
+     * // The value stored is an array by default, but can be anything. It can
+     * // be accessed one property at a time
+     * Symbol.keys[kOriginal].original = Object.prototype
+     * Symbol.keys[kOriginal].modified = Object.create(Object.prototype, ...)
+     *
+     * // Or wholesale replaced
+     * Symbol.keys[kOriginal] = [Object.prototype, Array.prototype]
+     *
+     * // But if all Symbol Extensions are in place, including prototype add-ons
+     * kOriginal.data.original = Object.prototype           // ...and...
+     * kOriginal.data = [Object.prototype, Array.prototype] // ...both work
+     */
+    keys: new symkeys_js_1.Symkeys('nejs'),
+});
+exports.SymbolPrototypeExtensions = new extension_1.Patch(Symbol.prototype, {
+    [extension_1.Patch.kMutablyHidden]: {
+        /**
+         * Returns an object representation of the symbol instance.
+         *
+         * This getter method creates and returns an object that wraps the
+         * symbol instance, allowing it to be treated as an object. The
+         * returned object is created using the `Object()` constructor,
+         * which takes the symbol instance as its argument.
+         *
+         * @type {Object}
+         * @readonly
+         *
+         * @example
+         * const sym = Symbol('example')
+         * console.log(typeof sym)        // 'symbol'
+         * console.log(typeof sym.instance) // 'object'
+         */
+        get instance() {
+            return Object(this);
+        },
+        /**
+         * Getter method for retrieving the data associated with a symbol.
+         *
+         * This method first checks if the symbol is a Symkey created symbol
+         * by checking the existence of Symbol.keys and if the symbol's
+         * description matches the Symkey pattern. If it is a Symkey symbol,
+         * it attempts to fetch its associated data.
+         *
+         * NOTE: Symkey data is returned as its value directly, this is because
+         * it is stored in a {@link Map}. Embedded JSON data might be expensive
+         * to parse and as such a function is returned when data is accessed that
+         * needs to be invoked in order to decode its contents. See
+         * `{@link mightHaveEmbeddedJSON}` for more information.
+         *
+         * If the symbol is not a Symkey symbol or if no data is associated
+         * with it, the method attempts to parse the symbol's description as
+         * JSON and returns the first valid JSON object found.
+         *
+         * If no valid JSON object is found in the description, the method
+         * returns undefined.
+         *
+         * @type {Object|Function}
+         * @readonly
+         *
+         * @example
+         * const keys = new Symkeys
+         * const key = keys.add('example', {count: 0})
+         * const data = key.data // note this isn't function!!
+         * const count = data.count
+         *
+         * @example
+         * const sym = Symbol.for('fun {"name":"Brie"}')
+         * let json = sym.data() // {name: 'Brie'} JS object
+         *
+         * @example
+         * const sym = Symbol('mySymbol')
+         * let data = sym.data() // undefined
+         */
+        get data() {
+            if (Symbol?.keys && symkeys_js_1.Symkeys.isSymkey(this)) {
+                const possibleData = Symbol.keys[this];
+                if (possibleData) {
+                    return possibleData;
+                }
+            }
+            return extractFrom(string);
+        },
+        /**
+         * Sets the data associated with a symbol.
+         *
+         * This setter method checks if the symbol is a Symkey and if it has
+         * associated data. If both conditions are met, it sets the data of the
+         * symbol to the provided value and returns true. If the conditions are
+         * not met, it simply returns false.
+         *
+         * While Symbols have been upgraded to also support embedded JSON data
+         * with this extension, symbol descriptions are static. Non Symkey symbols
+         * do not associated their data outside of a symbol, and cannot be changed,
+         * there new data cannot be set on them.
+         *
+         * @param {any} value - The value to be set as the symbol's data.
+         * @returns {boolean} - Returns true if the data was successfully set,
+         * false otherwise.
+         *
+         * @example
+         * const sym = Symbol.for('fun {"name":"Brie"}')
+         * Symkeys.isSymkey(sym) // false; not in Symkey format
+         * let json = sym.data() // {name: 'Brie'} JS object
+         * sym.data = JSON.stringify({name: 'Jane'}) // fails silently
+         * json = sym.data() // {name: 'Brie'} is hard-coded in description
+         *
+         * @example
+         * const sym = Symbol('mySymbol')
+         * Symkeys.isSymkey(sym) // false; not in Symkey format
+         * Symkeys.hasData(sym) // false
+         * sym.data = { name: 'John', age: 30 } // will fail silently
+         * Symkeys.hasData(sym) // still false
+         *
+         * // Now let's create a Symkey with data
+         * const symWithData = Symkeys.create('mySymbolWithData',
+         *                                    { name: 'Jane', age: 25 })
+         * Symkeys.isSymkey(symWithData) // true
+         * Symkeys.hasData(symWithData) // true
+         * symWithData.data = { name: 'Jane', age: 26 } // will succeed
+         * Symkeys.getData(symWithData) // returns { name: 'Jane', age: 26 }
+         */
+        set data(value) {
+            if (symkeys_js_1.Symkeys.isSymkey(this) && symkeys_js_1.Symkeys.hasData(this)) {
+                Symbol.keys.setData(this, value);
+            }
+        },
+        /**
+         * Checks if the symbol might have embedded JSON data.
+         *
+         * This getter method checks if the symbol's description might contain
+         * JSON data and if the data property of the symbol is a function. If both
+         * conditions are met, it returns true, otherwise it returns false.
+         *
+         * @returns {boolean} - Returns true if the symbol might have embedded
+         * JSON, false otherwise.
+         *
+         * @example
+         * const sym = Symbol.for('fun {"name":"Brie"}')
+         * console.log(sym.mightHaveEmbeddedJSON) // Output: true
+         *
+         * @example
+         * const sym = Symbol('mySymbol')
+         * console.log(sym.mightHaveEmbeddedJSON) // Output: false
+         */
+        get mightHaveEmbeddedJSON() {
+            return mightContain(this.description) && typeof this.data === 'function';
+        },
+    }
+});
+//# sourceMappingURL=symbol.extensions.js.map

package/dist/cjs/symbol.extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol.extensions.js","sourceRoot":"","sources":["../../src/symbol.extensions.js"],"names":[],"mappings":";;;AAAA,+CAAwC;AAExC,qDAA8C;AAC9C,6DAAqD;AAErD,MAAM,EAAE,WAAW,EAAE,YAAY,EAAE,GAAG,mCAAc,CAAC,OAAO,CAAA;AAE5D;;;;;;;GAOG;AACU,QAAA,gBAAgB,GAAG,IAAI,iBAAK,CAAC,MAAM,EAAE;IAChD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,IAAI,EAAE,IAAI;QACjB,OAAO,IAAI,KAAK,SAAS;YACvB,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,IAAI,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/C,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACtB,CAAC;IAED;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK;QACZ,OAAO,KAAK,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC;IAC9C,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,KAAK;QAC1C,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;YAC5B,IAAI,gBAAgB,EAAE,CAAC;gBACrB,MAAM,IAAI,SAAS,CAAC,mDAAmD,CAAC,CAAA;YAC1E,CAAC;YACD,OAAO,KAAK,CAAA;QACd,CAAC;QAED,OAAO,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS,CAAA;IAC3C,CAAC;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,eAAe,CAAC,KAAK,EAAE,gBAAgB,GAAG,KAAK;QAC7C,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAA;IACtD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,IAAI,EAAE,IAAI,oBAAO,CAAC,MAAM,CAAC;CAC1B,CAAC,CAAC;AAEU,QAAA,yBAAyB,GAAG,IAAI,iBAAK,CAAC,MAAM,CAAC,SAAS,EAAE;IACnE,CAAC,iBAAK,CAAC,cAAc,CAAC,EAAE;QACtB;;;;;;;;;;;;;;;WAeG;QACH,IAAI,QAAQ;YACV,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;QACrB,CAAC;QAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAqCG;QACH,IAAI,IAAI;YACN,IAAI,MAAM,EAAE,IAAI,IAAI,oBAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3C,MAAM,YAAY,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;gBACtC,IAAI,YAAY,EAAE,CAAC;oBACjB,OAAO,YAAY,CAAA;gBACrB,CAAC;YACH,CAAC;YAED,OAAO,WAAW,CAAC,MAAM,CAAC,CAAA;QAC5B,CAAC;QAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAsCG;QACH,IAAI,IAAI,CAAC,KAAK;YACZ,IAAI,oBAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,oBAAO,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpD,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;YAClC,CAAC;QACH,CAAC;QAED;;;;;;;;;;;;;;;;;WAiBG;QACH,IAAI,qBAAqB;YACvB,OAAO,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,UAAU,CAAA;QAC1E,CAAC;KACF;CACF,CAAC,CAAA"}

package/dist/cjs/{weakrefextensions.js → weakref.extensions.js}

@@ -16,4 +16,4 @@ exports.WeakRefExtensions = new extension_1.Patch(WeakRef, {
             (value === null || value === undefined));
     },
 });
-//# sourceMappingURL=weakrefextensions.js.map
+//# sourceMappingURL=weakref.extensions.js.map

package/dist/cjs/weakref.extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"weakref.extensions.js","sourceRoot":"","sources":["../../src/weakref.extensions.js"],"names":[],"mappings":";;;AAAA,+CAAuC;AAE1B,QAAA,iBAAiB,GAAG,IAAI,iBAAK,CAAC,OAAO,EAAE;IAClD;;;;;;OAMG;IACH,gBAAgB,CAAC,KAAK;QACpB,OAAO,CAAC,CACN,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,SAAS,CAAC;YACjE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,CAAC;YACxD,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC,CACxC,CAAA;IACH,CAAC;CACF,CAAC,CAAA"}

package/dist/mjs/array.extensions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `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: Patch;
+/**
+ * `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: Patch;
+import { Patch } from '@nejs/extension';

package/dist/mjs/array.extensions.js

@@ -0,0 +1,300 @@
+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;
+}
+//# sourceMappingURL=array.extensions.js.map

package/dist/mjs/array.extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.extensions.js","sourceRoot":"","sources":["../../src/array.extensions.js"],"names":[],"mappings":"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"}

package/dist/mjs/big.int.extension.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `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: Patch;
+/**
+ * `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: Patch;
+import { Patch } from '@nejs/extension';