@lumjs/core 1.38.8 → 1.39.0

package/lib/context.js

@@ -42,12 +42,12 @@
  * @property {boolean} isBundled - Is this a bundled app?
  * @property {boolean} isMain - Is this the main renderer frame?
  * @property {?string} type - `process.type`
- * @property {object} root - See {@link module:@lumjs/core/types.root}
  */
 
-const {root,B,F,U,O,isComplex,isObj} = require('./types');
-const { df, dfor } = require('./obj');
+const {B,F,U,O,isComplex,isObj} = require('./types/basics');
+const { df, dfor } = require('./obj/df');
 
+const root = globalThis;
 const fo = {enumerable: true}
 const ctx = {root};
 const rootHas = what => typeof root[what] !== U;

package/lib/enum.js

@@ -1,3 +1,4 @@
+const { deprecated } = require('./meta');
 const {S,F,def,notNil,isObj,needObj,TYPES} = require('./types');
 const {InternalObjectId} = require('./objectid');
 
@@ -79,6 +80,8 @@ const EOPT = Symbol(EID+':opts');
  * used as the `opts` for {@see module:@lumjs/core/obj.addLock addLock()},
  * which will be called on the open Enum object.
  * 
+ * This option is **deprecated** and will be removed in v2.0.
+ * 
  * @param {bool} [opts.configurable=false] Enum properties are configurable?
  * 
  * This option is ignored if `opts.open` is `false`.
@@ -188,7 +191,9 @@ function Enum (spec, opts={})
     { // Save the options into a special Symbol property.
       def(anEnum, EOPT, {value: opts});
       if (isObj(opts.lock))
-      { // Add lock() method.
+      { // Add lock() method; TODO: remove this in 2.0!
+        deprecated("Enum(opts.lock)");
+        let { addLock } = require('./obj/lock');
         addLock(anEnum, opts.lock);
       }
     }
@@ -196,7 +201,9 @@ function Enum (spec, opts={})
   else
   {
     if (notNil(opts.lock))
-    { // Use lock() function.
+    { // Use lock() function; TODO: remove this in 2.0!
+      deprecated("Enum(opts.lock)");
+      let { lock } = require('./obj/lock');
       let lockOpts;
       if (Array.isArray(opts.lock))
       { // Specified the lock parameters as an array.
@@ -250,6 +257,3 @@ def(Enum, 'is', isEnum);
 TYPES.add('ENUM', 'enum', isEnum, 'isEnum');
 
 module.exports = Enum;
-
-// Loading this at the end.
-const {lock,addLock} = require('./obj/lock');

package/lib/env.js

@@ -2,8 +2,8 @@
 
 const cp = Object.assign;
 const ctx = require('./context');
-const { df, lazy } = require('./obj');
-const { isObj } = require('./types');
+const { df, lazy } = require('./obj/df');
+const { isObj } = require('./types/basics');
 const NS = '@lumjs/core/env';
 const DataCache = Symbol(NS+'~DataCache');
 const Metadata = Symbol(NS+'~Metadata');
@@ -316,7 +316,8 @@ exports = module.exports =
     let info = {key, opts, env: this};
 
     let value = this.getStr(key),
-        cache = false;
+        cache = false,
+        isdef = false;
 
     if (typeof value === 'string')
     {
@@ -326,18 +327,22 @@ exports = module.exports =
     if (value === undefined)
     {
       value = (typeof opts.default === 'function')
-        ? opts.default.call(this, key, opts)
+        ? opts.default.call(this, key, opts, this)
         : opts.default;
+      isdef = true;
     }
 
-    if (isObj(value))
-    { 
-      cache = (opts.cache > 0);
-      this.extendObject(value, info);
-    }
-    else if (value !== undefined)
+    if (!isdef || opts.cache > 2) 
     {
-      cache = (opts.cache > 1);
+      if (isObj(value))
+      { 
+        cache = (opts.cache > 0);
+        this.extendObject(value, info);
+      }
+      else if (value !== undefined)
+      {
+        cache = (opts.cache > 1);
+      }
     }
 
     if (cache)
@@ -453,7 +458,7 @@ exports = module.exports =
       let meth = opts.dataSave;
       if (value[meth] !== undefined)
       {
-        console.error({key, opts, data: value});
+        console.error({meth, value, opts, info});
         throw new RangeError(meth+' property already exists');
       }
 
@@ -874,10 +879,14 @@ exports = module.exports =
  */
 exports.delete = exports.remove;
 
+//console.debug('Main env exports setup', exports);
+
 // Now the platform-specific methods are added!
 
 if (ctx.isNode)
 {
+  //console.debug('Adding node env helpers');
+
   exports.getStr = function(key)
   {
     return process.env[key];
@@ -893,6 +902,7 @@ if (ctx.isNode)
   exports.unset = function(key)
   {
     delete process.env[key];
+    return this;
   }
 
   exports.forEach = function(cb, opts)
@@ -907,6 +917,8 @@ if (ctx.isNode)
 }
 else if (ctx.isBrowser)
 {
+  console.debug('Adding browser env helpers');
+
   exports.getStr = function(key)
   { // getItem returns null for no value, but we want undefined.
     return localStorage.getItem(key) ?? undefined;
@@ -935,3 +947,7 @@ else if (ctx.isBrowser)
     return cb.done();
   }
 }
+else 
+{
+  throw new RangeError('Invalid environment');
+}

package/lib/index.js

@@ -24,18 +24,23 @@ exports = module.exports =
   Enum: require('./enum'),
   env: require('./env'),
   flags: require('./flags'),
-  lazy,
+  lazy, // ← TODO: nix in 2.x
   maps: require('./maps'),
   meta,
-  ...(meta), // ← TODO: nix in 2.x
   ...(require('./objectid')),
   // obj: require('./obj'), // ← TODO: uncomment in 2.x
   opt: require('./opt'),
+  proxy: require('./proxy'),
   state: require('./state'),
   strings: require('./strings'),
   types,
 }
 
+meta.deprecateAll(meta, {
+  dep: '@lumjs/core',
+  rep: '@lumjs/core.meta.{DEP}',
+}, exports);
+
 // ↓ TODO: nix everything below here in 2.x 
 
 df(exports, 'AbstractClass', 

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
  */