@lumjs/core 1.37.1 → 1.38.0

package/lib/obj/assignd.js

@@ -0,0 +1,30 @@
+"use strict";
+
+const def = require('../types/def');
+
+/**
+ * Copy properties into a target object.
+ * 
+ * Like Object.assign(), but it uses getOwnPropertyDescriptors()
+ * to get the properties to copy and type.def() 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)
+  {
+    const descs = Object.getOwnPropertyDescriptors(src);
+    def(target, descs);
+  }
+  return target;
+}
+
+module.exports = assignd;

package/lib/obj/df.js

@@ -0,0 +1,213 @@
+"use strict";
+
+const {doesDescriptor,needObj,needType,lazy,B,TYPES} = require('../types');
+
+const DEF_DESC = {configurable: true}
+const DEF_OPTS = {autoDesc: 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
+ * 
+ * If `opts.autoDesc` is `true` and this is an `object` that passes the
+ * {@link module:@lumjs/core/types.doesDescriptor} test, it will be
+ * used as the template descriptor to assign the property.
+ * 
+ * In any other case, this will be used as the `value` property of
+ * a generated descriptor to be assigned.
+ * 
+ * @param {object} [opts] Options
+ * 
+ * @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});
+
+  opts = clone(DEF_OPTS, opts);
+
+  const desc = descriptor(((opts.autoDesc && doesDescriptor(value)) 
+    ? 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;
+}
+
+/**
+ * Build magic closures to define properties using a chained syntax.
+ * 
+ * This actually creates three closures, one around df(), another
+ * that wraps dfa(), and one that wraps the lazy() function.
+ * 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()
+ * - `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.
+ * - `next(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 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},
+    update: 
+    {
+      value()
+      {
+        cp(opts, ...arguments);
+        return this;
+      },
+    },
+    next:
+    {
+      value(newobj)
+      {
+        return dfc(newobj, opts);
+      },
+    },
+  }
+
+  dps(fnOne, ctx);
+  dps(fnAll, ctx);
+
+  return fnOne;
+}
+
+
+
+module.exports = 
+{
+  df, dfa, 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,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, dfc, lazy,
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
   getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,

package/lib/types/def.js

@@ -1,12 +1,20 @@
-// Thanks to CJS `require()` rules, recursive dependencies are possible.
-const unbound = require('./root').unbound;
-const {F, B} = require('./js');
-const {isObj, isNil, isProperty, doesDescriptor} = require('./basics');
+"use strict";
+
+const {F,B} = require('./js');
+const {isObj,isNil,isProperty,doesDescriptor} = require('./basics');
 const clone = (...args) => Object.assign({}, ...args);
 
 /**
  * A wrapper around `Object.defineProperty()` with added flair!
  * 
+ * FUTURE DEPRECATION: When I release @lumjs/core 2.0, this function
+ * will be deprecated! 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,
+ * although for the `2.x` lifetime an alias will remain in the `type` 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.
@@ -95,9 +103,10 @@ const clone = (...args) => Object.assign({}, ...args);
  */
 function def(obj, name, value, opts)
 {
-  const isBound // Is this a 'bound' def function?
-    = !unbound(this, true, true) 
-    && typeof this.bound === F;
+  const isBound
+    = isObj(this)
+    && typeof this.bound === F
+    && this.bound.$this === this;
 
   if (isNil(name) || typeof name === B)
   { // Binding of Isaac?

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 version 2.x, this will be refactored to use the new
+ * [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 an alias left
+ * in the `types` module for the duration of the 2.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/lib/types/root.js

@@ -1,5 +1,5 @@
 const {U} = require('./js');
-const {isNil,isArray} = require('./basics');
+const {isNil,isObj,isArray} = require('./basics');
 
 // «private»
 function no_root()
@@ -11,40 +11,81 @@ function no_root()
  * The global root object. Usually `globalThis` these days.
  * @alias module:@lumjs/core/types.root
  */
-const root = typeof globalThis !== U ? globalThis
-  : typeof global !== U ? global 
-  : typeof self !== U ? self 
-  : typeof window !== U ? window 
+const root 
+  = typeof globalThis !== U ? globalThis
+  : typeof global     !== U ? global 
+  : typeof self       !== U ? self 
+  : typeof window     !== U ? window 
   : no_root(); // Unlike the old way, we'll die if the environment is undetermined.
 
 exports.root = root;
 
-// A list of objects to be considered unbound globally.
+// A Set of objects to be considered unbound globally.
 const unboundObjects = require('./unbound/objects');
 
+// Default options for unbound()
+const UBDO =
+{
+  nil:   true,
+  root:  true,
+}
+
 /**
  * Pass `this` here to see if it is bound to an object.
  * 
- * Always considers `null` and `undefined` as unbound.
+ * @param {*} whatIsThis - The `this` from any context
+ * 
+ * @param {(boolean|object)} [opts] Options for advanced behaviours.
+ * 
+ * If this is boolean then it'll be used as `opts.root`;
+ * If it is an `Array` or `Set` it will be used as `opts.list`;
+ * Use just a plain object literal for specifying named options.
+ * 
+ * TODO: as of v2.0 this will no longer accept a boolean value
+ * as a shortcut to `opts.root`. That must be explicitly set.
+ * 
+ * @param {boolean} [opts.root=true] The global root is unbound?
+ * @param {boolean} [opts.nil=true] `null` and `undefined` are unbound?
+ * @param {(Array|Set)} [opts.list] A list of additional values that
+ * for the purposes of this test will be considered unbound.
+ * 
+ * @param {(Array|Set|boolean)} [list] A positional version of `opts.list`;
+ * ONLY used when the `opts` argument is boolean.
+ * 
+ * TODO: remove this argument as of v2.0
  * 
- * @param {*} whatIsThis - The `this` from any context.
- * @param {boolean} [rootIsUnbound=true] The global root is unbound. 
- * @param {(boolean|Array)} [areUnbound=false] A list of unbound objects.
- *   If the is `true` we use an global list that can register special
- *   internal objects. Otherwise an `Array` of unbound objects may be used.
  * @returns {boolean}
  * @alias module:@lumjs/core/types.unbound
  */
-function unbound(whatIsThis, rootIsUnbound=true, areUnbound=false)
+function unbound(whatIsThis, opts=true, list)
 {
-  if (areUnbound === true)
-  { // If areUnbound is true, we use the unboundObjects 
-    areUnbound = unboundObjects;
+  if (isObj(opts))
+  { // Merge in defaults
+    if (opts instanceof Set || isArray(opts))
+    { // A shortcut to the `list` property
+      list = opts;
+      opts = Object.assign({}, UBDO);
+    }
+    else
+    { // Regular options were specified.
+      opts = Object.assign({}, UBDO, {list}, opts);
+      list = opts.list;
+    }
+  }
+  else
+  { // Assume old positional arguments are being used
+    opts = Object.assign({}, UBDO, {root: opts});
+  }
+
+  if (list === true)
+  { // Internal special unbound values
+    list = unboundObjects;
   }
 
-  if (isNil(whatIsThis)) return true;
-  if (rootIsUnbound && whatIsThis === root) return true;
-  if (isArray(areUnbound) && areUnbound.includes(whatIsThis)) return true;
+  if (opts.nil && isNil(whatIsThis)) return true;
+  if (opts.root && whatIsThis === root) return true;
+  if (list instanceof Set && list.has(whatIsThis)) return true;
+  if (isArray(list) && list.includes(whatIsThis)) return true;
 
   // Nothing considered unbound.
   return false;

package/lib/types/unbound/extend.js

@@ -2,45 +2,41 @@
 
 const def = require('../def');
 const {needObj} = require('../needs');
-const removeFromArray = require('../../arrays/list').removeItems;
 const unboundObjects = require('./objects');
 
-// Adds a couple magic methods to the `unbound` function.
+// Adds a couple proxy methods to the `unbound` function.
 module.exports = function(unbound)
 {
   /**
    * Add an item to the unbound global objects list.
    * 
-   * @function
-   * @param {(object|function)} obj - The object to be considered unbound.
-   * @returns {boolean} Will be `false` if `obj` is already unbound.
-   * @throws {TypeError} If `obj` was neither an `object` nor a `function`.
-   * @name module:@lumjs/core/types.unbound.add
+   * @deprecated the global list is going away in 2.0
+   * @function module:@lumjs/core/types.unbound.add
+   * @param {(object|function)} obj - Value to be added
+   * @returns {boolean} always true as of v1.37.2
+   * @throws {TypeError} If `obj` was not a valid value
    */
   def(unbound, 'add', function (obj)
   {
     needObj(obj, true);
-    if (unbound(obj, true, true))
-    { // Item is already unbound.
-      return false;
-    }
-    // Add to list and we're done.
-    unboundObjects.push(obj);
+    if (unboundObjects.has(obj)) return false;
+    unboundObjects.add(obj);
     return true;
   });
 
   /**
    * Remove an item from the unbound global objects list.
    * 
-   * @function
-   * @param {(object|function)} obj - The object to be removed.
-   * @returns {boolean} Will be `false` if the item was not in the list.
-   * @throws {TypeError} If `obj` was neither an `object` nor a `function`.
-   * @name module:@lumjs/core/types.unbound.remove
+   * @deprecated the global list is going away in 2.0
+   * @function module:@lumjs/core/types.unbound.remove
+   * @param {(object|function)} obj - value to be removed
+   * @returns {boolean} always true as of v1.37.2
+   * @throws {TypeError} If `obj` was not a valid value
    */
   def(unbound, 'remove', function(obj)
   {
     needObj(obj, true);
-    return (removeFromArray(unboundObjects, obj) > 0);
+    unboundObjects.delete(obj);
+    return true;
   });
 }

package/lib/types/unbound/objects.js

@@ -1,2 +1,3 @@
 // Private storage, not exported outside the package.
-module.exports = [];
+// TODO: remove this in 2.0
+module.exports = new Set();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.37.1",
+  "version": "1.38.0",
   "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",