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

package/dist/index.cjs

@@ -0,0 +1,486 @@
+'use strict';
+
+/**
+ * Base class for all objects in design.
+ */
+class Base {
+    /**
+     * Initialize the base class.
+     * @param {String} name
+     */
+    constructor () {
+        this.uid = crypto.randomUUID();
+    }
+
+    getType () {
+        return this.type;
+    }
+}
+
+class DALEngineError extends Error {
+    constructor (message) {
+        super(message);
+    }
+}
+
+class InvalidTransitionError extends DALEngineError {
+    constructor (from, to) {
+        super(`Invalid transition from "${from}" to "${to}"`);
+
+        this.name = "InvalidTransitionError";
+        this.prevBehavior = from;
+        this.nextBehavior = to;
+    }
+}
+
+class UnknownBehaviorError extends DALEngineError {
+    constructor (behaviorName) {
+        super(`The behavior named "${behaviorName}" was not found in graph.`);
+
+        this.name = "UnknownBehaviorError";
+        this.behaviorName = behaviorName;
+    }
+}
+
+let ENGINE_TYPES = {
+    BEHAVIOR: 1,
+    INVARIANT: 2,
+    PARTICIPANT: 3,
+    PRIMITIVE: 4,
+    BEHAVIORAL_CONTROL_GRAPH: 5,
+    GRAPH_NODE: 6,
+};
+ENGINE_TYPES = Object.freeze(ENGINE_TYPES);
+
+var ENGINE_TYPES$1 = ENGINE_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$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;
+            }
+        }
+    }
+
+    /**
+     * 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;
+        }
+    }
+}
+
+/**
+ * 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$1.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;
+    }
+}
+
+/**
+ * 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$1.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;
+                }
+            }
+        }
+    }
+}
+
+/**
+ * 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$1.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;
+    }
+}
+
+/**
+ * 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$1.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);
+        }
+    }
+}
+
+/**
+ * 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.
+ */
+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);
+    }
+}
+
+exports.DALEngine = DALEngine;