@lumjs/core 1.7.0 → 1.8.0

package/lib/index.js

@@ -19,117 +19,80 @@
  */
 const types = require('./types');
 
-/**
- * A helper for building modules
- * 
- * @alias module:@lumjs/core.ModuleBuilder
- * @see module:@lumjs/core/modulebuilder
- */
-const Builder = require('./modulebuilder');
-
-// And we'll use the builder to define the rest of this.
-const {has,can,from} = Builder.build(module);
-
 /**
  * Define properties on an object or function
  * @name module:@lumjs/core.def
- * @function
  * @see module:@lumjs/core/types.def
  */
+const def = types.def;
 
 /**
- * Define properties on an object or function
- * @name module:@lumjs/core.lazy
- * @function
+ * Define *lazy* properties on an object or function
+ * @alias module:@lumjs/core.lazy
  * @see module:@lumjs/core/types.lazy
  */
+const lazy = types.lazy;
 
-// Our fundamental bits.
-has('types', {value: types});
-has('def',   {value: types.def});
-has('lazy',  {value: types.lazy});
-
-// The module builder itself.
-has('ModuleBuilder', {value: Builder});
+// A descriptor template for def/lazy.
+const E = def.e;
 
-/**
- * Return a set of functions for building a module.
- * 
- * @name module:@lumjs/core.buildModule
- * @function
- * @see module:@lumjs/core/modulebuilder.build 
- */
-has('buildModule', 
-{
-  value: function(m,o) 
-  { 
-    return Builder.build(m,o); 
-  },
-});
+console.debug('E', E);
 
-/**
- * Create a new `ModuleBuilder` instance.
- * 
- * @name module:@lumjs/core.newBuilder
- * @function
- * @see module:@lumjs/core/modulebuilder.new
- */
-has('newBuilder',
-{
-  value: function(m, o)
-  {
-    return Builder.new(m,o);
-  }
-});
+def(exports, 'types', types, E);
+def(exports, 'def',   def,   E);
+def(exports, 'lazy',  lazy,  E);
 
 /**
  * Array utility functions «Lazy»
  * @name module:@lumjs/core.arrays
  * @type {module:@lumjs/core/arrays}
  */
-can('arrays');
+lazy(exports, 'arrays', () => require('./arrays'), E);
 
 /**
  * Information about the JS context we're running in
  * @name module:@lumjs/core.context
  * @type {module:@lumjs/core/context}
  */
-has('context');
+def(exports, 'context', require('./context'), E);
 
 /**
  * Functions for working with strings and locales «Lazy»
  * @name module:@lumjs/core.strings
  * @type {module:@lumjs/core/strings}
  */
-can('strings');
+lazy(exports, 'strings', () => require('./strings'), E);
 
 /**
  * Functions for working with binary flags «Lazy»
  * @name module:@lumjs/core.flags
  * @type {module:@lumjs/core/flags}
  */
-can('flags');
+lazy(exports, 'flags', () => require('./flags'), E);
 
 /**
- * Functions for manipulating objects
+ * Functions for manipulating objects «Lazy»
  * @name module:@lumjs/core.obj
  * @type {module:@lumjs/core/obj}
  */
-can('obj');
+lazy(exports, 'obj', () => require('./obj'), E);
 
 /**
  * Functions for getting values and properties with fallback defaults «Lazy»
  * @name module:@lumjs/core.opt
  * @type {module:@lumjs/core/opt}
  */
-can('opt');
+lazy(exports, 'opt', () => require('./opt'), E);
 
-/**
- * Meta functions related to JS modules «Lazy»
- * @alias module:@lumjs/core.modules
- * @see module:@lumjs/core/modules
- */
-can('modules');
+// Get a bunch of properties from a submodule.
+function from(modname, ...libs)
+{
+  const submod = require('./'+modname);
+  for (const lib of libs)
+  {
+    def(exports, lib, submod[lib], E);
+  }
+}
 
 // ObjectID stuff is imported directly without registering a sub-module.
 from('objectid', 'randomNumber', 'InternalObjectId');
