@lumjs/core 1.26.0 → 1.31.0

package/lib/obj/flip.js

@@ -59,6 +59,7 @@ function flip(obj, opts={})
  * @throws {ReferenceError} If `fatalDup` is `true`
  * and a duplicate value is found.
  * 
+ * @alias module:@lumjs/core/obj.flipKeyVal
  */
 function flipKeyVal(inObj, opts={})
 {
@@ -148,6 +149,7 @@ function flipKeyVal(inObj, opts={})
  * - If both `opts.valid.map` and `opts.valid.fatal` are `true`,
  *   and the validation tests against the `inMap` object fail.
  * 
+ * @alias module:@lumjs/core/obj.flipMap
  */
 function flipMap(inMap, opts={})
 {

package/lib/obj/index.js

@@ -13,6 +13,7 @@ const getProperty = require('./getproperty');
 const {lock,addLock} = require('./lock');
 const {mergeNested,syncNested} = require('./merge');
 const ns = require('./ns');
+const cp = require('./cp');
 
 const 
 {
@@ -22,7 +23,7 @@ const
 
 module.exports =
 {
-  CLONE, clone, addClone, cloneIfLocked, lock, addLock,
+  cp, CLONE, clone, addClone, cloneIfLocked, lock, addLock,
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
   getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,

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');
 
 /**

package/lib/objectid.js

@@ -1,26 +1,55 @@
 
 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;
 
 const validBase = base => (typeof base === N && base > 1 && base < 37);
 
+/**
+ * A class for generating unique ids for objects.
+ * 
+ * TODO: document all the methods, etc.
+ * 
+ * @alias module:@lumjs/core.UniqueObjectIds
+ */
 class UniqueObjectIds
 {
   constructor(opts={})
@@ -206,20 +235,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 +297,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;

package/lib/opt/args.js

@@ -0,0 +1,50 @@
+"use strict";
+
+const {isObj} = require('../types/basics');
+
+/**
+ * A helper function to support both positional arguments 
+ * and named options in the same method signature.
+ *
+ * @param {object} opts - Options built from positional arguments
+ * 
+ * Keep in mind that this object **WILL** be modified!
+ * 
+ * @param {string} optArg - The option that may contain named options
+ * 
+ * Generally the name of the first positional argument that may be
+ * an `object` full of options or a different positional argument value.
+ * 
+ * The biggest limitation is that it cannot be an `object` value when used
+ * as a positional argument, as that will always be seen as the _options_.
+ * 
+ * @param {*} optDef - A default value for `opts[optArg]`
+ * 
+ * If `opts[optArg]` was an `object`, we'll compose its properties
+ * into `opts` directly. If after that `opts[optArg]` is still the
+ * options `object` then this value will be used instead.
+ * 
+ * @example <caption>Example usage</caption>
+ * 
+ *   function example(first=true, second=null, third="test")
+ *   {
+ *     const opts = argOpts({first, second, third}, 'first', true);
+ *   }
+ * 
+ * @exports module:@lumjs/core/opt/args
+ */
+function argOpts(opts, optArg, optDef)
+{
+  if (isObj(opts[optArg]))
+  { // Merge the named options.
+    const specOpts = opts[optArg];
+    Object.assign(opts, specOpts);
+    if (opts[optArg] === specOpts)
+    { // specOpts didn't override the real option.
+      opts[optArg] = optDef;
+    }
+  }
+  return opts;
+} // argOpts()
+
+module.exports = argOpts;

package/lib/opt/getpath.js

@@ -0,0 +1,70 @@
+"use strict";
+
+const {isArrayOf,S} = require('../types/basics');
+const {getObjectPath} = require('../obj/ns');
+const {val} = require('./val');
+
+/**
+ * An alternative to `get()` that uses `getObjectPath()`
+ * to look for a specific nested property value.
+ * 
+ * While `get()` supports positional arguments like `val()`, 
+ * this function _only_ supports named options.
+ * 
+ * @param {object} obj - Object we're looking for properties in
+ * @param {(string|Array)} path - Path for `getObjectPath()`
+ * @param {object} [opts] Options
+ * 
+ * This supports all of the same options as `get()`, plus all of the
+ * options supported by `getObjectPath()`. See the docs for both those
+ * functions to see what all is supported. If the same option is supported
+ * by *both* functions (e.g. `allowFun`) then the default value 
+ * will be the one from `getObjectPath()` rather than `get()`.
+ * 
+ * @param {boolean} [opts.ro=false] Should `opts` be read-only?
+ * 
+ * If `true`, a copy of the `opts` will be made before any changes
+ * are performed, ensuring the original options aren't modified.
+ * 
+ * @returns {*} The property if found, or `opts.default` if not.
+ * 
+ * @see module:@lumjs/core/opt.get
+ * @see module:@lumjs/core/obj.getObjectPath
+ * @alias module:@lumjs/core/opt.getPath
+ */
+function getPath(obj, path, opts={})
+{
+  const defvalue = opts.default;
+  if (opts.ro)
+  {
+    opts = Object.assign({}, opts);
+  }
+  delete opts.default;
+  
+  return val(getObjectPath(obj, path, opts), defvalue,
+    (opts.allowNull ?? true),
+    opts.isLazy,
+    (opts.lazyThis ?? obj),
+    opts.lazyArgs);
+}
+
+/**
+ * Does a value appear to be a path usable by the
+ * {@link module:@lumjs/core/opt.getPath} function?
+ * 
+ * @param {*} value - Value to test;
+ * will be considered a path if it is:
+ * 
+ * - An `Array` with only `string` values in it.
+ * - A string with a `.` character in it.
+ * 
+ * @returns {boolean}
+ * @alias module:@lumjs/core/opt.isPath
+ */
+function isPath(value)
+{
+  return (isArrayOf(value, S) 
+  || (typeof value === S && value.includes('.')));
+}
+
+module.exports = {getPath, isPath};

package/lib/opt/getval.js

@@ -0,0 +1,61 @@
+"use strict";
+
+const {S,needObj,needType} = require('../types');
+const {_opts,val} = require('./val');
+
+/**
+ * See if a property in an object is set.
+ *
+ * If it is, return the property, otherwise return a default value.
+ * This uses the `val()` method, and as such supports the same arguments.
+ * However read the descriptions, as defaults may be quite different!
+ *
+ * @param {object} obj      - An object to test for a property in.
+ * @param {string} optname  - The property name we're checking for.
+ * @param {*}      defvalue - The default value.
+ *
+ * @param {(object|boolean)} [opts] Options
+ * 
+ * If this is a `boolean` it is used as the `allowNull` option.
+ * 
+ * @param {boolean} [opts.allowNull=true] Passed to `val()`;
+ * default is `true`, which differs from `val()`.
+ * @param {boolean} [opts.isLazy=false] Passed to `val()`;
+ * default is `false`, the same as `val()`.
+ * @param {object}  [opts.lazyThis=obj] Passed to `val()`;
+ * default is `obj`, which differs from `val()`.
+ * @param {Array}   [opts.lazyArgs] Passed to `val()`
+ * @param {boolean} [opts.allowFun=false] Allow `obj` to be a `function` ?
+ * 
+ * By default only `object` values are valid for `obj`; this can be set to
+ * `true` to allow `function` values to be used.
+ * 
+ * @param {boolean} [isLazy=false]   Same as `opts.isLazy`
+ * @param {object}  [lazyThis=opts]  Same as `opts.lazyThis`
+ * @param {Array}   [lazyArgs]       Same as `opts.lazyArgs`
+ * @param {boolean} [allowFun]       Same as `opts.allowFun`
+ *
+ * @returns {*} Either the property value, or the default value.
+ * @see module:@lumjs/core/opt.val
+ * @alias module:@lumjs/core/opt.get
+ */
+function get(obj, optname, defvalue, 
+  allowNull=true, 
+  isLazy=false, 
+  lazyThis=obj,
+  lazyArgs=[],
+  allowFun=false)
+{
+  const opts = _opts({allowNull,isLazy,lazyThis,lazyArgs,allowFun}, true);
+
+  needObj(obj, opts.allowFun);
+  needType(S, optname);
+
+  return val(obj[optname], defvalue, 
+    opts.allowNull, 
+    opts.isLazy, 
+    opts.lazyThis, 
+    opts.lazyArgs);
+}
+
+module.exports = {val, get};

package/lib/opt/index.js

@@ -0,0 +1,21 @@
+/**
+ * Functions for working with options and default values.
+ * @module @lumjs/core/opt
+ */
+
+const argOpts = require('./args');
+const {getPath,isPath} = require('./getpath');
+const {val,get} = require('./getval');
+
+exports = module.exports =
+{
+  argOpts, get, getPath, isPath, val,
+}
+
+const {wrapDepr} = require('../meta');
+wrapDepr(exports, 'Opts',
+{
+  dep: '@lumjs/core.opt.Opts',
+  rep: '@lumjs/opts',
+  get: () => require('@lumjs/opts'),
+});

package/lib/opt/val.js

@@ -0,0 +1,63 @@
+"use strict";
+
+const {U,F} = require('../types/js');
+const argOpts = require('./args');
+
+// Helper for `val()` and `get()` to support new-style options.
+function _opts(opts, defNull)
+{
+  return argOpts(opts, 'allowNull', defNull);
+}
+
+/**
+ * See if a value is *set*, and if not, return a default value.
+ * 
+ * This function used to use all positional arguments, but it now
+ * supports named options if an `object` is passed as the third argument.
+ * If both named options and the corresponding positional arguments are
+ * specified, the named options will take precedence.
+ *
+ * @param {*} optvalue - The value we are testing.
+ * @param {*} defvalue - The default value if opt was null or undefined.
+ * 
+ * @param {(object|boolean)} opts - Options
+ * 
+ * If this is a `boolean` it is used as the `allowNull` option.
+ *
+ * @param {boolean} [opts.allowNull=false] If true, allow null to count as *set*.
+ * @param {boolean} [opts.isLazy=false] If true, and `defvalue` is a function,
+ *                                      use the value from the function as 
+ *                                      the default.
+ * @param {object} [opts.lazyThis=null] If `isLazy` is true, this object will
+ *                                      be used as `this` for the function.
+ * @param {Array}  [opts.lazyArgs] If `isLazy` is true, this may be used
+ *                                 as a list of arguments to pass.
+ * 
+ * @param {boolean} [isLazy=false]  Same as `opts.isLazy`
+ * @param {object}  [lazyThis=null] Same as `opts.lazyThis`
+ * @param {Array}   [lazyArgs]      Same as `opts.lazyArgs`
+ *
+ * @return {*} Either `optvalue` or `defvalue` depending on the test.
+ * @alias module:@lumjs/core/opt.val
+ */
+function val(optvalue, defvalue, 
+  allowNull=false, 
+  isLazy=false, 
+  lazyThis=null,
+  lazyArgs=[])
+{
+  const opts = _opts({allowNull,isLazy,lazyThis,lazyArgs}, false);
+
+  if (typeof optvalue === U || (!opts.allowNull && optvalue === null))
+  { // The defined value was not "set" as per our rules.
+    if (opts.isLazy && typeof defvalue === F)
+    { // Get the default value from a passed in function.
+      return defvalue.apply(opts.lazyThis, opts.lazyArgs);
+    }
+    return defvalue;
+  }
+
+  return optvalue;
+}
+
+module.exports = {_opts, val};

package/lib/strings.js

@@ -2,7 +2,7 @@
  * String and locale related functions.
  * @module @lumjs/core/strings
  */
-const {S,B,F,isObj,root,isArray,needType,needObj,console} = require('./types');
+const {S,B,F,isObj,root,isArray,needType,needObj} = require('./types');
 
 /**
  * Get the locale/language string.

package/lib/types/basics.js

@@ -1,10 +1,27 @@
-const {O, F, S, SY} = require('./js');
+"use strict";
+
+/**
+ * Basic types sub-module.
+ * 
+ * Provides a whole assortment of simple type test functions, 
+ * as well as all of the constants found in its `JS` property.
+ * Which means `basics.S === basics.JS.S`.
+ * 
+ * Unlike the `JS` object, this sub-module is NOT frozen/locked,
+ * although the JS constants are assigned as _non-configurable_ so
+ * they cannot be overwritten by different values.
+ * 
+ * @module @lumjs/core/types/basics
+ */
+
+const JS = require('./js');
+const {O, F, S, SY} = JS;
 
 /**
  * See if a value is a non-null `object`.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isObj
+ * @alias module:@lumjs/core/types/basics.isObj
  */
 function isObj(v) { return (typeof v === O && v !== null); }
 
@@ -13,7 +30,7 @@ function isObj(v) { return (typeof v === O && v !== null); }
  * Like `isObj()`, `null` does not count as an `object`.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isComplex
+ * @alias module:@lumjs/core/types/basics.isComplex
  */
 function isComplex(v) { return (typeof v === F || isObj(v)); }
 
@@ -21,7 +38,7 @@ function isComplex(v) { return (typeof v === F || isObj(v)); }
  * See if a value is *nil* (i.e. either `null` or `undefined`).
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isNil
+ * @alias module:@lumjs/core/types/basics.isNil
  */
 function isNil(v) { return (v === undefined || v === null); }
 
@@ -29,7 +46,7 @@ function isNil(v) { return (v === undefined || v === null); }
  * See if a value is not *nil* (i.e. neither `null` nor `undefined`).
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.notNil
+ * @alias module:@lumjs/core/types/basics.notNil
  */
 function notNil(v) { return (v !== undefined && v !== null); }
 
@@ -39,7 +56,7 @@ function notNil(v) { return (v !== undefined && v !== null); }
  * is neither *nil* nor *complex*.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isScalar
+ * @alias module:@lumjs/core/types/basics.isScalar
  */
 function isScalar(v) { return (notNil(v) && !isComplex(v)); }
 
@@ -49,7 +66,7 @@ function isScalar(v) { return (notNil(v) && !isComplex(v)); }
  * @function
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isArray
+ * @alias module:@lumjs/core/types/basics.isArray
  */
 const isArray = Array.isArray;
 
@@ -57,7 +74,7 @@ const isArray = Array.isArray;
  * See if a value is a `TypedArray` object.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isTypedArray
+ * @alias module:@lumjs/core/types/basics.isTypedArray
  */
 function isTypedArray(v)
 {
@@ -70,7 +87,7 @@ function isTypedArray(v)
  * @param {boolean} [typed=false] If `true` we want a `TypedArray`.
  *   If `false` (default) we want a regular `Array`.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.nonEmptyArray
+ * @alias module:@lumjs/core/types/basics.nonEmptyArray
  */
 function nonEmptyArray(v, typed=false)
 {
@@ -84,7 +101,7 @@ function nonEmptyArray(v, typed=false)
  * See if a value is an `arguments` object.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isArguments
+ * @alias module:@lumjs/core/types/basics.isArguments
  */
 function isArguments(v) 
 {
@@ -95,7 +112,7 @@ function isArguments(v)
  * See if a value is a Property name.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isProperty
+ * @alias module:@lumjs/core/types/basics.isProperty
  */
 function isProperty(v)
 {
@@ -117,7 +134,7 @@ function isProperty(v)
  * function will pass the test.
  * 
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isIterable
+ * @alias module:@lumjs/core/types/basics.isIterable
  */
 function isIterable(v)
 {
@@ -129,7 +146,7 @@ function isIterable(v)
  * 
  * @param {*} v - Value to test
  * @returns {boolean}
- * @alias module:@lumjs/core/types.isConstructor
+ * @alias module:@lumjs/core/types/basics.isConstructor
  */
 function isConstructor(v)
 {
@@ -153,7 +170,7 @@ function isConstructor(v)
  * 
  * @param {object} obj - The object we are testing. 
  * @returns {boolean} - Is the object a valid descriptor?
- * @alias module:@lumjs/core/types.doesDescriptor
+ * @alias module:@lumjs/core/types/basics.doesDescriptor
  */
 function doesDescriptor(obj)
 {
@@ -193,7 +210,7 @@ function doesDescriptor(obj)
  *   If this is `false` then any unknown properties will be ignored.
  * 
  * @returns {boolean} Is the object a valid descriptor template?
- * @alias module:@lumjs/core/types.doesDescriptorTemplate
+ * @alias module:@lumjs/core/types/basics.doesDescriptorTemplate
  */
 function doesDescriptorTemplate(obj, accessor=false, strict=true)
 {
@@ -229,5 +246,7 @@ module.exports =
 {
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
   isIterable, nonEmptyArray, isArguments, isProperty, isConstructor,
-  doesDescriptor, doesDescriptorTemplate,
+  doesDescriptor, doesDescriptorTemplate, JS,
 }
+
+JS.addTo(module.exports);