dal-engine-core-js-lib-dev 0.0.4 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dal-engine-core-js-lib-dev",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "main": "dist/index.cjs",
   "module": "dist/index.esm.js",
   "type": "module",

package/src/Base.js

@@ -1,15 +1,20 @@
-/**
- * Base class for all objects in design.
- */
 class Base {
     /**
-     * Initialize the base class.
+     * Initialize the base class of all members of the design.
+     * The dal_engine_uid is a unique identifier for each instance.
+     * When the design is serialized, the dal_engine_uid is used
+     * to identify when the design is being loaded from file.
      * @param {String} name
      */
     constructor () {
-        this.uid = crypto.randomUUID();
+        this.dal_engine_uid = crypto.randomUUID();
     }
 
+    /**
+     * Returns the type of object as specifed in TYPES.js.
+     * (e.g. participant, behavior, invariant, graph node, etc.)
+     * @returns {Number} The type of node.
+     */
     getType () {
         return this.type;
     }

package/src/BehavioralControlGraph/BehavioralControlGraph.js

@@ -1,37 +1,68 @@
 import Base from "../Base";
+import BehaviorAlreadyExistsError from "../Errors/BehaviorAlreadyExistsError";
 import InvalidTransitionError from "../Errors/InvalidTransitionError";
+import MissingAttributes from "../Errors/MissingAttributes";
 import UnknownBehaviorError from "../Errors/UnknownBehaviorError";
+import isLoadedFromFile from "../helpers/isLoadedFromFile";
 import Behavior from "../Members/Behavior";
 import ENGINE_TYPES from "../TYPES";
 import GraphNode from "./GraphNode";
 
-/**
- * Class representing the behavioral control graph.
- */
+
 class BehavioralControlGraph extends Base {
     /**
-     * Initialize the behavioral control graph.
-     * @param {String} name
-     * @param args
+     * Class representing the behavioral control graph. The behavioral control
+     * graph is a directed graph where nodes represent behaviors and edges
+     * represent valid transitions between behaviors.
+     *
+     * The graph can be used to execute the design by starting at the atomic
+     * node and transitioning to observed behaviors. As the design is executed,
+     * the values of the participants are set from the observed values and the
+     * invariants are checked at each transition to recognize if the design has
+     * entered a semantically invalid state.
+     *
+     * Currently, it only has to be initialized with a name and the remaining
+     * attributes can be added using the provided methods. If the graph is being
+     * loaded from a file, then the presence of a UID in the args will select
+     * the relevant method to load the graph from a JSON object.
+     *
+     * @param {Object} args The args to initialize the behavioral control graph.
      */
     constructor (args) {
         super();
         this.type = ENGINE_TYPES.BEHAVIORAL_CONTROL_GRAPH;
         this.nodes = [];
-        if (typeof args === "object" && args !== null) {
-            if (Object.hasOwn(args, "uid")) {
-                this._loadGraphFromJSON(args);
-            } else {
-                this.name = args.name;
-            }
+        (isLoadedFromFile(args) ? this._loadFromFile(args) : this._loadArgs(args));
+    }
+
+    /**
+     * Loads the provided arguments.
+     * @throws {MissingAttributes} Thrown when required attr is not present.
+     * @param {Object} args
+     */
+    _loadArgs (args) {
+        /**
+         * TODO: Move the attributes to private and use getters and setters
+         * for them. Repeat for all the other classes.
+         */
+        const expectedAttributes = ["name"];
+        if (typeof args !== "object" || args === null || Array.isArray(args)) {
+            // Not an object, so all attributes are missing.
+            throw new MissingAttributes("BehavioralControlGraph", expectedAttributes);
         }
+        expectedAttributes.forEach((attr) => {
+            if (!(attr in args)) {
+                throw new MissingAttributes("BehavioralControlGraph", attr);
+            }
+            this[attr] = args[attr];
+        });
     }
 
     /**
      * Loads the graph from a JSON object..
      * @param {Object} graphJson
      */
-    _loadGraphFromJSON (graphJson) {
+    _loadFromFile (graphJson) {
         for (const [key, value] of Object.entries(graphJson)) {
             if (key === "nodes") {
                 value.forEach(node => this.nodes.push(new GraphNode(node)));
@@ -42,17 +73,27 @@ class BehavioralControlGraph extends Base {
     }
 
     /**
-     * Adds a node to the graph.
-     * @param {Behavior} behaviorId
-     * @param {Array} goToBehaviorsIds
-     * @param {Boolean} isAtomic
-     * @returns
+     * Adds a node to the graph with the provided arguments.
+     *
+     * @param {Behavior} behaviorId ID of the behavior represented by the node.
+     * @param {Array} goToBehaviorIds IDs of the behaviors that are valid
+     * transitions from this node.
+     * @param {Boolean} isAtomic Flag indicating if the behavior represented by
+     * the node is atomic.
+     * @param {Boolean} isDesignFork Flag indicating if the node is a
+     * design fork.
+     * @throws {BehaviorAlreadyExistsError} Raised when a node with the provided
+     * @returns {GraphNode} The created graph node.
      */
-    _addNode (behaviorId, goToBehaviorsIds, isAtomic) {
+    addNode (behaviorId, goToBehaviorIds, isAtomic, isDesignFork) {
+        if (this.nodes.some((node) => node.getBehavior().name === behaviorId)) {
+            throw new BehaviorAlreadyExistsError(behaviorId);
+        }
         const node = new GraphNode({
             behavior: new Behavior({name: behaviorId}),
-            goToBehaviorsIds: goToBehaviorsIds?goToBehaviorsIds:[],
+            goToBehaviorIds: goToBehaviorIds?goToBehaviorIds:[],
             isAtomic: isAtomic?isAtomic:false,
+            isDesignFork: isDesignFork?isDesignFork:false,
         });
         this.nodes.push(node);
         return node;
@@ -64,29 +105,25 @@ class BehavioralControlGraph extends Base {
      * @param {String} behaviorName
      * @throws {UnknownBehaviorError} Raised when the provided behavior
      * does not exist in the graph.
-     * @returns
+     * @returns {GraphNode} The found graph node.
      */
-    _findNode (behaviorName) {
-        for (let i = 0; i < this.nodes.length; i++) {
-            const behavior = this.nodes[i].getBehavior();
-            if (behavior.name === behaviorName) {
-                return this.nodes[i];
-            }
+    findNode (behaviorName) {
+        const node = this.nodes.find(
+            (node) => node.getBehavior().name === behaviorName
+        );
+        if (!node) {
+            throw new UnknownBehaviorError(behaviorName);
         }
-        throw new UnknownBehaviorError(behaviorName);
+        return node;
     }
 
     /**
      * Sets the active node given the behavior name.
-     * The execution provides the next observed
-     * behavior and the active node indicates if
-     * if it is a valid transition.
-     *
      *
      * @param {String} behaviorName
      */
-    _setCurrentBehavior (behaviorName) {
-        const node = this._findNode(behaviorName);
+    setCurrentBehavior (behaviorName) {
+        const node = this.findNode(behaviorName);
         /**
          * TODO: Ensure it is atomic because the execution
          * will only set a behavior when its the first one.
@@ -98,13 +135,15 @@ class BehavioralControlGraph extends Base {
     /**
      * Check if the observed behavior is a valid transition
      * given the current node.
-     * @param {String} nextBehaviorName
+     *
+     * @param {String} nextBehaviorName Name of the next behavior to
+     * transition to.
      * @throws {InvalidTransitionError} Raised when the provided
      * behavior is not a valid transition.
      */
-    _goToBehavior (nextBehaviorName) {
+    goToBehavior (nextBehaviorName) {
         if (this.currentNode.isValidTransition(nextBehaviorName)) {
-            this.currentNode = this._findNode(nextBehaviorName);
+            this.currentNode = this.findNode(nextBehaviorName);
         } else {
             throw new InvalidTransitionError(this.currentNode.getBehavior().name, nextBehaviorName);
         }

package/src/BehavioralControlGraph/GraphNode.js

@@ -1,14 +1,18 @@
 import Base from "../Base";
+import MissingAttributes from "../Errors/MissingAttributes";
+import TransitionAlreadyExistsError from "../Errors/TransitionAlreadyExistsError";
+import isLoadedFromFile from "../helpers/isLoadedFromFile";
 import Behavior from "../Members/Behavior";
 import ENGINE_TYPES from "../TYPES";
-/**
- * Class representing a behavioral control graph node.
- */
+
 class GraphNode extends Base {
     /**
-     * Initialize the node.
-     * @param {String} name
-     * @param args
+     * Class representing a behavioral control graph node. Each node has a
+     * behavior and a list of behaviors it can transition to. The node also
+     * has flags to indicate if the behavior is atomic or if the node is a
+     * design fork.
+     *
+     * @param {Object} args The args to initialize the graph node.
      */
     constructor (args) {
         super();
@@ -16,28 +20,41 @@ class GraphNode extends Base {
         this._behavior = null;
         this._goToBehaviorIds = [];
         this._isAtomic = false;
-        if (typeof args === "object" && args !== null) {
-            if (Object.hasOwn(args, "uid")) {
-                this._loadNodeFromJSON(args);
-            } else {
-                this._behavior = args.behavior;
-                this._goToBehaviorIds = args.goToBehaviorsIds;
-            }
+        this._isDesignFork = false;
+        (isLoadedFromFile(args) ? this._loadFromFile(args) : this._loadArgs(args));
+    }
+
+    /**
+     * Loads the provided arguments.
+     * @param {Object} args Arguments to initialize the graph node with.
+     * @throws {MissingAttributes} Thrown when required attr is not present.
+     */
+    _loadArgs (args) {
+        const expectedAttributes = ["behavior", "goToBehaviorIds", "isAtomic", "isDesignFork"];
+        if (typeof args !== "object" || args === null || Array.isArray(args)) {
+            // Not an object, so all attributes are missing.
+            throw new MissingAttributes("GraphNode", expectedAttributes);
         }
+        expectedAttributes.forEach((attr) => {
+            if (!(attr in args)) {
+                throw new MissingAttributes("GraphNode", attr);
+            }
+            this["_" + attr] = args[attr];
+        });
     }
 
     /**
-     * Loads the nodes from a JSON object.
-     * @param {Object} nodesJSON
+     * Loads the node from file.
+     * @param {Object} nodeJSON The JSON object read from file.
      */
-    _loadNodeFromJSON (nodesJSON) {
-        for (const [key, value] of Object.entries(nodesJSON)) {
+    _loadFromFile (nodeJSON) {
+        for (const [key, value] of Object.entries(nodeJSON)) {
             if (key === "behavior") {
                 this._behavior = new Behavior(value);
-            } else if (key === "goToBehaviorsIds") {
+            } else if (key === "goToBehaviorIds") {
                 value.forEach(behaviorId => this._goToBehaviorIds.push(behaviorId));
             } else {
-                this[key] = nodesJSON[key];
+                this[key] = nodeJSON[key];
             }
         };
     }
@@ -52,24 +69,27 @@ class GraphNode extends Base {
 
     /**
      * Returns the list of behavior names that this node transitions to.
-     * @returns {Array}
+     * @returns {Array} List of behavior names that this node transitions to.
      */
     getGoToBehaviors () {
         return this._goToBehaviorIds;
     }
 
     /**
-     * Adds a behavior name to the list of behaviors that this
-     * node transitions to.
+     * Adds a behavior to the transitions from this node.
      * @param {String} behaviorId ID of behavior.
+     * @throws {TransitionAlreadyExistsError} Raised when a transition to the
+     * provided behavior already exists.
      */
     addGoToBehavior (behaviorId) {
+        if (this._goToBehaviorIds.includes(behaviorId)) {
+            throw new TransitionAlreadyExistsError(this.behaviorName, behaviorId);
+        }
         this._goToBehaviorIds.push(behaviorId);
     }
 
     /**
-     * Adds a behavior name to the list of behaviors that this
-     * node transitions to.
+     * Adds list of behaviors to the transitions from this node.
      * @param {Array} behaviorIds IDs of behaviors.
      */
     addGoToBehaviors (behaviorIds) {
@@ -91,7 +111,7 @@ class GraphNode extends Base {
      * Raises a flag to indicate if the behavior is atomic or not.
      * @param {Boolean} isAtomic Flag indicates if the behavior is atomic.
      */
-    setAtomic (isAtomic) {
+    setIsAtomic (isAtomic) {
         this._isAtomic = isAtomic;
     }
 
@@ -103,6 +123,22 @@ class GraphNode extends Base {
         return this._isAtomic;
     }
 
+    /**
+     * Raises a flag to indicate if this node is a fork in the design.
+     * @param {Boolean} forks Flag indicates if the node is a fork.
+     */
+    setIsDesignFork (forks) {
+        this._isDesignFork = forks;
+    }
+
+    /**
+     * Returns whether the node is a fork in the design or not.
+     * @returns {Boolean}
+     */
+    isDesignFork () {
+        return this._isDesignFork;
+    }
+
     /**
      * Checks if the provided behavior name is a valid
      * transition from this node.

package/src/BehavioralControlGraph/Graphs.js

@@ -1,35 +1,137 @@
+import GraphWithNameExistsError from "../Errors/GraphWithNameExistsError";
+import UnknownGraph from "../Errors/UnknownGraph";
 import BehavioralControlGraph from "./BehavioralControlGraph";
 
 /**
  * Class representing a collection of atomic graphs.
  *
- * These graphs together represent the design. I chose to separate
- * them into their graphs because as the design grows larger, it will
- * be easier to manage the design if it is separated into smaller graphs.
- * It is also easier to visualize in the UI in managable way.
+ * These graphs together represent the design. Within each graph, every node
+ * must be part of the same tree. There cannot be multiple disconnected trees,
+ * if there are, then it is a separate graph in this collection. Each graph
+ * is identified by a unique name and is selected as the active graph when the
+ * atomic behavior is observed. The atomic behavior is not transitioned to from
+ * any other behavior, it is the root of the tree.
  */
-export class Graphs {
-
+class Graphs {
     constructor () {
         this._graphs = {};
+        this.addGraph("default graph");
     }
 
     /**
-     * Adds a graph to the collection of graphs.
+     * Load the graphs from file.
+     *
+     * @param {String} jsonText JSON text representing the collection of graphs.
+     */
+    loadFromJson (jsonText) {
+        const parsed = JSON.parse(jsonText);
+        Object.keys(parsed._graphs).forEach(graphId => {
+            this._graphs[graphId] = new BehavioralControlGraph(parsed._graphs[graphId]);
+        });
+        this._activeGraph = this._graphs[Object.keys(this._graphs)[0]];
+    }
+
+    /**
+     * Given a graph ID, creates the graph and adds it to the collection.
+     *
      * @param {String} graphId ID of the graph.
      * @returns {BehavioralControlGraph} The graph that was added.
+     * @throws {GraphWithNameExistsError} Raised when a graph with the provided
+     * name already exists in the collection of graphs.
      */
     addGraph (graphId) {
-        this._graphs[graphId] = new BehavioralControlGraph();
-        return this._graphs[graphId];
+        if (graphId in this._graphs) {
+            throw new GraphWithNameExistsError(graphId);
+        }
+        this._graphs[graphId] = new BehavioralControlGraph({name: graphId});
+        this._activeGraph = this._graphs[graphId];
+        return this._activeGraph;
     }
 
     /**
-     * Returns the graph with the given graphId.
+     * Returns the graph with the given graphID from the collection.
+     *
      * @param {String} graphId ID of the graph to return.
      * @returns {BehavioralControlGraph} The graph with the given graphId.
+     * @throws {UnknownGraph} Raised when a graph with the provided graphId does
+     * not exist in the collection of graphs.
      */
     getGraph (graphId) {
-        return this._graphs[graphId];
+        if (graphId in this._graphs) {
+            return this._graphs[graphId];
+        } else {
+            throw new UnknownGraph(graphId);
+        }
+    }
+
+    /**
+     * Removes a graph with the given id from the collection of graphs. After
+     * the graph is removed, it selects the first graph in the collection of
+     * graphs. If there are no graphs left in the collection, it creates a new
+     * graph with the name "default graph" and selects it as the active graph.
+     *
+     * @param {String} graphId ID of the graph to remove.
+     * @throws {UnknownGraph} Raised when the provided graphId does not exist
+     * in the collection of graphs.
+     */
+    removeGraph (graphId) {
+        if (graphId in this._graphs) {
+            delete this._graphs[graphId];
+        } else {
+            throw new UnknownGraph(graphId);
+        }
+        // TODO: Is there a better policy for which graph to select
+        // after the current graph is removed?
+        if (Object.keys(this._graphs).length === 0) {
+            this.addGraph("default graph");
+        } else {
+            this._activeGraph = this._graphs[Object.keys(this._graphs)[0]];
+        }
+    }
+
+    /**
+     * Finds the graph with the given graphId and sets it as the active graph.
+     *
+     * @param {String} graphId Id of the graph to set as active.
+     * @returns {BehavioralControlGraph} The currently active graph.
+     * @throws {UnknownGraph} Raised when the provided graphId does not exist
+     * in the collection of graphs.
+     */
+    setActiveGraph (graphId) {
+        if (graphId in this._graphs) {
+            this._activeGraph = this._graphs[graphId];
+        } else {
+            throw new UnknownGraph(graphId);
+        }
+        return this._activeGraph;
+    }
+
+    /**
+     * Returns the active graph.
+     *
+     * @returns {BehavioralControlGraph} The currently active graph.
+     */
+    getActiveGraph () {
+        return this._activeGraph;
+    }
+
+    /**
+     * Returns a collection of all the graphs in the design.
+     *
+     * @returns {Object} The collection of all graphs in the design.
+     */
+    getGraphs () {
+        return this._graphs;
+    }
+
+    /**
+     * Returns a list of all the graph names in the design.
+     *
+     * @returns {Array} A list of all graph names in the design.
+     */
+    getGraphNames () {
+        return Object.keys(this._graphs);
     }
 }
+
+export default Graphs;