@lumjs/core 1.0.0-beta.1

package/src/obj/ns.js

@@ -0,0 +1,194 @@
+// Import required bits here.
+const 
+{
+  B, root, isObj, needObj, def, nonEmptyArray, notNil
+} = require('../types');
+
+/**
+ * Internal: need a String or Array
+ */
+function SOA(name, err=true)
+{
+  const msg = (typeof name === S) 
+    ? name + ' ' + this.message 
+    : this.message;
+  return err ? (new TypeError(msg)) : msg;
+}
+SOA.message = "must be a string or non-empty array";
+def(SOA, 'toString', function() { return this.message; });
+
+exports.SOA = SOA;
+
+function nsString(ns, name='Namespace')
+{
+  if (nonEmptyArray(ns))
+  {
+    return ns.join('.');
+  }
+  else if (typeof ns !== S)
+  {
+    throw SOA(name);
+  }
+  return ns;
+}
+
+exports.nsString = nsString;
+
+function nsArray(ns, name='Namespace')
+{
+  if (typeof ns === S)
+  {
+    return ns.split('.');
+  }
+  else if (!nonEmptyArray(ns)) 
+  {
+    throw SOA(name);
+  }
+  return ns;
+}
+
+exports.nsArray = nsArray;
+
+/**
+ * Get a (nested) property from an object with a given path.
+ *
+ * @param {object} obj - Object we're looking in.
+ * @param {(string|Array)} proppath - Property path we're looking for.
+ *   Generally a string of dot (`.`) separated nested property names.
+ * @param {object} [opts] TBD.
+ * @return {*} The property if found, or `opts.default` if not.
+ */
+function getObjectPath(obj, proppath, opts={})
+{
+  needObj(obj);
+
+  if (typeof opts === B)
+    opts = {log: opts};
+  else if (!isObj(opts))
+    opts = {};
+
+  proppath = nsArray(proppath);
+
+  for (let p = 0; p < proppath.length; p++)
+  {
+    const propname = proppath[p];
+    if (obj[propname] === undefined)
+    { // End of search, sorry.
+      if (opts.log)
+      {
+        console.error("Object property path not found", 
+          propname, p, proppath, obj);
+      }
+      return opts.default;
+    }
+    obj = obj[propname];
+  }
+
+  return obj;
+}
+
+exports.getObjectPath = getObjectPath;
+
+/**
+ * Create a nested property path if it does not exist.
+ * 
+ * @param {object} obj - Object the property path is for.
+ * @param {(string|Array)} proppath - Property path to create.
+ * @param {object} [opts] TBD.
+ * @return {*} Generally the last object in the nested path.
+ *   However the output may vary depending on the options.
+ */
+function setObjectPath(obj, proppath, opts={})
+{
+  needObj(obj); needObj(opts);
+  proppath = nsArray(proppath);
+
+  let assign;
+  if (isObj(opts.desc))
+  { // An explicit descriptor.
+    assign = (o,p,v={}) => 
+    {
+      const desc = clone(opts.desc);
+      desc.value = v;
+      def(o,p,desc);
+    }
+  }
+  else if (opts.assign)
+  { // Use direct property assignment.
+    assign = (o,p,v={}) => o[p] = v;
+  }
+  else 
+  { // Use def with default descriptor.
+    assign = (o,p,v={}) => def(o,p,v);
+  }
+
+  let cns = obj;
+  const nsc = proppath.length;
+  const lastns = nsc - 1;
+
+  console.debug("setObjectPath", obj, proppath, opts, nsc, arguments);
+
+  for (let n = 0; n < nsc; n++)
+  {
+    const ns = proppath[n];
+
+    if (cns[ns] === undefined)
+    { // Nothing currently here. Let's fix that.
+      if (n == lastns && notNil(opts.value))
+      { // We're at the end and have a value to assign.
+        assign(cns, ns, opts.value);
+      }
+      else 
+      { // Create a new empty object.
+        assign(cns, ns);
+      }
+    }
+    else if (opts.overwrite && n == lastns && notNil(opts.value))
+    { // We have a value, and overwrite mode is on.
+      assign(cns, ns, opts.value);
+    }
+
+    cns = cns[ns];
+  }
+
+  if (opts.returnThis)
+  {
+    return this;
+  }
+  else if (opts.returnObj)
+  {
+    return obj;
+  }
+  else
+  { // Default is to return the last namespace object.
+    return cns;
+  }
+}
+
+exports.setObjectPath = setObjectPath;
+
+/**
+ * Get a global namespace path if it exists.
+ * 
+ * - TODO: document this.
+ * - TODO: rewrite `ns.get` to use this behind the scenes.
+ */
+function getNamespace(namespaces, opts={})
+{
+  return getObjectPath(root, namespaces, opts);
+}
+
+exports.getNamespace = getNamespace;
+
+/**
+ * Create a global namespace path if it does not exist.
+ * 
+ * - TODO: document this.
+ * - TODO: rewrite `ns.add` to use this behind the scenes.
+ */
+function setNamespace(namespaces, opts={})
+{
+  return setObjectPath(root, namespaces, opts);
+}
+
+exports.setNamespace = setNamespace;

