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

package/dist/index.esm.js

@@ -0,0 +1,484 @@
+/**
+ * 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$1 = {
+    BEHAVIOR: 1,
+    INVARIANT: 2,
+    PARTICIPANT: 3,
+    PRIMITIVE: 4,
+    BEHAVIORAL_CONTROL_GRAPH: 5,
+    GRAPH_NODE: 6,
+};
+ENGINE_TYPES$1 = Object.freeze(ENGINE_TYPES$1);
+
+var ENGINE_TYPES = ENGINE_TYPES$1;
+
+/**
+ * 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;
+        }
+    }
+}
+
+/**
+ * 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;
+    }
+}
+
+/**
+ * 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;
+                }
+            }
+        }
+    }
+}
+
+/**
+ * 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;
+    }
+}
+
+/**
+ * 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);
+        }
+    }
+}
+
+/**
+ * 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);
+    }
+}
+
+export { DALEngine };

package/eslint.config.js

@@ -0,0 +1,83 @@
+// eslint.config.js
+import jsdoc from "eslint-plugin-jsdoc";
+import simpleImportSort from "eslint-plugin-simple-import-sort";
+import globals from "globals";
+
+export default [
+    {
+        files: ["**/*.js"],
+        languageOptions: {
+            ecmaVersion: "latest",
+            sourceType: "module",
+            globals: {
+                ...globals.browser,
+                ...globals.es2021,
+            },
+        },
+
+        plugins: {
+            "simple-import-sort": simpleImportSort,
+            jsdoc,
+        },
+
+        rules: {
+            "brace-style": ["warn", "1tbs", {allowSingleLine: true}],
+            "comma-dangle": [
+                "warn",
+                {
+                    arrays: "always-multiline",
+                    objects: "always-multiline",
+                    imports: "never",
+                    exports: "never",
+                    functions: "never",
+                },
+            ],
+            "comma-spacing": "warn",
+            "eol-last": "warn",
+            indent: ["warn", 4, {SwitchCase: 1}],
+            "key-spacing": "warn",
+            "keyword-spacing": "warn",
+            "max-len": [
+                "warn",
+                {
+                    code: 100,
+                    comments: 80,
+                    ignoreComments: false,
+                    ignoreTrailingComments: false,
+                },
+            ],
+            "no-multi-spaces": "warn",
+            "no-multiple-empty-lines": "warn",
+            "no-trailing-spaces": "warn",
+            "no-unused-vars": "warn",
+            "object-curly-spacing": "warn",
+            "operator-linebreak": "off",
+            "padded-blocks": "off",
+            quotes: ["warn", "double", {avoidEscape: true}],
+            "semi-spacing": "warn",
+
+            // simple-import-sort
+            "simple-import-sort/exports": "warn",
+            "simple-import-sort/imports": [
+                "warn",
+                {
+                    groups: [
+                        [
+                            "^@?\\w",
+                            "^(@|@company|@ui|components|utils|config|vendored-lib)(/.*|$)",
+                        ],
+                        ["^\\.\\.(?!/?$)", "^\\.(?!/?$)"],
+                        ["^\\u0000"],
+                    ],
+                },
+            ],
+
+            "space-before-blocks": "warn",
+            "space-before-function-paren": ["warn", "always"],
+            "spaced-comment": "warn",
+            "jsdoc/require-jsdoc": "warn",
+            "jsdoc/require-param": "warn",
+            "jsdoc/require-returns": "warn",
+        },
+    },
+];

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "dal-engine-core-js-lib-dev",
+  "version": "0.0.0",
+  "main": "dist/index.cjs",
+  "module": "dist/index.esm.js",
+  "type": "module",
+  "scripts": {
+    "build": "rollup -c",
+    "dev": "rollup -c -w",
+    "test": "vitest",
+    "test:watch": "vitest --watch",
+    "test:run": "vitest run",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vishalpalaniappan/dal-engine-core-js.git"
+  },
+  "author": "Vishal Palaniappan",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/vishalpalaniappan/dal-engine-core-js/issues"
+  },
+  "homepage": "https://github.com/vishalpalaniappan/dal-engine-core-js",
+  "devDependencies": {
+    "@rollup/plugin-node-resolve": "^16.0.3",
+    "eslint": "^9.39.3",
+    "eslint-plugin-jsdoc": "^61.7.1",
+    "eslint-plugin-simple-import-sort": "^10.0.0",
+    "eslint-plugin-vitest": "^0.5.4",
+    "rollup": "^4.57.1",
+    "vitest": "^4.0.18"
+  }
+}

package/rollup.config.js

@@ -0,0 +1,16 @@
+import resolve from "@rollup/plugin-node-resolve";
+
+export default {
+    input: "src/DALEngine.js",
+    output: [
+        {
+            file: "dist/index.cjs",
+            format: "cjs",
+        },
+        {
+            file: "dist/index.esm.js",
+            format: "esm",
+        },
+    ],
+    plugins: [resolve()],
+};

package/src/Base.js

@@ -0,0 +1,18 @@
+/**
+ * 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;
+    }
+}
+
+export default Base;