@nejs/basic-extensions 2.7.0 → 2.8.0

package/dist/cjs/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/cjs/array.extensions.js

@@ -0,0 +1,303 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ArrayPrototypeExtensions = exports.ArrayExtensions = void 0;
+const extension_1 = require("@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
+ */
+exports.ArrayExtensions = new extension_1.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 } = exports.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
+ */
+exports.ArrayPrototypeExtensions = new extension_1.Patch(Array.prototype, {
+    [extension_1.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/cjs/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/cjs/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';

package/dist/cjs/big.int.extension.js

@@ -0,0 +1,164 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BigIntPrototypeExtensions = exports.BigIntExtensions = void 0;
+const extension_1 = require("@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
+ */
+exports.BigIntExtensions = new extension_1.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 } = exports.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
+ */
+exports.BigIntPrototypeExtensions = new extension_1.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;
+}
+//# sourceMappingURL=big.int.extension.js.map

package/dist/cjs/big.int.extension.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"big.int.extension.js","sourceRoot":"","sources":["../../src/big.int.extension.js"],"names":[],"mappings":";;;AAAA,+CAAuC;AAEvC;;;;;;;;;;;;;GAaG;AACU,QAAA,gBAAgB,GAAG,IAAI,iBAAK,CAAC,MAAM,EAAE;IAChD;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,KAAK;QACZ,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,YAAY,MAAM,CAAA;IAC7D,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,EAAE,SAAS;QAClC,OAAO,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,CAAA;IAC/D,CAAC;CACF,CAAC,CAAA;AAEF,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,wBAAgB,CAAC,OAAO,CAAA;AAE7E;;;;;;;;;;;;;GAaG;AACU,QAAA,yBAAyB,GAAG,IAAI,iBAAK,CAAC,MAAM,CAAC,SAAS,EAAE;IACnE;;;;;;;;;;;;;;;OAeG;IACH,IAAI,QAAQ;QACV,OAAO,MAAM,CAAC,IAAI,CAAC,CAAA;IACrB,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,IAAI,QAAQ;QACV,OAAO,SAAS,CAAC,IAAI,CAAC,CAAA;IACxB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS;QAC3B,OAAO,SAAS,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,CAAC,CAAA;IAC9C,CAAC;CACF,CAAC,CAAA;AAEF,0EAA0E;AAC1E,2EAA2E;AAC3E,+BAA+B;AAC/B,SAAS,UAAU,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE;IAC5B,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,IAAI,KAAK,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAAC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACnE,IAAI,KAAK,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAAC,OAAO,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAA;QACrE,CAAC;QAAC,OAAO,EAAE,IAAI,KAAK,CAAC;IACvB,CAAC;IAAC,OAAO,EAAE,CAAA;AACb,CAAC"}