@lumjs/core 1.38.3 → 1.38.5

package/lib/obj/cycle.js

@@ -0,0 +1,182 @@
+/*
+    cycle.js
+    2021-05-31
+
+    Public Domain.
+
+    NO WARRANTY EXPRESSED OR IMPLIED. USE AT YOUR OWN RISK.
+
+    This code should be minified before deployment.
+    See https://www.crockford.com/jsmin.html
+
+    USE YOUR OWN COPY. IT IS EXTREMELY UNWISE TO LOAD CODE FROM SERVERS YOU DO
+    NOT CONTROL.
+*/
+
+// The file uses the WeakMap feature of ES6.
+
+/*jslint eval */
+
+/*property
+    $ref, decycle, forEach, get, indexOf, isArray, keys, length, push,
+    retrocycle, set, stringify, test
+*/
+
+if (typeof JSON.decycle !== "function") {
+    JSON.decycle = function decycle(object, replacer) {
+        "use strict";
+
+// Make a deep copy of an object or array, assuring that there is at most
+// one instance of each object or array in the resulting structure. The
+// duplicate references (which might be forming cycles) are replaced with
+// an object of the form
+
+//      {"$ref": PATH}
+
+// where the PATH is a JSONPath string that locates the first occurance.
+
+// So,
+
+//      var a = [];
+//      a[0] = a;
+//      return JSON.stringify(JSON.decycle(a));
+
+// produces the string '[{"$ref":"$"}]'.
+
+// If a replacer function is provided, then it will be called for each value.
+// A replacer function receives a value and returns a replacement value.
+
+// JSONPath is used to locate the unique object. $ indicates the top level of
+// the object or array. [NUMBER] or [STRING] indicates a child element or
+// property.
+
+        var objects = new WeakMap();     // object to path mappings
+
+        return (function derez(value, path) {
+
+// The derez function recurses through the object, producing the deep copy.
+
+            var old_path;   // The path of an earlier occurance of value
+            var nu;         // The new object or array
+
+// If a replacer function was provided, then call it to get a replacement value.
+
+            if (replacer !== undefined) {
+                value = replacer(value);
+            }
+
+// typeof null === "object", so go on if this value is really an object but not
+// one of the weird builtin objects.
+
+            if (
+                typeof value === "object"
+                && value !== null
+                && !(value instanceof Boolean)
+                && !(value instanceof Date)
+                && !(value instanceof Number)
+                && !(value instanceof RegExp)
+                && !(value instanceof String)
+            ) {
+
+// If the value is an object or array, look to see if we have already
+// encountered it. If so, return a {"$ref":PATH} object. This uses an
+// ES6 WeakMap.
+
+                old_path = objects.get(value);
+                if (old_path !== undefined) {
+                    return {$ref: old_path};
+                }
+
+// Otherwise, accumulate the unique value and its path.
+
+                objects.set(value, path);
+
+// If it is an array, replicate the array.
+
+                if (Array.isArray(value)) {
+                    nu = [];
+                    value.forEach(function (element, i) {
+                        nu[i] = derez(element, path + "[" + i + "]");
+                    });
+                } else {
+
+// If it is an object, replicate the object.
+
+                    nu = {};
+                    Object.keys(value).forEach(function (name) {
+                        nu[name] = derez(
+                            value[name],
+                            path + "[" + JSON.stringify(name) + "]"
+                        );
+                    });
+                }
+                return nu;
+            }
+            return value;
+        }(object, "$"));
+    };
+}
+
+
+if (typeof JSON.retrocycle !== "function") {
+    JSON.retrocycle = function retrocycle($) {
+        "use strict";
+
+// Restore an object that was reduced by decycle. Members whose values are
+// objects of the form
+//      {$ref: PATH}
+// are replaced with references to the value found by the PATH. This will
+// restore cycles. The object will be mutated.
+
+// The eval function is used to locate the values described by a PATH. The
+// root object is kept in a $ variable. A regular expression is used to
+// assure that the PATH is extremely well formed. The regexp contains nested
+// * quantifiers. That has been known to have extremely bad performance
+// problems on some browsers for very long strings. A PATH is expected to be
+// reasonably short. A PATH is allowed to belong to a very restricted subset of
+// Goessner's JSONPath.
+
+// So,
+//      var s = '[{"$ref":"$"}]';
+//      return JSON.retrocycle(JSON.parse(s));
+// produces an array containing a single element which is the array itself.
+
+        var px = /^\$(?:\[(?:\d+|"(?:[^\\"\u0000-\u001f]|\\(?:[\\"\/bfnrt]|u[0-9a-zA-Z]{4}))*")\])*$/;
+
+        (function rez(value) {
+
+// The rez function walks recursively through the object looking for $ref
+// properties. When it finds one that has a value that is a path, then it
+// replaces the $ref object with a reference to the value that is found by
+// the path.
+
+            if (value && typeof value === "object") {
+                if (Array.isArray(value)) {
+                    value.forEach(function (element, i) {
+                        if (typeof element === "object" && element !== null) {
+                            var path = element.$ref;
+                            if (typeof path === "string" && px.test(path)) {
+                                value[i] = eval(path);
+                            } else {
+                                rez(element);
+                            }
+                        }
+                    });
+                } else {
+                    Object.keys(value).forEach(function (name) {
+                        var item = value[name];
+                        if (typeof item === "object" && item !== null) {
+                            var path = item.$ref;
+                            if (typeof path === "string" && px.test(path)) {
+                                value[name] = eval(path);
+                            } else {
+                                rez(item);
+                            }
+                        }
+                    });
+                }
+            }
+        }($));
+        return $;
+    };
+}

package/lib/obj/cycle2.js

@@ -0,0 +1,122 @@
+'use strict';
+
+// TODO: replace cycle.js with this once its finished.
+
+const { isObj } = require('../types');
+
+const isCache = v => isObj(v) 
+  && typeof v.get === 'function' 
+  && typeof v.set === 'function';
+
+const isRegularObj = v => isObj(v)
+  && !(value instanceof Boolean)
+  && !(value instanceof Date)
+  && !(value instanceof Number)
+  && !(value instanceof RegExp)
+  && !(value instanceof String);
+
+const DEF_ARGS = ['key','value'];
+
+/**
+ * An extended version of Douglas Crockford's JSON.decycle() function.
+ * @param {object} object - Object to be decycled.
+ */
+function decycle(object, opts={})
+{
+  if (typeof opts === 'function')
+  {
+    opts = {
+      cache: new WeakMap(), 
+      replacer: opts,
+      replacerArgs: DEF_ARGS.slice(),
+      weak: true
+    };
+    opts.ctx = {opts}; // speaking of circular references...
+  }
+  else if (isObj(opts))
+  {
+    if (!isCache(opts.cache))
+    {
+      opts.cache = (opts.weak ?? true) ? new WeakMap() : new Map();
+    }
+    
+    if (!isObj(opts.ctx))
+    {
+      opts.ctx = {};
+    }
+
+    opts.ctx.opts = opts; // there it is again...
+
+    if (typeof opts.replacerArgs === 'string')
+    {
+      opts.replacerArgs = [opts.replacerArgs];
+    }
+    else if (!Array.isArray(opts.replacerArgs))
+    {
+      opts.replacerArgs = DEF_ARGS.slice();
+    }
+  }
+  else
+  {
+    throw new TypeError("invalid options");
+  }
+
+  const replacer = (typeof opts.replacer === 'function')
+    ? opts.replacer
+    : null;
+  
+  opts.ctx.target = object;
+  
+  return (function derez(value, path, key)
+  {
+    if (replacer)
+    {
+      let args = [], namedArgs = {key,value,opts,path};
+      namedArgs.named = namedArgs;
+
+      for (let arg of opts.replacerArgs)
+      {
+        if (arg in namedArgs)
+        {
+          args.push(namedArgs[arg]);
+        }
+      }
+
+      value = replacer.apply(opts.ctx, args);
+    }
+
+    if (isRegularObj(value))
+    {
+      let oldPath = opts.cache.get(value);
+      if (oldPath !== undefined)
+      {
+        return {$ref: oldPath};
+      }
+
+      opts.cache.set(value, path);
+
+      let nu;
+      if (Array.isArray(value))
+      {
+        nu = [];
+        value.forEach(function(elem, i) 
+        {
+          nu[i] = derez(elem, path+`[${i}]`, i);
+        });
+      }
+      else
+      {
+        nu = {};
+      }
+
+      return nu;
+    }
+    return value;
+
+  })(object, '$', '');
+}
+
+function retrocycle(object, opts={})
+{
+  // TODO: this
+}

package/lib/obj/index.js

@@ -3,7 +3,7 @@
  * @module @lumjs/core/obj
  */
 
-const apply = require('./apply');
+const {apply,ApplyInfo,ApplyOpts,ApplyWith} = require('./apply');
 const assignd = require('./assignd');
 const {copyAll,duplicateOne,duplicateAll} = require('./copyall');
 const copyProps = require('./copyprops');
@@ -18,6 +18,7 @@ const {mergeNested,syncNested} = require('./merge');
 const ns = require('./ns');
 const cp = require('./cp');
 const unlocked = require('./unlocked');
+const ownCount = require('./owncount');
 
 const 
 {
@@ -49,7 +50,6 @@ module.exports =
   mergeNested, syncNested, copyProps, copyAll, ns, nsFactory,
   getObjectPath, setObjectPath, delObjectPath, getNamespace, setNamespace,
   getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,
-  MethodFilter, apply, flip, flipKeyVal, flipMap, unlocked,
-  getPrototypesOf,
+  MethodFilter, flip, flipKeyVal, flipMap, unlocked, getPrototypesOf,
+  apply, ApplyInfo, ApplyOpts, ApplyWith, ownCount,
 }
-

package/lib/obj/ns/formats.js

@@ -0,0 +1,300 @@
+'use strict';
+
+/**
+ * A collection of path formats for the obj.ns* functions.
+ * @namespace module:@lumjs/core/obj.NS
+ */
+
+const {isObj} = require('../../types');
+
+/**
+ * A format object for the obj.ns* functions.
+ * @typedef {object} module:@lumjs/core/obj.NS~Format
+ * @prop {function} canParse - Can this parse a path string?
+ * @prop {function} canStringify - Can this stringify a path array?
+ * @prop {function} parse - Parse a path string into a path array.
+ * @prop {function} stringify - Stringify a path array into a path string.
+ */
+
+/**
+ * A test to see if a value is a format object.
+ * @param {mixed} v - Value to be tested
+ * @returns {boolean}
+ */
+const isFormat = v => isObj(v) 
+  && typeof v.canParse === 'function'
+  && typeof v.canStringify === 'function'
+  && typeof v.parse === 'function'
+  && typeof v.stringify === 'function';
+
+/**
+ * The simplest base format for the obj.ns* functions.
+ * 
+ * This one has NO escapes, and there is no way to include the
+ * delimiter character (which is a single `'.'` in this format).
+ * 
+ * Its methods are designed so that this can be used as a template
+ * for other simplistic formats, and indeed the Pointer format
+ * is an extension of this one.
+ * 
+ * Using it as a template is simple:
+ * 
+ * ```js
+ * const MyFormat = {
+ *   // Begin by composing Simple properties.
+ *   ...Simple,
+ * 
+ *   // Override any of the syntax properties.
+ *   hasEscapes: true,
+ *   join: '/',
+ *   prefix: '/',
+ * 
+ *   // Add some filter methods for parse() and stringify().
+ *   preParse(pathStr) {
+ *     // Do something to process path string and return it.
+ *   },
+ *   postParse(part, index) {
+ *     // Do something to process each path segment after parsing.
+ *     // This is used as an array.map() callback.
+ *   },
+ *   preStringify(part, index) {
+ *     // Process path segment before joining (an array.map() callback).
+ *   },
+ *   postStringify(pathStr) {
+ *     // Process path string after joining.
+ *   },
+ * }
+ * ```
+ * 
+ * NOTE: Due to this format having no prefix its canParse() test
+ * always returns true, therefore it must be the last in a list
+ * of formats to test for.
+ * 
+ * @alias module:@lumjs/core/obj.NS.Simple
+ */
+const Simple =
+{
+  hasEscapes: false,
+  join: '.',
+  prefix: '',
+  suffix: '',
+
+  /**
+   * Test if this format can handle a path string.
+   * 
+   * This version tests if the path string starts with `this.prefix`.
+   * @param {string} pathStr
+   * @returns {boolean}
+   */
+  canParse(pathStr)
+  {
+    return pathStr.startsWith(this.prefix);
+  },
+
+  /**
+   * Test if this format can stringify a path array.
+   * 
+   * This version will return true immediately if `this.hasEscapes` is true.
+   * 
+   * Assuming `this.hasEscapes` is false, this will look at every part 
+   * in the path array and check for the delimiter (`this.join`),
+   * and will return false if any part contains the delimiter.
+   * It returns true if none of the parts contain the delimiter.
+   */
+  canStringify(pathArray)
+  {
+    if (this.hasEscapes)
+    { // Joiner can be escaped.
+      return true;
+    }
+
+    for (let part of pathArray)
+    {
+      if (typeof part === 'string')
+      {
+        if (part.includes(this.join))
+        {
+          return false;
+        }
+      }
+    }
+    // No dots found, we're good.
+    return true;
+  },
+
+  /**
+   * Parse a path string into an array of path segments.
+   * @param {string} pathStr
+   * @returns {Array}
+   */
+  parse(pathStr)
+  {
+    if (typeof this.preParse === 'function')
+    {
+      pathStr = this.preParse(pathStr);
+    }
+
+    let array = pathStr.split(this.join);
+
+    return ((typeof this.postParse === 'function')
+      ? array.map((p,i,a) => this.postParse(p,i,a))
+      : array);
+  },
+
+  /**
+   * Stringify an array of path segments into a path string.
+   * @param {Array} pathArray
+   * @returns {string}
+   */
+  stringify(pathArray)
+  {
+    if (typeof this.preStringify === 'function')
+    {
+      pathArray = pathArray.map((p,i,a) => this.preStringify(p,i,a));
+    }
+
+    let pathStr = this.prefix + pathArray.join(this.join) + this.suffix;
+
+    return ((typeof this.postStringify === 'function')
+      ? this.postStringify(pathStr)
+      : pathStr);
+  },
+}
+
+/**
+ * An extension of NS.Simple implementing a subset of JSONPointer.
+ * 
+ * This supports the two basic escapes (`~0` for `'~'` and `~1` for `'/'`),
+ * and will be used by nsArray() if a path string starts with a `/` slash.
+ * 
+ * @alias module:@lumjs/core/obj.NS.Pointer
+ */
+const Pointer =
+{
+  ...Simple,
+
+  escParse: [['~1','/'],['~0','~']],
+  escString: [['~','~0'],['/','~1']],
+  hasEscapes: true,
+  join: '/',
+  prefix: '/',
+
+  preParse(pathStr)
+  {
+    let strip = this.prefix || this.join;
+    if (pathStr.startsWith(strip))
+    {
+      pathStr = pathStr.substring(strip.length);
+    }
+
+    strip = this.suffix || this.join;
+    if (pathStr.endsWith(strip))
+    {
+      pathStr = pathStr.substring(0, pathStr.length-strip.length);
+    }
+
+    return pathStr;
+  },
+
+  postParse(part)
+  {
+    for (let esc of this.escParse)
+    {
+      part = part.replaceAll(...esc);
+    }
+    return part;
+  },
+
+  preStringify(part)
+  {
+    for (let esc of this.escString)
+    {
+      part = part.replaceAll(...esc);
+    }
+    return part;    
+  },
+}
+
+const JP_PRE = /^\$[.\[]/;
+const JP_BLOCK = /\.?\[(["'])?(?<spath>.*?)\1\]/g;
+const D = '.';
+const ESCD = '\b_\b';
+const IS_INT = /^\d+$/;
+const SAFE_PATH = /^\w+$/;
+
+/**
+ * A namespace path format based on a minimal subset of JSONPath.
+ * 
+ * Obviously given the use-cases, this only supports single paths
+ * with no extra query features. Basically the following are valid:
+ * 
+ * - `$.hello.darkness.my_old_friend` (plain dotted paths).
+ * - `$["test.com"].expired` (a key with reserved characters in it).
+ * - `$.users[3]` (an array index).
+ *
+ * Anything more complicated than that isn't going to work.
+ *  
+ * @alias module:@lumjs/core/obj.NS.JSPath
+ */
+const JSPath =
+{
+  canParse: pathStr => pathStr.startsWith('$'),
+  
+  // TODO: look into JSONPath escapes.
+  canStringify(pathArray)
+  {
+    for (let part of pathArray)
+    {
+      if (typeof part === 'string')
+      {
+        if (part.includes('"'))
+        {
+          return false;
+        }
+      }
+    }
+    // No double-quotes found, we're good.
+    return true;
+  },
+
+  parse(pathStr)
+  {
+    pathStr = pathStr.replace(JP_PRE, '')
+      .replaceAll(JP_BLOCK, function(...args)
+      {
+        let {spath} = args[args.length-1] ?? '';
+        return D+spath.replaceAll(D, ESCD);
+      });
+    return pathStr.split(D).map((vpath) => vpath.replaceAll(ESCD, D));
+  },
+
+  stringify(pathArr)
+  {
+    let pathStr = '$';
+    for (let path of pathArr)
+    {
+      let isInt = IS_INT.test(path);
+      if (!isInt && SAFE_PATH.test(path))
+      { // Can use dotted syntax.
+        pathStr += '.' + path;
+      }
+      else
+      {
+        let blockPath = isInt
+          ? `[${path}]` 
+          : `["${path}"]`;
+        pathStr += blockPath;
+      }
+    }
+    return pathStr;
+  },
+}
+
+module.exports = 
+{
+  Defaults: [Pointer, JSPath, Simple],
+  isFormat, 
+  Simple, 
+  Pointer, 
+  JSPath,
+}