@@ -165,12 +128,12 @@ from('objectid', 'randomNumber', 'InternalObjectId');
 from('meta', 'stacktrace', 'AbstractClass', 'Functions', 'NYI');
 
 /**
- * Create a magic *Enum* object
+ * Create a magic *Enum* object «Lazy»
  * @name module:@lumjs/core.Enum
  * @function
  * @see module:@lumjs/core/enum
  */
-can('Enum', {module: 'enum'});
+lazy(exports, 'Enum', () => require('./enum'), E);
 
 /**
  * Make an object support the *Observable* API «Lazy»
@@ -178,4 +141,4 @@ can('Enum', {module: 'enum'});
  * @function
  * @see module:@lumjs/core/observable
  */
-can('observable');
+lazy(exports, 'observable', () => require('./observable'), E);

package/lib/types/def.js

@@ -221,4 +221,8 @@ function def(obj, name, value, opts)
 
 } // def()
 
-module.exports = def;
+module.exports = def;
+
+// Now we'll setup the descriptor template accessors.
+const DT = require('./dt');
+DT.addTo(def);

package/lib/types/dt.js

@@ -0,0 +1,70 @@
+const def = require('./def');
+
+/**
+ * Build a descriptor template using a simple property syntax.
+ * 
+ * TODO: document this further.
+ * 
+ * @alias module:@lumjs/core/types~DescriptorTemplate
+ */
+function DescriptorTemplate()
+{
+  if (!new.target) return new DescriptorTemplate();
+  def(this, '_v', true);
+}
+
+const dp = DescriptorTemplate.prototype;
+
+function pa(prop)
+{
+  return(
+  {
+    get() 
+    { // Set a regular, enumerable, writable value.
+      this[prop] = this._v;
+      return this;
+    }
+  });
+}
+
+function va(value)
+{
+  return(
+  {
+    get()
+    { // Set a hidden, but configurable value. 
+      def(this, '_v', value);
+      return this;
+    }
+  });
+}
+
+def(dp, 'is',  va(true));
+def(dp, 'not', va(false));
+def(dp, 'e', pa('enumerable'));
+def(dp, 'c', pa('configurable'));
+def(dp, 'w', pa('writable'));
+
+function na(accessor)
+{
+  return(
+  {
+    get()
+    {
+      const dt = new DescriptorTemplate();
+      return dt[accessor];
+    }
+  });
+}
+
+const DTA = ['is','not','e','c','w'];
+
+DescriptorTemplate.addTo = function(target)
+{
+  for (const a of DTA)
+  {
+    def(target, a, na(a));
+  }
+}
+
+module.exports = DescriptorTemplate;

package/lib/types/lazy.js

@@ -24,6 +24,8 @@ const {doesDescriptor} = require('./basics');
  * If this is `false`, the value will be returned, but will **not** be 
  * *assigned*, so the lazy accessor property will remain.
  * 
+ * Leave it `undefined` to use the default assignment behaviour.
+ * 
  * @property {*} [def] Special options for `def()`
  * 
  * The [def()]{@link module:@lumjs/core/types.def} function has an
@@ -210,4 +212,7 @@ function lazy(target, name, initfunc, opts={})
 // Gotta be one of the greatest lines...
 def(def, 'lazy', lazy);
 
+// And this is a close second...
+def(lazy, 'def', def);
+
 module.exports = lazy;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "main": "lib/index.js",
   "exports":
   {
@@ -12,7 +12,6 @@
     "./flags": "./lib/flags.js",
     "./obj": "./lib/obj/index.js",
     "./opt": "./lib/opt.js",
-    "./modulebuilder": "./lib/modulebuilder.js",
     "./modules": "./lib/modules.js",
     "./meta": "./lib/meta.js",
     "./enum": "./lib/enum.js",
@@ -27,12 +26,11 @@
   },
   "devDependencies":
   {
-    "@lumjs/tests": "^1.3.0"
+    "@lumjs/tests": "^1.7.1"
   },
   "scripts":
   {
-    "-TODO-1": "Use `lumtest` once its available",
-    "test": "prove -e node --ext js ./test",
+    "test": "node ./node_modules/@lumjs/tests/bin/lumtest.js",
     "build-docs": "jsdoc -c ./jsdoc.json"
   }
 }

