@nejs/basic-extensions 2.2.1 → 2.4.0

package/dist/mjs/stringextensions.js

@@ -1,4 +1,5 @@
 import { Patch } from '@nejs/extension';
+const parenthesisPair = ['(', ')'];
 /**
  * `StringExtensions` is a patch for the JavaScript built-in `String` class. It
  * adds utility methods to the `String` class without modifying the global namespace
@@ -21,5 +22,132 @@ export const StringExtensions = new Patch(String, {
         }
         return false;
     },
+    /**
+     * A getter property that returns a pair of parentheses as an array.
+     * This property can be used when operations require a clear distinction
+     * between the opening and closing parentheses, such as parsing or
+     * matching balanced expressions in strings.
+     *
+     * @returns {[string, string]} An array containing a pair of strings: the
+     * opening parenthesis '(' as the first element, and the closing parenthesis
+     * ')' as the second element.
+     */
+    get parenthesisPair() {
+        return ['(', ')'];
+    },
+    /**
+     * A getter property that returns a pair of square brackets as an array.
+     * This property is particularly useful for operations that require a clear
+     * distinction between the opening and closing square brackets, such as
+     * parsing arrays in strings or matching balanced expressions within
+     * square brackets.
+     *
+     * @returns {[string, string]} An array containing a pair of strings: the
+     * opening square bracket '[' as the first element, and the closing square
+     * bracket ']' as the second element.
+     */
+    get squareBracketsPair() {
+        return ['[', ']'];
+    },
+    /**
+     * A getter property that returns a pair of curly brackets as an array.
+     * This property is particularly useful for operations that require a clear
+     * distinction between the opening and closing curly brackets, such as
+     * parsing objects in strings or matching balanced expressions within
+     * curly brackets. The returned array consists of the opening curly bracket
+     * '{' as the first element, and the closing curly bracket '}' as the
+     * second element.
+     *
+     * @returns {[string, string]} An array containing a pair of strings: the
+     * opening curly bracket '{' as the first element, and the closing curly
+     * bracket '}' as the second element.
+     */
+    get curlyBracketsPair() {
+        return ['{', '}'];
+    },
+});
+/**
+ * `StringPrototypeExtensions` provides a set of utility methods that are
+ * added to the `String` prototype. This allows all string instances to
+ * access new functionality directly, enhancing their capabilities beyond
+ * the standard `String` class methods. These extensions are applied using
+ * the `Patch` class from '@nejs/extension', ensuring that they do not
+ * interfere with the global namespace or existing properties.
+ *
+ * The extensions include methods for extracting substrings based on
+ * specific tokens, checking the presence of certain patterns, and more,
+ * making string manipulation tasks more convenient and expressive.
+ */
+export const StringPrototypeExtensions = new Patch(String.prototype, {
+    /**
+     * Extracts a substring from the current string, starting at a given offset
+     * and bounded by specified opening and closing tokens. This method is
+     * particularly useful for parsing nested structures or quoted strings,
+     * where the level of nesting or the presence of escape characters must
+     * be considered.
+     *
+     * @param {number} offset The position in the string from which to start the
+     * search for the substring.
+     * @param {[string, string]} tokens An array containing two strings: the
+     * opening and closing tokens that define the boundaries of the substring
+     * to be extracted.
+     * @returns {Object} An object with two properties: `extracted`, the
+     * extracted substring, and `newOffset`, the position in the original
+     * string immediately after the end of the extracted substring. If no
+     * substring is found, `extracted` is `null` and `newOffset` is the same
+     * as the input offset.
+     */
+    extractSubstring(offset = 0, tokens = parenthesisPair) {
+        let [openToken, closeToken] = tokens;
+        let depth = 0;
+        let start = -1;
+        let end = -1;
+        let leadingToken = '';
+        let firstToken = 0;
+        for (let i = offset; i < this.length; i++) {
+            const char = this[i];
+            if (char === openToken) {
+                depth++;
+                if (start === -1)
+                    start = i;
+            }
+            else if (char === closeToken) {
+                depth--;
+                if (depth === 0) {
+                    end = i;
+                    break;
+                }
+            }
+        }
+        let lRange = [
+            Math.max(0, start - 100),
+            start
+        ];
+        let leading = [...this.substring(lRange[0], lRange[1])].reverse().join('');
+        let reversedLeadingToken;
+        try {
+            reversedLeadingToken = /([^ \,\"\'\`]+)/.exec(leading)[1] ?? '';
+            leadingToken = [...reversedLeadingToken].reverse().join('');
+        }
+        catch (ignored) { }
+        if (start !== -1 && end !== -1) {
+            const sliceRange = [start, end + 1];
+            const extracted = this.slice(sliceRange[0], sliceRange[1]);
+            return {
+                extracted,
+                range: [start, end],
+                newOffset: end + 1,
+                leadingToken,
+            };
+        }
+        else {
+            return {
+                extracted: null,
+                range: [start, end],
+                newOffset: offset,
+                leadingToken,
+            };
+        }
+    },
 });
 //# sourceMappingURL=stringextensions.js.map

package/dist/mjs/stringextensions.js.map

@@ -1 +1 @@
-{"version":3,"file":"stringextensions.js","sourceRoot":"","sources":["../../src/stringextensions.js"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAExC;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,KAAK,CAAC,MAAM,EAAE;IAChD;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK;QACZ,IAAI,KAAK,IAAI,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,YAAY,MAAM,CAAC,EAAE,CAAC;YACpE,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,CAAA;QACzB,CAAC;QACD,OAAO,KAAK,CAAA;IACd,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"stringextensions.js","sourceRoot":"","sources":["../../src/stringextensions.js"],"names":[],"mappings":"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"}