@lumjs/compat 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -6,10 +6,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2022-08-11
+### Changed
+- Moved all *v4* stuff into a new `v4` sub-module.
+- Kept `compat/v4-meta` as an alias to `compat/v4/meta`.
+### Added
+- `v4/deprecated` 
+- `v4/loadtracker`
+- `v4/object-helpers`
+- `v4/promise`
+
 ## [1.0.0] - 2022-07-29
 ### Added
 - Initial release.
 
-[Unreleased]: https://github.com/supernovus/lum.compat.js/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/supernovus/lum.compat.js/compare/v1.1.0...HEAD
+[1.1.0]: https://github.com/supernovus/lum.compat.js/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/supernovus/lum.compat.js/releases/tag/v1.0.0
 

package/lib/v4/deprecated.js

@@ -0,0 +1,122 @@
+/**
+ * Mark a function/method/property as deprecated.
+ *
+ * Adds a warning to the Console that the method is deprecated.
+ *
+ * It can also optionally give example replacement code, and run a function 
+ * that will call the replacement code automatically.
+ *
+ * @param {string} name  The name of the deprecated method/property/etc.
+ *
+ *   This should actually be the full method signature, or at least the
+ *   signature matching what a call to the deprecated method made.
+ *
+ *   So rather than 'someOldMethod', use 'MyClass.someOldMethod(foo, bar)'
+ *   as a more detailed name. This is only used in the Console warning.
+ *
+ *   This is the only mandatory parameter.
+ *
+ * @param {mixed} [replace={}]  Replacement options.
+ * 
+ *   If this is a {string}, it is the same as passing an {object} with
+ *   the following options specified:
+ *
+ *     ```{msg: replace}```
+ *
+ *   If it is a {function}, it is the same as passing an {object} with
+ *   the following options specified:
+ *
+ *     ```{exec: replace, msg: true, strip: true}```
+ *
+ *   If it is an {object}, then it will be a set of options:
+ *
+ *     "exec" {function}
+ *
+ *       If specified, this function will be called and the value returned.
+ *       No paramters are passed to the function, so it should be a simple 
+ *       anonymous closure which simply calls the actual replacement code.
+ *
+ *     "msg" {string|boolean}
+ *
+ *       If this is a {string} it will be added to the warning output.
+ *
+ *       If this is `true` and `exec` is set, we will extract the function
+ *       text using `exec.toString()` and add it to the warning output.
+ *
+ *       In any other cases, no replacement message will be appended.
+ *
+ *     "strip" {boolean}
+ *
+ *       If this is `true`, then we will strip `'function() { return '`
+ *       from the start of the function text (whitespace ignored), as well
+ *       as stripping '}' from the very end of the function text.
+ *
+ *       This is only applicable if `exec` is set, and `msg` is `true`.
+ *
+ *   If the `replace` value is none of the above, it will be ignored.
+ *
+ * @return {mixed}  The output is dependent on the parameters passed.
+ *
+ * If `replace` is a function or an object with 
+ *
+ * In any other case the return value will be undefined.
+ *
+ * @alias module:@lumjs/compat/v4/deprecated
+ */
+module.exports = function (name, replace={})
+{
+  const DEP_MSG = ':Deprecated =>';
+  const REP_MSG = ':replaceWith =>';
+
+  if (typeof replace === S)
+  { // A string replacement example only.
+    replace = {msg: replace};
+  }
+  else if (typeof replace === F)
+  { // A function replacement.
+    replace = {exec: replace, msg: true, strip: true};
+  }
+  else if (!is_obj(replace))
+  { // Not an object, that's not valid.
+    replace = {};
+  }
+
+  const msgs = [DEP_MSG, name];
+  const exec = (typeof replace.exec === F) 
+    ? replace.exec
+    : null;
+
+  if (exec && replace.msg === true)
+  { // Extract the function text.
+    const strip = (typeof replace.strip === B)
+      ? replace.strip
+      : false;
+
+    let methtext = replace.exec.toString();
+
+    if (strip)
+    { // Remove wrapping anonymous closure function.
+      methtext = methtext.replace(/^function\(\)\s*\{\s*(return\s*)?/, '');
+      methtext = methtext.replace(/\s*\}$/, '');
+      // Also support arrow function version.
+      methtext = methtext.replace(/^\(\)\s*\=\>\s*/, '');
+    }
+
+    // Set the replacement msg to the method text.
+    replace.msg = methtext;
+  }
+
+  if (typeof replace.msg === 'string')
+  { // A replacement message.
+    msgs.push(REP_MSG, replace.msg);
+  }
+
+  // Show the messages.
+  console.warn(...msgs);
+
+  // Finally, call the replacement function if it was defined.
+  if (exec)
+  {
+    return exec();
+  }
+}

