@lumjs/core 1.4.0 → 1.5.1

package/docs/changelogs/1.x.md

@@ -6,6 +6,23 @@ See [Changelogs](index.md) for more information on the changelogs.
 
 ## [Unreleased]
 
+## [1.5.1] - 2022-09-29
+### Changed
+- Removed `constructor()` from `AbstractClass`.
+- Added `$needs()` to `AbstractClass`.
+### Fixed
+- `AbstractClass` actually works properly now.
+
+## [1.5.0] - 2022-09-27
+### Changed
+- Updated a few DocBlocks.
+- Added a couple explicitly named options to `def()`
+- Rewrote the default module to use `def()` to define its exported properties.
+- Made `arrays`, `strings`, `flags`, `opt`, `modules`, and `observable` use `lazy()`.
+### Fixed
+- Fixed `def()` so that the descriptor defaults are applied properly.
+- Fixed `lazy()` so it returns a proper value and not a descriptor on first access.
+
 ## [1.4.0] - 2022-09-26
 ### Changed
 - Moved `lazy` into `types` module by default (leaving an alias in `core`).
@@ -81,7 +98,9 @@ See [Changelogs](index.md) for more information on the changelogs.
 - See [1.0-beta.md](1.0-beta.md) for the beta versions of `1.0`
 - See [lum.js](https://github.com/supernovus/lum.js) for the original library set this is replacing.
 
-[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.4.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.core.js/compare/v1.5.1...HEAD
+[1.5.1]: https://github.com/supernovus/lum.core.js/compare/v1.5.0...v1.5.1
+[1.5.0]: https://github.com/supernovus/lum.core.js/compare/v1.4.0...v1.5.0
 [1.4.0]: https://github.com/supernovus/lum.core.js/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/supernovus/lum.core.js/compare/v1.3.0...v1.3.1
 [1.3.0]: https://github.com/supernovus/lum.core.js/compare/v1.2.1...v1.3.0

package/lib/index.js

@@ -4,89 +4,161 @@
  * This is the foundation upon which all the rest of my JS libraries
  * are built. It provides fundamental helper functions and classes.
  * 
+ * Properties marked as «Lazy» will be loaded on-demand the first time
+ * the property is accessed. All other properties are always loaded.
+ * 
  * @module @lumjs/core
  */
 
 /**
- * Constants and functions for basic type checking.
+ * Constants and functions for type checks
+ * and other fundamental functions
+ * 
  * @alias module:@lumjs/core.types
  * @see module:@lumjs/core/types
  */
 const types = require('./types');
 
 /**
- * Array utility functions.
- * @alias module:@lumjs/core.arrays
- * @see module:@lumjs/core/arrays
+ * Define properties on an object or function
+ * @name module:@lumjs/core.def
+ * @function
+ * @see module:@lumjs/core/types.def
+ */
+
+/**
+ * Define properties on an object or function
+ * @name module:@lumjs/core.lazy
+ * @function
+ * @see module:@lumjs/core/types.lazy
+ */
+
+// Get a descriptor for one of our sub-modules.
+function lib(name, def={})
+{
+  let value = def.value;
+  
+  if (value === undefined)
+  {
+    const module = def.module ?? name;
+    value = require('./'+module);
+
+    if (value && def.prop && value[def.prop] !== undefined)
+    { 
+      value = value[def.prop];
+    }
+  }
+
+  const desc = 
+  {
+    configurable: false, 
+    enumerable: true, 
+    writable: false,
+    value,
+  }
+
+  return desc;
+}
+
+// Export one of our always loaded properties.
+function has(name, def)
+{
+  types.def(exports, name, lib(name, def));
+}
+
+// Export one of our lazy loaded properties.
+function can(name, def)
+{
+  types.lazy(exports, name, () => lib(name, def), {enumerable: true});
+}
+
+// Export a set of always loaded properties from a sub-module
+function from(modname, ...libs)
+{
+  for (const lib of libs)
+  {
+    has(lib, {module: modname, prop: lib});
+  }
+}
+
+// Our fundamental bits.
+has('types', {value: types});
+has('def',   {value: types.def});
+has('lazy',  {value: types.lazy});
+
+/**
+ * Array utility functions «Lazy»
+ * @name module:@lumjs/core.arrays
+ * @type {module:@lumjs/core/arrays}
  */
-const arrays = require('./arrays');
+can('arrays');
 
 /**
- * Information about the JS context we're running in.
- * @alias module:@lumjs/core.context
- * @see module:@lumjs/core/context
+ * Information about the JS context we're running in
+ * @name module:@lumjs/core.context
+ * @type {module:@lumjs/core/context}
  */
-const context = require('./context');
+has('context');
 
 /**
- * Functions for working with strings and locales.
- * @alias module:@lumjs/core.strings
- * @see module:@lumjs/core/strings
+ * Functions for working with strings and locales «Lazy»
+ * @name module:@lumjs/core.strings
+ * @type {module:@lumjs/core/strings}
  */
-const strings = require('./strings');
+can('strings');
 
 /**
- * Functions for working with binary flags.
- * @alias module:@lumjs/core.flags
- * @see module:@lumjs/core/flags
+ * Functions for working with binary flags «Lazy»
+ * @name module:@lumjs/core.flags
+ * @type {module:@lumjs/core/flags}
  */
-const flags = require('./flags');
+can('flags');
 
 /**
- * Functions for manipulating objects.
- * @alis module:@lumjs/core.obj
- * @see module:@lumjs/core/obj
+ * Functions for manipulating objects
+ * @name module:@lumjs/core.obj
+ * @type {module:@lumjs/core/obj}
  */
-const obj = require('./obj');
+has('obj');
 
 /**
- * Functions for getting values and properties with fallback defaults.
- * @alias module:@lumjs/core.opt
- * @see module:@lumjs/core/opt
+ * Functions for getting values and properties with fallback defaults «Lazy»
+ * @name module:@lumjs/core.opt
+ * @type {module:@lumjs/core/opt}
  */
-const opt = require('./opt');
+can('opt');
 
 /**
- * Meta functions related to JS modules.
+ * Meta functions related to JS modules «Lazy»
  * @alias module:@lumjs/core.modules
  * @see module:@lumjs/core/modules
  */
-const modules = require('./modules');
+can('modules');
 
 // ObjectID stuff is imported directly without registering a sub-module.
-const {randomNumber, InternalObjectId} = require('./objectid');
+from('objectid', 'randomNumber', 'InternalObjectId');
 
 /**
- * Get a simplistic debugging stacktrace.
+ * Get a simplistic debugging stacktrace
  * @name module:@lumjs/core.stacktrace
  * @function
  * @see module:@lumjs/core/meta.stacktrace
  */
 
 /**
- * A simple base class for making *abstract* classes.
+ * A simple base class for making *abstract* classes
  * @name module:@lumjs/core.AbstractClass
  * @see module:@lumjs/core/meta.AbstractClass
  */
 
 /**
- * A *factory* for special types of JS `function` constructors.
+ * A *factory* for special types of JS `function` constructors
  * @name module:@lumjs/core.Functions
  * @see module:@lumjs/core/meta.Functions
  */
 
 /**
- * Throw an `Error` saying that a feature is not yet implemented.
+ * Throw an `Error` saying that a feature is not yet implemented
  * @name module:@lumjs/core.NYI
  * @function
  * @see module:@lumjs/core/meta.NYI
@@ -94,43 +166,20 @@ const {randomNumber, InternalObjectId} = require('./objectid');
 
 // 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 {stacktrace,AbstractClass,Functions,NYI} = require('./meta');
+from('meta', 'stacktrace', 'AbstractClass', 'Functions', 'NYI');
 
 /**
- * Create a magic *Enum* object.
- * @alias module:@lumjs/core.Enum
+ * Create a magic *Enum* object
+ * @name module:@lumjs/core.Enum
  * @function
  * @see module:@lumjs/core/enum
  */
-const Enum = require('./enum');
+has('Enum', {module: 'enum'});
 
 /**
- * Make an object support the *Observable* API.
- * @alias module:@lumjs/core.observable
+ * Make an object support the *Observable* API «Lazy»
+ * @name module:@lumjs/core.observable
  * @function
  * @see module:@lumjs/core/observable
  */
-const observable = require('./observable');
-
-/**
- * Define properties on an object or function.
- * @alias module:@lumjs/core.def
- * @function
- * @see module:@lumjs/core/types.def
- */
-const def = types.def;
-
-/**
- * Define properties on an object or function.
- * @alias module:@lumjs/core.lazy
- * @function
- * @see module:@lumjs/core/types.lazy
- */
- const lazy = types.lazy;
-
-module.exports =
-{
-  types, context, flags, obj, opt, modules, arrays, strings,
-  def, randomNumber, InternalObjectId, Enum, lazy, observable,
-  stacktrace, AbstractClass, Functions, NYI, 
-}
+can('observable');

package/lib/meta.js

@@ -3,6 +3,8 @@
  * @module @lumjs/core/meta
  */
 
+const {F,S,isArray,isa} = require('./types');
+
 /**
  * Get a stacktrace. Differs from browser to browser.
  *
@@ -30,20 +32,71 @@ exports.stacktrace = stacktrace;
 class AbstractClass
 {
   /**
-   * You must override the constructor.
+   * If you want to mark a method as abstract use this.
    */
-  constructor()
+  $abstract(name)
   {
-    const name = this.constructor.name;
-    throw new Error(`Cannot create instance of abstract class ${name}`);
+    if (name.indexOf('(') === -1)
+    { // Add empty method signature.
+      name += '()';
+    }
+    throw new Error(`Abstract method ${name} was not implemented`);
   }
 
   /**
-   * If you want to mark a method as abstract use this.
+   * 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.
+   * 
    */
-  $abstract(name)
+  $needs(...needs)
   {
-    throw new Error(`Abstract method ${name}() was not implemented`);
+    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);
+        }
+      }
+    }
   }
 
 }

