@lumjs/core 1.38.4 → 1.38.6

package/lib/index.js

@@ -14,44 +14,38 @@
 
 const types = require('./types');
 const {df,lazy} = require('./obj/df');
+const meta = require('./meta');
 
-// Get a bunch of properties from a submodule.
-function from(submod)
+exports = module.exports = 
 {
-  for (const key in submod)
-  {
-    df(exports, key, submod[key]);
-  }
+  context: require('./context'),
+  def: types.def,  // ← TODO: nix in 2.x
+  df,
+  Enum: require('./enum'),
+  env: require('./env'),
+  flags: require('./flags'),
+  lazy,
+  maps: require('./maps'),
+  meta,
+  ...(meta), // ← TODO: nix in 2.x
+  ...(require('./objectid')),
+  // obj: require('./obj'), // ← TODO: uncomment in 2.x
+  opt: require('./opt'),
+  state: require('./state'),
+  strings: require('./strings'),
+  types,
 }
 
-df(exports, 'types', types);
-df(exports, 'def',   types.def);
-df(exports, 'df',    df);
-df(exports, 'lazy',  lazy);
-
-df(exports, 'context', require('./context'));
-df(exports, 'state', {value: require('./state')});
+// ↓ TODO: nix everything below here in 2.x 
 
-// ObjectID stuff is imported directly without registering a sub-module.
-from(require('./objectid'));
-
-// These are exported directly, but a meta sub-module also exists.
-const meta = require('./meta');
-from(meta);
-df(exports, 'meta', meta);
 df(exports, 'AbstractClass', 
 {
   get() { return meta.AbstractClass; }
 });
 
 lazy(exports, 'arrays', () => require('./arrays'));
-lazy(exports, 'maps', () => require('./maps'));
-lazy(exports, 'strings', () => require('./strings'));
-lazy(exports, 'flags', () => require('./flags'));
 lazy(exports, 'obj', () => require('./obj'));
 lazy(exports, 'console', () => require('./console'));
 lazy(exports, 'traits', () => require('./traits'));
-lazy(exports, 'opt', () => require('./opt'), {df:{autoDesc: false}});
-lazy(exports, 'Enum', () => require('./enum'));
 lazy(exports, 'observable', () => require('./observable'));
 lazy(exports, 'events', () => require('./events'));

package/lib/meta.js

@@ -1,22 +1,16 @@
-"use strict";
 /**
- * Meta-programming helpers
- * 
- * All of the function exported by this module are also available
- * in the main {@link module:@lumjs/core core object} itself.
- * 
+ * Meta-programming helpers. 
  * @module @lumjs/core/meta
  */
