@lumjs/core 1.11.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/package.json

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