@lumjs/core 1.33.0 → 1.35.0

package/lib/traits.js

@@ -10,13 +10,18 @@ const getProp = require('./obj/getproperty');
 const 
 {
   def,F,B,S,
-  isObj,isArray,isConstructor,isProperty,
+  isObj,isArray,isConstructor,isProperty,isClassObject,
   needObj,needType,
 } = require('./types');
 
 // Symbol for private storage of composed traits.
 const COMPOSED_TRAITS = Symbol.for('@lumjs/core/traits~ComposedTraits');
 
+const FLAG_ET = 1; // Flag for ensure target
+const FLAG_ES = 2; // Flag for ensure source
+const FLAGS_S = 0; // Default flags for static mode
+const FLAGS_O = 3; // Default flags for object mode
+
 /**
  * For when we need a prototype object exclusively.
  * 
@@ -30,7 +35,7 @@ const COMPOSED_TRAITS = Symbol.for('@lumjs/core/traits~ComposedTraits');
  * If `from` is a `function` then `from.prototype` will be returned.
  * 
  * @throws {TypeError} If `from` was not a valid value;
- * including if it is a `function` but does not have a valid
+ * including if it is a function but does not have a valid
  * prototype object to return.
  * 
  * @alias module:@lumjs/core/traits.ensureProto
@@ -47,7 +52,42 @@ function ensureProto(from)
   }
   else
   {
-    throw new TypeError("Invalid class constructor or object instance");
+    throw new TypeError("Invalid class constructor or instance object");
+  }
+}
+
+/**
+ * For when we need a constructor function exclusively.
+ * 
+ * @param {(function|object)} from - Target
+ * 
+ * May either be a class constructor `function`, or an `object` instance.
+ * 
+ * @returns {function}
+ * 
+ * If `from` is a constructor function it will be returned as-is.
+ * If `from` is an object instance (with a constructor other than `Object`),
+ * then the `from.constructor` value will be returned.
+ * 
+ * @throws {TypeError} If `from` was not a valid value;
+ * including if it was a function without a prototype,
+ * or an object with a constructor of `Object`.
+ * 
+ * @alias module:@lumjs/core/traits.ensureConstructor
+ */
+function ensureConstructor(from)
+{
+  if (isConstructor(from))
+  { // Good to go
+    return from;
+  }
+  else if (isClassObject(from))
+  { // An instance of a class (other than `Object` itself)
+    return from.constructor;
+  }
+  else
+  {
+    throw new TypeError("Invalid class constructor or instance object");
   }
 }
 
@@ -125,13 +165,16 @@ function getComposed(target, source, tryClass=true)
     composed = target[COMPOSED_TRAITS];
   }
 
-  if (composed && source && composed.has(source))
-  { // Let's get definitions for a specific trait.
-    return composed.get(source);
-  }
-  else if (composed && !source)
-  { // No trait specified, but compose rules found.
-    return composed;
+  if (composed)
+  {
+    if (!source)
+    {
+      return composed;
+    }
+    if (composed.has(source))
+    { // Let's get definitions for a specific trait.
+      return composed.get(source);
+    }
   }
 
   if (tryClass && isObj(target))
@@ -224,9 +267,27 @@ function mapComposed(target, source)
  * or use the {@link module:@lumjs/core/traits.composeFully} function.
  * 
  * Only useful if `source` is a class constructor (always recommended).
+ * The exact behaviour may be customized further with the `.flags` option.
  * 
  * Default is `false`.
  * 
+ * @param {number} [opts.flags] Binary flags for advanced behaviours
+ * 
+ * The default `.flags` value, and the _ensure function_ used depends
+ * on the value of the `.static` option:
+ * 
+ * | .static | Default | Ensure function                                     |
+ * | ------- | ------- | --------------------------------------------------- |
+ * | `false` | `3`     | {@link module:@lumjs/core/traits.ensureProto}       |
+ * | `true`  | `0`     | {@link module:@lumjs/core/traits.ensureConstructor} |
+ * 
+ * The actual flags are fairly straightforward:
+ * 
+ * | Flag | Description                                                      |
+ * | ---- | ---------------------------------------------------------------- |
+ * | `1`  | Pass `target` through _ensure function_                          |
+ * | `2`  | Pass `source` through _ensure function_                          |
+ * 
  * @param {boolean} [opts.symbols=false] Auto-compose `Symbol` properties?
  * 
  * Calls `Object.getOwnPropertySymbols()` when generating a list of 
@@ -260,8 +321,7 @@ function compose(specTarget, specSource, opts={})
     =  getComposed(specTarget, specSource) 
     ?? mapComposed(specTarget, specSource);
 
-  const isStatic = opts.static ?? false;
-  
+  const isStatic = opts.static ?? false; 
   const mapId = isStatic ? 'static' : 'proto';
 
   if (composedMaps[mapId])
@@ -270,8 +330,11 @@ function compose(specTarget, specSource, opts={})
     return composedMaps;
   }
 
