@lumjs/core 1.0.0-beta.1 → 1.0.0-beta.6

package/src/descriptors.js

@@ -1,243 +0,0 @@
-
-const {InternalObjectId} = require('./objectid');
-const Enum = require('./enum');
-const {doesDescriptor,isObj,isComplex,def,B,F,N} = require('./types');
-
-  /**
-   * Get a property descriptor.
-   * 
-   * This is like `Object.getOwnPropertyDescriptor`, except that method
-   * fails if the property is inhereted. This method will travel through
-   * the entire prototype chain until it finds the descriptor.
-   * 
-   * @param {object|function} obj - Object to find a property in.
-   * @param {string} prop - Name of the property we want the descriptor of.
-   * @param {mixed} [defval] The fallback value if no descriptor is found.  
-   * 
-   * @returns {mixed} - The descriptor if found, `defval` if not.
-   */
-function getProperty(obj, prop, defval)
-{
-  if (!isComplex(obj)) throw new TypeError("Target must be an object or function");
-  // Yeah it looks like an infinite loop, but it's not.
-  while (true)
-  {
-    const desc = Object.getOwnPropertyDescriptor(obj, prop);
-    if (isObj(desc))
-    { // Found it.
-      return desc;
-    }
-
-    // Didn't find it, so let's try the next object in the prototype chain.
-    obj = Object.getPrototypeOf(obj);
-    if (!isComplex(obj))
-    { // We've gone as far up the prototype chain as we can, bye now!
-      return defval;
-    }
-  }
-}
-
-exports.getProperty = getProperty;
-
-const DESC_ID = new InternalObjectId({name: '$LumDescriptor'});
-const DESC_ADD = Enum(['ONE','SHORT', 'SET'], {flags: true});
-
-/**
- * Create a magic Descriptor object.
- * @param {object} desc - Descriptor template.
- * @param {object} [opts] - Options (to be documented.)
- * @returns {object} `desc`
- */
-function descriptor(desc, opts={})
-{
-  if (!isObj(opts)) throw new TypeError("Options must be an object");
-
-  if (typeof desc === B)
-  { // This is a special case.
-    opts.accessorSafe = desc;
-    opts.add = DESC_ADD.ONE;
-    desc = {};
-  }
-
-  if (!isObj(desc)) 
-    throw new TypeError("First parameter (desc) must be a descriptor template object");
-
-  if (!Object.isExtensible(desc))
-    throw new RangeError("First parameter (desc) must not be locked, sealed, frozen, etc.");
-
-  const accessorSafe = (typeof opts.accessorSafe === B) 
-    ? opts.accessorSafe
-    : (desc.writable === undefined);
-  
-  DESC_ID.tag(desc);
-
-  // Add a function or other property.
-  const add = def(desc);
-
-  // Add a getter.
-  function accessor(name, getter, setter)
-  {
-    const adef = {configurable: true};
-    if (typeof getter === F) adef.get = getter;
-    if (typeof setter === F) adef.set = setter;
-    def(desc, name, adef);
-  }
-
-  add('accessorSafe', accessorSafe);
-
-  add('whenDone', function(func)
-  {
-    if (typeof func === F)
-    {
-      add('done', func);
-    }
-    return this;
-  });
-
-  if (typeof opts.done === F)
-  {
-    desc.whenDone(opts.done);
-  }
-
-  add('setValue', function (val, noClean)
-  {
-    if (this.get !== undefined || this.set !== undefined)
-    {
-      console.error("Accessor properties already defined", this);
-    }
-    else
-    {
-      this.value = val;
-    }
-    
-    return this;
-  });
-
-  if (accessorSafe)
-  {
-    function validate ()
-    {
-      if (this.value !== undefined)
-      { 
-        console.error("Data 'value' property defined", this);
-        return false;
-      }
-
-      for (const arg of arguments)
-      { // All accessor arguments must be functions.
-        if (typeof arg !== F) throw new TypeError("Parameter must be a function");
-      }
-
-      return true;
-    }
-
-    add('setGetter', function(func)
-    {
-      if (validate.call(this, func))
-        this.get = func;
-      return this;
-    });
-
-    add('setSetter', function(func)
-    {
-      if (validate.call(this, func))
-        this.set = func;
-      return this;    
-    });
-
-    add('setAccessor', function(getter, setter)
-    {
-      if (validate.call(this, getter, setter))
-      {
-        this.get = getter;
-        this.set = setter;
-      }
-      return this;
-    });
-
-  } // accessorSafe
-
-  if (opts.add)
-  {
-    const addTypes 
-      = (typeof opts.add === N) 
-      ? opts.add 
-      : DESC_ADD.SET;
-
-    function addBool(propname)
-    {
-      const setBool = function() 
-      { 
-        this[propname] = true; 
-        return this; 
-      }
-
-      if (addTypes & DESC_ADD.ONE)
-      {
-        const aname = propname[0];
-        accessor(aname, setBool);
-      }
-      if (addTypes & DESC_ADD.SHORT)
-      {
-        const aname = propname.substring(0,4);
-        accessor(aname, setBool);
-      }
-      if (addTypes & DESC_ADD.SET)
-      {
-        const aname = 'set'+ucfirst(propname);
-        accessor(aname, setBool);
-      }
-    }
-
-    addBool('configurable');
-    addBool('enumerable');
-    addBool('writable');
-
-  } // addBools
-
-  // Is the descriptor ready to be used?
-  accessor('isReady', function()
-  {
-    return doesDescriptor(this);
-  });
-
-  return desc;
-} // descriptor()
-
-exports.descriptor = descriptor;
-
-/**
- * Get a Descriptor object.
- * @param {object} desc - Either a Descriptor, or a descriptor template. 
- * @returns {object}
- */
-function getDescriptor(desc)
-{
-  return DESC_ID.is(desc) ? desc : descriptor(desc);
-}
-
-exports.getDescriptor = getDescriptor;
-
-/**
- * A factory for building magic Descriptor objects.
- */
-const DESC =
-{
-  get RO()    { return descriptor(true)  },
-  get CONF()  { return descriptor(true).c  },
-  get ENUM()  { return descriptor(true).e  },
-  get WRITE() { return descriptor(false).w },
-  get RW()    { return descriptor(false).c.w },
-  get DEF()   { return descriptor(true).c.e  },
-  get OPEN()  { return descriptor(false).c.e.w },
-}
-
-def(DESC)
-  ('make', descriptor)
-  ('is',   DESC_ID.isFunction())
-  ('get',  getDescriptor)
-  ('does', doesDescriptor)
-  ('ADD',  DESC_ADD);
-
-exports.DESC = DESC;
-