package/src/objectid.js

@@ -0,0 +1,85 @@
+
+const {notNil,def,isNil} = require('./types');
+
+/**
+ * Generate a large random number.
+ * 
+ * Takes advantage of 
+ * 
+ * @returns {number}
+ */
+function randomNumber()
+{
+  return Math.floor(Math.random() * Date.now());
+}
+
+exports.randomNumber = randomNumber;
+
+/**
+ * A class for creating unique identifier objects.
+ * Generally only used by my own inernal libraries, thus the name.
+ */
+class InternalObjectId
+{
+  /**
+   * Build a unique InternalObjectId instance.
+   * 
+   * @param {object} opts - Named options to change default behaviours.
+   * @param {string} [opts.name] A friendly name for diagnostics.
+   * @param {(string|number)} [opts.id] An internal id value.
+   *   Default value is a large random number. 
+   * @param {(string|Symbol)} [opts.property] The property name or Symbol.
+   *   This is the property that will be set on objects that are tagged
+   *   with this InternalObjectId. Default is `Symbol(this.id)`.
+   * @param {boolean} [opts.useInstance=true] Store object or id value?
+   *   If this is `true` (now the default), we store the instance itself.
+   *   If this is `false` (the old default), we store just the `id` value.
+   * 
+   */
+  constructor(opts={})
+  {
+    this.name = opts.name;
+    this.id = opts.id ?? randomNumber();
+    this.property = opts.property ?? Symbol(this.id);
+    this.useInstance = opts.useInstance ?? true; 
+  }
+
+  /**
+   * Tag an object with the ObjectId.
+   * 
+   * @param {*} obj - The object to tag with the unique object id.
+   * @returns {*} `obj`
+   */
+  tag(obj)
+  {
+    if (isNil(obj)) throw new TypeError("Cannot tag a null or undefined value");
+    const val = this.useInstance ? this : this.id;
+    return def(obj, this.property, val);
+  }
+
+  /**
+   * Is the specified object tagged with this object id?
+   * 
+   * @param {*} obj - The object to test.
+   * @returns {boolean} If it's tagged or not.
+   */
+  is(obj)
+  {
+    const want = this.useInstance ? this : this.id;
+    return (notNil(obj) && obj[this.property] === want);
+  }
+
+  /**
+   * Generate a function that calls `instance.is()`
+   * 
+   * @returns {function} The wrapper function.
+   */
+  isFunction()
+  {
+    const oid = this;
+    return function(obj) { return oid.is(obj); }
+  }
+
+}
+
+exports.InternalObjectId = InternalObjectId;

package/src/observable.js

