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

package/src/BehavioralControlGraph/BehavioralControlGraph.js

@@ -0,0 +1,111 @@
+import Base from "../Base";
+import InvalidTransitionError from "../Errors/InvalidTransitionError";
+import UnknownBehaviorError from "../Errors/UnknownBehaviorError";
+import ENGINE_TYPES from "../TYPES";
+import GraphNode from "./GraphNode";
+
+/**
+ * Class representing the behavioral control graph.
+ */
+class BehavioralControlGraph extends Base {
+    /**
+     * Initialize the behavioral control graph.
+     * @param {String} name
+     * @param args
+     */
+    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;
+            }
+        }
+    }
+
+    /**
+     * Loads the graph from a JSON object..
+     * @param {Object} graphJson
+     */
+    loadGraphFromJSON (graphJson) {
+        for (const [key, value] of Object.entries(graphJson)) {
+            if (key === "nodes") {
+                value.forEach(node => this.nodes.push(new GraphNode(node)));
+            } else {
+                this[key] = graphJson[key];
+            }
+        };
+    }
+
+    /**
+     * Adds a node to the graph.
+     * @param {Behavior} behavior
+     * @param {Array} goToBehaviors
+     * @returns
+     */
+    addNode (behavior, goToBehaviors) {
+        const node = new GraphNode({
+            behavior: behavior,
+            goToBehaviors: goToBehaviors,
+        });
+        this.nodes.push(node);
+        return node;
+    }
+
+
+    /**
+     * Finds the given node given the behavior name.
+     * @param {String} behaviorName
+     * @throws {UnknownBehaviorError} Raised when the provided behavior
+     * does not exist in the graph.
+     * @returns
+     */
+    findNode (behaviorName) {
+        for (let i = 0; i < this.nodes.length; i++) {
+            const behavior = this.nodes[i].behavior;
+            if (behavior.name === behaviorName) {
+                return this.nodes[i];
+            }
+        }
+        throw new UnknownBehaviorError(behaviorName);
+    }
+
+    /**
+     * 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);
+        /**
+         * TODO: Ensure it is atomic because the execution
+         * will only set a behavior when its the first one.
+         * It will walk using goToBehavior after that.
+         */
+        this.currentNode = node;
+    }
+
+    /**
+     * Check if the observed behavior is a valid transition
+     * given the current node.
+     * @param {String} nextBehaviorName
+     * @throws {InvalidTransitionError} Raised when the provided
+     * behavior is not a valid transition.
+     */
+    goToBehavior (nextBehaviorName) {
+        if (this.currentNode.isValidGoToBehavior(nextBehaviorName)) {
+            this.currentNode = this.findNode(nextBehaviorName);
+        } else {
+            throw new InvalidTransitionError(this.currentNode.behavior.name, nextBehaviorName);
+        }
+    }
+}
+
+export default BehavioralControlGraph;

package/src/BehavioralControlGraph/GraphNode.js

