@lumjs/core 1.21.0 → 1.23.0

package/PLANS.txt

@@ -0,0 +1,10 @@
+# Future Plans
+
+## 2.x 
+
+I've done a lot of updates to this vanity library since writing it, and it's built up a 
+bit of cruft over time.
+
+While it likely won't happen for a while yet, I do plan to have a clean-up version where
+anything marked deprecated is removed, and any other cleanup that may break stuff can be
+done at that time as well.

package/lib/index.js

@@ -105,7 +105,10 @@ function from(submod, ...libs)
 
 // ObjectID stuff is imported directly without registering a sub-module.
 const objectid = require('./objectid');
-from(objectid, 'randomNumber', 'InternalObjectId');
+from(objectid, 
+  'randomNumber', 
+  'UniqueObjectIds', 
+  'InternalObjectId');
 
 /**
  * Get a simplistic debugging stacktrace
@@ -136,7 +139,12 @@ from(objectid, 'randomNumber', 'InternalObjectId');
 // 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', 'Functions', 'NYI');
+from(meta, 
+  'stacktrace', 
+  'AbstractClass',
+  'AbstractError',
+  'Functions', 
+  'NYI');
 
 /**
  * Create a magic *Enum* object «Lazy»

package/lib/meta.js

@@ -27,6 +27,7 @@ exports.stacktrace = stacktrace;
 
 /**
  * Abstract classes for Javascript.
+ * @deprecated Just use `throw new AbstractError()` instead.
  * @alias module:@lumjs/core/meta.AbstractClass
  */
 class AbstractClass
@@ -103,6 +104,64 @@ class AbstractClass
 
 exports.AbstractClass = AbstractClass;
 
