@lumjs/core 1.25.2 → 1.30.0

package/README.md

@@ -6,6 +6,16 @@ and work in CommonJS/Node.js and modern browsers without any modifications.
 
 Used by all the rest of my *Lum.js* libraries.
 
+## Notes
+
+As of version `1.30.0` the `opt.Opts` class has been split into its the new
+[@lumjs/opts] package, which itself depends on a new [@lumjs/errors] package.
+
+Until the next major release (`2.0`), this package will have
+a dependency on the split-away pacakages, so that it can have a deprecated
+alias to the old class name available. As of `2.0` that alias will be
+removed, and the dependencies will also be removed.
+
 ## Documentation
 
 ### [API Docs](https://supernovus.github.io/docs/js/@lumjs/core/)
@@ -34,3 +44,7 @@ Timothy Totten <2010@totten.ca>
 
 [MIT](https://spdx.org/licenses/MIT.html)
 
+---
+
+[@lumjs/opts]: https://github.com/supernovus/lum.opts.js
+[@lumjs/errors]: https://github.com/supernovus/lum.errors.js

package/TODO.md

@@ -17,6 +17,8 @@ for the future would be a good idea. A few of the things I want to do:
   - Cut anything that seems superfluous or rarely used
   - Add ability to copy `Symbol` properties
 - Replace `obj.syncNested` with `obj.sync` using the new `obj.copy` API
+- Move `opt.Opts` into its own separate package
+- Give `observable` some TLC
 
 I will likely update this list a bit before I get around to starting the
 new branch that will eventually become the `2.0.0` release.

package/lib/console.js

@@ -177,4 +177,58 @@ for (const method of DEFAULT_METHODS)
   addMethod(method);
 }
 
+/**
+ * Export our wrapper to replace the real console
+ * in the global namespace.
+ * 
+ * @param {*} [handler] Set a handler while we're exported.
+ * 
+ * See the description of `handler` for possible values.
+ * Any existing handler value will be saved to the `preHandler`
+ * static property.
+ * 
+ * @function module:@lumjs/core/console.export
+ */
+def(LC, 'export', function(handler)
+{
+  if (handler !== undefined)
+  { // Save the existing handler as 'preHandler'
+    LC.preHandler = LC.handler ?? null; // Prevent `undefined`
+    LC.handler = handler;
+  }
+
+  globalThis.console = LC;
+  return LC;
+});
+
+/**
+ * Restore the real console.
+ * 
+ * If a `handler` was passed to `export()`, then
+ * it will be removed, and the previous handler value
+ * will be restored.
+ * 
+ * @function module:@lumjs/core/console.restore
+ */
+def(LC, 'restore', function()
+{
+  if (LC.preHandler !== undefined)
+  {
+    LC.handler = LC.preHandler;
+    delete LC.preHandler;
+  }
+
+  globalThis.console = LC.real;
+  return LC;
+});
+
+/**
+ * A shortcut for `LC.export(false)`
+ * @function module:@lumjs/core/console.mute
+ */
+def(LC, 'mute', function()
+{
+  return LC.export(false);
+});
+
 module.exports = LC;

package/lib/enum.js

@@ -2,7 +2,10 @@ const {S,def,notNil,isObj,needObj,TYPES} = require('./types');
 const {InternalObjectId} = require('./objectid');
 
 // Internal id instances should never be exported.
