@lumjs/core 1.0.0-beta.4 → 1.1.0

package/lib/types/basics.js

@@ -4,6 +4,7 @@ const {O, F, S, SY} = require('./js');
  * See if a value is a non-null `object`.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
+ * @alias module:@lumjs/core/types.isObj
  */
  function isObj(v) { return (typeof v === O && v !== null); }
 
@@ -12,6 +13,7 @@ const {O, F, S, SY} = require('./js');
   * Like `isObj()`, `null` does not count as an `object`.
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isComplex
   */
  function isComplex(v) { return (typeof v === F || isObj(v)); }
  
@@ -19,6 +21,7 @@ const {O, F, S, SY} = require('./js');
   * See if a value is *nil* (i.e. either `null` or `undefined`).
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isNil
   */
  function isNil(v) { return (v === undefined || v === null); }
  
@@ -26,6 +29,7 @@ const {O, F, S, SY} = require('./js');
   * See if a value is not *nil* (i.e. neither `null` nor `undefined`).
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.notNil
   */
  function notNil(v) { return (v !== undefined && v !== null); }
  
@@ -35,14 +39,17 @@ const {O, F, S, SY} = require('./js');
   * is neither *nil* nor *complex*.
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isScalar
   */
  function isScalar(v) { return (notNil(v) && !isComplex(v)); }
  
  /**
   * See if a value is an `Array` object.
   * This is literally just a copy of `Array.isArray`.
+  * @function
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isArray
   */
  const isArray = Array.isArray;
  
