@nejs/basic-extensions 2.2.1 → 2.4.0

package/package.json

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

package/repl.bootstrap.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node --no-warnings --no-deprecations
+
+// Import everything for playtesting.
+(await import('./dist/mjs/index.js')).Controls.enableAll();
+
+const nejsExtension = await import('@nejs/extension');
+
+const repl = await import('node:repl');
+const fs = await import('node:fs');
+const project = JSON.parse(String(fs.readFileSync('./package.json')));
+
+const options = {
+  useGlobal: true,
+  prompt: '\x1b[32mλ\x1b[1;39m\x1b[22m '
+};
+
+let allowInvocation = true;
+
+Object.assign(global, { Patch: nejsExtension.Patch, Extension: nejsExtension.Extension });
+global.replServer = new repl.REPLServer(options);
+
+function about() {
+  console.log(`\x1b[32m${project.name}\x1b[39m v\x1b[1m${project.version}\x1b[22m`);
+  console.log(`\x1b[3m${project.description}\x1b[23m`);
+  console.log(`Written by \x1b[34m${project.author ?? 'Jane Doe'}\x1b[39m.\n`);
+  this?.displayPrompt() ?? replServer.displayPrompt();
+}
+
+const clear = () => {
+  if (allowInvocation) {
+    process.stdout.write('\x1b[0;0H\x1b[J');
+    return about();
+  }
+}
+
+clear();
+
+replServer.defineCommand('cls', {
+  action: clear,
+  help: 'Clears the screen.'
+});
+replServer.defineCommand('clear', {
+  action: clear,
+  help: 'Clears the screen.'
+});
+replServer.defineCommand('about', {
+  action: about,
+  help: 'Shows info about this project.'
+});
+replServer.defineCommand('state', {
+  help: 'Shows stats about this REPL\'s state.',
+  action() {
+    const state = generateState();
+    const i = (s) => `\x1b[3m${s}\x1b[23m`;
+    const j = ', ';
+
+    state.classes = [...Object.keys(state.classes)].map(k => String(k));
+    state.functions = [...Object.keys(state.functions)].map(k => String(k));
+    state.properties = [...Object.keys(state.properties)].map(k => String(k));
+    state.descriptors.accessors = [...Object.keys(state.descriptors.accessors)].map(k => String(k));
+    state.descriptors.data = [...Object.keys(state.descriptors.data)].map(k => String(k));
+
+    console.log(`\x1b[1mClasses\x1b[22m\n${wrapContent(state.classes, i, j)}`);
+    console.log(`\x1b[1mFunctions\x1b[22m\n${wrapContent(state.functions, i, j)}`);
+    console.log(`\x1b[1mProperties\x1b[22m\n${wrapContent(state.properties, i, j)}`);
+    console.log(`\x1b[1mAccessor Descriptors\x1b[22m\n${wrapContent(state.descriptors.accessors, i, j)}`);
+    console.log(`\x1b[1mData Descriptors\x1b[22m\n${wrapContent(state.descriptors.data, i, j)}`);
+
+    replServer.displayPrompt();
+  }
+});
+
+overridableGlobal('clear', clear);
+overridableGlobal('cls', clear);
+overridableGlobal('state', generateState);
+
+Object.defineProperty(replServer, '_initialPrompt', {
+  get() {
+    const isRed = !globalThis?._;
+    const prompt = isRed
+      ? '\x1b[31mλ\x1b[1;39m\x1b[22m '
+      : '\x1b[32mλ\x1b[1;39m\x1b[22m ';
+
+    return prompt;
+  }
+});
+
+function overridableGlobal(
+  property,
+  action,
+  changeText = 'Expression assignment to "@X", previous function now disabled.'
+) {
+  const message = changeText.replaceAll(/\@X/g, property);
+  let changed = false;
+  let storage = undefined;
+
+  const makeDescriptor = () => ({
+    get() {
+      if (changed === false) {
+        return action();
+      }
+      return storage;
+    },
+    set(value) {
+      if (changed === false) {
+        console.log(message);
+        changed = true;
+      }
+      storage = value;
+    },
+    configurable: true,
+    get enumerable() { return changed }
+  });
+
+  replServer.defineCommand(
+    `restore${property.charAt(0).toUpperCase()}${property.substring(1,property.length)}`,
+    {
+      action() {
+        changed = false;
+        storage = undefined;
+        Object.defineProperty(globalThis, property, makeDescriptor());
+        console.log(this.help);
+      },
+      help: `Restores ${property} to default REPL custom state.`,
+    }
+  );
+
+  Object.defineProperty(globalThis, property, makeDescriptor());
+}
+
+function generateState() {
+  const replState = {
+    classes: {},
+    functions: {},
+    properties: {},
+    descriptors: {
+      accessors: {},
+      data: {},
+    },
+  };
+
+  if (!allowInvocation) {
+    return replState;
+  }
+
+  let skipped = [];
+
+  allowInvocation = false;
+  Reflect.ownKeys(globalThis).forEach(key => {
+    try {
+      const value = globalThis[key];
+      const descriptor = Object.getOwnPropertyDescriptor(globalThis, key);
+
+      if (String(value).startsWith('class')) {
+        replState.classes[key] = {key, value, descriptor};
+      }
+      else if (typeof value === 'function') {
+        replState.functions[key] = {key, value, descriptor};
+      }
+      else {
+        replState.properties[key] = {key, value, descriptor};
+      }
+
+      if (Reflect.has(descriptor, 'get') || Reflect.has(descriptor, 'set')) {
+        replState.descriptors.accessors[key] = { key, descriptor };
+      }
+      else if (Reflect.has(descriptor, 'value')) {
+        replState.descriptors.data[key] = { key, descriptor };
+      }
+    }
+    catch (ignored) {
+      skipped.push(String(key));
+    }
+  });
+  allowInvocation = true;
+
+  return replState;
+}
+
+/**
+ * Formats a string or array of values into lines with specified indentation and line width.
+ * @param {string|array} input - The input string or array of strings to be formatted.
+ * @param {number} nCols - The maximum number of columns per line (default 80).
+ * @param {number} nSpaceIndents - The number of spaces for indentation (default 2).
+ * @returns {string} The formatted string.
+ */
+function formatValues(input, transform, nCols = 80, nSpaceIndents = 2) {
+  // Split the string into an array if input is a string
+  const values = typeof input === 'string' ? input.split(', ') : input;
+  let line = ''.padStart(nSpaceIndents, ' ');
+  let result = [];
+
+  values.forEach((value, index) => {
+    // Transform value if a transform function is supplied.
+    if (transform && typeof transform === 'function') {
+      value = transform(value);
+    }
+
+    // Check if adding the next value exceeds the column limit
+    if (line.length + value.length + 2 > nCols && line.trim().length > 0) {
+      // If it does, push the line to the result and start a new line
+      result.push(line);
+      line = ''.padStart(nSpaceIndents, ' ');
+    }
+
+    // Add the value to the line, followed by ", " if it's not the last value
+    line += value + (index < values.length - 1 ? ', ' : '');
+  });
+
+  // Add the last line if it's not empty
+  if (line.trim().length > 0) {
+    result.push(line);
+  }
+
+  return result.join('\n');
+}
+
+function wrapContent(longString, transform, joinOn = ' ', indent = 2, wrapAt = 80) {
+  let asArray = Array.isArray(longString)
+    ? longString
+    : String(longString).replaceAll(/\r\n/g, '\n').split('\n');
+
+  asArray = asArray.map(element => String(element).trim());
+
+  let lines = [];
+  let maxLen = wrapAt - indent;
+  let curLine = [];
+  let sgrLength = (s) => s.replaceAll(/\x1b\[?\d+(;\d+)*[a-zA-Z]/g, '').length;
+
+  for (let element of asArray) {
+    if (typeof transform === 'function') {
+      element = String(transform(element)).trim();
+    }
+
+    let curLength = sgrLength(curLine.join(joinOn));
+    let elementLength = sgrLength(String(element) + joinOn);
+
+    if (curLength + elementLength > maxLen) {
+      let leading = indent > 0 ? ' '.repeat(indent) : '';
+      lines.push(`${leading}${curLine.join(joinOn)}`);
+      curLine = [];
+    }
+
+    curLine.push(String(element));
+  }
+
+  return lines.join('\n');
+}

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/newClasses/deferred.js

@@ -49,6 +49,10 @@ export class Deferred extends Promise {
    */
   #resolve = null
 
+  #rejected = false
+
+  #resolved = false
+
   /**
    * When the Deferred is settled with {@link Deferred.resolve}, the `value`
    * passed to that function will be set here as well.
@@ -145,6 +149,10 @@ export class Deferred extends Promise {
       }
       // Mark the Deferred instance as settled
       this.#settled = true
+
+      // Mark the Deferred instance as resolved
+      this.#resolved = true
+
       // Resolve the promise with the provided value
       return _resolve(value)
     }
@@ -157,6 +165,10 @@ export class Deferred extends Promise {
       }
       // Mark the Deferred instance as settled
       this.#settled = true
+
+      // Mark the Deferred as being rejected.
+      this.#rejected = true
+
       // Reject the promise with the provided reason
       return _reject(reason)
     }
@@ -184,6 +196,32 @@ export class Deferred extends Promise {
     return this.#settled
   }
 
+  /**
+   * A getter that returns a boolean indicating whether the Deferred instance
+   * was rejected. This property can be used to check if the Deferred has been
+   * settled with a rejection. It is particularly useful in scenarios where
+   * the resolution status of the Deferred needs to be checked without
+   * accessing the rejection reason or invoking any additional logic.
+   *
+   * @returns {boolean} `true` if the Deferred was rejected, otherwise `false`.
+   */
+  get wasRejected() {
+    return this.#rejected
+  }
+
+  /**
+   * A getter that returns a boolean indicating whether the Deferred instance
+   * was resolved. This property is useful for checking if the Deferred has been
+   * settled with a resolution, allowing for checks on the Deferred's status
+   * without needing to access the resolved value or trigger any additional
+   * logic.
+   *
+   * @returns {boolean} `true` if the Deferred was resolved, otherwise `false`.
+   */
+  get wasResolved() {
+    return this.#resolved
+  }
+
   /**
    * Accessor for the promise managed by this Deferred instance.
    *
@@ -223,6 +261,35 @@ export class Deferred extends Promise {
     return this.#reject(reason)
   }
 
+  /**
+   * Customizes the output of `util.inspect` on instances of Deferred when
+   * used in Node.js. This method is invoked by Node.js's `util.inspect`
+   * utility to format the inspection output of a Deferred instance.
+   *
+   * The output includes the state of the Deferred (resolved, rejected, or
+   * unsettled) along with the resolved value or rejection reason, if
+   * applicable. This provides a quick, readable status of the Deferred
+   * instance directly in the console or debugging tools.
+   *
+   * @param {number} depth The depth to which `util.inspect` will recurse.
+   * @param {object} options Formatting options provided by `util.inspect`.
+   * @param {function} inspect Reference to the `util.inspect` function.
+   * @returns {string} A formatted string representing the Deferred instance.
+   */
+  [Symbol.for('nodejs.util.inspect.custom')](depth, options, inspect) {
+    return [
+      '\x1b[1mDeferred [\x1b[22;3mPromise\x1b[23;1m]\x1b[22m ',
+      '{ ',
+      (this.settled
+        ? (this.wasResolved
+          ? `resolved with \x1b[32m${this.value}\x1b[39m`
+          : `rejected with \x1b[31m${this.reason?.message ?? this.reason}\x1b[39m`)
+        : '\x1b[33munsettled valued or reason\x1b[39m'
+      ),
+      ' }'
+    ].join('')
+  }
+
   /**
    * A getter for the species symbol which returns a custom DeferredPromise
    * class. This class extends from Deferred and is used to ensure that the

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: '',
+    });
+  });
+});