-const ENUM_ID = new InternalObjectId({name: '$Enum'});
+const EID = '@lumjs/core/enum';
+const ENUM_ID = new InternalObjectId({name: EID});
+const isEnum = ENUM_ID.isFunction();
+const EOPT = Symbol(EID+':opts');
 
 /**
  * A function to build magic Enum objects.
@@ -72,7 +75,16 @@ function Enum (spec, opts={})
   needObj(spec, "Enum spec must be an object")
   needObj(opts, "Enum options must be an object")
 
-  const anEnum = ENUM_ID.tag({});
+  const isExisting = isEnum(opts);
+  const anEnum = isExisting ? opts : ENUM_ID.tag({});
+  if (isExisting)
+  {
+    opts = anEnum[EOPT];
+    if (!isObj(opts))
+    {
+      throw new Error("existing Enum was not open for changes");
+    }
+  }
 
   const configurable = opts.configurable ?? false;
   const enumerable   = opts.enumerable   ?? true;
@@ -130,6 +142,10 @@ function Enum (spec, opts={})
         counter++;
       }
     }
+    if (opts.open)
+    { // Save the last counter value into the opts
+      opts.counter = counter;
+    }
   }
   else
   { // An object mapping of property name to value.
@@ -141,7 +157,14 @@ function Enum (spec, opts={})
     }
   }
 
-  if (!opts.open)
+  if (opts.open)
+  {
+    if (!isExisting)
+    { // Save the options into a special Symbol property.
+      def(anEnum, EOPT, {value: opts});
+    }
+  }
+  else
   {
     if (notNil(opts.lock))
     { // Use lock() function.
@@ -180,13 +203,11 @@ function Enum (spec, opts={})
  * @param {*} obj - The expected object/function to test.
  * @returns {boolean}
  */
-const isEnum = ENUM_ID.isFunction()
 def(Enum, 'is', isEnum);
 
 /**
  * Is a value an *Enum* magic object?
- * @name module:@lumjs/core/types.isEnum
- * @function
+ * @function module:@lumjs/core/types.isEnum
  * @param {*} v - The value to test.
  * @returns {boolean}
  * @see module:@lumjs/core/enum.is

package/lib/index.js

@@ -98,24 +98,19 @@ lazy(exports, 'traits', () => require('./traits'));
  * @name module:@lumjs/core.opt
  * @type {module:@lumjs/core/opt}
  */
-const optOpts = {enumerable: true, def:{autoDesc: false}}
-lazy(exports, 'opt', () => require('./opt'), optOpts);
+lazy(exports, 'opt', () => require('./opt'), {def:{autoDesc: false}});
 
 // Get a bunch of properties from a submodule.
-function from(submod, ...libs)
+function from(submod)
 {
-  for (const lib of libs)
+  for (const key in submod)
   {
-    def(exports, lib, submod[lib]);
+    def(exports, key, submod[key]);
   }
 }
 
 // ObjectID stuff is imported directly without registering a sub-module.
-const objectid = require('./objectid');
-from(objectid, 
-  'randomNumber', 
-  'UniqueObjectIds', 
-  'InternalObjectId');
+from(require('./objectid'));
 
 /**
  * Get a simplistic debugging stacktrace
@@ -143,15 +138,16 @@ from(objectid,
  * @see module:@lumjs/core/meta.NYI
  */
 
+// TODO: documentation for 'deprecated' and 'wrapDepr'
+
 // These are exported directly, but a meta sub-module also exists.
 // Unlike most sub-modules there is no `meta` property in the main library.
 const meta = require('./meta');
-from(meta, 
-  'stacktrace', 
-  'AbstractClass',
-  'AbstractError',
-  'Functions', 
-  'NYI');
+from(meta);
+def(exports, 'AbstractClass', 
+{
+  get() { return meta.AbstractClass; }
+});
 
 /**
  * Create a magic *Enum* object «Lazy»

package/lib/meta.js

@@ -1,9 +1,6 @@
-/**
- * Meta-programming helpers.
- * @module @lumjs/core/meta
- */
+"use strict";
 
