@lumjs/core 1.10.0 → 1.12.0

package/lib/enum.js

@@ -9,9 +9,62 @@ const ENUM_ID = new InternalObjectId({name: '$Enum'});
  * 
  * Like the built-in `Symbol`, this is called as a function, not a constructor.
  * 
- * @param {*} spec - TBD
- * @param {*} [opts] - TBD
+ * @param {(string[]|object)} spec - May be in one of two formats:
+ * 
+ * - An `Array` of strings. Each string represents the name of an Enum 
+ *   property name. The property value will be automatically determined
+ *   based on the options. The default is a series of sequential integers 
+ *   starting at `0`.
+ * 
+ * - A plain object used as a map of property names to underlying values.
+ *   In most cases the value can be whatever you want and will be directly
+ *   mapped as is. However if `opts.symbols` is `true`, and the value is a
+ *   string, the string will be used as the name for the symbol rather than
+ *   the property name.
+ * 
+ * @param {object} [opts] Options for creating the Enum
+ * 
+ * @param {bool} [opts.symbols=false] Use `Symbol` property values.
+ * 
+ * @param {bool} [opts.globals=false] Use `Symbol.for()` property values.
+ * 
+ * This option is only used if `opts.symbols` is `true`.
+ * 
+ * @param {bool} [opts.strings=false] The property name is also the value.
+ * 
+ * This is only used if `spec` is an `Array`, and `opts.symbols` is `false`.
+ * 
+ * @param {bool} [opts.flags=false] Use binary flag property values.
+ * 
+ * This is only used if `spec` is an `Array`, and both `opts.symbols` and
+ * `opts.strings` are `false`.
+ * 
+ * This handles incrementing automatically, so: `[1,2,4,8,16,...]`
+ * 
+ * @param {number} [opts.counter] The starting value when auto-incrementing.
+ * 
+ * The default value is `1` if `opts.flags` is `true` or `0` otherwise.
+ * 
+ * @param {bool} [opts.open=false] If `true` the Enum object won't be locked.
+ * If `false`, by default we use `Object.freeze()` to lock the object.
+ * 
+ * @param {(bool|object|Array)} [opts.lock=null] If this is *not* `null`, 
+ * use {@see module:@lumjs/core/obj.lock lock()} instead of `Object.freeze()`.
+ * 
+ * Only used if `opts.open` is `false`. The supported values are:
+ * 
+ * - `Array`: The `[cloneable, cloneOpts, useSeal]` parameters for `clone()`.
+ * - `object`: The `cloneOpts` parameter for `clone()`.
+ * - `bool`: The `cloneable` parameter for `clone()`.
+ * 
+ * @param {bool} [opts.configurable=false] Enum properties are configurable?
+ * 
+ * This option is ignored if `opts.open` is `false`.
+ * 
+ * @param {bool} [opts.enumerable=true] Enum properties are enumerable?
+ * 
  * @returns {object} A magic Enum object.
+ * @throws {TypeError} If an invalid value was passed.
  * @exports module:@lumjs/core/enum
  */
 function Enum (spec, opts={})
@@ -52,11 +105,10 @@ function Enum (spec, opts={})
 
   if (Array.isArray(spec))
   { // An array of strings is expected.
-    let counter = opts.counter ?? 1;
+    let counter = opts.counter ?? (opts.flags ? 1 : 0);
 
-    for (let i = 0; i < spec.length; i++)
+    for (const name of spec)
     {
-      const name = spec[i];
       if (typeof name !== S)
       {
         throw new TypeError("Non-string passed in Enum object");
@@ -65,7 +117,7 @@ function Enum (spec, opts={})
       const val 
         = opts.strings 
         ? name 
-        : (opts.flags ? counter : i);
+        : counter;
 
       addVal(name, name, val);
 
@@ -73,6 +125,10 @@ function Enum (spec, opts={})
       { // Increment the binary flag counter.
         counter *= 2;
       }
+      else
+      { // Increment a regular counter.
+        counter++;
+      }
     }
   }
   else
@@ -85,30 +141,33 @@ function Enum (spec, opts={})
     }
   }
 
