@nejs/basic-extensions 2.2.1 → 2.3.0

package/package.json

@@ -58,9 +58,9 @@
     "test": "jest"
   },
   "type": "module",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "dependencies": {
     "@nejs/extension": "^2.7.1"
   },
-  "browser": "dist/@nejs/basic-extensions.bundle.2.2.0.js"
+  "browser": "dist/@nejs/basic-extensions.bundle.2.2.1.js"
 }

package/src/index.js

@@ -3,7 +3,7 @@ import { ObjectExtensions, ObjectPrototypeExtensions } from './objectextensions.
 import { MapPrototypeExtensions } from './mapextensions.js'
 import { SetPrototypeExtensions } from './setextensions.js'
 import { ReflectExtensions } from './reflectextensions.js'
-import { StringExtensions } from './stringextensions.js'
+import { StringExtensions, StringPrototypeExtensions } from './stringextensions.js'
 import { SymbolExtensions } from './symbolextensions.js'
 import { ArrayPrototypeExtensions } from './arrayextensions.js'
 import { DescriptorExtensions, Descriptor } from './newClasses/descriptor.js'
@@ -32,6 +32,7 @@ const StaticPatches = [
 
 const InstancePatches = [
   [Object.prototype, ObjectPrototypeExtensions, Object.name],
+  [String.prototype, StringPrototypeExtensions, String.name],
   [Function.prototype, FunctionPrototypeExtensions, Function.name],
   [Array.prototype, ArrayPrototypeExtensions, Array.name],
   [Map.prototype, MapPrototypeExtensions, Map.name],
@@ -137,9 +138,9 @@ export const all = (() => {
   const instancePatchReducer = (accumulator, [_, patch, ownerName]) => {
     if (!accumulator?.[ownerName])
       accumulator[ownerName] = {};
-    
+
     if (!accumulator[ownerName]?.prototype)
-      accumulator[ownerName].prototype = {};    
+      accumulator[ownerName].prototype = {};
 
       [...patch].reduce(entriesReducer, accumulator[ownerName].prototype)
     return accumulator
@@ -151,13 +152,13 @@ export const all = (() => {
     .flatMap(extension => [...extension])
     .reduce(entriesReducer, dest.classes)
   )
-  
+
   for (const [key, entry] of GlobalFunctionsAndProps) {
     const descriptor = new Descriptor(entry.descriptor, entry.owner)
     Object.defineProperty(dest.global, key, descriptor.toObject(true))
   }
 
-  return dest  
+  return dest
 })()
 
 const results = {

package/src/stringextensions.js

@@ -1,5 +1,7 @@
 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
@@ -22,4 +24,141 @@ 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,
+      };
+    }
+  },
+})

package/tests/arrayextensions.test.js

@@ -0,0 +1,54 @@
+const { Patches } = require('../dist/cjs/index.js')
+const ArrayPrototypeExtensions = Patches.get(Array.prototype)
+
+ArrayPrototypeExtensions.apply();
+
+describe('ArrayPrototypeExtensions', () => {
+  describe('contains method', () => {
+    it('should return true if the array contains the specified element', () => {
+      const arr = [1, 2, 3];
+      expect(arr.contains(2)).toBeTruthy();
+    });
+
+    it('should return false if the array does not contain the specified element', () => {
+      const arr = [1, 2, 3];
+      expect(arr.contains(4)).toBeFalsy();
+    });
+  });
+
+  describe('findEntry method', () => {
+    it('should return the first matching [index, value] entry', () => {
+      const arr = ['a', 'b', 'c'];
+      expect(arr.findEntry(x => x === 'b')).toEqual([1, 'b']);
+    });
+
+    it('should return undefined if no match is found', () => {
+      const arr = ['a', 'b', 'c'];
+      expect(arr.findEntry(x => x === 'd')).toBeUndefined();
+    });
+  });
+
+  describe('first getter', () => {
+    it('should return the first element of the array', () => {
+      const arr = [1, 2, 3];
+      expect(arr.first).toBe(1);
+    });
+
+    it('should return undefined if the array is empty', () => {
+      const arr = [];
+      expect(arr.first).toBeUndefined();
+    });
+  });
+
+  describe('last getter', () => {
+    it('should return the last element of the array', () => {
+      const arr = [1, 2, 3];
+      expect(arr.last).toBe(3);
+    });
+
+    it('should return undefined if the array is empty', () => {
+      const arr = [];
+      expect(arr.last).toBeUndefined();
+    });
+  });
+});

package/tests/stringextensions.test.js

@@ -0,0 +1,60 @@
+const { Patches } = require('../dist/cjs/index.js')
+const StringExtensions = Patches.get(String)
+const StringPrototypeExtensions = Patches.get(String.prototype)
+
+describe('StringExtensions', () => {
+  beforeAll(() => {
+    // Apply the StringExtensions patch
+    StringExtensions.apply();
+  });
+
+  test('isString should correctly identify strings', () => {
+    expect(String.isString('hello')).toBe(true);
+    expect(String.isString(new String('hello'))).toBe(true);
+    expect(String.isString(123)).toBe(false);
+    expect(String.isString(null)).toBe(false);
+    expect(String.isString(undefined)).toBe(false);
+    expect(String.isString({})).toBe(false);
+  });
+
+  test('parenthesisPair should return correct pair', () => {
+    expect(String.parenthesisPair).toEqual(['(', ')']);
+  });
+
+  test('squareBracketsPair should return correct pair', () => {
+    expect(String.squareBracketsPair).toEqual(['[', ']']);
+  });
+
+  test('curlyBracketsPair should return correct pair', () => {
+    expect(String.curlyBracketsPair).toEqual(['{', '}']);
+  });
+});
+
+describe('StringPrototypeExtensions', () => {
+  beforeAll(() => {
+    // Apply the StringPrototypeExtensions patch
+    StringPrototypeExtensions.apply();
+  });
+
+  test('extractSubstring should correctly extract substrings', () => {
+    const testString = "This is a test (with a substring) and some more text.";
+    const result = testString.extractSubstring(0, ['(', ')']);
+    expect(result).toEqual({
+      extracted: "(with a substring)",
+      range: [15, 32],
+      newOffset: 33,
+      leadingToken: 'test',
+    });
+  });
+
+  test('extractSubstring with no matching tokens should return null', () => {
+    const testString = "No parentheses here.";
+    const result = testString.extractSubstring();
+    expect(result).toEqual({
+      extracted: null,
+      range: [-1, -1],
+      newOffset: 0,
+      leadingToken: '',
+    });
+  });
+});