+/**
+ * An Error that can be thrown from abstract methods.
+ * 
+ * Example usage:
+ * 
+ * ```js
+ * class MyAbstractClass
+ * {
+ *   abstractMethod()
+ *   {
+ *     throw new AbstractError();
+ *     // msg = "Abstract method not implemented"
+ *   }
+ * 
+ *   namedMethod()
+ *   {
+ *     throw new AbstractError("namedMethod");
+ *     // msg = "Abstract method 'namedMethod' not implemented"
+ *   }
+ * 
+ *   get absProp()
+ *   {
+ *     throw new AbstractError("absProp", true);
+ *     // msg = "Abstract getter 'absProp' not implemented"
+ *   }
+ * }
+ * ```
+ * 
+ * @alias module:@lumjs/core/meta.AbstractError
+ */
+class AbstractError extends Error
+{
+  /**
+   * Construct an AbstractError
+   * 
+   * @param {string} [name] Name of abstract method/getter.
+   * 
+   * If included will be included in error message.
+   * 
+   * @param {boolean} [getter=false] Is a getter?
+   * 
+   * This option literally just changes the phrasing of the
+   * error message to use 'getter' instead of 'method'.
+   * 
+   */
+  constructor(name, getter=false)
+  {
+    let msg = "Abstract ";
+    msg += (getter ? 'getter ' : 'method ');
+    if (name) msg += `'${name}' `;
+    msg += 'not implemented';
+    super(msg);
+    this.name = 'AbstractError';
+  }
+}
+
+exports.AbstractError = AbstractError;
+
 /**
  * Function prototypes for async, generator, and async generator functions.
  * @namespace

package/lib/obj/flip.js

@@ -0,0 +1,258 @@
+"use strict";
+
+const {B,S,isObj,needObj,isMapOf,isa,isArray} = require('../types');
+
+/**
+ * Flip an object's keys and values.
+ * 
+ * Is a wrapper around the other `flip*` functions.
+ * 
+ * @alias module:@lumjs/core/obj.flip
+ * 
+ * @param {object} obj - Object to flip.
+ * 
+ * If `obj` is a `Map`, passes it to `flipMap()`.
+ * Anything else will be passed to `flipKeyVal()`.
+ * 
+ * Other supported types may be added in the future.
+ * 
+ * @param {object} [opts] Any options supported by the
+ * underlying `flip*` functions that may be called.
+ * 
+ * @returns {object} Object with flipped keys and values.
+ * 
+ * @throws {Error} See the underlying functions for exact error types.
+ * 
+ * @see {@link module:@lumjs/core/obj.flipKeyVal}
+ * @see {@link module:@lumjs/core/obj.flipMap}
+ */
+function flip(obj, opts={})
+{
+  if (obj instanceof Map)
+  {
+    return flipMap(obj, opts);
+  }
+  else
+  {
+    return flipKeyVal(obj, opts);
+  }
+}
+
+/**
+ * Flip a plain object's keys and values.
+ * 
+ * Works for _enumerable_ properties with _non-duplicate_ `string` values.
+ * 
+ * @param {object} inObj - The input object to flip.
+ * 
+ * @param {object} [opts] Options
+ * @param {boolean} [opts.warnDup=true] Use `console` on duplicate values?
+ * @param {boolean} [opts.fatalDup=false] Throw Error on duplicate values?
+ * @param {boolean} [opts.warnStr=true] Use `console` on non-string values?
+ * @param {boolean} [opts.fatalStr=false] Throw Error on non-string values?
+ * 
+ * @returns {object} A new `object` with flipped keys and values.
+ * 
+ * @throws {TypeError} If `obj` was not a valid `object`,
+ * or if `fatalStr` is `true` and a non-string value is found.
+ * 
+ * @throws {ReferenceError} If `fatalDup` is `true`
+ * and a duplicate value is found.
+ * 
+ */
+function flipKeyVal(inObj, opts={})
+{
+  needObj(inObj);
+
+  const wdup = opts.warnDup  ?? true,
+        fdup = opts.fatalDup ?? false,
+        wstr = opts.warnStr  ?? true,
+        fstr = opts.fatalStr ?? false;
+
+  const outObj = {};
+
+  for (const key in inObj)
+  {
+    const val = inObj[key];
+    if (typeof val === S)
+    {
+      if (outObj[val] === undefined)
+      {
+        outObj[val] = key;
+      }
+      else
+      {
+        if (wdup) console.error({key, val, obj: inObj});
+        if (fdup) throw new ReferenceError("Duplicate value");
+      }
+    }
+    else
+    {
+      if (wstr) console.error({key, val, obj: inObj});
+      if (fstr) throw new TypeError("Non-string value");
+    }
+  }
+
+  return outObj;
+}
+
+/**
+ * Flip the keys and values of a `Map`.
+ * 
+ * @param {Map} inMap - The input Map to flip.
+ * 
+ * @param {object} [opts] Options
+ * 
+ * @param {boolean} [opts.warn=true]   Log warnings with `console`?
+ * @param {boolean} [opts.fatal=false] Throw Errors for invalid parameters?
+ * 
+ * @param {object} [opts.valid] Validate the `inMap` keys/values?
+ * @param {?Array} [opts.valid.keys=null] Valid key type tests.
+ * @param {?Array} [opts.valid.values=null] Validate value type tests.
+ * 
+ * @param {(boolean|object)} [opts.valid.map=false] Validate entire map?
+ * 
+ * If this is `true` or an `object` then the entire `inMap` will be tested 
+ * using `isMapOf()`. If an `object`, it will be used as the `rules`
+ * to pass to `isMapOf()` (the `inMap` will be assigned as `rules.value`).
+ * If the validation fails when this is `true`, no attempt to flip the
+ * map will be done.
+ * 
+ * If this is `false`, but at least one of `.keys` or 
+ * `.values` is set, then each key and/or value will be tested using
+ * the `isa()` function, and any invalid key-val pair will be skipped.
+ * 
+ * If not specified, this will default to the value of the `.fatal` option.
+ * 
+ * @param {boolean} [opts.valid.warn] Use `console` if validation failed?
+ * 
+ * If `.map` is `true`, the console will only have one log entry added
+ * with the results of the `isMapOf()` test.
+ * 
+ * If `.map` is `false`, the console will have an entry for every
+ * invalid key-val pair in the `inMap`.
+ * 
+ * If not specified, this will default to the value of the `..warn` option.
+ * 
+ * @param {boolean} [opts.valid.fatal] Throw Error on invalid `inMap`?
+ * 
+ * Only applicable if `.map` is `true`.
+ * If not specified, this will default to the value of the `..fatal` option.
+ * 
+ * @returns {?Map} A new Map with flipped keys and values.
+ * 
+ * @throws {TypeError} Thrown in specific situations:
+ * 
+ * - If `inMap` is not a valid `Map` and `opts.fatal` is `true`.
+ * 
+ * - If both `opts.valid.map` and `opts.valid.fatal` are `true`,
+ *   and the validation tests against the `inMap` object fail.
+ * 
+ */
+function flipMap(inMap, opts={})
+{
+  const warn  = opts.warn  ?? true;
+  const fatal = opts.fatal ?? false;
+
+  if (!(inMap instanceof Map))
+  {
+    const errMsg = "Invalid Map instance";
+
+    if (warn)
+    {
+      const log = [{inMap, opts}];
+      if (!fatal) log.unshift(errMsg);
+      console.error(log);
+    }
+    
+    if (fatal)
+    {
+      throw new TypeError(errMsg);
+    }
+    else
+    {
+      return null;
+    }
+  }
+
+  const vopts  = opts.valid  ?? {};
+  const vwarn  = vopts.warn  ?? warn;
+  const vfatal = vopts.fatal ?? fatal;
+  const vmap   = vopts.map   ?? vfatal;
+
+  const vkeys = isArray(vopts.keys)   ? vopts.keys   : null;
+  const vvals = isArray(vopts.values) ? vopts.values : null;
+
+  function validate(key, val)
+  {
+    if (vkeys && !isa(key, ...vkeys))
+    {
+      if (vwarn)
+      {
+        console.error("Invalid Key", {key, val});
+      }
+      return false;
+    }
+
+    if (vvals && !isa(val, ...vvals))
+    {
+      if (vwarn)
+      {
+        console.error("Invalid Value", {key, val});
+      }
+      return false;
+    }
+
+    return true;
+  }
+
+  if (vmap)
+  { // Validating the entire input Map.
+    const rules = isObj(vmap) ? vmap : {};
+    const valid = isMapOf(rules, vkeys, vvals);
+
+    let passed = false;
+    if (typeof valid === B)
+    {
+      passed = valid;
+    }
+    else if (isObj(valid) && typeof valid.pass === B)
+    {
+      passed = valid.pass;
+    }
+
+    if (!passed)
+    {
+      if (vwarn)
+      { // Log to the console.
+        console.error("Map validation failed", {inMap, opts, valid});
+      }
+      if (vfatal)
+      {
+        throw new TypeError("Invalid Map content");
+      }
+      else
+      { // We're done here. 
+        return null;
+      }
+    }
+  }
+
+  const outMap = new Map();
+
+  for (const [key, val] of inMap)
+  {
+    if (!vmap && !validate(key, val))
+    { // Skip invalid key-val pair.
+      continue;
+    }
+    outMap.set(val, key);
+  }
+
+  return outMap;
+}
+
+module.exports =
+{
+  flip, flipKeyVal, flipMap,
+}