@@ -0,0 +1,62 @@
+import Base from "../Base";
+import Behavior from "../Members/Behavior";
+import ENGINE_TYPES from "../TYPES";
+/**
+ * Class representing a behavioral control graph node.
+ */
+class GraphNode extends Base {
+    /**
+     * Initialize the node.
+     * @param {String} name
+     * @param args
+     */
+    constructor (args) {
+        super();
+        this.type = ENGINE_TYPES.GRAPH_NODE;
+        this.goToBehaviors = [];
+        if (typeof args === "object" && args !== null) {
+            if (Object.hasOwn(args, "uid")) {
+                this.loadNodeFromJSON(args);
+            } else {
+                this.behavior = args.behavior;
+                this.goToBehaviors = args.goToBehaviors;
+            }
+        }
+    }
+
+    /**
+     * Loads the nodes from a JSON object.
+     * @param {Object} nodesJSON
+     */
+    loadNodeFromJSON (nodesJSON) {
+        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 {
+                this[key] = nodesJSON[key];
+            }
+        };
+    }
+
+    /**
+     * Checks if the provided behavior name is a valid
+     * behavior that the control flow selects as a
+     * result of the this nodes state transformation. i.e.
+     * is this behavior in the goToBehavior list.
+     * @param {String} behaviorName
+     * @returns {Boolean}
+     */
+    isValidGoToBehavior (behaviorName) {
+        for (let i = 0; i < this.goToBehaviors.length; i++) {
+            const behavior = this.goToBehaviors[i];
+            if (behavior.name === behaviorName) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+
+export default GraphNode;

package/src/DALEngine.js

@@ -0,0 +1,73 @@
+import BehavioralControlGraph from "./BehavioralControlGraph/BehavioralControlGraph";
+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.
+ *
+ * The execution of an program instrumented with the
+ * same design be used to step through the design
+ * while the engine automatically debugs the execution.
+ */
+export class DALEngine {
+    constructor (args) {
+        this.graph = new BehavioralControlGraph();
+        for (const [key, value] of Object.entries(args)) {
+            this[key] = value;
+        }
+    }
+
+    /**
+     * Exports the behavioral control graph to JSON text.
+     * @returns {String}
+     */
+    serialize () {
+        return JSON.stringify(this.graph);
+    }
+
+    /**
+     * Import the behavioral control graph from JSON text.
+     * @param {String} jsonText
+     */
+    deserialize (jsonText) {
+        this.graph = new BehavioralControlGraph();
+        this.graph.loadGraphFromJSON(JSON.parse(jsonText));
+    }
+
+    /**
+     * Creates a participant.
+     * @param {Object} args
+     * @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);
+    }
+
+    /**
+     * Creates a behavior.
+     * @param {Object} args
+     * @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);
+    }
+
+    /**
+     * Creates an invariant.
+     * @param {Object} args
+     * @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);
+    }
+}

package/src/Errors/DALEngineError.js

@@ -0,0 +1,7 @@
+class DALEngineError extends Error {
+    constructor (message) {
+        super(message);
+    }
+}
+
+export default DALEngineError;

package/src/Errors/InvalidTransitionError.js

@@ -0,0 +1,13 @@
+import DALEngineError from "./DALEngineError";
+
+class InvalidTransitionError extends DALEngineError {
+    constructor (from, to) {
+        super(`Invalid transition from "${from}" to "${to}"`);
+
+        this.name = "InvalidTransitionError";
+        this.prevBehavior = from;
+        this.nextBehavior = to;
+    }
+}
+
+export default InvalidTransitionError;

package/src/Errors/UnknownBehaviorError.js

@@ -0,0 +1,12 @@
+import DALEngineError from "./DALEngineError";
+
+class UnknownBehaviorError extends DALEngineError {
+    constructor (behaviorName) {
+        super(`The behavior named "${behaviorName}" was not found in graph.`);
+
+        this.name = "UnknownBehaviorError";
+        this.behaviorName = behaviorName;
+    }
+}
+
+export default UnknownBehaviorError;

package/src/Members/Behavior.js

@@ -0,0 +1,70 @@
+import Base from "../Base";
+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
+     */
+    constructor (args) {
+        super();
+        this.type = ENGINE_TYPES.BEHAVIOR;
+        this.participants = [];
+        this.invalidWorldState = false;
+        if (typeof args === "object" && args !== null) {
+            if (Object.hasOwn(args, "uid")) {
+                this.loadBehaviorFromJSON(args);
+            } else {
+                this.name = args.name;
+            }
+        }
+    }
+
+    /**
+     * Loads the behavior from a JSON object.
+     * @param {Object} behaviorJSON
+     */
+    loadBehaviorFromJSON (behaviorJSON) {
+        for (const [key, value] of Object.entries(behaviorJSON)) {
+            if (key === "participants") {
+                value.forEach(node => this.participants.push(new Participant(node)));
+            } else {
+                this[key] = behaviorJSON[key];
+            }
+        };
+    }
+
+    /**
+     * Adds a participant to the behavior.
+     * @param {Participant} participant
+     * @returns
+     */
+    addParticpant (participant) {
+        this.participants.push(participant);
+        return participant;
+    }
+
+    /**
+     * Set the participant value.
+     * @param {String} participantName
+     * @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;
+                }
+            }
+        }
+    }
+}
+
+export default Behavior;

package/src/Members/Invariant.js

@@ -0,0 +1,69 @@
+import Base from "../Base";
+import ENGINE_TYPES from "../TYPES";
+/**
+ * Class representing a Invariant in the design.
+ */
+class Invariant extends Base {
+    /**
+     * Initialize the Invariant.
+     * @param {String} name
+     * @param args
+     */
+    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;
+            }
+        }
+    }
+
+    /**
+     * Loads the participant from a JSON object.
+     * @param {Object} invariantJSON
+     */
+    loadInvariantFromJSON (invariantJSON) {
+        for (const [key, value] of Object.entries(invariantJSON)) {
+            this[key] = value;
+        };
+        // Reset these because they are set by the execution
+        this.invariantViolated = null;
+        this.value = null;
+    }
+
+    /**
+     * Evaluate the invariant.
+     * @param {*} value
+     * @returns {Boolean}
+     */
+    evaluate (value) {
+        this.invariantViolated = false;
+        if (this.rule.type === "minLength") {
+            this.enforceMinLength(value);
+        }
+        return this.invariantViolated;
+    }
+
+    /**
+     * Enforce the string min length invariant
+     * @param value
+     */
+    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;
+        }
+    }
+}
+
+export default Invariant;

package/src/Members/Participant.js

