@nejs/basic-extensions 1.6.1 → 1.7.0

package/jsdoc-config.json

@@ -0,0 +1,31 @@
+{
+	"tags": {
+		"allowUnknownTags": true
+	},
+	"source": {
+		"include": [
+			"src"
+		]
+	},
+	"plugins": ["plugins/markdown"],
+	"templates": {
+		"cleverLinks": false,
+		"monospaceLinks": false,
+		"default": {
+			"outputSourceFiles": true
+		}
+	},
+	"opts": {
+		"encoding": "utf8",
+		"destination": "docs",
+		"recurse": true,
+		"template": "node_modules/docdash"
+	},
+	"markdown.hardwrap": true,
+	"markdown": {
+		"hardwrap": true
+	},
+	"metadata": {
+		"title": "@nejs/basic-extensions docs"
+	}
+}

package/package.json

@@ -3,10 +3,17 @@
   "description": "Basic but commonly used extensions",
   "devDependencies": {
     "@jest/expect": "^29.7.0",
+    "clean-documentation-theme": "^0.5.2",
+    "docdash": "^2.0.2",
+    "documentation": "^14.0.2",
+    "documentation-devseed-theme": "^0.1.7",
     "esbuild": "^0.19.10",
+    "esdoc": "^1.1.0",
+    "esdoc-standard-plugin": "^1.0.0",
     "jest": "^29.7.0",
     "jest-cli": "^29.7.0",
     "jest-localstorage-mock": "^2.4.26",
+    "jsdoc": "^4.0.2",
     "prompts": "^2.4.2",
     "rimraf": "^5.0.5",
     "typescript": "^5.2.2"
@@ -42,13 +49,15 @@
     "build": "bin/clean && bin/esbuild && bin/build",
     "browser": "bin/esbuild",
     "clean": "bin/clean",
+    "jsdoc": "jsdoc -c jsdoc-config.json -p -a all -R README.md",
+    "documentation": "documentation build src/** -f html --github -o docs && documentation readme src/index.js --section=API",
     "module": "bin/build",
     "test": "jest"
   },
   "type": "module",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "dependencies": {
-    "@nejs/extension": "^1.3.0"
+    "@nejs/extension": "^2.1.0"
   },
-  "browser": "dist/@nejs/basic-extensions.bundle.1.6.0.js"
+  "browser": "dist/@nejs/basic-extensions.bundle.1.6.1.js"
 }

package/src/globals.js

@@ -1,7 +1,7 @@
 import { Patch } from '@nejs/extension'
 import { FunctionExtensions } from './functionextensions.js'
 