-
-const {F} = require('./types/js');
+'use strict';
 
 /**
- * Get a stacktrace. Differs from browser to browser.
+ * Get a stacktrace. 
  *
  * Uses the `stack` property of an `Error` object as the source.
- * This is a super simplistic hack. For a more complete solution, try
- * the `stacktrace-js` library, which will be used in the new `@lumjs/debug`
- * library as a dependency.
+ * Every runtime differs greatly in what is contained in the `stack` text,
+ * so this may not be particularly useful. For a more complete solution, 
+ * try the `stacktrace-js` library.
  *
  * @param {string} [msg] - A message for the Error object.
  *
@@ -186,9 +180,9 @@ exports.deprecated = deprecated;
  */
 function wrapDepr(obj,prop,spec)
 {
-  if (typeof spec === F)
+  if (typeof spec === 'function')
     spec = {get: spec};
-  if (typeof spec.get !== F) 
+  if (typeof spec.get !== 'function') 
     throw new TypeError("invalid init");
 
   return df(obj, prop, 

package/lib/node/index.js

@@ -0,0 +1,14 @@
+/**
+ * A module namespace for NodeJS specific features.
+ * 
+ * This is currently mostly a placeholder for future development.
+ * 
+ * @module @lumjs/core/node
+ */
+'use strict';
+
+module.exports = 
+{
+  modules: require('./modules'),
+  Package: require('./package'),
+}

package/lib/{modules.js → node/modules.js}

@@ -1,11 +1,36 @@
 /**
  * Module helpers.
- * @module @lumjs/core/modules
+ * 
+ * `@lumjs/core/modules` is a deprecated alias to this.
+ * 
+ * @module @lumjs/core/node/modules
  */
 
 const path = require('path');
-const {S,isObj} = require('./types');
-const replace = require('./strings').replaceItems;
+const {S,isObj} = require('../types');
+const replace = require('../strings').replaceItems;
+
+/**
+ * Test if a passed value is a CommonJS `module` object.
+ * @param {*} mod - Value to test.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/node/modules.isCJS
+ */
+const isCJS = (mod) => (isObj(mod) 
+  && typeof mod.id === 'string'
+  && typeof mod.require === 'function'
+);
+
+/**
+ * Test if a passed value is an ES Module `import.meta` object.
+ * @param {*} mod - Value to test.
+ * @returns {boolean}
+ * @alias module:@lumjs/core/node/modules.isESM
+ */
+const isESM = (mod) => (isObj(mod)
+  && typeof mod.url === 'string'
+  && typeof mod.resolve === 'function'
+);
 
 /**
  * Get the name of a module.
@@ -41,9 +66,13 @@ function name(module, opts={})
   { // Going to assume a string is the filename.
     filename = module;
   }
-  else if (isObj(module) && typeof module.filename === S)
+  else if (isCJS(module))
   { // It's a CommonJS module context object.
-    filename = module.filename;
+    filename = module.filename ?? module.id;
+  }
+  else if (isESM(module))
+  { // It's an ES Module metadata (import.meta) object.
+    filename = module.filename ?? path.basename(module.url);
   }
   else
   { // Sorry, we don't support that.
@@ -110,4 +139,4 @@ function name(module, opts={})
   return filename;
 }
 
-exports.name = name;
+module.exports = { name, isCJS, isESM }

package/lib/node/package.js

@@ -0,0 +1,107 @@
+'use strict';
+
+const semver = require('semver');
+const PKGJSON = '/package.json';
+
+function validate(pkgid, autoAppend)
+{
+  if (typeof pkgid !== 'string')
+  {
+    throw new TypeError("package id must be a string");
+  }
+
+  if (autoAppend && !pkgid.endsWith(PKGJSON))
+  {
+    pkgid += PKGJSON;
+  }
+
+  return pkgid;
+}
+
+/**
+ * A wrapper class around package.json data that provides some version
+ * related helper methods.
+ * @exports @lumjs/core/node.Package
+ */
+class Package
+{
+  /**
+   * Build a Package instance.
+   * 
+   * This requires that you've already loaded and parsed a package.json file.
+   * See the require() and import() static methods which take a package name,
+   * and expect that the package has a `/package.json` export defined.
+   * 
+   * @param {object} pkginfo - Data parsed from a package.json file.
+   */
+  constructor(pkginfo)
+  { 
+    /**
+     * The package.json data.
+     * @type {object}
+     */
+    this.info = pkginfo;
+
+    /**
+     * A `SemVer` instance (from the `semver` package) parsed from
+     * the `version` property of the package.json data.
+     * @type {object}
+     */
+    this.version = semver.parse(this.info.version);
+  }
+
+  /**
+   * See if the package version satisfies a range statement.
+   * @param {string} range - A semver range statement.
+   * @param {object} [options] Options; see semver documentation.
+   */
+  satisfies(range, options)
+  {
+    return semver.satisfies(this.version, range, options);
+  }
+
+  /**
+   * Build a Package instance using require() to load a package.json file.
+   * 
+   * @param {string} pkgid - Package id.
+   * 
+   * Assuming the package exports it's package.json as `/package.json` you
+   * can simply pass the plain package name here (e.g. `@lumjs/core`).
+   * 
+   * @param {boolean} [autoAppend=true] Auto-append `/package.json` to pkgid?
+   * 
+   * If this is true (it is by default) and `pkgid` does NOT end in 
+   * `/package.json`, it will be automatically appended before passing 
+   * to require(). If for whatever reason the actual sub-module breaks the
+   * expected naming convention, you'll need to pass the full sub-module
+   * path as the `pkgid` and set this argument to false.
+   * 
+   * @returns {module:@lumjs/core/node.Package}
+   * @throws {TypeError} If `pkgid` is not a string.
+   * @throws {Error} If the package.json can not be loaded.
+   */
+  static require(pkgid, autoAppend=true)
+  {
+    let pkginfo = require(validate(pkgid, autoAppend));
+    return new this(pkginfo);
+  }
+
+  /**
+   * Build a Package instance using import() to load a package.json file.
+   * 
+   * All arguments are handled exactly the same as the require() method.
+   * The only difference is import() is asynchronous, so this will return
+   * a Promise that will resolve to the new Package instance.
+   * 
+   * @param {string} pkgid
+   * @param {boolean} [autoAppend=true]
+   * @returns {Promise<module:@lumjs/core/node.Package>}
+   */
+  static async import(pkgid, autoAppend=true)
+  {
+    let pkginfo = await import(validate(pkgid, autoAppend));
+    return new this(pkginfo);
+  }
+}
+
+module.exports = Package;

package/lib/obj/apply.js

@@ -1,52 +1,260 @@
-const {F,isObj} = require('../types');
-const copyProps = require('./copyprops');
+const {F} = require('../types');
 
 /**
- * Apply functions to an object
- *  
- * In addition to the parameters passed, we'll also define:
+ * ApplyInfo objects will have a property with this Symbol
+ * as its key and boolean `true` as its value.
  * 
- * - `cp` will be a `CopyProps` instance via `copyProps.cache.into(obj)`;
- * - `args` will be an array of `[obj, opts]`;
- * - `opts` will be an object of `{obj, cp, args}`;
+ * The `apply.Info` property is an alias to this.
  * 
- * @param {(object|function)} obj - The target we're applying to.
+ * @type {Symbol}
+ * @name module:@lumjs/core/obj.ApplyInfo
+ */
+const ApplyInfo = Symbol('@lumjs/core/obj.ApplyInfo');
+
+/**
+ * ApplyOpts objects will have a property with this Symbol
+ * as its key and boolean `true` as its value.
  * 
- * @param  {...(function|object)} fns - Values we are applying.
+ * The `apply.Opts` property is an alias to this.
+ * 
+ * @type {Symbol}
+ * @name module:@lumjs/core/obj.ApplyOpts
+ */
+const ApplyOpts = Symbol('@lumjs/core/obj.ApplyOpts');
+
+/**
+ * Options for apply() functions and value handlers.
+ * @typedef {object} module:@lumjs/core/obj~ApplyOpts
+ * @prop {(object|function)} target - Target object.
+ * @prop {(object|function)} obj - DEPRECATED alias of `target`.
+ * @prop {(object|function)} ctx - Context (`this`) for functions.
+ * Set to `target` when opts are initially created.
+ * @prop {Set<module:@lumjs/core/obj~ApplyHandler>} handlers
+ * Registered value handlers.
+ * @prop {Array} args - Arguments passed to `function` values.
  * 
- * For each value of `fns` as `fn`:
+ * In v1.x this defaults to `[target, opts]`.
+ * In v2.x this will default to `[opts]`.
+ */
+
+/**
+ * Info for apply() value handlers.
+ * @typedef {object} module:@lumjs/core/obj~ApplyInfo
+ * @prop {mixed} value - The value that needs to be handled.
+ * @prop {object} opts - The current apply() options.
+ * @prop {boolean} ok - If a handler can handle `value` it must set
+ * this to `true` indicating the value has been handled.
+ * Otherwise apply() will throw a TypeError if every handler has
+ * been called and none can handle the value.
+ * @prop {boolean} done - If a handler has handled a value it may
+ * set this to `true` to indicate that no further handlers need
+ * to be called for that value. If this property is true then
+ * the `ok` property will automatically be considered true as well.
+ */
+
+/**
+ * An apply() value handler.
  * 
- * - If a `function` we'll call `fn.apply(obj, args)`; 
- * - If an `object` we'll call `cp.from(fn)`.
+ * In order to add a handler it must be added to `opts.handlers` using a
+ * registration function. You can make a handler that can register itself
+ * by checking the argument(s) for the `ApplyInfo` or `ApplyOpts` properties.
+ * 
+ * An example for the upcoming v2.x default arguments:
+ * 
+ * ```js
+ * const {apply} = require('@lumjs/core/obj');
+ * function myHandler(info)
+ * {
+ *   if (info[apply.Opts])
+ *   { // Registration (info is opts).
+ *     info.handlers.add(myHandler);
+ *   }
+ *   else if (info[apply.Info])
+ *   { // Handler call.
+ *     if (someTest(info.value))
+ *     { // Code to handle the value would be here.
+ *       info.ok = true;
+ *     }
+ *   }
+ * }
+ * 
+ * // Then to use the handler:
+ * apply(myObj, myHandler, ...valuesToApply);
+ * ```
+ * 
+ * Support for the v1.x default arguments (or even custom arguments),
+ * and dealing with invalid arguments is left up to your imagination.
+ * 
+ * @callback module:@lumjs/core/obj~ApplyHandler
+ * @param {module:@lumjs/core/obj~ApplyHandlerInfo} info 
+ * @returns {void} No return value is required or used.
+ */
+
+/**
+ * Some pre-defined value handlers and registration functions.
+ * @type {object}
+ * @alias module:@lumjs/core/obj.ApplyWith
+ */
+const ApplyWith =
+{
+  /**
+   * A value handler for obj.apply() that uses `cp` to handle objects.
+   *
+   * This is a self-registering handler designed for @lumjs/core v2.x.
+   * Just pass it as a function value to apply() and it will add itself to 
+   * `opts.handlers`, set `opts.cp` to `copyProps.cache.into(opts.target)`, 
+   * and `opts.cp.applyDone` to `true`.
+   * 
+   * This is automatically registered in v1.x. No need to manually add it.
+   * 
+   * For any `object` value passed to apply() after registering this handler,
+   * it will call: `opts.cp.from(value)` to merge the value's properties into
+   * the target object. Finally it will set `info.ok` to `true` (fixed value),
+   * and `info.done` to `opts.cp.applyDone`.
+   * 
+   * It does not handle anything other than `object` values.
+   * 
+   * NOTE: As of v1.38.5 this is an alias to `@lumjs/cp/apply.Handler`
+   * 
+   * @function module:@lumjs/obj.ApplyWith.cpHandler
+   */
+
+  /**
+   * A helper for registration functions that may have the `opts`
+   * passed in different argument positions.
+   * @param {Iterable} args - Arguments passed to function.
+   * @param {mixed} ctx - The value of `this` in the function.
+   * In case `opts.ctx` 
+   * @returns {?module:@lumjs/core/obj~ApplyOpts}
+   * Will be null if no ApplyOpts object could be found in the arguments.
+   */
+  getOpts(args)
+  {
+    for (let arg of args)
+    {
+      if (arg && arg[ApplyOpts]) return arg;
+    }
+    // No opts found.
+    return null;
+  },
+  
+  /**
+   * A registration function that sets `opts.args` to `[opts.target, opts]`
+   * which is the default arguments for @lumjs/core v1.x.
+   */
+  v1Args()
+  {
+    let opts = ApplyInfo.getOpts(arguments);
+    if (opts)
+    {
+      opts.args = [opts.target, opts];
+    }
+  },
+
+  /**
+   * A registration function that sets `opts.args` to `[opts]`
+   * which is the default arguments for @lumjs/core v2.x.
+   */
+  v2Args()
+  {
+    let opts = ApplyInfo.getOpts(arguments);
+    if (opts)
+    {
+      opts.args = [opts];
+    }
+  },
+}
+
+/**
+ * Apply functions (and other values) to an object.
+ *  
+ * NOTE: For the duration of the v1.x releases, the `ApplyWith.cpHandler` 
+ * function will be registered automatically. That will be removed in v2.x,
+ * and you'll have to add it manually from the `@lumjs/cp` package.
+ * 
+ * @param {(object|function)} target - The target we're applying to.
+ * @param  {...(function|object)} values - Values we are applying.
+ * 
+ * For each `value` of the `values`:
+ * 
+ * - If it's a `function` this will do `value.apply(obj, opts.args)`; 
+ * - For any other kind of value:
+ *   - Create an {@link module:@lumjs/core/obj~ApplyInfo} object.
+ *   - For each handler in `opts.handlers` do `handler.call(obj, info)`;
+ *   - If none of the handlers set `info.ok` or `info.done` to true,
+ *     then a TypeError will be thrown, indicating an unhandled value.
  * 
  * @returns {object} `obj`
- * @throws {TypeError} If a `fns` value is not valid.
+ * @throws {TypeError} If a value could not be handled.
  * @alias module:@lumjs/core/obj.apply
  */
-function apply(obj, ...fns)
+function apply(target, ...values)
 {
-  const cp = copyProps.cache.into(obj);
-  const opts = {obj, cp};
-  const args = [obj, opts];
-  opts.args = args;
+  const opts = 
+  {
+    [ApplyOpts]: true, 
+    target, 
+    obj: target,     // DEPRECATED: use target
+    copyProps: true, // Change to false in v2.x
+    ctx: target, 
+    handlers: new Set(),
+  };
+
+  // TODO: change this to `[opts]` in v2.x
+  opts.args = [target, opts];
 
-  for (const fn of fns)
+  // TODO: remove this line in v2.x
+  ApplyWith.cpHandler(opts);
+
+  for (let value of values)
   {
-    if (typeof fn === F)
+    if (typeof value === F)
     { 
-      fn.apply(obj, args);
-    }
-    else if (isObj(fn))
-    {
-      cp.from(fn);
+      value.apply(opts.ctx, opts.args);
     }
     else
     {
-      throw new TypeError("invalid parameter value");
+      let info = 
+      {
+        [ApplyInfo]: true,
+        value,
+        opts, 
+        ok: false, 
+        done: false
+      };
+
+      for (let handler of opts.handlers)
+      {
+        handler.call(opts.ctx, info);
+        if (info.done)
+        {
+          info.ok = true;
+          break;
+        }
+      }
+
+      if (!info.ok)
+      {
+        throw new TypeError("invalid parameter value");
+      }
     }
   }
 
-  return obj;
+  return target;
 }
 
-module.exports = apply;
+// Make aliases to the symbols.
+Object.defineProperties(apply, 
+{
+  Info: { value: ApplyInfo },
+  Opts: { value: ApplyOpts },
+});
+
+module.exports = {apply, ApplyInfo, ApplyOpts, ApplyWith};
+
+const cpApply = require('@lumjs/cp/apply');
+Object.assign(ApplyWith, 
+{
+  cpInit: cpApply.init,
+  cpHandler: cpApply.Handler,
+});

package/lib/obj/copyall.js

@@ -6,21 +6,11 @@
  * 
  * Use `copyProps`, or `mergeNested` for more robust versions.
  * 
- * @alias module:@lumjs/core/obj.copyAll
- * @deprecated Use `Object.assign()` instead.
+ * NOTE: As of v1.38.5 this is an alias of @lumjs/cp/fun.copyAll
+ * 
+ * @name module:@lumjs/core/obj.copyAll
+ * @deprecated Moved to @lumjs/cp package.
  */
-function copyAll(target, ...sources)
-{
-  for (const source of sources)
-  {
-    for (const name in source)
-    {
-      target[name] = source[name];
-    }
-  }
-  return target;
-}
-exports.copyAll = copyAll;
 
 /**
  * Make a (shallow) copy of a single object using `copyAll`.
@@ -29,12 +19,13 @@ exports.copyAll = copyAll;
  * 
  * Alias: `copyAll.clone`
  * 
- * @alias module:@lumjs/core/obj.duplicateOne
+ * NOTE: As of v1.38.5 this is an alias of @lumjs/cp/fun.duplicateOne
+ * 
+ * @name module:@lumjs/core/obj.duplicateOne
  * @param {object} obj - The object to duplicate.
  * @returns {object} A clone of the object.
- * @deprecated Use `clone()` or `Object.assign()` depending on needs.
+ * @deprecated Moved to @lumjs/cp package.
  */
-exports.duplicateOne = copyAll.clone = obj => copyAll({}, obj);
 
 /**
  * Make a new object containing properties from other objects using `copyAll`.
@@ -43,9 +34,12 @@ exports.duplicateOne = copyAll.clone = obj => copyAll({}, obj);
  * 
  * Alias: `copyAll.duplicate`
  * 
- * @alias module:@lumjs/core/obj.duplicateOne
+ * NOTE: As of v1.38.5 this is an alias of @lumjs/cp/fun.duplicateAll
+ * 
+ * @name module:@lumjs/core/obj.duplicateAll
  * @param {object} obj - The object to duplicate.
  * @returns {object} A clone of the object.
- * @deprecated Use `Object.assign()`
+ * @deprecated Moved to @lumjs/cp package.
  */
-exports.duplicateAll = copyAll.duplicate = () => copyAll({}, ...arguments);
+
+module.exports = require('@lumjs/cp/fun');