core/Concept.js

  1. /**
  2.  *  Concept - The central part of the Varv language
  3.  * 
  4.  *  This code is licensed under the MIT License (MIT).
  5.  *  
  6.  *  Copyright 2020, 2021, 2022 Rolf Bagge, Janus B. Kristensen, CAVI,
  7.  *  Center for Advanced Visualization and Interaction, Aarhus University
  8.  *  
  9.  *  Permission is hereby granted, free of charge, to any person obtaining a copy
  10.  *  of this software and associated documentation files (the “Software”), to deal
  11.  *  in the Software without restriction, including without limitation the rights 
  12.  *  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
  13.  *  copies of the Software, and to permit persons to whom the Software is 
  14.  *  furnished to do so, subject to the following conditions:
  15.  *  
  16.  *  The above copyright notice and this permission notice shall be included in 
  17.  *  all copies or substantial portions of the Software.
  18.  *  
  19.  *  THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
  20.  *  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
  21.  *  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
  22.  *  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
  23.  *  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
  24.  *  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 
  25.  *  THE SOFTWARE.
  26.  *  
  27.  */
  29. /**
  30.  *
  31.  */
  32. class Concept {
  33.     constructor(name) {
  34.         this.name = name;
  35.         this.properties = new Map();
  36.         this.actions = new Map();
  37.         this.behaviours = new Map();
  38.         this.triggers = new Map();
  39.         this.mappings = new Map();
  41.         this.otherConcepts = new Set();
  42.         this.appearedCallbacks = [];
  43.         this.disappearedCallbacks = [];
  44.     }
  46.     addTrigger(trigger, removeOld=false) {
  47.         if(removeOld) {
  48.             let oldTrigger = this.triggers.get(trigger.name);
  50.             if (oldTrigger != null) {
  51.                 if (Concept.DEBUG) {
  52.                     console.log("Overwriting trigger:", oldTrigger, trigger);
  53.                 }
  55.                 this.removeTrigger(oldTrigger);
  56.             }
  57.         }
  59.         this.triggers.set(trigger.name, trigger);
  60.     }
  62.     removeTrigger(trigger) {
  63.         this.triggers.delete(trigger.name);
  64.         trigger.disable(this);
  65.     }
  67.     getTrigger(name) {
  68.         return this.triggers.get(name);
  69.     }
  71.     addBehaviour(behaviour, removeOld=false) {
  72.         if(removeOld) {
  73.             let oldBehaviour = this.behaviours.get(behaviour.name);
  75.             if (oldBehaviour != null) {
  76.                 if (Concept.DEBUG) {
  77.                     console.log("Overwriting behaviour:", oldBehaviour, behaviour);
  78.                 }
  80.                 this.removeBehaviour(oldBehaviour);
  81.             }
  82.         }
  84.         this.behaviours.set(behaviour.name, behaviour);
  86.         if(behaviour.callableAction) {
  87.             this.addAction(behaviour.actionChain);
  88.         }
  89.     }
  91.     removeBehaviour(behaviour) {
  92.         this.removeAction(behaviour.actionChain);
  93.         this.behaviours.delete(behaviour.name);
  94.         behaviour.destroy();
  95.     }
  97.     getBehaviour(name) {
  98.         return this.behaviours.get(name);
  99.     }
  101.     addAction(action, removeOld=false) {
  102.         if(removeOld) {
  103.             let oldAction = this.actions.get(action.name);
  105.             if (oldAction != null) {
  106.                 if (Concept.DEBUG) {
  107.                     console.log("Overwriting action:", oldAction, action);
  108.                 }
  110.                 this.removeAction(oldAction);
  111.             }
  112.         }
  114.         this.actions.set(action.name, action);
  115.     }
  117.     removeAction(action) {
  118.         this.actions.delete(action.name);
  119.     }
  121.     getAction(name) {
  122.         return this.actions.get(name);
  123.     }
  125.     addProperty(property, removeOld=false) {
  126.         if(removeOld) {
  127.             let oldProperty = this.properties.get(property.name);
  129.             if (oldProperty != null) {
  130.                 if (Concept.DEBUG) {
  131.                     console.log("Overwriting property:", oldProperty, property);
  132.                 }
  134.                 this.removeProperty(oldProperty);
  135.             }
  136.         }
  138.         this.properties.set(property.name, property);
  139.     }
  141.     removeProperty(property) {
  142.         this.unmapProperty(property);
  143.         this.properties.delete(property.name);
  144.     }
  146.     getProperty(name) {
  147.         const self = this;
  149.         let markStart = VarvPerformance.start();
  151.         let property = null;
  153.         if(name === "uuid") {
  154.             property = {
  155.                 name: "uuid",
  156.                 type: "string",
  157.                 addUpdatedCallback: () => {},
  158.                 removeUpdatedCallback: () => {},
  159.                 isConceptType: () => false,
  160.                 isConceptArrayType: () => false,
  161.                 getValue: (uuid) => {
  162.                     return uuid;
  163.                 }
  164.             };
  165.         } else if(name === "concept::uuid") {
  166.             property = {
  167.                 name: "uuid",
  168.                 type: "string",
  169.                 addUpdatedCallback: ()=>{},
  170.                 removeUpdatedCallback: ()=>{},
  171.                 isConceptType: () => false,
  172.                 isConceptArrayType: () => false,
  173.                 getValue: (uuid) => {
  174.                     return uuid;
  175.                 }
  176.             };
  177.         } else if(name === "concept::name") {
  178.             property = {
  179.                 name: "name",
  180.                 type: "string",
  181.                 addUpdatedCallback: ()=>{},
  182.                 removeUpdatedCallback: ()=>{},
  183.                 isConceptType: () => false,
  184.                 isConceptArrayType: () => false,
  185.                 getValue: (uuid) => {
  186.                     return self.name;
  187.                 }
  188.             };
  189.         } else {
  190.             property = this.properties.get(name);
  191.         }
  193.         if(property != null) {
  194.             VarvPerformance.stop("Concept.getProperty", markStart);
  195.             return property;
  196.         } else {
  197.             VarvPerformance.stop("Concept.getProperty.error", markStart);
  198.             throw new Error("No property ["+name+"] on ["+this.name+"]");
  199.         }
  200.     }
  202.     async setPropertyValue(uuid, name, value, skipStateChangeTrigger=false) {
  203.         await this.getProperty(name).setValue(uuid, value, skipStateChangeTrigger);
  204.     }
  206.     getPropertyValue(uuid, name) {
  207.         return this.getProperty(name).getValue(uuid);
  208.     }
  210.     setupTriggers(debug) {
  211.         const self = this;
  213.         if(debug) {
  214.             console.groupCollapsed("Setting up triggers on concept [" + this.name + "]");
  215.         }
  217.         for(let trigger of this.triggers.values()) {
  218.             if(debug) {
  219.                 console.log("Enabling trigger:", trigger);
  220.             }
  221.             trigger.enable(this);
  222.         }
  224.         //We should listen for deleted concepts, and update our property when any we have are deleted...
  225.         this.deletedTriggerDeleter = Trigger.registerTriggerEvent("deleted", async (contexts)=>{
  226.             for(let context of contexts) {
  227.                 if(context.target != null) {
  228.                     let concept = await VarvEngine.getConceptFromUUID(context.target);
  229.                     if(concept != null) {
  230.                         //A concept was deleted, check if we have any properties with the given concept
  231.                         for(let property of self.properties.values()) {
  232.                             if(property.holdsConceptOfType(concept)) {
  233.                                 await property.removeAllReferences(self.name, context.target);
  234.                             }
  235.                         }
  236.                     }
  237.                 }
  238.             }
  239.         });
  241.         if(debug) {
  242.             console.groupEnd();
  243.         }
  244.     }
  246.     destroyTriggers() {
  247.         for(let trigger of this.triggers.values()) {
  248.             if(Concept.DEBUG) {
  249.                 console.log("Disabling trigger:", trigger);
  250.             }
  251.             trigger.disable(this);
  252.         }
  254.         this.deletedTriggerDeleter.delete();
  255.     }
  257.     async create(wantedUUID=null, properties=null){
  258.         let mark = VarvPerformance.start();
  259.         if(wantedUUID == null) {
  260.             let uuidMark = VarvPerformance.start();
  261.             wantedUUID = UUIDGenerator.generateUUID("concept");
  262.             VarvPerformance.stop("Concept.create.generateUUID", uuidMark);
  263.         } else {
  265.             // TODO is this correct?
  267.             let oldConcept = await VarvEngine.getConceptFromUUID(wantedUUID);
  269.             //If already present, just return as if it has been created?
  270.             if(oldConcept != null) {
  271.                 if(oldConcept !== this) {
  272.                     throw new Error("Trying to create ["+wantedUUID+"] as ["+this.name+"] but it is already registered as a ["+oldConcept.name+"]");
  273.                 }
  275.                 throw new Error("Trying to create ["+wantedUUID+"] that already existed, as the same concept type..");
  276.             }
  277.         }       
  279.         await VarvEngine.registerConceptFromUUID(wantedUUID, this);
  280.         await this.appeared(wantedUUID, true);
  282.         if (properties != null) {
  283.             for (let key of Object.keys(properties)) {
  284.                 let value = properties[key];
  286.                 await this.setPropertyValue(wantedUUID, key, value, false);
  287.             }
  288.         } else {
  289.             //Now trigger stateChanged for all properties
  290.             for(let [key, prop] of this.properties) {
  291.                 let value = prop.getDefaultValue();
  292.                 await prop.stateChanged(wantedUUID, value);
  293.             }
  294.         }
  296.         await this.created(wantedUUID);
  298.         for (let callback of this.appearedCallbacks) {
  299.             await callback(wantedUUID, this);
  300.         }
  302.         VarvPerformance.stop("Concept.create", mark);
  304.         return wantedUUID;
  305.     }
  306.     
  307.     /**
  308.      * Clones the given UUID into a new one
  309.      * @param {type} sourceUUID
  310.      * @returns {@var;wantedUUID}
  311.      */
  312.     async clone(sourceUUID, deep=false, alreadyClonedReferences={}){
  313.         let clonedProperties = {};
  314.         for (const [propertyName, property] of this.properties){
  315.             clonedProperties[propertyName] = await property.getValue(sourceUUID);
  316.             
  317.             if (deep){
  318.                 async function cloneUUID(propertyConcept, uuid){
  319.                     let propertyActualConcept = await VarvEngine.getConceptFromUUID(uuid);
  320.                     if (!propertyActualConcept) {
  321.                         console.warn("Invalid reference to UUID '"+uuid+"' while deep-cloning property "+propertyName+" on "+propertyConcept.name+", the property was left as is (invalid)");
  322.                         return uuid;
  323.                     }
  324.                     if (uuid===sourceUUID) throw new Error("Currently no support for deep cloning of concept instances with properties that contain direct self-references");
  325.                     // TODO: cycles too
  326.                     
  327.                     // Check if we already cloned it, if not do so
  328.                     if (alreadyClonedReferences[uuid]){
  329.                         return alreadyClonedReferences[uuid];                        
  330.                     } else {
  331.                         let theClone = await propertyConcept.clone(uuid, true);
  332.                         alreadyClonedReferences[uuid] = theClone;
  333.                         return theClone;
  334.                     }
  335.                 }
  336.                 
  337.                 // Referenced Concepts and Concept reference lists should also be cloned
  338.                 if (property.isConceptType()){
  339.                     let propertyConcept = await VarvEngine.getConceptFromType(property.getType());   
  340.                     clonedProperties[propertyName] = await cloneUUID(propertyConcept, clonedProperties[propertyName]);
  341.                 }
  342.                 if (property.isConceptArrayType()){
  343.                     let propertyConcept = await VarvEngine.getConceptFromType(property.getArrayType());      
  344.                     let newPropertyValue = [];
  345.                     for(let i = 0; i < clonedProperties[propertyName].length; i++) {
  346.                         newPropertyValue.push(await cloneUUID(propertyConcept, clonedProperties[propertyName][i]));
  347.                     }
  348.                     clonedProperties[propertyName] = newPropertyValue;
  349.                 }
  350.             };
  351.         }        
  353.         return this.create(null, clonedProperties);
  354.     }
  356.     finishSetup(debug) {
  357.         if(debug) {
  358.             console.groupCollapsed("Finishing concept:", this.name);
  359.         }
  360.         //this.finishProperties(debug);
  361.         this.finishBehaviours(debug);
  362.         this.setupTriggers(debug);
  363.         if(debug) {
  364.             console.groupEnd();
  365.         }
  366.     }
  368.     doAfterSpecLoadSetup(debug) {
  369.         let mark = VarvPerformance.start();
  370.         this.finishProperties(debug);
  371.         VarvPerformance.stop("Concept.doAfterSpecLoadSetup", mark, this.name);
  372.     }
  374.     finishProperties(debug) {
  375.         let self = this;
  377.         if(debug) {
  378.             console.group("Properties:");
  379.         }
  381.         this.properties.forEach((property)=>{
  382.             if(debug) {
  383.                 console.log(property)
  384.             }
  385.             property.finishSetup(self);
  386.         });
  388.         if(debug) {
  389.             console.groupEnd();
  390.         }
  391.     }
  394.     finishBehaviours(debug) {
  395.         if(debug) {
  396.             console.group("Behaviours:");
  397.         }
  398.         this.behaviours.forEach((behaviour, key)=>{
  399.             if(debug) {
  400.                 console.log(behaviour);
  401.             }
  402.             behaviour.setupEvents();
  403.         });
  404.         if(debug) {
  405.             console.groupEnd();
  406.         }
  407.     }
  409.     omit(omitConfig) {
  410.         let self = this;
  412.         if(omitConfig.schema != null) {
  413.             if(!Array.isArray(omitConfig.schema)) {
  414.                 omitConfig.schema = [omitConfig.schema];
  415.             }
  416.             omitConfig.schema.forEach((propertyName)=>{
  417.                 let property = self.getProperty(propertyName);
  418.                 if(property != null) {
  419.                     self.removeProperty(property);
  420.                 }
  421.             });
  422.         }
  424.         if(omitConfig.actions != null) {
  425.             if(!Array.isArray(omitConfig.actions)) {
  426.                 omitConfig.actions = [omitConfig.actions];
  427.             }
  429.             omitConfig.actions.forEach((actionName)=>{
  430.                 let behaviour = self.getBehaviour(actionName);
  431.                 if(behaviour != null) {
  432.                     self.removeBehaviour(behaviour);
  433.                 }
  435.                 let action = self.getAction(actionName);
  436.                 if(action != null) {
  437.                     self.removeAction(action);
  438.                 }
  439.             });
  440.         }
  441.     }
  443.     /**
  444.      * Import the otherConcept into this one. This concept will be the combination of both concepts but retains its name.
  445.      * In case of clashes the otherConcept will override existing entries in this concept.
  446.      * 
  447.      * @param {Concept} otherConcept Other concept to import into this one
  448.      */
  449.     join(otherConcept){
  450.         if(this === otherConcept) {
  451.             console.warn("Attempting to join concept to itself!");
  452.             return;
  453.         }
  455.         if(Concept.DEBUG) {
  456.             console.group("Joining:", otherConcept.name, " into ", this.name);
  457.         }
  459.         const self = this;
  461.         otherConcept.properties.forEach((property)=>{
  462.             self.addProperty(property.cloneFresh(self), true);
  463.         });
  465.         for (let [propertyName, mappings] of otherConcept.mappings){
  466.             this.mapProperty(this.getProperty(propertyName), mappings);
  467.         }
  469.         otherConcept.behaviours.forEach((behaviour)=>{
  470.             self.addBehaviour(behaviour.cloneFresh(self), true);
  471.         });
  473.         this.otherConcepts.add(otherConcept.name);
  474.         otherConcept.otherConcepts.forEach((otherConceptType)=>{
  475.             self.otherConcepts.add(otherConceptType);
  476.         })
  478.         if(Concept.DEBUG) {
  479.             console.groupEnd();
  480.         }
  481.     }
  483.     unmapProperty(property) {
  484.         this.mappings.get(property.name).forEach((datastoreName)=>{
  485.             let datastore = Datastore.getDatastoreFromName(datastoreName);
  486.             if(datastore != null) {
  487.                 datastore.removeBackingStore(this, property);
  488.             } else {
  489.                 // TODO: Throw an error here?, We might just be unmapping from a join before datastores are even a thing...
  490.             }
  491.         });
  492.         this.mappings.delete(property.name);
  493.     }
  495.     mapProperty(property, propertyMappings){
  496.         this.mappings.set(property.name, propertyMappings);
  497.     }
  499.     enableMappings(debug = false) {
  500.         const self = this;
  501.         this.mappings.forEach((propertyMappings, propertyName)=>{
  502.             let property = self.getProperty(propertyName);
  504.             if(debug) {
  505.                 console.log(propertyName, propertyMappings);
  506.             }
  508.             let sharedDataStores = [];
  510.             propertyMappings.forEach((datastoreName)=>{
  511.                 let datastore = Datastore.getDatastoreFromName(datastoreName);
  513.                 if(datastore != null) {
  514.                     if(datastore.isShared()) {
  515.                         sharedDataStores.push(datastoreName);
  516.                     }
  518.                     datastore.createBackingStore(this, property);
  519.                 } else {
  520.                     if (!Datastore.optionalDatastores.includes(datastoreName)) console.warn("["+self.name+"] is attempting to map ["+propertyName+"] to a non existing datastore ["+datastoreName+"]");
  521.                 }
  522.             });
  524.             if(sharedDataStores.length > 1) {
  525.                 console.log("%c Property "+self.name+"."+propertyName+" is mapped to multiple shared datastores ["+sharedDataStores+"], this can create race conditions in multi user use cases.", "background: yellow; color: red;");
  526.             }
  527.         });
  528.     }
  530.     async delete(uuid){
  531.         // Trigger deleted() trigger with target set to uuid
  532.         await this.deleted(uuid);
  534.         await this.disappeared(uuid);
  535.     }
  537.     addAppearedCallback(callback) {
  538.         this.appearedCallbacks.push(callback);
  539.     }
  541.     addDisappearedCallback(callback) {
  542.         this.disappearedCallbacks.push(callback);
  543.     }
  545.     async deleted(uuid) {
  546.         let mark = VarvPerformance.start();
  547.         await Trigger.trigger("deleted", {
  548.             target: uuid
  549.         });
  550.         VarvPerformance.stop("Concept.Event.deleted", mark);
  551.     }
  553.     async created(uuid) {
  554.         let mark = VarvPerformance.start();
  555.         await Trigger.trigger("created", {
  556.             target: uuid
  557.         });
  558.         VarvPerformance.stop("Concept.Event.created", mark);
  559.     }
  561.     async appeared(uuid, skipCallback=false) {
  562.         let mark = VarvPerformance.start();
  563.         // This instance just appeared in at least one datastore
  564.         await VarvEngine.sendEvent("appeared", {
  565.             target: uuid,
  566.             concept: this
  567.         });
  569.         if(!skipCallback) {
  570.             for (let callback of this.appearedCallbacks) {
  571.                 await callback(uuid, this);
  572.             }
  573.         }
  575.         VarvPerformance.stop("Concept.Event.appeared", mark);
  576.     }
  577.     async disappeared(uuid) {
  578.         let mark = VarvPerformance.start();
  580.         // This instance just disappeared in at least one datastore
  581.         await VarvEngine.sendEvent("disappeared", {
  582.             target: uuid,
  583.             concept: this
  584.         });
  586.         //Unregister the UUID
  587.         VarvEngine.deregisterConceptFromUUID(uuid, this);
  589.         for(let callback of this.disappearedCallbacks) {
  590.             await callback(uuid, this);
  591.         }
  593.         VarvPerformance.stop("Concept.Event.disappeared", mark);
  594.     }
  596.     async destroy() {
  597.         const self = this;
  599.         if(Concept.DEBUG) {
  600.             console.log("Destroying:", this);
  601.         }
  603.         //Destroy triggers
  604.         this.destroyTriggers();
  606.         //Destroy properties
  607.         for(let property of this.properties.values()) {
  608.             if(Concept.DEBUG) {
  609.                 console.log("Derigestering property:", property);
  610.             }
  611.             //Brute force trying to remove from any datastore known to mankind...
  612.             Datastore.datastores.forEach((datastore)=>{
  613.                 try {
  614.                     datastore.removeBackingStore(self, property);
  615.                 } catch(e) {
  616.                     //Ignore
  617.                 }
  618.             })
  619.         }
  621.         //Destroy behaviours
  622.         for(let behaviour of this.behaviours.values()) {
  623.             behaviour.destroy();
  624.         }
  626.         //Destroy actions
  627.         this.actions = null;
  629.         this.triggers = null;
  630.         this.properties = null;
  631.         this.behaviours = null;
  633.         if(Concept.DEBUG) {
  634.             console.log("Deregistering from VarvEngine...");
  635.         }
  636.         VarvEngine.deregisterConceptFromType(this.name);
  637.     }
  639.     isA(conceptType) {
  640.         if(conceptType instanceof Concept) {
  641.             conceptType = conceptType.name;
  642.         }
  644.         return this.name === conceptType || this.otherConcepts.has(conceptType);
  645.     }
  646. }
  647. Concept.DEBUG = false;
  648. window.Concept = Concept;