package/src/obj/clone.js

@@ -1,201 +0,0 @@
-// Import *most* required bits here.
-const {B,N,F, isObj, isComplex, def} = require('../types');
-const Enum = require('../enum');
-const {getDescriptor, DESC} = require('../descriptors');
-const copyProps = require('./copyprops');
-
-/**
- * An enum of supported modes for the `clone` method.
- * 
- * `CLONE.DEFAULT` → Shallow clone of enumerable properties for most objects.
- * `CLONE.JSON`    → Deep clone using JSON serialization (Arrays included.)
- * `CLONE.FULL`    → Shallow clone of all object properties.
- * `CLONE.ALL`     → Shallow clone of all properties (Arrays included.)
- * 
- */
- const CLONE = Enum(['DEF','JSON','FULL','ALL']);
-
- exports.CLONE = CLONE;
- 
- /**
-  * Clone an object or function.
-  *
-  * @param {object|function} obj - The object we want to clone.
-  * @param {object} [opts={}] - Options for the cloning process.
-  * 
-  * @param {number} [opts.mode=MODE_DEFAULT] - One of the `CLONE.*` enum values.
-  *
-  *   For any mode that doesn't saay "Arrays included", Array objects will
-  *   use a shortcut technique of `obj.slice()` to create the clone.
-  * 
-  *   Note: The `CLONE` enum is also aliased as `clone.MODE` as an alternative.
-  *
-  * @param {boolean} [opts.addClone=false] - Call {@link Lum._.addClone} on the cloned object.
-  *
-  *   The options sent to this function will be used as the defaults in
-  *   the clone() method added to the object.
-  *
-  * @param {boolean} [opts.addLock=false] - Call {@link Lum._.addLock} on the cloned object.
-  *
-  *   No further options for this, just add a lock() method to the clone.
-  *
-  * @param {?object} [opts.copy] Call {@link Lum._.copy} on the cloned object.
-  *
-  *   Will pass the original `obj` as the source to copy from.
-  *   Will pass `opts.copy` as the options.
-  *
-  * @return {object} - The clone of the object.
-  */
- function clone(obj, opts={}) 
- {
-   //console.debug("Lum~clone()", obj, opts);
- 
-   if (!isComplex(obj))
-   { // Doesn't need cloning.
-     //console.debug("no cloning required");
-     return obj;
-   }
- 
-   if (!isObj(opts))
-   { // Opts has to be a valid object.
-     opts = {};
-   }
- 
-   const mode    = typeof opts.mode      === N ? opts.mode      : CLONE.DEF;
-   const reclone = typeof opts.addClone  === B ? opts.addClone  : false;
-   const relock  = typeof opts.addLock   === B ? opts.addLock   : false;
- 
-   let copy;
- 
-   //console.debug("::clone", {mode, reclone, relock});
- 
-   if (mode === CLONE.JSON)
-   { // Deep clone enumerable properties using JSON trickery.
-     //console.debug("::clone using JSON cloning");
-     copy = JSON.parse(JSON.stringify(obj));
-   }
-   else if (mode !== CLONE.ALL && Array.isArray(obj))
-   { // Make a shallow copy using slice.
-     //console.debug("::clone using Array.slice()");
-     copy = obj.slice();
-   }
-   else
-   { // Build a clone using a simple loop.
-     //console.debug("::clone using simple loop");
-     copy = {};
- 
-     let props;
-     if (mode === CLONE.ALL || mode === CLONE.FULL)
-     { // All object properties.
-       //console.debug("::clone getting all properties");
-       props = Object.getOwnPropertyNames(obj);
-     }
-     else
-     { // Enumerable properties.
-       //console.debug("::clone getting enumerable properties");
-       props = Object.keys(obj);
-     }
- 
-     //console.debug("::clone[props]", props);
- 
-     for (let p = 0; p < props.length; p++)
-     {
-       let prop = props[p];
-       copy[prop] = obj[prop];
-     }
-   }
- 
-   if (reclone)
-   { // Add the clone() method to the clone, with the passed opts as defaults.
-     addClone(copy, opts);
-   }
- 
-   if (opts.copy)
-   { // Pass the clone through the copyProps() function as well.
-     copyProps(obj, copy, opts.copy);
-   }
- 
-   if (relock)
-   { // Add the lock() method to the clone.
-     addLock(copy, opts);
-   }
- 
-   return copy;
- }
- 
- // Alias the CLONE enum as clone.MODE
- def(clone, 'MODE', CLONE);
- 
- // Export the clone here.
- exports.clone = clone;
- 
- /**
-  * Add a clone() method to an object.
-  *
-  * @param {object|function} obj - The object to add clone() to.
-  * @param {object} [defOpts=null] Default options for the clone() method.
-  *
-  * If `null` or anything other than an object, the defaults will be:
-  *
-  * ```{mode: CLONE.DEF, addClone: true, addLock: false}```
-  *
-  * @method Lum._.addClone
-  */
- function addClone(obj, defOpts=null)
- {
-   if (!isObj(defOpts))
-   { // Assign a default set of defaults.
-     defOpts = {mode: CLONE.DEF, addClone: true, addLock: false};
-   }
- 
-   const defDesc = getDescriptor(defOpts.cloneDesc ?? DESC.CONF);
- 
-   defDesc.setValue(function (opts)
-   {
-     if (!isObj(opts)) 
-       opts = defOpts;
-     return clone(obj, opts);
-   });
- 
-   return def(obj, 'clone', defDesc);
- }
- 
- exports.addClone = addClone; 
- 
- /**
-  * Clone an object if it's not extensible (locked, sealed, frozen, etc.)
-  *
-  * If the object is extensible, it's returned as is.
-  *
-  * If not, if the object has a `clone()` method it will be used.
-  * Otherwise use the {@link Lum._.clone} method.
-  *
-  * @param {object} obj - The object to clone if needed.
-  * @param {object} [opts] - Options to pass to `clone()` method.
-  *
-  * @return {object} - Either the original object, or an extensible clone.
-  *
-  * @method Lum._.cloneIfLocked
-  */
- function cloneIfLocked(obj, opts)
- {
-   if (!Object.isExtensible(obj))
-   {
-     if (typeof obj.clone === F)
-     { // Use the object's clone() method.
-       return obj.clone(opts);
-     }
-     else
-     { // Use our own clone method.
-       return clone(obj, opts);
-     }
-   }
- 
-   // Return the object itself, it's fine.
-   return obj;
- }
- 
- exports.cloneIfLocked = cloneIfLocked;
-
-// Import `addLock()` here *after* assigning the clone methods.
-const {addLock} = require('./lock');

