@nejs/basic-extensions 2.8.0 → 2.9.0

package/package.json

@@ -60,10 +60,10 @@
     "repl": "npm run build && node --no-warnings repl.bootstrap.js"
   },
   "type": "module",
-  "version": "2.8.0",
+  "version": "2.9.0",
   "dependencies": {
-    "@nejs/extension": "^2.15.0",
+    "@nejs/extension": "^2.20.0",
     "zod": "^3.22.5"
   },
-  "browser": "dist/@nejs/basic-extensions.bundle.2.7.0.js"
-}
+  "browser": "dist/@nejs/basic-extensions.bundle.2.9.0.js"
+}

package/src/json.extensions.js

@@ -65,8 +65,9 @@ export const JSONExtensions = new Patch(JSON, {
      * // Using `mightContain`
      * console.log(JSON.mightContain(str))  // Output: true
      */
-    mightContain(string) {
-      return !!this.JSONStartPattern.exec(string)
+    mightContain(string, detail = false) {
+      const results = this.JSONStartPattern.exec(string)
+      return detail ? [!!results, results?.index ?? -1, results] : !!results
     },
 
     /**

package/src/object.extensions.js

@@ -181,18 +181,27 @@ export const ObjectExtensions = new Patch(Object, {
       return Object.defineProperty(object, key, { ...properties, get, set })
     },
 
+    addAccessor(to, key, getter, setter, storage) {
+      const store = storage ?? (!getter && !setter) ? true : undefined;
+      return this.add({ to, key, get: getter, set: setter, storage: store })
+    },
+
+    addData(to, key, value) {
+      return this.add({ to, key, value })
+    },
+
     add(...args) {
       const { isDescriptor } = Descriptor
       const { isObject: isObj } = this
       const { kDescriptorStore } = this
 
-      let toObject, key, value, _get, _set, storage, storageKey
+      let obj, key, value, _get, _set, storage, storageKey
       let _type, _flag, _desc
 
       // Check to see if we received multiple arguments or an object
       if (args.length && isObj(args[0])) {
         ({
-          toObject: obj,
+          to: obj,
           key,
           value,
           get: _get,
@@ -206,7 +215,7 @@ export const ObjectExtensions = new Patch(Object, {
       }
       else if (args.length > 1) {
         ([
-          toObject,
+          to,
           _type,
           key,
           getOrValue,
@@ -217,6 +226,7 @@ export const ObjectExtensions = new Patch(Object, {
           _desc,
         ] = args)
 
+        obj = to
         _type = (
           ['accessor', 'data'].includes(_type.toLowerCase())
           ? _type.toLowerCase() : 'data'
@@ -225,6 +235,11 @@ export const ObjectExtensions = new Patch(Object, {
         _value = _type === 'data' ? getOrValue : undefined
       }
 
+      if (!this.isObject(obj)) {
+        console.warn('Object.add() must receive an object for `toObject`')
+        return obj;
+      }
+
       const more = isDescriptor(_desc) ? _desc : {}
       const flag = _flag || Object.definitionType.mutablyVisible
       const props = { ...Patch.getDescriptorOverridesFromSymbol(flag), ...more }
@@ -250,7 +265,7 @@ export const ObjectExtensions = new Patch(Object, {
           }
           // store should be defined by here: object or undefined
 
-          if (!get && !set && makeStore) {
+          if ((!get && !set) && makeStore) {
             // being lazy here, someone has defined we make an accessor but
             // wants the default accessor behaviors with an associated store
             // made by us.
@@ -261,11 +276,11 @@ export const ObjectExtensions = new Patch(Object, {
               writable: true,
             })
 
-            get = () => this[kDescriptorStore].data[storeKey]
+            get = () => this[kDescriptorStore]?.data?.[storeKey]
             set = (value) => { this[kDescriptorStore].data[storeKey] = value }
           }
 
-          else if (get.length && set.length > 1 && store) {
+          else if (get?.length && set?.length > 1 && store) {
             // if we received a get or set that takes more arguments than
             // expected, assume the last argument should be the store variable
             // so we execute the supplied function with the storage and its

package/src/string.extensions.js

@@ -273,68 +273,287 @@ export const StringExtensions = new Patch(String, {
     return `rgba(${red}, ${green}, ${blue}, ${alpha.toFixed(2)})`
   },
 
+  /**
+   * Applies Select Graphic Rendition (SGR) parameters to a given message for
+   * styling in terminal environments. This function allows for the dynamic
+   * styling of text output using ANSI escape codes. It supports a variety of
+   * modes such as color, brightness, and text decorations like bold or underline.
+   *
+   * @param {string} message The message to be styled.
+   * @param {...string} useModes A series of strings representing the desired
+   * styling modes. Modes can include colors (e.g., 'red', 'blue'), brightness
+   * ('bright'), foreground/background ('fg', 'bg'), and text decorations
+   * ('bold', 'underline'). Modes can be combined in a single string using
+   * commas or passed as separate arguments.
+   *
+   * Colors:
+   * ```
+   * 'black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'
+   * ```
+   * Color Specifiers:
+   * ```
+   * 'fg' -> foreground   |  'bg' -> background  |  'bright' -> bright colors
+   * ```
+   *
+   * Modes:
+   * ```
+   * 'blink' or 'k' | 'conceal' or 'c' | 'italics' or 'i'  | 'strike' or 's'
+   * 'bold' or 'b'  | 'dim' or 'd'     | 'negative' or 'n' | 'underline' or 'u'
+   * ```
+   *
+   * Examples:
+   * - `sgr('Hello', 'red')` applies red color to 'Hello'.
+   * - `sgr('World', 'green,bold')` applies green color and bold styling
+   *   to 'World'.
+   * - `sgr('Example', 'bluebgbright')` applies bright blue
+   *   background color.
+   *
+   * Short hand syntax is also allowed:
+   * - `sgr('hello', 'biu')` applies bold, italics and underline
+   * - `sgr('hello', 'bi,redfg')` applies bold, italics and red foreground
+   *
+   * As a bonus, there is a secret getter applied to the return string that
+   * allows you to invoke `sgr(...).show` to automatically log the output to
+   * `console.log`. This is done by wrapping the output string in `Object()`
+   * to make it a `String` instance and then adding the property descriptor.
+   * A custom `Symbol` is applied to make it evaluate in nodejs as though it
+   * were a normal string. To strip the extras, wrap the output in `String()`
+   *
+   * @returns {string} The message wrapped in ANSI escape codes corresponding
+   * to the specified modes. The returned string, when printed to a terminal,
+   * displays the styled message. Additional properties are attached to the
+   * result for utility purposes, such as 'show' for immediate console output.
+   */
+  sgr(message, ...useModes) {
+    const colors = Object.assign(
+      ['black', 'red', 'green', 'yellow', 'blue', 'magenta', 'cyan', 'white'],
+      {
+        isBG: a => !!/bg/i.exec(a),
+        isBright: a => !!/bright/i.exec(a),
+        isColor: a => {
+          let color = colors.find(c => new RegExp(c, 'i').exec(a));
+          return [!!color, colors.indexOf(color)];
+        },
+      }
+    );
+
+    const arrayifyString = s => {
+      if (Array.isArray(s)) {
+        let results = [];
+
+        for (const i of s) {
+          results = [ ...results, ...arrayifyString(i) ];
+        }
+
+        return results.flat().filter(i => i.length);
+      }
+
+      if (!s || typeof s !== 'string') {
+        return [''];
+      }
+      else if (s.includes(',')) {
+        return arrayifyString(s.split(','));
+      }
+      else {
+        if (!colors.isColor(s)[0] && s.length > 1) {
+          return [...s];
+        }
+        else return [s];
+      }
+    }
+
+    let modes = arrayifyString(useModes)
+
+    const sgrModes = {
+      blink: ['\x1b[5m', '\x1b[25m', 'k'],
+      bold: ['\x1b[1m', '\x1b[22m', 'b'],
+      conceal: ['\x1b[8m', '\x1b[28m', 'c'],
+      dim: ['\x1b[2m', '\x1b[22m', 'd'],
+      italics: ['\x1b[3m', '\x1b[23m', 'i'],
+      negative: ['\x1b[7m', '\x1b[27m', 'n'],
+      strike: ['\x1b[9m', '\x1b[29m', 's'],
+      underline: ['\x1b[4m', '\x1b[24m', 'u'],
+    };
+
+    Object.values(sgrModes).forEach(mode => sgrModes[mode[2]] = mode);
+
+    const codes = a => {
+      let open = '', close = '', mode = String(a).toLowerCase();
+      let [_isColor, colorIndex] = colors.isColor(mode);
+
+      if (_isColor) {
+        open = colors.isBG(mode)
+          ? `\x1b[${colors.isBright(mode) ? 10 : 4}${colorIndex}m`
+          : `\x1b[${colors.isBright(mode) ? 9 : 3}${colorIndex}m`;
+        close = colors.isBG(mode) ? '\x1b[49m' : `\x1b[39m`;
+      }
+      else if (sgrModes[mode]) {
+        open = sgrModes[mode][0];
+        close = sgrModes[mode][1];
+      }
+
+      return [open, close];
+    };
+
+    const onOrder = modes.map(key => codes(key)[0]).join('');
+    const offOrder = modes.map(key => codes(key)[1]).reverse().join('');
+
+    let result = Object(`${onOrder}${message}${offOrder}`)
+
+    Object.defineProperties(result, {
+      show: {
+        get() { console.log(String(this)); return this },
+        enumerable: false,
+      },
+      [Symbol.for('nodejs.util.inspect.custom')]: {
+        value(depth, options, inspect) {
+          return inspect(String(this), options)
+        },
+        enumerable: false,
+      },
+    })
+
+    return result
+  },
+
+  /**
+   * Wraps an object's properties into a formatted string.
+   *
+   * This method takes an object and a set of options to format the
+   * object's properties into a string. It allows customization of
+   * indentation, line endings, maximum line length, and more.
+   *
+   * @param {Object} [object=globalThis] - The object to wrap.
+   * @param {Object} [options={}] - The formatting options.
+   * @param {number} [options.indent=2] - The number of indentation
+   * characters to use.
+   * @param {string} [options.indentCharacter=' '] - The character to use
+   * for indentation.
+   * @param {Array} [options.inspector=[Object, 'getOwnPropertyNames']] -
+   * The inspector to use for retrieving object properties.
+   * @param {string} [options.lineEnding='\n'] - The line ending character.
+   * @param {number} [options.maxLen=78] - The maximum line length.
+   * @param {Function} [options.perLine=undefined] - A function to apply
+   * per line of output.
+   * @param {Function} [options.perLinePerProperty=undefined] - A function
+   * to apply per property per line of output.
+   * @param {Function} [options.preProcess=undefined] - A function to
+   * preprocess the object's properties.
+   * @param {Function} [options.preReturn=undefined] - A function to apply
+   * to the final output before returning.
+   * @param {string} [options.separator=', '] - The separator to use
+   * between properties.
+   *
+   * @returns {string} The formatted string representation of the object.
+   *
+   * @example
+   * const obj = { a: 1, b: 2, c: 3 }
+   * const wrapped = StringExtensions.wrap(obj, { maxLen: 20 })
+   * console.log(wrapped)
+   * // Output:
+   * // {
+   * //   a: 1,
+   * //   b: 2,
+   * //   c: 3
+   * // }
+   */
   wrap(
-    object = globalThis,
+    objectOrLines,
     options = {
+      colorProperties: undefined,
       indent: 2,
-      separator: ', ',
       indentCharacter: ' ',
-      lineEnding: '\n',
       inspector: [Object, 'getOwnPropertyNames'],
-      mapValues: undefined,
-      mapLine: undefined,
+      lineEnding: '\n',
+      maxLen: 78,
+      perLine: undefined,
+      perLinePerProperty: undefined,
+      preProcess: undefined,
+      preReturn: undefined,
+      separator: ', ',
     }
   ) {
-    const {
-      indent = 2,
-      separator = ', ',
-      indentCharacter = ' ',
-      lineEnding = '\n',
-      inspector = [Object, 'getOwnPropertyNames'],
-      mapValues,
-      mapLine,
+    let {
+      colorProperties = undefined,
+      indent = options?.indent ?? 2,
+      indentCharacter = options?.indentCharacter ?? ' ',
+      inspector = options?.inspector ?? [Object, 'getOwnPropertyNames'],
+      lineEnding = options?.lineEnding ?? '\n',
+      maxLen = options?.maxLen ?? 78,
+      perLine = options?.perLine ?? undefined,
+      perLinePerProperty = options?.perLinePerProperty ?? undefined,
+      preProcess = options?.preProcess ?? undefined,
+      preReturn = options?.preReturn ?? undefined,
+      separator = options?.separator ?? ', ',
     } = options ?? {}
 
-    let tab = indent === 0 ? '' : indentCharacter.repeat(Number(indent) || 2);
-    let maxLen = 76 - tab.length;
-    let line = [];
+    let tab = indent === 0 ? ''
+      : indentCharacter.repeat(Number(indent) || 2)
+    maxLen = 78 - tab.length
+
+    const sgr = this.sgr;
+    const validMapper = f => typeof f === 'function'
+
+    let line = []
     let getElements = inspector[0][inspector[1]]
-    let values = Array.isArray(object) ? object : getElements(Object(object));
+    let values = Array.isArray(objectOrLines)
+      ? objectOrLines : getElements(Object(objectOrLines))
 
-    if (typeof mapValues === 'function') {
-      values = values.map(mapValues)
+    if (validMapper(preProcess)) {
+      values = preProcess(values)
     }
 
-    return values.reduce((acc,key,index,{length}) => {
-      const endOfLine = index < (length - 1) ? separator : '';
-      let ifCombined = [
-        tab,...line.join(separator), key, endOfLine
-      ].join('').trim();
+    const context = { indent, indentCharacter, lineEnding, maxLen, tab, sgr }
+
+    let finalLines = values.reduce((acc, nextProp) => {
+      let ifCombined = [...line, nextProp].join(separator)
 
-      if (ifCombined.length < maxLen) {
-        line.push(key)
+      if ((tab.length + ifCombined.length) <= maxLen) {
+        line.push(nextProp)
       }
+
       else {
+        let lineProps = [...line]
+
+        if (validMapper(perLinePerProperty)) {
+          lineProps = lineProps.map((value, index, array) => {
+            return perLinePerProperty(value, index, array, context)
+          })
+        }
 
-        let lineElements = [...line, key ]
-        let debug = `<-- (len: ${[tab,...line.join(separator),key,endOfLine].join('').trim().length})`
-        if (typeof mapLine === 'function') {
-          lineElements = lineElements.map(mapLine)
+        if (colorProperties) {
+          const sgrArgs = (Array.isArray(colorProperties)
+            ? colorProperties
+            : [colorProperties]
+          )
+          lineProps = lineProps.map(v => sgr(v, ...sgrArgs))
         }
 
-        const completeLine = (
-          tab +
-          lineElements.slice(1).join(separator) +
-          endOfLine
-        ).trim()
+        lineProps = [tab, lineProps.join(separator)].join('')
+        if (validMapper(perLine)) {
+          lineProps = perLine(lineProps[0], 0, lineProps)?.[0] ?? lineProps[0]
+        }
+
+        acc.push(lineProps)
+        line = []
+      }
 
-        acc.push(completeLine + debug);
+      return acc
+    }, [])
 
-        line = [];
-      };
+    if (validMapper(preReturn)) {
+      finalLines = finalLines.map((value, index, array) => {
+        return preReturn(value, index, array, context)
+      })
+    }
+
+    Symbol.for(`@nejs.string.wrap ${JSON.stringify({lines: finalLines})}`)
+
+    if (lineEnding) {
+      finalLines = finalLines.join(lineEnding)
+    }
 
-      return acc;
-    }, []).join(lineEnding)
+    return finalLines
   },
 });
 

package/src/symbol.extensions.js

@@ -1,9 +1,9 @@
-import { Patch } from '@nejs/extension';
+import { Patch, PatchToggle } from '@nejs/extension';
 
 import { Symkeys } from './classes/symkeys.js'
 import { JSONExtensions } from './json.extensions.js'
 
-const { extractFrom, mightContain } = JSONExtensions.patches
+const JSONToggle = new PatchToggle(JSONExtensions)
 
 /**
  * `SymbolExtensions` is a patch for the JavaScript built-in `Symbol` class. It
@@ -14,31 +14,16 @@ const { extractFrom, mightContain } = JSONExtensions.patches
  * utility functions.
  */
 export const SymbolExtensions = new Patch(Symbol, {
-  /**
-   * Creates a new Symbol with the given name and optional data. If data
-   * is provided, it will be stringified and appended to the symbol's
-   * name. This method is useful for creating unique symbols that carry
-   * additional metadata.
-   *
-   * @param {string} name The name of the symbol.
-   * @param {*} [data] Optional data to be associated with the symbol.
-   * @returns {symbol} A new symbol created with Symbol.for(), using the
-   * provided name and stringified data (if provided).
-   *
-   * @example
-   * const symbolWithData = Symbol.withData('mySymbol', { foo: 'bar' })
-   * console.log(symbolWithData.toString())
-   * // Output: "Symbol(mySymbol {"foo":"bar"})"
-   *
-   * @example
-   * const symbolWithoutData = Symbol.withData('mySymbol')
-   * console.log(symbolWithoutData.toString())
-   * // Output: "Symbol(mySymbol)"
-   */
-  withData(name, data) {
-    return data !== undefined
-      ? Symbol.for(`${name} ${JSON.stringify(data)}`)
-      : Symbol.for(name)
+  add(named, associatedData = {}) {
+    return this.keys.add(named, associatedData)
+  },
+
+  deleteData(forSymbol, replaceWith = undefined) {
+    return this.keys.deleteData(forSymbol, replaceWith)
+  },
+
+  hasData(forSymbol) {
+    return this.keys.hasData(forSymbol)
   },
 
   /**
@@ -125,6 +110,37 @@ export const SymbolExtensions = new Patch(Symbol, {
    * kOriginal.data = [Object.prototype, Array.prototype] // ...both work
    */
   keys: new Symkeys('nejs'),
+
+  setData(forSymbol, value) {
+    this.keys.setData(forSymbol, value)
+  },
+
+  /**
+   * Creates a new Symbol with the given name and optional data. If data
+   * is provided, it will be stringified and appended to the symbol's
+   * name. This method is useful for creating unique symbols that carry
+   * additional metadata.
+   *
+   * @param {string} name The name of the symbol.
+   * @param {*} [data] Optional data to be associated with the symbol.
+   * @returns {symbol} A new symbol created with Symbol.for(), using the
+   * provided name and stringified data (if provided).
+   *
+   * @example
+   * const symbolWithData = Symbol.withData('mySymbol', { foo: 'bar' })
+   * console.log(symbolWithData.toString())
+   * // Output: "Symbol(mySymbol {"foo":"bar"})"
+   *
+   * @example
+   * const symbolWithoutData = Symbol.withData('mySymbol')
+   * console.log(symbolWithoutData.toString())
+   * // Output: "Symbol(mySymbol)"
+   */
+  withData(name, data) {
+    return data !== undefined
+      ? Symbol.for(`${name} ${JSON.stringify(data)}`)
+      : Symbol.for(name)
+  },
 });
 
 export const SymbolPrototypeExtensions = new Patch(Symbol.prototype, {
@@ -195,7 +211,23 @@ export const SymbolPrototypeExtensions = new Patch(Symbol.prototype, {
         }
       }
 
-      return extractFrom(string)
+      let result = undefined;
+      let revertToggle = false
+      if (!JSONExtensions.applied) {
+        JSONToggle.start()
+        revertToggle = true
+      }
+
+      if (JSON.mightContain(this.description)) {
+        try { result = JSON.extractFrom(this.description) }
+        catch (ignore) { }
+      }
+
+      if (revertToggle) {
+        JSONToggle.stop()
+      }
+
+      return result
     },
 
     /**
@@ -262,7 +294,96 @@ export const SymbolPrototypeExtensions = new Patch(Symbol.prototype, {
      * console.log(sym.mightHaveEmbeddedJSON) // Output: false
      */
     get mightHaveEmbeddedJSON() {
-      return mightContain(this.description) && typeof this.data === 'function'
+      return mightContain(this.description)
+    },
+
+    get sgrString() {
+      let revert = false
+      let detail = undefined
+
+      let { sgr } = String
+      if (!sgr) { sgr = (string, ...args) => string }
+
+      if (!JSONExtensions.applied) { JSONToggle.start(); revert = true }
+      if ((detail = JSON.mightContain(this.description, true))) {
+        let jsonText = detail[2][0]
+        let index = detail[1]
+
+        if (~index && jsonText && jsonText.length > 30) {
+          let desc = this.description
+          let newDescription = [
+            sgr(`Symbol.for(${desc.slice(0, index)}`, 'green'),
+            sgr(jsonText.slice(0, 10), 'di'),
+            '...',
+            sgr(jsonText.slice(-5), 'di'),
+            sgr(`${desc.slice(index + jsonText.length + 1)})`, 'green'),
+          ].join('')
+
+          if (revert) { JSONToggle.stop() }
+          return `${newDescription}`
+        }
+      }
+
+      if (revert) { JSONToggle.stop() }
+
+      return newDescription
     },
-  }
+
+    /**
+     * Custom inspect method for Node.js util.inspect.
+     *
+     * NOTE: this will only apply if looking at an instance of Symbol,
+     * sadly; {@see SymbolPrototypeExtensions.instance}
+     *
+     * This method is used by Node.js util.inspect to provide a custom
+     * representation of the symbol when inspected. It checks if the
+     * symbol's description might contain JSON data and if so, it
+     * truncates the JSON data in the description to a maximum of 30
+     * characters and formats the output with colors using the `sgr`
+     * function from the `String` object.
+     *
+     * @param {number} depth - The current depth of the recursive
+     * inspection.
+     * @param {Object} options - The options object passed to
+     * util.inspect.
+     * @param {Function} inspect - The original util.inspect function.
+     *
+     * @returns {string} - The formatted representation of the symbol.
+     *
+     * @example
+     * const sym = Symbol.for('fun {"name":"John Doe"}')
+     * console.log(util.inspect(sym))
+     * // Output: Symbol.for(fun {"name":"John ...hn Doe"})
+     */
+    [Symbol.for('nodejs.util.inspect.custom')](depth, options, inspect) {
+      let revert = false
+      let detail = undefined
+
+      let { sgr } = String
+      if (!sgr) { sgr = (string, ...args) => string }
+
+      if (!JSONExtensions.applied) { JSONToggle.start(); revert = true }
+      if ((detail = JSON.mightContain(this.description, true))) {
+        let jsonText = detail[2][0]
+        let index = detail[1]
+
+        if (~index && jsonText && jsonText.length > 30) {
+          let desc = this.description
+          let newDescription = [
+            sgr(`Symbol.for(${desc.slice(0, index)}`, 'green'),
+            sgr(jsonText.slice(0, 10), 'di'),
+            '...',
+            sgr(jsonText.slice(-5), 'di'),
+            sgr(`${desc.slice(index + jsonText.length + 1)})`, 'green'),
+          ].join('')
+
+          if (revert) { JSONToggle.stop() }
+          return `${newDescription}`
+        }
+      }
+
+      if (revert) { JSONToggle.stop() }
+      return inspect(this, { colors: true })
+    },
+  },
 })