@lumjs/core 1.37.2 → 1.38.1

package/lib/obj/assignd.js

@@ -0,0 +1,39 @@
+"use strict";
+
+const {dfa} = require('./df');
+const {isObj,isNil} = require('../types');
+
+/**
+ * Copy properties into a target object.
+ * 
+ * Like Object.assign(), but it uses getOwnPropertyDescriptors() to get
+ * the properties to copy, and [dfa()]{@link module:@lumjs/core/obj.dfa} 
+ * to assign them.
+ * 
+ * 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
+ * @returns {object} the `target` object
+ * 
+ * @alias module:@lumjs/core/obj.assignd
+ */
+function assignd (target, ...sources)
+{
+  for (const src of sources)
+  {
+    if (isObj(src))
+    {
+      const descs = Object.getOwnPropertyDescriptors(src);
+      dfa(target, descs);
+    }
+    else if (!isNil(src))
+    {
+      console.error("Invalid assignd source", {src, sources, target});
+    }
+  }
+  return target;
+}
+
+module.exports = assignd;

package/lib/obj/df.js

@@ -0,0 +1,260 @@
+"use strict";
+
+const {doesDescriptor,needObj,needType,lazy,B,TYPES} = require('../types');
+
+const DEF_DESC = {configurable: true}
+
+const cp = Object.assign;
+const clone = (...args) => cp({}, ...args);
+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.
+ * 
+ * @param {object} desc - Descriptor object from df()
+ * @param {object} opts - Options from df();
+ * 
+ * Will be checked for default descriptor options in the
+ * case where those options were not explicitly defined
+ * in the descriptor object.
+ * 
+ * @param {boolean} [opts.configurable=true] configurable rule;
+ * this is the only option with a fallback default value.
+ * 
+ * @param {boolean} [opts.enumerable] enumerable rule
+ * 
+ * @param {boolean} [opts.writable] writable rule;
+ * only applies to data descriptors (ones with a `value` property),
+ * NOT to accessor descriptors.
+ * 
+ * @returns {object} `desc`
+ * @alias module:@lumjs/core/obj~descriptor
+ */
+function descriptor(desc, opts)
+{
+  opts = clone(DEF_DESC, opts);
+
+  const dps = ['configurable', 'enumerable'];
+  if (desc.value) dps.push('writable');
+
+  for (const dp of dps)
+  {
+    if (typeof desc[dp] !== B && typeof opts[dp] === B)
+    {
+      desc[dp] = opts[dp];
+    }
+  }
+
+  return desc;
+}
+
+/**
+ * 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.
+ * 
+ * This is the main one that all the rest use and is just a wrapper
+ * around Object.defineProperty() that simplifies its use a bit.
+ * 
+ * @param {(object|function)} obj - Target to define property in
+ * @param {(string|symbol)} name  - Property identifier
+ * @param {*} value - Value to assign
+ * 
+ * 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
+ * 
+ * See {@link module:@lumjs/core/obj~descriptor} for options that
+ * are used as descriptor defaults when assigning the property.
+ * 
+ * @param {?boolean} [opts.useDesc=null] Treat `value` is a descriptor?
+ * 
+ * If this is set to `true` then the `value` will be assumed to be a
+ * valid descriptor object; no tests will be done to confirm, so be sure!
+ * 
+ * If this is set to `false` then a descriptor of `{value}` will be created.
+ * Again, no tests will be done, so this is a way to assign properties that
+ * have `value`, `get`, or `set` properties in them.
+ * 
+ * If this is `null` (the default), then the `value` will be tested with
+ * [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
+ */
+function df(obj, name, value, opts={})
+{
+  const log = {obj,name,value,opts};
+  needObj(obj, {log, fun: true});
+  needType(TYPES.PROP, name, {log});
+
+  const useDesc = opts.useDesc ?? doesDescriptor(value);
+  const desc = descriptor((useDesc ? value : {value}), opts);
+  
+  return Object.defineProperty(obj, name, desc);
+}
+
+// Sub-export
+df(df, 'descriptor', descriptor);
+df(df, 'lazy',       lazy);
+
+/**
+ * A wrapper around df() that defines multiple properties at once.
+ * 
+ * @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
+ * 
+ * @returns {object} `obj`
+ * @alias module:@lumjs/core/obj.dfa
+ */
+function dfa(obj, values, opts)
+{
+  const log = {obj,values,opts};
+  needObj(values, {log});
+
+  for (const key in values)
+  {
+    df(obj, key, values[key], opts);
+  }
+
+  return obj;
+}
+
+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.
+ * 
+ * This actually creates closures for df(), dfa(), dfb(), and lazy().
+ * You can switch between them using magic 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:
+ * 
+ * - `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.
+ *   Uses Object.assign() to copy options from the specied object
+ *   to the internal options object from the original dfc() 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().
+ *   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.
+ * 
+ * @param {(object|function)} obj - Target to define property in;
+ * available as the `obj` magic property on the closures.
+ * 
+ * @param {object} [opts] Options - see df() for details;
+ * available as the `opts` magic property on the closures.
+ * 
+ * @returns {function} The `one` closure.
+ */
+function dfc(obj, opts={})
+{
+  const fnOne = function (name, value)
+  {
+    df(obj, name, value, opts);
+    return fnOne;
+  }
+
+  const fnAll = function (values) 
+  { 
+    dfa(obj, values, 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);
+    return fnLazy;
+  }
+
+  const ctx =   
+  {
+    obj:  {value: obj},
+    opts: {value: opts},
+    one:  {value: fnOne},
+    all:  {value: fnAll},
+    both: {value: fnBoth},
+    lazy: {value: fnLazy},
+    update: 
+    {
+      value()
+      {
+        cp(opts, ...arguments);
+        return this;
+      },
+    },
+    for:
+    {
+      value(newobj)
+      {
+        return dfc(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);
+
+module.exports = 
+{
+  df, dfa, dfb, dfc, lazy,
+}

package/lib/obj/index.js

@@ -4,9 +4,11 @@
  */
 
 const apply = require('./apply');
+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 {flip, flipKeyVal, flipMap} = require('./flip');
 const {getMethods,signatureOf,MethodFilter} = require('./getmethods');
 const getProperty = require('./getproperty');
@@ -24,7 +26,8 @@ const
 
 module.exports =
 {
-  cp, CLONE, clone, addClone, cloneIfLocked, lock, addLock,
+  assignd, cp, CLONE, clone, addClone, cloneIfLocked, lock, addLock,
+  df, dfa, dfb, dfc, lazy,
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
   getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,

package/lib/types/def.js

@@ -7,6 +7,14 @@ const clone = (...args) => Object.assign({}, ...args);
 /**
  * A wrapper around `Object.defineProperty()` with added flair!
  * 
+ * **FUTURE DEPRECATION**: this function will be deprecated in v1.19.0!
+ * It's gotten almost as convoluted as the old prop() method it replaced 
+ * from my original Nano.js libraries.
+ * 
+ * I have written new `obj.{df,dfa,dfc}` functions that will replace this
+ * function going forward. The related `types.lazy()` function will also
+ * be refactored to use the new functions, and moved to the `obj` module.
+ * 
  * @param {(object|function)} obj - The object to add a property to.
  * 
  * @param {?(string|symbol|boolean|object)} name 
@@ -73,8 +81,8 @@ const clone = (...args) => Object.assign({}, ...args);
  * directly, so any changes will be made on the original.
  * 
  * @param {boolean} [opts.configurable=true] Default `configurable` value 
- * @param {boolean} [opts.enumerable=false] Default `enumerable` value
- * @param {boolean} [opts.writable=false] Default `writable` value
+ * @param {boolean} [opts.enumerable] Default `enumerable` value
+ * @param {boolean} [opts.writable] Default `writable` value
  * 
  * Only used with *data descriptors* and will be ignored with
  * *accessor* descriptors.

package/lib/types/lazy.js

@@ -100,6 +100,12 @@ const {doesDescriptor} = require('./basics');
  * 
  * This is an extension of the [def()]{@link module:@lumjs/core/types.def} 
  * method, and indeed an alias called `def.lazy()` is also available.
+ * 
+ * IMPORTANT: In a later v1.18.x release, this will be refactored to use the
+ * [obj.df()]{@link module:@lumjs/core/obj.df} function that will replace
+ * def(). There's already an alias called `df.lazy()` available now.
+ * This will also be moved to the `obj` module, with a deprecated alias left
+ * in the `types` module for the duration of the 1.x lifecycle.
  *
  * @param {(object|function)} target - The object to add the property to.
  * 

package/lib/types/needs.js

@@ -2,44 +2,103 @@ const {F, S, B} = require('./js');
 const {isType, isa} = require('./isa');
 const {isObj, isComplex} = require('./basics');
 
+// Internal function used by both needObj and needType
+function needOpts(opts, fn, bopt, ons)
+{
+  if (isObj(opts))
+  {
+    if (opts.log)
+    { // Make a closure to handle the logging
+      const info = (opts.log === true) ? [opts] 
+        : (Array.isArray(opts.log) ? opts.log : [opts.log]);
+      opts.$log = () => console.error(...info);
+    }
+  }
+  else if (typeof opts === S)
+  { // A message was passed.
+    opts = 
+    {
+      msg: opts,
+    }
+    if (ons) ons(opts);
+  }
+  else if (typeof opts === B)
+  {
+    opts = {[bopt]: opts}
+  }
+  else
+  {
+    console.error('invalid options', {fn, opts});
+    opts = {};
+  }
+  return opts;
+}
+
+exports._needOptions = needOpts;
+
 /**
  * If a value is not an object, throw an error.
  * 
  * @param {*} v - The value we're testing.
- * @param {(boolean|string)} [allowFunc=false] - Also accept `function`?
+ * 
+ * @param {(object|boolean|string)} [opts] Options
+ * 
+ * - If this is a string, it will be used as `opts.msg`,
+ *   and `opts.fun` will be determined by the presence
+ *   of the word 'function' (case-insensitive) in the message.
+ * - If this is a boolean, it will be used as `opts.fun`,
+ *   and the default message will be used.
+ * 
+ * @param {boolean} [opts.fun=false] Also accept `function`?
  * 
  * By default this function uses `isObj()` to perform the
- * test. If `allowFunc` is `true` then it'll use `isComplex()` instead.
+ * test. If `opts.fun` is `true` then it'll use `isComplex()` instead.
+ * 
+ * @param {(object|string|true)} [opts.log] Optional debugging information.
+ * 
+ * This is a way to specify arguments to be sent to the
+ * console.error() method before the TypeError is thrown.
+ * 
+ * If this is an `Array` object, it will be used as positional arguments.
  * 
- * If this is a `string` then it'll be assigned to the `msg`
- * parameter, and `allowFunc` will be `true` if the word
- * `function` is found in the message, or `false` otherwise.
+ * If it is boolean `true`, the `opts` object itself will be used.
  * 
- * @param {string} [msg] A custom error message.
+ * Any other value will be used as the sole argument.
  * 
- * If not specified, a generic one will be used.
+ * @param {string} [opts.msg] The error message to use on failure.
+ * 
+ * If not specified, a simple default message will be used.
+ * 
+ * @param {?string} [msg=null] A positional version of `opts.msg`.
+ * 
+ * Setting `opts.msg` as a named option will take precedence 
+ * over this positional argument.
  * 
  * @throws {TypeError} If the type check failed.
  * @alias module:@lumjs/core/types.needObj
  */
-function needObj (v, allowFunc=false, msg=null)
+function needObj (v, opts={}, msg=null)
 {
-  if (typeof allowFunc === S)
-  { // A message was passed.
-    msg = allowFunc;
-    allowFunc = msg.toLowerCase().includes(F);
-  }
+  opts = needOpts(opts, 'needObj', 'fun', 
+    (o) => o.fun = o.msg.toLowerCase().includes(F));
 
-  const ok = allowFunc ? isComplex(v) : isObj(v);
+  const ok = opts.fun ? isComplex(v) : isObj(v);
 
   if (!ok)
   { // Did not pass the test.
-    if (typeof msg !== S)
+    if (typeof opts.msg === S)
+    {
+      msg = opts.msg;
+    }
+    else if (typeof msg !== S)
     { // Use a default message.
       msg = "Invalid object";
-      if (allowFunc)
+      if (opts.fun)
         msg += " or function";
     }
+
+    if (opts.$log) opts.$log();
+
     throw new TypeError(msg);
   }
 }
@@ -51,28 +110,42 @@ exports.needObj = needObj;
  * 
  * @param {string} type - The type name as per `isType()`.
  * @param {*} v - The value we're testing.
- * @param {string} [msg] A custom error message.
+ * 
+ * @param {(object|string)} [opts] Options
+ * 
+ * If this is a string, it will be used as `opts.msg`.
+ * 
+ * @param {string} [opts.msg] See needObj() for details.
+ * @param {(object|string|true)} [opts.log] See needObj() for details.
+ * 
+ * @param {?string} [msg=null] A positional version of `opts.msg`;
+ * handled the same was as needObj().
+ * 
  * @throws {TypeError} If the type check failed.
  * @alias module:@lumjs/core/types.needType
  */
-function needType (type, v, msg, unused)
+function needType (type, v, opts={}, msg=null)
 {
+  opts = needOpts(opts, 'needType', 'null');
+
+  if (typeof opts.null === B)
+  {
+    console.warn("needType(): 'allowNull' is no longer supported");
+  }
+
   if (!isType(type, v))
   {
-    if (typeof msg === B)
+    if (typeof opts.msg === S)
     {
-      console.warn("needType(): 'allowNull' is no longer supported");
-      if (typeof unused === S)
-      { // Compatibility with old code.
-        msg = unused;
-      }
+      msg = opts.msg;
     }
-
-    if (typeof msg !== S)
+    else if (typeof msg !== S)
     { // Use a default message.
       msg = `Invalid ${type} value`;
     }
 
+    if (opts.$log) opts.$log();
+
     throw new TypeError(msg);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.37.2",
+  "version": "1.38.1",
   "main": "lib/index.js",
   "exports": 
   {
@@ -17,6 +17,7 @@
     "./modules": "./lib/modules.js",
     "./obj": "./lib/obj/index.js",
     "./obj/cp": "./lib/obj/cp.js",
+    "./obj/df": "./lib/obj/df.js",
     "./observable": "./lib/observable.js",
     "./opt": "./lib/opt/index.js",
     "./opt/args": "./lib/opt/args.js",