@lumjs/core 1.0.0-beta.2 → 1.0.0

package/lib/types/def.js

@@ -0,0 +1,183 @@
+// Thanks to CJS `require()` rules, recursive dependencies are possible.
+const unbound = require('./root').unbound;
+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()`.
+ * 
+ * This has a few features that makes adding properties a lot nicer.
+ * 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.
+ * 
+ *   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 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 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 {*} [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 `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 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
+ *   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);
+ * ```
+ * 
+ * @alias module:@lumjs/core/types.def
+ */
+function def(obj, name, value, opts)
+{
+  const isBound // Is this a 'bound' def function?
+    = !unbound(this, true, true) 
+    && typeof this.bound === F;
+
+  // When we're finished, return this value.
+  const done = () => 
+  { 
+    if (isBound)
+    { // Bound version, returns itself recursively.
+      return this.bound;
+    }
+    else 
+    { // Not bound, or doesn't have a reference to itself.
+      return obj;
+    }
+  }
+
+  if (isBound && isNil(opts))
+  { // We'll use `this` as the options.
+    opts = this;
+  }
+
+  if (isObj(name))
+  { // Assume it's a map of {name: value} entries.
+    for (const key in name)
+    {
+      def(obj, key, name[key], 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");
+  }
+
+  let desc;
+
+  if (opts !== false && doesDescriptor(value))
+  { // The value is a descriptor, let's use it.
+    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 
+  { // The value is just a value, so let's assign it.
+    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;
+      }
+    }
+
+    cd('configurable', true);
+    cd('enumerable');
+    if (desc.get === undefined && desc.set === undefined)
+    { // Only look for this one on data descriptors.
+      cd('writable');
+    }
+  } // if isObj(opts)
+
+  // Now after all that, let's actually define the property!
+  Object.defineProperty(obj, name, desc);
+
+  return done();
+
+} // def()
+
+module.exports = def;

package/lib/types/index.js

@@ -0,0 +1,55 @@
+/**
+ * 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');
+
+// Basic type check functions.
+const 
+{
+  isObj, isComplex, isNil, notNil, isScalar, isArray, isTypedArray,
+  nonEmptyArray, isArguments, isProperty, doesDescriptor,
+} = require('./basics');
+
+// Root namespace helpers.
+const {root, unbound} = require('./root');
+
+// Advanced type checks.
+const {isInstance, isType, isa} = require('./isa');
+
+// Error-throwing type checks.
+const {needObj, needType, needs} = require('./needs');
+
+// A few standalone items.
+
+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.
+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, stringify,
+}
+
+// Last but not least, this will be the module for TYPES.add()
+def(TYPES, '$module', module);

package/lib/types/isa.js

@@ -0,0 +1,186 @@
+const {O, F, S} = require('./js');
+const {isObj} = require('./basics');
+const TYPES = require('./typelist');
+
+/**
+ * See if a value is an instance of a class.
+ * @param {*} v - The value we're testing.
+ * @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) 
+ {
+   if (!isObj(v)) return false; // Not an object.
+   if (needProto && (typeof v.prototype !== O || v.prototype === null))
+   { // Has no prototype.
+     return false;
+   }
+ 
+   if (typeof f !== F || !(v instanceof f)) return false;
+ 
+   // Everything passed.
+   return true;
+ }
+ 
+ exports.isInstance = isInstance;
+
+ /**
+  * A smarter `typeof` function.
+  * 
+  * @param {string} type - The type we're checking for.
+  * 
+  * 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)
+ {
+   if (typeof type !== S || !TYPES.list.includes(type))
+   {
+     throw new TypeError(`Invalid type ${JSON.stringify(type)} specified`);
+   }
+ 
+   if (typeof TYPES.tests[type] === F)
+   { // A type-specific test.
+     return TYPES.tests[type](v);
+   }
+   else 
+   { // No type-specific tests.
+     return (typeof v === type);
+   }
+ }
+ 
+ exports.isType = isType;
+
+ // Default options parser.
+ const DEFAULT_ISA_PARSER = function(type, v)
+ { // `this` is the options object itself.
+   if (typeof type.is === F)
+   { // We assume `is()` methods are the type check.
+     if (type.is(v)) return true;
+   }
+ 
+   if (typeof type.isa === O)
+   { // Process our known options.
+     const opts = type.isa;
+ 
+     if (typeof opts.process === F)
+     { // We'll pass the current `opts` as well as the `v` to this method.
+       // It doesn't return anything on its own, but can assign further tests,
+       // which by default only apply to `object` 
+       opts.process(this, v);
+     }
+ 
+     if (typeof opts.parsers === F)
+     { // Assign another parser.
+       this.parsers.push(opts.parsers);
+     }
+ 
+     if (typeof opts.test === F)
+     { // A custom test, will be passed `v` and the current `opts`.
+       if (opts.test(v, this))
+       { // Mark this as having passed.
+         return true;
+       }
+     }
+ 
+     // Okay, now anything else gets set.
+     const RESERVED = ['parsers','process','test'];
+     for (const opt in opts)
+     {
+       if (RESERVED.includes(opt)) continue; // Skip it.
+       this[opt] = opts[opt];
+     }
+ 
+   }
+ 
+   // We should almost always return false.
+   return false;
+ }
+ 
+ /**
+  * Is value a certain type, or an instance of a certain class.
+  * 
+  * @param {*} v - The value we're testing.
+  * @param {...any} types - The types the value should be one of.
+  * 
+  * For each of the `types`, if it is a `string` we test with `isType()`,
+  * if it is a `function` we test with `isInstance()`. 
+  * 
+  * If it is an `object` and has an `is()` method, use that as the test.
+  * 
+  * If it is an `object` it will be passed to the current options parsers.
+  * The default options parser looks for an `object` property called `isa`,
+  * which supports the following child properties:
+  * 
+  *  - `needProto: boolean`, Change the `needProto` option for `isInstance()`
+  *  - `parsers: function`, Add another options parser function.
+  *  - `process: function`, A one-time set-up function.
+  *  - `test: function`, Pass the `v` to this test and return `true` if it passes.
+  *  - Anything else will be set as an option.
+  * 
+  * 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)
+ {
+   // A special options object.
+   const opts =
+   {
+     needProto: false,
+     parsers:
+     [
+       DEFAULT_ISA_PARSER,
+     ],
+     process(type, v)
+     {
+       for (const parser of this.parsers)
+       {
+         if (typeof parser === F)
+         {
+           if (parser.call(this, type, v) === true)
+           { // Returning true means a custom test passed.
+             return true;
+           }
+         }
+       }
+       return false;
+     },
+   }
+ 
+   for (const type of types)
+   {
+     // First a quick test for absolute equality.
+     if (v === type) return true;
+ 
+     // With that out of the way, let's go!
+     if (typeof type === S)
+     { // A string is passed to isType()
+       if (isType(type, v)) return true;
+     }
+     else if (typeof type === F)
+     { // A function is passed to isInstance()
+       if (isInstance(v, type, opts.needProto)) return true;     
+     }
+     else if (isObj(type))
+     { // Objects can be additional tests, or options.
+       if (opts.process(type, v)) return true;
+     }
+ 
+   }
+ 
+   // None of the tests passed. We have failed.
+   return false;
+ }
+
+ exports.isa = isa;

package/lib/types/js.js

@@ -0,0 +1,12 @@
+// 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};

package/lib/types/needs.js

@@ -0,0 +1,117 @@
+const {F, S, B} = require('./js');
+const {isType, isa} = require('./isa');
+const {isObj, isComplex} = require('./basics');
+
+/**
+ * If a value is not an object, throw an error.
+ * 
+ * @param {*} v - The value we're testing.
+ * @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)
+{
+  if (allowFunc && isComplex(v)) return;
+  if (isObj(v)) return;
+
+  if (typeof msg !== S)
+  { // Use a default message.
+    msg = "Invalid object";
+    if (allowFunc)
+      msg += " or function";
+  }
+  throw new TypeError(msg);
+}
+
+exports.needObj = needObj;
+
+/**
+ * If a value is not a certain type, throw an error.
+ * 
+ * @param {string} type - The type name as per `isType()`.
+ * @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)
+{
+  if (!isType(type, v))
+  {
+    if (typeof msg === B)
+    {
+      console.warn("needType(): 'allowNull' is no longer supported");
+      if (typeof unused === S)
+      { // Compatibility with old code.
+        msg = unused;
+      }
+    }
+
+    if (typeof msg !== S)
+    { // Use a default message.
+      msg = `Invalid ${type} value`;
+    }
+
+    throw new TypeError(msg);
+  }
+}
+
+exports.needType = needType;
+
+// Options parser for needs();
+const NEEDS_PARSER = function(type, v)
+{ // `this` is the options object itself.
+  if (typeof type.is === F)
+  { // We assume `is()` methods are the type check.
+    if (type.is(v)) return true;
+  }
+}
+ 
+/**
+* A wrapper around `isa()` that will throw an error on failure.
+* 
+* @param {*} v - The value we're testing.
+* @param {...any} types - The types the value should be one of.
+* 
+* In addition to the `types` supported by `isa()` this will also
+* 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)
+{
+  let error;
+
+  function parser(type, v)
+  {
+    // Only process objects with a single `error` property.
+    if ('error' in type && Object.keys(type).length === 1)
+    {
+      if (typeof type.error === 'string')
+      { // An error message.
+        error = new TypeError(type.error);
+      }
+      else if (type.error instanceof Error)
+      { // An error object.
+        error = type.error;
+      }
+    }
+  }
+
+  if (!isa(v, {isa:{parsers: parser}}, ...types))
+  {
+    if (!(error instanceof Error))
+    {
+      error = new TypeError("value did not pass needs check");
+    }
+    throw error;
+  }
+}
+
+exports.needs = needs;

package/lib/types/root.js

@@ -0,0 +1,92 @@
+const {U} = require('./js');
+const {isNil,isArray} = require('./basics');
+
+// «private»
+function no_root()
+{
+  throw new Error("Invalid JS environment, no root object found");
+}
+
+/**
+ * The global root object. Usually `globalThis` these days.
+ * @alias module:@lumjs/core/types.root
+ */
+const root = typeof globalThis !== U ? globalThis
+  : typeof global !== U ? global 
+  : typeof self !== U ? self 
+  : typeof window !== U ? window 
+  : no_root(); // Unlike the old way, we'll die if the environment is undetermined.
+
+exports.root = root;
+
+// A list of objects to be considered unbound globally.
+const unboundObjects = [];
+
+/**
+ * Pass `this` here to see if it is bound to an object.
+ * 
+ * Always considers `null` and `undefined` as unbound.
+ * 
+ * @param {*} whatIsThis - The `this` from any context.
+ * @param {boolean} [rootIsUnbound=true] The global root is unbound. 
+ * @param {(boolean|Array)} [areUnbound=false] A list of unbound objects.
+ *   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)
+{
+  if (areUnbound === true)
+  { // If areUnbound is true, we use the unboundObjects 
+    areUnbound = unboundObjects;
+  }
+
+  if (isNil(whatIsThis)) return true;
+  if (rootIsUnbound && whatIsThis === root) return true;
+  if (isArray(areUnbound) && areUnbound.includes(whatIsThis)) return true;
+
+  // Nothing considered unbound.
+  return false;
+}
+
+exports.unbound = unbound;
+
+// Now that 'unbound' is exported, we can do some wibbly wobbly magic.
+const def = require('./def');
+
+/**
+ * Add an item to the unbound global objects list.
+ * 
+ * @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)
+{
+  needObj(obj, true);
+  if (unbound(obj, true, true))
+  { // Item is already unbound.
+    return false;
+  }
+  // Add to list and we're done.
+  unboundObjects.push(obj);
+  return true;
+});
+
+/**
+ * Remove an item from the unbound global objects list.
+ * 
+ * @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)
+{
+  needObj(obj, true);
+  return (removeFromArray(unboundObjects, obj) > 0);
+});