@lumjs/core 1.0.0 → 1.2.0

package/docs/changelogs/1.x.md

@@ -6,12 +6,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2022-08-10
+### Added
+- Moved the `array.powerset()` and `array.random()` methods from Lum.js v4 into `core.arrays`.
+- Added a new `core.context.isCommonJS()` method which is only used in certain circumstances.
+
+### Fixed 
+- A typo in one of the `package.json` exports.
+- Commented out a debugging line.
+
+## [1.1.1] - 2022-08-02
+### Fixed
+- A couple missing constants in some functions.
+
+## [1.1.0] - 2022-07-29
+### Added
+- `types.doesDescriptorTemplate()` method.
+- `obj.getProperty()` method (used to be in the `descriptors` sub-module.)
+### Changed
+- Tweaked documentation for:
+  - `obj.getObjectPath()`
+  - `obj.setObjectPath()`
+  - `obj.getNamespace()`
+  - `obj.setNamespace()`
+- Updated error messages in `obj.setObjectPath()`
+- Made `obj.setObjectPath()` use `types.doesDescriptorTemplate()` for validation of `opts.desc` option.
+- Changed `obj.getObjectPath()` and `obj.setObjectPath()` to support `function` parent objects.
+- Enhanced `types.stringify()` to support `RegExp` as well as supporting custom extensions down the road.
+
 ## [1.0.0] - 2022-07-27
 ### Changed
 - Initial *stable* release.
 - See [1.0-beta.md](1.0-beta.md) for the beta versions of `1.0`
 - See [lum.js](https://github.com/supernovus/lum.js) for the original library this is replacing.
 
-[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/supernovus/lum.core.js/compare/v1.1.1...v1.2.0
+[1.1.1]: https://github.com/supernovus/lum.core.js/compare/v1.1.0...v1.1.1
+[1.1.0]: https://github.com/supernovus/lum.core.js/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/supernovus/lum.core.js/releases/tag/v1.0.0
 

package/lib/arrays.js

@@ -1,6 +1,6 @@
 /**
  * Array helper functions.
- * @module module:@lumjs/core/arrays
+ * @module @lumjs/core/arrays
  */
 
 /** 
@@ -76,3 +76,36 @@ function removeItems(array, ...items)
 }
 
 exports.removeItems = removeItems;
+
+/**
+ * Return a Powerset of values in the array.
+ * @param {Array} array  The array to make the powerset from.
+ * @returns {Array}  The powerset.
+ * @alias module:@lumjs/core/arrays.powerset
+ */
+function powerset(array) 
+{
+  var ps = [[]];
+  for (var i=0; i < array.length; i++) 
+  {
+    // we modify the ps array in the next loop,
+    // so can't use the ps.length property directly in the loop condition.
+    var current_length = ps.length;
+    for (var j = 0; j < current_length; j++) 
+    {
+      ps.push(ps[j].concat(array[i]));
+    }
+  }
+  return ps;
+}
+
+/**
+ * Get a random element from an array.
+ * @param {Array} array  The array to get an item from.
+ * @returns {mixed}  The randomly selected item.
+ * @alias module:@lumjs/core/arrays.random
+ */
+function random(array)
+{
+  return array[Math.floor(Math.random()*array.length)];
+}

package/lib/context.js

@@ -28,18 +28,31 @@ const ctx = {root};
 const rootHas = what => typeof root[what] !== U;
 const cd = def(ctx, true);
 
+function isCommonJS(module)
+{
+  if (typeof module !== O || module === null) return false;
+  if (!ctx.hasRequire) return false;
+  if (!isComplex(module.exports)) return false;
+  if (typeof module.$lib === O && typeof module.$lib.$cached === O) 
+    return false; // It's our fake CommonJS emulation layer.
+  // Okay, all tests are okay.
+  return true;
+}
+
 cd('AMD', typeof define === F && define.amd)
   ('hasRequire', typeof require === F)
   ('hasExports', typeof exports !== U)
   ('hasModule', typeof module === O && module !== null)
-  ('CJS', ctx.hasRequire && ctx.hasModule && isComplex(module.exports))
+  ('CJS', isCommonJS(module)) // Detected value at load time in *this* module.
+  ('isCommonJS', isCommonJS)  // Dynamically detect via a module *reference*.
   ('isNode', ctx.CJS && ctx.hasExports)
   ('isWindow', !ctx.CJS && rootHas('window'))
   ('isWorker', !ctx.CJS && rootHas('WorkerGlobalScope'))
   ('isServiceWorker', !ctx.CJS && rootHas('ServiceWorkerGlobalScope'))
   ('isDedicatedWorker', !ctx.CJS && rootHas('DedicatedWorkerGlobalScope'))
   ('isSharedWorker', !ctx.CJS && rootHas('SharedWorkerGlobalScope'))
-  ('isBrowser', ctx.isWindow || ctx.isWorker);
+  ('isBrowser', ctx.isWindow || ctx.isWorker)
+  ;
 
 /**
  * See if a root-level name is defined.

package/lib/obj/getproperty.js

@@ -0,0 +1,38 @@
+const types = require('../types');
+const {isComplex,isObj} = types;
+
+/**
+ * Get a property descriptor.
+ * 
+ * This is like `Object.getOwnPropertyDescriptor`, except that method
+ * fails if the property is inhereted. This method will travel through
+ * the entire prototype chain until it finds the descriptor.
+ * 
+ * @param {object|function} obj - Object to find a property in.
+ * @param {string} prop - Name of the property we want the descriptor of.
+ * @param {mixed} [defval] The fallback value if no descriptor is found.  
+ * 
+ * @returns {mixed} - The descriptor if found, `defval` if not.
+ */
+function getProperty(obj, prop, defval)
+{
+  if (!isComplex(obj)) throw new TypeError("Target must be an object or function");
+  // Yeah it looks like an infinite loop, but it's not.
+  while (true)
+  {
+    const desc = Object.getOwnPropertyDescriptor(obj, prop);
+    if (isObj(desc))
+    { // Found it.
+      return desc;
+    }
+
+    // Didn't find it, so let's try the next object in the prototype chain.
+    obj = Object.getPrototypeOf(obj);
+    if (!isComplex(obj))
+    { // We've gone as far up the prototype chain as we can, bye now!
+      return defval;
+    }
+  }
+}
+
+module.exports = getProperty;

package/lib/obj/index.js

@@ -9,6 +9,7 @@ const {CLONE,clone,addClone,cloneIfLocked} = require('./clone');
 const {lock,addLock} = require('./lock');
 const {mergeNested,syncNested} = require('./merge');
 const ns = require('./ns');
+const getProperty = require('./getproperty');
 const 
 {
   getObjectPath,setObjectPath,
@@ -20,4 +21,5 @@ module.exports =
   CLONE, clone, addClone, cloneIfLocked, lock, addLock,
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
+  getProperty,
 }

package/lib/obj/ns.js

@@ -1,7 +1,9 @@
 // Import required bits here.
 const 
 {
-  B, root, isObj, needObj, def, nonEmptyArray, notNil
+  B, S,
+  root, isObj, needObj, def, nonEmptyArray, notNil,
+  doesDescriptorTemplate,
 } = require('../types');
 
 /**
@@ -75,16 +77,20 @@ exports.nsArray = nsArray;
 /**
  * Get a (nested) property from an object with a given path.
  *
- * @param {object} obj - Object we're looking in.
+ * @param {(object|function)} obj - Object we're looking in.
  * @param {(string|Array)} proppath - Property path we're looking for.
  *   Generally a string of dot (`.`) separated nested property names.
- * @param {object} [opts] TBD.
+ * @param {(object|boolean)} [opts] Options changing the behaviours.
+ *   If this is a `boolean` it's assumed to be the `opts.log` option.
+ * @param {boolean} [opts.log=false] Log errors for missing namespaces?
+ * @param {*} [opts.default] A default value if the namespace is not found.
+ * 
  * @return {*} The property if found, or `opts.default` if not.
  * @alias module:@lumjs/core/obj.getObjectPath
  */
 function getObjectPath(obj, proppath, opts={})
 {
-  needObj(obj);
+  needObj(obj, true);
 
   if (typeof opts === B)
     opts = {log: opts};
@@ -116,20 +122,32 @@ exports.getObjectPath = getObjectPath;
 /**
  * Create a nested property path if it does not exist.
  * 
- * @param {object} obj - Object the property path is for.
+ * @param {(object|function)} obj - Object the property path is for.
  * @param {(string|Array)} proppath - Property path to create.
- * @param {object} [opts] TBD.
- * @return {*} Generally the last object in the nested path.
- *   However the output may vary depending on the options.
+ * @param {object} [opts] Options changing the behaviours.
+ * @param {*} [opts.value] A value to assign to the last property path.
+ * @param {boolean} [opts.overwrite=false] Allow overwriting property paths.
+ *   Only applicable if `opts.value` was also specified.
+ * @param {object} [opts.desc] Descriptor rules for defining the properties.
+ *   Must NOT contain `value`, `get`, or `set` properties.
+ *   Only, `configurable`, `enumerable`, and `writable` are supported.
+ *   Will be ignored if `opts.assign` is `true`.
+ * @param {boolean} [opts.assign=false] Use direct assignment instead of `def()`.
+ * @param {boolean} [opts.returnThis=false] Return `this` variable.
+ * @param {boolean} [opts.returnObj=false] Return the `obj` parameter.
+ * @return {*} Generally the last object in the nested property paths.
+ *   Unless one of `opts.returnThis` or `opts.returnObj` was `true`.
  * @alias module:@lumjs/core/obj.setObjectPath
  */
 function setObjectPath(obj, proppath, opts={})
 {
-  needObj(obj); needObj(opts);
+  needObj(obj, true, 'obj parameter must be an object or function');
+  needObj(opts, 'opts parameter must be an object');
+
   proppath = nsArray(proppath);
 
   let assign;
-  if (isObj(opts.desc))
+  if (doesDescriptorTemplate(opts.desc))
   { // An explicit descriptor.
     assign = (o,p,v={}) => 
     {
@@ -151,7 +169,7 @@ function setObjectPath(obj, proppath, opts={})
   const nsc = proppath.length;
   const lastns = nsc - 1;
 
-  console.debug("setObjectPath", obj, proppath, opts, nsc, arguments);
+  //console.debug("setObjectPath", obj, proppath, opts, nsc, arguments);
 
   for (let n = 0; n < nsc; n++)
   {
@@ -218,8 +236,7 @@ exports.getNamespace = getNamespace;
  * 
  * @param {(string|Array)} proppath - Property path to create.
  * @param {object} [opts] See `setObjectPath()` for details.
- * @return {*} Generally the last object in the nested path.
- *   However the output may vary depending on the options.
+ * @return {*} See `setObjectPath()` for details.
  * @alias module:@lumjs/core/obj.setNamespace
  * @see module:@lumjs/core/obj.setObjectPath
  */

package/lib/opt.js

@@ -3,7 +3,7 @@
  * @module @lumjs/core/opt
  */
 
-const {U,needObj,needType} = require('./types');
+const {U,F,S,needObj,needType} = require('./types');
 
 /**
  * See if a value is *set*, and if not, return a default value.

package/lib/types/basics.js

@@ -104,16 +104,16 @@ function isProperty(v)
 }
 
 /**
- * See if an object can be used as a valid descriptor.
+ * See if an object can be used as a valid *descriptor*.
  * 
- * Basically in order to be considered a valid descriptor, 
+ * Basically in order to be considered a valid *descriptor*, 
  * one of the the following sets of rules must be true:
  * 
- *  - A Data Descriptor:
+ *  - A *Data descriptor*:
  *      - Has a `value` property.
  *      - Does not have a `get` property.
  *      - Does not have a `set` property.
- *  - An Accessor Descriptor:
+ *  - An *Accessor descriptor*:
  *      - Has a `get` and/or `set` property.
  *      - Does not have a `value` property.
  *      - Does not have a `writable` property.
@@ -145,10 +145,56 @@ function isProperty(v)
    return false;
  }
 
- // Now export those.
- module.exports =
- {
-  isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
-  nonEmptyArray, isArguments, isProperty, doesDescriptor,
- }
- 
+/**
+ * See if an object can be used as a valid *descriptor template*.
+ * 
+ * This is similar to `doesDescriptor`, except that a *template*
+ * **must not** contain `value`, `get` or `set` properties.
+ * 
+ * @param {object} obj - The object we are testing.
+ * @param {boolean} [accessor=false] Template is for an Accessor.
+ *   If this is `true` then the `writable` property will also be forbidden.
+ * @param {boolean} [strict=true] Only allow valid descriptor properties.
+ *   If this is `true` then **only** allow `configurable`, `enumerable`, and
+ *   conditionally `writable` (only if `accessor` is `false`.)
+ *   If this is `false` then any unknown properties will be ignored.
+ * 
+ * @returns {boolean} Is the object a valid descriptor template?
+ * @alias module:@lumjs/core/types.doesDescriptorTemplate
+ */
+function doesDescriptorTemplate(obj, accessor=false, strict=true)
+{
+  if (!isObj(obj)) return false;
+
+  // Get a list of enumerable properties in the object.
+  const props = Object.keys(obj);
+
+  if (strict)
+  { // Strict enforcement, only valid descriptor properties allowed.
+    const valid = ['configurable', 'enumerable'];
+    if (!accessor) valid.push('writable');
+    for (const prop of props)
+    {
+      if (!valid.includes(prop)) return false;
+    }
+  }
+  else
+  { // Loose enforcement mode, reject on forbidden properties only.
+    const forbidden = ['value','get','set'];
+    if (accessor) forbidden.push('writable');
+    for (const prop of props)
+    {
+      if (forbidden.includes(prop)) return false;
+    }
+  }
+
+  // No tests failed, this can be used as a template.
+  return true;
+}
+
+// Now export those.
+module.exports =
+{
+isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
+nonEmptyArray, isArguments, isProperty, doesDescriptor, doesDescriptorTemplate,
+}

package/lib/types/index.js

@@ -24,6 +24,7 @@ const
 {
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
   nonEmptyArray, isArguments, isProperty, doesDescriptor,
+  doesDescriptorTemplate,
 } = require('./basics');
 
 // Root namespace helpers.
@@ -49,6 +50,7 @@ module.exports =
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray, 
   nonEmptyArray, isArguments, isProperty, doesDescriptor, 
   isInstance, isType, isa, needObj, needType, needs, stringify,
+  doesDescriptorTemplate,
 }
 
 // Last but not least, this will be the module for TYPES.add()

package/lib/types/stringify.js

@@ -1,8 +1,11 @@
 // Get the extended type list.
 const TYPES = require('./typelist');
 const {isObj, isArray, isTypedArray} = require('./basics');
+const def = require('./def');
 
-const TOSTRING = [TYPES.F, TYPES.SY];
+const TOSTRING_TYPES = [TYPES.F, TYPES.SY];
+const TOSTRING_INSTANCES = [RegExp];
+const CUSTOM = [];
 
 /**
  * Stringify a Javascript value.
@@ -30,69 +33,110 @@ const TOSTRING = [TYPES.F, TYPES.SY];
 function stringify (what, recurse=1, addNew=false)
 {
   const whatType = typeof what;
-  if (TOSTRING.includes(whatType)) return what.toString();
 
-  // A few formatting helpers used below.
+  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;
+    }
+  }
 
-  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));
+  // A few types we simply stringify right now.
+  if (TOSTRING_TYPES.includes(whatType)) return what.toString();
 
-  if (isTypedArray(what))
-  { // This one is pretty simple.
-    return construct(what.toString());
-  }
-  
-  if (what instanceof Map)
-  {
-    return arrayish(what.entries());
-  }
-  
-  if (what instanceof Set)
-  {
-    return arrayish(what.values());
-  }
+  if (isObj(what))
+  { // We support a few kinds of objects.
 
-  if (what instanceof Error)
-  {
-    return construct(what.message);
-  }
-  
-  if (recurse && isObj(what))
-  { // 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='')
+    // Any class instance that we can simply call `toString()` on, let's do that.
+    for (const aClass of TOSTRING_INSTANCES)
+    {
+      if (what instanceof aClass)
       {
-        out += `${pre}${key}:${stringify(what[key], recurse-1, addNew)}`
+        return 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 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());
+    }
+    
+    if (what instanceof Map)
+    {
+      return arrayish(what.entries());
+    }
+    
+    if (what instanceof Set)
+    {
+      return arrayish(what.values());
+    }
+
+    if (what instanceof Error)
+    {
+      return `${what.name}(${JSON.stringify(what.message)})`;
+    }
+    
+    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='')
         {
-          add(key, ',');
+          out += `${pre}${key}:${stringify(what[key], recurse-1, addNew)}`
+        }
+        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)
+          {
+            add(key, ',');
+          }
         }
+        out += '}';
       }
-      out += '}';
+      return out;
     }
-    return out;
-  }
-  else
-  { // If we reached here, there's no special methods, use JSON.
-    return JSON.stringify(what);
-  }
+
+  } // if isObj
+  
+  // If we reached here, there's no special methods, use JSON.
+  return JSON.stringify(what);
 }
 
+// Add a custom extension.
+def(stringify, '$extend',
+function(func, registration=false)
+{
+  if (typeof func === TYPES.F)
+  {
+    if (registration)
+    { // Using the function to register custom behaviour.
+      func.call({stringify, TOSTRING_INSTANCES, TOSTRING_TYPES}, CUSTOM);
+    }
+    else 
+    { // The function is a custom test.
+      CUSTOM.push(func);
+    }
+  }
+});
+
+// Export it.
 module.exports = stringify;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "main": "lib/index.js",
   "exports":
   {
@@ -12,7 +12,7 @@
     "./flags": "./lib/flags.js",
     "./obj": "./lib/obj/index.js",
     "./opt": "./lib/opt.js",
-    "./modules": "./lib/moduless.js",
+    "./modules": "./lib/modules.js",
     "./meta": "./lib/meta.js",
     "./enum": "./lib/enum.js",
     "./observable": "./lib/observable.js",
@@ -26,8 +26,7 @@
   },
   "devDependencies":
   {
-    "@lumjs/tests": "^1.3.0",
-    "jsdoc": "^3.6.10"
+    "@lumjs/tests": "^1.3.0"
   },
   "scripts":
   {