@nejs/basic-extensions 2.7.0 → 2.8.0

package/dist/cjs/regular.expression.extensions.js

@@ -0,0 +1,423 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RegExpExtensions = void 0;
+const extension_1 = require("@nejs/extension");
+exports.RegExpExtensions = new extension_1.Patch(RegExp, {
+    [extension_1.Patch.kMutablyHidden]: {
+        /**
+         * Generates a regular expression pattern that matches any character.
+         *
+         * This method creates a regular expression pattern that matches any
+         * character. The pattern can be configured to be greedy or non-greedy,
+         * and to include or exclude newline characters.
+         *
+         * @param {boolean} [greedy=false] - If true, the pattern will be greedy,
+         * meaning it will match as many characters as possible. If false, the
+         * pattern will be non-greedy, meaning it will match as few characters
+         * as possible.
+         * @param {boolean} [includeNewlines=false] - If true, the pattern will
+         * include newline characters ('\n' and '\r'). If false, newline
+         * characters will be excluded from the pattern.
+         * @returns {string} - The generated regular expression pattern.
+         *
+         * @example
+         * // Generate a non-greedy pattern that excludes newlines
+         * console.log(anything())  // Output: '[.]*?'
+         *
+         * @example
+         * // Generate a greedy pattern that includes newlines
+         * console.log(anything(true, true))  // Output: '[.\\n\\r]*'
+         */
+        anything(greedy = false, includeNewlines = false) {
+            return `[.${includeNewlines ? '\\n\\r' : ''}]*${greedy ? '' : '?'}`;
+        },
+        /**
+         * Creates a non-capturing group in a regular expression.
+         *
+         * This method wraps the provided string in a non-capturing group,
+         * which is denoted by the syntax `(?:...)` in a regular expression.
+         * Non-capturing groups match the pattern inside the group but do not
+         * capture the matched content for later use.
+         *
+         * @param {string} string - The string to be wrapped in a non-capturing group.
+         * @returns {string} - The string wrapped in a non-capturing group.
+         *
+         * @example
+         * // Suppose we have a string 'abc'
+         * const str = 'abc'
+         *
+         * // Using `nonCaptureGroup`
+         * console.log(nonCaptureGroup(str))  // Output: '(?:abc)'
+         */
+        nonCaptureGroup(string) {
+            return `(?:${string})`;
+        },
+        /**
+         * Creates a capturing group in a regular expression.
+         *
+         * This method wraps the provided string in a capturing group,
+         * which is denoted by the syntax `(...)` in a regular expression.
+         * Capturing groups match the pattern inside the group and capture
+         * the matched content for later use.
+         *
+         * @param {string} string - The string to be wrapped in a capturing group.
+         * @returns {string} - The string wrapped in a capturing group.
+         *
+         * @example
+         * // Suppose we have a string 'abc'
+         * const str = 'abc'
+         *
+         * // Using `captureGroup`
+         * console.log(captureGroup(str))  // Output: '(abc)'
+         */
+        captureGroup(string) {
+            return `(${string})`;
+        },
+        /**
+         * Creates a regular expression pattern that matches any one of the
+         * provided strings.
+         *
+         * This method takes any number of strings as arguments, and returns a
+         * string that represents a regular expression pattern. The pattern
+         * matches any one of the provided strings. The strings are joined
+         * together with the '|' character, which represents the OR operator
+         * in regular expressions.
+         *
+         * @param {...string} strings - The strings to be included in the pattern.
+         * @returns {string} - A string representing a regular expression pattern
+         * that matches any one of the provided strings.
+         *
+         * @example
+         * // Suppose we have strings 'abc', 'def', and 'ghi'
+         * const str1 = 'abc'
+         * const str2 = 'def'
+         * const str3 = 'ghi'
+         *
+         * // Using `oneOf`
+         * console.log(oneOf(str1, str2, str3))  // Output: 'abc|def|ghi'
+         */
+        oneOf(...strings) {
+            return strings.join('|');
+        },
+        /**
+         * Creates a regular expression pattern that matches zero or more
+         * occurrences of the provided string.
+         *
+         * This method wraps the provided string in a non-capturing group,
+         * which is denoted by the syntax `(?:...)` in a regular expression,
+         * and appends the `*` character, which represents zero or more
+         * occurrences in regular expressions.
+         *
+         * @param {string} string - The string to be matched zero or more times.
+         * @returns {string} - A string representing a regular expression pattern
+         * that matches zero or more occurrences of the provided string.
+         *
+         * @example
+         * // Suppose we have a string 'abc'
+         * const str = 'abc'
+         *
+         * // Using `zeroOrMore`
+         * console.log(zeroOrMore(str))  // Output: '(?:abc)*'
+         */
+        zeroOrMore(string) {
+            return `(?:${string})*`;
+        },
+        /**
+         * Creates a regular expression pattern that matches zero or one
+         * occurrence of the provided string.
+         *
+         * This method wraps the provided string in a non-capturing group,
+         * which is denoted by the syntax `(?:...)` in a regular expression,
+         * and appends the `?` character, which represents zero or one
+         * occurrence in regular expressions.
+         *
+         * @param {string} string - The string to be matched zero or one time.
+         * @returns {string} - A string representing a regular expression pattern
+         * that matches zero or one occurrence of the provided string.
+         *
+         * @example
+         * // Suppose we have a string 'abc'
+         * const str = 'abc'
+         *
+         * // Using `zeroOrOne`
+         * console.log(zeroOrOne(str))  // Output: '(?:abc)?'
+         */
+        zeroOrOne(string) {
+            return `(?:${string})?`;
+        },
+        /**
+         * Escapes special characters in a string for use in a regular expression.
+         *
+         * This method checks if the `RegExp.escape` method is available. If it is,
+         * it uses that method to escape the string. If it's not, it uses a polyfill
+         * method to escape the string.
+         *
+         * The polyfill method replaces all special characters in the string with
+         * their escaped equivalents. The special characters are defined by the
+         * regular expression `/[-[\]{}()*+?.,\\^$|#\s]/g`.
+         *
+         * @param {string} string - The string to be escaped.
+         * @returns {string} - The escaped string.
+         *
+         * @example
+         * // Suppose we have a string with special characters
+         * const str = 'Hello, [World]!'
+         *
+         * // Using `escape` or `escapePolyfill`
+         * console.log(RegExp[RegExp.escape ? 'escapePolyfill' : 'escape'](str))
+         * // Output: 'Hello\\, \\[World\\]\\!'
+         */
+        escape(string) {
+            return RegExpEscape(string);
+        },
+        /**
+         * Getter method that returns a string 'null'.
+         *
+         * This method is used when you need a string representation of null
+         * in your regular expressions. It simply returns the string 'null'.
+         *
+         * @returns {string} - A string 'null'.
+         *
+         * @example
+         * // Using `null`
+         * console.log(this.null)  // Output: 'null'
+         */
+        get null() {
+            return 'null';
+        },
+        /**
+         * Getter method that returns a regular expression string for boolean
+         * values.
+         *
+         * This method uses the `oneOf` method to create a regular expression
+         * string that matches either 'true' or 'false'. This is useful when you
+         * need to match boolean values in a string using a regular expression.
+         *
+         * @returns {string} - A regular expression string that matches 'true'
+         * or 'false'.
+         *
+         * @example
+         * // Using `bool`
+         * const boolRegex = new RegExp(this.bool)
+         * console.log(boolRegex.test('true'))  // Output: true
+         * console.log(boolRegex.test('false')) // Output: true
+         * console.log(boolRegex.test('maybe')) // Output: false
+         */
+        get bool() {
+            return this.oneOf('true', 'false');
+        },
+        /**
+         * Generates a regular expression string that matches the symbols of
+         * specified currencies.
+         *
+         * This method uses the Intl API to get the symbols of the specified
+         * currencies and constructs a regular expression string that matches
+         * these symbols. If no specific currencies are provided, it defaults
+         * to all known currencies. If a single currency is provided as a
+         * string, it is converted to an array. If the symbols array is empty
+         * after filtering out unknown currencies, it defaults back to all
+         * known currencies.
+         *
+         * @param {Array|string} [symbols=[['*'], ['USD','GBP']][0]] - The
+         * currencies to include in the regular expression. Can be an array
+         * of currency codes or a single currency code as a string. Defaults
+         * to all known currencies.
+         * @param {string} [locale='en-US'] - The locale to use when getting
+         * the currency symbols. Defaults to 'en-US'.
+         * @returns {string} - A regular expression string that matches the
+         * symbols of the specified currencies.
+         *
+         * @example
+         * // Using `currencySymbols` with default parameters
+         * console.log(this.currencySymbols())
+         * // Output: A regular expression string that matches all known
+         * // currency symbols
+         *
+         * @example
+         * // Using `currencySymbols` with specific currencies
+         * console.log(this.currencySymbols(['USD', 'EUR']))
+         * // Output: A regular expression string that matches the symbols
+         * // of USD and EUR
+         */
+        currencySymbols(symbols = [['*'], ['USD', 'GBP']][0], locale = 'en-US') {
+            const known = Intl.supportedValuesOf('currency');
+            const has = code => !!~known.indexOf(code);
+            if (typeof symbols === 'string' && has(symbols)) {
+                symbols = [symbols];
+            }
+            if (!Array.isArray(symbols)) {
+                symbols = known;
+            }
+            symbols = symbols.filter(symbol => has(symbol));
+            if (!symbols.length) {
+                symbols = known;
+            }
+            const opts = (currency) => ({ style: 'currency', currency });
+            const fmt = (place, currency) => Intl.NumberFormat(place, opts(currency));
+            const codes = (((symbols.length === 1 && symbols[0] === '*') ? known : symbols)
+                .filter(code => has(code))
+                .map(currency => {
+                const symbol = fmt(locale, currency).formatToParts()?.[0].value;
+                return symbol && `(?:${RegExp.escape(symbol)})`;
+            })
+                .join('|'));
+            return codes;
+        },
+        /**
+         * Getter method that returns a regular expression string for numbers.
+         *
+         * This method returns a regular expression string that matches both
+         * integer and floating point numbers. The returned regular expression
+         * string is '\\d+\\.?\\d*', which matches one or more digits followed
+         * by an optional decimal point and zero or more digits.
+         *
+         * @returns {string} - A regular expression string that matches numbers.
+         *
+         * @example
+         * // Using `number`
+         * const numberRegex = new RegExp(this.number)
+         * console.log(numberRegex.test('123'))    // Output: true
+         * console.log(numberRegex.test('123.45')) // Output: true
+         * console.log(numberRegex.test('abc'))    // Output: false
+         */
+        get number() {
+            const instance = Object(`\\d+\\.?\\d*`);
+            const self = this;
+            Object.defineProperties(instance, {
+                // alias for .float
+                any: { get() { return String(instance); } },
+                /**
+                 * Getter method that returns a regular expression string for floating
+                 * point numbers.
+                 *
+                 * This method returns a regular expression string that matches floating
+                 * point numbers. It leverages the 'number' getter method which matches
+                 * both integer and floating point numbers. The returned regular expression
+                 * string is '\\d+\\.?\\d*', which matches one or more digits followed by
+                 * an optional decimal point and zero or more digits.
+                 *
+                 * @returns {string} - A regular expression string that matches floating
+                 * point numbers.
+                 *
+                 * @example
+                 * // Using `float`
+                 * const floatRegex = new RegExp(this.float)
+                 * console.log(floatRegex.test('123.45')) // Output: true
+                 * console.log(floatRegex.test('123'))    // Output: false
+                 * console.log(floatRegex.test('abc'))    // Output: false
+                 */
+                float: { get() { return String(instance); } },
+                // any known locale currency symbol + .float
+                money: { get() { return `(?:${self.currencySymbols()})?${this.float}`; } },
+                /**
+                 * Getter method that returns a regular expression string for integers.
+                 *
+                 * This method returns a regular expression string that matches integer
+                 * numbers. The returned regular expression string is '\\d+', which matches
+                 * one or more digits.
+                 *
+                 * @returns {string} - A regular expression string that matches integers.
+                 *
+                 * @example
+                 * // Using `integer`
+                 * const integerRegex = new RegExp(this.integer)
+                 * console.log(integerRegex.test('123'))    // Output: true
+                 * console.log(integerRegex.test('123.45')) // Output: false
+                 * console.log(integerRegex.test('abc'))    // Output: false
+                 */
+                integer: { get() { return `\\d+`; } },
+                /**
+                 * Getter method that returns a regular expression string for pretty
+                 * numbers.
+                 *
+                 * This method returns a regular expression string that matches numbers
+                 * with commas or spaces for thousands separators. The returned regular
+                 * expression string is '[\\d\\$]+\\.?[\\d,\\$]*', which matches one or
+                 * more digits or dollar signs, followed by an optional decimal point,
+                 * and zero or more digits, commas, or dollar signs.
+                 *
+                 * @returns {string} - A regular expression string that matches pretty
+                 * numbers.
+                 *
+                 * @example
+                 * // Using `pretty`
+                 * const prettyRegex = new RegExp(this.pretty)
+                 * console.log(prettyRegex.test('1,234.56')) // Output: true
+                 * console.log(prettyRegex.test('1234.56'))  // Output: true
+                 * console.log(prettyRegex.test('1 234.56')) // Output: true
+                 * console.log(prettyRegex.test('abc'))      // Output: false
+                 */
+                pretty: {
+                    value(locale = 'en-US') {
+                        const symbols = self.zeroOrMore(self.currencySymbols(['*'], locale));
+                        return `${symbols}[\\d,]+\\.?[\\d]*`;
+                    }
+                },
+                /**
+                 * Getter method that returns a regular expression string for JavaScript
+                 * literals.
+                 *
+                 * This method returns a regular expression string that matches JavaScript
+                 * literals. The returned regular expression string is '[\\d_]+', which
+                 * matches one or more digits or underscores.
+                 *
+                 * @returns {string} - A regular expression string that matches JavaScript
+                 * literals.
+                 *
+                 * @example
+                 * // Using `jsLiteral`
+                 * const jsLiteralRegex = new RegExp(this.jsLiteral)
+                 * console.log(jsLiteralRegex.test('123_456')) // Output: true
+                 * console.log(jsLiteralRegex.test('abc'))     // Output: false
+                 */
+                jsLiteral: { get() { return `[\\d_]+`; } }
+            });
+            return instance;
+        },
+        /**
+         * Getter method that returns a regular expression string for integers.
+         *
+         * This method returns a regular expression string that matches integer
+         * numbers. The returned regular expression string is '\\d+', which matches
+         * one or more digits.
+         *
+         * @returns {string} - A regular expression string that matches integers.
+         *
+         * @example
+         * // Using `integer`
+         * const integerRegex = new RegExp(this.integer)
+         * console.log(integerRegex.test('123'))    // Output: true
+         * console.log(integerRegex.test('123.45')) // Output: false
+         * console.log(integerRegex.test('abc'))    // Output: false
+         */
+        get integer() {
+            return `\\d+`;
+        },
+        get string() {
+            return {
+                get doubleQuoted() {
+                    return '"[^"\\\\]*(?:\\\\.[^"\\\\]*)*"';
+                },
+                get singleQuoted() {
+                    return "'[^'\\\\]*(?:\\\\.[^'\\\\]*)*'";
+                }
+            };
+        },
+        get whitespace() {
+            return `\\s*`;
+        },
+        get comma() {
+            return `,${this.whitespace}`;
+        },
+    }
+}, {
+    conditions: {
+        ['escape']() { return !Reflect.has(RegExp, 'escape'); },
+    }
+});
+// Simple variant that does not require external dependencies; may not cover
+// all known use cases.
+function RegExpEscape(string) {
+    return string.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g, "\\$&");
+}
+//# sourceMappingURL=regular.expression.extensions.js.map