package/src/obj/index.js

@@ -1,18 +0,0 @@
-// Object helper utilities.
-// We *could* use `copyAll` to simply merge everything in here automatically.
-// But I'm going to be more explicit and import everything I want separately.
-// I may change my mind on that in the future, who knows.
-
-const copyAll = require('./copyall');
-const copyProps = require('./copyprops');
-const {CLONE,clone,addClone,cloneIfLocked} = require('./clone');
-const {lock,addLock} = require('./lock');
-const {mergeNested,syncNested} = require('./merge');
-const {SOA,nsString,nsArray,getObjectPath,setObjectPath} = require('./ns');
-
-module.exports =
-{
-  CLONE, clone, addClone, cloneIfLocked, lock, addLock,
-  mergeNested, syncNested, SOA, nsString, nsArray,
-  getObjectPath, setObjectPath, copyProps, copyAll,
-}

package/src/prop.js

@@ -1,170 +0,0 @@
-
-const {isObj,isNil,notNil,isProperty,unbound,F} = require('./types');
-const {DESC,getDescriptor} = require('./descriptors');
-const {cloneIfLocked} = require('./obj/clone');
-
-/**
- * A magic wrapper for Object.defineProperty()
- *
- * @method Lum.prop
- * 
- * More in-depth than the `def()` function, this has a bazillion different 
- * features, and will continue to evolve, while the simpler function is done.
- *
- * Rather than documenting the arguments in the usual manner, I'm
- * going to simply show all of the ways this method can be called.
- * 
- * Anywhere the `target` parameter is shown, this parameter can be an `object` or `function`.
- * It's the target to which we're adding new properties.
- * 
- * Anywhere the `property` parameter is shown, this parameter can be specified in two different
- * forms. The first and simplest is as a `string` in which case it's simply the name of the property we're adding.
- * The second more advanced form is as an `object`. If it is specified as an object, then it is a set of special options.
- * In this case, a property of that `property` object called `name` will be used as the name of the property.
- * If the `name` property is absent or `undefined`, it's the same as not passing the `property` parameter at all, 
- * and a *bound* function will be returned, using the custom options as its bound defaults.
- * 
- * See below the usage 
- *
- * `Lum.prop(object)`
- *
- *   Return a function that is a bound copy of this function with
- *   the object as it's first parameter.
- *
- * `Lum.prop(object, property)`
- *
- *   Add a property to the object which is mapped to a bound copy of
- *   this function with the object as it's first parameter.
- *
- * `Lum.prop(object, property, function, function)`
- *
- *   Add a getter and setter property with the default descriptor.
- *
- * `Lum.prop(object, property, function, function, object)`
- *
- *   Add a getter and setter property with specified Descriptor options.
- *   Do not use `get`, `set`, or `value` in the descriptor options.
- *
- * `Lum.prop(object, property, function, null, object)`
- *
- *   Add a getter only with specified descriptor options.
- *   Same restrictions to the descriptor options as above.
- *   You can specify `{}` as the descriptor options to use the defaults.
- *
- * `Lum.prop(object, property, null, function, object)`
- *
- *   Add a setter only with specified descriptor options.
- *   Same restrictions as above, and again you can use `{}` for defaults.
- *
- * `Lum.prop(object, property, !null)`
- *
- *   Add a property with the specified non-null value.
- *   This uses the default descriptor.
- *
- * `Lum.prop(object, property, !null, object)`
- *
- *   Add a property value with the specified descriptor options.
- *   Has the same restrictions to the descriptor options as above.
- *
- * `Lum.prop(object, property, null, object)`
- *
- *   Add a property using the descriptor object alone.
- *   Use the newer and shorter `def()` function instead.
- * 
- * `Lum.prop(object, property, Descriptor)`
- * 
- *   If you use `DESC.make()` or `descriptor()` to build a magic
- *   descriptor object, you can pass it and it'll be used with
- *   a few bonus features I need to document that aren't supported by
- *   the otherwise equivalent `def(object,property,descriptor)` call.
- *
- */
-function prop(obj, name, arg1, arg2, arg3)
-{
-  let opts;
-
-  const isUnbound = unbound(this, true, true);
-
-  if (isObj(name))
-  { // A way to set some special options.
-    opts = name;
-    name = opts.name;
-  }
-  else if (isUnbound)
-  { // Use the default options.
-    opts = isObj(prop.options) ? prop.options : {};
-  }
-  else if (isObj(this))
-  { // This is already a bound copy, so `this` is the options.
-    opts = this;
-  }
-  else 
-  { // Something weird is going on here...
-    throw new Error("Invalid `this` in a prop() function call");
-  }
-
-  if (isNil(name))
-  { // A special case, returns a copy of this function bound to the object.
-    return prop.bind(opts, obj);
-  }
-  else if (!isProperty(name))
-  { // The property must in every other case be a string.
-    throw new Error("property name must be a string or Symbol");
-  }
-
-  let desc;
-
-  if (arg1 === undefined && arg2 === undefined)
-  { // Another special case, the property is a bound version of this.
-    return prop(obj, name, prop.bind(opts, obj));
-  }
-  else if (DESC.is(arg1) && arg2 === undefined)
-  { // Yet another special case.
-    if (arg1.isReady)
-    { // Already has a value or get/set properties assigned.
-      desc = arg1;
-    }
-    else 
-    { // We'll need to call setValue(), setGetter(), etc, then done().
-      return arg1.whenDone(function()
-      {
-        return prop(obj, name, this);
-      });
-    }
-  }
-  else if (typeof arg1 === F && typeof arg2 === F)
-  { // A getter and setter were specified.
-    desc = getDescriptor(isObj(arg3) ? cloneIfLocked(arg3) : DESC.CONF);
-    desc.setAccessor(arg1, arg2);
-  }
-  else if (isObj(arg3))
-  { // A custom descriptor for an accessor, find the accessor.
-    desc = getDescriptor(cloneIfLocked(arg3));
-    if (typeof arg1 === F)
-    { // A getter-only accessor.
-      desc.setGetter(arg1);
-    }
-    else if (typeof arg2 === F)
-    { // A setter-only accessor.
-      desc.setSetter(arg2);
-    }
-  }
-  else
-  { // Not a getter/setter, likely a standard value.
-    desc = getDescriptor(isObj(arg2) ? cloneIfLocked(arg2) : DESC.CONF);
-    
-    if (notNil(arg1))
-    { // If you really want a null 'value', use a custom descriptor.
-      desc.setValue(arg1);
-    }
-  }
-
-  // TODO: 
-  //   - Add different configurable return values.
-  //   - Make default return values consistent with def().
-
-  // If we reached here, we should have a valid descriptor now.
-  return Object.defineProperty(obj, name, desc);
-}
-
-module.exports = prop;

