dal-engine-core-js-lib-dev 0.0.0 → 0.0.2

package/dist/index.cjs

@@ -54,6 +54,18 @@ ENGINE_TYPES = Object.freeze(ENGINE_TYPES);
 
 var ENGINE_TYPES$1 = ENGINE_TYPES;
 
+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 representing a Invariant in the design.
  */
@@ -67,16 +79,34 @@ class Invariant extends Base {
         super();
         this.type = ENGINE_TYPES$1.INVARIANT;
         this.invariantViolated = false;
-        if (typeof args === "object" && args !== null) {
-            if (Object.hasOwn(args, "uid")) {
-                this.loadInvariantFromJSON(args);
-            } else {
-                this.name = args.name;
-                this.rule = args.rule;
-            }
+        this.invariantType = null;
+        this.traceId = null;
+        if (typeof args === "object" && Object.hasOwn(args, "uid")) {
+            this.loadInvariantFromJSON(args);
+        } else {
+            this.loadArgs(args);
         }
     }
 
+    /**
+     * Loads the provided arguments.
+     * @throws {MissingAttributes} Thrown when required attr is not present.
+     * @param {Object} args
+     */
+    loadArgs (args) {
+        const expectedAttributes = ["name", "rule"];
+        if (typeof args !== "object" || args === null || Array.isArray(args)) {
+            // Not an object, so all attributes are missing.
+            throw new MissingAttributes("Invariant", expectedAttributes);
+        }
+        expectedAttributes.forEach((attr) => {
+            if (!(attr in args)) {
+                throw new MissingAttributes("Invariant", attr);
+            }
+            this[attr] = args[attr];
+        });
+    }
+
     /**
      * Loads the participant from a JSON object.
      * @param {Object} invariantJSON
@@ -109,13 +139,52 @@ class Invariant extends Base {
     enforceMinLength (value) {
         if ("keys" in this.rule) {
             for (let i = 0; i < this.rule["keys"].length; i++) {
-                console.log(this.rule["keys"][i], value);
                 value = value[this.rule["keys"][i]];
             }
         }        if (value === null || typeof value !== "string" || value.length < this.rule.value) {
             this.invariantViolated = true;
         }
     }
+
+
+    /**
+     * Sets the invariant type.
+     *
+     * The two types of invariants are: Intrinsic and Substrate
+     *
+     * Substrate invariants are learnt by the design from the
+     * environment.
+     *
+     * Intrinsic invariants are arrived at naturally from the
+     * designs control flow, data dependencies and semantic assumptions.
+     *
+     * @param {String} invariantType
+     */
+    setInvariantType (invariantType) {
+        // TODO: Add validation for invariantType.
+        this.invariantType = invariantType;
+    }
+
+    /**
+     * This function adds the trace id which can be used for
+     * automated testing.
+     *
+     * Substrate invariants correspond to a trace that represents
+     * an environment that 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.
+     *
+     * Intrisinc invariants correspond to a trace that represents
+     * a factory default environment that enables the implementation
+     * to prove that it respects the invariant.
+     *
+     * @param {String} traceId ID of trace used for automated testing.
+     */
+    setTraceId (traceId) {
+        // TODO: Add validation for traceId.
+        this.traceId = traceId;
+    }
 }
 
 /**
@@ -131,16 +200,34 @@ class Participant extends Base {
         super();
         this.type = ENGINE_TYPES$1.INVARIANT;
         this.invariants = [];
+        this.abstractionId = null;
         this.invariantViolated = false;
-        if (typeof args === "object" && args !== null) {
-            if (Object.hasOwn(args, "uid")) {
-                this.loadParticipantFromJSON(args);
-            } else {
-                this.name = args.name;
-            }
+        if (typeof args === "object" && Object.hasOwn(args, "uid")) {
+            this.loadParticipantFromJSON(args);
+        } else {
+            this.loadArgs(args);
         }
     }
 
+    /**
+     * Loads the provided arguments.
+     * @throws {MissingAttributes} Thrown when required attr is not present.
+     * @param {Object} args
+     */
+    loadArgs (args) {
+        const expectedAttributes = ["name"];
+        if (typeof args !== "object" || args === null || Array.isArray(args)) {
+            // Not an object, so all attributes are missing.
+            throw new MissingAttributes("Participant", expectedAttributes);
+        }
+        expectedAttributes.forEach((attr) => {
+            if (!(attr in args)) {
+                throw new MissingAttributes("Participant", attr);
+            }
+            this[attr] = args[attr];
+        });
+    }
+
     /**
      * Loads the participant from a JSON object.
      * @param {Object} participantJSON
@@ -187,6 +274,18 @@ class Participant extends Base {
         }
         return this.invariantViolated;
     }
+
+    /**
+     * Map the abstraction ID from the execution to the participant.
+     *
+     * This abstraction id will be used to assign a value to the
+     * participant from the execution using the logged abstraction id.
+     *
+     * @param {String} abstractionId
+     */
+    mapAbstraction (abstractionId) {
+        this.abstractionId = abstractionId;
+    }
 }
 
 /**
@@ -202,16 +301,34 @@ class Behavior extends Base {
         super();
         this.type = ENGINE_TYPES$1.BEHAVIOR;
         this.participants = [];
+        this.abstractionIds = [];
         this.invalidWorldState = false;
-        if (typeof args === "object" && args !== null) {
-            if (Object.hasOwn(args, "uid")) {
-                this.loadBehaviorFromJSON(args);
-            } else {
-                this.name = args.name;
-            }
+        if (typeof args === "object" && Object.hasOwn(args, "uid")) {
+            this.loadBehaviorFromJSON(args);
+        } else {
+            this.loadArgs(args);
         }
     }
 
+    /**
+     * Loads the provided arguments.
+     * @throws {MissingAttributes} Thrown when required attr is not present.
+     * @param {Object} args
+     */
+    loadArgs (args) {
+        const expectedAttributes = ["name"];
+        if (typeof args !== "object" || args === null || Array.isArray(args)) {
+            // Not an object, so all attributes are missing.
+            throw new MissingAttributes("Behavior", expectedAttributes);
+        }
+        expectedAttributes.forEach((attr) => {
+            if (!(attr in args)) {
+                throw new MissingAttributes("Behavior", attr);
+            }
+            this[attr] = args[attr];
+        });
+    }
+
     /**
      * Loads the behavior from a JSON object.
      * @param {Object} behaviorJSON
@@ -241,17 +358,21 @@ class Behavior extends Base {
      * @param {*} value
      */
     setParticipantValue (participantName, value) {
-        for (let i = 0; i < this.participants.length; i++) {
-            const participant = this.participants[i];
-            if (participant.name === participantName) {
-                participant.value = value;
-                const violation = participant.enforceInvariants();
-                if (violation) {
-                    this.invalidWorldState = true;
-                }
-            }
+        const participant = this.participants.find(obj => obj.name === participantName);
+        participant.value = value;
+        const violation = participant.enforceInvariants();
+        if (violation) {
+            this.invalidWorldState = true;
         }
     }
+
+    /**
+     * Maps the abstraction id from execution to the behavior.
+     * @param {String} abstractionId
+     */
+    addMapping (abstractionId) {
+        this.abstractionIds.push(abstractionId);
+    }
 }
 
 /**
@@ -266,13 +387,13 @@ class GraphNode extends Base {
     constructor (args) {
         super();
         this.type = ENGINE_TYPES$1.GRAPH_NODE;
-        this.goToBehaviors = [];
+        this.goToBehaviorsIds = [];
         if (typeof args === "object" && args !== null) {
             if (Object.hasOwn(args, "uid")) {
                 this.loadNodeFromJSON(args);
             } else {
                 this.behavior = args.behavior;
-                this.goToBehaviors = args.goToBehaviors;
+                this.goToBehaviorsIds = args.goToBehaviorsIds;
             }
         }
     }
@@ -285,13 +406,22 @@ class GraphNode extends Base {
         for (const [key, value] of Object.entries(nodesJSON)) {
             if (key === "behavior") {
                 this.behavior = new Behavior(value);
-            } else if (key === "goToBehaviors") {
-                value.forEach(node => this.goToBehaviors.push(new Behavior(node)));
+            } else if (key === "goToBehaviorsIds") {
+                value.forEach(behaviorId => this.goToBehaviorsIds.push(behaviorId));
             } else {
                 this[key] = nodesJSON[key];
             }
         }    }
 
+    /**
+     * Adds a behavior name to the list of behaviors that this 
+     * node transitions to.
+     * @param {String} behaviorId ID of behavior.
+     */
+    addGoToBehavior (behaviorId) {
+        this.goToBehaviorsIds.push(behaviorId);
+    }
+
     /**
      * Checks if the provided behavior name is a valid
      * behavior that the control flow selects as a
@@ -301,9 +431,9 @@ class GraphNode extends Base {
      * @returns {Boolean}
      */
     isValidGoToBehavior (behaviorName) {
-        for (let i = 0; i < this.goToBehaviors.length; i++) {
-            const behavior = this.goToBehaviors[i];
-            if (behavior.name === behaviorName) {
+        for (let i = 0; i < this.goToBehaviorsIds.length; i++) {
+            const behaviorId = this.goToBehaviorsIds[i];
+            if (behaviorId === behaviorName) {
                 return true;
             }
         }
@@ -349,13 +479,13 @@ class BehavioralControlGraph extends Base {
     /**
      * Adds a node to the graph.
      * @param {Behavior} behavior
-     * @param {Array} goToBehaviors
+     * @param {Array} goToBehaviorsIds
      * @returns
      */
-    addNode (behavior, goToBehaviors) {
+    addNode (behavior, goToBehaviorsIds) {
         const node = new GraphNode({
             behavior: behavior,
-            goToBehaviors: goToBehaviors,
+            goToBehaviorsIds: goToBehaviorsIds,
         });
         this.nodes.push(node);
         return node;
@@ -412,6 +542,20 @@ class BehavioralControlGraph extends Base {
             throw new InvalidTransitionError(this.currentNode.behavior.name, nextBehaviorName);
         }
     }
+
+    /**
+     * Exports the graph represented using mermaid syntax for visualization.
+     * @returns {String} Graph as mermaid diagram.
+     */
+    exportAsMermaid () {
+        let mermaid = "flowchart TD\n";
+        this.nodes.forEach((node) => {
+            node.goToBehaviorsIds.forEach((behaviorId) => {
+                mermaid += `  ${node.behavior.name} --> ${behaviorId}\n`;
+            });
+        });
+        return mermaid;
+    }
 }
 
 /**
@@ -419,16 +563,37 @@ class BehavioralControlGraph extends Base {
  * abstraction language. It exposes functions
  * configure the engine through the DAL specification.
  *
- * The execution of an program instrumented with the
- * same design be used to step through the design
- * while the engine automatically debugs the execution.
+ * 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.
  */
 class DALEngine {
     constructor (args) {
         this.graph = new BehavioralControlGraph();
-        for (const [key, value] of Object.entries(args)) {
-            this[key] = value;
+        this.loadArgs(args);
+    }
+
+    /**
+     * Loads the provided arguments.
+     * @throws {MissingAttributes} Thrown when required attr is not present.
+     * @param {Object} args
+     */
+    loadArgs (args) {
+        const expectedAttributes = ["name"];
+        if (typeof args !== "object" || args === null || Array.isArray(args)) {
+            // Not an object, so all attributes are missing.
+            throw new MissingAttributes("Engine", expectedAttributes);
         }
+        expectedAttributes.forEach((attr) => {
+            if (!(attr in args)) {
+                throw new MissingAttributes("Engine", attr);
+            }
+            this[attr] = args[attr];
+        });
     }
 
     /**
@@ -454,9 +619,6 @@ class DALEngine {
      * @returns {Participant}
      */
     createParticipant (args) {
-        // TODO: Validate that the args have the necessary keys
-        // and raise custom error if they are missing.
-        // Perhaps it is better to do that in the class itself.
         return new Participant(args);
     }
 
@@ -466,8 +628,6 @@ class DALEngine {
      * @returns {Behavior}
      */
     createBehavior (args) {
-        // TODO: Validate that the args have the necessary keys
-        // and raise custom error if they are missing.
         return new Behavior(args);
     }
 
@@ -477,10 +637,45 @@ class DALEngine {
      * @returns {Invariant}
      */
     createInvariant (args) {
-        // TODO: Validate that the args have the necessary keys
-        // and raise custom error if they are missing.
         return new Invariant(args);
     }
+
+
+    /**
+     * Returns the node in the graph with the given behavior name.
+     * @param {String} behaviorId
+     * @returns {GraphNode}
+     */
+    getNode (behaviorId) {
+        return this.graph.findNode(behaviorId);
+    }
+
+    /**
+     * Adds a node to the graph with the given behaviorId and goToBehaviors.
+     * @param {String} behaviorId
+     * @param {Array} goToBehaviorsIds
+     * @returns {GraphNode}
+     */
+    addNode (behaviorId, goToBehaviorsIds) {
+        const behavior = this.createBehavior({name: behaviorId});
+        return this.graph.addNode(behavior, goToBehaviorsIds);
+    }
+
+    /**
+     * Adds a goToBehavior to the node with the given behaviorId.
+     * @param {String} behaviorId
+     * @param {String|Array} goToBehaviorIds
+     * @returns {GraphNode}
+     */
+    addGoToBehavior (behaviorId, goToBehaviorIds) {
+        const node = this.graph.findNode(behaviorId);
+        if (Array.isArray(goToBehaviorIds)) {
+            node.goToBehaviorsIds.push(...goToBehaviorIds);
+        } else {
+            node.goToBehaviorsIds.push(goToBehaviorIds);
+        }
+        return node;
+    }
 }
 
 exports.DALEngine = DALEngine;