package/dist/cjs/regular.expression.extensions.js.map

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

package/dist/cjs/set.extensions.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `SetExtensions` is a constant that applies a patch to the global
+ * `Set` constructor. This patch extends the `Set` with additional
+ * methods and properties, enhancing its functionality.
+ *
+ * The `Patch` function takes two arguments: the target object to be patched
+ * (in this case, `Set`), and an object containing the methods and
+ * properties to be added to the target object.
+ *
+ * @example
+ * // Using a method added by SetExtensions
+ * const set = new Set();
+ * console.log(Set.isSet(set)); // Output: true
+ *
+ * @const
+ * @type {Patch}
+ * @memberof module:set.extensions
+ */
+export const SetExtensions: Patch;
+/**
+ * `SetPrototypeExtensions` is a constant that applies a patch to the
+ * prototype of the built-in JavaScript `Set` object. This patch extends the
+ * `Set` prototype with additional methods and properties, enhancing its
+ * functionality.
+ *
+ * The `Patch` function takes two arguments: the target object to be patched
+ * (in this case, `Set.prototype`), and an object containing the methods and
+ * properties to be added to the target object.
+ *
+ * @example
+ * // Using a method added by SetPrototypeExtensions
+ * const mySet = new Set();
+ * mySet.myNewMethod(); // Calls the new method added by the patch
+ *
+ * @const
+ * @type {Patch}
+ * @memberof module:set.extensions
+ */
+export const SetPrototypeExtensions: Patch;
+import { Patch } from '@nejs/extension';

