@lumjs/core 1.25.2 → 1.30.0

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.
+ * 
+ * @class
  * @alias module:@lumjs/core/types~DescriptorTemplate
+ * 
+ * The constructor function is also available via `def.DT`,
+ * but using the built-in properties is easier.
  */
-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,47 @@
+"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`.
+ * 
+ * Re-exports everything from the {@link @lumjs/core/types/basics}
+ * sub-module with the same names, and adds a whole lot more!
  * 
  * @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,29 @@
-// Fundamental core types.
-const O='object', F='function', S='string', B='boolean', N='number',
-      U='undefined', SY='symbol', BI='bigint';
-
-/**
- * One or two character identifiers for the core JS type names.
- * 
- * 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.
- */
-module.exports = {O, F, S, B, N, U, SY, BI};
+"use strict";
+
+// A package-private collection of constants.
+// Exported as a part of `basics` and `index`.
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.25.2",
+  "version": "1.30.0",
   "main": "lib/index.js",
   "exports":
   {
@@ -16,10 +16,13 @@
     "./modules": "./lib/modules.js",
     "./obj": "./lib/obj/index.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"
   },
@@ -31,7 +34,8 @@
   },
   "devDependencies":
   {
-    "@lumjs/tests": "^1.8.0"
+    "@lumjs/opts": "^1.0.0",
+    "@lumjs/tests": "^2.0.0"
   },
   "scripts":
   {