package/lib/v4/loadtracker.js

@@ -0,0 +1,509 @@
+
+const core = require('@lumjs/core');
+const {F,S,B,needObj,needType,def} = core.types
+
+/**
+ * Track if libraries, plugins, or whatever are loaded.
+ * 
+ * Automatically manages events that are trigged on load.
+ * Also will automatically run events assigned *after* the 
+ * desired item has been loaded.
+ * 
+ * Can handle custom tests in addition to the default
+ * test which simply see's if the `loadTracker.mark()`
+ * method has been called for the specified name.
+ * 
+ * @class Lum.LoadTracker
+ */
+class LoadTracker
+{
+  /**
+  * Build a LoadTracker
+  * 
+  * @param {object} [opts] - Named options for custom behaviours.
+  * 
+  * @param {function} [opts.or] A custom test for `is()` method.
+  *   If this returns true, `is()` will return true immediately.
+  *   Mutually exclusive with the `opts.and` option.
+  * 
+  *   The function will have `this` set to the `LoadTracker` instance.
+  *   It will be passed the same arguments sent to the `is()` method.
+  *   The function must return a boolean value indicating if the item
+  *   is considered *loaded* for the purposes of this loader instance.
+  * 
+  * @param {function} [opts.and] A custom test for `is()` method.
+  *   If this returns false, `is()` will return false immediately.
+  *   Mutually exclusive with the `opts.or` option.
+  * 
+  *   The same function notes as `opts.or` apply to this as well.
+  * 
+  * @param {boolean} [opts.before=false] When to run the custom test.
+  *   If `true` the custom test is run before the standard test.
+  *   If `false` the custom test is run after the standard test.
+  * 
+  *   If `opts.or` was used, and whichever test is ran first returns 
+  *   `true`, the other test won't be run at all.
+  * 
+  *   Likewise, if `opts.and` was used, and whichever test is ran first
+  *   returns `false`, the other test won't be run at all.
+  *
+  * @param {function} [opts.check] A custom test for the `check*` methods.
+  *   If specified, this will be ran *before* checking the rest of the
+  *   arguments. The first parameter passed to the function is a boolean,
+  *   indicating if only a single return value is expected; `checkOne()` 
+  *   passes `true` while `checkAll()` passes false. All subsequent
+  *   parameters will be the arguments passed to the calling method.
+  *   The function will have `this` set to the `LoadTracker` instance.
+  * 
+  *   When called from `checkOne()` if it returns a string, that will
+  *   be returned as the missing item name. Return nil if no errors.
+  * 
+  *   When called from `checkAll()` if it returns an Array, all items
+  *   from that array will be added to the list of missing items, and
+  *   then the regular `checkAll()` logic will continue. If however it
+  *   returns a string, then that will be returned as the sole item in
+  *   the missing list without running any further `checkAll()` logic.
+  *   Return nil or an *empty* array if no errors.
+  * 
+  */
+  constructor(opts={})
+  {
+    needObj(opts);
+
+    def(this, '$loaded', {}); // List of loaded libraries.
+    def(this, '$onload', {}); // Events to trigger when libraries are loaded.
+
+    let isTest = false, testOr = false;
+    if (typeof opts.or === F)
+    { // A test that can override 
+      isTest = opts.or;
+      testOr = true;
+    }
+    else if (typeof opts.and === F)
+    {
+      isTest = opts.and;
+      testOr = false;
+    }
+    
+    def(this, '$isTest',  isTest);
+    def(this, '$isOr',    testOr);
+    def(this, '$is1st',   opts.before ?? false);
+    def(this, '$check',   opts.check  ?? false);
+    def(this, '$typeOne', opts.type   ?? 'item');
+    def(this, '$typeAll', opts.types  ?? this.$typeOne + 's');
+    
+  }
+
+  /**
+  * Assign a callback function to be called.
+  * 
+  * All callbacks for a given `name` will be ran when
+  * that `name` has been passed to `mark()` or `call()`.
+  * 
+  * @param {string}   name  - The name of the item to be loaded.
+  * @param {function} event - The callback function.
+  *  
+  * @returns {boolean} - Is the method call deferred?
+  *   If `true` the `name` has not been marked as loaded, so the
+  *   method has been added to a queue that will be called
+  */
+  on(name, event)
+  {
+    needType(S, name,  "Name must be a string");
+    needType(F, event, "Event must be a function");
+
+    if (!Array.isArray(this.$onload[name]))
+    { // Add an array of events.
+      def(this.$onload, name, []);
+    }
+
+    this.$onload[name].push(event);
+
+    if (this.is(name))
+    { // Execute the function right now.
+      event.call(Lum, name, false);
+      return false;
+    }
+
+    return true;
+  }
+
+  /**
+  * Mark an item as loaded.
+  * 
+  * @param {string} name - Item being marked as loaded.
+  * @param {boolean} [call=true]     Also call `call()` method?
+  * @param {boolean} [skipTest=true] Passed to `call()` method.
+  */
+  mark(name, call=true, skipTest=true)
+  { 
+    def(this.$loaded, name, true);
+    if (call)
+    {
+      this.call(name, skipTest);
+    }
+  }
+
+  /**
+  * Call all of the callback function for an item.
+  * 
+  * @param {string} name - The name of the item. 
+  * @param {boolean} [skipTest=false] Skip the `is()` test?
+  *  If `false` we call `this.is(name)` and will only continue
+  *  if it returns a true value. If `true` we call without testing.
+  *  
+  * @returns {boolean} - If the events were called or not.
+  */
+  call(name, skipTest=false)
+  {
+    if (!skipTest && !this.is(name))
+    { // Okay, we cannot call if the item isn't loaded.
+      console.error("Cannot call events if item is not loaded", name, this);
+      return false;
+    }
+
+    if (Array.isArray(this.$onload[name]))
+    {
+      for (const event of this.$onload[name])
+      {
+        event.call(Lum, name, true);
+      }
+    }
+
+    return true;
+  }
+
+  /**
+  * Check if the item is loaded.
+  * 
+  * @param {string} name - The item to check.
+  * @returns {boolean}
+  */
+  is(name)
+  {
+    if (typeof name !== S)
+    {
+      console.error("Name must be a string", name);
+      return false;
+    }
+
+    let okay = false;
+
+    const hasTest = (typeof this.$isTest === F);
+    const test1st = this.$is1st;
+    const testOr  = this.$isOr;
+
+    // A test that indicates we can return `okay` value.
+    const done = () => (!hasTest || (testOr && okay) || (!testOr && !okay));
+
+    if (hasTest && test1st)
+    { // A custom test that is called before the normal test.
+      okay = this.$isTest(...arguments);
+      console.debug("is:before", okay, this);
+      if (done()) return okay;
+    }
+
+    // Call the normal test, is the name marked?
+    okay = (this.$loaded[name] ?? false);
+    if (done()) return okay;
+
+    if (hasTest && !test1st)
+    { // A custom test that is called after the normal test.
+      okay = this.$isTest(...arguments);
+      console.debug("is:after", okay, this);
+    }
+
+    return okay;
+  }
+
+  /**
+  * Get a list of loaded items.
+  * 
+  * This only includes items that have been marked using the
+  * `mark()` method.
+  * 
+  * @param {(boolean|function)} [sort=false] Should we sort the results?
+  *   If this is `true` we use the default sorting algorithm.
+  *   If this is a function, it's passed to the `array.sort()` method.
+  *   Any other value and the list will be in the order returned
+  *   by the `Object.keys()` method.
+  * 
+  * @returns {Array} The list of loaded items.
+  */
+  list(sort=false)
+  {
+    let list = Object.keys(this.$loaded);
+    if (sort === true)
+    { // If sort is boolean true, use default sorting algorithm.
+      list.sort();
+    }
+    else if (typeof sort === F)
+    { // A custom sort function.
+      list.sort(sort);
+    }
+    return list;
+  }
+
+  /**
+  * The same output as `list(false)` but as a readonly accessor property.
+  */
+  get keys()
+  {
+    return Object.keys(this.$loaded);
+  }
+
+  /**
+  * Return the first item that isn't loaded.
+  * 
+  * @param {string} ...names - Any items you want to look for.
+  * 
+  * @returns {string|undefined} If no items are missing, will be undefined.
+  */
+  checkOne()
+  {
+    if (typeof this.$check === F)
+    {
+      const check = this.$check(true, ...arguments);
+      console.debug("checkOne:$check", check, this);
+      if (typeof check === S && check.trim() !== '')
+      { // A non-empty string was passed.
+        return check;
+      }
+    }
+
+    for (const lib of arguments)
+    {
+      if (!this.is(lib))
+      {
+        return lib;
+      }
+    }
+  }
+
+  /**
+  * Return a full list of any missing items.
+  * 
+  * @param {string} ...names - Any items you want to look for.
+  * 
+  * @returns {Array} A list of missing items.
+  */
+  checkAll()
+  {
+    const missing = [];
+
+    if (typeof this.$check === F)
+    {
+      const check = this.$check(false, ...arguments);
+      console.debug("checkAll:$check", check, this);
+      if (Array.isArray(check))
+      { // May have missing items, or be empty.
+        missing.push(...check);
+      }
+      else if (typeof check === S)
+      { // A string indicates we can continue no further.
+        missing.push(check);
+        return missing;
+      }
+    }
+
+    for (const lib of arguments)
+    {
+      if (!this.is(lib))
+      {
+        missing.push(lib);
+      }
+    }
+
+    return missing;
+  }
+
+  /**
+  * Setup a namespace object with wrapper methods.
+  * 
+  * @param {object} ns - The namespace object, may also be a function. 
+  * @param {object} [names] A map of alternate names for the methods.
+  * 
+  * The default method names are:
+  * 
+  * `mark`     → Call `lt.mark`, returns `ourself()`.
+  * `has`      → Proxy `lt.is`.
+  * `check`    → Proxy `lt.checkOne`.
+  * `checkAll` → Proxy `lt.checkAll`.
+  * `list`     → Proxy `lt.list`.
+  * `need`     → Call `check`, if any missing, throw Error.
+  * `want`     → Call `check`, return true if all are loaded, false if not.
+  * `onLoad`   → Proxy `on`.
+  * 
+  * If any of the method names are already present, they will be skipped.
+  * 
+  */
+  setupNamespace(ns, names={})
+  {
+    needObj(ns, true, "Invalid namespace object");
+    needObj(names, false, "Names must be an object");
+
+    const thisLoad = this; // Contextual instance reference.
+    let propName;          // Will be set by hasnt() closure.
+
+    const getname = (name) => names[name] ?? name;
+
+    const hasnt = (name) => 
+    {
+      propName = getname(name);
+      return (ns[propName] === undefined);
+    }
+
+    const addfunc = (func) => def(ns, propName, func);
+    const addgetter = (func) => def(ns, propName, {get: func});
+
+    // Options for need() and want().
+    const loadOpts = def(ns, '$loadOpts', 
+    {
+      checkAll: false,
+      warnings: false,
+    }).$loadOpts;
+
+    if (hasnt('mark'))
+    {
+      addfunc(function()
+      {
+        thisLoad.mark(...arguments);
+        return ourself();
+      });
+    }
+    
+    if (hasnt('has'))
+    {
+      addfunc(function()
+      {
+        return thisLoad.is(...arguments);
+      });
+    }
+
+    if (hasnt('check'))
+    {
+      addfunc(function()
+      {
+        return thisLoad.checkOne(...arguments);
+      })
+    }
+
+    if (hasnt('checkAll'))
+    {
+      addfunc(function()
+      {
+        return thisLoad.checkAll(...arguments);
+      });
+    }
+
+    if (hasnt('list'))
+    {
+      addfunc(function()
+      {
+        return thisLoad.list(...arguments);
+      });
+    }
+
+    if (hasnt('missing'))
+    {
+      addfunc(function(
+      {
+        fatal = false, 
+        all   = loadOpts.checkAll, 
+        warn  = loadOpts.warnings, 
+        ok    = this,
+      },
+        ...items)
+      {
+        const thisCheck = all ? getname('checkAll') : getname('check');
+        const result = ns[thisCheck](...items);
+
+        if (typeof result === S 
+          || (all && Array.isArray(result) && result.length > 0))
+        { // There are missing libraries.
+          const typeName = all ? thisLoad.$typeAll : thisLoad.$typeOne;
+          const missing = fatal ? JSON.stringify(result) : result;
+
+          if (fatal)
+          {
+            throw new Error(`Missing required ${typeName}: ${missing}`);
+          }
+          else 
+          {
+            if (warn)
+            {
+              console.warn("Missing", typeName, missing);
+            }
+            return false;
+          }
+        }
+
+        // If we reached here, nothing was reported as missing.
+        return ok;
+      });
+    }
+
+    if (hasnt('need'))
+    {
+      addfunc(function()
+      {
+        const missing = getname('missing');
+        return ns[missing]({fatal: true, ok: ourself()}, ...arguments);
+      });
+    }
+
+    if (hasnt('want'))
+    {
+      addfunc(function()
+      {
+        const missing = getname('missing');
+        return ns[missing]({fatal: false, ok: true}, ...arguments);
+      });
+    }
+
+    if (hasnt('all'))
+    {
+      addgetter(function()
+      {
+        loadOpts.checkAll = true;
+        return ns;
+      });
+    }
+
+    if (hasnt('one'))
+    {
+      addgetter(function()
+      {
+        loadOpts.checkAll = false;
+        return ns;
+      });
+    }
+
+    if (hasnt('showWarnings'))
+    {
+      addfunc(function(val)
+      {
+        if (typeof val === B)
+        {
+          loadOpts.warnings = val;
+          return this;
+        }
+        else 
+        {
+          return loadOpts.warnings;
+        }
+      });
+    }
+
+    if (hasnt('onLoad'))
+    {
+      addfunc(function()
+      {
+        return thisLoad.on(...arguments);
+      });
+    }
+
+  }
+} // LoadTracker class
+
+module.exports = LoadTracker;

