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

package/src/Members/Participant.js

@@ -1,16 +1,20 @@
 import Base from "../Base";
 import MissingAttributes from "../Errors/MissingAttributes";
+import isLoadedFromFile from "../helpers/isLoadedFromFile";
 import ENGINE_TYPES from "../TYPES";
 import Invariant from "./Invariant";
 
-/**
- * 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();
@@ -18,11 +22,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));
     }
 
     /**
@@ -46,9 +46,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)));
@@ -60,8 +60,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);
@@ -69,16 +69,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
@@ -98,9 +100,15 @@ 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;
     }
 }

package/src/TYPES.js

@@ -2,9 +2,8 @@ let ENGINE_TYPES = {
     BEHAVIOR: 1,
     INVARIANT: 2,
     PARTICIPANT: 3,
-    PRIMITIVE: 4,
-    BEHAVIORAL_CONTROL_GRAPH: 5,
-    GRAPH_NODE: 6,
+    BEHAVIORAL_CONTROL_GRAPH: 4,
+    GRAPH_NODE: 5,
 };
 ENGINE_TYPES = Object.freeze(ENGINE_TYPES);
 

package/src/helpers/isLoadedFromFile.js

@@ -0,0 +1,15 @@
+/**
+ * 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");
+};
+
+export default isLoadedFromFile;

package/tests/DALEngine.test.js

@@ -1,10 +1,13 @@
+// eslint-disable-next-line no-unused-vars
 import {readFile, unlink, writeFile} from "fs/promises"
 import {resolve} from "path"
 import {describe, expect, it} from "vitest";
 
 import {DALEngine} from "../src/DALEngine.js";
+import BehaviorAlreadyExistsError from "../src/Errors/BehaviorAlreadyExistsError.js";
 import InvalidTransitionError from "../src/Errors/InvalidTransitionError.js";
 import MissingAttributes from "../src/Errors/MissingAttributes.js";
+import TransitionAlreadyExistsError from "../src/Errors/TransitionAlreadyExistsError.js";
 import UnknownBehaviorError from "../src/Errors/UnknownBehaviorError.js";
 import ENGINE_TYPES from "../src/TYPES.js";
 
@@ -36,6 +39,12 @@ describe("DALEngine", () => {
         expect(node.getGoToBehaviors()).toStrictEqual(goToBehaviorIds);
     });
 
+    it("throws when a behavior with same name is added to graph", () => {
+        const d = new DALEngine({name: "Library Manager"});
+        d.addNode("AcceptBookFromUser", []);
+        expect(() => {d.addNode("AcceptBookFromUser", [])}).toThrow(BehaviorAlreadyExistsError);
+    });
+
     it("find node that was added using behavior name", () => {
         const d = new DALEngine({name: "Library Manager"});
         const node = d.addNode("AcceptBookFromUser", []);
@@ -120,6 +129,16 @@ describe("DALEngine", () => {
         expect(lastInvariant).toBe(invariant);
     });
 
+    it ("add duplicate transition and check error is raised", () => {
+        const d = new DALEngine({name: "Library Manager"});
+        const node1 = d.addNode("AcceptBookFromUser", []);
+        const node2 = d.addNode("AddBookToBasket", []);
+        node1.addGoToBehavior("AddBookToBasket");
+        expect(() => {
+            node1.addGoToBehavior("AddBookToBasket");
+        }).toThrow(TransitionAlreadyExistsError);
+    });
+
     it("serialize to file and deseralize from file", async () => {
         let d = new DALEngine({name: "Library Manager"});
         const book = d.createParticipant({name: "book"});

package/tests/Graphs.test.js

@@ -0,0 +1,80 @@
+// eslint-disable-next-line no-unused-vars
+import {readFile, unlink, writeFile} from "fs/promises"
+import {resolve} from "path"
+import {describe, expect, it} from "vitest";
+
+import {DALEngine} from "../src/DALEngine.js";
+import GraphWithNameExistsError from "../src/Errors/GraphWithNameExistsError";
+
+describe("multiple graphs test", () => {
+
+    it("create multiple graphs and switch", async () => {
+        const d = new DALEngine({name: "Library Manager"});
+        d.createGraph("graph 1");
+        d.addNode("graph1behavior", []);
+
+        d.createGraph("graph 2");
+        d.addNode("graph2behavior", []);
+
+        d.selectGraph("graph 1");
+        expect(d.getNode("graph1behavior")).toBeTruthy();
+        expect(() => d.getNode("graph2behavior")).toThrow();
+        await writeFile(resolve(__dirname, "./temp/graph1.json"), d.serialize())
+
+        d.selectGraph("graph 2");
+        expect(d.getNode("graph2behavior")).toBeTruthy();
+        expect(() => d.getNode("graph1behavior")).toThrow();
+        await writeFile(resolve(__dirname, "./temp/graph2.json"), d.serialize())
+    });
+
+
+    it("get list of graphs", async () => {
+        const d = new DALEngine({name: "Library Manager"});
+        d.createGraph("graph 1");
+        d.addNode("graph1behavior", []);
+
+        d.createGraph("graph 2");
+        d.addNode("graph2behavior", []);
+
+        expect(d.getSelectableGraphs()).toEqual(["default graph", "graph 1", "graph 2"]);
+
+        d.selectGraph("graph 1");
+        expect(d.getNode("graph1behavior")).toBeTruthy();
+        expect(() => d.getNode("graph2behavior")).toThrow();
+    });
+
+    it("create graph with existing name", async () => {
+        const d = new DALEngine({name: "Library Manager"});
+        d.createGraph("graph 1");
+        expect(() => d.createGraph("graph 1")).toThrow(GraphWithNameExistsError);
+    });
+
+    it("test that graph is removed", async () => {
+        const d = new DALEngine({name: "Library Manager"});
+        d.createGraph("graph 1");
+        d.addNode("graph1behavior", []);
+        d.createGraph("graph 2");
+        d.addNode("graph2behavior", []);
+        expect(d.getSelectableGraphs()).toEqual(["default graph", "graph 1", "graph 2"]);
+        d.removeGraph("graph 1");
+
+        // After removing a graph, the first graph in the list is active.
+        // If there are no graphs, a default graph is created and set as active.
+        expect(d.getSelectableGraphs()).toEqual(["default graph", "graph 2"]);
+        expect(d.graph.name).toBe("default graph");
+    });
+
+    it("serialize and deserialize", async () => {
+        const d = new DALEngine({name: "Library Manager"});
+        d.createGraph("graph 1");
+        d.addNode("graph1behavior", []);
+
+        d.createGraph("graph 2");
+        d.addNode("graph2behavior", []);
+
+        await writeFile(resolve(__dirname, "./temp/graphs.json"), d.serialize());
+
+        d.deserialize(await readFile(resolve(__dirname, "./temp/graphs.json"), "utf-8"));
+        expect(d.getSelectableGraphs()).toEqual(["default graph", "graph 1", "graph 2"]);
+    });
+});

package/tests/Invariant.test.js

@@ -1,3 +1,4 @@
+// eslint-disable-next-line no-unused-vars
 import {readFile, unlink, writeFile} from "fs/promises"
 import {resolve} from "path"
 import {describe, expect, it} from "vitest";