package/lib/types/def.js

@@ -14,60 +14,83 @@ const clone = obj => copy({}, obj);
  * It replaces the `prop()` method from the old Lum.js v4.
  * 
  * @param {(object|function)} obj - The object to add a property to.
- * @param {?(string|boolean|object)} name - If a `string`, the property name.
- *   Property names may also be `symbol` values.
+ * @param {?(string|symbol|boolean|object)} name 
+ * If a `string` or `symbol`, it's the property name.
  * 
- *   If this is `null` or `undefined` then the `value` is ignored entirely,
- *   and instead a bound version of this function is created with the
- *   `obj` already passed as the first parameter, and any of the options from
- *   `opts` added to a new default set of options bound to the function.
- *   Can be useful if you need to add a lot of properties to the same object.
+ * If this is `null` or `undefined` then the `value` is ignored entirely,
+ * and instead a bound version of this function is created with the
+ * `obj` already passed as the first parameter, and any of the options from
+ * `opts` added to a new default set of options bound to the function.
+ * Can be useful if you need to add a lot of properties to the same object.
  * 
- *   If this is a `boolean`, then the same logic as if it was `null` or 
- *   `undefined` will apply, except that an `enumerable` property with this 
- *   value will also be added to the descriptors.
+ * If this is a `boolean`, then the same logic as if it was `null` or 
+ * `undefined` will apply, except that an `enumerable` property with this 
+ * value will also be added to the descriptors.
  * 
