@lumjs/core 1.38.1 → 1.38.3

package/lib/obj/assignd.js

@@ -1,7 +1,10 @@
 "use strict";
 
-const {dfa} = require('./df');
-const {isObj,isNil} = require('../types');
+const {df,dfa} = require('./df');
+const {isObj,isIterable,isNil} = require('../types');
+const cp = Object.assign;
+const ASSIGND_OPTS = Symbol('@lumjs/core/obj.assignd~opts');
+const DEF_OPTS = {force: 'configurable'};
 
 /**
  * Copy properties into a target object.
@@ -13,27 +16,71 @@ const {isObj,isNil} = require('../types');
  * Basically a super simple, non-recursive replacement for my copyProps()
  * and cp() functions that were overly complex and tried to do way too much.
  * 
- * @param {object} target - The target object to copy properties into
- * @param {...object} sources - Source objects to copy properties from
+ * The default options used by this function when calling dfa() are:
+ * 
+ * `{configurable: true, force: 'configurable'}`
+ * 
+ * Which simply means that by default the `configurable` descriptor property
+ * will be forced to `true` on the properties assigned, allowing them to be
+ * re-assigned later. You can override the defaults using special properties
+ * in either the target or source objects.
+ * 
+ * @param {object} target - The target object to copy properties into.
+ * 
+ * If you create a `target[assignd.OPTS]` property as an object, it may be
+ * used to set any of the options supported by the dfa() function.
+ * The options specified here take priority over the defaults shown above,
+ * and will be used for all sources.
+ * 
+ * In addition to the options supported by dfa(), an additional `skip`
+ * option may be specified, it should be an array of property keys that
+ * SHOULD NOT be overwritten in the target. The `assignd.OPTS` property
+ * is always implicitly in the skip list and will never be overridden.
+ * 
+ * @param {...object} sources - Source objects to copy properties from.
+ * 
+ * If you create a `source[assignd.OPTS]` property as an object, it may be
+ * used to set any of the options supported by the dfa() function.
+ * The options specified here take priority over any set in the `target`,
+ * and only apply to that specific source object.
+ * 
+ * The options assigned to source objects do NOT support the `skip` option.
+ * 
  * @returns {object} the `target` object
  * 
  * @alias module:@lumjs/core/obj.assignd
  */
 function assignd (target, ...sources)
 {
+  const skips = [ASSIGND_OPTS];
+  const topts = cp({}, DEF_OPTS, target[ASSIGND_OPTS]);
+
+  if (isIterable(topts.skip))
+  {
+    skips.push(...topts.skip);
+  }
+
   for (const src of sources)
   {
     if (isObj(src))
     {
+      const sopts = cp({}, topts, src[ASSIGND_OPTS]);
       const descs = Object.getOwnPropertyDescriptors(src);
-      dfa(target, descs);
+      for (let skip of skips)
+      {
+        delete descs[skip];
+      }
+      dfa(target, descs, sopts);
     }
     else if (!isNil(src))
     {
       console.error("Invalid assignd source", {src, sources, target});
     }
   }
+
   return target;
 }
 
+df(assignd, 'OPTS', {value: ASSIGND_OPTS});
+
 module.exports = assignd;

package/lib/obj/df.js

@@ -1,6 +1,8 @@
 "use strict";
 
-const {doesDescriptor,needObj,needType,lazy,B,TYPES} = require('../types');
+const {B,F,S,doesDescriptor} = require('../types/basics');
+const {needObj,needType} = require('../types/needs');
+const TYPES = require('../types/typelist');
 
 const DEF_DESC = {configurable: true}
 
