@lumjs/core 1.38.4 → 1.38.5

package/lib/objectid.js

@@ -1,5 +1,6 @@
+'use strict';
 
-const {notNil,def,isNil,isObj,F,N,S,SY} = require('./types');
+const {isObj,isComplex,isProperty,F,N,S,SY} = require('./types');
 const argOpts = require('./opt/args');
 
 /**
@@ -45,14 +46,52 @@ function randomNumber(seed=0, mode=1)
   }
 }
 
-exports.randomNumber = randomNumber;
+//exports.randomNumber = randomNumber;
 
-const validBase = base => (typeof base === N && base > 1 && base < 37);
+const validBase = (base) => (typeof base === N && base > 1 && base < 37);
 
 /**
  * A class for generating unique ids for objects.
  * 
- * TODO: document all the methods, etc.
+ * @param {object} [opts] Named options;
+ * Will be assigned to `this.options` property.
+ * 
+ * There are three mutually-exclusive options that will determine
+ * how ids are generated. They are checked for in a specific order:
+ * 
+ * - `opts.random`
+ * - `opts.timestamp`
+ * - `opts.incremental`
+ * 
+ * The first one that has a truthful value will be used and the
+ * others won't be checked at all. If none of them are specified,
+ * then `incremental` mode will be used as the default.
+ * 
+ * @param {number} [opts.radix=16] Base for id numbers.
+ * We use `16` (hexadecimal) as the default.
+ * 
+ * @param {(number|boolean)} [opts.incremental] Use incremental ids.
+ * 
+ * - A number will override `opts.radix`.
+ * - Boolean true may be used for consistency with the other modes,
+ *   but is not required at all, as this is the default mode.
+ * - Boolean false will show a warning message if none of the other
+ *   modes were enabled, as in that case incremental mode will be
+ *   forced as the default.
+ * 
+ * @param {(object|number|boolean)} [opts.random] Use random ids.
+ * 
+ * The numeric portion of ids will be generated via randomNumber().
+ * 
+ * - An object will be used as named options for randomNumber();
+ *   for any value other than an object, default options are used.
+ * - A number will override `opts.radix`.
+ * - Boolean true enables random ids without overriding anything.
+ * 
+ * @param {(number|boolean)} [opts.timestamp] Use timestamps as ids.
+ * 
+ * - A number will override `opts.radix`.
+ * - Boolean true enables timestamps without overriding anything.
  * 
  * @alias module:@lumjs/core.UniqueObjectIds
  */