package/lib/v4/object-helpers.js

@@ -0,0 +1,191 @@
+const core = require('@lumjs/core');
+const {O,F,S,B,isObj} = core.types;
+const {clone,copyProps} = core.obj;
+
+/**
+ * A way to handle Mixins/Traits.
+ *
+ * This is basically a magic wrapper around {@link Lum.obj.into} which we 
+ * use instead of Object.assign() as we don't want to overwrite properties
+ * by default.
+ *
+ * As it's designed to extend the class prototype and only the prototype,
+ * it will see if anything passed to it is a function/class and if so, it
+ * will automatically use the prototype of the function/class. If you want
+ * to copy static class properties, use {@link Lum.obj.into} instead of this.
+ *
+ * @param {object|function} target - The target we are copying into.
+ * @param {...*} sources - The source traits we want to mix in.
+ *
+ * @return {object|function}  The `target` will be returned.
+ *
+ * @alias module:@lumjs/compat/v4/object-helpers.mixin
+ */
+exports.mixin = function (target, ...inSources)
+{
+  var outSources = [];
+
+  function unwrap (what)
+  {
+    if (typeof what === F && typeof what.prototype === O)
+    {
+      return what.prototype;
+    }
+    else if (isObj(what))
+    {
+      return what;
+    }
+    else
+    {
+      throw new Error("Invalid function/object passed to addTraits()");
+    }
+  }
+
+  target = unwrap(target); // Ensure the target is an object.
+
+  for (var s in inSources)
+  {
+    var source = inSources[s];
+    if (typeof source === B || typeof source === S)
+    { // A special option statement, push it directly.
+      outSources.push(source);
+    }
+    else
+    { // Anything else needs to be unwrapped.
+      outSources.push(unwrap(source));
+    }
+  }
+
+  return exports.into(target, outSources);
+}
+
+/**
+ * Copy properties between objects. Can be used for mixins/traits.
+ *
+ * For each of the sources specified, this will call:
+ *
+ *  ```Lum.obj.copy(source, target, opts)```
+ *
+ * The current `opts` can be changed dynamically using special statements.
+ * See below for details on the statements to make that work.
+ * The default `opts` is `{default: true, overwrite: false}`
+ *
+ * @param  {object|function} target - The target we are copying into.
+ * @param {...*} sources - The sources to copy from, and options.
+ *
+ * If a source is a boolean, it will reset the `opts.overwrite` property.
+ *
+ * If a source is the string 'default' we set the `opts` to:
+ *   `{default: true, overwrite: opts.overwrite}`
+ *
+ * If a source is the string 'all' we set the `opts` to:
+ *   `{all: true, overwrite: opts.overwrite}`
+ *
+ * If a source is an object with a property of `__copy_opts` which is `true`
+ * then the `opts` will be set to the source itself.
+ *
+ * If a source is an object with a property of `__copy_opts` which is an
+ * `object` then the `opts` will be set to the object, and the rest of
+ * the properties from the source will be copied as usual.
+ *
+ * If the source is any other object or function, it will be considered a
+ * valid source to copy into the `target`.
+ *
+ * Anything else will be invalid and will throw an Error.
+ *
+ * @return {object|function}  The `target` will be returned.
+ *
+ * @method Lum.obj.into
+ */
+exports.into = function (target, ...sources)
+{
+  let opts = {default: true, overwrite: false}; // default opts.
+
+//    console.debug("Lum.obj.copyInto()", target, sources);
+
+  for (let s in sources)
+  {
+    let source = sources[s];
+    const stype = typeof source;
+//      console.debug("source", source, stype);
+    if (stype === B)
+    {
+      opts.overwrite = source;
+    }
+    else if (stype === S)
+    {
+      if (source === 'default')
+      {
+        opts = {default: true, overwrite: opts.overwrite};
+      }
+      else if (source === 'all')
+      {
+        opts = {all: true, overwrite: opts.overwrite};
+      }
+    }
+    else if (stype === O || stype === F)
+    {
+//        console.debug("copying properties", source);
+      if (source.__copy_opts === true)
+      { // Source is copy options.
+        opts = source;
+        continue; // Nothing more to do here.
+      }
+      else if (isObj(source.__copy_opts))
+      { // Copy options included in source.
+        opts = source.__copy_opts;
+        source = clone(source); // Make a copy of the source.
+        delete(source.__copy_opts); // Remove the __copy_opts.
+      }
+
+      // Copy the properties.
+      copyProps(source, target, opts);
+    }
+    else
+    {
+      throw new Error("Invalid function/object passed to copyInto()");
+    }
+  }
+
+  return target;
+}
+
+/**
+ * Clone a simple object, using the {@link Lum._.clone} function.
+ *
+ * By default it uses `Lum._.CLONE.JSON` mode for cloning, but this can
+ * be adjusted as desired by passing a `cloneOpts.mode` option.
+ *
+ * Can also clone extended properties that aren't serialized in JSON.
+ *
+ * @param {object} object The object or function to clone.
+ *
+ * @param {object} [copyProperties] Use {@link Lum.copyProperties} as well.
+ *
+ *   If copyProperties is defined, and is a non-false value, then we'll
+ *   call {@link Lum.obj.copy} after cloning to copy 'special' properties.
+ *
+ * @param {object} [cloneOpts] Options to send to {@link Lum._clone}
+ *
+ *   This can be any options supported by the {@link Lum._.clone} function.
+ *
+ * @return {object}  A clone of the object.
+ *
+ */
+exports.clone = function(object, copyProperties, cloneOpts)
+{
+  if (!isObj(cloneOpts))
+  {
+    cloneOpts = {mode: clone.MODE.JSON};
+  }
+
+  if (copyProperties)
+  {
+    cloneOpts.copy = copyProperties;
+  }
+
+  //console.debug("Lum.obj.clone", object, copyProperties, cloneOpts);
+
+  return clone(object, cloneOpts);
+}
+

