@nejs/basic-extensions 2.3.0 → 2.4.0

package/package.json

@@ -58,9 +58,9 @@
     "test": "jest"
   },
   "type": "module",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "dependencies": {
-    "@nejs/extension": "^2.7.1"
+    "@nejs/extension": "^2.7.2"
   },
-  "browser": "dist/@nejs/basic-extensions.bundle.2.2.1.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/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