dmx-api 2.1.0 → 3.0.0

package/README.md

@@ -2,6 +2,52 @@
 
 ## Version History
 
+**3.0** -- May 19, 2023
+
+Version 3.0 of the `dmx-api` library extends/modifies the API in order to support a wider variety of frontend
+applications. Additionally, depending on application type, the launch time is reduced as less data is transferred from
+server ([#497](https://git.dmx.systems/dmx-platform/dmx-platform/-/issues/497),
+[#501](https://git.dmx.systems/dmx-platform/dmx-platform/-/issues/501)). This required some breaking changes in the
+library's `init()` function.
+
+* BREAKING CHANGES
+    - changed behavior of the library's `init()` function:
+        - The client-side type cache is not fully pre-populated by default anymore. Instead the application pass
+          `topicTypes` config to pre-populate selectively, or pass `all`. Depending on application type this results in
+          less data transfer at application launch.
+        - The SVG utility for FontAwesome icons is not initialized by default anymore. Instead an application can
+          initialize it on-demand (by calling `dmx.icons.init()`). Applications who don't need it launch quicker as
+          downloading the FontAwesome SVG data (450K) is omitted.
+    - rename class `Type` -> `DMXType`
+    - remove `getPosition()` from `ViewTopic`. Use the new `pos` getter instead.
+* Improvement:
+    - The library's `init()` function optionally opens the WebSocket for client-synchronization (if `messageHandler`
+      config is passed). The application no longer depends on
+      [dmx-websocket](https://github.com/dmx-systems/dmx-websocket) module then.
+    - Vanilla [axios](https://github.com/axios/axios) http instance (without error interceptor set by application) is
+      exported as `rpc._http`.
+* Model:
+    - change `Type`'s `newFormModel()`:
+        - `object` parameter is now optional
+        - add `allChildren` parameter (optional)
+    - add `panX`, `panY`, `zoom`, `bgImageUrl` getters to `Topicmap`
+    - add `updateTopic()`, `updateAssoc()` to `Topicmap` (part of
+      [dmx-topicmap-panel](https://github.com/dmx-systems/dmx-topicmap-panel) protocol)
+    - add `pos` getter to `ViewTopic`
+* RPC:
+    - add `getTopicType()` and `getAssocType()`
+    - add `includeChildren` parameter to `getTopicmap()`
+    - add `includeChildren` and `includeAssocChildren` parameters to `getAssignedWorkspace()`
+    - add `getMemberships()` to get the members of a workspace
+    - add `bulkUpdateUserMemberships()` and `bulkUpdateWorkspaceMemberships()`
+    - add `deleteWorkspace()`
+    - change `updateTopic()`: returns `Topic` plus directives (formerly just directives)
+    - change `login()`: returned promise resolves with username (formerly undefined)
+* Utils:
+    - add `stripHtml()`
+* Fix:
+    - fixed a bug where nested entities loose their child values while update request
+
 **2.1** -- Jun 13, 2021
 
 * Model:
@@ -219,7 +265,8 @@
 
 **0.13** -- Mar 25, 2018
 
-* Model: `Topicmap.revealTopic()`'s `pos` param is optional. If not given it's up to the topicmap renderer to position the topic.
+* Model: `Topicmap.revealTopic()`'s `pos` param is optional. If not given it's up to the topicmap renderer to position
+  the topic.
 * Utils: `clone()` for deep-cloning arbitrary objects
 * Depends on module `clone` instead `lodash.clonedeep`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dmx-api",
-  "version": "2.1.0",
-  "description": "DMX 5 base types and API",
+  "version": "3.0.0",
+  "description": "API and utilities for DMX 5 based frontends",
   "author": "Jörg Richter <jri@dmx.berlin>",
   "license": "AGPL-3.0",
   "main": "src/index.js",

package/src/icons.js

@@ -6,11 +6,17 @@ import rpc from './rpc'
 let faFont              // Font Awesome SVG <font> element
 let faDefaultWidth      // Default icon width
 
-// a promise resolved once the Font Awesome SVG is loaded
-const svgReady = rpc.getXML(fa).then(svg => {
-  faFont = svg.querySelector('font')
-  faDefaultWidth = faFont.getAttribute('horiz-adv-x')
-})
+/**
+ * Initializes the Icons-Toolkit.
+ *
+ * @returns   a promise resolved once the toolkit is ready for `faGlyph()` calls (Font Awesome SVG is loaded).
+ */
+function init () {
+  return rpc.getXML(fa).then(svg => {
+    faFont = svg.querySelector('font')
+    faDefaultWidth = faFont.getAttribute('horiz-adv-x')
+  })
+}
 
 function faGlyph (unicode) {
   try {
@@ -25,6 +31,6 @@ function faGlyph (unicode) {
 }
 
 export default {
-  ready: svgReady,
+  init,
   faGlyph
 }

package/src/index.js

@@ -1,22 +1,23 @@
-import {
-  DMXObject, Topic, Assoc, Player, RelatedTopic, Type, TopicType, AssocType, Topicmap, ViewTopic, ViewAssoc,
-  setIconRenderers
-} from './model'
-import rpc       from './rpc'
-import typeCache from './type-cache'
-import permCache from './permission-cache'
-import utils     from './utils'
-import icons     from './icons'
-
-console.log('[DMX-API] 2021/06/13')
+import * as model   from './model'
+import rpc          from './rpc'
+import permCache    from './permission-cache'
+import utils        from './utils'
+import icons        from './icons'
+import DMXWebSocket from './websocket'
+import {default as typeCache, init as initTypeCache, storeModule} from './type-cache'
+
+console.log('[DMX-API] 3.0')
 
 let adminWorkspaceId    // promise
 
-export default {
+const clientId = newClientId()
+updateClientIdCookie()
 
-  /* eslint object-property-newline: "off" */
-  DMXObject, Topic, Assoc, Player, RelatedTopic, Type, TopicType, AssocType, Topicmap, ViewTopic, ViewAssoc,
+window.addEventListener('focus', updateClientIdCookie)
 
+export default {
+
+  ...model,
   rpc,
   typeCache,
   permCache,
@@ -24,10 +25,12 @@ export default {
   icons,
 
   init (config) {
-    config.iconRenderers && setIconRenderers(config.iconRenderers)
-    config.onHttpError && rpc.setErrorHandler(config.onHttpError)
     adminWorkspaceId = rpc.getAdminWorkspaceId()
-    return typeCache.init(config.store)
+    config.store.registerModule('typeCache', storeModule)
+    config.messageHandler && new DMXWebSocket(rpc.getWebsocketConfig(), config.messageHandler)
+    config.onHttpError && rpc.setErrorHandler(config.onHttpError)
+    config.iconRenderers && model.setIconRenderers(config.iconRenderers)
+    return initTypeCache(config.topicTypes)
   },
 
   /**
@@ -37,3 +40,12 @@ export default {
     return adminWorkspaceId.then(id => permCache.isWritable(id))
   }
 }
+
+function updateClientIdCookie () {
+  // DEV && console.log('dmx_client_id', clientId)
+  utils.setCookie('dmx_client_id', clientId)
+}
+
+function newClientId () {
+  return Math.floor(Number.MAX_SAFE_INTEGER * Math.random())
+}

package/src/model.js

@@ -17,7 +17,7 @@ class DMXObject {
 
   constructor (object) {
     if (!object) {
-      throw Error(`invalid object passed to DMXObject constructor: ${object}`)
+      throw Error(`invalid object passed to DMXObject constructor: ${JSON.stringify(object)}`)
     } else if (object.constructor.name !== 'Object') {
       throw Error(`DMXObject constructor expects Object, got ${object.constructor.name} ${JSON.stringify(object)}`)
     }
@@ -186,7 +186,6 @@ class Topic extends DMXObject {
   }
 
   update () {
-    // console.log('update', this)
     return rpc.updateTopic(this)
   }
 
@@ -315,7 +314,6 @@ class Assoc extends DMXObject {
   }
 
   update () {
-    console.log('update', this)
     return rpc.updateAssoc(this)
   }
 
@@ -415,8 +413,7 @@ class RelatedTopic extends Topic {
   }
 }
 
-// TODO: name it "DMXType"
-class Type extends Topic {
+class DMXType extends Topic {
 
   constructor (type) {
     super(type)
@@ -481,15 +478,25 @@ class Type extends Topic {
   /**
    * Creates a form model for this type.
    *
-   * @param   object  optional, if given its values are filled in. ### FIXDOC
-   *                  The object is expected to be of *this* type.
+   * @param   object        optional, if given 1) its values are filled in, and 2) is manipulated in-place, that
+   *                        includes a) adding empty fields, and b) removing fields when "Reduced Details" is
+   *                        switched on (the default, see "allChildren" parameter).
+   *                        The given object is expected to be of *this* type.
+   * @param   allChildren   optional, if true all children are included in the returned form model, that is
+   *                        "Reduced Details" is switched off. Default is false.
    *
-   * @return  the created form model. ### FIXDOC
+   * @return  the created form model. If "object" is given the (in-place manipulated) object is returned.
+   *          Otherwise a newly created form model with empty values is returned.
    */
-  newFormModel (object) {
-    const o = this._newFormModel(object)
-    object.children = utils.instantiateChildren(o.children)
-    return object
+  newFormModel (object, allChildren) {
+    const o = this._newFormModel(object, allChildren)
+    if (object) {
+      object.children = utils.instantiateChildren(o.children)
+      // FIXME: o.assoc is not used
+      return object
+    } else {
+      return o
+    }
   }
 
   /**
@@ -498,14 +505,14 @@ class Type extends Topic {
    *
    * @return  a newly constructed plain object
    */
-  _newFormModel (object) {
+  _newFormModel (object, allChildren, level = 0, compDef) {
 
     function _newFormModel (object, type, level, compDef) {
       const o = type._newInstance(object)
       if (type.isComposite) {
         type.compDefs.forEach(compDef => {
           // Reduced details: at deeper levels for entity types only their identity attributes are included
-          if (level === 0 || type.isValue || compDef.isIdentityAttr) {
+          if (allChildren || level === 0 || type.isValue || compDef.isIdentityAttr) {
             const compDefUri = compDef.compDefUri
             const childType = compDef.childType
             const child = object && object.children[compDefUri]
@@ -528,23 +535,21 @@ class Type extends Topic {
       return o
     }
 
-    return _newFormModel(object, this, 0)
+    return _newFormModel(object, this, level, compDef)
   }
 
   _newInstance (object) {
-    // console.log('_newInstance', this, object)
-    const o = {
+    return {
       id:      object ? object.id      : -1,
       uri:     object ? object.uri     : '',
       typeUri: object ? object.typeUri : this.uri,
       value:   object ? object.value   : '',
       children: {}
     }
-    return o
   }
 }
 
-class TopicType extends Type {
+class TopicType extends DMXType {
 
   /**
    * Creates a form model for this topic type, and fills in the given value.
@@ -589,7 +594,7 @@ class TopicType extends Type {
   }
 }
 
-class AssocType extends Type {
+class AssocType extends DMXType {
 
   get isTopicType () {
     return false
@@ -674,7 +679,7 @@ class CompDef extends Assoc {
     return topic && topic.value
   }
 
-  // ### TODO: principal copy in Type
+  // ### TODO: principal copy in DMXType
   _getViewConfig (childTypeUri) {
     // TODO: don't hardcode config type URI
     const configTopic = this.viewConfig['dmx.webclient.view_config']
@@ -694,8 +699,8 @@ class CompDef extends Assoc {
     return 'dmx.core.composition'
   }
 
-  emptyChildInstance () {
-    const topic = this.childType._newFormModel()
+  emptyChildInstance (level) {
+    const topic = this.childType._newFormModel(undefined, false, level, this)
     topic.assoc = this.instanceLevelAssocType._newFormModel()
     return new Topic(topic)
   }
@@ -796,17 +801,16 @@ class Topicmap extends Topic {
   }
 
   /**
-   * Returns the position of the given topic/assoc.
-   *
-   * Note: ViewTopic has getPosition() too but ViewAssoc has not
-   * as a ViewAssoc doesn't know the Topicmap it belongs to.
+   * Returns the position of the given topic/assoc of this topicmap.
    *
    * @param   id      a topic ID or an assoc ID
    */
   getPosition (id) {
+    // Note: a ViewAssoc can't have a `pos` getter (like ViewTopic) as assoc pos is calculated from the player objects
+    // and the assoc only has its IDs and no reference to the Topicmap. So we make `getPosition()` a Topicmap method.
     const o = this.getObject(id)
     if (o.isTopic) {
-      return o.getPosition()
+      return o.pos
     } else {
       const pos1 = this.getPosition(o.player1.id)
       const pos2 = this.getPosition(o.player2.id)
@@ -818,22 +822,28 @@ class Topicmap extends Topic {
   }
 
   /**
+   * Adds the given topic to this topicmap.
+   * If the topic is contained in the topicmap already (ID-check) it is replaced.
+   *
    * @param   topic   a dmx.ViewTopic
    */
   addTopic (topic) {
     if (!(topic instanceof ViewTopic)) {
-      throw Error(`addTopic() expects a ViewTopic, got ${topic.constructor.name}`)
+      throw Error(`addTopic() expects ViewTopic, got ${topic.constructor.name}`)
     }
     // reactivity is required to trigger "visibleTopicIds" getter (module dmx-cytoscape-renderer)
     Vue.set(this._topics, topic.id, topic)
   }
 
   /**
+   * Adds the given assoc to this topicmap.
+   * If the assoc is contained in the topicmap already (ID-check) it is replaced.
+   *
    * @param   assoc   a dmx.ViewAssoc
    */
   addAssoc (assoc) {
     if (!(assoc instanceof ViewAssoc)) {
-      throw Error(`addAssoc() expects a ViewAssoc, got ${assoc.constructor.name}`)
+      throw Error(`addAssoc() expects ViewAssoc, got ${assoc.constructor.name}`)
     }
     // reactivity is required to trigger "visibleAssocIds" getter (module dmx-cytoscape-renderer)
     Vue.set(this._assocs, assoc.id, assoc)
@@ -905,6 +915,21 @@ class Topicmap extends Topic {
     return op
   }
 
+  // the following 4 methods are part of the Topicmap Panel protocol
+
+  updateTopic (topic) {
+    if (this.id === topic.id) {
+      Vue.set(
+        this.children,
+        'dmx.base.url#dmx.topicmaps.background_image',
+        topic.children['dmx.base.url#dmx.topicmaps.background_image']
+      )
+    }
+  }
+
+  updateAssoc (assoc) {
+  }
+
   /**
    * Note: if the topic is not in this topicmap nothing is performed.
    */
@@ -965,6 +990,23 @@ class Topicmap extends Topic {
 
   // Topicmap
 
+  get panX () {
+    return this.viewProps['dmx.topicmaps.pan_x']
+  }
+
+  get panY () {
+    return this.viewProps['dmx.topicmaps.pan_y']
+  }
+
+  get zoom () {
+    return this.viewProps['dmx.topicmaps.zoom']
+  }
+
+  get bgImageUrl () {
+    const url = this.children['dmx.base.url#dmx.topicmaps.background_image']
+    return url && url.value
+  }
+
   setViewport (pan, zoom) {
     this.viewProps['dmx.topicmaps.pan_x'] = pan.x
     this.viewProps['dmx.topicmaps.pan_y'] = pan.y
@@ -1020,8 +1062,7 @@ class ViewTopic extends viewPropsMixin(Topic) {
     return rpc.getTopic(this.id, true, true)
   }
 
-  // TODO: make it a "pos" getter?
-  getPosition () {
+  get pos () {
     return {
       x: this.getViewProp('dmx.topicmaps.x'),
       y: this.getViewProp('dmx.topicmaps.y')
@@ -1059,7 +1100,7 @@ export {
   Assoc,
   Player,
   RelatedTopic,
-  Type,
+  DMXType,
   TopicType,
   AssocType,
   RoleType,

package/src/rpc.js

@@ -108,9 +108,11 @@ export default {
   },
 
   updateTopic (topicModel) {
-    return http.put(`/core/topic/${topicModel.id}`, topicModel).then(response =>
-      response.data
-    )
+    return http.put(`/core/topic/${topicModel.id}`, topicModel).then(response => {
+      const topic = new Topic(response.data)
+      topic.directives = response.data.directives
+      return topic
+    })
   },
 
   deleteTopic (id) {
@@ -204,6 +206,12 @@ export default {
 
   // Topic Types
 
+  getTopicType (topicTypeUri) {
+    return http.get(`/core/topic-type/${topicTypeUri}`).then(response =>
+      new TopicType(response.data)
+    )
+  },
+
   getTopicTypeImplicitly (topicId) {
     return http.get(`/core/topic-type/topic/${topicId}`).then(response =>
       new TopicType(response.data)
@@ -230,6 +238,12 @@ export default {
 
   // Association Types
 
+  getAssocType (assocTypeUri) {
+    return http.get(`/core/assoc-type/${assocTypeUri}`).then(response =>
+      new AssocType(response.data)
+    )
+  },
+
   getAssocTypeImplicitly (assocId) {
     return http.get(`/core/assoc-type/assoc/${assocId}`).then(response =>
       new AssocType(response.data)
@@ -300,8 +314,12 @@ export default {
     )
   },
 
-  getTopicmap (topicmapId) {
-    return http.get(`/topicmaps/${topicmapId}`).then(response =>
+  getTopicmap (topicmapId, includeChildren) {
+    return http.get(`/topicmaps/${topicmapId}`, {
+      params: {
+        children: includeChildren,
+      }
+    }).then(response =>
       new Topicmap(response.data)
     )
   },
@@ -368,7 +386,6 @@ export default {
   },
 
   setTopicmapViewport: utils.debounce((topicmapId, pan, zoom) => {
-    // console.log('setTopicmapViewport')
     roundPos(pan, 'x', 'y')
     http.put(`/topicmaps/${topicmapId}/pan/${pan.x}/${pan.y}/zoom/${zoom}`)
   }, 3000),
@@ -386,6 +403,10 @@ export default {
     )
   },
 
+  deleteWorkspace (workspaceId) {
+    http.delete(`/workspaces/${workspaceId}`)
+  },
+
   getAssignedTopics (workspaceId, topicTypeUri, includeChildren, includeAssocChildren) {
     return http.get(`/workspaces/${workspaceId}/topics/${topicTypeUri}`, {
       params: {
@@ -400,8 +421,13 @@ export default {
   /**
    * @return  the workspace topic, or empty string if no workspace is assigned
    */
-  getAssignedWorkspace (objectId) {
-    return http.get(`/workspaces/object/${objectId}`).then(response =>
+  getAssignedWorkspace (objectId, includeChildren, includeAssocChildren) {
+    return http.get(`/workspaces/object/${objectId}`, {
+      params: {
+        children: includeChildren,
+        assocChildren: includeAssocChildren
+      }
+    }).then(response =>
       // Note: if no workspace is assigned the response is 204 No Content; "data" is the empty string then
       response.data && new Topic(response.data)
     )
@@ -422,7 +448,10 @@ export default {
       headers: {
         Authorization: authMethod + ' ' + btoa(credentials.username + ':' + credentials.password)
       }
-    }).then(() => permCache.clear())
+    }).then(() => {
+      permCache.clear()
+      return credentials.username
+    })
   },
 
   logout () {
@@ -448,6 +477,34 @@ export default {
     )
   },
 
+  getMemberships (id) {
+    return http.get(`/access-control/workspace/${id}/memberships`).then(response =>
+      utils.instantiateMany(response.data, RelatedTopic)
+    )
+  },
+
+  bulkUpdateUserMemberships (username, addWorkspaceIds, removeWorkspaceIds) {
+    return http.put(`/access-control/user/${username}`, undefined, {
+      params: {
+        addWorkspaceIds: addWorkspaceIds.join(','),
+        removeWorkspaceIds: removeWorkspaceIds.join(',')
+      }
+    }).then(response =>
+      utils.instantiateMany(response.data, RelatedTopic)
+    )
+  },
+
+  bulkUpdateWorkspaceMemberships (workspaceId, addUserIds, removeUserIds) {
+    return http.put(`/access-control/workspace/${workspaceId}`, undefined, {
+      params: {
+        addUserIds: addUserIds.join(','),
+        removeUserIds: removeUserIds.join(',')
+      }
+    }).then(response =>
+      utils.instantiateMany(response.data, RelatedTopic)
+    )
+  },
+
   getAdminWorkspaceId () {
     return http.get('/access-control/workspace/admin/id').then(response =>
       response.data
@@ -548,7 +605,9 @@ export default {
         return Promise.reject(error)
       }
     )
-  }
+  },
+
+  _http
 }
 
 function toPath (idLists) {

package/src/type-cache.js

@@ -3,14 +3,15 @@ import rpc from './rpc'
 import utils from './utils'
 import Vue from 'vue'
 
+const typeP = {}      // intermediate type promises
+
 // Note: the type cache is reactive state. E.g. new topic types appear in the Search Widget's
 // type menu automatically (see "createTopicTypes" getter in search.js of module dmx-search).
-
 const state = {
-  topicTypes: undefined,    // object: topic type URI (string) -> TopicType
-  assocTypes: undefined,    // object: assoc type URI (string) -> AssocType
-  roleTypes:  undefined,    // object: role type URI (string) -> RoleType
-  dataTypes:  undefined     // object: data type URI (string) -> data type (Topic)
+  topicTypes: {},     // object: topic type URI (string) -> TopicType
+  assocTypes: {},     // object: assoc type URI (string) -> AssocType
+  roleTypes:  {},     // object: role type URI (string) -> RoleType
+  dataTypes:  {}      // object: data type URI (string) -> data type (Topic)
 }
 
 const actions = {
@@ -27,8 +28,11 @@ const actions = {
     _putRoleType(roleType)
   },
 
+  /**
+   * Re-populates the type cache with *all* types readable by current user.
+   */
   initTypeCache () {
-    return initTypes()
+    return initAllTypes()
   },
 
   // WebSocket messages
@@ -104,30 +108,17 @@ const actions = {
   }
 }
 
-function init (store) {
-  store.registerModule('typeCache', {state, actions})
-  return initTypes()
-}
-
-function initTypes () {
-  return Promise.all([
-    // init state
-    rpc.getAllTopicTypes().then(topicTypes => {
-      state.topicTypes = utils.mapByUri(topicTypes)
-      _putTopicType(bootstrapType())
-    }),
-    rpc.getAllAssocTypes().then(assocTypes => {
-      state.assocTypes = utils.mapByUri(assocTypes)
-    }),
-    rpc.getAllRoleTypes().then(roleTypes => {
-      state.roleTypes = utils.mapByUri(roleTypes)
-    }),
-    rpc.getTopicsByType('dmx.core.data_type').then(dataTypes => {
-      state.dataTypes = utils.mapByUri(dataTypes)
-    })
-  ]).then(() => {
-    // console.log('### Type cache ready!')
-  })
+function init (topicTypes) {
+  if (topicTypes) {
+    let p
+    if (topicTypes === 'all') {
+      p = initAllTypes()
+    } else {
+      topicTypes.forEach(_initTopicType)
+      // TODO: return promise
+    }
+    return p
+  }
 }
 
 // ---
@@ -149,9 +140,9 @@ function getRoleType (uri) {
 }
 
 function getType (uri, className, prop) {
-  const type = state[prop] && state[prop][uri]
+  const type = _getType(uri, prop)
   if (!type) {
-    throw Error(`unknown ${className} "${uri}"`)
+    throw Error(`${className} "${uri}" not in type cache`)
   }
   return type
 }
@@ -169,7 +160,7 @@ function getTypeById (id) {
 
 // TODO: the following 4 functions return async data so they should return promise
 
-// IMPORTANT: call these methods only from a reactive context, otherwise you might get undefined
+// IMPORTANT: calling these methods must be synced, otherwise you might get undefined
 
 function getAllTopicTypes () {
   return getAllTypes('topicTypes')
@@ -196,6 +187,67 @@ function getAllTypes (prop) {
 
 // ---
 
+function initAllTypes () {
+  return Promise.all([
+    // init state
+    rpc.getAllTopicTypes().then(topicTypes => {
+      state.topicTypes = utils.mapByUri(topicTypes)
+      _putTopicType(bootstrapType())
+    }),
+    rpc.getAllAssocTypes().then(assocTypes => {
+      state.assocTypes = utils.mapByUri(assocTypes)
+    }),
+    rpc.getAllRoleTypes().then(roleTypes => {
+      state.roleTypes = utils.mapByUri(roleTypes)
+    }),
+    rpc.getTopicsByType('dmx.core.data_type').then(dataTypes => {
+      state.dataTypes = utils.mapByUri(dataTypes)
+    })
+  ])
+}
+
+function _initTopicType (uri) {
+  _initType(uri, 'topicTypes', TopicType, rpc.getTopicType).then(topicType => {
+    topicType.compDefs.forEach(compDef => {
+      _initTopicType(compDef.childTypeUri)
+      _initAssocType(compDef.instanceLevelAssocTypeUri)
+    })
+  })
+}
+
+function _initAssocType (uri) {
+  _initType(uri, 'assocTypes', AssocType, rpc.getAssocType).then(assocType => {
+    assocType.compDefs.forEach(compDef => {
+      _initTopicType(compDef.childTypeUri)
+      // TODO: call _initAssocType()?
+    })
+  })
+}
+
+function _initType (uri, prop, typeClass, fetchFunc) {
+  const type = _getType(uri, prop)
+  if (type) {
+    return Promise.resolve(type)
+  } else {
+    let p = typeP[uri]
+    if (!p) {
+      p = fetchFunc(uri).then(type => {
+        _putType(type, typeClass, prop)
+        delete typeP[uri]
+        return type
+      })
+      typeP[uri] = p
+    }
+    return p
+  }
+}
+
+function _getType (uri, prop) {
+  return state[prop] && state[prop][uri]
+}
+
+// ---
+
 function putTopicType (topicType) {
   _putTopicType(new TopicType(topicType))
 }
@@ -260,8 +312,9 @@ function bootstrapType () {
   })
 }
 
+// public API
+
 export default {
-  init,
   getTopicType,
   getAssocType,
   getDataType,
@@ -272,3 +325,8 @@ export default {
   getAllDataTypes,
   getAllRoleTypes
 }
+
+// module internal API
+
+export {init}
+export const storeModule = {state, actions}

package/src/utils.js

@@ -184,6 +184,10 @@ function round (val, decimals) {
   return Math.round(factor * val) / factor
 }
 
+function stripHtml (html) {
+  return html.replace(/<.*?>/g, '')     // *? is the reluctant version of the * quantifier (which is greedy)
+}
+
 // ---
 
 export default {
@@ -202,5 +206,6 @@ export default {
   deleteCookie,
   fulltextQuery,
   formatFileSize,
-  round
+  round,
+  stripHtml
 }

package/src/websocket.js

@@ -0,0 +1,77 @@
+const IDLE_INTERVAL   = 60 * 1000     // 60s
+const RECONNECT_DELAY =  5 * 1000     // 5s
+
+/**
+ * A WebSocket connection to the DMX server.
+ *
+ * The URL to connect to is determined automatically, based on the server-side `dmx.websockets.url` config property.
+ * WebSocket messages are expected to be JSON. Serialization/Deserialization performs automatically.
+ *
+ * Properties:
+ *   `url` - url of the WebSocket server
+ *   `ws`  - the native WebSocket object
+ */
+export default class DMXWebSocket {
+
+  /**
+   * @param   messageHandler
+   *              the function that processes incoming messages.
+   *              One argument is passed: the message pushed by the server (a deserialzed JSON object).
+   */
+  constructor (config, messageHandler) {
+    this.messageHandler = messageHandler
+    config.then(config => {
+      this.url = config['dmx.websockets.url']
+      // DEV && console.log('[DMX] CONFIG: WebSocket server is reachable at', this.url)
+      this._connect()
+    })
+  }
+
+  /**
+   * Sends a message to the server.
+   *
+   * @param   message   the message to be sent (arbitrary type). Will be serialized as JSON.
+   */
+  send (message) {
+    this.ws.send(JSON.stringify(message))
+  }
+
+  _connect () {
+    DEV && console.log('[DMX] Opening WebSocket connection to', this.url)
+    this.ws = new WebSocket(this.url)
+    this.ws.onopen = e => {
+      this._startIdling()
+    }
+    this.ws.onmessage = e => {
+      const message = JSON.parse(e.data)
+      DEV && console.log('[DMX] Receiving message', message)
+      this.messageHandler(message)
+    }
+    this.ws.onclose = e => {
+      DEV && console.log('[DMX] Closing WebSocket connection (' + e.reason + '), try reconnect in ' +
+        RECONNECT_DELAY / 1000 + ' seconds')
+      this._stopIdling()
+      this._reconnect()
+    }
+    this.ws.onerror = e => {
+      DEV && console.warn('[DMX] WebSocket error')
+    }
+  }
+
+  _reconnect () {
+    setTimeout(this._connect.bind(this), RECONNECT_DELAY)
+  }
+
+  _startIdling () {
+    this.idleId = setInterval(this._idle.bind(this), IDLE_INTERVAL)
+  }
+
+  _stopIdling () {
+    clearInterval(this.idleId)
+  }
+
+  _idle () {
+    DEV && console.log('[DMX] WebSocket connection idle')
+    this.send({type: 'idle'})
+  }
+}