package/lib/v4/promise.js

@@ -0,0 +1,381 @@
+const {B,O,F} = require('@lumjs/core').types;
+
+/**
+ * @class LumPromise
+ *
+ * Build the Promise object.
+ *
+ * @param (object|boolean) options Options for the Promise object.
+ *
+ *  If options is a boolean, it's assumed to be the 'jquery' option.
+ *
+ *  Recognized properties if options is an object:
+ *
+ *   jquery: (boolean)  If true, run this._extendJQuery(options);
+ *                      If false, run this._extendInternal(options);
+ *
+ * @deprecated Use HTML 5 Promises, or the jQuery.Deferred API directly.
+ */
+function LumPromise(options)
+{
+  if (typeof options === B)
+  { // Assume the 'jquery' option was passed implicitly.
+    options = {jquery: options};
+  }
+  else if (typeof options !== O || options === null)
+  { // Ensure options is an object, and auto-select jQuery if it's loaded.
+    options = {jquery: (typeof jQuery === O)};
+  }
+
+  if (options.jquery)
+  {
+    this._extendJQuery(options)
+  }
+  else
+  {
+    this._extendInternal(options);
+  }
+}
+
+const lpp = LumPromise.prototype;
+
+/**
+ * Add the methods from jQuery.Deferred to ourself.
+ *
+ * If jQuery is not loaded, this will throw an error.
+ */
+lpp._extendJQuery = function (options)
+{
+  if (jQuery === undefined)
+  {
+    throw new Error("Cannot use 'jquery' without jQuery loaded.");
+  }
+  var def = jQuery.Deferred();
+  for (var f in def)
+  {
+    this[f] = def[f];
+  }
+}
+
+/**
+ * Create our own internal represenation of the Deferred API.
+ *
+ *  Setters:             done(), fail(), always(), progress()
+ *  Promise chaining:    then(), catch()
+ *  Triggers:            resolve(), reject(), notify()
+ *  Targetted triggers:  resolveWith(), rejectWith(), notifyWith()
+ *  Info:                state()
+ *
+ */
+lpp._extendInternal = function (options)
+{
+  // A copy of this for use in closures.
+  var self = this;
+
+  // Private storage for the state of the Promise.
+  var state = 'pending';
+
+  // Private storage for the arguments used to resolve/reject.
+  var final_args;
+
+  // Private storage for the 'this' object to use in callbacks.
+  var final_this = this;
+
+  var callbacks =
+  {
+    always: [],
+    done: [],
+    fail: [],
+    progress: [],
+  };
+
+  // Private function to run registered callbacks.
+  function apply_callbacks (name, args, current_this)
+  {
+    if (args === undefined)
+    {
+      args = final_args;
+    }
+    if (current_this === undefined)
+    {
+      current_this = final_this;
+    }
+    var cbs = callbacks[name];
+    if (cbs && cbs.length)
+    {
+      for (var i = 0; i < cbs.length; i++)
+      {
+        var cb = cbs[i];
+        cb.apply(current_this, args);
+      }
+    }
+  }
+
+  // Private function to create a listener.
+  function create_listener (name, validStates)
+  {
+    var listener = function ()
+    {
+      var args = Array.prototype.slice.call(arguments);
+      for (var i = 0; i < args.length; i++)
+      {
+        if (typeof args[i] === O && Array.isArray(args[i]))
+        { // An array of callbacks, recurse them.
+          listener.apply(self, args[i]);
+        }
+        else if (typeof args[i] === F)
+        {
+          if (state === 'pending')
+          { // Add the callback to the appropriate listener queue.
+            callbacks[name].push(args[i]);
+          }
+          else if (validStates.indexOf(state) != -1)
+          { // Execute the callback now.
+            args[i].apply(final_this, final_args);
+          }
+        }
+        else
+        {
+          console.warn("Unhandled parameter passed to "+name, args[i]);
+        }
+      }
+      return self;
+    }
+    return listener;
+  }
+
+  // Add our event assignment methods.
+  var meths = 
+  {
+    done: ['resolved'],
+    fail: ['rejected'],
+    always: ['resolved', 'rejected'],
+    progress: [],
+  };
+  for (var mname in meths)
+  {
+    var mstate = meths[mname];
+    self[mname] = create_listener(mname, mstate);
+  }
+
+  // Add our trigger methods.
+  self.resolve = function ()
+  {
+    if (state === 'pending')
+    {
+      var args = Array.prototype.slice.call(arguments);
+      if (args.length === 1 && typeof args[0] === O && 
+        typeof args[0].then === F)
+      { // Passed a promise. We'll 'then' it, and resolve again from it.
+        args[0].then(function ()
+        {
+          self.resolve.apply(self, arguments);
+        });
+      }
+      else
+      { // Not a promise, let's do this.
+        state = 'resolved';
+        final_args = args;
+        apply_callbacks('always');
+        apply_callbacks('done');
+      }
+    }
+  }
+
+  self.resolveWith = function (withObj)
+  {
+    if (state === 'pending')
+    {
+      final_this = withObj;
+      var resolveArgs = Array.prototype.slice.call(arguments, 1);
+      self.resolve.apply(self, resolveArgs);
+    }
+  }
+
+  self.reject = function ()
+  {
+    if (state === 'pending')
+    {
+      var args = Array.prototype.slice.call(arguments);
+      if (args.length === 1 && typeof args[0] === O && 
+        typeof args[0].then === F)
+      { // Passed a promise. We'll 'then' it, and resolve again from it.
+        args[0].then(null, function ()
+        {
+          self.reject.apply(self, arguments);
+        });
+      }
+      else
+      { // Not a promise, let's do this.
+        state = 'rejected';
+        final_args = args;
+        apply_callbacks('always');
+        apply_callbacks('fail');
+      }
+    }
+  }
+
+  self.rejectWith = function (withObj)
+  {
+    if (state === 'pending')
+    {
+      final_this = withObj;
+      var rejectArgs = Array.prototype.slice.call(arguments, 1);
+      self.reject.apply(self, rejectArgs);
+    }
+  }
+
+  self.notify = function ()
+  {
+    if (state === 'pending')
+    {
+      var args = Array.prototype.slice.call(arguments);
+      if (args.length === 1 && typeof args[0] === O && 
+        typeof args[0].then === F)
+      { // Passed a promise. We'll 'then' it, and resolve again from it.
+        args[0].then(null, null, function ()
+        {
+          self.notify.apply(self, arguments);
+        });
+      }
+      else
+      { // Not a promise, let's do this.
+        apply_callbacks('progress', args);
+      }
+    }
+  }
+
+  self.notifyWith = function (withObj)
+  {
+    if (state === 'pending')
+    {
+      var args = Array.prototype.slice.call(arguments, 1);
+      if (args.length === 1 && typeof args[0] === O && 
+        typeof args[0].then === F)
+      { // Passed a promise. We'll 'then' it, and resolve again from it.
+        args[0].then(null, null, function ()
+        {
+          var subargs = Array.prototype.slice.call(arguments);
+          subargs.unshift(withObj);
+          self.notifyWith.apply(self, subargs);
+        });
+      }
+      else
+      { // Not a promise, let's do this.
+        apply_callbacks('progress', args, withObj);
+      }
+    }
+  }
+
+  self.catch = function (failFilter)
+  {
+    return self.then(null, failFilter);
+  }
+
+  self.then = function (doneFilter, failFilter, progressFilter)
+  {
+    var newPromise = new LumPromise(false);
+
+    function make_callback (filterSpec)
+    {
+      var callback = function ()
+      {
+        var useWith = (this !== self);
+        var args = Array.prototype.slice.call(arguments);
+        var result = filterSpec.filter.apply(this, args);
+        if (useWith)
+        {
+          newPromise[filterSpec.methodWith](this, result);
+        }
+        else
+        {
+          newPromise[filterSpec.methodName](result);
+        }
+      }
+      return callback;
+    }
+
+    var filterSpecs =
+    {
+      done:
+      {
+        filter: doneFilter,
+        methodName: 'resolve',
+        methodWith: 'resolveWith',
+      },
+      fail:
+      {
+        filter: failFilter,
+        methodName: 'reject',
+        methodWith: 'rejectWith',
+      },
+      progress:
+      {
+        filter: progressFilter,
+        methodName: 'notify',
+        methodWith: 'notifyWith',
+      },
+    };
+
+    for (var onName in filterSpecs)
+    {
+      var filterSpec = filterSpecs[onName];
+      if (typeof filterSpec.filter === F)
+      {
+        var callback = make_callback(filterSpec);
+        self[onName](callback);
+      }
+    }
+
+    return newPromise;
+  }
+
+  self.state = function ()
+  {
+    return state;
+  }
+}
+
+/**
+ * Execute a delayed 'done' action.
+ *
+ * @param mixed  obj      The object to send to the done().
+ * @param str    ts       The textStatus to send to done().
+ * @param mixed  xhr      Object to use as XHR (default is this.)
+ * @param int    timeout  The timeout (in ms) defaults to 5.
+ */
+lpp.deferDone = function (obj, ts, xhr, timeout)
+{
+  var self = this;
+  if (timeout === undefined)
+    timeout = 5; // 5ms should be enough time to register .done events.
+  if (xhr === undefined)
+    xhr = self;
+  self.doneTimer = setTimeout(function() 
+  { 
+    self.resolve(obj, ts, xhr);
+  }, timeout);
+}
+
+/**
+ * Execute a delayed 'fail' action.
+ *
+ * @param mixed  error    The message, code, or object to send to fail().
+ * @param str    ts       The textStatus to send to fail().
+ * @param mixed  xhr      Object to use as XHR (default is this.)
+ * @param int    timeout  The timeout (in ms) defaults to 5.
+ */
+lpp.deferFail = function (error, ts, xhr, timeout)
+{
+  var self = this;
+  if (timeout === undefined)
+    timeout = 5;
+  if (xhr === undefined)
+    xhr = self;
+  self.failTimer = setTimeout(function () 
+  {
+    self.reject(xhr, ts, error);
+  }, timeout);
+}
+
+module.exports = LumPromise;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@lumjs/compat",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "main": "lib/index.js",
   "exports": {
     ".": "./lib/index.js",
-    "./v4-meta": "./lib/v4-meta.js",
+    "./v4-meta": "./lib/v4/meta.js",
+    "./v4/*": "./lib/v4/*.js",
     "./package.json": "./package.json"
   },
   "license": "MIT",