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

package/src/Members/Behavior.js

@@ -1,4 +1,5 @@
 import Base from "../Base";
+import MissingAttributes from "../Errors/MissingAttributes";
 import ENGINE_TYPES from "../TYPES";
 import Participant from "./Participant";
 /**
@@ -14,16 +15,34 @@ class Behavior extends Base {
         super();
         this.type = ENGINE_TYPES.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
@@ -54,17 +73,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);
+    }
 }
 
 export default Behavior;

package/src/Members/Invariant.js

@@ -1,5 +1,7 @@
 import Base from "../Base";
+import MissingAttributes from "../Errors/MissingAttributes";
 import ENGINE_TYPES from "../TYPES";
+
 /**
  * Class representing a Invariant in the design.
  */
@@ -12,17 +14,35 @@ class Invariant extends Base {
     constructor (args) {
         super();
         this.type = ENGINE_TYPES.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.invariantViolated = false;
+        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
@@ -56,7 +76,6 @@ 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]];
             }
         };
@@ -64,6 +83,46 @@ class Invariant extends Base {
             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;
+    }
 }
 
 export default Invariant;

package/src/Members/Participant.js

@@ -1,6 +1,8 @@
 import Base from "../Base";
+import MissingAttributes from "../Errors/MissingAttributes";
 import ENGINE_TYPES from "../TYPES";
 import Invariant from "./Invariant";
+
 /**
  * Class representing a participant in the design.
  */
@@ -14,16 +16,34 @@ class Participant extends Base {
         super();
         this.type = ENGINE_TYPES.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
@@ -71,6 +91,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;
+    }
 }
 
 export default Participant;

package/tests/DALEngine.test.js

@@ -4,6 +4,7 @@ import {describe, expect, it} from "vitest";
 
 import {DALEngine} from "../src/DALEngine.js";
 import InvalidTransitionError from "../src/Errors/InvalidTransitionError.js";
+import MissingAttributes from "../src/Errors/MissingAttributes.js";
 import UnknownBehaviorError from "../src/Errors/UnknownBehaviorError.js";
 import ENGINE_TYPES from "../src/TYPES.js";
 
@@ -13,41 +14,46 @@ describe("DALEngine", () => {
         expect(dalInstance.name).toBe("Library Manager");
     });
 