package/lib/obj/index.js

@@ -7,11 +7,13 @@ const apply = require('./apply');
 const {copyAll,duplicateOne,duplicateAll} = require('./copyall');
 const copyProps = require('./copyprops');
 const {CLONE,clone,addClone,cloneIfLocked} = require('./clone');
+const {flip, flipKeyVal, flipMap} = require('./flip');
+const {getMethods,signatureOf,MethodFilter} = require('./getmethods');
+const getProperty = require('./getproperty');
 const {lock,addLock} = require('./lock');
 const {mergeNested,syncNested} = require('./merge');
 const ns = require('./ns');
-const getProperty = require('./getproperty');
-const {getMethods,signatureOf,MethodFilter} = require('./getmethods');
+
 const 
 {
   getObjectPath,setObjectPath,
@@ -24,5 +26,5 @@ module.exports =
   mergeNested, syncNested, copyProps, copyAll, ns,
   getObjectPath, setObjectPath, getNamespace, setNamespace,
   getProperty, duplicateAll, duplicateOne, getMethods, signatureOf,
-  MethodFilter, apply,
+  MethodFilter, apply, flip, flipKeyVal, flipMap,
 }

package/lib/objectid.js

@@ -1,19 +1,198 @@
 
-const {notNil,def,isNil} = require('./types');
+const {notNil,def,isNil,F,N,S,SY} = require('./types');
 
 /**
  * Generate a large random number.
  * 
+ * @param {number} [seed] A base number to use.
+ * 
+ * The default is to use `Date.now()` as the `seed`.
+ * 
  * @returns {number}
  * @alias module:@lumjs/core.randomNumber
  */