package/dist/cjs/{setextensions.js → set.extensions.js}

@@ -1,7 +1,95 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SetPrototypeExtensions = void 0;
+exports.SetPrototypeExtensions = exports.SetExtensions = void 0;
 const extension_1 = require("@nejs/extension");
+/**
+ * `SetExtensions` is a constant that applies a patch to the global
+ * `Set` constructor. This patch extends the `Set` with additional
+ * methods and properties, enhancing its functionality.
+ *
+ * The `Patch` function takes two arguments: the target object to be patched
+ * (in this case, `Set`), and an object containing the methods and
+ * properties to be added to the target object.
+ *
+ * @example
+ * // Using a method added by SetExtensions
+ * const set = new Set();
+ * console.log(Set.isSet(set)); // Output: true
+ *
+ * @const
+ * @type {Patch}
+ * @memberof module:set.extensions
+ */
+exports.SetExtensions = new extension_1.Patch(Set, {
+    [extension_1.Patch.kMutablyHidden]: {
+        /**
+         * Determines if the supplied `value` is a `Set` object. This check
+         * is performed by first looking for the `Symbol.toStringTag` on the
+         * `value` and checking to see if it is equal to the string "Set".
+         * If that check fails, `instanceof` is used as a fallback to check
+         * the prototype chain.
+         *
+         * @param {any} value the value that needs to be checked to determine
+         * if it is a `Set` object or not
+         * @returns {boolean} `true` if the supplied `value` is a `Set`
+         * object, `false` otherwise
+         *
+         * @example
+         * const set = new Set()
+         * isSet(set) // true
+         * isSet(new Map()) // false
+         * isSet([]) // false
+         * isSet({}) // false
+         */
+        isSet(value) {
+            return value?.[Symbol.toStringTag] === Set.name || value instanceof Set;
+        },
+        /**
+         * Conditionally returns a value based on whether the supplied
+         * `value` is a `Set` object or not. If the `value` is a `Set`
+         * object, the `thenValue` will be returned. If it is not a `Set`
+         * object, the `elseValue` will be returned instead.
+         *
+         * @param {any} value the value to check to determine if it is a
+         * `Set` object
+         * @param {any} thenValue the value to return if the supplied
+         * `value` is a `Set` object
+         * @param {any} elseValue the value to return if the supplied
+         * `value` is not a `Set` object
+         * @returns {any} either the `thenValue` or `elseValue` depending
+         * on if the supplied `value` is a `Set` object
+         *
+         * @example
+         * const set = new Set()
+         * const map = new Map()
+         * ifSet(set, 'is a set', 'not a set') // 'is a set'
+         * ifSet(map, 'is a set', 'not a set') // 'not a set'
+         */
+        ifSet(value, thenValue, elseValue) {
+            return isThenElse(this.isSet(value), thenValue, elseValue);
+        },
+    }
+});
+const { isSet: pIsSet } = exports.SetExtensions.patches;
+/**
+ * `SetPrototypeExtensions` is a constant that applies a patch to the
+ * prototype of the built-in JavaScript `Set` object. This patch extends the
+ * `Set` prototype with additional methods and properties, enhancing its
+ * functionality.
+ *
+ * The `Patch` function takes two arguments: the target object to be patched
+ * (in this case, `Set.prototype`), and an object containing the methods and
+ * properties to be added to the target object.
+ *
+ * @example
+ * // Using a method added by SetPrototypeExtensions
+ * const mySet = new Set();
+ * mySet.myNewMethod(); // Calls the new method added by the patch
+ *
+ * @const
+ * @type {Patch}
+ * @memberof module:set.extensions
+ */
 exports.SetPrototypeExtensions = new extension_1.Patch(Set.prototype, {
     [extension_1.Patch.kMutablyHidden]: {
         /**
@@ -120,6 +208,52 @@ exports.SetPrototypeExtensions = new extension_1.Patch(Set.prototype, {
             }
             return undefined;
         },
+        /**
+         * Determines if the current object is a `Set` object.
+         *
+         * This is a getter that uses the `isSet` function from the
+         * `SetExtensions` patch to check if the current object (`this`) is
+         * a `Set` object.
+         *
+         * @type {boolean}
+         * @readonly
+         *
+         * @example
+        * const set = new Set()
+        * console.log(set.isSet) // Output: true
+        *
+        * const notSet = {}
+        * console.log(notSet.isSet) // Output: false
+        */
+        get isSet() {
+            return pIsSet(this);
+        },
+        /**
+         * Checks if the current object is a Set and returns the
+         * corresponding value based on the result.
+         *
+         * This method uses the `isThenElse` function from the
+         * `SetExtensions` patch to determine if the current object
+         * (`this`) is a Set. If it is a Set, the `thenValue` is returned.
+         * Otherwise, the `elseValue` is returned.
+         *
+         * @param {any} thenValue - The value to return if the current object
+         * is a Set.
+         * @param {any} elseValue - The value to return if the current object
+         * is not a Set.
+         * @returns {any} The `thenValue` if the current object is a Set, or
+         * the `elseValue` if it is not a Set.
+         *
+         * @example
+         * const set = new Set([1, 2, 3])
+         * console.log(set.ifSet('Is a Set', 'Not a Set')) // 'Is a Set'
+         *
+         * const notSet = {}
+         * console.log(notSet.ifSet('Is a Set', 'Not a Set')) // 'Not a Set'
+         */
+        ifSet(thenValue, elseValue) {
+            return isThenElse(pIsSet(this), thenValue, elseValue);
+        },
         /**
          * A getter property that returns the number of elements in the set.
          * This is an alias for the `size` property of the set.
@@ -203,4 +337,18 @@ exports.SetPrototypeExtensions = new extension_1.Patch(Set.prototype, {
         },
     },
 });
-//# sourceMappingURL=setextensions.js.map
+// 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=set.extensions.js.map

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

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