-const {F,S,isArray,isa,console} = require('./types');
+const {F} = require('./types/js');
 
 /**
  * Get a stacktrace. Differs from browser to browser.
@@ -16,7 +13,7 @@ const {F,S,isArray,isa,console} = require('./types');
  * @param {string} [msg] - A message for the Error object.
  *
  * @returns {string[]} An array of stack strings.
- * @alias module:@lumjs/core/meta.stacktrace
+ * @alias module:@lumjs/core.stacktrace
  */
 function stacktrace(msg)
 {
@@ -25,85 +22,6 @@ function stacktrace(msg)
 
 exports.stacktrace = stacktrace;
 
-/**
- * Abstract classes for Javascript.
- * @deprecated Just use `throw new AbstractError()` instead.
- * @alias module:@lumjs/core/meta.AbstractClass
- */
-class AbstractClass
-{
-  /**
-   * If you want to mark a method as abstract use this.
-   */
-  $abstract(name)
-  {
-    if (name.indexOf('(') === -1)
-    { // Add empty method signature.
-      name += '()';
-    }
-    throw new Error(`Abstract method ${name} was not implemented`);
-  }
-
-  /**
-   * Check for required properties
-   * 
-   * @param {...(string|Array)} needs - What is needed
-   * 
-   * If this is a `string` it should be in a format like:
-   * 
-   * - `methodName(arg1,arg2,arg3)`
-   * - `anotherMethod(number, string, object) : boolean`
-   * - `yetAnother (className) : resultClass`
-   * 
-   * The names are case sensitive, and we'll look for the method after 
-   * stripping off anything from the first *non-word* character.
-   * 
-   * If this is an `Array`, the first item must be the name of a property,
-   * and each other item should be a type checking value, or array of type 
-   * checking values from the [TYPES]{@link module:@lumjs/core/types.TYPES} 
-   * object, as used by [isa()]{@link module:@lumjs/core/types.isa}.
-   * 
-   * If you are calling this in an abstract class constructor, likely only 
-   * the method checks will be useful, as the `super()` call must be done 
-   * *before* any instance property assignments.
-   * 
-   */
-  $needs(...needs)
-  {
-    const className = this.constructor.name;
-
-    const getName = fullName => fullName.replace(/\W.*/, '');
-    const missing = propName => 
-    { 
-      throw new Error(`${className} is missing ${propName}`); 
-    }
-
-    for (const need of needs)
-    {
-      if (typeof need === S)
-      { // A simple method
-        const meth = getName(need);
-        if (typeof this[meth] !== F)
-        {
-          missing(need);
-        }
-      }
-      else if (isArray(need))
-      {
-        const prop = getName(need[0]);
-        const types = need.slice(1);
-        if (!isa(this[prop], ...types))
-        {
-          missing(need);
-        }
-      }
-    }
-  }
-
-}
-
-exports.AbstractClass = AbstractClass;
-
 /**
  * An Error that can be thrown from abstract methods.
  * 
@@ -132,7 +50,7 @@ exports.AbstractClass = AbstractClass;
  * }
  * ```
  * 
- * @alias module:@lumjs/core/meta.AbstractError
+ * @alias module:@lumjs/core.AbstractError
  */
 class AbstractError extends Error
 {
@@ -165,7 +83,7 @@ exports.AbstractError = AbstractError;
 /**
  * Function prototypes for async, generator, and async generator functions.
  * @namespace
- * @alias module:@lumjs/core/meta.Functions
+ * @alias module:@lumjs/core.Functions
  */
 const Functions =
 {
@@ -196,7 +114,7 @@ exports.Functions = Functions;
  * @param {string} [prefix=''] A prefix for the error message.
  * 
  * @returns {void}
- * @alias module:@lumjs/core/meta.NYI
+ * @alias module:@lumjs/core.NYI
  */
 function NYI(fatal=true, prefix='') 
 { 
@@ -208,3 +126,65 @@ function NYI(fatal=true, prefix='')
 }
 
 exports.NYI = NYI;
+
+/**
+ * Send a deprecation message with a stack trace.
+ * 
+ * @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.deprecated
+ */
+function deprecated(dep, rep, ret)
+{
+  const msgs = [dep,'is deprecated'];
+  if (rep)
+  {
+    msgs.push('replace with', rep);
+  }
+  console.trace(...msgs);
+  return ret;
+}
+
+exports.deprecated = deprecated;
+
+/**
+ * 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
+ * 
+ * If this is a `function` it will be used as the `spec.get` value.
+ * 
+ * @param {function} spec.get - The function that returns the real value
+ * @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`
+ */
+function wrapDepr(obj,prop,spec)
+{
+  if (typeof spec === F)
+    spec = {get: spec};
+  if (typeof spec.get !== F) 
+    throw new TypeError("invalid init");
+
+  return def(obj, prop, 
+  {
+    get: () =>
+      deprecated(spec.dep??prop, spec.rep, spec.get())
+  }, spec.opts);
+}
+
+exports.wrapDepr = wrapDepr;
+
+// This is near the bottom, but before any calls to wrapDepr.
+const def = require('./types/def');
+
+wrapDepr(exports, 'AbstractClass', () => require('./old/abstractclass'));

package/lib/obj/clone.js

@@ -1,5 +1,5 @@
 // Import *most* required bits here.
-const {N,F, isObj, isComplex, def, isArray, console} = require('../types');
+const {N,F, isObj, isComplex, def, isArray} = require('../types');
 const copyProps = require('./copyprops');
 const getProp = require('./getproperty');
  

package/lib/obj/copyprops.js

@@ -1,6 +1,6 @@
 
 // Get some constants
-const {S,B,N,F,isObj,isArray,needObj,def,console} = require('../types');
+const {S,B,N,F,isObj,isArray,needObj,def} = require('../types');
 const {copyAll, duplicateOne: clone} = require('./copyall');
 
 const RECURSE_NONE =  0;

package/lib/obj/merge.js

@@ -1,5 +1,5 @@
 // Import required bits here.
-const {B, N, isObj} = require('../types');
+const {B, isObj} = require('../types');
 const copyProps = require('./copyprops');
 
 // A shortcut for the recursive option.

package/lib/obj/ns.js

@@ -3,7 +3,7 @@ const
 {
   B, S,
   root, isObj, needObj, def, nonEmptyArray, notNil,
-  doesDescriptorTemplate, console,
+  doesDescriptorTemplate,
 } = require('../types');
 
 /**
@@ -83,6 +83,11 @@ exports.nsArray = nsArray;
  * @param {(object|boolean)} [opts] Options changing the behaviours.
  *   If this is a `boolean` it's assumed to be the `opts.log` option.
  * @param {boolean} [opts.log=false] Log errors for missing namespaces?
+ * @param {boolean} [opts.allowFun=true] Allow `obj` to be a `function` ?
+ * 
+ * By default both `object` and `function` are valid `obj` argument values;
+ * if this is set to `false`, only `object` values will be allowed.
+ * 
  * @param {*} [opts.default] A default value if the namespace is not found.
  * 
  * @return {*} The property if found, or `opts.default` if not.
@@ -90,13 +95,13 @@ exports.nsArray = nsArray;
  */
 function getObjectPath(obj, proppath, opts={})
 {
-  needObj(obj, true);
-
   if (typeof opts === B)
     opts = {log: opts};
   else if (!isObj(opts))
     opts = {};
 
+  needObj(obj, (opts.allowFun ?? true));
+
   proppath = nsArray(proppath);
 
   for (let p = 0; p < proppath.length; p++)

package/lib/objectid.js

@@ -1,20 +1,42 @@
 
 const {notNil,def,isNil,F,N,S,SY} = require('./types');
+const argOpts = require('./opt/args');
 
 /**
- * Generate a large random number.
+ * Generate a random number.
  * 
- * @param {number} [seed] A base number to use.
+ * @param {(object|number)} [opts] Options
  * 
- * The default is to use `Date.now()` as the `seed`.
+ * @param {number} [opts.seed] A base number to use.
+ *
+ * If this is omitted, or an invalid value (including `0`), 
+ * the default is to use `Date.now()` as the `seed`.
+ * 
+ * @param {number} [mode=1] Determine how to handle return value
+ * 
+ * | Mode    | Description                                               |
+ * | ------- | --------------------------------------------------------- |
+ * | `0`     | Return unmodified floating point number                   |
+ * | `1`     | `Math.round()` (default)                                  |
+ * | `2`     | `Math.floor()`                                            |
+ * | `3`     | `Math.ceil()`                                             |
  * 
  * @returns {number}
  * @alias module:@lumjs/core.randomNumber
  */
-function randomNumber(seed)
+function randomNumber(seed=0, mode=1)
 {
-  if (typeof seed !== N) seed = Date.now();
-  return Math.floor(Math.random() * seed);
+  if (typeof seed !== N || seed === 0) seed = Date.now();
+
+  const rand = Math.random() * seed;
+
+  switch(mode)
+  {
+    case 1: return Math.round(rand);
+    case 2: return Math.floor(rand);
+    case 3: return Math.ceil(rand);
+    default: return rand;
+  }
 }
 
 exports.randomNumber = randomNumber;
@@ -206,20 +228,20 @@ class InternalObjectId
    * @param {object} opts - Named options to change default behaviours.
    * @param {string} [opts.name] A friendly name for diagnostics.
    * @param {(string|number)} [opts.id] An internal id value.
-   *   Default value is a large random number. 
+   *   A reasonable default will be generated if it's not specified.
    * @param {(string|Symbol)} [opts.property] The property name or Symbol.
    *   This is the property that will be set on objects that are tagged
-   *   with this InternalObjectId. Default is `Symbol(this.id)`.
+   *   with this InternalObjectId. Default is a unique (non-global) `Symbol`.
    * @param {boolean} [opts.useInstance=true] Store object or id value?
    *   If this is `true` (now the default), we store the instance itself.
    *   If this is `false` (the old default), we store just the `id` value.
    */
   constructor(opts={})
   {
+    const ui = this.useInstance = opts.useInstance ?? true;
     this.name = opts.name;
-    this.id = opts.id ?? randomNumber();
-    this.property = opts.property ?? Symbol(this.id);
-    this.useInstance = opts.useInstance ?? true; 
+    this.id = opts.id ?? (ui ? Date.now() : randomNumber());
+    this.property = opts.property ?? Symbol(this.name ?? this.id);
   }
 
   /**
@@ -268,8 +290,7 @@ class InternalObjectId
    */
   isFunction()
   {
-    const oid = this;
-    return function(obj) { return oid.is(obj); }
+    return obj => this.is(obj);
   }
 
 }

package/lib/observable.js

@@ -1,5 +1,5 @@
 // Defining these after observable.
-const {B,F,S,def,isObj,isComplex,TYPES,console} = require('./types');
+const {B,F,S,def,isObj,isComplex,TYPES} = require('./types');
 const {duplicateAll: clone} = require('./obj/copyall');
 const lock = Object.freeze;
 

package/lib/old/abstractclass.js

@@ -0,0 +1,82 @@
+"use strict";
+
+const {F,S,isArray,isa} = require('../types');
+
+/**
+ * Abstract classes for Javascript.
+ * @deprecated Just use `throw new AbstractError()` instead.
+ * @alias module:@lumjs/core/meta.AbstractClass
+ */
+class AbstractClass
+{
+  /**
+   * If you want to mark a method as abstract use this.
+   */
+  $abstract(name)
+  {
+    if (name.indexOf('(') === -1)
+    { // Add empty method signature.
+      name += '()';
+    }
+    throw new Error(`Abstract method ${name} was not implemented`);
+  }
+
+  /**
+   * Check for required properties
+   * 
+   * @param {...(string|Array)} needs - What is needed
+   * 
+   * If this is a `string` it should be in a format like:
+   * 
+   * - `methodName(arg1,arg2,arg3)`
+   * - `anotherMethod(number, string, object) : boolean`
+   * - `yetAnother (className) : resultClass`
+   * 
+   * The names are case sensitive, and we'll look for the method after 
+   * stripping off anything from the first *non-word* character.
+   * 
+   * If this is an `Array`, the first item must be the name of a property,
+   * and each other item should be a type checking value, or array of type 
+   * checking values from the [TYPES]{@link module:@lumjs/core/types.TYPES} 
+   * object, as used by [isa()]{@link module:@lumjs/core/types.isa}.
+   * 
+   * If you are calling this in an abstract class constructor, likely only 
+   * the method checks will be useful, as the `super()` call must be done 
+   * *before* any instance property assignments.
+   * 
+   */
+  $needs(...needs)
+  {
+    const className = this.constructor.name;
+
+    const getName = fullName => fullName.replace(/\W.*/, '');
+    const missing = propName => 
+    { 
+      throw new Error(`${className} is missing ${propName}`); 
+    }
+
+    for (const need of needs)
+    {
+      if (typeof need === S)
+      { // A simple method
+        const meth = getName(need);
+        if (typeof this[meth] !== F)
+        {
+          missing(need);
+        }
+      }
+      else if (isArray(need))
+      {
+        const prop = getName(need[0]);
+        const types = need.slice(1);
+        if (!isa(this[prop], ...types))
+        {
+          missing(need);
+        }
+      }
+    }
+  }
+
+}
+
+module.exports = AbstractClass;