-  const target = isStatic ? specTarget : ensureProto(specTarget);
-  const source = isStatic ? specSource : ensureProto(specSource);
+  const flags = parseInt(opts.flags) ?? (isStatic ? FLAGS_S : FLAGS_O);
+  const ensure = isStatic ? ensureConstructor : ensureProto;
+
+  const target = (flags & FLAG_ET) ? specTarget : ensure(specTarget);
+  const source = (flags & FLAG_ES) ? specSource : ensure(specSource);
 
   let props  = opts.props;
 
@@ -382,7 +445,6 @@ function compose(specTarget, specSource, opts={})
     composed.set(tprop, cdef);
   }
 
-  composedMaps[mapId] = composed;
   return composedMaps;
 }
 
@@ -642,9 +704,10 @@ class CoreTrait
    * @param {boolean} info.ok - Will always be `true` initially.
    * 
    * If an overridden `removeTrait()` method sets this to `false`,
-   * then the `decomposeFrom()` operation will be cancelled before
-   * decomposing the trait.
+   * then the decomposeFrom() operation will skip the step of
+   * actually decomposing the trait.
    * 
+   * @returns {*} Return value is not used. 
    */
   static removeTrait(info)
   {
@@ -714,7 +777,7 @@ class CoreTrait
  * @returns {function} The `registerTrait()` function created above.
  * @alias module:@lumjs/core/traits.makeRegistry
  */
-function makeTraitRegistry(registry)
+function makeTraitRegistry(registry={})
 {
   needObj(registry, false, 'invalid trait registry object');
 
@@ -749,56 +812,10 @@ function makeTraitRegistry(registry)
 module.exports = 
 {
   compose, composeFully, getComposed, decompose,
-  Trait: CoreTrait, IGNORE_STATIC, ensureProto,
+  Trait: CoreTrait, IGNORE_STATIC, 
+  ensureProto, ensureConstructor,
   makeRegistry: makeTraitRegistry,
 
   // Undocumented:
   hasOwn,
 }
-
-/**
- * Composed property maps.
- * 
- * @typedef {object} module:@lumjs/core/traits~Composed
- * 
- * @prop {?Map} proto  - Map of composed *prototype* properties.
- * 
- * Keys are the `string` or `symbol` for each composed property.
- * Values are {@link module:@lumjs/core/traits~ComposedProperty} objects.
- * 
- * If no applicable trait properties are currently composed,
- * this will be `null`.
- * 
- * @prop {?Map} static - Map of composed *static* properties.
- * 
- * Exactly the same description as `proto`, but for static properties.
- * 
- * @prop {boolean} forClass - Are these property maps from a class?
- * 
- * Will be `true` if the original target was a `function`, or `false`
- * otherwise. Only really useful when trait functions need to be called
- * differently depending on if the trait was applied to an individual
- * instance or a class constructor.
- * 
- */
-
-/**
- * Composed property definitions.
- * 
- * @typedef {object} module:@lumjs/core/traits~ComposedProperty
- * 
- * @prop {(string|Symbol)} id - The property key on the `target`
- * @prop {(string|Symbol)} [srcKey] The property key from the `source`;
- * only included if different from `propKey`.
- * 
- * @prop {?object} newDescriptor - The property descriptor to be added;
- * will be `null` if the property did not exist.
- * 
- * @prop {object} [oldDescriptor] The replaced property descriptor;
- * only included if there was an existing property in the `target` 
- * and the `opts.overwrite` option was `true`.
- * 
- * @prop {boolean} found - Was the property found in the `source` ?
- * @prop {boolean} added - Was the property added to the `target` ?
- * 
- */

package/lib/types/basics.js

@@ -144,6 +144,9 @@ function isIterable(v)
 /**
  * Does a value appear to be a class constructor?
  * 
+ * For the purposes of this test, a class constructor is
+ * any Function that has a `prototype` Object property.
+ * 
  * @param {*} v - Value to test
  * @returns {boolean}
  * @alias module:@lumjs/core/types/basics.isConstructor
@@ -153,6 +156,35 @@ function isConstructor(v)
   return (typeof v === F && isObj(v.prototype));
 }
 
+/**
+ * Is a value a _plain_ object?
+ * 
+ * A plain object is one which has a `constructor` property
+ * that **IS** the `globalThis.Object` function.
+ * 
+ * @param {*} v - Value to test
+ * @returns {boolean}
+ */
+function isPlainObject(v)
+{
+  return (isObj(v) && v.constructor === Object);
+}
+
+/**
+ * Is a value a class instance object?
+ * 
+ * This is a counterpart to isPlainObject() that only returns
+ * true if the `constructor` property exists, but is **NOT**
+ * the `globalThis.Object` function.
+ * 
+ * @param {*} v - Value to test
+ * @returns {boolean}
+ */
+function isClassObject(v)
+{
+  return (isObj(v) && typeof v.constructor === F && v.constructor !== Object);
+}
+
 /**
  * See if an object can be used as a valid *descriptor*.
  * 
@@ -246,7 +278,8 @@ module.exports =
 {
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
   isIterable, nonEmptyArray, isArguments, isProperty, isConstructor,
-  doesDescriptor, doesDescriptorTemplate, JS,
+  isPlainObject, isClassObject, doesDescriptor, doesDescriptorTemplate,
+  JS,
 }
 
 JS.addTo(module.exports);

package/lib/types/index.js

@@ -16,11 +16,11 @@ Object.assign(exports,
   require('./basics'), 
   require('./root'),
   require('./isa'),
+  require('./stringify'),
   require('./needs'),
   { // A few standalone exports.
     def, lazy,
     TYPES: require('./typelist'),
-    stringify: require('./stringify'),
     ownCount: require('./owncount'),
   },
 );

package/lib/types/stringify.js

@@ -1,142 +1,301 @@
 // Get the extended type list.
 const TYPES = require('./typelist');
-const {isObj, isArray, isTypedArray} = require('./basics');
+const {F, S, N, B, isObj, isArray, isTypedArray} = require('./basics');
 const def = require('./def');
 
-const TOSTRING_TYPES = [TYPES.F, TYPES.SY];
+const TOSTRING_TYPES     = [TYPES.SY];
 const TOSTRING_INSTANCES = [RegExp];
 const CUSTOM = [];
+const DEF = 
+{
+  MAXD: 1,
+  NEWD: 0,
+}
 
 /**
  * Stringify a Javascript value.
  * 
- * We typically just use `JSON.stringify()` but that doesn't work on
- * some types. So this function adds string formats for:
+ * Creates a new `Stringify` instance, then passes the
+ * first argument to it's `stringify()` method.
+ * 
+ * This is the primary way to use the Stringify class
+ * rather than manually creating an instance of it.
+ * 
+ * @param {*} what - Passed to `instance.stringify()`
+ * @param {(object|number)} [opts] Options for Stringify constructor;
+ * 
+ * If this is a `number` it's the `opts.maxDepth` option value.
+ * 
+ * @param {(number|boolean)} [addNew] The `opts.newDepth` option value;
+ * 
+ * For compatibility with old API. Boolean values are shortcuts:
+ * - `false` = `0`
+ * - `true`  = `1`
+ * 
+ * @returns {string} The stringified value
+ * 
+ * @alias module:@lumjs/core/types.stringify
+ * @see module:@lumjs/core/types.Stringify
+ * @see module:@lumjs/core/types.Stringify#stringify
+ */
+function stringify (what, opts={}, addNew=null)
+{
+  if (typeof opts === N)
+  {
+    opts = {maxDepth: opts}
+  }
+
+  if (typeof addNew === N)
+  {
+    opts.newDepth = addNew;
+  }
+  else if (typeof addNew === B)
+  {
+    opts.newDepth = addNew ? 1 : 0;
+  }
+
+  const si = new Stringify(opts);
+  return si.stringify(what);
+}
+
+/**
+ * A class to stringify Javascript values for testing and debugging.
+ * 
+ * This is NOT meant for serializing data, the output is in a format
+ * that's meant to be read by a developer, not parsed by a machine.
+ * 
+ * Currently directly supports:
+ * 
  *  - `function`
  *  - `symbol`
  *  - `TypedArray`
  *  - `Map`
  *  - `Set`
  *  - `Error`
- * I may add even more extended types in the future, but that's enough
- * for now.
+ *  - `RegExp`
+ *  - `Object`
  * 
- * This is NOT meant for serializing data, and does not use a JSON-friendly
- * output format. I'm writing a different library for that.
+ * Any other JS value types (`number`,`boolean`, `string`, etc.) will
+ * be serialized using JSON.
  * 
- * @param {*} what - The value to stringify.
- * @param {integer} [recurse=1] Recurse objects to this depth.
- * @param {boolean} [addNew=false] Use 'new Class()' instead of 'Class()'. 
- * @returns {string} The stringified value.
- * @alias module:@lumjs/core/types.stringify
+ * @alias module:@lumjs/core/types.Stringify
  */
-function stringify (what, recurse=1, addNew=false)
+class Stringify 
 {
-  const whatType = typeof what;
-
-  for (const test of CUSTOM)
-  { // If there are custom extensions, we check them first.
-    const ret = test.call({stringify}, what, recurse, addNew);
-    if (typeof ret === TYPES.S)
-    { // The extension processed the item.
-      return ret;
-    }
-  }
+  /**
+   * Create a new Stringify instance
+   * @param {object} [opts] Options; saved to `this.options`
+   * @param {number} [opts.maxDepth=1] Max depth to recurse?
+   * @param {number} [opts.newDepth=0] Depth to prepend 'new' to strings?
+   * @param {boolean} [opts.fnString=false] Fully stringify functions?
+   * @param {(Array|function)} [opts.setCustom] Set custom stringifiers;
+   * used *INSTEAD* of the globally registered ones.
+   * @param {(Array|function)} [opts.addCustom] Add custom stringifiers;
+   * used *in addition* to the globally registered ones.
+   */
+  constructor(opts={})
+  {
+    this.options = opts;
+    this.maxDepth = opts.maxDepth ?? DEF.MAXD;
+    this.newDepth = opts.newDepth ?? DEF.NEWD;
+    this.seenObjects = new Map(); // object => description
+    this.seenDescrip = new Map(); // description => count
+    this.strClass = TOSTRING_INSTANCES.slice();
+    this.strTypes = TOSTRING_TYPES.slice();
 
-  // A few types we simply stringify right now.
-  if (TOSTRING_TYPES.includes(whatType)) return what.toString();
+    if (opts.fnString)
+    {
+      this.strTypes.push(F);
+    }
 
-  if (isObj(what))
-  { // We support a few kinds of objects.
+    if (opts.errString)
+    {
+      this.strClass.push(Error);
+    }
 
-    // Any class instance that we can simply call `toString()` on, let's do that.
-    for (const aClass of TOSTRING_INSTANCES)
+    if (Array.isArray(opts.setCustom))
+    {
+      this.customFn = opts.setCustom.slice();
+    }
+    else if (typeof opts.setCustom === F)
     {
-      if (what instanceof aClass)
+      this.customFn = [];
+      opts.setCustom.call(this, this.customFn);
+    }
+    else
+    { // Start out with the global custom tests.
+      this.customFn = CUSTOM.slice();
+      if (Array.isArray(opts.addCustom))
+      {
+        this.customFn.push(...opts.addCustom);
+      }
+      else if (typeof opts.addCustom === F)
       {
-        return what.toString();
+        opts.addCustom.call(this, this.customFn);
       }
     }
 
-    // A few formatting helpers used below.
-    const classname = () => (addNew ? 'new ' : '') + what.constructor.name;
-    const construct = val => `${classname()}(${val})`;
-    const reconstruct = val => construct(stringify(val,recurse,addNew));
-    const arrayish = vals => reconstruct(Array.from(vals));
+  }
 
-    if (isTypedArray(what))
-    { // This one is pretty simple.
-      return construct(what.toString());
+  /**
+   * Stringify a JS value
+   * @param {*} what - Value to stringify
+   * @returns {string} A friendly representation of `what`
+   */
+  stringify(what, curd=0)
+  {
+    if (this.seenObjects.has(what))
+    { // Cached string for this subject already found.
+      return this.seenObjects.get(what);
     }
+
+    const recurse = curd < this.maxDepth;
+    const addNew  = curd < this.newDepth;
+    const whatType = typeof what;
+    const strFor = (str) => this._stringFor(what, str);
     
-    if (what instanceof Map)
-    {
-      return arrayish(what.entries());
+    for (const test of this.customFn)
+    { // If there are custom extensions, we check them first.
+      const ret = test.call(this, what, curd);
+      if (typeof ret === S)
+      { // The extension processed the item.
+        return strFor(ret);
+      }
     }
-    
-    if (what instanceof Set)
+
+    // A few types we simply stringify right now.
+    if (this.strTypes.includes(whatType)) 
     {
-      return arrayish(what.values());
+      return strFor(what.toString());
     }
 
-    if (what instanceof Error)
-    {
-      return `${what.name}(${JSON.stringify(what.message)})`;
+    if (!this.options.fnString && typeof what === F)
+    { // Simple format for functions
+      return strFor(what.name+'()');
     }
     
-    if (recurse)
-    { // Recursion mode enabled.
-      let out = '';
-      if (isArray(what))
-      { // Stringify an array.
-        out = '[';
-        out += what.map(item => stringify(item, recurse-1, addNew)).join(',');
-        out += ']';
-      }
-      else
-      { // Stringify a plain object.
-        out = '{';
-        function add(key, pre='')
+    if (isObj(what))
+    { // We support a few kinds of objects.
+
+      // Any class instance that we can simply call `toString()` on, let's do that.
+      for (const aClass of this.strClass)
+      {
+        if (what instanceof aClass)
         {
-          out += `${pre}${key}:${stringify(what[key], recurse-1, addNew)}`
+          return strFor(what.toString());
         }
-        const keys = Object.keys(what);
-        //console.debug("keys!", keys);
-        if (keys.length > 0)
-        { // Let's add the first key, then all subsequent keys.
-          add(keys.shift());    
-          for (const key of keys)
+      }
+
+      // A few formatting helpers used below.
+      const nameFor = (name=what.constructor.name) => 
+        (addNew ? 'new ' : '') + strFor(name);
+      
+      const container = (content, ps='[', pe=']') =>
+      {
+        let cstr = nameFor();
+        if (recurse)
+        {
+          cstr += ps;
+          if (!Array.isArray(content))
           {
-            add(key, ',');
+            content = Array.from(content);
           }
+          cstr += (content
+            .map(item => this.stringify(item, curd+1))
+            .join(','));
+          cstr += pe;
+        }
+        return cstr;
+      }
+      
+      if (isTypedArray(what))
+      { // This one is pretty simple.
+        if (this.options.typedContent)
+        {
+          return container(what.toString());
         }
-        out += '}';
+        return nameFor();
+      }
+
+      if (what instanceof Map)
+      {
+        return container(what.entries());
+      }
+      
+      if (what instanceof Set)
+      {
+        return container(what.values());
+      }
+
+      if (isArray(what))
+      {
+        return container(what);
+      }
+
+      if (!this.options.errString && what instanceof Error)
+      {
+        return nameFor(what.name)+'('+JSON.stringify(what.message)+')';
       }
-      return out;
+
+      // If we reached here, it's another kind of object entirely.
+      return container(Object.keys(what), '{', '}');
+
+    } // if isObj
+    
+    // If we reached here, there's no special methods, use JSON.
+    return JSON.stringify(what);
+  }
+
+  _stringFor(obj, str)
+  {
+    let count = 0;
+    if (this.seenDescrip.has(str))
+    {
+      count = this.seenDescrip.get(str);
     }
+    this.seenDescrip.set(str, ++count);
+    str += '#' + count.toString(16).padStart(3, '0');
+    this.seenObjects.set(obj, str);
+    return str;
+  }
 
-  } // if isObj
-  
-  // If we reached here, there's no special methods, use JSON.
-  return JSON.stringify(what);
-}
+  static addCustoms(...testFns)
+  {
+    for (let fn of testFns)
+    {
+      if (typeof fn === F)
+      {
+        CUSTOM.push(fn);
+      }
+      else
+      {
+        console.debug({fn, testFns});
+        throw new TypeError("Invalid custom stringify function");
+      }
+    }
+  }
 
-// Add a custom extension.
-def(stringify, '$extend',
-function(func, registration=false)
-{
-  if (typeof func === TYPES.F)
+  static registerCustoms(registerFn)
   {
-    if (registration)
-    { // Using the function to register custom behaviour.
-      func.call({stringify, TOSTRING_INSTANCES, TOSTRING_TYPES}, CUSTOM);
+    if (typeof registerFn === F)
+    {
+      registerFn.call(this, this);
     }
-    else 
-    { // The function is a custom test.
-      CUSTOM.push(func);
+    else
+    {
+      console.debug({registerFn});
+      throw new TypeError("Invalid custom registration function");
     }
   }
-});
+
+} // Stringify
+
+// Add some static properties for registerCustoms to use
+def(Stringify) 
+  ('strClass', {value: TOSTRING_INSTANCES})
+  ('strTypes', {value: TOSTRING_TYPES})
+  ('customFn', {value: CUSTOM})
+  ('DEFAULTS', {value: DEF})
 
 // Export it.
-module.exports = stringify;
+module.exports = {stringify, Stringify};