package/lib/modulebuilder.js

@@ -1,367 +0,0 @@
-
-const 
-{
-  S,F,B,
-  isObj,needObj,needType,
-  def,lazy
-} = require('./types');
-
-const clone = require('./obj/copyall').duplicateOne;
-
-// Methods we want to export in the functional API.
-const BUILD_METHODS = ['has', 'can', 'from', 'set'];
-
-/**
- * A class to make building modules easier.
- * 
- * Basically wraps calls to `require()`, `def()`, `lazy()`,
- * and assignments to `module.exports` into a simple set of methods.
- * 
- * @exports module:@lumjs/core/modulebuilder
- */
-class ModuleBuilder
-{
-  /**
-   * Build a new ModuleBuilder instance.
-   * 
-   * @param {object} targetModule - The `module` context variable.
-   * @param {object} [opts] - Options to change some default settings.
-   * @param {boolean} [opts.configurable=false] Default `configurable` value.
-   * @param {boolean} [opts.enumerable=true] Default `enumerable` value.
-   * @param {boolean} [opts.writable=false] Default `writable` value.
-   * 
-   * @param {number} [opts.nested=NESTED_ERROR] How to handle nested names.
-   * 
-   * If the `name` parameter in either the `has()` or `can()` method is passed 
-   * as the path to a nested module with one or more `/` characters, 
-   * this mode will determine how we derive the property name. 
-   * 
-   * For each mode, we'll use an example `name` of `./some/nested/path`.
-   * 
-   * - `ModuleBuilder.NESTED_ERROR` `[0]` (default mode)
-   *   Throw an `Error` saying paths are unhandled.
-   * - `ModuleBuilder.NESTED_FIRST` `[1]`
-   *   Use the first (non-dot) path element, e.g. `some`
-   * - `ModuleBuilder.NESTED_LAST` `[2]`
-   *   Use the last path element, e.g. `path`
-   * - `ModuleBuilder.NESTED_CAMEL` `[3]`
-   *   Convert the name to camelCase, e.g. `someNestedPath`
-   * 
-   * It's always possible to set the `conf.module` parameter manually as well,
-   * which avoids the need to generate a separate parameter name.
-   * 
-   */
-  constructor(targetModule, opts={})
-  {
-    needObj(opts, 'opts was not an object');
-    needObj(targetModule, 'targetModule was not an object');
-    needObj(targetModule.exports, 'targetModule.exports was not an object');
-    needType(F, targetModule.require, 'targetModule.require was not a function');
-
-    this.module = targetModule;
-
-    this.configurable = opts.configurable ?? false;
-    this.enumerable   = opts.enumerable   ?? true;
-    this.writable     = opts.writable     ?? false;
-
-    this.nested = opts.nested ?? ModuleBuilder.NESTED_ERROR;
-
-    this.strings = opts.strings;
-    this.locale = opts.locale;
-  }
-
-  // Get a descriptor for a module export.
-  requireDescriptor(name, conf={})
-  {
-    if (typeof conf.getter === F || typeof conf.setter === F)
-    { // It's an accessor-style descriptor already.
-      return conf;
-    }
-
-    let value = conf.value;
-    
-    if (value === undefined)
-    {
-      if (typeof conf.module === S)
-        name = conf.module; 
-      if (!name.startsWith('./'))
-        name = './'+name;
-
-      value = this.module.require(name);
-
-      if (value && conf.prop && value[conf.prop] !== undefined)
-      { 
-        value = value[conf.prop];
-      }
-    }
-
-    const configurable = conf.configurable ?? this.configurable;
-    const enumerable   = conf.enumerable   ?? this.enumerable;
-    const writable     = conf.writable     ?? this.writable;
-
-    return {configurable, enumerable, writable, value};
-  }
-
-  // Normalize a property name.
-  $normalizeProperty(name)
-  {
-    if (name.startsWith('./'))
-    { // Get rid of the prefix.
-      name = name.substring(2);
-    }
-
-    if (name.includes('/'))
-    { // Multiple paths found.
-      const names = name.split('/');
-      if (this.nested === ModuleBuilder.NESTED_FIRST)
-      {
-        name = names[0];
-      }
-      else if (this.nested === ModuleBuilder.NESTED_LAST)
-      {
-        name = names[names.length-1];
-      }
-      else if (this.nested === ModuleBuilder.NESTED_CAMEL)
-      {
-        name = this.$normalizeWithCamelCase(names);
-      }
-      else 
-      {
-        throw new Error("No valid nested path handling method was set");
-      }
-    }
-
-    return name;
-  }
-
-  $normalizeWithCamelCase(names)
-  {
-    if (this.strings === undefined)
-    {
-      this.strings = require('./strings');
-    }
-    if (this.locale === undefined)
-    {
-      this.locale = this.strings.getLocale();
-    }
-    let name = names.shift().toLocaleLowerCase(this.locale);
-    for (const path in names)
-    {
-      name += this.strings.ucfirst(path, true, this.locale);
-    }
-    return name;
-  }
-  
-  /**
-   * Export a module directly.
-   * 
-   * @param {string} name - The property name to export.
-   *
-   * @param {object} [conf] Additional export configuration options.
-   * @param {string} [conf.module=`./${name}`] The module to `require()`.
-   * @param {string} [conf.prop] If set, we want an exported property
-   * of this name from the loaded module.
-   * 
-   * If not set, the entire loaded module will be our exported value.
-   * 
-   * @param {boolean} [conf.configurable=this.configurable] 
-   * Descriptor `configurable` value.
-   * @param {boolean} [conf.enumerable=this.enumerable] 
-   * Descriptor `enumerable` value.
-   * @param {boolean} [conf.writable=this.writable] 
-   * Descriptor `writable` value.
-   * 
-   * @param {*} [conf.value] An explicit value to set.
-   * 
-   * This skips the `require()` call entirely.
-   * 
-   * @returns {object} `this`
-   */
-  has(name, conf={})
-  {
-    const pname = this.$normalizeProperty(name);
-    const desc = this.requireDescriptor(name, conf);
-    def(this.module.exports, pname, desc);
-    return this;
-  }
-
-  /**
-   * Export a lazy-loaded module.
-   * 
-   * @param {string} name - The property name to export.
-   * 
-   * @param {object} [conf] Additional export configuration options.
-   * 
-   * In addition to all the options supported by 
-   * [has()]{@link module:@lumjs/core/modules.has}
-   * this also supports one further option.
-   * 
-   * @param {object} [conf.lazy] Advanced options for the `lazy()` call.
-   * 
-   * If not specified, sane defaults will be used, that ensures the
-   * `enumerable` descriptor property for the lazy getter is set the
-   * same as the final descriptor property once its loaded.
-   * 
-   * @returns {object} `this`
-   */
-  can(name, conf={})
-  {
-    const pname = this.$normalizeProperty(name);
-    const enumerable = conf.enumerable ?? this.enumerable;
-    const lazyOpts = isObj(conf.lazy) ? conf.lazy : {enumerable};
-    const getter = () => this.requireDescriptor(name, conf);
-    lazy(this.module.exports, pname, getter, lazyOpts);
-    return this;
-  }
-
-  /**
-   * Re-export some exported properties from a module.
-   * 
-   * By default this uses `has()` to define the exports, but that
-   * can be changed using special parameter values.
-   * 
-   * @param {string} modname - The module to export the properties from.
-   * @param  {...any} libs - What we're exporting.
-   * 
-   * If this is a `string` it is the name of an exported property we want to
-   * re-export directly.
-   * 
-   * If this is `true`, all subsequent values will be exported using `can()`.
-   * 
-   * If this is `false`, all subsequent values will be exported using `has()`.
-   * 
-   * If this is an `object`, then it's considered the `conf` parameter for
-   * the `has()` or `can()` methods. If the `conf` does not have a `module`
-   * property, the `modname` will be assigned as the `module` property.
-   * You cannot set the `prop` property, as it's overwritten for every 
-   * exported property.
-   * 
-   * @returns {object} `this`
-   */
-  from(modname, ...libs)
-  {
-    let func = 'has';
-    let curConf = {module: modname};
-    for (const lib of libs)
-    {
-      if (isObj(lib))
-      { // Change the current config.
-        curConf = clone(lib);
-        if (curConf.module === undefined)
-        { // Make sure the module name is assigned.
-          curConf.module = modname;
-        }
-      }
-      else if (typeof lib === B)
-      { // Change the function we're calling.
-        func = lib ? 'can' : 'has';
-      }
-      else if (typeof lib === S)
-      {
-        const conf = clone(curConf);
-        conf.prop = lib;
-        this[func](lib, conf);
-      }
-      else 
-      {
-        throw new TypeError("libs must be strings, booleans, or objects");
-      }
-    }
-    return this;
-  }
-
-  /**
-   * Define an exported property in our module.
-   * 
-   * This is literally just a wrapper around the
-   * [def()]{@link module:@lumjs/core/types.def} method,
-   * that passes `this.module.exports` as the `obj` parameter.
-   * 
-   * @param {*} name - See `def()` for details.
-   * @param {*} value - See `def()` for details.
-   * @param {*} opts - See `def()` for details.
-   * @returns {(object|function)} What is returned may vary:
-   * 
-   * If the `def()` returns a *bound* copy of itself, we'll return that
-   * bound function directly.
-   * 
-   * In any other case, we return `this` ModuleBuilder instance.
-   */
-  set(name, value, opts)
-  {
-    const retval = def(this.module.exports, name, value, opts);
-    if (typeof retval === F && isObj(retval.$this) && retval.$this.bound === retval)
-    { // A bound copy was returned, we're going to return it directly.
-      return retval;
-    }
-    return this;
-  }
-
-  /**
-   * Create a functional API for the ModuleBuilder class.
-   * 
-   * Basically makes a new `ModuleBuilder` instance, then creates standalone 
-   * closure functions that wrap the main instance methods.
-   * 
-   * These functions can be imported into a namespace directly.
-   * They each have a special `builder` property which is a reference
-   * to the underlying `ModuleBuilder` instance.
-   * 
-   * There's also a `builder` property in the exported function list,
-   * as well as a copy of the `def()` method for quick exporting.
-   * 
-   * Example usage:
-   * 
-   * ```js
-   * const {has,can,from,set} 
-   *  = require('@lumjs/core').ModuleBuilder.build(module);
-   * // or the shortcut: require('@lumjs/core).buildModule(module);
-   * 
-   * // exports.foo = require('./foo');
-   * has('foo'); 
-   * 
-   * // exports.someNestedPath = require('./some/nested/path');
-   * has('./some/nested/path'); 
-   * 
-   * ```
-   * 
-   * @param {object} targetModule - The `module` for the Builder instance.
-   * @param {object} [opts] - Any options for the Builder instance.
-   * @returns {object} An object containing the closure functions.
-   */
-  static build(targetModule, opts)
-  {
-    const builder = new this(targetModule, opts);
-    const funcs = {builder, def};
-    for (const name of BUILD_METHODS)
-    {
-      const func = function()
-      {
-        return builder[name](...arguments);
-      }
-      def(func, 'builder', builder);
-      funcs[name] = func;
-    }
-    return funcs;
-  }
-
-  /**
-   * A static alternative to `new ModuleBuilder()`;
-   * 
-   * @param {object} targetModule 
-   * @param {object} [opts] 
-   * @returns {object} The new `ModuleBuilder` instance.
-   */
-  static new(targetModule, opts)
-  {
-    return new this(targetModule, opts);
-  }
-
-}
-
-def(ModuleBuilder, 'NESTED_ERROR', 0)
-def(ModuleBuilder, 'NESTED_FIRST', 1);
-def(ModuleBuilder, 'NESTED_LAST',  2);
-def(ModuleBuilder, 'NESTED_CAMEL', 3);
-
-module.exports = ModuleBuilder;