@lumjs/core 1.38.7 → 1.39.0

package/lib/meta.js

@@ -4,6 +4,12 @@
  */
 'use strict';
 
+const { getOwnKeys, keyName } = require('./obj/keys');
+const { isIterable, isObj } = require('./types/basics');
+
+const cp = Object.assign;
+const dp = Object.defineProperty;
+
 /**
  * Get a stacktrace. 
  *
@@ -17,13 +23,10 @@
  * @returns {string[]} An array of stack strings.
  * @alias module:@lumjs/core/meta.stacktrace
  */
-function stacktrace(msg)
-{
+function stacktrace(msg) {
   return (new Error(msg)).stack.split("\n");
 }
 
-exports.stacktrace = stacktrace;
-
 /**
  * An Error that can be thrown from abstract methods.
  * 
@@ -54,8 +57,7 @@ exports.stacktrace = stacktrace;
  * 
  * @alias module:@lumjs/core/meta.AbstractError
  */
-class AbstractError extends Error
-{
+class AbstractError extends Error {
   /**
    * Construct an AbstractError
    * 
@@ -69,8 +71,7 @@ class AbstractError extends Error
    * error message to use 'getter' instead of 'method'.
    * 
    */
-  constructor(name, getter=false)
-  {
+  constructor(name, getter = false) {
     let msg = "Abstract ";
     msg += (getter ? 'getter ' : 'method ');
     if (name) msg += `'${name}' `;
@@ -80,8 +81,6 @@ class AbstractError extends Error
   }
 }
 
-exports.AbstractError = AbstractError;
-
 /**
  * Function prototypes for async, generator, and async generator functions.
  * @alias module:@lumjs/core/meta.Functions
@@ -91,22 +90,20 @@ const Functions =
   /**
    * Constructor for dynamic generator functions.
    */
-  Generator: Object.getPrototypeOf(function*(){}).constructor,
+  Generator: Object.getPrototypeOf(function* () { }).constructor,
 
   /**
    * Constructor for dynamic async functions.
    */
-  Async: Object.getPrototypeOf(async function(){}).constructor,
+  Async: Object.getPrototypeOf(async function () { }).constructor,
 
   /**
    * Constructor for dynamic async generator functions.
    */
-  AsyncGenerator: Object.getPrototypeOf(async function*(){}).constructor,
+  AsyncGenerator: Object.getPrototypeOf(async function* () { }).constructor,
 
 }
 
-exports.Functions = Functions;
-
 /**
  * A placeholder function for when something is not implemented.
  * 
@@ -117,54 +114,134 @@ exports.Functions = Functions;
  * @returns {void}
  * @alias module:@lumjs/core/meta.NYI
  */
-function NYI(fatal=true, prefix='') 
-{ 
-  const msg = prefix+"« NOT YET IMPLEMENTED »";
+function NYI(fatal = true, prefix = '') {
+  const msg = prefix + "« NOT YET IMPLEMENTED »";
   if (fatal)
     throw new Error(msg);
   else
     console.error(msg);
 }
 
-exports.NYI = NYI;
+function defaultDeprecateItemHandler(item) {
+  let { depVar } = this.opts;
+  if (depVar && typeof item === 'string') {
+    return item.trim().replaceAll(depVar, this.dep);
+  }
+  else if (this.setOpts && isObj(item)) {
+    cp(this.opts, item);
+    return this.next = true;
+  }
+  return item;
+}
+
+const DEP_OPTS =
+{
+  depVar: '{DEP}',
+  handle: defaultDeprecateItemHandler,
+  preDep: '[DEPRECATED]:',
+}
 
 /**
- * Send a deprecation message to the console.
+ * Send a deprecation message to the console (low-level).
  * 
- * Will default to using `console.warn()` to send the message,
- * unless `core.state.get('core.traceDeprecated')` evaluates to true,
- * in which case it will use `console.trace()` instead. 
+ * Will default to using `console.warn()` to send the message, however
+ * it can be made to use `console.trace()` instead if one of the following
+ * evaluates to a true value:
+ * - `core.env.get('LUM_TRACE_DEPRECATED')`
+ * - `core.state.get('core.traceDeprecated')`
+ * As the state module is deprecated, as of 2.x only the env.get() test
+ * will continue to work.
  * 
- * @param {string} dep - Name of what is deprecated
- * @param {(string|string[])} [rep] Replacement suggestion(s).
- * @param {*} [ret] Value to return
- * @returns {mixed} `ret`
- * @alias module:@lumjs/core/meta.deprecated
+ * @param {string} dep - Name of what is deprecated.
+ * @param {...mixed} [info] Additional information.
+ * 
+ * This may be used to suggest replacements, or whatever other
+ * information you want to include in the logs.
+ * 
+ * TODO: document how functions are handled.
  */
-function deprecated(dep, rep, ret)
-{
-  const fn = require('./state').get('core.traceDeprecated')
-    ? 'trace' 
+function deprecate(dep, ...info) {
+
+  let stateLib = require('./state');
+  let fn = stateLib.eors('LUM_TRACE_DEPRECATED', 'core.traceDeprecated')
+    ? 'trace'
     : 'warn';
-  const msgs = [dep,'is deprecated'];
-  if (rep)
-  {
-    msgs.push('replace with', rep);
+
+  let ctx = {
+    add: true,
+    dep,
+    done: false,
+    info,
+    logs: [],
+    next: false,
+    opts: cp({showDep: dep}, DEP_OPTS),
+    setOpts: true,
+  }
+
+  for (let item of info) {
+    if (typeof item === 'function') {
+      item.call(ctx, ctx);
+    }
+    else {
+      if (typeof ctx.opts.handle === 'function') {
+        ctx.next = false;
+        item = ctx.opts.handle.call(ctx, item, ctx);
+        if (ctx.next) continue; // Move on.
+      }
+
+      if (ctx.add) {
+        if (ctx.logs.length === 0 && ctx.opts.preDep) {
+          ctx.logs.push(ctx.opts.preDep);
+        }
+        ctx.logs.push(ctx.opts.showDep || ctx.dep || dep);
+        ctx.add = false;
+      }
+
+      if (item) {
+        ctx.logs.push(item);
+      }
+    }
+    if (ctx.done) break; // No more items, we're done.
   }
-  console[fn](...msgs);
-  return ret;
+
+  console[fn](...ctx.logs);
+  return ctx.return ?? ctx.opts.return;
 }
 
-exports.deprecated = deprecated;
+const DED_OPTS =
+{
+  preRep: 'replace with',
+}
+
+/**
+ * Send a deprecation message to the console (simple).
+ * 
+ * This is now a frontend to the newer `deprecate()` function,
+ * which may replace it entirely one day.
+ * 
+ * @param {string} dep - Name of what is deprecated.
+ * @param {?(string|string[])} [rep] Replacement suggestion(s).
+ * @param {mixed} [ret] Value to return
+ * @param {object} [opts] Formatting options.
+ *
+ * @returns {mixed} `ret`
+ * @alias module:@lumjs/core/meta.deprecated
+ */
+function deprecated(dep, rep, ret, opts) {
+  opts = cp({}, DED_OPTS, opts);
+  rep = Array.isArray(rep) ? rep.slice(0) : [rep];
+  if (opts.preRep) rep.unshift(opts.preRep);
+  return deprecate(dep, opts, ...rep);
+}
 
 /**
  * Assign a getter property that when accessed will
  * show a deprecation message via `deprecated()` function
  * before returning the deprecated property value.
  * 
- * @param {object} obj - Target to assign property on
- * @param {string} prop - Property to assign
- * @param {(object|function)} spec - Specification
+ * @param {(object|function)} obj - Target to assign property on.
+ * @param {(string|symbol)} prop - Property to assign.
+ * @param {(object|function)} spec - Specification.
  * 
  * If this is a `function` it will be used as the `spec.get` value.
  * 
@@ -172,29 +249,154 @@ exports.deprecated = deprecated;
  * @param {string} [spec.dep=prop] Name of what is deprecated;
  * defaults to `prop` if omitted.
  * @param {(string|string[])} [spec.rep] Replacement suggestion(s).
- * @param {object} [spec.opts] Options for `def()` to add getter with.
- * 
  * @returns {object} `obj`
  * 
  * @alias module:@lumjs/core/meta.wrapDepr
  */
-function wrapDepr(obj,prop,spec)
-{
+function wrapDepr(obj, prop, spec) {
   if (typeof spec === 'function')
-    spec = {get: spec};
-  if (typeof spec.get !== 'function') 
+    spec = { get: spec };
+  if (typeof spec.get !== 'function')
     throw new TypeError("invalid init");
 
-  return df(obj, prop, 
-  {
-    get: () =>
-      deprecated(spec.dep??prop, spec.rep, spec.get())
-  }, spec.opts);
+  let getter;
+  if (spec.rep) { // Original style using deprecated() function.
+    getter = () =>
+      deprecated(spec.dep ?? prop, spec.rep, spec.get(), spec)
+  }
+  else {
+    getter = () => {
+      let info = Array.isArray(spec.info) ? spec.info.slice(0) : [];
+      return deprecate(spec.dep ?? prop, {return: spec.get()}, spec, ...info);
+    }
+  }
+
+  return dp(obj, prop, {
+    configurable: true,
+    get: getter,
+  });
 }
 
-exports.wrapDepr = wrapDepr;
+wrapDepr(exports, 'AbstractClass', () => require('./old/abstractclass'));
 
-// This is near the bottom, but before any calls to wrapDepr.
-const {df} = require('./obj/df');
+const FUN_RESERVED = new Set(['prototype', 'length', 'name']);
+const FUN_FILTER = (key) => !FUN_RESERVED.has(key);
 
-wrapDepr(exports, 'AbstractClass', () => require('./old/abstractclass'));
+/**
+ * Deprecate an entire module.
+ * 
+ * This will use `getOwnKeys()` to get a list of properties in a module,
+ * and will create a wrapped version that will use `wrapDepr()` for each
+ * of the properties.
+ * 
+ * @param {(object|function)} src - The exported module.
+ * 
+ * If this is a function, a wrapped version that calls deprecated()
+ * before passing all arguments will be created. It will also use
+ * the name of the function as a default `basespec.dep` value.
+ * 
+ * @param {(object|string)} [basespec] Base specification.
+ * 
+ * If this is a string it will be used as the `basespec.dep` option.
+ * 
+ * Properties in this will be used as the defaults for the `spec` for each
+ * property in the `src` when calling the `wrapDepr()` function, with the
+ * exception of `dep` (see below for how it is handled), and `get` which
+ * is generated automatically for each property.
+ * 
+ * @param {string} [basespec.dep] The name of the module being deprecated.
+ * 
+ * If this is specified as a non-empty string then the spec for each property
+ * will use `{dep: basespec.dep+sep+key}`; otherwise it will use `key` alone.
+ * 
+ * @param {function} [basespec.filter] Filter the properties.
+ * 
+ * If this is specified it will be passed to `keys.filter()` to filter
+ * the keys that will actually be created in the destination object.
+ * 
+ * If `src` is a *function*, and this is NOT specified, then a *default*
+ * will be used that excludes `[prototype, length, name]` from the keys.
+ * 
+ * There is NO default when `src` is an *object*.
+ * 
+ * @param {string} [basespec.sep] Value to use as `sep` (see `basespec.dep`).
+ *
+ * The default is a single dot (`.`) character.
+ * 
+ * @param {object} [dest] Object to add wrapped properties to.
+ * 
+ * This is only applicable if `src` is an *object*. 
+ * It will NOT be used when `src` is a *function*.
+ * If not specified, an empty object will be created.
+ * 
+ * @returns {(object|function)} Return value depends on the type of `src`.
+ */
+function deprecateAll(src, basespec, dest = {}) {
+  if (typeof basespec === 'string') {
+    basespec = cp({ dep: basespec }, DED_OPTS);
+  }
+  else {
+    basespec = cp({}, DED_OPTS, basespec);
+  }
+
+  let hasName = () =>
+    (typeof basespec.dep === 'string' && basespec.dep.trim() !== '');
+
+  let getInfo = (spec) => {
+    let info = Array.isArray(spec.info) 
+      ? spec.info.slice(0)     
+      : [];
+    if (spec.rep) {
+      info.push(spec.rep);
+      delete spec.rep;
+    }
+    return info;
+  }
+
+  let keys = getOwnKeys(src);
+  let sep = basespec.sep ?? '.';
+
+  if (typeof src === 'function') {
+    if (!hasName()) basespec.dep = src.name;
+    if (!basespec.filter) basespec.filter = FUN_FILTER;
+
+    dest = function () {
+      let fun = {src, arguments};
+      let spec = cp({}, basespec, {fun});
+      let info = getInfo(spec);
+      deprecate(spec.dep, spec, ...info);
+      return src.apply(this, arguments);
+    }
+  }
+
+  if (typeof basespec.filter === 'function') {
+    keys = keys.filter(basespec.filter);
+  }
+
+  hasName = hasName(); // finalise
+
+  for (let key of keys) {
+    //let dep = hasName ? basespec.dep + sep + keyName(key) : key;
+    let spec = cp({}, basespec, { 
+      dep: key,
+      get: () => src[key],
+    });
+
+    if (hasName) {
+      spec.info = getInfo(spec);
+      if (basespec.preRep) spec.info.unshift(basespec.preRep);
+      spec.showDep = basespec.dep + sep + keyName(key);
+    }
+
+    wrapDepr(dest, key, spec);
+  }
+
+  return dest;
+}
+
+cp(deprecateAll, {FUN_FILTER, FUN_RESERVED});
+
+exports = module.exports = {
+  AbstractError, deprecate, deprecated, deprecateAll, Functions, 
+  NYI, stacktrace, wrapDepr,
+}

package/lib/obj/apply.js

@@ -1,5 +1,3 @@
-const {F} = require('../types');
-
 /**
  * ApplyInfo objects will have a property with this Symbol
  * as its key and boolean `true` as its value.
@@ -208,7 +206,7 @@ function apply(target, ...values)
 
   for (let value of values)
   {
-    if (typeof value === F)
+    if (typeof value === 'function')
     { 
       value.apply(opts.ctx, opts.args);
     }

package/lib/obj/basics.js

@@ -0,0 +1,12 @@
+'use strict';
+
+const getProperty = require('./getproperty.js');
+const getPrototypeOf = require('./getprotos.js');
+const { getOwnKeys, isEmptyObject, keyName } = require('./keys.js');
+const ownCount = require('./owncount.js');
+const unlocked = require('./unlocked.js');
+
+module.exports = {
+  getOwnKeys, getProperty, getPrototypeOf, keyName, isEmptyObject,
+  ownCount, unlocked,
+}

package/lib/obj/cp.js

@@ -1,7 +1,7 @@
 /**
  * Object property copying utilities.
  * 
- * NOTE: This now just re-exports the `@lumjs/cp` package.
+ * NOTE: This now just re-exports the `@lumjs/cp/obj` package.
  * 
  * @module @lumjs/core/obj/cp
  */

package/lib/obj/df.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const {B,F,S,doesDescriptor} = require('../types/basics');
+const {doesDescriptor} = require('../types/basics');
 const {needObj,needType} = require('../types/needs');
 const TYPES = require('../types/typelist');
 
@@ -67,8 +67,8 @@ function descriptor(desc, opts)
 
   for (const dp of dps)
   {
-    if (typeof opts[dp] === B 
-      && (force.includes(dp) || typeof desc[dp] !== B))
+    if (typeof opts[dp] === 'boolean' 
+      && (force.includes(dp) || typeof desc[dp] !== 'boolean'))
     {
       desc[dp] = opts[dp];
     }
@@ -122,11 +122,11 @@ function df(obj, name, value, opts={})
   needObj(obj, {log, fun: true});
   needType(TYPES.PROP, name, {log});
 
-  if (typeof opts === B)
+  if (typeof opts === 'boolean')
   {
     opts = {useDesc: opts};
   }
-  else if (typeof opts === F && typeof value === F)
+  else if (typeof opts === 'function' && typeof value === 'function')
   {
     value = {get: value, set: opts};
     opts = {useDesc: true};
@@ -220,7 +220,7 @@ function dfor(obj, opts={}, prev=null)
 {
   const fnOne = function (name, value, setter)
   {
-    if (typeof setter === F && typeof value === F)
+    if (typeof setter === 'function' && typeof value === 'function')
     {
       value = {get: value, set: setter}
       opts = clone(opts, {useDesc: true});
@@ -334,7 +334,7 @@ function lazy(target, name, initfunc, opts={})
   let log = {target, name, initfunc, opts};
   needObj(target, {log, fun: true});
   needType(TYPES.PROP, name, {log});
-  needType(F, initfunc, {log});
+  needType('function', initfunc, {log});
   needObj(opts, {log});
 
   // The `this` object for the functions.
@@ -367,7 +367,7 @@ function lazy(target, name, initfunc, opts={})
     }
     else if (doesDescriptor(value))
     { // A descriptor was returned, extract the real value.
-      if (typeof value.get === F)
+      if (typeof value.get === 'function')
       {
         return value.get();
       }
@@ -387,7 +387,7 @@ function lazy(target, name, initfunc, opts={})
     return defval(initfunc.call(ctx,ctx));
   }
 
-  if (typeof opts.set === F)
+  if (typeof opts.set === 'function')
   { // We want to assign a lazy setter as well.
     desc.set = function(value)
     {

package/lib/obj/getproperty.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const {isComplex,isObj} = require('../types');
+const {isComplex,isObj} = require('../types/basics');
 
 /**
  * Get a property descriptor.

package/lib/obj/index.js

@@ -5,20 +5,15 @@
 
 const {apply,ApplyInfo,ApplyOpts,ApplyWith} = 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,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');
-const cp = require('./cp');
 const unlocked = require('./unlocked');
 const ownCount = require('./owncount');
+const {getOwnKeys,isEmptyObject} = require('./keys');
 
 const 
 {
@@ -26,6 +21,11 @@ const
   getNamespace,setNamespace,nsFactory,
 } = ns;
 
+// Deprecated functions; TODO: remove in 2.0
+const NSO = '@lumjs/core/obj';
+const { deprecateAll } = require('../meta');
+const cp = deprecateAll(require('./cp'), NSO+'/cp');
+
 /**
  * Create a new object with a `null` prototype.
  * 
@@ -43,13 +43,17 @@ const
 const discrete = (props) => Object.create(null, props);
 
 // TODO: reorder the following alphabetically, for sanity sake...
-module.exports =
+exports = module.exports =
 {
-  assignd, cp, CLONE, clone, addClone, cloneIfLocked, lock, addLock,
-  df, dfa, dfor, lazy, discrete,
-  mergeNested, syncNested, copyProps, copyAll, ns, nsFactory,
-  getObjectPath, setObjectPath, delObjectPath, getNamespace, setNamespace,
-  getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,
-  MethodFilter, flip, flipKeyVal, flipMap, unlocked, getPrototypesOf,
-  apply, ApplyInfo, ApplyOpts, ApplyWith, ownCount,
+  cp, // TODO: remove this line in 2.0
+
+  apply, ApplyInfo, ApplyOpts, ApplyWith, assignd, 
+  delObjectPath, df, dfa, dfor, discrete, flip, flipKeyVal, flipMap,
+  getMethods, getNamespace, getObjectPath, getOwnKeys, getProperty, 
+  getPrototypesOf, isEmptyObject, lazy, MethodFilter, ns, nsFactory,
+  ownCount, setNamespace, setObjectPath, signatureOf, unlocked,
 }
+
+// Deprecated collections; TODO: remove in 2.0
+deprecateAll(require('@lumjs/cp/fun'), NSO, exports);
+deprecateAll(require('@lumjs/cp/util'), NSO, exports);

package/lib/obj/keys.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Get both string and symbol keys from an object.
+ * @param {object} obj - Target object.
+ * @returns {(string|symbol)[]}
+ */
+const getOwnKeys = obj => [
+  ...(Object.getOwnPropertyNames(obj)),
+  ...(Object.getOwnPropertySymbols(obj)),
+];
+
+/**
+ * See if an object has its own properties.
+ */
+const isEmptyObject = obj => getOwnKeys(obj).length === 0;
+
+/**
+ * Get the name of a property key.
+ * @param {(string|symbol)} key - Property key.
+ * 
+ * If this is a string it will be returned as-is.
+ * If this is a symbol then how it is formatted depends
+ * on the options specified.
+ * 
+ * @param {object} [opts] Options for handling symbol property keys.
+ * @param {string} [opts.prefix] Prefix character; default: `[`.
+ * @param {string} [opts.suffix] Suffix character; default: `]`.
+ * @param {boolean} [opts.toStr=false] Use toString method?
+ * 
+ * If this is false (default), then the return value will be the
+ * `key.description` value with the prefix and suffix values applied.
+ * 
+ * If this is true then the prefix/suffix options are ignored,
+ * and `key.toString()` will be used as the return value.
+ * 
+ * @returns {string}
+ */
+function keyName(key, opts={}) {
+  if (typeof key === 'string') return key;
+  if (typeof key === 'symbol') {
+    if (opts.toStr) {
+      return key.toString();
+    }
+
+    let pf = opts.prefix ?? '[';
+    let sf = opts.suffix ?? ']';
+    return pf+key.description+sf;
+  }
+  
+  console.error({key, opts});
+  throw new TypeError('Invalid key');
+}
+
+module.exports = {getOwnKeys, isEmptyObject, keyName}