@@ -11,8 +13,8 @@ const dps = Object.defineProperties;
 /**
  * Handle populating descriptor objects for df() and family.
  * 
- * Exported as `obj.df.descriptor`, but since jsdoc doesn't like
- * properties attached to functions, I've listed it as internal.
+ * Alias: `df.descriptor()`
+ * @alias module:@lumjs/core/obj~descriptor
  * 
  * @param {object} desc - Descriptor object from df()
  * @param {object} opts - Options from df();
@@ -30,8 +32,17 @@ const dps = Object.defineProperties;
  * only applies to data descriptors (ones with a `value` property),
  * NOT to accessor descriptors.
  * 
+ * @param {(boolean|string|string[])} [opts.force=false] Force `opts` values?
+ * 
+ * If this is set to true, then any descriptor property specified in `opts`
+ * will be set on `desc` regardless as to if it already has that property.
+ * That includes the fallback `configurable` property value.
+ * 
+ * You may also set this to the name(s) of the properties which should
+ * be forced (any not in the list will only be assigned if not in the
+ * `desc` object already).
+ * 
  * @returns {object} `desc`
- * @alias module:@lumjs/core/obj~descriptor
  */
 function descriptor(desc, opts)
 {
@@ -40,9 +51,24 @@ function descriptor(desc, opts)
   const dps = ['configurable', 'enumerable'];
   if (desc.value) dps.push('writable');
 
+  let force;
+  if (!opts.force)
+  { // force NONE
+    force = [];
+  }
+  else if (opts.force === true)
+  { // force ALL
+    force = dps; 
+  }
+  else
+  { // force selected
+    force = Array.isArray(opts.force) ? opts.force : [opts.force];
+  }
+
   for (const dp of dps)
   {
-    if (typeof desc[dp] !== B && typeof opts[dp] === B)
+    if (typeof opts[dp] === B 
+      && (force.includes(dp) || typeof desc[dp] !== B))
     {
       desc[dp] = opts[dp];
     }
@@ -52,14 +78,10 @@ function descriptor(desc, opts)
 }
 
 /**
- * A replacement for `types.def()`, but MUCH simpler.
- *
- * Instead of one function where every argument has several different
- * purposes depending on the type of value, there are now a bunch
- * of functions, each one with a single purpose, and a single signature.
+ * A wrapper around Object.defineProperty() which simplifies things a bit.
  * 
- * This is the main one that all the rest use and is just a wrapper
- * around Object.defineProperty() that simplifies its use a bit.
+ * Alias: `df.one`
+ * @alias module:@lumjs/core/obj.df
  * 
  * @param {(object|function)} obj - Target to define property in
  * @param {(string|symbol)} name  - Property identifier
@@ -68,9 +90,15 @@ function descriptor(desc, opts)
  * See `opts.useDesc` for how this value is handled in regards to
  * whether it is treated as a property descriptor or a plain data value.
  * 
- * @param {object} [opts] Options
+ * @param {(object|function|boolean)} [opts] Options
  * 
- * See {@link module:@lumjs/core/obj~descriptor} for options that
+ * If this is a boolean, it will be used as `opts.useDesc`.
+ * 
+ * If both `value` and this are functions, then they will be used
+ * as the `get` and `set` descriptor values and `opts.useDesc` will
+ * be set to `true`.
+ * 
+ * See {@link module:@lumjs/core/obj~descriptor} for more options that
  * are used as descriptor defaults when assigning the property.
  * 
  * @param {?boolean} [opts.useDesc=null] Treat `value` is a descriptor?
@@ -86,8 +114,7 @@ function descriptor(desc, opts)
  * [doesDescriptor()]{@link module:@lumjs/core/types.doesDescriptor}, 
  * and that will determine if the value is treated as a descriptor or not.
  * 
- * @returns {object} `obj`
- * @alias module:@lumjs/core/obj.df
+ * @returns {(object|function)} `obj`
  */
 function df(obj, name, value, opts={})
 {
@@ -95,26 +122,37 @@ function df(obj, name, value, opts={})
   needObj(obj, {log, fun: true});
   needType(TYPES.PROP, name, {log});
 
+  if (typeof opts === B)
+  {
+    opts = {useDesc: opts};
+  }
+  else if (typeof opts === F && typeof value === F)
+  {
+    value = {get: value, set: opts};
+    opts = {useDesc: true};
+  }
+
   const useDesc = opts.useDesc ?? doesDescriptor(value);
   const desc = descriptor((useDesc ? value : {value}), opts);
   
   return Object.defineProperty(obj, name, desc);
 }
 
-// Sub-export
+df(df, 'one', df);
 df(df, 'descriptor', descriptor);
-df(df, 'lazy',       lazy);
 
 /**
  * A wrapper around df() that defines multiple properties at once.
+ *
+ * Alias: `df.all`
+ * @alias module:@lumjs/core/obj.dfa
  * 
  * @param {(object|function)} obj - Target to define property in
  * @param {object} values 
  * All string-keyed enumerable properties will be passed to df()
- * @param {object} [opts] See df() for details
+ * @param {(object|boolean)} [opts] See df() for details
  * 
- * @returns {object} `obj`
- * @alias module:@lumjs/core/obj.dfa
+ * @returns {(object|function)} `obj`
  */
 function dfa(obj, values, opts)
 {
@@ -132,55 +170,38 @@ function dfa(obj, values, opts)
 df(df, 'all', dfa);
 
 /**
- * A wrapper around df() that defines an *accessor property* with 
- * BOTH a getter and a setter specified explicitly.
- * 
- * @param {(object|function)} obj - Target to define property in
- * @param {(string|symbol)} name - Property identifier
- * @param {function} getter - Getter function
- * @param {function} setter - Setter function
- * @param {object} [opts] Options
- * 
- * The actual options passed to df() will be a clone, with the
- * `useDesc` option explicitly forced to `true`.
- * 
- */
-function dfb(obj, name, getter, setter, opts)
-{
-  const log = {obj,name,getter,setter,opts};
-  opts = clone(opts, {useDesc: true});
-  return df(obj, name, {get: getter, set: setter}, opts);
-}
-
-df(df, 'both', dfb);
-
-/**
- * Build magic closures to define properties using a chained syntax.
+ * Build closures to define properties using a chained syntax.
  * 
- * This actually creates closures for df(), dfa(), dfb(), and lazy().
- * You can switch between them using magic properties.
+ * This creates closures for df(), dfa(), and lazy().
+ * You can switch between them using special properties.
  * 
  * The closures when called will pass their arguments to the function
  * they are wrapping, and in a bit of brain-melting recursion, the
  * return value from each closure is the closure itself.
  * 
- * Magic Properties that are added to both closures:
+ * Special Properties that are added to all of the closures:
  * 
- * - `one(name, value)` → A closure that wraps df()
- * - `all(values)`      → A closure that wraps dfa()
- * - `both(name, g, s)` → A closure that wraps dfb()
- * - `lazy(name, func)` → A closure that wraps lazy()
- * - `update(opts)`     → Update the options used by the closures.
+ * - `one(name, val, [set])` → A closure that wraps df();
+ *   `set` (setter function) is only used if `val` is a getter function.
+ * - `all(values)`           → A closure that wraps dfa()
+ * - `lazy(name, func)`      → A closure that wraps lazy()
+ * - `update(opts)`          → Update the options used by the closures.
  *   Uses Object.assign() to copy options from the specied object
- *   to the internal options object from the original dfc() call.
+ *   to the internal options object from the original dfor() call.
  *   This is a method call, NOT a closure function.
- * - `opts`             → The actual options object used by the closures.
- * - `obj`              → The target object used by the closures.
- * - `for(obj)`         → A wrapper method that will call dfc().
+ * - `opts`                  → The options object used by the closures.
+ * - `obj`                   → The target object used by the closures.
+ * - `for(obj)`              → A wrapper method that will call dfor().
  *   When using this method, a *new set of closures* will be created,
  *   with the current options, but a new target object.
  *   If you use this in a chained statement, any calls after this
  *   will be using the new closures rather than the original ones.
+ * - `prev`                  → The previous closure(s) from which
+ *   the chained `for()` method was called. If there is no previous
+ *   set of closures, then this will return the current closure.
+ * 
+ * Alias: `df.for()`
+ * @alias module:@lumjs/core/obj.dfor
  * 
  * @param {(object|function)} obj - Target to define property in;
  * available as the `obj` magic property on the closures.
@@ -188,12 +209,22 @@ df(df, 'both', dfb);
  * @param {object} [opts] Options - see df() for details;
  * available as the `opts` magic property on the closures.
  * 
+ * @param {?function} [prev=null] INTERNAL USE ONLY;
+ * if the `for()` wrapper method is used in a closure,
+ * that closure will be passed here, which makes returning
+ * to the previous closure possible.
+ * 
  * @returns {function} The `one` closure.
  */
-function dfc(obj, opts={})
+function dfor(obj, opts={}, prev=null)
 {
-  const fnOne = function (name, value)
+  const fnOne = function (name, value, setter)
   {
+    if (typeof setter === F && typeof value === F)
+    {
+      value = {get: value, set: setter}
+      opts = clone(opts, {useDesc: true});
+    }
     df(obj, name, value, opts);
     return fnOne;
   }
@@ -204,12 +235,6 @@ function dfc(obj, opts={})
     return fnAll;
   }
 
-  const fnBoth = function (name, getter, setter)
-  {
-    dfb(obj, name, getter, setter, opts);
-    return fnBoth;
-  }
-
   const fnLazy = function (name, initfunc)
   {
     lazy(obj, name, initfunc, opts);
@@ -222,8 +247,8 @@ function dfc(obj, opts={})
     opts: {value: opts},
     one:  {value: fnOne},
     all:  {value: fnAll},
-    both: {value: fnBoth},
     lazy: {value: fnLazy},
+    prev: {get() { return prev ?? this }},
     update: 
     {
       value()
@@ -236,25 +261,147 @@ function dfc(obj, opts={})
     {
       value(newobj)
       {
-        return dfc(newobj, opts);
+
+        return dfor(newobj, opts);
       },
     },
   }
 
-  // Quick alias
-  ctx.next = ctx.for;
-
   dps(fnOne,  ctx);
   dps(fnAll,  ctx);
-  dps(fnBoth, ctx);
   dps(fnLazy, ctx);
 
   return fnOne;
 }
 
-df(df, 'for', dfc);
+df(df, 'for', dfor);
 
-module.exports = 
+/**
+ * Build a lazy initializer property.
+ * 
+ * This builds an *accessor* property that will replace itself
+ * with a initialized property, the value of which is obtained from
+ * a supplied initialization function. Any subsequent use of the
+ * property will obviously be using the initialized property directly.
+ * 
+ * The general purpose is if there is a property that requires
+ * a fairly intensive load time, or requires a large library that
+ * you may not always *need* for basic things, you can use this
+ * to ensure that the property is only initialized when needed.
+ * 
+ * Alias: `df.lazy`
+ * @alias module:@lumjs/core/obj.lazy
+ *
+ * @param {(object|function)} target - The object to add the property to.
+ * 
+ * @param {string} name - The name of the property to add.
+ * 
+ * @param {module:@lumjs/core/obj~LazyGetter} initfunc 
+ * The function to initialize the property.
+ * 
+ * This will normally only ever be called the first time the property
+ * is accessed in a *read* operation. The return value from this
+ * will be assigned to the property using `def()`, replacing the
+ * lazy accessor property.
+ * 
+ * @param {object} [opts] Options to customize behavior.
+ * 
+ * @param {module:@lumjs/core/obj~LazySetter} [opts.set]
+ * A function to handle assignment attempts.
+ * 
+ * This obviously only applies to the *lazy accessor* property,
+ * and will have no affect once the property has been replaced
+ * by its initialized value.
+ * 
+ * @param {boolean} [opts.enumerable=false] Is the property enumerable?
+ * 
+ * This applies to the *lazy accessor* property only.
+ * You can set custom descriptor rules in the `initfunc`
+ * if you need them on the initialized property.
+ * 
+ * @param {?boolean} [opts.assign] The *default* value for the `assign` property
+ * in the [LazyDef]{@link module:@lumjs/core/obj~LazyDef} object.
+ * 
+ * @param {*} [opts.df] The *default* value for the `df`/`def` property in
+ * the [LazyDef]{@link module:@lumjs/core/obj~LazyDef} object.
+ * 
+ * @param {*} [opts.def] Alias of `opts.df` for compatibility.
+ *
+ * @returns {(object|function)} The `target` argument
+ */
+function lazy(target, name, initfunc, opts={})
 {
-  df, dfa, dfb, dfc, lazy,
+  let log = {target, name, initfunc, opts};
+  needObj(target, {log, fun: true});
+  needType(TYPES.PROP, name, {log});
+  needType(F, initfunc, {log});
+  needObj(opts, {log});
+
+  // The `this` object for the functions.
+  const ctx = 
+  { 
+    name, 
+    target, 
+    opts, 
+    arguments,
+    assign: opts.assign,
+    df: opts.df ?? opts.def ?? {},
+  }
+  ctx.def = ctx.df;
+
+  // The descriptor for the lazy accessor.
+  const desc = 
+  {
+    configurable: true, 
+    enumerable: opts.enumerable ?? false,
+  };
+
+  // Replace the property if rules are correct.
+  const defval = function(value)
+  {
+    if (ctx.assign ?? value !== undefined)
+    { // Replace the lazy accessor with the returned value.
+      df(target, name, value, ctx.df);
+      // Now return the newly assigned value.
+      return target[name];
+    }
+    else if (doesDescriptor(value))
+    { // A descriptor was returned, extract the real value.
+      if (typeof value.get === F)
+      {
+        return value.get();
+      }
+      else 
+      {
+        return value.value;
+      }
+    }
+    else 
+    { // Just return the original value.
+      return value;
+    }
+  }
+
+  desc.get = function()
+  { 
+    return defval(initfunc.call(ctx,ctx));
+  }
+
+  if (typeof opts.set === F)
+  { // We want to assign a lazy setter as well.
+    desc.set = function(value)
+    {
+      defval(opts.set.call(ctx,value,ctx));
+    }
+  }
+
+  // Assign the lazy accessor property.
+  return df(target, name, desc);
 }
+
+df(df, 'lazy', lazy);
+df(lazy, 'df', df);
+// TODO: remove this for v2.x
+lazy(lazy, 'def', () => require('../types/def'));
+
+module.exports = {descriptor, df, dfa, dfor, lazy}

package/lib/obj/getprotos.js

@@ -0,0 +1,25 @@
+'use strict';
+
+function getPrototypesOf(obj)
+{ 
+  let chain = [];
+  while (true) 
+  {
+    if (obj && typeof obj === 'object') 
+    {
+      let objClass = obj.constructor;
+      if (!chain.includes(objClass))
+      {
+        chain.push(objClass);
+      }
+      obj = getProto(obj);
+    }
+    else 
+    {
+      break;
+    }
+  }
+  return chain;
+}
+
+module.exports = getPrototypesOf;

package/lib/obj/index.js

@@ -8,10 +8,11 @@ const assignd = require('./assignd');
 const {copyAll,duplicateOne,duplicateAll} = require('./copyall');
 const copyProps = require('./copyprops');
 const {CLONE,clone,addClone,cloneIfLocked} = require('./clone');
-const {df,dfa,dfb,dfc,lazy} = require('./df');
+const {df,dfa,dfor,lazy} = require('./df');
 const {flip, flipKeyVal, flipMap} = require('./flip');
 const {getMethods,signatureOf,MethodFilter} = require('./getmethods');
 const getProperty = require('./getproperty');
+const getPrototypesOf = require('./getprotos');
 const {lock,addLock} = require('./lock');
 const {mergeNested,syncNested} = require('./merge');
 const ns = require('./ns');
@@ -20,16 +21,35 @@ const unlocked = require('./unlocked');
 
 const 
 {
-  getObjectPath,setObjectPath,
-  getNamespace,setNamespace,
+  getObjectPath,setObjectPath,delObjectPath,
+  getNamespace,setNamespace,nsFactory,
 } = ns;
 
+/**
+ * Create a new object with a `null` prototype.
+ * 
+ * @alias module:@lumjs/core/obj.discrete
+ * 
+ * Unlike regular objects, discrete objects won't have any
+ * of the usual meta-programming methods or properties.
+ * Not sure why you'd want that, but anyway, here you go.
+ * 
+ * @param {object} [props] Optional properties to define in
+ * the new object. Uses the same format as Object.defineProperties()
+ * 
+ * @returns {object}
+ */
+const discrete = (props) => Object.create(null, props);
+
+// TODO: reorder the following alphabetically, for sanity sake...
 module.exports =
 {
   assignd, cp, CLONE, clone, addClone, cloneIfLocked, lock, addLock,
-  df, dfa, dfb, dfc, lazy,
-  mergeNested, syncNested, copyProps, copyAll, ns,
-  getObjectPath, setObjectPath, getNamespace, setNamespace,
+  df, dfa, dfor, lazy, discrete,
+  mergeNested, syncNested, copyProps, copyAll, ns, nsFactory,
+  getObjectPath, setObjectPath, delObjectPath, getNamespace, setNamespace,
   getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,
   MethodFilter, apply, flip, flipKeyVal, flipMap, unlocked,
+  getPrototypesOf,
 }
+