@@ -0,0 +1,76 @@
+import Base from "../Base";
+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
+     */
+    constructor (args) {
+        super();
+        this.type = ENGINE_TYPES.INVARIANT;
+        this.invariants = [];
+        this.invariantViolated = false;
+        if (typeof args === "object" && args !== null) {
+            if (Object.hasOwn(args, "uid")) {
+                this.loadParticipantFromJSON(args);
+            } else {
+                this.name = args.name;
+            }
+        }
+    }
+
+    /**
+     * Loads the participant from a JSON object.
+     * @param {Object} participantJSON
+     */
+    loadParticipantFromJSON (participantJSON) {
+        for (const [key, value] of Object.entries(participantJSON)) {
+            if (key === "invariants") {
+                value.forEach(node => this.invariants.push(new Invariant(node)));
+            } else {
+                this[key] = participantJSON[key];
+            }
+        };
+    }
+
+    /**
+     * Adds an invariant to the participant.
+     * @param {Invariant} invariant
+     * @returns
+     */
+    addInvariant (invariant) {
+        this.invariants.push(invariant);
+        return invariant;
+    }
+
+    /**
+     * Sets the value of the participant.
+     * @param {*} value
+     */
+    setValue (value) {
+        this.value = value;
+    }
+
+    /**
+     * Enforces the particiants invariants.
+     * @returns {Boolean}
+     */
+    enforceInvariants () {
+        this.invariantViolated = false
+        this.invariantViolationCount = 0;
+        for (let i = 0; i < this.invariants.length; i++) {
+            if (this.invariants[i].evaluate(this.value)) {
+                this.invariantViolated = true;
+                this.invariantViolationCount++;
+            }
+        }
+        return this.invariantViolated;
+    }
+}
+
+export default Participant;

package/src/TYPES.js

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

package/tests/DALEngine.test.js

@@ -0,0 +1,130 @@
+import {readFile, unlink, writeFile} from "fs/promises"
+import {resolve} from "path"
+import {describe, expect, it} from "vitest";
+
+import {DALEngine} from "../src/DALEngine.js";
+import InvalidTransitionError from "../src/Errors/InvalidTransitionError.js";
+import UnknownBehaviorError from "../src/Errors/UnknownBehaviorError.js";
+import ENGINE_TYPES from "../src/TYPES.js";
+
+describe("DALEngine", () => {
+    it("sets the name correctly", () => {
+        const dalInstance = new DALEngine({name: "Library Manager"});
+        expect(dalInstance.name).toBe("Library Manager");
+    });
+
+    it("adds node to graph", () => {
+        const d = new DALEngine({name: "Library Manager"});
+        const behavior1 = d.createBehavior({name: "AcceptBookFromUser"});
+        const behavior2 = d.createBehavior({name: "AddBookToBasket"});
+        const goToBehaviors = [behavior2];
+
+        const node = d.graph.addNode(behavior1, goToBehaviors)
+
+        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);
+    });
+
+    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 foundNode = d.graph.findNode("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, [])
+
+        // Misspell behavior name to trigger unknown behavior error
+        expect(() => {
+            d.graph.setCurrentBehavior("AcceptBookromUser");
+        }).toThrow(UnknownBehaviorError);
+
+        d.graph.setCurrentBehavior("AcceptBookFromUser");
+        expect(d.graph.currentNode.behavior).toBe(behavior1);
+
+        d.graph.goToBehavior("AddBookToBasket")
+        expect(d.graph.currentNode.behavior).toBe(behavior2);
+
+        // Reset current behavior so transition is valid
+        d.graph.setCurrentBehavior("AcceptBookFromUser");
+        d.graph.goToBehavior("AnotherBehavior")
+        expect(d.graph.currentNode.behavior).toBe(behavior3);
+
+        // Raises error because current behavior is "AnotherBehavior"
+        // and it does not transition to itself.
+        expect(() => {
+            d.graph.goToBehavior("AnotherBehavior")
+        }).toThrow(InvalidTransitionError);
+
+        // Reset the current behavior and then go to a behavior
+        // which is misspelled and expect an invalid transition error
+        expect(() => {
+            d.graph.setCurrentBehavior("AcceptBookFromUser");
+            d.graph.goToBehavior("AddBookToasket")
+        }).toThrow(InvalidTransitionError);
+    });
+
+    it("add invariant to participant", () => {
+        const d = new DALEngine({name: "Library Manager"});
+        const book = d.createParticipant({name: "book"});
+        const invariant = d.createInvariant({name: "minLength"});
+
+        book.addInvariant(invariant);
+
+        const lastInvariant = book.invariants[book.invariants.length - 1];
+        expect(lastInvariant).toBe(invariant);
+    });
+
+    it("serialize to file and deseralize from file", async () => {
+        let d = new DALEngine({name: "Library Manager"});
+        const book = d.createParticipant({name: "book"});
+        const invariant = d.createInvariant(
+            {
+                "name": "MinLengthConstraint",
+                "rule": {
+                    "type": "minLength",
+                    "keys": ["value", "name"],
+                    "value": 1,
+                },
+            }
+        );
+        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 filePath = resolve(__dirname, "./temp/inspectSerializeTemp.json")
+        await writeFile(filePath, d.serialize())
+
+        d = new DALEngine({name: "Library Manager"});
+        d.deserialize(await readFile(filePath, "utf-8"));
+        expect(d.graph.nodes.length).toBe(3);
+
+        // Intentionally not cleaning up the file because I want to inspect
+        // await unlink(filePath)
+
+        // This is a temporary file I create for my own inspection
+        const filePath2 = resolve(__dirname, "./temp/inspectDeseralizeTemp.json")
+        await writeFile(filePath2, d.serialize())
+    });
+});