@@ -0,0 +1,292 @@
+// This library was original based on the observable library from riot.js,
+// but has been refactored and expanded a lot since then.
+
+const {B,F,S,def,isObj,isComplex} = require('./types');;
+
+/**
+ * Make an object support the observable API.
+ *
+ * Adds `on()`, `off()`, `one()`, and `trigger()` methods.
+ * 
+ * @param {object} el - The object we are making observable.
+ * @param {object} [opts] Options that define behaviours.
+ * @param {string} [opts.wildcard='*'] The event name used as a wildcard. 
+ * @param {boolean} [opts.wrapthis=false] If `true`, `this` will be a wrapper.
+ * 
+ * If 'wrapthis' is true, the function will be called with a wrapper object as 
+ * the 'this' variable instead of the target object. The wrapper will be:
+ *
+ * ```js
+ * {
+ *   self: el,        // The target object.
+ *   name: event,     // The event name that was triggered.
+ *   wildcard: bool,  // Will be true if this was a wildcard event handler.
+ *   func: function,  // The function being called.
+ * }
+ * ```
+ * 
+ * @param {boolean} [opts.addname=!opts.wrapthis] If `true` callbacks with 
+ *   multiple events will have the name of the triggered event added as
+ *   the first parameter.
+ * 
+ * @param {boolean} [opts.addis=opts.wrapthis] If `true` add immutable
+ *   property named `isObservable` which will have a value of `true`.
+ * @param {string} [opts.addme] If set, add a method with this name
+ *   to the object, which is a version of `observable()` with the
+ *   default options being the same as the current `opts`.
+ *   If `opts.wrapthis` is `true`, then this defaults to `'makeObservable'`.
+ *   In any other case it defaults to `null`.
+ *
+ * @returns {object} el
+ */
+function observable (el={}, opts={}) 
+{
+  //console.debug("observable", el, opts);
+
+  if (!isComplex(el))
+  { // Don't know how to handle this, sorry.
+    throw new Error("non-object sent to observable()");
+  }
+
+  if (observable.is(el))
+  { // It's already observable.
+    return el;
+  }
+
+  if (typeof opts === B)
+  { // Assume it's the wrapthis option.
+    opts = {wrapthis: opts};
+  }
+  else if (!isObj(opts))
+  {
+    opts = {};
+  }
+
+  const noSpace = /^\S+$/;
+
+  const wildcard = (typeof opts.wildcard === S 
+    && noSpace.test(opts.wildcard))
+    ? opts.wildcard
+    : '*';
+
+  const wrapthis = (typeof opts.wrapthis === 'boolean') 
+    ? opts.wrapthis 
+    : false;
+
+  const addname = (typeof opts.addname === 'boolean') 
+    ? opts.addname 
+    : !wrapthis;
+
+  const addis = (typeof opts.addis === 'boolean')
+    ? opts.addis
+    : wrapthis;
+
+  const validIdent = /^[a-zA-Z_$][0-9a-zA-Z_$]*$/;
+
+  const addme = (typeof opts.addme === 'string'
+    && validIdent.test(opts.addme))
+    ? opts.addme
+    : (wrapthis ? 'makeObservable' : null);
+
+  const slice = Array.prototype.slice;
+
+  function onEachEvent (e, fn) 
+  { 
+    e.replace(/\S+/g, fn);
+  }
+
+  const add = def(el);
+
+  function runCallback (name, fn, args)
+  {
+    if (fn.busy) return;
+    fn.busy = 1;
+
+    let fthis;
+
+    if (wrapthis)
+    {
+      const isWild = (name === wildcard);
+      const fname = isWild ? (addname ? args[0] : args.shift()) : name;
+      fthis = 
+      {
+        self: el,
+        name: fname,
+        func: fn,
+        wildcard: isWild,
+      };
+    }
+    else
+    {
+      fthis = el;
+    }
+
+    let fargs = (fn.typed && addname) ? [name].concat(args) : args;
+
+    fn.apply(fthis, fargs);
+
+    fn.busy = 0;
+  }
+
+  let callbacks = {};
+
+  /**
+  * Assign an event handler
+  * 
+  * Listen to the given space separated list of `events` and execute
+  * the `callback` each time an event is triggered.
+  * @param  {string} events - events ids
+  * @param  {function} fn - callback function
+  * @returns {object} el
+  */
+  add('on', function(events, fn) 
+  {
+    if (typeof fn !== F)
+    {
+      console.error("non-function passed to on()");
+      return el;
+    }
+
+    onEachEvent(events, function(name, pos) 
+    {
+      (callbacks[name] = callbacks[name] || []).push(fn);
+      fn.typed = pos > 0;
+    });
+
+    return el;
+  });
+
+  /**
+  * Removes the given space separated list of `events` listeners
+  * 
+  * @param   {string} events - events ids
+  * @param   {function} fn - callback function
+  * @returns {object} el
+  */
+  add('off', function(events, fn) 
+  {
+    if (events === wildcard && !fn) 
+    { // Clear all callbacks.
+      callbacks = {};
+    }
+    else 
+    {
+      onEachEvent(events, function(name) 
+      {
+        if (fn) 
+        { // Find a specific callback to remove.
+          var arr = callbacks[name]
+          for (var i = 0, cb; cb = arr && arr[i]; ++i) 
+          {
+            if (cb == fn) arr.splice(i--, 1);
+          }
+        } 
+        else 
+        { // Remove all callbacks for this event.
+          delete callbacks[name];
+        }
+      });
+    }
+    return el
+  });
+
+  /**
+  * Add a one-shot event handler.
+  * 
+  * Listen to the given space separated list of `events` and execute 
+  * the `callback` at most once.
+  * 
+  * @param   {string} events - events ids
+  * @param   {function} fn - callback function
+  * @returns {object} el
+  */
+  add('one', function(events, fn) 
+  {
+    function on() 
+    {
+      el.off(events, on)
+      fn.apply(el, arguments)
+    }
+    return el.on(events, on);
+  });
+
+  /**
+  * Execute all callback functions that listen to the given space 
+  * separated list of `events`
+  * @param   {string} events - events ids
+  * @returns {object} el
+  */
+  add('trigger', function(events) 
+  {
+    // getting the arguments
+    // skipping the first one
+    const args = slice.call(arguments, 1);
+
+    onEachEvent(events, function(name) 
+    {
+      const fns = slice.call(callbacks[name] || [], 0);
+
+      for (var i = 0, fn; fn = fns[i]; ++i) 
+      {
+        runCallback(name, fn, args);
+        if (fns[i] !== fn) { i-- }
+      }
+
+      if (callbacks[wildcard] && name != wildcard)
+      { // Trigger the wildcard.
+        el.trigger.apply(el, ['*', name].concat(args));
+      }
+
+    });
+
+    return el
+  });
+
+  if (addis)
+  {
+    add('isObservable', true);
+  }
+
+  if (addme)
+  { // Add a wrapper for observable() that sets new default options.
+    const ourProps = Object.keys(opts);
+    add(addme, function (obj=null, mopts={})
+    {
+      if (ourProps.length > 0)
+      {
+        for (const prop of ourProps)
+        {
+          if (mopts[prop] === undefined)
+          {
+            mopts[prop] = opts[prop];
+          }
+        }
+      }
+      return observable(obj, mopts);
+    });
+  }
+
+  return el
+
+} // observable()
+
+module.exports = observable;
+
+/**
+ * See if an object appears to be observable.
+ * 
+ * @param {object} obj 
+ * @returns {boolean}
+ */
+function isObservable(obj)
+{
+  return (isObj(obj)
+    && typeof obj.trigger === F
+    && typeof obj.on === F);
+}
+
+// Add an 'is()' method to `observable` itself.
+def(observable, 'is', isObservable);
+
+// And make it available as `types.doesObservable`
+require('./types').doesObservable = isObservable;