-  if (notNil(opts.lock))
-  { // Use lock() function.
-    let lockOpts;
-    if (Array.isArray(opts.lock))
-    { // Specified the lock parameters as an array.
-      lockOpts = opts.lock;
-    }
-    else if (isObj(opts.lock))
-    { // An object is assumed to be the `cloneOpts` parameter.
-      lockOpts = [true, opts.lock, false];
-    }
-    else if (typeof opts.lock === B)
-    { // Boolean is assumed to be the `cloneable` parameter.
-      lockOpts = [opts.lock, null, false];
+  if (!opts.open)
+  {
+    if (notNil(opts.lock))
+    { // Use lock() function.
+      let lockOpts;
+      if (Array.isArray(opts.lock))
+      { // Specified the lock parameters as an array.
+        lockOpts = opts.lock;
+      }
+      else if (isObj(opts.lock))
+      { // An object is assumed to be the `cloneOpts` parameter.
+        lockOpts = [true, opts.lock, false];
+      }
+      else if (typeof opts.lock === B)
+      { // Boolean is assumed to be the `cloneable` parameter.
+        lockOpts = [opts.lock, null, false];
+      }
+      else 
+      { // Anything else is invalid.
+        throw new TypeError('opts.lock was not a valid value');
+      }
+      return lock(anEnum, ...lockOpts);
     }
-    else 
-    { // Anything else we use default values.
-      lockOpts = [];
+    else
+    { // Use Object.freeze()
+      return Object.freeze(anEnum);
     }
-    return lock(anEnum, ...lockOpts);
-  }
-  else if (!opts.open) 
-  { // Use Object.freeze()
-    return Object.freeze(anEnum);
   }
 
   return anEnum;

package/lib/observable.js

@@ -1,5 +1,7 @@
 
 const {B,F,S,def,isObj,isComplex,TYPES,console} = require('./types');
+const {duplicateAll: clone} = require('./obj/copyall');
+const lock = Object.freeze;
 
 /**
  * Make an object support the *Observable* API.
@@ -11,29 +13,57 @@ const {B,F,S,def,isObj,isComplex,TYPES,console} = require('./types');
  * @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:
+ * 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
  * {
+ *   isObservable:
+ *   {
+ *     event: true,   // This is an event data object.
+ *     target: false, // This is not the target object.
+ *   },
  *   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.
+ *   args: array,     // The arguments passed to trigger.
  * }
  * ```
  * 
- * @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.
+ * The object will be frozen so its values cannot be modified.
+ * 
+ * @param {boolean} [opts.wrapargs=false] If `true`, the functions will be
+ * passed a single object as the sole argument. The object will be the same
+ * as the one from `opts.wrapthis`.
+ * 
+ * @param {boolean} [opts.addname] If `true` callbacks with 
+ * multiple events will have the name of the triggered event added as
+ * the first parameter.
+ * 
+ * If either `wrapthis` or `wrapargs` are `true`, then this will default
+ * to `false`, otherwise it will default to `true`.
+ * 
+ * @param {boolean} [opts.addis] If `true` add a read-only, frozen
+ * object property named `isObservable` with the value:
+ * 
+ * ```js
+ * {
+ *   event: false, // This is not an event data object.
+ *   target: true, // This is the target object.
+ * }
+ * ```
+ *
+ * If either `wrapthis` or `wrapargs` are `true`, then this will default
+ * to `true`, otherwise it will default to `false`.
  * 
- * @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`.
+ * to the `el` object, which is a version of `observable()` with the
+ * default options being the same as the current `opts`.
+ * 
+ * @param {string} [opts.addre] If set, add a method with this name
+ * to the `el` object, which is a function that can re-build the
+ * observable API methods with new `opts` replacing the old ones. 
  *
  * @returns {object} el
  * 
@@ -69,30 +99,46 @@ function observable (el={}, opts={})
     ? opts.wildcard
     : '*';
 
-  const wrapthis = (typeof opts.wrapthis === 'boolean') 
+  const wrapthis = (typeof opts.wrapthis === B) 
     ? opts.wrapthis 
     : false;
 
-  const addname = (typeof opts.addname === 'boolean') 
+  const wrapargs = (typeof opts.wrapargs === B)
+    ? opts.wrapargs
+    : false;
+
+  const wrapped = (wrapthis || wrapargs);
+
+  const addname = (typeof opts.addname === B) 
     ? opts.addname 
-    : !wrapthis;
+    : !wrapped;
 
-  const addis = (typeof opts.addis === 'boolean')
+  const addis = (typeof opts.addis === B)
     ? opts.addis
-    : wrapthis;
+    : wrapped;
 
   const validIdent = /^[a-zA-Z_$][0-9a-zA-Z_$]*$/;
 
-  const addme = (typeof opts.addme === 'string'
+  const addme = (typeof opts.addme === S
     && validIdent.test(opts.addme))
     ? opts.addme
-    : (wrapthis ? 'makeObservable' : null);
+    : null;
+
+  const addre = (typeof opts.addre === S
+    && validIdent.test(opts.addre))
+    ? opts.addre
+    : null;
 
   const slice = Array.prototype.slice;
 
   function onEachEvent (e, fn) 
   { 
-    e.replace(/\S+/g, fn);
+    const es = e.split(/\s+/);
+    const me = es.length > 1;
+    for (e of es)
+    {
+      fn(e, me);
+    }
   }
 
   const add = def(el);
@@ -102,29 +148,28 @@ function observable (el={}, opts={})
     if (fn.busy) return;
     fn.busy = 1;
 
-    let fthis;
+    let fobj;
 
-    if (wrapthis)
-    {
+    if (wrapthis || wrapargs)
+    { // Something is going to use our wrapper object.
       const isWild = (name === wildcard);
       const fname = isWild ? (addname ? args[0] : args.shift()) : name;
-      fthis = 
-      {
+      fobj = 
+      lock({
+        isObservable: lock({event: true, target: false}),
         self: el,
         name: fname,
         func: fn,
         wildcard: isWild,
-      };
-    }
-    else
-    {
-      fthis = el;
+        args,
+      });
     }
 
-    let fargs = (fn.typed && addname) ? [name].concat(args) : args;
-
+    const fthis = wrapthis ? fobj : el;
+    const fargs = wrapargs ? [fobj] 
+      : ((fn.typed && addname) ? [name].concat(args) : args);
+    
     fn.apply(fthis, fargs);
-
     fn.busy = 0;
   }
 
@@ -147,10 +192,10 @@ function observable (el={}, opts={})
       return el;
     }
 
-    onEachEvent(events, function(name, pos) 
+    onEachEvent(events, function(name, typed) 
     {
       (callbacks[name] = callbacks[name] || []).push(fn);
-      fn.typed = pos > 0;
+      fn.typed = typed;
     });
 
     return el;
@@ -244,28 +289,28 @@ function observable (el={}, opts={})
 
   if (addis)
   {
-    add('isObservable', true);
+    add('isObservable', lock({event: false, target: 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 observable(obj, clone(opts, mopts));
+    });
+  }
+
+  if (addre)
+  { // Add a method to change the observable options.
+    add(addre, function(opts={})
+    {
+      return observable(el, opts);
     });
   }
 
+  // Metadata
+  add('$$observable$$', lock({opts, observable}));
+
   return el
 
 } // observable()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.10.0",
+  "version": "1.12.0",
   "main": "lib/index.js",
   "exports":
   {