- *   If this is an `object`, we also ignore `value` entirely, as each of 
- *   the keys of this object will be used as the name of a property, 
- *   and the value associated with the key will be the value to assign it.
+ * If this is an `object`, we also ignore `value` entirely, as each of 
+ * the keys of this object will be used as the name of a property, 
+ * and the value associated with the key will be the value to assign it.
  * 
  * @param {*} value - Used to determine the value of the property.
  * 
- *   If it is an a valid descriptor object (as per `doesDescriptor()`),
- *   it will be used as the descriptor. If it has no `configurable`
- *   property defined, one will be added, and will be set to `true`.
- *   This behaviour may be overridden by the `opts` parameter.
+ * If it is an a valid descriptor object (as per `doesDescriptor()`),
+ * it will be used as the descriptor. If it has no `configurable`
+ * property defined, one will be added, and will be set to `true`.
+ * This behaviour may be overridden by the `opts` parameter.
  * 
- *   If this and `opts` are both `function` values, then this will
- *   be used as a *getter*, and `opts` will be used a *setter*.
+ * If this and `opts` are both `function` values, then this will
+ * be used as a *getter*, and `opts` will be used a *setter*.
  * 
- *   Any other value passed here will be used as the `value` in a
- *   pre-canned descriptor, also with `configurable` set to `true`.
+ * Any other value passed here will be used as the `value` in a
+ * pre-canned descriptor, also with `configurable` set to `true`.
  * 
  * @param {*} [opts] - A multi-purpose option.
  * 
- *   If this is an `object` then it is reserved for named options.
- *   The named options `configurable`, `enumerable`, and `writable`
- *   can be used to define default values to the descriptor properties
- *   of the same name.
+ * If this is an `object` then it is reserved for named options.
  * 
- *   If `value` and this are both `function` values, then `value` will
- *   be used as a *getter* and this will be used as a *setter*.
+ * The named options `configurable`, `enumerable`, and `writable`
+ * can be used to define default values to the descriptor properties
+ * of the same name.
  * 
- *   If `value` is a valid descriptor object, then setting this to `false`
- *   will disable the assumption that it is the descriptor to set.
- *   Setting this to `true` on will instruct the function to make a clone 
- *   of the descriptor object before modifying any properties in it.
+ * If `value` and this are both `function` values, then `value` will
+ * be used as a *getter* and this will be used as a *setter*.
  * 