package/src/opt.js

@@ -0,0 +1,60 @@
+// Simple option handling.
+
+const {U,needObj,needType} = require('./types');
+
+/**
+ * See if a value is *set*, and if not, return a default value.
+ *
+ * @param {*} opt - The value we are testing.
+ * @param {*} defvalue - The default value if opt was null or undefined.
+ *
+ * @param {boolean} [allowNull=false] If true, allow null to count as *set*.
+ * @param {boolean} [isLazy=false]    If true, and `defvalue` is a function,
+ *                                    use the value from the function as 
+ *                                    the default.
+ * @param {object} [lazyThis=null]    If `isLazy` is true, this object will
+ *                                    be used as `this` for the function.
+ *
+ * @return {*} Either the specified `opt` value or the default value.
+ */
+function val(opt, defvalue, allowNull=false, isLazy=false, lazyThis=null)
+{
+  if (typeof opt === U || (!allowNull && opt === null))
+  { // The defined value was not "set" as per our rules.
+    if (isLazy && typeof defvalue === F)
+    { // Get the default value from a passed in function.
+      return defvalue.call(lazyThis);
+    }
+    return defvalue;
+  }
+
+  return opt;
+}
+
+exports.val = val;
+
+/**
+ * See if a property in an object is set.
+ *
+ * If it is, return the property, otherwise return a default value.
+ * This uses the `val()` method, and as such supports the same options.
+ * However read the parameters carefully, as the defaults may be different!
+ *
+ * @param {object} obj     - An object to test for a property in.
+ * @param {string} optname - The property name we're checking for.
+ * @param {*} defvalue     - The default value.
+ *
+ * @param {bool}   [allowNull=true] Same as `val()`, but the default is `true`.
+ * @param {bool}   [isLazy=false]   Same as `val()`.
+ * @param {object} [lazyThis=opts]  Same as `val()`.
+ *
+ * @return {*} Either the property value, or the default value.
+ */
+function get(obj, optname, defvalue, allowNull=true, isLazy=false, lazyThis=obj)
+{
+  needObj(obj);
+  needType(S, optname);
+  return val(obj[optname], defvalue, allowNull, isLazy, lazyThis);
+}
+
+exports.get = get;