-const { isClass, isFunction } = FunctionExtensions.patchEntries.isClass.computed
+const { isClass, isFunction } = FunctionExtensions.patches
 const CustomInspect = Symbol.for('nodejs.util.inspect.custom')
 
 export const GlobalFunctionsAndProps = new Patch(globalThis, {

package/src/index.js

@@ -1,97 +1,93 @@
 import { FunctionExtensions } from './functionextensions.js'
-import { ObjectExtensions } from './objectextensions.js'
+import { ObjectExtensions, ObjectPrototypeExtensions } from './objectextensions.js'
+import { MapPrototypeExtensions } from './mapextensions.js'
 import { ReflectExtensions } from './reflectextensions.js'
 import { StringExtensions } from './stringextensions.js'
 import { SymbolExtensions } from './symbolextensions.js'
 import { ArrayPrototypeExtensions } from './arrayextensions.js'
-import { DescriptorExtensions } from './descriptor.js'
+import { DescriptorExtensions, Descriptor } from './newClasses/descriptor.js'
 import { GlobalFunctionsAndProps } from './globals.js'
-import { RefSetExtensions } from './refset.js'
+import { RefSetExtensions } from './newClasses/refset.js'
+import { RefMapExtensions } from './newClasses/refmap.js'
 
 import {
   AsyncIteratorExtensions,
   AsyncIterableExtensions
-} from './asyncIterable.js'
+} from './newClasses/asyncIterable.js'
 
 import {
   IteratorExtensions,
   IterableExtensions
-} from './iterable.js'
-
-import { Patch } from '@nejs/extension'
-
-const Owners = [
-  Object,
-  Function,
-  Reflect,
-  String,
-  Symbol,
-
-  Array.prototype,
-]
-
-const NetNew = [
-  GlobalFunctionsAndProps,
-  DescriptorExtensions,
-  AsyncIterableExtensions,
-  AsyncIteratorExtensions,
-  IterableExtensions,
-  IteratorExtensions,
-  RefSetExtensions,
-]
-
-export function enableAll(owners) {
-  const list = owners || Owners
-
-  if (!list) {
-    throw new Error('Unable to enable features without owners list')
-  }
-
-  list.forEach(owner => {
-    Patch.enableFor(owner)
-  })
-
-  enableNetNew()
+} from './newClasses/iterable.js'
+
+const Patches = new Map([
+  [Object, ObjectExtensions],
+  [Function, FunctionExtensions],
+  [Reflect, ReflectExtensions],
+  [String, StringExtensions],
+  [Symbol, SymbolExtensions],
+
+  [Object.prototype, ObjectPrototypeExtensions],
+  [Array.prototype, ArrayPrototypeExtensions],
+  [Map.prototype, MapPrototypeExtensions],
+  [globalThis, GlobalFunctionsAndProps],
+])
+
+const Extensions = {
+  [DescriptorExtensions.key]: DescriptorExtensions,
+  [AsyncIterableExtensions.key]: AsyncIterableExtensions,
+  [AsyncIteratorExtensions.key]: AsyncIteratorExtensions,
+  [IterableExtensions.key]: IterableExtensions,
+  [IteratorExtensions.key]: IteratorExtensions,
+  [RefSetExtensions.key]: RefSetExtensions,
+  [RefMapExtensions.key]: RefMapExtensions,
 }
 
-export function enableNetNew() {
-  NetNew.forEach(extension => { extension.apply() })
-}
+const Controls = {}
 
-export function disableAll(owners) {
-  const list = owners || Owners
+Object.assign(Controls, {
+  enableAll() {
+    Controls.enablePatches()
+    Controls.enableExtensions()
+  },
 
-  if (!list) {
-    throw new Error('Unable to disable features without owners list')
-  }
+  enablePatches() {
+    Patches.forEach((extension) => { extension.apply() })
+  },
 
-  list.forEach(owner => {
-    Patch.disableFor(owner)
-  })
+  enableExtensions() {
+    Object.values(Extensions).forEach((extension) => { extension.apply() })
+  },
 
-  disableNetNew()
-}
+  disableAll(owners) {
+    Controls.disablePatches()
+    Controls.disableExtensions()
+  },
 
-export function disableNetNew() {
-  NetNew.forEach(extension => { extension.revert() })
-}
+  disablePatches() {
+    Patches.forEach((extension) => { extension.revert() })
+  },
+
+  disableExtensions() {
+    Object.values(Extensions).forEach((extension) => { extension.revert() })
+  },
+})
 
 export const all = (() => {
-  let extensions = [
-    ObjectExtensions,
-    FunctionExtensions,
-    ReflectExtensions,
-    StringExtensions,
-    SymbolExtensions,
-    ArrayPrototypeExtensions,
-
-    GlobalFunctionsAndProps,
-    DescriptorExtensions,
+  const extensions = [
+    ...Array.from(Patches.values()),
+    ...Array.from(Object.values(Extensions)),
   ]
 
   const dest = extensions.reduce((accumulator, extension) => {
     Reflect.ownKeys(extension.patchEntries).reduce((_, key) => {
-      accumulator[key] = extension.patchEntries[key].computed
+      const entry = extension.patchEntries[key]
+
+      if (entry.isAccessor)
+        accumulator[key] = new Descriptor(entry.descriptor)
+      else
+        accumulator[key] = entry.computed
+
       return accumulator
     }, accumulator)
 
@@ -101,20 +97,17 @@ export const all = (() => {
   return dest
 })()
 
+const results = {
+  ...Controls,
+  extensions: Extensions,
+  patches: Patches,
+  all,
+}
+
+export default results
 
 export {
-  ObjectExtensions,
-  FunctionExtensions,
-  ReflectExtensions,
-  StringExtensions,
-  SymbolExtensions,
-  ArrayPrototypeExtensions,
-
-  GlobalFunctionsAndProps,
-  DescriptorExtensions,
-  AsyncIterableExtensions,
-  AsyncIteratorExtensions,
-  IterableExtensions,
-  IteratorExtensions,
-  RefSetExtensions,
-}
+  Extensions,
+  Patches,
+  Controls,
+}

package/src/mapextensions.js

@@ -0,0 +1,30 @@
+import { Patch } from '@nejs/extension';
+
+export const MapPrototypeExtensions = new Patch(Map.prototype, {
+  /**
+   * The function `getKey` returns the key associated with a given value
+   * in a map.
+   *
+   * @param {any} value - The value parameter is the value that you want to
+   * find the corresponding key for in the map.
+   * @param [strict=true] - The "strict" parameter is a boolean value that
+   * determines whether strict equality (===) or loose equality (==) should
+   * be used when comparing the "value" parameter with the values in the
+   * entries of the object. If "strict" is set to true, strict equality will
+   * be used.
+   * @returns the key associated with the given value. If a matching key is
+   * found, it is returned. If no matching key is found, null is returned.
+   */
+  getKey(value, strict = true) {
+    for (const [key, entryValue] of this) {
+      if (
+        (strict && value === entryValue) &&
+        (!strict && value == entryValue)
+      ) {
+        return key
+      }
+
+      return null
+    }
+  },
+})

package/src/{asyncIterable.js → newClasses/asyncIterable.js}

@@ -8,7 +8,7 @@ import { Extension } from '@nejs/extension'
  * reading in chunks, or any other data that is not immediately available but
  * arrives over time.
  */
-class AsyncIterable {
+export class AsyncIterable {
   /**
    * Private field to store the elements of the async iterable.
    * @private
@@ -69,140 +69,140 @@ class AsyncIterable {
   }
 
   /**
-   * Being able to create a compliant `AsyncIterator` around any type of
-   * iterable object. This can be wrapped around any type of object that
-   * has a `[Symbol.asyncIterator]` property assigned to a generator
-   * function.
+   * Checks if a given value is an async iterable. This method determines if
+   * the provided value has a `Symbol.asyncIterator` property that is an async
+   * generator function. It's a precise way to identify if the value conforms
+   * to the async iterable protocol using an async generator function.
+   *
+   * Note: This method specifically checks for async generator functions. Some
+   * async iterables might use regular async functions that return an async
+   * iterator, which this method won't identify.
+   *
+   * @param {*} value - The value to be checked for async iterability.
+   * @returns {boolean} - Returns true if the value is an async iterable
+   * implemented using an async generator function, false otherwise.
    */
-  static AsyncIterator = class AsyncIterator {
-    /**
-     * Creates a new `AsyncIterator` object instance.
-     *
-     * @param {object} asyncIterable any object that has a
-     * `[Symbol.asyncIterable]` property assigned to a generator function.
-     */
-    constructor(asyncIterable) {
-      if (!asyncIterable || !Reflect.has(asyncIterable, Symbol.asyncIterator)) {
-        throw new TypeError(
-          'Value used to instantiate AsyncIterator is not an async iterable'
-        );
-      }
-
-      this.#asyncIterable = asyncIterable;
-      this.#asyncIterator = asyncIterable[Symbol.asyncIterator]();
-    }
+  static isAsyncIterable(value) {
+    const type = Object.prototype.toString.call(value?.[Symbol.asyncIterator]);
+    return type === '[object AsyncGeneratorFunction]';
+  }
+}
 
-    /**
-     * Returns a new `Array` derived from the iterable this object
-     * wraps.
-     *
-     * @returns {array} a new `Array` generated from the wrapped
-     * iterable. The method is generated from using an async for of
-     * loop.
-     */
-    async asArray() {
-      const array = []
-
-      for await (const value of this) {
-        array.push(value)
-      }
-
-      return array
+/**
+ * Being able to create a compliant `AsyncIterator` around any type of
+ * iterable object. This can be wrapped around any type of object that
+ * has a `[Symbol.asyncIterator]` property assigned to a generator
+ * function.
+ */
+export class AsyncIterator {
+  /**
+   * Creates a new `AsyncIterator` object instance.
+   *
+   * @param {object} asyncIterable any object that has a
+   * `[Symbol.asyncIterable]` property assigned to a generator function.
+   */
+  constructor(asyncIterable) {
+    if (!asyncIterable || !Reflect.has(asyncIterable, Symbol.asyncIterator)) {
+      throw new TypeError(
+        'Value used to instantiate AsyncIterator is not an async iterable'
+      );
     }
 
-    /**
-     * Returns the actual iterable object passed to the constructor that
-     * created this instance.
-     *
-     * @returns {object} the object containing the `[Symbol.iterator]`
-     */
-    get asyncIterable() {
-      return this.#asyncIterable
-    }
+    this.#asyncIterable = asyncIterable;
+    this.#asyncIterator = asyncIterable[Symbol.asyncIterator]();
+  }
 
-    /**
-     * The function retrieves the next value in the iterator. If the
-     * the iterator has run its course, `reset()` can be invoked to
-     * reset the pointer to the beginning of the iteration.
-     *
-     * @returns {any} the next value
-     */
-    async next() {
-      const result = await this.#asyncIterator.next();
-      if (result.done) {
-        return { value: undefined, done: true };
-      } else {
-        return { value: result.value, done: false };
-      }
-    }
+  /**
+   * Returns a new `Array` derived from the iterable this object
+   * wraps.
+   *
+   * @returns {array} a new `Array` generated from the wrapped
+   * iterable. The method is generated from using an async for of
+   * loop.
+   */
+  async asArray() {
+    const array = []
 
-    /**
-     * Resets the async iterator to the beginning allowing it to be
-     * iterated over again.
-     */
-    async reset() {
-      this.#asyncIterator = this.#asyncIterable[Symbol.asyncIterator]();
+    for await (const value of this) {
+      array.push(value)
     }
 
-    /**
-     * The existence of this symbol on the object instances, indicates that
-     * it can be used in `for(.. of ..)` loops and its values can be
-     * extracted from calls to `Array.from()`
-     *
-     * @returns {AsyncIterable} this is returned since this object is already
-     * conforming to the expected JavaScript AsyncIterator interface
-     */
-    [Symbol.asyncIterator]() {
-      return this;
-    }
+    return array
+  }
 
-    /**
-     * Ensures that the constructor of this object instance's name
-     * is returned if the string tag for this instance is queried
-     *
-     * @returns {string} the name of the class
-     */
-    get [Symbol.toStringTag]() {
-      return this.constructor.name;
+  /**
+   * Returns the actual iterable object passed to the constructor that
+   * created this instance.
+   *
+   * @returns {object} the object containing the `[Symbol.iterator]`
+   */
+  get asyncIterable() {
+    return this.#asyncIterable
+  }
+
+  /**
+   * The function retrieves the next value in the iterator. If the
+   * the iterator has run its course, `reset()` can be invoked to
+   * reset the pointer to the beginning of the iteration.
+   *
+   * @returns {any} the next value
+   */
+  async next() {
+    const result = await this.#asyncIterator.next();
+    if (result.done) {
+      return { value: undefined, done: true };
+    } else {
+      return { value: result.value, done: false };
     }
+  }
 
-    /**
-     * The object from which its iterator functionality is derived.
-     *
-     * @type {object}
-     * @private
-     */
-    #asyncIterable = null;
-
-    /**
-     * The results of a call to the iterable's `[Symbol.asyncIterator]`
-     * generator function.
-     *
-     * @type {object}
-     * @private
-     */
-    #asyncIterator = null;
+  /**
+   * Resets the async iterator to the beginning allowing it to be
+   * iterated over again.
+   */
+  async reset() {
+    this.#asyncIterator = this.#asyncIterable[Symbol.asyncIterator]();
   }
 
   /**
-   * Checks if a given value is an async iterable. This method determines if
-   * the provided value has a `Symbol.asyncIterator` property that is an async
-   * generator function. It's a precise way to identify if the value conforms
-   * to the async iterable protocol using an async generator function.
+   * The existence of this symbol on the object instances, indicates that
+   * it can be used in `for(.. of ..)` loops and its values can be
+   * extracted from calls to `Array.from()`
    *
-   * Note: This method specifically checks for async generator functions. Some
-   * async iterables might use regular async functions that return an async
-   * iterator, which this method won't identify.
+   * @returns {AsyncIterable} this is returned since this object is already
+   * conforming to the expected JavaScript AsyncIterator interface
+   */
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+
+  /**
+   * Ensures that the constructor of this object instance's name
+   * is returned if the string tag for this instance is queried
    *
-   * @param {*} value - The value to be checked for async iterability.
-   * @returns {boolean} - Returns true if the value is an async iterable
-   * implemented using an async generator function, false otherwise.
+   * @returns {string} the name of the class
    */
-  static isAsyncIterable(value) {
-    const type = Object.prototype.toString.call(value?.[Symbol.asyncIterator]);
-    return type === '[object AsyncGeneratorFunction]';
+  get [Symbol.toStringTag]() {
+    return this.constructor.name;
   }
+
+  /**
+   * The object from which its iterator functionality is derived.
+   *
+   * @type {object}
+   * @private
+   */
+  #asyncIterable = null;
+
+  /**
+   * The results of a call to the iterable's `[Symbol.asyncIterator]`
+   * generator function.
+   *
+   * @type {object}
+   * @private
+   */
+  #asyncIterator = null;
 }
 
 export const AsyncIterableExtensions = new Extension(AsyncIterable)
-export const AsyncIteratorExtensions = new Extension(AsyncIterable.AsyncIterator)
+export const AsyncIteratorExtensions = new Extension(AsyncIterator)