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

package/dist/index.esm.js

@@ -1,23 +1,49 @@
-/**
- * Base class for all objects in design.
- */
+class DALEngineError extends Error {
+    constructor (message) {
+        super(message);
+    }
+}
+
+class GraphWithNameExistsError extends DALEngineError {
+    constructor (name) {
+        let msg = `Graph with name "${name}" already exists.`;
+        super(msg);
+    }
+}
+
+class UnknownGraph extends DALEngineError {
+    constructor (name) {
+        let msg = `Graph with name "${name}" does not exist.`;
+        super(msg);
+    }
+}
+
 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;
     }
 }
 
-class DALEngineError extends Error {
-    constructor (message) {
-        super(message);
+class BehaviorAlreadyExistsError extends DALEngineError {
+    constructor (name) {
+        let msg = `Node with Behavior name "${name}" already exists in the graph.`;
+        super(msg);
     }
 }
 
@@ -31,6 +57,18 @@ class InvalidTransitionError extends DALEngineError {
     }
 }
 
+class MissingAttributes extends DALEngineError {
+    constructor (type, attribute) {
+        let msg;
+        if (Array.isArray(attribute) && attribute.length > 1) {
+            msg = `"${type}" must be initialized with the attributes "${attribute}".`;
+        } else {
+            msg = `"${type}" must be initialized with the attribute "${attribute}".`;
+        }
+        super(msg);
+    }
+}
+
 class UnknownBehaviorError extends DALEngineError {
     constructor (behaviorName) {
         super(`The behavior named "${behaviorName}" was not found in graph.`);
@@ -40,38 +78,69 @@ class UnknownBehaviorError extends DALEngineError {
     }
 }
 
-class MissingAttributes extends DALEngineError {
-    constructor (type, attribute) {
-        let msg;
-        if (Array.isArray(attribute) && attribute.length > 1) {
-            msg = `"${type}" must be initialized with the attributes "${attribute}".`;
-        } else {
-            msg = `"${type}" must be initialized with the attribute "${attribute}".`;
-        }
+/**
+ * Checks if the provided object was loaded from a file. This is determind by
+ * checking if the argument is an object and has a "dal_engine_uid" attribute,
+ * which is added to all objects when they are created and is written to file
+ * when the object is serialized.
+ *
+ * @param {*} obj The object to check.
+ * @returns {Boolean} True if the object was loaded from file, false otherwise.
+ */
+const isLoadedFromFile = (obj) => {
+    return typeof obj === "object" && obj !== null
+        && !Array.isArray(obj) && Object.hasOwn(obj, "dal_engine_uid");
+};
+
+class ParticipantAlreadyExistsError extends DALEngineError {
+    constructor (name) {
+        let msg = `Participant with name "${name}" already exists in the behavior.`;
         super(msg);
     }
 }
 
+class UnknownParticipantError extends DALEngineError {
+    constructor (participantName) {
+        super(`The participant named "${participantName}" was not found in the behavior.`);
+    }
+}
+
 let ENGINE_TYPES$1 = {
     BEHAVIOR: 1,
     INVARIANT: 2,
     PARTICIPANT: 3,
-    PRIMITIVE: 4,
-    BEHAVIORAL_CONTROL_GRAPH: 5,
-    GRAPH_NODE: 6,
+    BEHAVIORAL_CONTROL_GRAPH: 4,
+    GRAPH_NODE: 5,
 };
 ENGINE_TYPES$1 = Object.freeze(ENGINE_TYPES$1);
 
 var ENGINE_TYPES = ENGINE_TYPES$1;
 
-/**
- * Class representing a Invariant in the design.
- */
 class Invariant extends Base {
     /**
-     * Initialize the Invariant.
-     * @param {String} name
-     * @param args
+     * Class representing a Invariant in the design. Invariants are rules that
+     * define a valid world state for participants in behaviors. The invariants
+     * are used to check if the design has entered a semantically invalid state
+     * during execution.
+     *
+     * The expected attributes in args are:
+     * - name: Name of the invariant.
+     * - rule: The rule that defines the how to enforce the invariant. This
+     * will be formally defined in a collection of invariant rules that can
+     * be chosen from when creating an invariant.
+     *
+     * Currently, the only supported invariant rule is the string min length
+     * rule, which can be specified as follows:
+     * {
+     *     "name": "MinLengthConstraint",
+     *     "rule": {
+     *         "type": "minLength",
+     *         "keys": ["value", "name"],
+     *         "value": 1,
+     *     },
+     * }
+     *
+     * @param {Object} args The arguments to initialize the invariant with.
      */
     constructor (args) {
         super();
@@ -79,17 +148,13 @@ class Invariant extends Base {
         this.invariantViolated = false;
         this.invariantType = null;
         this.traceId = null;
-        if (typeof args === "object" && Object.hasOwn(args, "uid")) {
-            this._loadInvariantFromJSON(args);
-        } else {
-            this._loadArgs(args);
-        }
+        (isLoadedFromFile(args) ? this._loadFromFile(args) : this._loadArgs(args));
     }
 
     /**
-     * Loads the provided arguments.
+     * Loads the invariant from the provided arguments.
      * @throws {MissingAttributes} Thrown when required attr is not present.
-     * @param {Object} args
+     * @param {Object} args The arguments to initialize the invariant with.
      */
     _loadArgs (args) {
         const expectedAttributes = ["name", "rule"];
@@ -106,10 +171,10 @@ class Invariant extends Base {
     }
 
     /**
-     * Loads the participant from a JSON object.
-     * @param {Object} invariantJSON
+     * Loads the invariant from file.
+     * @param {Object} invariantJSON The JSON object to load the invariant from.
      */
-    _loadInvariantFromJSON (invariantJSON) {
+    _loadFromFile (invariantJSON) {
         for (const [key, value] of Object.entries(invariantJSON)) {
             this[key] = value;
         }        // Reset these because they are set by the execution
@@ -118,9 +183,10 @@ class Invariant extends Base {
     }
 
     /**
-     * Evaluate the invariant.
-     * @param {*} value
-     * @returns {Boolean}
+     * Evaluate the invariant by applying the invariant rule to the provided
+     * value. Returns a flag indicating whether the invariant was violated.
+     * @param {*} value The value to evaluate the invariant on.
+     * @returns {Boolean} Returns flag indicating if invariant was violated.
      */
     evaluate (value) {
         this.invariantViolated = false;
@@ -131,8 +197,8 @@ class Invariant extends Base {
     }
 
     /**
-     * Enforce the string min length invariant
-     * @param value
+     * Enforce the string min length invariant.
+     * @param {*} value The value to enforce the invariant on.
      */
     enforceMinLength (value) {
         if ("keys" in this.rule) {
@@ -168,7 +234,7 @@ class Invariant extends Base {
      * automated testing.
      *
      * Substrate invariants correspond to a trace that represents
-     * an environment that reveals a limitation of the substrate,
+     * an environment which reveals a limitation of the substrate,
      * thus motivating the invariant. It is also the environment
      * in which an implementation can prove that it respects this
      * invariant.
@@ -185,14 +251,17 @@ class Invariant extends Base {
     }
 }
 
-/**
- * Class representing a participant in the design.
- */
 class Participant extends Base {
     /**
-     * Initialize the semantic participant.
-     * @param {String} name
-     * @param args
+     * Class representing a participant in the design. The participants are
+     * entites in deisgn that participate in the behavior. They are mapped onto
+     * the implementation and their value is loaded from the execution. The
+     * participants define a valid world state for the behavior to happen in
+     * through invariants. When the value of the participant violates an
+     * invariant, the design has entered a semantically invalid state and is
+     * the root cause of downstream failure(s).
+     *
+     * @param {Object} args The arguments to initialize the participant.
      */
     constructor (args) {
         super();
@@ -200,11 +269,7 @@ class Participant extends Base {
         this.invariants = [];
         this.abstractionId = null;
         this.invariantViolated = false;
-        if (typeof args === "object" && Object.hasOwn(args, "uid")) {
-            this._loadParticipantFromJSON(args);
-        } else {
-            this._loadArgs(args);
-        }
+        (isLoadedFromFile(args) ? this._loadFromFile(args) : this._loadArgs(args));
     }
 
     /**
@@ -228,9 +293,9 @@ class Participant extends Base {
 
     /**
      * Loads the participant from a JSON object.
-     * @param {Object} participantJSON
+     * @param {Object} participantJSON The JSON object read from file.
      */
-    _loadParticipantFromJSON (participantJSON) {
+    _loadFromFile (participantJSON) {
         for (const [key, value] of Object.entries(participantJSON)) {
             if (key === "invariants") {
                 value.forEach(node => this.invariants.push(new Invariant(node)));
@@ -241,8 +306,8 @@ class Participant extends Base {
 
     /**
      * Adds an invariant to the participant.
-     * @param {Invariant} invariant
-     * @returns
+     * @param {Invariant} invariant The invariant to add.
+     * @returns {Invariant} The invariant that was added.
      */
     addInvariant (invariant) {
         this.invariants.push(invariant);
@@ -250,16 +315,18 @@ class Participant extends Base {
     }
 
     /**
-     * Sets the value of the participant.
-     * @param {*} value
+     * Sets the value of this participant.
+     * @param {*} value The value to set for the participant.
      */
     setValue (value) {
         this.value = value;
     }
 
     /**
-     * Enforces the particiants invariants.
-     * @returns {Boolean}
+     * Enforces the participant's invariants. Raises a flag indicating if an
+     * invariant was violated and counts the number of invariant violations.
+     *
+     * @returns {Boolean} Returns flag indicating if any invariant was violated.
      */
     enforceInvariants () {
         this.invariantViolated = false;
@@ -279,19 +346,23 @@ class Participant extends Base {
      * This abstraction id will be used to assign a value to the
      * participant from the execution using the logged abstraction id.
      *
-     * @param {String} abstractionId
+     * @param {String} abstractionId The abstraction ID to map to the
+     * participant.
      */
     mapAbstraction (abstractionId) {
+        /**
+         * TODO: Much like the behavior, I am settling on a clean way to map
+         * the participant onto the implementation without introducing new
+         * unncessary layers.
+         */
         this.abstractionId = abstractionId;
     }
 }
 
-/**
- * Class representing a Behavior in the design.
- */
 class Behavior extends Base {
     /**
      * Initialize the Behavior.
+     *
      * @param {String} name
      * @param args
      */
@@ -301,15 +372,12 @@ class Behavior extends Base {
         this.participants = [];
         this.abstractionIds = [];
         this.invalidWorldState = false;
-        if (typeof args === "object" && Object.hasOwn(args, "uid")) {
-            this._loadBehaviorFromJSON(args);
-        } else {
-            this._loadArgs(args);
-        }
+        (isLoadedFromFile(args) ? this._loadFromFile(args) : this._loadArgs(args));
     }
 
     /**
      * Loads the provided arguments.
+     *
      * @throws {MissingAttributes} Thrown when required attr is not present.
      * @param {Object} args
      */
@@ -328,10 +396,12 @@ class Behavior extends Base {
     }
 
     /**
-     * Loads the behavior from a JSON object.
-     * @param {Object} behaviorJSON
+     * Loads the behavior from a JSON object that was read from file.
+     *
+     * @param {Object} behaviorJSON The JSON object representing the behavior
+     * read from file.
      */
-    _loadBehaviorFromJSON (behaviorJSON) {
+    _loadFromFile (behaviorJSON) {
         for (const [key, value] of Object.entries(behaviorJSON)) {
             if (key === "participants") {
                 value.forEach(node => this.participants.push(new Participant(node)));
@@ -342,45 +412,65 @@ class Behavior extends Base {
 
     /**
      * Adds a participant to the behavior.
-     * @param {Participant} participant
-     * @returns
+     *
+     * @param {Participant} participant The participant to add.
+     * @returns {Participant} The added participant.
+     * @throws {ParticipantAlreadyExistsError} Thrown when a participant with
+     * the same name already exists in the behavior.
      */
     addParticipant (participant) {
+        if (this.participants.some(p => p.name === participant.name)) {
+            throw new ParticipantAlreadyExistsError(participant.name);
+        }
         this.participants.push(participant);
         return participant;
     }
 
     /**
-     * Set the participant value.
-     * @param {String} participantName
-     * @param {*} value
+     * Sets the value of a participant and checks for invariant violations.
+     * If any invariant is violated, the world state for this behavior is
+     * marked as invalid.
+     *
+     * @param {String} name Name of the participant whose value is being set.
+     * @param {*} value Value to set for the participant.
+     * @throws {UnknownParticipantError} Thrown when a participant with the
+     * provided name does not exist in the behavior.
      */
-    setParticipantValue (participantName, value) {
-        const participant = this.participants.find(obj => obj.name === participantName);
+    setParticipantValue (name, value) {
+        const participant = this.participants.find(obj => obj.name === name);
+        if (!participant) {
+            throw new UnknownParticipantError(name);
+        }
         participant.value = value;
-        const violation = participant.enforceInvariants();
-        if (violation) {
+        if (participant.enforceInvariants()) {
             this.invalidWorldState = true;
         }
     }
 
     /**
-     * Maps the abstraction id from execution to the behavior.
-     * @param {String} abstractionId
+     * Maps the abstraction id from implementation to the behavior.
+     *
+     * @param {String} abstractionId ID of mapped abstraction.
      */
     addMapping (abstractionId) {
+        /**
+         * TODO: After some more thinking, it seems to me that the
+         * uniqe identifier should be a file name and line number.
+         * It doesn't make sense to create a new abstraction id,
+         * however, I will resolve this soon and remove this TODO.
+         */
         this.abstractionIds.push(abstractionId);
     }
 }
 
-/**
- * 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();
@@ -388,28 +478,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];
             }
         }    }
 
@@ -423,15 +526,14 @@ 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.
      */
     addGoToBehavior (behaviorId) {
@@ -439,8 +541,7 @@ class GraphNode extends Base {
     }
 
     /**
-     * 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) {
@@ -462,7 +563,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;
     }
 
@@ -474,6 +575,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.
@@ -491,33 +608,60 @@ class GraphNode extends Base {
     }
 }
 
-/**
- * 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)));
@@ -527,17 +671,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;
@@ -549,29 +703,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.
@@ -583,13 +733,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);
         }
@@ -611,31 +763,174 @@ class BehavioralControlGraph extends Base {
 }
 
 /**
- * An object representing an engine written in Design
- * abstraction language. It exposes functions
- * configure the engine through the DAL specification.
+ * Class representing a collection of atomic graphs.
+ *
+ * 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.
+ */
+class Graphs {
+    constructor () {
+        this._graphs = {};
+        this.addGraph("default graph");
+    }
+
+    /**
+     * 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) {
+        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 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) {
+        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);
+    }
+}
+
+/**
+ * This engine can be used to define and execute designs defined in a
+ * Design Abstraction Language (DAL).
+ *
+ * This class is the main interface for users to interact with the
+ * engine. It exposes functions to configure the engine and to execute
+ * the design. It also exposes functions to serialize and deserialize
+ * the engine to and from JSON text.
+ *
+ * A design can consist of multiple atomic behavioral control graphs and
+ * this class allows users to create, select, and delete graphs. It also
+ * allows users to add nodes to the graph and to transition between
+ * behaviors in the graph. It also allows users to create participants,
+ * behaviors, and invariants and assign them to nodes in the graph.
  *
- * The design specified in this engine is mapped onto
- * the implementation using abstraction ids. The
- * implementation is then instrumented and the resulting
- * execution trace is fed back into the engine and is
- * automatically debugged by transforming the execution
- * into the behavior of the design and enforcing the
- * invariants.
+ * The selected graph is determined by the atomic behavior that is observed.
+ * The design is executed by transitioning between behaviors in the graph.
+ * 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.
  */
 class DALEngine {
     constructor (args) {
-        this.graph = new BehavioralControlGraph();
-        this.atomicGraphs = [];
-        this.loadArgs(args);
+        this.graphs = new Graphs();
+        this.graph = this.graphs.getActiveGraph();
+        this._loadArgs(args);
+        console.log("Initialized DAL Engine with graphs: ", this.graphs);
     }
 
     /**
-     * Loads the provided arguments.
-     * @throws {MissingAttributes} Thrown when required attr is not present.
-     * @param {Object} args
+     * Sets the provided arguments to the engine.
+     *
+     * @throws {MissingAttributes} Thrown when required attributes are
+     * not present.
+     * @param {Object} args Arguments to load.
      */
-    loadArgs (args) {
+    _loadArgs (args) {
         const expectedAttributes = ["name"];
         if (typeof args !== "object" || args === null || Array.isArray(args)) {
             // Not an object, so all attributes are missing.
@@ -650,98 +945,187 @@ class DALEngine {
     }
 
     /**
-     * Exports the behavioral control graph to JSON text.
-     * @returns {String}
+     * Serializes the behavioral control graphs and returns the JSON text.
+     *
+     * @returns {String} Returns JSON string representing the control graphs.
      */
     serialize () {
-        return JSON.stringify(this.graph);
+        return JSON.stringify(this.graphs);
     }
 
     /**
-     * Import the behavioral control graph from JSON text.
-     * @param {String} jsonText
+     * Loads the behavioral control graphs from JSON text and sets
+     * the active graph to the first graph in the collection of graphs.
+     *
+     * @param {String} serializedText JSON text representing the control
+     * graphs.
+     * @throws {SyntaxError|TypeError} Thrown when the JSON text is invalid.
      */
-    deserialize (jsonText) {
-        this.graph = new BehavioralControlGraph(JSON.parse(jsonText));
+    deserialize (serializedText) {
+        // TODO: Improve validation to throw specific error.
+        this.graphs = new Graphs();
+        this.graphs.loadFromJson(serializedText);
+        this.graph = this.graphs.getActiveGraph();
     }
 
     /**
-     * Creates a participant.
-     * @param {Object} args
-     * @returns {Participant}
+     * Creates a graph with the given name and sets it as the active graph.
+     *
+     * @param {String} name Name of the graph to create.
+     * @throws {GraphWithNameExistsError} Thrown when a graph with the
+     * provided name already exists.
+     */
+    createGraph (name) {
+        this.graph = this.graphs.addGraph(name);
+    }
+
+    /**
+     * Sets the active graph to the graph with the given graphId.
+     *
+     * @param {String} graphId ID of the graph to set as active
+     * @throws {UnknownGraph} Thrown when the provided graphId does
+     * not exist in the collection of graphs.
+     */
+    selectGraph (graphId) {
+        this.graph = this.graphs.setActiveGraph(graphId);
+    }
+
+    /**
+     * Removes the graph with the given graphId
+     *
+     * @param {String} graphId Id of graph to remove.
+     * @throws {UnknownGraph} Thrown when the provided graphId does not
+     * exist in the collection of graphs.
+     */
+    removeGraph (graphId) {
+        this.graphs.removeGraph(graphId);
+        this.graph = this.graphs.getActiveGraph();
+    }
+
+    /**
+     * Returns the names of all the graphs in the design.
+     *
+     * @returns {Array} Returns an array of graph names.
+     */
+    getSelectableGraphs () {
+        return this.graphs.getGraphNames();
+    }
+
+    /**
+     * Creates a participant with the provided args and returns it.
+     *
+     * @param {Object} args Arguments to create the participant with.
+     * @returns {Participant} Returns the created participant.
+     * @throws {MissingAttributes} Thrown when required attributes are not
+     * present in the args. See Participant class for required attributes.
      */
     createParticipant (args) {
         return new Participant(args);
     }
 
     /**
-     * Creates a behavior.
-     * @param {Object} args
-     * @returns {Behavior}
+     * Creates a behavior with the provided args and returns it.
+     *
+     * @param {Object} args Arguments to create the behavior with.
+     * @returns {Behavior} Returns the created behavior.
+     * @throws {MissingAttributes} Thrown when required attributes are not
+     * present in the args. See Behavior class for required attributes.
      */
     createBehavior (args) {
         return new Behavior(args);
     }
 
     /**
-     * Creates an invariant.
-     * @param {Object} args
-     * @returns {Invariant}
+     * Creates an invariant with the provided args and returns it.
+     *
+     * @param {Object} args Arguments to create the invariant with.
+     * @returns {Invariant} Returns the created invariant.
+     * @throws {MissingAttributes} Raised when required attributes are not
+     * present in the args. See Invariant class for required attributes.
      */
     createInvariant (args) {
         return new Invariant(args);
     }
 
-
     /**
      * Returns the node in the graph with the given behavior name.
-     * @param {String} behaviorId
-     * @returns {GraphNode}
+     *
+     * @param {String} behaviorId ID of the behavior.
+     * @returns {GraphNode} Returns the node in the graph with the
+     * given behavior name.
+     * @throws {UnknownBehaviorError} Thrown when the provided behaviorId is not
+     * a valid behavior in the graph.
      */
     getNode (behaviorId) {
-        return this.graph._findNode(behaviorId);
+        return this.graph.findNode(behaviorId);
     }
 
     /**
      * Adds a node to the graph with the given behaviorId and goToBehaviors.
-     * @param {String} behaviorId
-     * @param {Array} goToBehaviorsIds
-     * @param {Boolean} isAtomic
-     * @returns {GraphNode}
+     *
+     * @param {String} behaviorId ID of the behavior for the node.
+     * @param {Array} goToBehaviorIds IDs of the behaviors that this node
+     * transitions to.
+     * @param {Boolean} isAtomic Flag to indicate if this node contains an
+     * atomic behavior.
+     * @param {Boolean} isDesignFork Flag to indicate if this node
+     * is a fork in the design.
+     * @returns {GraphNode} Returns the created graph node.
+     * @throws {BehaviorAlreadyExistsError} Raised when a node with the provided
+     * behaviorId already exists in the graph.
      */
-    addNode (behaviorId, goToBehaviorsIds, isAtomic) {
-        return this.graph._addNode(behaviorId, goToBehaviorsIds, isAtomic);
+    addNode (behaviorId, goToBehaviorIds, isAtomic, isDesignFork) {
+        return this.graph.addNode(
+            behaviorId,
+            goToBehaviorIds,
+            isAtomic,
+            isDesignFork
+        );
     }
 
     /**
      * Deletes a node from the graph with the given behaviorId and
      * removes it from the goToBehavior list of all other nodes.
-     * @param {String} behaviorId
+     *
+     * @param {String} behaviorId Behavior ID of the node to delete.
+     * @returns {GraphNode} Returns the deleted graph node.
+     * @throws {UnknownBehaviorError} Thrown when the provided behaviorId is not
+     * a valid behavior in the graph.
      */
     removeNode (behaviorId) {
-        const node = this.graph._findNode(behaviorId);
+        const node = this.graph.findNode(behaviorId);
         const nodeIndex = this.graph.nodes.indexOf(node);
-        this.graph.nodes.splice(nodeIndex, 1);
+        const removedNode = this.graph.nodes.splice(nodeIndex, 1);
         for (const node of this.graph.nodes) {
             node.removeGoToBehavior(behaviorId);
         }
+        return removedNode[0];
     }
 
     /**
-     * Sets the current behavior in the graph.
-     * @param {String} behaviorId
+     * Sets the current behavior in the graph. Since the behavior is not
+     * being transitioned from another, it must be an atomic behavior.
+     *
+     * @param {String} behaviorId ID of the behavior to set as current.
+     * @throws {UnknownBehaviorError} Thrown when the provided behavior is not
+     * a valid behavior in the graph.
      */
     setCurrentBehavior (behaviorId) {
-        this.graph._setCurrentBehavior(behaviorId);
+        this.graph.setCurrentBehavior(behaviorId);
     }
 
     /**
-     * Transitions the graph to the given behavior if it
-     *  is a valid transition from the current behavior.
+     * For the current node in the graph, transitions to the node with the given
+     * behaviorId if it is a valid transition.
+     *
      * @param {String} nextBehaviorId ID of the next behavior.
+     * @throws {UnknownBehaviorError} Thrown when the provided behavior is not
+     * a valid behavior in the graph.
+     * @throws {InvalidTransitionError} Thrown when the provided behavior is not
+     * a valid transition from the current node.
      */
     goToBehavior (nextBehaviorId) {
-        this.graph._goToBehavior(nextBehaviorId);
+        this.graph.goToBehavior(nextBehaviorId);
     }
 }