@transitive-sdk/utils-web 0.7.5 → 0.7.7

package/README.md

@@ -0,0 +1,11 @@
+<p align="center">
+  <a href="https://transitiverobotics.com">
+    <img src="https://transitiverobotics.com/img/logo.svg" style="height: 64px">
+  </a>
+</p>
+
+## Transitive Web Utils
+
+Utilities used by the web components of [Transitive Robotics](https://transitiverobotics.com) capabilities.
+
+[Documentation](https://transitiverobotics.com/docs/sdk/utils-web)

package/client.js

@@ -18,7 +18,7 @@ export const parseCookie = str =>
       return acc;
     }, {});
 
-/* get or post (if body given) json */
+/** get or post (if body given) json */
 export const fetchJson = (url, callback, options = {}) => {
   fetch(url, {
     method: options.method || (options.body ? 'post' : 'get'),

package/docs/index.md

@@ -0,0 +1,739 @@
+# Web (browser)
+
+These classes and functions are available via the `@transitive-sdk/utils-web` npm package and are for use in the browser or other browser based front-ends.
+
+### Example
+
+In this example we create a new web-component (custom element) from a React component using mqttSync to subscribe to some data and re-rendering it in real-time whenever it changes.
+
+```js
+import React, { useEffect } from 'react';
+
+import { createWebComponent, useTransitive, getLogger }
+  from '@transitive-sdk/utils-web';
+
+const log = getLogger('my-new-capability');
+log.setLevel('debug');
+
+// Get the name of the package we are part of. TR_PKG_NAME is set by esbuild.
+const [scope, capabilityName] = TR_PKG_NAME.split('/');
+
+const Device = ({jwt, id, host, ssl}) => {
+
+  const { mqttSync, data, StatusComponent, prefixVersion } =
+    useTransitive({ jwt, id, host, ssl,
+      capability: TR_PKG_NAME,
+      versionNS: TR_PKG_VERSION_NS
+    });
+
+  // once mqttSync is connected, subscribe to some topics
+  useEffect(() => {
+      if (!mqttSync) return;
+      mqttSync.subscribe(`${prefixVersion}/device`);
+      mqttSync.subscribe(`${prefixVersion}/cloud`);
+    }, [mqttSync]);
+
+  log.debug({prefixVersion, data, TR_PKG_NAME, TR_PKG_VERSION, TR_PKG_VERSION_NS});
+
+  return <div>
+    <StatusComponent />
+    <pre>
+      {/* Render the data. This updates automatically whenever data changes. */}
+      {JSON.stringify(data, true, 2)}
+    </pre>
+  </div>;
+};
+
+createWebComponent(Device, `${capabilityName}-device`, ['jwt']);
+```
+
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## DataCache
+
+A class implementing a local data cache, used as a local data store with
+deduplication detection and update events. While this class is very handy
+you probably won't need to create instances of it directly. Instead use
+the mqttSync.data instance which holds the locally stored data
+subscribed/published from/to MQTTSync.
+For example on the robot:
+
+```js
+// update/publish our status:
+mqttSync.data.update('status', {changed: Date.now(), msg: 'OK'});
+// subscribe to new user requests (e.g., from UI):
+mqttSync.data.subscribePath('+user/request', (request, key, {user}) => {
+log.debug(`user ${user} made request`, request);
+});
+```
+
+In the cloud or in a web component you would need to use the full topic including
+org, device, scope, cap-name, and version.
+
+#### Parameters
+
+*   `data`   (optional, default `{}`)
+
+### filter
+
+Filter the object using path with wildcards
+
+##### Parameters
+
+*   `path` &#x20;
+
+### filterByTopic
+
+Filter the object using topic with wildcards
+
+##### Parameters
+
+*   `topic` &#x20;
+
+### forMatch
+
+For each topic match, invoke the callback with the value, topic, and match
+just like subscribePath, but on the current data rather than future changes.
+
+##### Parameters
+
+*   `topic` &#x20;
+*   `callback` &#x20;
+
+### forPathMatch
+
+For each path match, invoke the callback with the value, topic, and match
+just like subscribePath
+
+##### Parameters
+
+*   `path` &#x20;
+*   `callback` &#x20;
+
+### get
+
+Get sub-value at path, or entire object if none given
+
+##### Parameters
+
+*   `path`   (optional, default `[]`)
+
+### getByTopic
+
+Get sub-value specified by topic
+
+##### Parameters
+
+*   `topic` &#x20;
+
+### subscribe
+
+Add a callback for all change events.
+
+##### Parameters
+
+*   `callback` &#x20;
+
+### subscribePath
+
+Subscribe to a specific topic only. Callback receives
+`value, key, matched, tags`.
+
+##### Parameters
+
+*   `topic` &#x20;
+*   `callback` &#x20;
+
+### subscribePathFlat
+
+Same as subscribePath but always get all changes in flat form
+
+##### Parameters
+
+*   `topic` &#x20;
+*   `callback` &#x20;
+
+### unsubscribe
+
+Remove a callback previously registered using `subscribe`.
+
+##### Parameters
+
+*   `callback` &#x20;
+
+### update
+
+Update the value at the given path (array or dot separated string)
+
+##### Parameters
+
+*   `path` &#x20;
+*   `value` &#x20;
+*   `tags` &#x20;
+
+### updateFromArray
+
+Update the object with the given value at the given path, remove empty;
+return the flat changes (see toFlatObject). Add `tags` to updates to mark
+them somehow based on the context, e.g., so that some subscriptions can choose
+to ignore updates with a certain tag.
+
+##### Parameters
+
+*   `path` &#x20;
+*   `value` &#x20;
+*   `tags`   (optional, default `{}`)
+
+### updateFromModifier
+
+Update data from a modifier object where keys are topic names to be
+interpreted as paths, and values are the values to set
+
+##### Parameters
+
+*   `modifier` &#x20;
+*   `tags` &#x20;
+
+### updateFromTopic
+
+Set value from the given topic (with or without leading or trailing slash)
+
+##### Parameters
+
+*   `topic` &#x20;
+*   `value` &#x20;
+*   `tags` &#x20;
+
+## ErrorBoundary
+
+**Extends React.Component**
+
+A simple error boundary. Usage: <ErrorBoundary message="Something went wrong"> <SomeFlakyComponent /> </ErrorBoundary>
+
+#### Parameters
+
+*   `props` &#x20;
+
+## MqttSync
+
+A class that combines DataCache and MQTT to implement a data synchronization
+feature over the latter. Relies on retained messages in mqtt for persistence.
+
+#### Parameters
+
+*   `options` **[object][1]**&#x20;
+
+    *   `options.mqttClient` **[object][1]** An already connected mqtt.js client.
+    *   `options.onChange` **[function][2]?** A function that is called any time there
+        is a change to the shared data. This is not usually used. It's usually better to
+        use the finer grained `MqttSync.data.subscribePath` instead, that allows you to
+        subscribe to changes just on a specific sun-object instead, see DataCache.
+    *   `options.ignoreRetain` **[boolean][3]?** retain all messages, ignorant of the retain
+        flag.
+    *   `options.migrate` **[array][4]?** an array of objects of the form
+        `{topic, newVersion, level}`. Only meaningful in the cloud. Instructs MQTTSync
+        to first migrate existing topics to a new version namespace, publishing at the
+        designated level down from the version level. For example:```js
+        [{ topic: `/myorg/mydevice/@local/my-cap/+/config`,
+        newVersion: this.version,
+        level: 1
+        }]
+        ```Would migrate any existing data in the capability's `config` namespace to the
+        current version of the package, publishing at the `config/+` level (rather than
+        atomically at the config level itself).
+    *   `options.onReady` **[function][2]?** A function that is called when the MQTTSync
+        client is ready and has completed any requested migrations.
+    *   `options.sliceTopic` **[number][5]?** a number indicating at what level to
+        slice the topic, i.e., only use a suffix. Used in robot-capabilities to slice
+        off the topic prefix (namespaces).
+
+### beforeDisconnect
+
+Run all registered hooks before disconnecting
+
+### clear
+
+Delete all retained messages in a certain topic prefix, waiting for
+a mqtt broker heartbeat to collect existing retained. Use with care, never
+delete topics not owned by us. Harmless within capabilities, which are
+namespaced already.
+
+`options.filter(topic)`: a function that can be provided to further,
+programmatically filter the set of topics to clear, e.g., to onlt clear
+topics of old versions.
+
+Note: This may not yet work in robot-capabilities, since the subscription
+prefix and received topic prefix don't match (the device prefix is added to
+subscription by localMQTT.
+
+##### Parameters
+
+*   `prefixes` &#x20;
+*   `callback`   (optional, default `undefined`)
+*   `options`   (optional, default `{}`)
+
+### clearThrottle
+
+clear the set throttling delay
+
+### isPublished
+
+Check whether we are publishing the given topic in a non-atomic way.
+This is used to determine whether to store the published value or not.
+
+##### Parameters
+
+*   `topic` &#x20;
+
+### isSubscribed
+
+check whether we are subscribed to the given topic
+
+##### Parameters
+
+*   `topic` &#x20;
+
+### migrate
+
+Migrate a list of {topic, newVersion, transform}. The version number in
+topic will be ignored, and all versions' values will be merged, applied in
+order, such that the latest version is applied last.
+
+##### Parameters
+
+*   `list` &#x20;
+*   `onReady`   (optional, default `undefined`)
+
+### onBeforeDisconnect
+
+register a new hook to be called before disconnecting
+
+##### Parameters
+
+*   `fn` &#x20;
+
+### publish
+
+Register a listener for path in data. Make sure to populate the data
+before calling this or set the data all at once afterwards.
+
+With option "atomic" this will always send the whole sub-document,
+not flat changes. Useful, e.g., for desiredPackages, see
+[https://github.com/chfritz/transitive/issues/85][6].
+
+##### Parameters
+
+*   `topic` &#x20;
+*   `options`   (optional, default `{atomic:false}`)
+
+Returns **any** true if publication added (false, e.g., when already present)
+
+### publishAtLevel
+
+Publish all values at the given level of the given object under the given
+topic (plus sub-key, of course).
+TODO: Is this OK, or do we need to go through this.publish?
+
+##### Parameters
+
+*   `topic` &#x20;
+*   `value` &#x20;
+*   `level` &#x20;
+
+### setThrottle
+
+set min delay between processing of queue
+
+##### Parameters
+
+*   `delay` &#x20;
+
+### subscribe
+
+Subscribe to the given topic (and all sub-topics). The callback will
+indicate success/failure, *not* a message on the topic.
+
+##### Parameters
+
+*   `topic` &#x20;
+*   `callback`   (optional, default `noop`)
+
+### waitForHeartbeatOnce
+
+register a callback for the next heartbeat from the broker
+
+##### Parameters
+
+*   `callback` &#x20;
+
+## clone
+
+Deep-clone the given object. All functionality is lost, just data is kept.
+
+#### Parameters
+
+*   `obj` &#x20;
+
+## Code
+
+reusable component for showing code
+
+#### Parameters
+
+*   `$0` **[Object][1]**&#x20;
+
+    *   `$0.children` &#x20;
+
+## componentPermitsRefs
+
+whether or not the given react component allows refs, i.e., is either
+a functional component wrapped with forwardRef or a class component
+
+#### Parameters
+
+*   `Component` &#x20;
+
+## createWebComponent
+
+Create a WebComponent from the given react component and name that is
+reactive to the given attributes (if any).
+
+#### Parameters
+
+*   `Component` &#x20;
+*   `name` &#x20;
+*   `reactiveAttributes`   (optional, default `[]`)
+*   `version`   (optional, default `'0.0.0'`)
+*   `options`   (optional, default `{}`)
+
+## dropWildcardIds
+
+reduce wildcards with Ids, such as `+sessionId`, to just +
+
+#### Parameters
+
+*   `x` &#x20;
+
+## fetchJson
+
+get or post (if body given) json
+
+#### Parameters
+
+*   `url` &#x20;
+*   `callback` &#x20;
+*   `options`   (optional, default `{}`)
+
+## forMatchIterator
+
+Iterate through the object and invoke callback for each match of path (with
+named wildcards)
+
+#### Parameters
+
+*   `obj` &#x20;
+*   `path` &#x20;
+*   `callback` &#x20;
+*   `pathSoFar`   (optional, default `[]`)
+*   `matchSoFar`   (optional, default `{}`)
+
+## getLogger
+
+Get a new loglevel logger; call with a name, e.g., `module.id`. The returned
+logger has methods trace, debug, info, warn, error. See
+[https://www.npmjs.com/package/loglevel][7] for details.
+
+## isPrefixOf
+
+prefixArray is a prefix of the array
+
+#### Parameters
+
+*   `prefixArray` &#x20;
+*   `array` &#x20;
+
+## isSubTopicOf
+
+sub is a strict sub-topic of parent, and in particular not equal
+
+#### Parameters
+
+*   `sub` &#x20;
+*   `parent` &#x20;
+
+## LevelBadge
+
+The right badge for the level
+
+#### Parameters
+
+*   `$0` **[Object][1]**&#x20;
+
+    *   `$0.level` &#x20;
+
+## mergeVersions
+
+given an object where the keys are versions, merge this into one object
+where the latest version of each subfield overwrites any previous
+
+#### Parameters
+
+*   `versionsObject` &#x20;
+*   `subTopic`   (optional, default `undefined`)
+*   `options`   (optional, default `{}`)
+
+## mqttClearRetained
+
+delete all retained messages in a certain topic prefix, waiting for
+a given delay to collect existing retained. Use with care, never delete topics
+not owned by us. Harmless within capabilities, which are namespaced already.
+
+#### Parameters
+
+*   `mqttClient` &#x20;
+*   `prefixes` &#x20;
+*   `callback` &#x20;
+*   `delay`   (optional, default `1000`)
+
+## parseCookie
+
+parse document cookies
+
+#### Parameters
+
+*   `str` &#x20;
+
+## parseMQTTTopic
+
+parse an MQTT topic according to our topic schema
+
+#### Parameters
+
+*   `topic` &#x20;
+
+## parseMQTTUsername
+
+parse usernames used in MQTT
+
+#### Parameters
+
+*   `username` &#x20;
+
+## pathToTopic
+
+convert a path array to mqtt topic; reduces +id identifiers to +
+
+#### Parameters
+
+*   `pathArray` &#x20;
+
+## selectFromObject
+
+given an object and a path with wildcards (\* and +), *modify* the object
+to only contain elements matched by the path, e.g.,
+{a: {b: 1, c: 2}, d: 2} and \['a','+'] would give {a: {b: 1, c: 2}}
+
+#### Parameters
+
+*   `obj` **[object][1]** The object to select from
+*   `path` **[array][4]** An array specifying the path to select, potentially
+    containing mqtt wildcards ('+').
+
+## setFromPath
+
+Like \_.set but without arrays. This allows using numbers as keys.
+
+#### Parameters
+
+*   `obj` &#x20;
+*   `path` &#x20;
+*   `value` &#x20;
+
+## toFlatObject
+
+Given an object, return a new flat object of topic+value pairs, e.g.:
+
+```js
+{a: {b: 1, c: 2}, d: 3}   →   {'/a/b': 1, '/a/c': 2, '/d': 3}
+```
+
+Note: not idempotent!
+
+```js
+{'/a/b': 1, '/a/c': 2, d: 3}  →  {'%2Fa%2Fb': 1, '%2Fa%2Fc': 2, '/d': 3}
+```
+
+#### Parameters
+
+*   `obj` &#x20;
+*   `prefix`   (optional, default `[]`)
+*   `rtv`   (optional, default `{}`)
+
+## topicMatch
+
+match a slash-separated topic with a selector using +XYZ for (named)
+wildcards. Return the matching result.
+
+#### Parameters
+
+*   `selector` &#x20;
+*   `topic` &#x20;
+
+## topicToPath
+
+convert topic to path array
+
+#### Parameters
+
+*   `topic` &#x20;
+
+## tryJSONParse
+
+Try parsing JSON, return null if unsuccessful
+
+#### Parameters
+
+*   `string` &#x20;
+
+## unset
+
+Unset the topic in that obj, and clean up parent if empty, recursively.
+Return the path to the removed node.
+
+#### Parameters
+
+*   `obj` &#x20;
+*   `path` &#x20;
+
+## updateObject
+
+given a modifier {"a/b/c": "xyz"} update the object `obj` such that
+obj.a.b.c = "xyz"
+
+#### Parameters
+
+*   `obj` &#x20;
+*   `modifier` &#x20;
+
+## useMqttSync
+
+hook for using MqttSync in React
+
+#### Parameters
+
+*   `$0` **[Object][1]**&#x20;
+
+    *   `$0.jwt` &#x20;
+    *   `$0.id` &#x20;
+    *   `$0.mqttUrl` &#x20;
+
+## useTransitive
+
+Hook for using Transitive in React. Connects to MQTT, establishes sync, and
+exposes reactive `data` state variable.
+
+#### Parameters
+
+*   `$0` **[Object][1]**&#x20;
+
+    *   `$0.jwt` &#x20;
+    *   `$0.id` &#x20;
+    *   `$0.host` &#x20;
+    *   `$0.ssl` &#x20;
+    *   `$0.capability` &#x20;
+    *   `$0.versionNS` &#x20;
+
+## versionCompare
+
+Compare to version strings. Return -1 if a is lower than b,
+0 if they are equal, and 1 otherwise. If either is not a complete version,
+e.g., 2.0, interpret it as a range and use its minimum version for the
+comparison. Hence, 2.0 < 2.0.1.
+
+#### Parameters
+
+*   `a` &#x20;
+*   `b` &#x20;
+
+## visit
+
+Reusable visitor pattern: iteratively visits all nodes in the tree
+described by `object`, where `childField` indicates the child-of predicate.
+
+#### Parameters
+
+*   `object` &#x20;
+*   `childField` &#x20;
+*   `visitor` &#x20;
+
+## wait
+
+Wait for delay ms, for use in async functions.
+
+#### Parameters
+
+*   `delay` &#x20;
+
+## extractAttributes
+
+Takes in a node attributes map and returns an object with camelCased
+properties and values
+
+#### Parameters
+
+*   `nodeMap` &#x20;
+
+Returns **{}**&#x20;
+
+## getStyleElementsFromReactWebComponentStyleLoader
+
+An optional library which is conditionally added
+
+Returns **\[]**&#x20;
+
+## setConfig
+
+method exposed to the wrapped component via prop that allows setting
+the "config" state variable inside the wrapper (not the component
+itself). This config is retrieved by the portal for inclusion in the
+embedding instructions.
+
+#### Parameters
+
+*   `config` &#x20;
+
+## setOnDisconnect
+
+function used by `Component` to register a onDisconnect handler
+
+#### Parameters
+
+*   `fn` &#x20;
+
+## webComponentAttributeChanged
+
+Note this relies on the changes made in
+github:amay0048/react-web-component#780950800e2962f45f0f029be618bb8b84610c89
+that we used in our copy.
+TODO: move this into our copy, i.e., do it internally to react-web-component
+and update props.
+
+#### Parameters
+
+*   `name` &#x20;
+*   `oldValue` &#x20;
+*   `newValue` &#x20;
+
+[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[6]: https://github.com/chfritz/transitive/issues/85
+
+[7]: https://www.npmjs.com/package/loglevel

package/docs_header.md

@@ -0,0 +1,49 @@
+# Web (browser)
+
+These classes and functions are available via the `@transitive-sdk/utils-web` npm package and are for use in the browser or other browser based front-ends.
+
+### Example
+
+In this example we create a new web-component (custom element) from a React component using mqttSync to subscribe to some data and re-rendering it in real-time whenever it changes.
+
+```js
+import React, { useEffect } from 'react';
+
+import { createWebComponent, useTransitive, getLogger }
+  from '@transitive-sdk/utils-web';
+
+const log = getLogger('my-new-capability');
+log.setLevel('debug');
+
+// Get the name of the package we are part of. TR_PKG_NAME is set by esbuild.
+const [scope, capabilityName] = TR_PKG_NAME.split('/');
+
+const Device = ({jwt, id, host, ssl}) => {
+
+  const { mqttSync, data, StatusComponent, prefixVersion } =
+    useTransitive({ jwt, id, host, ssl,
+      capability: TR_PKG_NAME,
+      versionNS: TR_PKG_VERSION_NS
+    });
+
+  // once mqttSync is connected, subscribe to some topics
+  useEffect(() => {
+      if (!mqttSync) return;
+      mqttSync.subscribe(`${prefixVersion}/device`);
+      mqttSync.subscribe(`${prefixVersion}/cloud`);
+    }, [mqttSync]);
+
+  log.debug({prefixVersion, data, TR_PKG_NAME, TR_PKG_VERSION, TR_PKG_VERSION_NS});
+
+  return <div>
+    <StatusComponent />
+    <pre>
+      {/* Render the data. This updates automatically whenever data changes. */}
+      {JSON.stringify(data, true, 2)}
+    </pre>
+  </div>;
+};
+
+createWebComponent(Device, `${capabilityName}-device`, ['jwt']);
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitive-sdk/utils-web",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Web utils for the Transitive framework",
   "homepage": "https://transitiverobotics.com",
   "author": {
@@ -18,7 +18,8 @@
   "scripts": {
     "test": "webpack serve -c webpack-test.config.js",
     "build-test": "webpack -c webpack-test.config.js",
-    "prepare": "webpack --no-watch --mode=production"
+    "prepare": "webpack --no-watch --mode=production",
+    "prepack": "cat ../docs.js | node --input-type=module"
   },
   "dependencies": {
     "@babel/runtime": "^7.16.7",

package/react-web-component/index.js

@@ -16,7 +16,7 @@ const lifeCycleHooks = {
 };
 
 module.exports = {
-  /**
+  /*
    * @param {JSX.Element} wrapper: the wrapper component class to be instantiated and wrapped
    * @param {string} tagName - The name of the web component. Has to be minus "-" delimited.
    * @param {boolean} useShadowDom - If the value is set to "true" the web component will use the `shadowDom`. The default value is true.
@@ -90,13 +90,13 @@ module.exports = {
         this.callLifeCycleHook('adoptedCallback', [oldDocument, newDocument]);
       }
 
-      /** call a function defined in the component, either as a class method, or
+      /* call a function defined in the component, either as a class method, or
       * via useImperativeHandle */
       call(functionName, args) {
         return compRef?.current?.[functionName]?.call(compRef?.current, args);
       }
 
-      /** predefined function to retrieve the pre-defined config object of the
+      /* predefined function to retrieve the pre-defined config object of the
        * state, populated via the pre-defined `setConfig` method given as prop
        * to the wrapped component. */
       getConfig() {