package/src/strings.js

@@ -1,76 +0,0 @@
-// String methods.
-const {isObj,root} = require('./types')
-
-/**
- * Get the locale/language string.
- * 
- * 1. If `navigator.language` exists it will be used.
- * 2. If `Intl` exists it will be used.
- * 3. If neither of those exist, uses `'en-US'` as a default.
- * 
- * @returns string - The locale/language string.
- */
-function getLocale()
-{
-  if (isObj(root.navigator) && typeof root.navigator.language === S)
-  {
-    return root.navigator.language;
-  }
-  else if (isObj(root.Intl))
-  {
-    try 
-    {
-      const lang = root.Intl.DateTimeFormat().resolvedOptions().locale;
-      return lang;
-    }
-    catch (err)
-    {
-      console.warn("Attempt to get locale from Intl failed", err);
-    }
-  }
-
-  // A last-ditch fallback.
-  return 'en-US';
-}
-
-exports.getLocale = getLocale;
-
-/**
- * Make the first character of a string uppercase.
- * 
- * @param {string} string - The input string.
- * @param {boolean} [lcrest=false] Make the rest of the string lowercase? 
- * @param {string} [locale=getLocale()] The locale/language of the string.
- * 
- * @returns string - The output string.
- */
-function ucfirst ([ first, ...rest ], lcrest = false, locale = getLocale())
-{
-  first = first.toLocaleUpperCase(locale);
-  rest  = rest.join('');
-  if (lcrest)
-  {
-    rest = rest.toLocaleLowerCase(locale);
-  }
-  return first + rest;
-}
-
-exports.ucfirst = ucfirst;
-
-/**
- * Make the first character of each *word* in a string uppercase.
- *  
- * @param {string} string - The input string. 
- * @param {boolean} [unicode=false] Use Unicode words? (Only uses ASCII words otherwise)
- * @param {boolean} [lcrest=false] Make the rest of each word lowercase? 
- * @param {string} [locale=getLocale()] The locale/language of the string. 
- * 
- * @returns {string} - The output string.
- */
-function ucwords(string, unicode = false, lcrest = false, locale = getLocale())
-{
-  const regex = unicode ? /[0-9\p{L}]+/ug : /\w+/g;
-  return string.replace(regex, word => ucfirst(word, lcrest, locale));
-}
-
-exports.ucwords = ucwords;