@lumjs/core 1.21.0 → 1.22.0

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/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/isa.js

@@ -4,6 +4,7 @@ const TYPES = require('./typelist');
 
 /**
  * See if a value is an instance of a class.
+ * @deprecated Just use `instanceof` directly, this function is unnecessary.
  * @param {*} v - The value we're testing.
  * @param {function} f - The constructor/class we want.
  * @param {boolean} [needProto=false] If true, the `v` must have a `prototype`.
@@ -23,7 +24,7 @@ function isInstance(v, f, needProto=false)
   // Everything passed.
   return true;
 }
- 
+
 exports.isInstance = isInstance;
 
 /**
@@ -38,6 +39,7 @@ exports.isInstance = isInstance;
  * this function does not count `null` as a valid `object`. 
  * 
  * @param {*} v - The value we're testing. 
+ * 
  * @returns {boolean} If the value was of the desired type.
  * @alias module:@lumjs/core/types.isType
  */
@@ -52,12 +54,12 @@ function isType(type, v)
   { // A type-specific test.
     return TYPES.tests[type](v);
   }
-  else 
+  else
   { // No type-specific tests.
     return (typeof v === type);
   }
 }
- 
+
 exports.isType = isType;
 
 // Default options parser.
@@ -127,7 +129,8 @@ function processOptions(type, v)
  * @param {...any} types - The types the value should be one of.
  * 
  * For each of the `types`, by default if it is a `string` 
- * we test with `isType()`, if it is a `function` we test with `isInstance()`.
+ * we test with `isType()`, if it is a `function` we see if `v`
+ * is either an instance of the type or a sub-class of it.
  * 
  * If it is an `object` and has an `is()` method, use that as the test.
  * 
@@ -138,9 +141,9 @@ function processOptions(type, v)
  *  - `needProto: boolean`, Change the `needProto` option for `isInstance()`
  *  - `parsers: function`, Add another options parser function.
  *  - `process: function`, A one-time set-up function.
- *  - `test: function`, Pass the `v` to this test and return `true` if it passes.
- *  - `typeof: boolean`, If `true` use `typeof` instead of `isType()` for tests.
- *  - `instanceof: boolean`, If `true` use `instanceof` instead of `isInstance()`.
+ *  - `test: function`, Pass the `v` to this and return `true` if it passes.
+ *  - `instanceof: boolean`, If `true` use `instanceof` *instead of* `isInstance()`.
+ *     As of version `1.22`, this defaults to `true`.
  *  - Anything else will be set as an option that may be used by other parsers.
  * 
  * Any other type value will only match if `v === type`
@@ -156,8 +159,7 @@ function isa(v, ...types)
     needProto: false,
     parsers: [DEFAULT_ISA_PARSER],
     process: processOptions,
-    typeof: false,
-    instanceof: false,
+    instanceof: true,
   }
 
   for (const type of types)
@@ -168,13 +170,25 @@ function isa(v, ...types)
     // With that out of the way, let's go!
     if (typeof type === S)
     { // A string is passed to isType()
-      if (opts.typeof && typeof v === type) return true;
       if (isType(type, v)) return true;
     }
     else if (typeof type === F)
     { // A function is passed to isInstance()
-      if (opts.instanceof && v instanceof type) return true;
-      if (isInstance(v, type, opts.needProto)) return true;     
+      if (typeof v === F)
+      { // See if it is a sub-class.
+        if (type.isPrototypeOf(v)) return true;
+      }
+      else
+      { // See if it is an instance.
+        if (opts.instanceof)
+        { // Simple test, is default now.
+          if (v instanceof type) return true;
+        }
+        else
+        { // Old test, will be removed in the future.
+          if (isInstance(v, type, opts.needProto)) return true;
+        }
+      }
     }
     else if (isObj(type))
     { // Objects can be additional tests, or options.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.21.0",
+  "version": "1.22.0",
   "main": "lib/index.js",
   "exports":
   {