- *   This defaults to `undefined`, except if 
+ * If this is `true`, it sets `opts.cloneDesc` to `true`.
+ *   
+ * If this is `false`, it sets `opts.autoDesc` to `false`.
+ * 
+ * This defaults to `undefined`, except in bound functions.
+ * 
+ * @param {boolean} [opts.autoDesc=true] Automatically detect descriptors?
+ * 
+ * If `true` (the default value) then the automatic descriptor detection
+ * is used any time the `value` is an `object`.
+ * 
+ * If `false` the descriptor detection is disabled, and we'll always
+ * wrap all values in a new internal descriptor.
+ * 
+ * @param {boolean} [opts.cloneDesc=false] Clone descriptors?
+ * 
+ * If `true` then we'll clone detected descriptors before making
+ * any changes to them.
+ * 
+ * If `false` (the default value), we'll use passed descriptors
+ * directly, so any changes will be made on the original.
+ * 
+ * @param {boolean} [opts.configurable=true] Default `configurable` value 
+ * @param {boolean} [opts.enumerable=false] Default `enumerable` value
+ * @param {boolean} [opts.writable=false] Default `writable` value
+ * 
+ * Only used with *data descriptors* and will be ignored with
+ * *accessor* descriptors.
  * 
  * @returns {*} Normally the `obj` argument with new property added.
  * 
- *   The exception is if this is a bound copy of the function created
- *   using the syntax described in the `name` parameter documentation.
- *   In that case the return value is the bound copy itself.
- *   While that might seem strange, it allows for chaining in a way
- *   that otherwise would not be possible, take this example:
+ * The exception is if this is a bound copy of the function created
+ * using the syntax described in the `name` parameter documentation.
+ * In that case the return value is the bound copy itself.
+ * While that might seem strange, it allows for chaining in a way
+ * that otherwise would not be possible, take this example:
  * 
  * ```
  *   def(myObj)('name', "Bob")('age', 42);
@@ -136,11 +159,31 @@ function def(obj, name, value, opts)
     throw new TypeError("Property name must be a string or a Symbol");
   }
 
+  function getOpt(name, defVal)
+  {
+    const revVal = !defVal;
+    if (isObj(opts) && typeof opts[name] === B)
+    { // Found the option.
+      return opts[name];
+    }
+    else if (opts === revVal)
+    { // A special default rule was found.
+      return revVal;
+    }
+    else 
+    { // Return the default.
+      return defVal;
+    }
+  }
+
+  const autoDesc  = getOpt('autoDesc',  true);
+  const cloneDesc = getOpt('cloneDesc', false);
+
   let desc;
 
-  if (opts !== false && doesDescriptor(value))
+  if (autoDesc && doesDescriptor(value))
   { // The value is a descriptor, let's use it.
-    desc = (opts === true) ? clone(value) : value;
+    desc = cloneDesc ? clone(value) : value;
   }
   else if (typeof value === F && typeof opts === F)
   { // A getter and setter were both specified.
@@ -151,27 +194,28 @@ function def(obj, name, value, opts)
     desc = {value};
   }
 
-  if (isObj(opts))
-  { // If opts is an object, let's look for some supported defaults.
-    const cd = (opt, defval) =>
-    {
-      if (typeof opts[opt] === B && typeof desc[opt] !== B)
-      { // Default descriptor option specified in `opts`
-        desc[opt] = opts[opt];
-      }
-      else if (typeof defval === B)
-      { // A fallback default. 
-        desc[opt] = defval;
-      }
+  const cd = (opt, defval) =>
+  {
+    if (typeof desc[opt] === B) 
+    { // Property was set explicitly.
+      return;
     }
-
-    cd('configurable', true);
-    cd('enumerable');
-    if (desc.get === undefined && desc.set === undefined)
-    { // Only look for this one on data descriptors.
-      cd('writable');
+    else if (isObj(opts) && typeof opts[opt] === B)
+    { // Default descriptor option specified in `opts`
+      desc[opt] = opts[opt];
+    }
+    else if (typeof defval === B)
+    { // A fallback default. 
+      desc[opt] = defval;
     }
-  } // if isObj(opts)
+  }
+
+  cd('configurable', true);
+  cd('enumerable');
+  if (desc.get === undefined && desc.set === undefined)
+  { // Only look for this one on data descriptors.
+    cd('writable');
+  }
 
   // Now after all that, let's actually define the property!
   Object.defineProperty(obj, name, desc);

package/lib/types/lazy.js

@@ -2,6 +2,7 @@ const def = require('./def');
 const {S,F} = require('./js');
 const {COMPLEX} = require('./typelist');
 const {needType,needObj} = require('./needs');
+const {doesDescriptor} = require('./basics');
 
 /**
  * Metadata for the property definition.
@@ -169,8 +170,24 @@ function lazy(target, name, initfunc, opts={})
     if (assign)
     { // Replace the lazy accessor with the returned value.
       def(target, name, value, context.def);
+      // Now return the newly assigned value.
+      return target[name];
+    }
+    else if (doesDescriptor(value))
+    { // A descriptor was returned, extract the real value.
+      if (typeof value.get === F)
+      {
+        return value.get();
+      }
+      else 
+      {
+        return value.value;
+      }
+    }
+    else 
+    { // Just return the original value.
+      return value;
     }
-    return value;
   }
 
   desc.get = function()

package/package.json

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