@lumjs/core 1.26.0 → 1.31.0

package/lib/types/def.js

@@ -2,29 +2,27 @@
 const unbound = require('./root').unbound;
 const {F, B} = require('./js');
 const {isObj, isNil, isProperty, doesDescriptor} = require('./basics');
-const {copy, duplicateOne: clone} = require('../obj/copyall');
+const clone = (...args) => Object.assign({}, ...args);
 
 /**
- * A wrapper around `Object.defineProperty()`.
- * 
- * This has a few features that makes adding properties a lot nicer.
- * It replaces the `prop()` method from the old Lum.js v4.
+ * A wrapper around `Object.defineProperty()` with added flair!
  * 
  * @param {(object|function)} obj - The object to add a property to.
+ * 
  * @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.
+ * `obj` already passed as the first parameter. It will generate context
+ * options which will compose the enumerable properties of `opts` if
+ * that argument is passed.
  * 
  * 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 
+ * If this is an `object`, the `value` will be ignored, 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.
  * 
@@ -101,6 +99,40 @@ function def(obj, name, value, opts)
     = !unbound(this, true, true) 
     && typeof this.bound === F;
 
+  if (isNil(name) || typeof name === B)
+  { // Binding of Isaac?
+    const bindOpts = (to) =>
+    {
+      Object.assign(to, opts);
+      if (typeof name === B) to.enumerable = name;
+      return to;
+    }
+
+    if (isBound)
+    { // Already bound, update options and return.
+      return bindOpts(this).bound;
+    }
+
+    const V = (value) => ({value, configurable: false});
+
+    // Create a fresh binding context for the bound function.
+    const bind = bindOpts({});
+    // Create a bound function.
+    const bound = def.bind(bind, obj);
+    // Add a reference to the function in the binding context.
+    def(bind, 'bound', V(bound));
+    // And a reference to the binding options from the function.
+    def(bound, '$this', V(bind));
+
+    if (value)
+    { // Add DescriptorTemplate magic properties.
+      const dopts = clone(value, {desc: bind});
+      DT.addInstance(bound, dopts);
+    }
+
+    return bound;
+  }
+
   // When we're finished, return this value.
   const done = () => 
   { 
@@ -114,9 +146,12 @@ function def(obj, name, value, opts)
     }
   }
 
-  if (isBound && isNil(opts))
-  { // We'll use `this` as the options.
-    opts = this;
+  if (isBound)
+  { // Assign `this` options.
+    if (isNil(opts)) 
+      opts = this;
+    else if (isObj(opts))
+      opts = clone(this, opts);
   }
 
   if (isObj(name))
@@ -128,29 +163,6 @@ function def(obj, name, value, opts)
     // Okay, we're done now.
     return done();
   }
-  else if (isNil(name) || typeof name === B)
-  { // Create a fresh binding context for the bound function.
-    const bind = {};
-
-    if (isObj(opts))
-    { // Copy our existing options as defaults.
-      copy(bind, opts);
-    }
-
-    if (typeof name === B)
-    { // A boolean `name` overrides the enumerable option.
-      bind.enumerable = name;
-    }
-
-    // Create a bound function.
-    const bound = def.bind(bind, obj);
-    // Add a reference to the function in the binding context.
-    bind.bound = bound;
-    // And a reference to the binding options from the function.
-    bound.$this = bind;
-
-    return bound;
-  }
   else if (!isProperty(name))
   { // That's not valid.
     throw new TypeError("Property name must be a string or a Symbol");
@@ -225,4 +237,5 @@ module.exports = def;
 
 // Now we'll setup the descriptor template accessors.
 const DT = require('./dt');
-DT.addTo(def);
+DT.addInit(def);
+def.DT = DT;

package/lib/types/dt.js

@@ -1,16 +1,65 @@
 const def = require('./def');
+const {F} = require('./js');
+const {isObj,isProperty} = require('./basics');
+
+const V = Symbol('@lumjs/core/types~dt:V');
+const A = Object.freeze(
+{
+  i: 'is',
+  n: 'not',
+  e: 'e',
+  c: 'c',
+  w: 'w',
+  v: 'val',
+  g: 'getter',
+  s: 'setter',
+  d: 'desc',
+  p: 'dt',
+});
+const P = Object.freeze(
+{
+  e: 'enumerable',
+  c: 'configurable',
+  w: 'writable',
+  g: 'get',
+  s: 'set',
+  v: 'value',
+});
 
 /**
  * Build a descriptor template using a simple property syntax.
  * 
- * TODO: document this further.
+ * Generally used via magic properties on the `def` function:
+ * 
+ * ```js
+ * def(o1, 'p1', val1, def.e);     // Add 'enumerable' property.
+ * def(o2, 'p2', val2, def.not.c); // Remove 'configurable' status.
+ * ```
+ * 
+ * The supported magic properties are:
+ * 
+ * | Prop  | Description                                               |
+ * | ----- | --------------------------------------------------------- |
+ * | `is`  | Make subsequent rule accessors set their value to `true`  |
+ * | `not` | Make subsequent rule accessors set their value to `false` |
+ * | `c`   | Accessor that sets `configurable` descriptor rule value   |
+ * | `e`   | Accessor that sets `enumerable` descriptor rule value     |
+ * | `w`   | Accessor that sets `writable` descriptor rule value       |
  * 
+ * Similar magic properties may be added to bound instances of `def`;
+ * I'll add further docs for that later. Look at the tests for examples.
+ * 
+ * The constructor function is also available via `def.DT`,
+ * but using the built-in properties is easier.
+ * 
+ * @class
  * @alias module:@lumjs/core/types~DescriptorTemplate
  */