-function randomNumber()
+function randomNumber(seed)
 {
-  return Math.floor(Math.random() * Date.now());
+  if (typeof seed !== N) seed = Date.now();
+  return Math.floor(Math.random() * seed);
 }
 
 exports.randomNumber = randomNumber;
 
+const validBase = base => (typeof base === N && base > 1 && base < 37);
+
+class UniqueObjectIds
+{
+  constructor(opts={})
+  {
+    def(this, '$options', {value: opts});
+
+    if (validBase(opts.random))
+    { // Use random ids.
+      def(this, '$randIds', {value: {}});
+    }
+    else if (validBase(opts.timestamp))
+    { // Use timestamp-based ids.
+      def(this, '$timeIds', {value: {}});
+    }
+    else
+    { // Use incremental ids.
+      def(this, '$incIds',  {value: {}});
+    }
+    
+    const propType = (typeof opts.idProperty);
+    const hasProp  = (propType === S || propType === SY);
+    const useRegistry = opts.useRegistry ?? !hasProp;
+
+    if (useRegistry)
+    { // Using an internal registry.
+      def(this, '$registry', {value: new Map()});
+    }
+    else if (!hasProp)
+    { // At least ONE of them MUST be used!
+      throw new RangeError("Need one of 'useRegistry' or 'idProperty'");
+    }
+
+    if (hasProp)
+    { // Add a direct reference to the id property key.
+      def(this, '$idProp', {value: opts.idProperty});
+    }
+
+  }
+
+  id(obj)
+  {
+    const hasRegistry = (this.$registry instanceof Map);
+    if (hasRegistry && this.$registry.has(obj))
+    { // The object was found in the registry.
+      return this.$registry.get(obj);
+    }
+
+    const idProp = this.$idProp;
+
+    if (idProp && obj[idProp])
+    { // An existing object id was found in the object's id property.
+      return obj[idProp];
+    }
+
+    let cno = this.$options.className ?? {};
+    if (typeof cno === F)  cno = {setup: cno};
+    else if (cno === 'lc') cno = {lowercase: true};
+    else if (cno === 'uc') cno = {uppercase: true};
+
+    let id = '', idNum = null;
+
+    if (typeof this.$options.prefix === S)
+    {
+      id += this.$options.prefix; 
+    }
+
+    let className = obj.constructor.name;
+
+    if (typeof cno.setup === F)
+    { // Perform a transformation before any other changes.
+      className = cno.setup(className);
+    }
+
+    if (cno.lowercase)
+    { // Force to lowercase.
+      className = className.toLowerCase();
+    }
+    else if (cno.uppercase)
+    { // Force to uppercase.
+      className = className.toUpperCase();
+    }
+
+    id += className;
+
+    if (this.$incIds)
+    { // Auto-incrementing ids.
+      const ids = this.$incIds;
+      if (ids[className])
+      { // An existing value was found.
+        idNum = (++ids[className]).toString();
+      }
+      else
+      { // No existing values yet.
+        const start = this.$options.startAt ?? 1;
+        ids[className] = start;
+        if (!this.$options.skipFirst)
+        {
+          idNum = start;
+        }
+      }
+    }
+    else
+    { // Something other than auto-increment.
+      let ids, radix;
+      if (this.$randIds)
+      { // Using a random id.
+        ids = this.$randIds;
+        radix = this.$options.random;
+      }
+      else if (this.$timeIds)
+      { // Using timestamp ids.
+        ids = this.$timeIds;
+        radix = this.$options.timestamp;
+      }
+      else
+      { // Something went horribly wrong.
+        throw new Error("No id storage vars found");
+      }
+
+      const getId = () => (this.$randIds 
+        ? randomNumber() 
+        : Date.now())
+        .toString(radix);
+
+      if (ids[className])
+      { // Existing ids for this className have been set.
+        while (!idNum)
+        {
+          idNum = getId();
+          if (ids[className][idNum])
+          { // That id has already been used.
+            idNum = null;
+          }
+          else
+          { // Hasn't been used yet, yay!
+            ids[className][idNum] = true;
+          }
+        }
+      }
+      else
+      {
+        idNum = getId();
+        ids[className] = {};
+        ids[className][idNum] = true;
+      }
+    }
+
+    if (typeof idNum === S)
+    {
+      if (typeof this.$options.infix  === S)
+      {
+        id += this.$options.infix;
+      }
+      id += idNum;
+    }
+
+    if (idProp)
+    {
+      def(obj, idProp, {value: id});
+    }
+
+    if (hasRegistry)
+    {
+      this.$registry.set(obj, id);
+    }
+
+    return id;
+  } // id()
+} // UniqueObjectIds class
+
+exports.UniqueObjectIds = UniqueObjectIds;
+
 /**
  * A class for creating unique identifier objects.
  * Generally only used by my own inernal libraries, thus the name.

package/lib/types/basics.js

@@ -103,6 +103,27 @@ function isProperty(v)
   return (t === S || t === SY);
 }
 
+/**
+ * See if a value is an Iterable object.
+ * 
+ * Objects with `[Symbol.iterator]` can be used in
+ * `for (foo of bar)` statements. This tests for that.
+ * 
+ * @param {*} v - Value we're testing
+ * 
+ * While `string` values implement the `Iterable` interface,
+ * they are not considered an `object` in this and thus will fail.
+ * Only actual `object` values that implement the `[Symbol.iterator]` 
+ * function will pass the test.
+ * 
+ * @returns {boolean}
+ * @alias module:@lumjs/core/types.isIterable
+ */
+function isIterable(v)
+{
+  return (isObj(v) && typeof v[Symbol.iterator] === F);
+}
+
 /**
  * See if an object can be used as a valid *descriptor*.
  * 
@@ -192,9 +213,9 @@ function doesDescriptorTemplate(obj, accessor=false, strict=true)
   return true;
 }
 
-// Now export those.
 module.exports =
 {
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
-  nonEmptyArray, isArguments, isProperty, doesDescriptor, doesDescriptorTemplate,
+  isIterable, nonEmptyArray, isArguments, isProperty,
+  doesDescriptor, doesDescriptorTemplate,
 }

package/lib/types/index.js

@@ -23,7 +23,7 @@ const {O, F, S, B, N, U, SY, BI} = require('./js');
 const 
 {
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
-  nonEmptyArray, isArguments, isProperty, doesDescriptor,
+  nonEmptyArray, isArguments, isProperty, doesDescriptor, isIterable,
   doesDescriptorTemplate,
 } = require('./basics');
 
@@ -31,7 +31,11 @@ const
 const {root, unbound} = require('./root');
 
 // Advanced type checks.
-const {isInstance, isType, isArrayOf, isa} = require('./isa');
+const 
+{
+  isInstance, isType, isa,
+  isArrayOf, isListOf, isMapOf, isObjOf, OfTest,
+} = require('./isa');
 
 // Error-throwing type checks.
 const {needObj, needType, needs} = require('./needs');
@@ -55,7 +59,8 @@ module.exports =
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray, 
   nonEmptyArray, isArguments, isProperty, doesDescriptor, 
   isInstance, isType, isa, needObj, needType, needs, stringify,
-  doesDescriptorTemplate, ownCount, isArrayOf,
+  doesDescriptorTemplate, ownCount, isIterable,
+  isArrayOf, isListOf, isMapOf, isObjOf, OfTest, 
   console,
 }