@nejs/basic-extensions 2.9.0 → 2.11.0

package/src/classes/index.js

@@ -21,6 +21,9 @@ export * from './param.parser.js'
 import { PluggableProxy, ProxyHandler } from './pluggable.proxy.js'
 export * from './pluggable.proxy.js'
 
+import { Property, PropertyExtensions } from './property.js'
+export * from './property.js'
+
 import { RefMap  } from './refmap.js'
 export * from './refmap.js'
 
@@ -44,6 +47,7 @@ export const NewClassesExtension = new Patch(globalThis, {
   ParamParser,
   PluggableProxy,
   ProxyHandler,
+  Property,
   RefMap,
   RefSet,
   Symkeys,

package/src/classes/iterable.js

@@ -215,6 +215,80 @@ export class Iterator {
    * @private
    */
   #iterator = null;
+
+  /**
+   * Creates an Iterator for the keys of the given object.
+   *
+   * @note alternatives to keyFetcher might be `Reflect.ownKeys` or even
+   * `Object.keys`. Each type of fetcher has their own requirements but
+   * any function that takes an object and returns keys will suffice.
+   *
+   * @param {Object} object - The object whose keys will be iterated.
+   * @param {Function} [mapEach] - Optional function to map each key.
+   * @param {Function} [keyFetcher=Object.getOwnPropertyNames] - Function to
+   * fetch keys from the object. Defaults to Object.getOwnPropertyNames.
+   * @returns {Iterator} An Iterator instance containing the object's keys.
+   */
+  static keys(object, mapEach, keyFetcher) {
+    keyFetcher ??= Object.getOwnPropertyNames;
+
+    const keys = keyFetcher(object);
+    return new Iterator(keys, mapEach);
+  }
+
+  /**
+   * Creates an Iterator for the entries of the given object.
+   *
+   * @note alternatives to keyFetcher might be `Reflect.ownKeys` or even
+   * `Object.keys`. Each type of fetcher has their own requirements but
+   * any function that takes an object and returns keys will suffice.
+   *
+   * @param {Object} object - The object whose entries will be iterated.
+   * @param {Function} [mapEach] - Optional function to map each entry.
+   * @param {Function} [keyFetcher=Object.getOwnPropertyNames] - Function to
+   * fetch keys from the object. Defaults to Object.getOwnPropertyNames.
+   * @returns {Iterator} An Iterator instance containing the object's entries.
+   */
+  static entries(object, mapEach, keyFetcher) {
+    keyFetcher ??= Object.getOwnPropertyNames;
+
+    const keys = keyFetcher(object);
+    const entries = [];
+
+    for (const key of keys) {
+      entries.push([key, object[key]]);
+    }
+
+    return new Iterator(entries, mapEach)
+  }
+
+  /**
+   * Creates an Iterator for the property descriptors of the given object.
+   *
+   * @note alternatives to keyFetcher might be `Reflect.ownKeys` or even
+   * `Object.keys`. Each type of fetcher has their own requirements but
+   * any function that takes an object and returns keys will suffice.
+   *
+   * @param {Object} object - The object whose descriptors will be iterated.
+   * @param {Function} [mapEach] - Optional function to map each descriptor
+   * entry.
+   * @param {Function} [keyFetcher=Object.getOwnPropertyNames] - Function to
+   * fetch keys from the object. Defaults to Object.getOwnPropertyNames.
+   * @returns {Iterator} An Iterator instance containing entries of [key,
+   * descriptor] pairs.
+   */
+  static descriptors(object, mapEach, keyFetcher) {
+    keyFetcher ??= Object.getOwnPropertyNames;
+
+    const keys = keyFetcher(object);
+    const entries = [];
+
+    for (const key of keys) {
+      entries.push([key, Object.getOwnPropertyDescriptor(object, key)])
+    }
+
+    return new Iterator(entries, mapEach);
+  }
 }
 
 export const IterableExtensions = new Extension(Iterable)

package/src/classes/property.js

@@ -0,0 +1,333 @@
+import { Extension } from '@nejs/extension'
+
+export class Property {
+  constructor(key, descriptor) {
+    if (key.startsWith(':')) key = Symbol.for(key.slice(1))
+    if (typeof key !== 'string' && typeof key !== 'symbol') {
+      throw new TypeError('Key or symbol or :symbol must be supplied!');
+    }
+
+    this.key = key;
+
+    if (!Property.is.descriptor(descriptor)) {
+      this.descriptor = {
+        value: descriptor,
+        writable: true,
+        configurable: true,
+        enumerable: true,
+      }
+    }
+    else {
+      this.descriptor = descriptor;
+    }
+  }
+
+  apply(toObject, asKey) {
+    if (!toObject || !['object','function'].some(k => k == typeof toObject))
+      return;
+
+    return Object.defineProperty(toObject, asKey ?? this.key, this.descriptor)
+  }
+
+  get descriptor() {
+    const baseline = { configurable: true, enumerable: false };
+    const result = {
+      enumerable: this.meta.enumerable,
+      configurable: this.meta.configurable,
+    };
+
+    if (this.is.accessor) {
+      result.get = this.meta.accessor.get;
+      result.set = this.meta.accessor.set;
+    }
+    else {
+      result.value = this.meta.data.value;
+      result.writable = this.meta.data.writable;
+    }
+
+    return Object.defineProperties(result, {
+      make: {
+        ...baseline,
+        get() {
+          const self = this;
+
+          return {
+            get enumerable() {self.enumerable = true; return self},
+            get hidden() {self.enumerable = false; return self},
+
+            get writable() {self.writable = true; return self},
+            get readonly() {self.writable = false; return self},
+
+            get configurable() {self.configurable = true; return self},
+            get immutable() {self.configurable = false; return self},
+          }
+        }
+      },
+
+      is: {
+        ...baseline,
+        get() {
+          const self = this;
+
+          return {
+            get accessor() {return self.is.accssor},
+            get data() {return self.is.data}
+          }
+        }
+      },
+    })
+  }
+
+  set descriptor(descriptor) {
+    const { is } = this.constructor;
+
+    if (!is.descriptor(descriptor))
+      return;
+
+    this.meta.configurable = descriptor.configurable ?? true
+    this.meta.enumerable = descriptor.enumerable ?? true
+
+    if (Reflect.has(descriptor, 'get') || Reflect.has(descriptor, 'set')) {
+      const { get, set } = descriptor;
+
+      if (get !== undefined) this.meta.accessor.get = get;
+      if (set !== undefined) this.meta.accessor.set = set;
+    }
+    else {
+      const { value, writable } = descriptor;
+
+      this.meta.data.value = value;
+      this.meta.data.writable = writable ?? true;
+    }
+  }
+
+  get is() {
+    const self = this;
+
+    return {
+      get accessor() {
+        return !!(
+          self.meta.accessor.get ||
+          self.meta.accessor.set
+        );
+      },
+
+      get data() {
+        return !!!this.accessor
+      },
+    }
+  }
+
+  toString(colors = false, {key, descriptor} = {}) {
+    const bold = s => colors ? `\x1b[1m${s}\x1b[22m` : s;
+    const dim = s => colors ? `\x1b[2m${s}\x1b[22m` : s;
+    const red = s => colors ? `\x1b[31m${s}\x1b[39m` : s;
+    const green = s => colors ? `\x1b[32m${s}\x1b[39m` : s;
+    const blue = s => colors ? `\x1b[34m${s}\x1b[39m` : s;
+
+    if (!key) ({key} = this);
+    if (!descriptor || !Property.is.descriptor(descriptor))
+      ({descriptor} = this);
+
+    const buffer = [`${bold(key)} { `]
+    const keyPresent = (object) => (key) => Reflect.has(object, key)
+    const eqeq = (value, compare = (a,b) => a === b) =>
+      (element) => compare(element, value);
+
+    if (['get', 'set'].some(keyPresent(descriptor))) {
+      if (descriptor.get) {
+        buffer.push(blue('getter'))
+        if (descriptor.set) {
+          buffer.push(bold('|'))
+        }
+      }
+
+      if (descriptor.set) {
+        buffer.push(blue('setter'))
+      }
+    }
+    else {
+      buffer.push(green('value'))
+      buffer.push(bold('|'))
+      buffer.push(descriptor.writable ? green('writable') : red('readonly'))
+    }
+
+    buffer.push(' ')
+    buffer.push(descriptor.configurable ? green('mutable') : red('immuatable'))
+
+    buffer.push(' ')
+    buffer.push(descriptor.enumerable ? green('visible') : red('hidden'))
+
+    buffer.push(' }')
+
+    return buffer.join('')
+  }
+
+  [Symbol.for('nodejs.util.inspect.custom')](depth, options, inspect) {
+    return this.toString(true);
+  }
+
+  /**
+   * Creates an accessor property with customizable getter and setter functions.
+   *
+   * This method offers flexible ways to define accessor properties, including
+   * support for storage-based getters and setters. It can handle various input
+   * formats, making it versatile for different use cases.
+   *
+   * @param {string} name - The name of the accessor property.
+   * @param {Object} accessors - Object containing getter and/or setter functions.
+   * @param {Function} [accessors.get] - Getter function for the property.
+   * @param {Function} [accessors.set] - Setter function for the property.
+   * @param {Object} [accessors.prototype] - Prototype object for getter/setter.
+   * @param {Object} [options] - Additional options for the accessor property.
+   * @param {boolean} [options.configurable=true] - Whether property is configurable.
+   * @param {boolean} [options.enumerable=true] - Whether property is enumerable.
+   * @param {Object} [options.storage] - Storage object for getter/setter closures.
+   * @returns {Property} A new Property instance representing the accessor.
+   * @throws {TypeError} If no name, getter, or setter is provided.
+   *
+   * @example
+   * // Basic usage
+   * Property.accessor('color', {
+   *   get() { return this._color; },
+   *   set(value) { this._color = value; }
+   * });
+   *
+   * @example
+   * // Using storage
+   * Property.accessor('keyword', {
+   *   get(storage) { return () => storage.keyword; },
+   *   set(storage) { return (value) => { storage.keyword = value; } }
+   * }, { storage: { keyword: 'initial' } });
+   *
+   * @example
+   * // Using named getter function
+   * Property.accessor('color', function get() { return 'red' })
+   *
+   * @example
+   * // Using prototype
+   * const ColorAccessors = {
+   *   red: { get() { return this._red; } }
+   * };
+   * Property.accessor('red', ColorAccessors.red);
+   */
+  static accessor(
+    name,
+    {get, set, prototype},
+    {configurable, enumerable, storage} = {}
+  ) {
+    if (!get && !set && prototype) {
+      const constructor = prototype?.constructor;
+
+      if (constructor?.name === 'get') {
+        get = constructor;
+      }
+      else if (constructor?.name === 'set') {
+        set = constructor
+      }
+    }
+
+    if (get && storage && get.length == 1) {
+      get = get(storage);
+    }
+
+    if (set && storage && set.length == 1) {
+      set = set(storage);
+    }
+
+    if (!name && !get && !set) throw new TypeError('Cannot create accessor');
+
+    configurable ??= true
+    enumerable ??= true
+
+    return new Property(name, { get, set, configurable, enumerable });
+  }
+
+  static data(name, value, { writable, configurable, enumerable } = {}) {
+    if (!name) throw new TypeError('Cannot create data property without name')
+
+    writable ??= true
+    configurable ??= true
+    enumerable ??= true
+
+    return new Property(name, { value, writable, configurable, enumerable })
+  }
+
+  static from(object, name) {
+    const descriptor = Object.getOwnPropertyDescriptor(object, name);
+    return new Property(name, descriptor);
+  }
+
+  static get is() {
+    return {
+      object(value) {
+        return value && ['object','function'].some(k => k == typeof value);
+      },
+
+      descriptor(object) {
+        if (!Property.is.object(object)) {
+          return false;
+        }
+
+        const present = element => Reflect.has(object, element);
+        const props = {
+          base: ['configurable', 'enumerable'],
+          data: ['writable', 'value'],
+          accessor: ['get', 'set'],
+        };
+
+        if (Object.getOwnPropertyNames(object).length > 4)
+          return false;
+
+        if (props.data.some(present) && props.accessor.some(present))
+          return false;
+
+        if (props.base.some(present)) return true;
+        if (props.data.some(present)) return true;
+        if (props.accessor.some(present)) return true;
+
+        return false;
+      }
+    }
+  }
+
+  static {
+    const storage = Object.assign(Object.create(null), {
+      key: undefined,
+      meta: {
+        enumerable: true,
+        configurable: true,
+        accessor: {
+          get: undefined,
+          set: undefined
+        },
+        data: {
+          value: undefined,
+          writable: true
+        },
+      },
+    });
+
+    basic_accessor(this.prototype, 'key', storage.key, storage)
+    basic_accessor(this.prototype, 'meta', storage.meta, storage);
+  }
+}
+
+export const PropertyExtensions = new Extension(Property);
+
+function basic_accessor(prototype, key, initialValue, storage = {}) {
+  storage[key] = initialValue;
+
+  Object.defineProperty(prototype, key, {
+    get() {
+      return storage[key]
+    },
+    set(value) {
+      storage[key] = value
+    },
+    enumerable: true,
+    configurable: true,
+  });
+
+  return Object.getOwnPropertyDescriptor(prototype, key);
+}

package/src/classes/symkeys.js

@@ -18,35 +18,136 @@ import { Extension } from '@nejs/extension'
 */
 export class Symkeys {
   /**
-   * Adds a new entry to the Symkeys with a unique symbol based on the provided
-   * name and associates it with the given data.
-   *
-   * @param named - The base name for the symbol to be created.
-   * @param [associatedData={}] - The data to associate with the symbol.
-   * @returns The unique symbol created for the entry.
+   * Adds a new symbol to the Symkeys instance with the given name and
+   * associated data.
+   *
+   * This method generates a unique symbol based on the provided name,
+   * optional domain, separator, and token. It also allows embedding
+   * additional data into the symbol's name.
+   *
+   * @param {string} named - The base name for the new symbol.
+   * @param {Object} options - Additional options for the symbol.
+   * @param {*} [options.associate={}] - Data to associate with the symbol.
+   * @param {Object} [options.embed] - Optional data to embed in the symbol.
+   * @param {string} [options.useDomain] - Optional domain to include in the
+   * symbol's name.
+   * @param {string} [options.useSeparator] - Optional separator to use in
+   * the symbol's name.
+   * @param {string} [options.useToken] - Optional token to use for the
+   * symbol. If not provided, a random token is generated.
+   * @returns {Symbol} The newly created symbol.
    *
    * @example
-   * // Add an entry with associated data
-   * const symbol = Symkeys.add('myEntry', { foo: 'bar' });
-   * // Retrieve the associated data using the symbol
-   * const data = Symkeys.dataFor(symbol);
-   * console.log(data); // Output: { foo: 'bar' }
+   * // Add a symbol with associated data
+   * const mySymbol = symkeys.add('myIdentifier', {
+   *   associate: { foo: 'bar' },
+   *   embed: { baz: 'qux' },
+   *   useDomain: 'exampleDomain',
+   *   useSeparator: '-',
+   *   useToken: 'customToken',
+   * })
+   * console.log(mySymbol)
+   * // Symbol(@exampleDomain-myIdentifier {"baz":"qux"} #customToken)
    */
-  add(named, associatedData = {}) {
+  add(
+    named,
+    {
+      associate = {},
+      embed = undefined,
+      useDomain = undefined,
+      useSeparator = undefined,
+      useToken = undefined,
+    }
+  ) {
     // Generate a unique token for the symbol
-    const token = Symkeys.token;
+    const token = useToken ?? Symkeys.token
 
     // Calculate a name (optionally with domain and separator)
-    const symName = this.calculateName(named)
+    let symName = this.calculateName(named, useDomain, useSeparator)
+
+    if (embed && typeof embed === 'object') {
+      try {
+        symName += ` ${JSON.stringify(embed)}`
+      }
+      catch (error) {
+        console.warn(`Cannot create JSON from ${embed}; skipping`)
+      }
+    }
 
     // Create a symbol using the provided name and the unique token
-    const symbol = Symbol.for(`@${symName} #${token}`);
+    const symbol = Symbol.for(`@${symName} #${token}`)
 
     // Store the symbol and associated data in the Symkeys's internal map
-    this[Symkeys.kDataKey].set(symbol, associatedData);
+    this[Symkeys.kDataKey].set(symbol, associate ?? {})
 
     // Return the unique symbol for external use
-    return symbol;
+    return symbol
+  }
+
+  /**
+   * Creates or retrieves a shared symbol key with the given name and
+   * optional associated data.
+   *
+   * This method generates a shared symbol key using the provided name
+   * and optional parameters. If the symbol already exists in the
+   * Symkeys's internal map, it updates the associated data if provided.
+   * Otherwise, it creates a new symbol with the specified parameters.
+   *
+   * @param {string} named - The name to use for the shared symbol key.
+   * @param {Object} options - Optional parameters for the shared symbol key.
+   * @param {Object} [options.associate] - Data to associate with the symbol.
+   * @param {Object} [options.embed] - Data to embed in the symbol's name.
+   * @param {string} [options.useDomain] - Domain to include in the symbol's name.
+   * @param {string} [options.useSeparator] - Separator to use in the symbol's name.
+   * @returns {Symbol} The shared symbol key.
+   *
+   * @example
+   * // Create or retrieve a shared symbol key with associated data
+   * const sharedSymbol = symkeys.sharedKey('mySharedKey', {
+   *   associate: { foo: 'bar' },
+   *   embed: { baz: 'qux' },
+   *   useDomain: 'exampleDomain',
+   *   useSeparator: '-',
+   * })
+   * console.log(sharedSymbol)
+   * // Symbol(@exampleDomain-mySharedKey {"baz":"qux"} #shared)
+   */
+  sharedKey(named, { associate, embed, useDomain, useSeparator }) {
+    // Calculate the symbol name with optional domain and separator
+    const symName = this.calculateName(named, useDomain, useSeparator)
+
+    // Initialize JSON string for embedded data
+    let json = ''
+    if (embed && typeof embed === 'object') {
+      try {
+        json = ` ${JSON.stringify(embed)}`
+      } catch (ignored) {
+        // Ignore JSON stringify errors
+      }
+    }
+
+    // Create the shared symbol key
+    const symbol = Symbol.for(`@${symName}${json} #shared`)
+
+    // Check if the symbol already exists in the internal map
+    if (this[Symkeys.kDataKey].has(symbol)) {
+      // Update associated data if provided and symbol is a Symkey
+      if (associate && symbol.isSymkey) {
+        symbol.data = associate
+      }
+
+      // Return the existing symbol
+      return symbol
+    }
+
+    // Add a new symbol with the specified parameters
+    return this.add(named, {
+      associate: associate ?? {},
+      embed,
+      useDomain,
+      useSeparator,
+      useToken: 'shared'
+    })
   }
 
   /**
@@ -175,7 +276,7 @@ export class Symkeys {
   token(forSymbol) {
     // Use a regular expression to match the token pattern in the symbol
     // description exists on symbol but our JS output target is too old
-    return /^.* \#(.*?)$/.exec(forSymbol).description?.[1];
+    return /^.* \#(.*?)$/.exec(forSymbol)?.description?.[1];
   }
 
   /**
@@ -386,7 +487,7 @@ export class Symkeys {
       return false
     }
 
-    return !!/^@.*? #\w+$/.exec(value.description)
+    return !!/^@.*? #\w+$/.exec(value?.description)
   }
 
   /**

package/src/function.extensions.js

@@ -772,6 +772,8 @@ export const FunctionPrototypeExtensions = new Patch(Function.prototype, {
 // Object<->Function<->Global occurs. See original source in global.this.js
 // {@see globalThis.isThenElse}
 function isThenElse(bv, tv, ev) {
+  function isFunction(value) { typeof value === 'function' }
+
   if (arguments.length > 1) {
     var _then = isFunction(tv) ? tv(bv) : tv; if (arguments.length > 2) {
       var _else = isFunction(ev) ? tv(bv) : ev; return bv ? _then : _else

package/src/global.this.js

@@ -1,11 +1,19 @@
 import { Patch } from '@nejs/extension'
 import { FunctionExtensions } from './function.extensions.js'
+import * as copyObject from './utils/copy.object.js'
+import { as, has, is, si } from './utils/toolkit.js'
 
 const { isClass, isFunction } = FunctionExtensions.patches
 const CustomInspect = Symbol.for('nodejs.util.inspect.custom')
 
 export const GlobalFunctionsAndProps = new Patch(globalThis, {
   [Patch.kMutablyHidden]: {
+    /** copyObject suite exports into global */
+    ...copyObject,
+
+    /** Type toolkit exports into global */
+    as, has, is, si,
+
     /**
      * The `isThenElse` function is a utility function that behaves like a
      * ternary operator. It takes three arguments: `boolValue`, `thenValue`,

package/src/index.js

@@ -17,6 +17,7 @@ import { DescriptorExtensions, Descriptor } from './classes/descriptor.js'
 import { IntrospectorExtensions } from './classes/introspector.js'
 import { IteratorExtensions, IterableExtensions } from './classes/iterable.js'
 import { ParamParserExtensions } from './classes/param.parser.js'
+import { PropertyExtensions } from './classes/property.js'
 import {
   PluggableProxyExtensions,
   ProxyHandlerExtensions,
@@ -27,6 +28,10 @@ import { RefSetExtensions } from './classes/refset.js'
 import { SymkeysExtension } from './classes/symkeys.js'
 import { TypeExtensions } from './classes/type.js'
 
+export * from './utils/copy.object.js'
+export * from './utils/toolkit.js'
+export * from './utils/descriptor.utils.js'
+
 import {
   AsyncIteratorExtensions,
   AsyncIterableExtensions
@@ -75,6 +80,7 @@ const Extensions = {
   [ParamParserExtensions.key]: ParamParserExtensions,
   [PluggableProxyExtensions.key]: PluggableProxyExtensions,
   [ProxyHandlerExtensions.key]: ProxyHandlerExtensions,
+  [PropertyExtensions.key]: PropertyExtensions,
   [RefMapExtensions.key]: RefMapExtensions,
   [RefSetExtensions.key]: RefSetExtensions,
   [SymkeysExtension.key]: SymkeysExtension,