-    it("adds node to graph", () => {
+    it(" throws on missing attributes", () => {
+        expect(() => {new DALEngine()}).toThrow(MissingAttributes);
         const d = new DALEngine({name: "Library Manager"});
-        const behavior1 = d.createBehavior({name: "AcceptBookFromUser"});
-        const behavior2 = d.createBehavior({name: "AddBookToBasket"});
-        const goToBehaviors = [behavior2];
+        expect(() => {d.createBehavior()}).toThrow(MissingAttributes);
+        expect(() => {d.createBehavior({})}).toThrow(MissingAttributes);
+        expect(() => {d.createBehavior({"rule": "adsf"})}).toThrow(MissingAttributes);
+        expect(() => {d.createInvariant({"name": "asdf"})}).toThrow(MissingAttributes);
+        expect(() => {d.createParticipant()}).toThrow(MissingAttributes);
+        expect(() => {d.createParticipant({})}).toThrow(MissingAttributes);
+    });
 
-        const node = d.graph.addNode(behavior1, goToBehaviors)
+    it("adds node to graph", () => {
+        const d = new DALEngine({name: "Library Manager"});
+        const goToBehaviorIds = ["AddBookToBasket"];
+        const node = d.addNode("AcceptBookFromUser", goToBehaviorIds)
 
         const nodeType = node.type;
         expect(nodeType).toBe(ENGINE_TYPES.GRAPH_NODE);
-        expect(node.behavior).toStrictEqual(behavior1);
-        expect(node.goToBehaviors).toStrictEqual([behavior2]);
-
-        const foundNode = d.graph.findNode("AcceptBookFromUser");
-        expect(foundNode).toStrictEqual(node);
+        expect(node.behavior.name).toStrictEqual("AcceptBookFromUser");
+        expect(node.goToBehaviorsIds).toStrictEqual(goToBehaviorIds);
     });
 
     it("find node that was added using behavior name", () => {
         const d = new DALEngine({name: "Library Manager"});
-        const behavior1 = d.createBehavior({name: "AcceptBookFromUser"});
-        const behavior2 = d.createBehavior({name: "AddBookToBasket"});
-        const node = d.graph.addNode(behavior1, [behavior2])
+        const node = d.addNode("AcceptBookFromUser", []);
 
-        const foundNode = d.graph.findNode("AcceptBookFromUser");
+        expect(() => {d.getNode("AcceptBookFrmUser")}).toThrow(UnknownBehaviorError);
+
+        const foundNode = d.getNode("AcceptBookFromUser");
         expect(foundNode).toStrictEqual(node);
     });
 
     it("find node and check if observed behavior is valid transition", () => {
         const d = new DALEngine({name: "Library Manager"});
-        const behavior1 = d.createBehavior({name: "AcceptBookFromUser"});
-        const behavior2 = d.createBehavior({name: "AddBookToBasket"});
-        const behavior3 = d.createBehavior({name: "AnotherBehavior"});
-        d.graph.addNode(behavior1, [behavior2, behavior3])
-        d.graph.addNode(behavior2, [])
-        d.graph.addNode(behavior3, [])
+        const node1 = d.addNode("AcceptBookFromUser", []);
+        const node2 = d.addNode("AddBookToBasket", []);
+        d.addNode("AnotherBehavior", []);
+
+        node1.addGoToBehavior("AddBookToBasket");
+        node2.addGoToBehavior("AnotherBehavior");
 
         // Misspell behavior name to trigger unknown behavior error
         expect(() => {
@@ -55,20 +61,20 @@ describe("DALEngine", () => {
         }).toThrow(UnknownBehaviorError);
 
         d.graph.setCurrentBehavior("AcceptBookFromUser");
-        expect(d.graph.currentNode.behavior).toBe(behavior1);
+        expect(d.graph.currentNode).toBe(node1);
 
         d.graph.goToBehavior("AddBookToBasket")
-        expect(d.graph.currentNode.behavior).toBe(behavior2);
+        expect(d.graph.currentNode).toBe(node2);
 
         // Reset current behavior so transition is valid
         d.graph.setCurrentBehavior("AcceptBookFromUser");
-        d.graph.goToBehavior("AnotherBehavior")
-        expect(d.graph.currentNode.behavior).toBe(behavior3);
+        d.graph.goToBehavior("AddBookToBasket")
+        expect(d.graph.currentNode).toBe(node2);
 
         // Raises error because current behavior is "AnotherBehavior"
         // and it does not transition to itself.
         expect(() => {
-            d.graph.goToBehavior("AnotherBehavior")
+            d.graph.goToBehavior("AddBookToBasket")
         }).toThrow(InvalidTransitionError);
 
         // Reset the current behavior and then go to a behavior
@@ -82,7 +88,16 @@ describe("DALEngine", () => {
     it("add invariant to participant", () => {
         const d = new DALEngine({name: "Library Manager"});
         const book = d.createParticipant({name: "book"});
-        const invariant = d.createInvariant({name: "minLength"});
+        const invariant = d.createInvariant(
+            {
+                "name": "MinLengthConstraint",
+                "rule": {
+                    "type": "minLength",
+                    "keys": ["value", "name"],
+                    "value": 1,
+                },
+            }
+        );
 
         book.addInvariant(invariant);
 
@@ -105,13 +120,15 @@ describe("DALEngine", () => {
         );
         book.addInvariant(invariant);
 
-        const behavior1 = d.createBehavior({name: "AcceptBookFromUser"});
-        behavior1.addParticpant(book);
-        const behavior2 = d.createBehavior({name: "AddBookToBasket"});
-        const behavior3 = d.createBehavior({name: "AnotherBehavior"});
-        d.graph.addNode(behavior1, [behavior2, behavior3]);
-        d.graph.addNode(behavior2, []);
-        d.graph.addNode(behavior3, []);
+
+        const node1 = d.addNode("AcceptBookFromUser", []);
+        d.addNode("AddBookToBasket", []);
+        d.addNode("AnotherBehavior", []);
+
+        node1.addGoToBehavior("AddBookToBasket");
+        node1.addGoToBehavior("AnotherBehavior");
+
+        node1.behavior.addParticpant(book);
 
         const filePath = resolve(__dirname, "./temp/inspectSerializeTemp.json")
         await writeFile(filePath, d.serialize())

package/tests/Invariant.test.js

@@ -3,8 +3,17 @@ import {resolve} from "path"
 import {describe, expect, it} from "vitest";
 
 import {DALEngine} from "../src/DALEngine.js";
+import MissingAttributes from "../src/Errors/MissingAttributes.js";
 
 describe("invariantTests", () => {
+
+    it("invariant throws on missing attributes", () => {
+        let d = new DALEngine({name: "Library Manager"});
+        expect(() => {d.createInvariant({"name": "asdf"})}).toThrow(MissingAttributes);
+        expect(() => {d.createInvariant({})}).toThrow(MissingAttributes);
+        expect(() => {d.createInvariant()}).toThrow(MissingAttributes);
+    });
+
     it("test invariant directly through participants", async () => {
         let d = new DALEngine({name: "Library Manager"});
 
@@ -63,28 +72,27 @@ describe("invariantTests", () => {
         ));
 
         // Create behavior and participant
-        const behavior1 = d.createBehavior({name: "AcceptBookFromUser"});
-        behavior1.addParticpant(book);
-        d.graph.addNode(behavior1, []);
+        const node1 = d.addNode("AcceptBookFromUser", []);
+        node1.behavior.addParticpant(book);
 
         // Add value that respects invariant and expect valid world state
-        behavior1.setParticipantValue("book", {
+        node1.behavior.setParticipantValue("book", {
             "uid": 1,
             "value": {
                 "name": "Harry Potter and Chamber of Secrets",
             },
         })
-        expect(behavior1.invalidWorldState).toBe(false);
+        expect(node1.behavior.invalidWorldState).toBe(false);
 
 
         // Add value that violates invariant and expect invalid world state
-        behavior1.setParticipantValue("book", {
+        node1.behavior.setParticipantValue("book", {
             "uid": 1,
             "value": {
                 "name": "",
             },
         })
-        expect(behavior1.invalidWorldState).toBe(true);
+        expect(node1.behavior.invalidWorldState).toBe(true);
 
         // Write to file for inspection
         const filePath = resolve(__dirname, "./temp/invariantBehaviorTemp.json")

package/tests/SimpleDesign.test.js

@@ -0,0 +1,31 @@
+import {readFile, unlink, writeFile} from "fs/promises"
+import {resolve} from "path"
+import {describe, expect, it} from "vitest";
+
+import {DALEngine} from "../src/DALEngine.js";
+
+describe("SimpleDesignTest", () => {
+
+    it("create simple design", async () => {
+        const d = new DALEngine({name: "Library Manager"});
+        d.addNode("AcceptChoiceToAddBookToBasket", ["AcceptBookFromUser"]);
+        d.addNode("AcceptBookFromUser", ["AddBookToBasket"]);
+        d.addNode("AddBookToBasket", []);
+        d.addNode("AcceptChoiceToAuditLibrary", ["GenerateAuditReport"]);
+        d.addNode("GenerateAuditReport", ["HandAuditToUser"]);
+        d.addNode("HandAuditToUser", []);
+
+        d.addNode("AcceptChoiceToPlaceBooksOnShelf", ["GetBookFromBasket"]);
+        d.addNode("GetBookFromBasket", ["GetFirstLetterOfBookName"]);
+        d.addNode("GetFirstLetterOfBookName", ["CreateSlotOnBookShelf", "AddBookToShelf"]);
+        d.addNode("CreateSlotOnBookShelf", ["AddBookToShelf"]);
+        d.addNode("AddBookToShelf", ["GetBookFromBasket"]);
+
+        const filePath = resolve(__dirname, "./simple_design_temp.json")
+        await writeFile(filePath, d.serialize())
+
+        // Output can be viewed using https://mermaid.live/
+        const filePath2 = resolve(__dirname, "./temp/simple_design_mermaid.txt")
+        await writeFile(filePath2, d.graph.exportAsMermaid())
+    });
+});

package/tests/simple_design_temp.json

@@ -0,0 +1 @@
+{"uid":"0f4433c4-abd7-43da-96e3-6809863c93ab","type":5,"nodes":[{"uid":"1b0751a9-c46e-4fa6-ae7f-cf6204fdd83b","type":6,"goToBehaviorsIds":["AcceptBookFromUser"],"behavior":{"uid":"e336a950-f89c-43a6-b3c4-09df32f64831","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"AcceptChoiceToAddBookToBasket"}},{"uid":"deb11624-0fae-4d1b-9d22-d421dea1d712","type":6,"goToBehaviorsIds":["AddBookToBasket"],"behavior":{"uid":"65b253bb-c4f2-4dee-8f36-648f73b3300c","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"AcceptBookFromUser"}},{"uid":"f914f2c9-86e3-4c54-a926-b6c9c425cf9f","type":6,"goToBehaviorsIds":[],"behavior":{"uid":"76b6962c-24b1-4999-9719-5ac2e4f1c022","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"AddBookToBasket"}},{"uid":"84912fd4-c193-4b7d-ad62-cdc6b254d529","type":6,"goToBehaviorsIds":["GenerateAuditReport"],"behavior":{"uid":"76f3d5a5-2e64-4bea-8beb-70d0d38e0645","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"AcceptChoiceToAuditLibrary"}},{"uid":"4056410c-37c5-4ffa-8766-2ecd7a079617","type":6,"goToBehaviorsIds":["HandAuditToUser"],"behavior":{"uid":"f6a6e7d4-0151-4881-8d57-fb327620fd4a","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"GenerateAuditReport"}},{"uid":"e6de6529-7d64-40f4-8787-c0e1c1c324eb","type":6,"goToBehaviorsIds":[],"behavior":{"uid":"8a3efec4-1068-4ee5-b66d-715bcc7b6d79","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"HandAuditToUser"}},{"uid":"91b71f6c-e384-4c31-9d39-4eae95e61872","type":6,"goToBehaviorsIds":["GetBookFromBasket"],"behavior":{"uid":"9caee137-24b9-4314-b5a7-e4a7f6e93256","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"AcceptChoiceToPlaceBooksOnShelf"}},{"uid":"4ea36149-15cf-4e6d-8770-cfd6bdc9645d","type":6,"goToBehaviorsIds":["GetFirstLetterOfBookName"],"behavior":{"uid":"1477b094-eb0a-4c2c-88b2-35ba99155f1e","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"GetBookFromBasket"}},{"uid":"bd6116de-8cd9-41b2-a256-fab5d979d80e","type":6,"goToBehaviorsIds":["CreateSlotOnBookShelf","AddBookToShelf"],"behavior":{"uid":"36b0483d-d831-4478-a34e-c091db38370d","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"GetFirstLetterOfBookName"}},{"uid":"54948771-65b7-40cb-8331-85f5b7d6cbf1","type":6,"goToBehaviorsIds":["AddBookToShelf"],"behavior":{"uid":"1fcd8aa4-6f25-4406-a0bc-ba43912ec572","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"CreateSlotOnBookShelf"}},{"uid":"ff292a3c-e556-44de-9a47-9510ef0910e4","type":6,"goToBehaviorsIds":["GetBookFromBasket"],"behavior":{"uid":"b736147d-faf3-4718-86c2-a2e8ffa8fb51","type":1,"participants":[],"abstractionIds":[],"invalidWorldState":false,"name":"AddBookToShelf"}}]}