-function DescriptorTemplate()
+function DescriptorTemplate(opts={})
 {
-  if (!new.target) return new DescriptorTemplate();
-  def(this, '_v', true);
+  if (!new.target) return new DescriptorTemplate(opts);
+  def(this, V, true);
+  def(this, A.d, {value: (isObj(opts.desc) ? opts.desc : this)});
 }
 
 const dp = DescriptorTemplate.prototype;
@@ -21,7 +70,7 @@ function pa(prop)
   {
     get() 
     { // Set a regular, enumerable, writable value.
-      this[prop] = this._v;
+      this[A.d][prop] = this[V];
       return this;
     }
   });
@@ -33,38 +82,118 @@ function va(value)
   {
     get()
     { // Set a hidden, but configurable value. 
-      def(this, '_v', 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 af(p)
+{
+  return function(fn)
+  {
+    const d = this[A.d];
+    delete d[P.v];
+    delete d[P.w];
+    d[p] = fn;
+    return this;
+  }
+}
 
-function na(accessor)
+def(dp)
+  (A.i, va(true))
+  (A.n, va(false))
+  (A.e, pa(P.e))
+  (A.c, pa(P.c))
+  (A.w, pa(P.w))
+  (A.g, af(P.g))
+  (A.s, af(P.s))
+  (A.v, function(v1, v2)
+  { // A function to set a value with.
+    const d = this[A.d];
+    if (typeof v2 === F && typeof v1 === F)
+    {
+      delete d[P.v];
+      delete d[P.w];
+      d.get = v1;
+      d.set = v2;
+    }
+    else
+    {
+      delete d.get;
+      delete d.set;
+      d.value = v1;
+    }
+    return this;
+  })
+; // def(dp)
+
+// for addInit()
+function na(dp, opts)
 {
   return(
   {
     get()
-    {
-      const dt = new DescriptorTemplate();
-      return dt[accessor];
+    { 
+      const dt = new DescriptorTemplate(opts);
+      return dt[dp];
     }
   });
 }
 
-const DTA = ['is','not','e','c','w'];
+// For addInstance()
+function ni(ip, dp)
+{
+  return(
+  {
+    get()
+    { 
+      this[ip][dp];
+      return this;
+    }
+  });
+}
 
-DescriptorTemplate.addTo = function(target)
+const DTA = [A.i,A.n,A.e,A.c,A.w];
+
+DescriptorTemplate.addInit = function(target, opts={})
 {
   for (const a of DTA)
   {
-    def(target, a, na(a));
+    def(target, a, na(a, opts));
+  }
+}
+
+DescriptorTemplate.addInstance = function(target, opts={})
+{
+  const prop = isProperty(opts.prop) ? opts.prop : A.p;
+  const dt = new DescriptorTemplate(opts);
+
+  def(target, prop, {value: dt});
+
+  for (const a of DTA)
+  {
+    def(target, a, ni(prop, a));
   }
+
+  return target;
 }
 
 module.exports = DescriptorTemplate;
+
+/**
+ * Set a data value or accessor getter/setter combo.
+ * 
+ * @function module:@lumjs/core/types~DescriptorTemplate#val
+ * 
+ * @param {mixed} v1 - Value to assign, or Getter function
+ * 
+ * This is used as a Getter is if `v2` is also a `function`.
+ * In any other case this will assign a data `value` property.
+ * 
+ * @param {function} [v2] - Setter function
+ * 
+ * This is only used if `v1` is also a `function`.
+ * 
+ * @returns {object} `this`
+ */

package/lib/types/index.js

@@ -1,71 +1,44 @@
+"use strict";
+
 /**
- * Fundamental Types sub-module.
+ * The complete `types` module.
  * 
  * As `@lumjs/core` is the foundation for all my JS libraries,
- * this sub-module is the foundation for `@lumjs/core`.
- * Everything else is built upon this.
+ * this module is the foundation for `@lumjs/core`.
  * 
  * @module @lumjs/core/types
- * @property {string} O - "object"
- * @property {string} F - "function"
- * @property {string} S - "string"
- * @property {string} B - "binary"
- * @property {string} N - "number"
- * @property {string} U - "undefined"
- * @property {string} SY - "symbol"
- * @property {string} BI - "bigint"
  */
 
-// Constants representing core Javascript types.
-const {O, F, S, B, N, U, SY, BI} = require('./js');
-
-// Basic type check functions.
-const 
-{
-  isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
-  nonEmptyArray, isArguments, isProperty, doesDescriptor, isIterable,
-  isConstructor, doesDescriptorTemplate,
-} = require('./basics');
-
-// Root namespace helpers.
-const {root, unbound} = require('./root');
-
-// Advanced type checks.
-const 
-{
-  isInstance, isType, isa,
-  isArrayOf, isListOf, isMapOf, isObjOf, OfTest,
-} = require('./isa');
-
-// Error-throwing type checks.
-const {needObj, needType, needs} = require('./needs');
-
-// A few standalone items.
-
-const def   = require('./def');
-const lazy  = require('./lazy');
-const TYPES = require('./typelist');
-const stringify = require('./stringify');
-const ownCount = require('./owncount');
-
-// An alias for legacy reasons.
-const console = require('../console');
-
-// Okay, add all those to our exports.
-// Further tests can be added by `TYPES.add()` later.
-module.exports =
+const def = require('./def'), lazy = require('./lazy');
+
+// Compose in sub-modules.
+Object.assign(exports,
+  require('./basics'), 
+  require('./root'),
+  require('./isa'),
+  require('./needs'),
+  { // A few standalone exports.
+    def, lazy,
+    TYPES: require('./typelist'),
+    stringify: require('./stringify'),
+    ownCount: require('./owncount'),
+  },
+);
+
+// Replace the configurable constant props with readonly ones
+exports.JS.addTo(exports);
+
+// Deprecated alias for `console` module, lazy-loaded if requested.
+const {wrapDepr} = require('../meta');
+wrapDepr(exports, 'console',
 {
-  O, F, S, B, N, U, SY, BI, TYPES, root, unbound, def, lazy,
-  isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray, 
-  nonEmptyArray, isArguments, isProperty, doesDescriptor, 
-  isInstance, isType, isa, needObj, needType, needs, stringify,
-  doesDescriptorTemplate, ownCount, isIterable, isConstructor,
-  isArrayOf, isListOf, isMapOf, isObjOf, OfTest, 
-  console,
-}
+  dep: 'core.types.console',
+  rep: 'core.console',
+  get: () => require('../console'),
+});
 
 // This will be the module for TYPES.add()
-def(TYPES, '$module', module);
+def(exports.TYPES, '$module', module);
 
 // Extend `unbound` with add() and remove() methods.
-require('./unbound/extend')(unbound);
+require('./unbound/extend')(exports.unbound);

package/lib/types/isa.js

@@ -16,6 +16,7 @@ const def = require('./def');
  */
 function isInstance(v, f, needProto=false) 
 {
+  deprecated('types.isInstace','instanceof');
   if (!isObj(v)) return false; // Not an object.
   if (needProto && (typeof v.prototype !== O || v.prototype === null))
   { // Has no prototype.
@@ -909,3 +910,6 @@ def(isPlainObjectOf, 'rules', function()
 });
 
 exports.isObjOf = isPlainObjectOf;
+
+// Just in case let's load this down here.
+const {deprecated} = require('../meta');

package/lib/types/js.js

@@ -1,12 +1,48 @@
-// Fundamental core types.
-const O='object', F='function', S='string', B='boolean', N='number',
-      U='undefined', SY='symbol', BI='bigint';
+"use strict";
 
 /**
- * One or two character identifiers for the core JS type names.
+ * An absolutely minimal map of one or two letter string constants
+ * representing all of the fundamental JS types.
+ * 
+ * This object is *frozen* and cannot be modified in any way!
  * 
  * These are only the strings returned by the `typeof` operator.
- * See the `TYPES` object (defined in `typelist.js`) for a list
- * that includes special types and compound pseudo-types, etc.
+ * See {@link module:@lumjs/core/types.TYPES} for a much more complete
+ * list that includes special types and compound pseudo-types, etc.
+ * 
+ * @prop {string} O - object
+ * @prop {string} F - function
+ * @prop {string} S - string
+ * @prop {string} B - boolean
+ * @prop {string} N - number
+ * @prop {string} U - undefined
+ * @prop {string} SY - symbol
+ * @prop {string} BI - bigint
+ * 
+ * @memberof module:@lumjs/core/types/basics
  */
-module.exports = {O, F, S, B, N, U, SY, BI};
+const JS =
+{
+  O:  'object', 
+  F:  'function', 
+  S:  'string', 
+  B:  'boolean', 
+  N:  'number', 
+  U:  'undefined', 
+  SY: 'symbol',
+  BI: 'bigint',
+}
+
+function addTo(target)
+{
+  for (const key in this)
+  {
+    const value = this[key];
+    const desc = {value, enumerable: true};
+    Object.defineProperty(target, key, desc);
+  }
+}
+
+Object.defineProperty(JS, 'addTo', {value: addTo});
+
+module.exports = Object.freeze(JS);

package/lib/types/lazy.js

@@ -41,6 +41,7 @@ const {doesDescriptor} = require('./basics');
  * A function to generate the property value.
  * 
  * @callback module:@lumjs/core/types~LazyGetter 
+ * @param {module:@lumjs/core/types~LazyDef} info - A metadata object
  * @returns {*} The generated *value* of the property
  * 
  * By default if this is `undefined` the value will **not** be
@@ -60,7 +61,7 @@ const {doesDescriptor} = require('./basics');
  * Regardless of the value of `this.assign`, this value will
  * be *returned* as the property value.
  * 
- * @this {module:@lumjs/core/types~LazyDef} A metadata object.
+ * @this {module:@lumjs/core/types~LazyDef} The `info` metadata object
  */
 
 /**
@@ -194,7 +195,7 @@ function lazy(target, name, initfunc, opts={})
 
   desc.get = function()
   { 
-    return defval(initfunc.call(context));
+    return defval(initfunc.call(context,context));
   }
 
   if (typeof opts.set === F)

package/lib/types/needs.js

@@ -1,7 +1,6 @@
 const {F, S, B} = require('./js');
 const {isType, isa} = require('./isa');
 const {isObj, isComplex} = require('./basics');
-const console = require('../console');
 
 /**
  * If a value is not an object, throw an error.

package/lib/types/typelist.js

@@ -9,12 +9,14 @@ const
 /**
  * A map of **Types**, including *special* and *union* types.
  * 
- * Contains the same `O, F, S, B, N, U, SY, BI` properties as also
- * found in the top-level {@link module:@lumjs/core/types} module.
- * While most of the core JS types simply use `typeof` as their
+ * Contains the constants from {@link module:@lumjs/core/types/basics.JS},
+ * plus a whole bunch of _special types_ that require tests other than
+ * `typeof` to determine if a given value matches that type.
+ * 
+ * Also, while MOST of the core JS types simply use `typeof` as their
  * test, this maps the `O` (`object`) type to the `isObj` test.
  * 
- * Will also contain a few helper functions, and a map of tests
+ * It also contain a few helper functions, and a map of tests
  * that are used by `isType`, `isa`, `needType`, and `needs`.
  * Any one of these properties may be passed to those functions as
  * the desired *type* a desired value must be.

package/lum.build.js

@@ -0,0 +1,40 @@
+"use strict";
+
+const D =
+{
+  build: 'docs/build',
+  api: 'docs/api/',
+  changelogs: 'docs/changelogs',
+  ad(from)
+  {
+    const to = D.api+from.replace(/\.md/, '.html');
+    return {from,to}
+  },
+}
+
+const dirs = 
+[
+  D.build,
+  D.api+D.changelogs,
+]
+
+const header = "<html><body>";
+const footer = "</body></html>";
+
+const files = 
+[
+  {
+    from: 'README.md', 
+    to: D.build+'/README.md',
+  },
+  D.ad('docs/TODO.md'),
+  D.ad(D.changelogs+'/index.md'),
+  D.ad(D.changelogs+'/1.0-beta.md'),
+  D.ad(D.changelogs+'/1.x.md'),
+  D.ad(D.changelogs+'/2.x.md'),
+]
+
+module.exports =
+{
+  dirs, files, header, footer,
+}

package/package.json

@@ -1,41 +1,51 @@
 {
   "name": "@lumjs/core",
-  "version": "1.26.0",
+  "version": "1.31.0",
   "main": "lib/index.js",
-  "exports":
+  "exports": 
   {
     ".": "./lib/index.js",
-
     "./arrays": "./lib/arrays/index.js",
     "./console": "./lib/console.js",
     "./context": "./lib/context.js",
     "./enum": "./lib/enum.js",
+    "./events": "./lib/events/index.js",
     "./flags": "./lib/flags.js",
     "./maps": "./lib/maps.js",
     "./meta": "./lib/meta.js",
     "./modules": "./lib/modules.js",
     "./obj": "./lib/obj/index.js",
+    "./obj/cp": "./lib/obj/cp.js",
     "./observable": "./lib/observable.js",
-    "./opt": "./lib/opt.js",
+    "./opt": "./lib/opt/index.js",
+    "./opt/args": "./lib/opt/args.js",
     "./strings": "./lib/strings.js",
     "./traits": "./lib/traits.js",
     "./types": "./lib/types/index.js",
-
+    "./types/basics": "./lib/types/basics.js",
+    "./types/def": "./lib/types/def.js",
     "./package.json": "./package.json"
   },
-  "license": "MIT",
-  "repository":
+  "dependencies": 
   {
-    "type": "git",
-    "url": "https://github.com/supernovus/lum.core.js.git"
+    "@lumjs/opts": "^1.0.0"
   },
-  "devDependencies":
+  "devDependencies": 
   {
-    "@lumjs/tests": "^1.8.0"
+    "@lumjs/build": "^1.0.0",
+    "@lumjs/tests": "^2.0.0"
   },
-  "scripts":
+  "scripts": 
   {
     "test": "lumtest.js",
-    "build-docs": "jsdoc -c ./jsdoc.json"
-  }
+    "build-meta": "lum-build",
+    "build-jsdoc": "jsdoc -c ./jsdoc.js",
+    "build-docs": "npm run build-meta && npm run build-jsdoc"
+  },
+  "repository": 
+  {
+    "type": "git",
+    "url": "https://github.com/supernovus/lum.core.js.git"
+  },
+  "license": "MIT"
 }