@@ -60,31 +99,43 @@ class UniqueObjectIds
 {
   constructor(opts={})
   {
-    def(this, '$options', {value: opts});
+    df(this, 'options', {value: opts});
 
-    let radix = null;
+    let radix = opts.radix ?? 16;
 
-    if (isObj(opts.random))
-    { // Random ids with custom options.
-      def(this, '$randOpts', {value: opts.random});
-      if (validBase(opts.random.radix))
+    if (opts.random)
+    {
+      let randOpts;
+      if (isObj(opts.random))
       {
-        radix = opts.random.radix;
+        randOpts = opts.random;
       }
+      else if (typeof opts.random === N)
+      {
+        radix = opts.random;
+        randOpts = {};
+      }
+      df(this, '$randOpts', {value: randOpts});
     }
-    else if (validBase(opts.random))
-    { // Use random ids.
-      def(this, '$randOpts', {value: {}});
-      radix = opts.random;
-    }
-    else if (validBase(opts.timestamp))
+    else if (opts.timestamp)
     { // Use timestamp-based ids.
-      def(this, '$timeIds', {value: {}});
-      radix = opts.timestamp;
+      df(this, '$timeIds', {value: {}});
+      if (validBase(opts.timestamp))
+      {
+        radix = opts.timestamp;
+      }
     }
     else
     { // Use incremental ids.
-      def(this, '$incIds',  {value: {}});
+      df(this, '$incIds',  {value: {}});
+      if (validBase(opts.incremental))
+      {
+        radix = opts.incremental;
+      }
+      else if (opts.incremental === false)
+      {
+        console.error("no modes enabled; forcing incremental ids");
+      }
     }
 
     if (!radix)
@@ -92,39 +143,49 @@ class UniqueObjectIds
       radix = validBase(opts.radix) ? opts.radix : 16;
     }
 
-    def(this, '$radix', radix);
+    df(this, '$radix', radix);
 
     if (this.$randOpts)
     {
-      def(this, '$randIds',  {value: {}});
+      df(this, '$randIds',  {value: {}});
     }
     
-    const propType = (typeof opts.idProperty);
-    const hasProp  = (propType === S || propType === SY);
-    const useRegistry = opts.useRegistry ?? !hasProp;
+    let propType = (typeof opts.idProperty),
+        hasProp  = (propType === S || propType === SY),
+        useRegistry = (opts.useRegistry ?? !hasProp),
+        reg = null;
 
     if (useRegistry)
-    { // Using an internal registry.
-      def(this, '$registry', {value: new Map()});
+    { // Using an internal registry to store ids.
+      if (useRegistry instanceof TaggedObjects)
+      {
+        reg = useRegistry;
+      }
+      else
+      { // ↓ TODO: `s/property/tagProperty/` in v2.x
+        let ro = Object.assign({property: false}, opts, {useRegistry});
+        reg = new TaggedObjects(ro);
+      }
     }
     else if (!hasProp)
     { // At least ONE of them MUST be used!
       throw new RangeError("Need one of 'useRegistry' or 'idProperty'");
     }
 
+    df(this, 'metadata', {value: reg});
+
     if (hasProp)
     { // Add a direct reference to the id property key.
-      def(this, '$idProp', {value: opts.idProperty});
+      df(this, '$idProp', {value: opts.idProperty});
     }
-
   }
 
   id(obj)
   {
-    const hasRegistry = (this.$registry instanceof Map);
-    if (hasRegistry && this.$registry.has(obj))
-    { // The object was found in the registry.
-      return this.$registry.get(obj);
+    let metadata = this.metadata?.for(obj);
+    if (metadata && metadata.uid)
+    { // Found the id in the registry metadata.
+      return metadata.uid;
     }
 
     const idProp = this.$idProp;
@@ -136,16 +197,16 @@ class UniqueObjectIds
 
     let radix = this.$radix;
 
-    let cno = this.$options.className ?? {};
+    let cno = this.options.className ?? {};
     if (typeof cno === F)  cno = {setup: cno};
     else if (cno === 'lc') cno = {lowercase: true};
     else if (cno === 'uc') cno = {uppercase: true};
 
     let id = '', idNum = null;
 
-    if (typeof this.$options.prefix === S)
+    if (typeof this.options.prefix === S)
     {
-      id += this.$options.prefix; 
+      id += this.options.prefix; 
     }
 
     let className = (typeof obj === F ? obj : obj.constructor).name;
@@ -175,9 +236,9 @@ class UniqueObjectIds
       }
       else
       { // No existing values yet.
-        const start = this.$options.startAt ?? 1;
+        const start = this.options.startAt ?? 1;
         ids[className] = start;
-        if (!this.$options.skipFirst)
+        if (!this.options.skipFirst)
         {
           idNum = start;
         }
@@ -229,101 +290,196 @@ class UniqueObjectIds
 
     if (typeof idNum === S)
     {
-      if (typeof this.$options.infix  === S)
+      if (typeof this.options.infix  === S)
       {
-        id += this.$options.infix;
+        id += this.options.infix;
       }
       id += idNum;
     }
 
     if (idProp)
     {
-      def(obj, idProp, {value: id});
+      df(obj, idProp, {value: id});
     }
 
-    if (hasRegistry)
-    {
-      this.$registry.set(obj, id);
+    if (metadata)
+    { // Set the uid.
+      metadata.uid = id;
     }
 
     return id;
   } // id()
+
 } // UniqueObjectIds class
 
-exports.UniqueObjectIds = UniqueObjectIds;
+//exports.UniqueObjectIds = UniqueObjectIds;
 
 /**
- * A class for creating unique identifier objects.
- * Generally only used by my own inernal libraries, thus the name.
- * @alias module:@lumjs/core.InternalObjectId
+ * A class that allows tagging objects for specific purposes.
+ * 
+ * This was originally used solely as a way to identify internal objects,
+ * and its classname was InternalObjectId (an alias to which will continue
+ * to exist for the duration of v1.x).
+ * 
+ * In v1.38.5 however it was redesigned to support using an internal registry
+ * instead of a unique property on the object itself, and with this came the
+ * ability to define custom metadata for any tagged objects. So I renamed it,
+ * and updated the UniqueObjectIds class to support using an instance of this
+ * for its own internal registry (replacing the Map it used previously).
+ * 
+ * @alias module:@lumjs/core.TaggedObjects
  */
-class InternalObjectId
+class TaggedObjects
 {
   /**
-   * Build a unique InternalObjectId instance.
+   * Build a unique TaggedObjects instance.
    * 
-   * @param {object} opts - Named options to change default behaviours.
+   * @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.
-   *   A reasonable default will be generated if it's not specified.
-   * @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 a unique (non-global) `Symbol`.
+   * 
+   * A reasonable default will be generated if it's not specified.
+   * 
+   * @param {(string|symbol|false)} [opts.property] **DEPRECATED**
+   * 
+   * Use `opts.tagProperty` instead of this which is the older name.
+   * This is currently supported as an alias, but will be removed in v2.x.
+   * 
    * @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.
+   * 
+   * - If this is true (now the default), we use `this` instance as the tag.
+   * - If this is false (the old default), we use `this.id` as the tag.
+   * 
+   * @param {boolean} [opts.useRegistry=false] Register tagged items?
+   * 
+   * If this is true, then `this.registry` will be created as a Map instance,
+   * and every object/function passed to tag() will be added as a key, with
+   * a plain object that can be used for arbitrary metadata as the value.
+   * 
+   * If both this and `opts.tagProperty` are false, an error will be thrown.
+   * 
+   * @param {(string|symbol|false)} [opts.tagProperty] Tag property.
+   * 
+   * This is the property that will be set on objects that are tagged
+   * with this TaggedObjects. Default is a unique (non-global) `Symbol`.
+   * 
+   * If explicitly set to false, no property will be assigned.
+   * 
+   * If both this and `opts.useRegistry` are false, an error will be thrown.
+   * 
+   * @throws {RangeError} If `useRegistry` and `tagProperty` are both false.
    */
   constructor(opts={})
   {
-    const ui = this.useInstance = opts.useInstance ?? true;
+    let ui = this.useInstance = opts.useInstance ?? true;
     this.name = opts.name;
     this.id = opts.id ?? (ui ? Date.now() : randomNumber());
-    this.property = opts.property ?? Symbol(this.name ?? this.id);
+    this.property = opts.tagProperty 
+      ?? opts.property 
+      ?? Symbol(this.name ?? this.id);
+    this.options = opts;
+
+    if (opts.useRegistry)
+    {
+      this.registry = new Map();
+    }
+    else if (!isProperty(this.property))
+    {
+      throw new RangeError("Need one of 'useRegistry' or 'tagProperty'");
+    }
+  }
+
+  /**
+   * Get metadata for an object.
+   * 
+   * If the object 
+   * 
+   * This is ONLY able to be used if `opts.useRegistry` was true
+   * when creating the intance. An error will be thrown otherwise.
+   * 
+   * @param {(object|function)} obj - Target to get metadata for.
+   * @returns {object} Metadata.
+   */
+  for(obj)
+  {
+    if (!this.registry) throw new Error("No registry");
+    if (!this.registry.has(obj))
+    { // Tag the object.
+      this.tag(obj);
+    }
+    return this.registry.get(obj);
   }
 
   /**
    * Tag an object with the ObjectId.
    * 
-   * @param {*} obj - The object to tag with the unique object id.
-   * @returns {*} `obj`
+   * @param {(object|function)} obj - The target to tag.
+   * @returns {(object|function)} `obj`
    */
   tag(obj)
   {
-    if (isNil(obj)) throw new TypeError("Cannot tag a null or undefined value");
+    if (!isComplex(obj)) throw new TypeError("Invalid tag target");
+
+    if (this.registry)
+    {
+      if (!this.registry.has(obj))
+      { // Initialize the metadata.
+        this.registry.set(obj, {});
+      }
+      if (this.property === false)
+      {
+        return obj;
+      }
+    }
+    
     const val = this.useInstance ? this : this.id;
-    return def(obj, this.property, val);
+    return df(obj, this.property, val);
   }
 
   /**
    * Remove the tag from a tagged object.
    * 
-   * @param {*} obj 
+   * @param {(object|function)} obj - The target to untag.
+   * @returns {(object|function)} `obj`
    */
   untag(obj)
   {
-    if (notNil(obj))
+    if (isComplex(obj))
     {
-      delete(obj[this.property]);
+      if (this.registry)
+      {
+        this.registry.delete(obj);
+      }
+
+      if (this.property !== false)
+      {
+        delete(obj[this.property]);
+      }
     }
+
     return obj;
   }
 
   /**
    * Is the specified object tagged with this object id?
    * 
-   * @param {*} obj - The object to test.
+   * @param {(object|function)} obj - The object to test.
    * @returns {boolean} If it's tagged or not.
    */
   is(obj)
   {
+    if (this.registry)
+    {
+      return this.registry.has(obj);
+    }
     const want = this.useInstance ? this : this.id;
-    return (notNil(obj) && obj[this.property] === want);
+    return (isComplex(obj) && obj[this.property] === want);
   }
 
   /**
-   * Generate a function that calls `instance.is()`
+   * Generate a closure that calls `instance.is()`
    * 
-   * @returns {function} The wrapper function.
+   * @returns {function} The closure function.
    */
   isFunction()
   {
@@ -332,4 +488,13 @@ class InternalObjectId
 
 }
 
-exports.InternalObjectId = InternalObjectId;
+module.exports = 
+{
+  InternalObjectId: TaggedObjects,
+  randomNumber,
+  TaggedObjects,
+  UniqueObjectIds,
+  validBase,
+}
+
+const {df} = require('./obj/df');

package/lib/state.js

@@ -1,13 +1,13 @@
 "use strict";
 
-const {S,isObj} = require('./types')
-const ctx = require('./context')
+const {isObj} = require('./types')
 const ns = require('./obj/ns');
 const cp = require('./obj/cp');
+const env = require('./env');
 const stateSym  = Symbol('@lumjs/core/state')
 const stateData = {[stateSym]: false}
 const stateKey  = 'LUM_JS_STATE'
-const stateOpts = {}
+const stateOpts = env.getOpts(); // Some default opts.
 
 function getOpts(localOpts)
 {
@@ -17,16 +17,18 @@ function getOpts(localOpts)
 /**
  * A simple persistent state helper object.
  * 
- * Will use `localStorage` in a browser environment,
- * and `process.env` if running in Node.js.
+ * Uses the `env` module as an abstraction layer for where
+ * the state data is stored.
  * 
- * In both cases the key `LUM_JS_STATE` is used,
- * and the value must be valid JSON data.
+ * The key `LUM_JS_STATE` is used, and the value must be valid JSON data.
  * 
+ * @deprecated use the more flexible `env` module instead.
  * @exports module:@lumjs/core/state
  */
 exports = module.exports =
 {
+  env,
+  
   /**
    * Load (retrieve) state data
    * @param {object} [opts] Options
@@ -45,26 +47,12 @@ exports = module.exports =
 
     if (opts.refresh || !stateData[stateSym])
     {
-      let json;
-      if (ctx.isNode)
-      {
-        json = process.env[stateKey];
-      }
-      else if (ctx.isBrowser)
-      {
-        json = localStorage.getItem(stateKey);
-      }
-  
-      if (typeof json === S)
+      delete opts.default;
+      let storedData = env.get(stateKey, opts);
+      if (isObj(storedData))
       {
-        const revive = opts.jsonRevive;
-        const storedData = JSON.parse(json, revive);
-        if (isObj(storedData))
-        {
-          Object.assign(stateData, storedData);
-        }
+        Object.assign(stateData, storedData);
       }
-
       stateData[stateSym] = true;
     }
 
@@ -77,36 +65,33 @@ exports = module.exports =
    * In a web browser environment, this will save the data
    * into the `localStorage` global object directly.
    * 
-   * In Node.js while this updates the `process.env` object,
-   * there's no way to export to the environment in a truly 
-   * persistent way. So this also will output a shell statement
-   * via `console.log()` that can be exported into the environment 
-   * (or added to a `.env` file, etc.)
+   * In Node.js it is saved to `process.env` but in order to make
+   * those changes persist you'd have to save them to an .env file
+   * or something similar.
    * 
    * @param {object} [opts] Options
    * @param {function} [opts.jsonReplace] JSON.stringify() replacer
-   * @returns {string} The JSON data
+   * @param {function} [opts.onSave] Callback to pass results to.
+   * 
+   * This exists so that a hook may be added that can save the
+   * environment data back into an .env file or something similar
+   * on Node.js runtimes where the environment is not persistent.
+   * 
+   * It will be passed the result object from env.set() and can
+   * do with it whatever is required.
+   * 
+   * @returns {module:@lumjs/core/env~SetResult}
    */
   save(opts)
   {
     if (!stateData[stateSym]) return false;
-
     opts = getOpts(opts);
-  
-    const replace = opts.jsonReplace;
-    let json = JSON.stringify(stateData, replace);
-  
-    if (ctx.isBrowser)
-    {
-      localStorage.setItem(stateKey, json);
-    }
-    else if (ctx.isNode)
+    let res = env.set(stateKey, stateData);
+    if (typeof opts.onSave === 'function')
     {
-      process.env[stateKey] = json;
-      console.log(`${stateKey}='${json.replaceAll("'", "'\"'\"'")}'`);
+      opts.onSave.call(opts, res);
     }
-
-    return json;
+    return res;
   },
 
   /**

package/lib/types/index.js

@@ -21,7 +21,7 @@ Object.assign(exports,
   { // A few standalone exports.
     def,
     TYPES: require('./typelist'),
-    ownCount: require('./owncount'),
+    ownCount: require('../obj/owncount'), // ← TODO: nix in 2.x
   },
 );
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumjs/core",
-  "version": "1.38.4",
+  "version": "1.38.5",
   "main": "lib/index.js",
   "exports": 
   {
@@ -9,13 +9,17 @@
     "./console": "./lib/console.js",
     "./context": "./lib/context.js",
     "./enum": "./lib/enum.js",
+    "./env": "./lib/env.js",
     "./events": "./lib/events/index.js",
     "./events/observable": "./lib/events/observable.js",
     "./flags": "./lib/flags.js",
     "./maps": "./lib/maps.js",
     "./meta": "./lib/meta.js",
-    "./modules": "./lib/modules.js",
+    "./modules": "./lib/node/modules.js",
+    "./node": "./lib/node/index.js",
+    "./node/modules": "./lib/node/modules.js",
     "./obj": "./lib/obj/index.js",
+    "./obj/apply": "./lib/obj/apply.js",
     "./obj/cp": "./lib/obj/cp.js",
     "./obj/df": "./lib/obj/df.js",
     "./observable": "./lib/observable.js",
@@ -32,7 +36,8 @@
   "dependencies": 
   {
     "@lumjs/opts": "^1.0.0",
-    "@lumjs/events-observable": "^1.0.1"
+    "@lumjs/events-observable": "^1.0.1",
+    "semver": "^7.7.3"
   },
   "devDependencies": 
   {