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

package/src/DALEngine.js

@@ -1,35 +1,45 @@
-import BehavioralControlGraph from "./BehavioralControlGraph/BehavioralControlGraph";
+import Graphs from "./BehavioralControlGraph/Graphs";
 import MissingAttributes from "./Errors/MissingAttributes";
 import Behavior from "./Members/Behavior";
 import Invariant from "./Members/Invariant";
 import Participant from "./Members/Participant";
 
 /**
- * An object representing an engine written in Design
- * abstraction language. It exposes functions
- * configure the engine through the DAL specification.
+ * This engine can be used to define and execute designs defined in a
+ * Design Abstraction Language (DAL).
  *
- * 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.
+ * 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 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.
  */
 export 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);
     }
 
     /**
-     * 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.
@@ -44,97 +54,188 @@ export 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);
+    }
+
+    /**
+     * 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 (serializedText) {
+        // TODO: Improve validation to throw specific error.
+        this.graphs = new Graphs();
+        this.graphs.loadFromJson(serializedText);
+        this.graph = this.graphs.getActiveGraph();
+    }
+
+    /**
+     * 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);
     }
 
     /**
-     * Import the behavioral control graph from JSON text.
-     * @param {String} jsonText
+     * 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.
      */
-    deserialize (jsonText) {
-        this.graph = new BehavioralControlGraph(JSON.parse(jsonText));
+    selectGraph (graphId) {
+        this.graph = this.graphs.setActiveGraph(graphId);
     }
 
     /**
-     * Creates a participant.
-     * @param {Object} args
-     * @returns {Participant}
+     * 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);
+        // TODO: Move this to graph class, this class shouldn't
+        // modifiy the graph structure directly.
+        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);
     }
 }

package/src/Errors/BehaviorAlreadyExistsError.js

@@ -0,0 +1,10 @@
+import DALEngineError from "./DALEngineError";
+
+class BehaviorAlreadyExistsError extends DALEngineError {
+    constructor (name) {
+        let msg = `Node with Behavior name "${name}" already exists in the graph.`;
+        super(msg);
+    }
+}
+
+export default BehaviorAlreadyExistsError;

package/src/Errors/GraphWithNameExistsError.js

@@ -0,0 +1,10 @@
+import DALEngineError from "./DALEngineError";
+
+class GraphWithNameExistsError extends DALEngineError {
+    constructor (name) {
+        let msg = `Graph with name "${name}" already exists.`;
+        super(msg);
+    }
+}
+
+export default GraphWithNameExistsError;

package/src/Errors/ParticipantAlreadyExistsError.js

@@ -0,0 +1,10 @@
+import DALEngineError from "./DALEngineError";
+
+class ParticipantAlreadyExistsError extends DALEngineError {
+    constructor (name) {
+        let msg = `Participant with name "${name}" already exists in the behavior.`;
+        super(msg);
+    }
+}
+
+export default ParticipantAlreadyExistsError;

package/src/Errors/TransitionAlreadyExistsError.js

@@ -0,0 +1,11 @@
+import DALEngineError from "./DALEngineError";
+
+class TransitionAlreadyExistsError extends DALEngineError {
+    constructor (behaviorName, transitionName) {
+        let msg = `Node with behavior named "${behaviorName}" already has a transition\
+         to behavior "${transitionName}".`;
+        super(msg);
+    }
+}
+
+export default TransitionAlreadyExistsError;

package/src/Errors/UnknownGraph.js

@@ -0,0 +1,10 @@
+import DALEngineError from "./DALEngineError";
+
+class UnknownGraph extends DALEngineError {
+    constructor (name) {
+        let msg = `Graph with name "${name}" does not exist.`;
+        super(msg);
+    }
+}
+
+export default UnknownGraph;

package/src/Errors/UnknownParticipantError.js

@@ -0,0 +1,9 @@
+import DALEngineError from "./DALEngineError";
+
+class UnknownParticipantError extends DALEngineError {
+    constructor (participantName) {
+        super(`The participant named "${participantName}" was not found in the behavior.`);
+    }
+}
+
+export default UnknownParticipantError;

package/src/Members/Behavior.js

@@ -1,13 +1,16 @@
 import Base from "../Base";
 import MissingAttributes from "../Errors/MissingAttributes";
+import ParticipantAlreadyExistsError from "../Errors/ParticipantAlreadyExistsError";
+import UnknownParticipantError from "../Errors/UnknownParticipantError";
+import isLoadedFromFile from "../helpers/isLoadedFromFile";
 import ENGINE_TYPES from "../TYPES";
 import Participant from "./Participant";
-/**
- * Class representing a Behavior in the design.
- */
+
+
 class Behavior extends Base {
     /**
      * Initialize the Behavior.
+     *
      * @param {String} name
      * @param args
      */
@@ -17,15 +20,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
      */
@@ -44,10 +44,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)));
@@ -59,33 +61,53 @@ 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);
     }
 }

package/src/Members/Invariant.js

@@ -1,15 +1,33 @@
 import Base from "../Base";
 import MissingAttributes from "../Errors/MissingAttributes";
+import isLoadedFromFile from "../helpers/isLoadedFromFile";
 import ENGINE_TYPES from "../TYPES";
 
-/**
- * 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();
@@ -17,17 +35,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"];
@@ -44,10 +58,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;
         };
@@ -57,9 +71,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;
@@ -70,8 +85,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) {
@@ -108,7 +123,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.