@@ -50,6 +57,7 @@ const {O, F, S, SY} = require('./js');
   * See if a value is a `TypedArray` object.
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isTypedArray
   */
  function isTypedArray(v)
  {
@@ -62,6 +70,7 @@ const {O, F, S, SY} = require('./js');
   * @param {boolean} [typed=false] If `true` we want a `TypedArray`.
   *   If `false` (default) we want a regular `Array`.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.nonEmptyArray
   */
  function nonEmptyArray(v, typed=false)
  {
@@ -75,6 +84,7 @@ const {O, F, S, SY} = require('./js');
   * See if a value is an `arguments` object.
   * @param {*} v - The value we're testing.
   * @returns {boolean}
+  * @alias module:@lumjs/core/types.isArguments
   */
  function isArguments(v) 
  {
@@ -85,6 +95,7 @@ const {O, F, S, SY} = require('./js');
  * See if a value is a Property name.
  * @param {*} v - The value we're testing.
  * @returns {boolean}
+ * @alias module:@lumjs/core/types.isProperty
  */
 function isProperty(v)
 {
@@ -93,22 +104,23 @@ function isProperty(v)
 }
 
 /**
- * See if an object can be used as a valid descriptor.
+ * See if an object can be used as a valid *descriptor*.
  * 
- * Basically in order to be considered a valid descriptor, 
+ * Basically in order to be considered a valid *descriptor*, 
  * one of the the following sets of rules must be true:
  * 
- *  - A Data Descriptor:
+ *  - A *Data descriptor*:
  *      - Has a `value` property.
  *      - Does not have a `get` property.
  *      - Does not have a `set` property.
- *  - An Accessor Descriptor:
+ *  - An *Accessor descriptor*:
  *      - Has a `get` and/or `set` property.
  *      - Does not have a `value` property.
  *      - Does not have a `writable` property.
  * 
  * @param {object} obj - The object we are testing. 
  * @returns {boolean} - Is the object a valid descriptor?
+ * @alias module:@lumjs/core/types.doesDescriptor
  */
  function doesDescriptor(obj)
  {
@@ -133,10 +145,56 @@ function isProperty(v)
    return false;
  }
 
- // Now export those.
- module.exports =
- {
-  isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
-  nonEmptyArray, isArguments, isProperty, doesDescriptor,
- }
- 
+/**
+ * See if an object can be used as a valid *descriptor template*.
+ * 
+ * This is similar to `doesDescriptor`, except that a *template*
+ * **must not** contain `value`, `get` or `set` properties.
+ * 
+ * @param {object} obj - The object we are testing.
+ * @param {boolean} [accessor=false] Template is for an Accessor.
+ *   If this is `true` then the `writable` property will also be forbidden.
+ * @param {boolean} [strict=true] Only allow valid descriptor properties.
+ *   If this is `true` then **only** allow `configurable`, `enumerable`, and
+ *   conditionally `writable` (only if `accessor` is `false`.)
+ *   If this is `false` then any unknown properties will be ignored.
+ * 
+ * @returns {boolean} Is the object a valid descriptor template?
+ * @alias module:@lumjs/core/types.doesDescriptorTemplate
+ */
+function doesDescriptorTemplate(obj, accessor=false, strict=true)
+{
+  if (!isObj(obj)) return false;
+
+  // Get a list of enumerable properties in the object.
+  const props = Object.keys(obj);
+
+  if (strict)
+  { // Strict enforcement, only valid descriptor properties allowed.
+    const valid = ['configurable', 'enumerable'];
+    if (!accessor) valid.push('writable');
+    for (const prop of props)
+    {
+      if (!valid.includes(prop)) return false;
+    }
+  }
+  else
+  { // Loose enforcement mode, reject on forbidden properties only.
+    const forbidden = ['value','get','set'];
+    if (accessor) forbidden.push('writable');
+    for (const prop of props)
+    {
+      if (forbidden.includes(prop)) return false;
+    }
+  }
+
+  // No tests failed, this can be used as a template.
+  return true;
+}
+
+// Now export those.
+module.exports =
+{
+isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
+nonEmptyArray, isArguments, isProperty, doesDescriptor, doesDescriptorTemplate,
+}

package/lib/types/def.js

@@ -4,6 +4,9 @@ const {F, B} = require('./js');
 const {isObj, isNil, isProperty, doesDescriptor} = require('./basics');
 const copy = require('../obj/copyall');
 
+// A really really cheap version of clone().
+const clone = obj => copy({}, obj);
+
 /**
  * A wrapper around `Object.defineProperty()`.
  * 
@@ -12,16 +15,22 @@ const copy = require('../obj/copyall');
  * 
  * @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.
  * 
  *   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. Can be useful if you
- *   need to add a lot of properties to the same object.
+ *   `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 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()`),
@@ -29,31 +38,29 @@ const copy = require('../obj/copyall');
  *   property defined, one will be added, and will be set to `true`.
  *   This behaviour may be overridden by the `opts` parameter.
  * 
- *   If this is a `function` and `opts` is a `boolean` or `function`,
- *   then this will be used as a getter or setter (see `opts` for details.)
+ *   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`.
  * 
- * @param {(object|function|boolean)} [opts] - A multi-purpose option.
+ * @param {*} [opts] - A multi-purpose option.
  * 
  *   If this is an `object` then it is reserved for named options.
- *   Any other use of this is dependent on the `value` parameter.
+ *   The named options `configurable`, `enumerable`, and `writable`
+ *   can be used to define default values to the descriptor properties
+ *   of the same name.
  * 
  *   If `value` and this are both `function` values, then `value` will
  *   be used as a *getter* and this will be used as a *setter*.
  * 
- *   If `value` is a `function` and this is `true`, then `value` will
- *   be used as a *getter* and no *setter* will be assigned.
- * 
- *   If `value` is a `function` and this is `false`, then `value` will
- *   be used as a *setter* and no *getter* will be assigned.
- * 
  *   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.
  * 
+ *   This defaults to `undefined`, except if 
+ * 
  * @returns {*} Normally the `obj` argument with new property added.
  * 
  *   The exception is if this is a bound copy of the function created
@@ -66,6 +73,7 @@ const copy = require('../obj/copyall');
  *   def(myObj)('name', "Bob")('age', 42);
  * ```
  * 
+ * @alias module:@lumjs/core/types.def
  */
 function def(obj, name, value, opts)
 {
@@ -132,17 +140,12 @@ function def(obj, name, value, opts)
 
   if (opts !== false && doesDescriptor(value))
   { // The value is a descriptor, let's use it.
-    desc = (opts === true) ? copy(value) : value;
+    desc = (opts === true) ? clone(value) : value;
   }
   else if (typeof value === F && typeof opts === F)
   { // A getter and setter were both specified.
     desc = {get: value, set: opts};
   }
-  else if (typeof value === F && typeof opts === B)
-  { // A function value with a boolean opts is a getter or setter.
-    const prop = opts ? 'get' : 'set';
-    desc = {[prop]: value};
-  }
   else 
   { // The value is just a value, so let's assign it.
     desc = {value};

package/lib/types/index.js

@@ -1,4 +1,20 @@
-/// Type checking and other features common to everything else.
+/**
+ * Fundamental Types sub-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.
+ * 
+ * @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');
@@ -8,6 +24,7 @@ const
 {
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
   nonEmptyArray, isArguments, isProperty, doesDescriptor,
+  doesDescriptorTemplate,
 } = require('./basics');
 
 // Root namespace helpers.
@@ -23,6 +40,7 @@ const {needObj, needType, needs} = require('./needs');
 
 const def   = require('./def');
 const TYPES = require('./typelist');
+const stringify = require('./stringify');
 
 // Okay, add all those to our exports.
 // Further tests can be added by `TYPES.add()` later.
@@ -31,7 +49,8 @@ module.exports =
   O, F, S, B, N, U, SY, BI, TYPES, root, unbound, def,
   isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray, 
   nonEmptyArray, isArguments, isProperty, doesDescriptor, 
-  isInstance, isType, isa, needObj, needType, needs,
+  isInstance, isType, isa, needObj, needType, needs, stringify,
+  doesDescriptorTemplate,
 }
 
 // Last but not least, this will be the module for TYPES.add()

package/lib/types/isa.js

@@ -8,6 +8,7 @@ const TYPES = require('./typelist');
  * @param {function} f - The constructor/class we want.
  * @param {boolean} [needProto=false] If true, the `v` must have a `prototype`.
  * @returns {boolean}
+ * @alias module:@lumjs/core/types.isInstance
  */
  function isInstance(v, f, needProto=false) 
  {
@@ -30,24 +31,15 @@ const TYPES = require('./typelist');
   * 
   * @param {string} type - The type we're checking for.
   * 
-  * This supports all the same type names as `typeof` plus:
-  * 
-  * - `arguments`   → An arguments object inside a function.
-  * - `array`       → An Array object.
-  * - `null`        → A null value.
-  * - `typedarray`  → One of the typed array objects.
-  * - `descriptor`  → An object which is a valid descriptor.
-  * - `complex`     → Either an `object` or a `function.
-  * - `scalar`      → Anything other than an `object` or `function`.
-  * - `property`    → A `string` or a `symbol`.
-  * - `nil`         → Either `null` or `undefined`.
+  * This supports all the same type names as `typeof` plus any of
+  * the properties defined in the `TYPES` object.
   * 
   * One other thing, while `typeof` reports `null` as being an `object`,
   * 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
   */
  function isType(type, v)
  {
@@ -138,6 +130,7 @@ const TYPES = require('./typelist');
   * Any other type value will only match if `v === type`
   * 
   * @returns {boolean} Was the value one of the desired types?
+  * @alias module:@lumjs/core/types.isa
   */
  function isa(v, ...types)
  {

package/lib/types/needs.js

@@ -9,6 +9,7 @@ const {isObj, isComplex} = require('./basics');
  * @param {boolean} [allowFunc=false] - Also accept functions?
  * @param {string} [msg] A custom error message.
  * @throws {TypeError} If the type check failed.
+ * @alias module:@lumjs/core/types.needObj
  */
 function needObj (v, allowFunc=false, msg=null)
 {
@@ -33,6 +34,7 @@ exports.needObj = needObj;
  * @param {*} v - The value we're testing.
  * @param {string} [msg] A custom error message.
  * @throws {TypeError} If the type check failed.
+ * @alias module:@lumjs/core/types.needType
  */
 function needType (type, v, msg, unused)
 {
@@ -77,7 +79,10 @@ const NEEDS_PARSER = function(type, v)
 * look for an `object` with a single property named `error`
 * which can be either a `string` or any subclass of `Error`.
 * If specified, it will override the error message that will be thrown.
-* 
+*
+* @throws {TypeError} If the type check failed.
+* @throws {Error} If a custom error was specified.
+* @alias module:@lumjs/core/types.needs
 */
 function needs(v, ...types)
 {

package/lib/types/root.js

@@ -9,6 +9,7 @@ function no_root()
 
 /**
  * The global root object. Usually `globalThis` these days.
+ * @alias module:@lumjs/core/types.root
  */
 const root = typeof globalThis !== U ? globalThis
   : typeof global !== U ? global 
@@ -32,6 +33,7 @@ const unboundObjects = [];
  *   If the is `true` we use an global list that can register special
  *   internal objects. Otherwise an `Array` of unbound objects may be used.
  * @returns {boolean}
+ * @alias module:@lumjs/core/types.unbound
  */
 function unbound(whatIsThis, rootIsUnbound=true, areUnbound=false)
 {
@@ -56,13 +58,11 @@ const def = require('./def');
 /**
  * Add an item to the unbound global objects list.
  * 
- * @method unbound.add 
- * 
+ * @function
  * @param {(object|function)} obj - The object to be considered unbound.
- * 
  * @returns {boolean} Will be `false` if `obj` is already unbound.
- * 
  * @throws {TypeError} If `obj` was neither an `object` nor a `function`.
+ * @alias module:@lumjs/core/types.unbound.add
  */
 def(unbound, 'add', function (obj)
 {
@@ -79,13 +79,11 @@ def(unbound, 'add', function (obj)
 /**
  * Remove an item from the unbound global objects list.
  * 
- * @method unbound.remove
- * 
+ * @function
  * @param {(object|function)} obj - The object to be removed.
- * 
  * @returns {boolean} Will be `false` if the item was not in the list.
- * 
  * @throws {TypeError} If `obj` was neither an `object` nor a `function`.
+ * @alias module:@lumjs/core/types.unbound.remove
  */
 def(unbound, 'remove', function(obj)
 {

package/lib/types/stringify.js

@@ -0,0 +1,142 @@
+// Get the extended type list.
+const TYPES = require('./typelist');
+const {isObj, isArray, isTypedArray} = require('./basics');
+const def = require('./def');
+
+const TOSTRING_TYPES = [TYPES.F, TYPES.SY];
+const TOSTRING_INSTANCES = [RegExp];
+const CUSTOM = [];
+
+/**
+ * Stringify a Javascript value.
+ * 
+ * We typically just use `JSON.stringify()` but that doesn't work on
+ * some types. So this function adds string formats for:
+ *  - `function`
+ *  - `symbol`
+ *  - `TypedArray`
+ *  - `Map`
+ *  - `Set`
+ *  - `Error`
+ * I may add even more extended types in the future, but that's enough
+ * for now.
+ * 
+ * This is NOT meant for serializing data, and does not use a JSON-friendly
+ * output format. I'm writing a different library for that.
+ * 
+ * @param {*} what - The value to stringify.
+ * @param {integer} [recurse=1] Recurse objects to this depth.
+ * @param {boolean} [addNew=false] Use 'new Class()' instead of 'Class()'. 
+ * @returns {string} The stringified value.
+ * @alias module:@lumjs/core/types.stringify
+ */
+function stringify (what, recurse=1, addNew=false)
+{
+  const whatType = typeof what;
+
+  for (const test of CUSTOM)
+  { // If there are custom extensions, we check them first.
+    const ret = test.call({stringify}, what, recurse, addNew);
+    if (typeof ret === TYPES.S)
+    { // The extension processed the item.
+      return ret;
+    }
+  }
+
+  // A few types we simply stringify right now.
+  if (TOSTRING_TYPES.includes(whatType)) return what.toString();
+
+  if (isObj(what))
+  { // We support a few kinds of objects.
+
+    // Any class instance that we can simply call `toString()` on, let's do that.
+    for (const aClass of TOSTRING_INSTANCES)
+    {
+      if (what instanceof aClass)
+      {
+        return what.toString();
+      }
+    }
+
+    // A few formatting helpers used below.
+    const classname = () => (addNew ? 'new ' : '') + what.constructor.name;
+    const construct = val => `${classname()}(${val})`;
+    const reconstruct = val => construct(stringify(val,recurse,addNew));
+    const arrayish = vals => reconstruct(Array.from(vals));
+
+    if (isTypedArray(what))
+    { // This one is pretty simple.
+      return construct(what.toString());
+    }
+    
+    if (what instanceof Map)
+    {
+      return arrayish(what.entries());
+    }
+    
+    if (what instanceof Set)
+    {
+      return arrayish(what.values());
+    }
+
+    if (what instanceof Error)
+    {
+      return `${what.name}(${JSON.stringify(what.message)})`;
+    }
+    
+    if (recurse)
+    { // Recursion mode enabled.
+      let out = '';
+      if (isArray(what))
+      { // Stringify an array.
+        out = '[';
+        out += what.map(item => stringify(item, recurse-1, addNew)).join(',');
+        out += ']';
+      }
+      else
+      { // Stringify a plain object.
+        out = '{';
+        function add(key, pre='')
+        {
+          out += `${pre}${key}:${stringify(what[key], recurse-1, addNew)}`
+        }
+        const keys = Object.keys(what);
+        //console.debug("keys!", keys);
+        if (keys.length > 0)
+        { // Let's add the first key, then all subsequent keys.
+          add(keys.shift());    
+          for (const key of keys)
+          {
+            add(key, ',');
+          }
+        }
+        out += '}';
+      }
+      return out;
+    }
+
+  } // if isObj
+  
+  // If we reached here, there's no special methods, use JSON.
+  return JSON.stringify(what);
+}
+
+// Add a custom extension.
+def(stringify, '$extend',
+function(func, registration=false)
+{
+  if (typeof func === TYPES.F)
+  {
+    if (registration)
+    { // Using the function to register custom behaviour.
+      func.call({stringify, TOSTRING_INSTANCES, TOSTRING_TYPES}, CUSTOM);
+    }
+    else 
+    { // The function is a custom test.
+      CUSTOM.push(func);
+    }
+  }
+});
+
+// Export it.
+module.exports = stringify;

package/lib/types/typelist.js

@@ -7,12 +7,76 @@ const
 } = require('./basics');
 
 /**
- * A map of type names including special and union types.
+ * 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
+ * test, this maps the `O` (`object`) type to the `isObj` test.
+ * 
  * Will also contain a few helper functions, and a map of tests
- * for any types that require tests other than `typeof v === 'typename'`
+ * 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.
+ * 
+ * We will list the types added by the `types` module in
+ * the *Properties* table, and any types added by other *core modules*
+ * in the *Members* list, prior to listing the *Methods*.
+ * 
+ * @namespace module:@lumjs/core/types.TYPES
+ * @property {string} NULL - Represents `null` values.
+ * @property {string} ARGS - Represents an *argument* object.
+ * @property {string} PROP - A `string` or a `symbol`.
+ * @property {string} ARRAY - An `Array` object.
+ * @property {string} TYPEDARRAY - A `TypedArray` object.
+ * @property {string} DESCRIPTOR - A *Descriptor* object (Data or Accessor). 
+ * @property {string} COMPLEX - A `function` or an `object`.
+ * @property {string} SCALAR - A non-null value that is **not** *complex*.
+ * @property {string} NIL - Either `null` or `undefined`.
+ * @property {string} NOTNIL - Anything other than `null` or `undefined`.
+ * @property {string} MAP - A `Map` object.
+ * @property {object} tests - A map of tests for the above types.
  */
  const TYPES = {};
 
+ /**
+  * Add a new type to the `TYPES`.
+  * @name module:@lumjs/core/types.TYPES.add
+  * @function
+  * @param {(string|object)} name - If a `string` the property name to use.
+  *   When adding the property the string will be forced to uppercase.
+  * 
+  *   If an `object` then its a shortcut for adding a bunch of types at once.
+  *   Each key will be the `name`, and the type of the *value* can be one of:
+  *   - `string` → Use as the `ident` parameter.
+  *   - `function` → Use as the `test` parameter.
+  *   - `object` → Supports `id`, `test`, and `export` parameters.
+  * 
+  * @param {?string} [ident] The identifier string for the type.
+  *   If not specified or `null`, it will default to a completely lowercase 
+  *   version of the `name` parameter.
+  * @param {function} [test] A type check test.
+  *   Must accept a single value to test, must return a boolean.
+  * @param {string} [exportTest] A name to export the test as.
+  *   The test will be added to the `types` module with this name.
+  * 
+  * @returns {void}
+  */
+
+ /**
+  * Get a list of type properties available in `TYPES`.
+  * @name module:@lumjs/core/types.TYPES.keys
+  * @function
+  * @returns {string[]}
+  */
+
+  /**
+  * Get a list of type identifier values available in `TYPES`.
+  * @name module:@lumjs/core/types.TYPES.list
+  * @function
+  * @returns {string[]}
+  */
+
  // Let's setup the TYPES with its magic functions.
  const dt = def(TYPES);
  dt('tests', {})