@transitive-sdk/utils-web 0.7.5 → 0.7.6

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.
+
+[API Documentation](./docs/index.md)

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,708 @@
+<!-- 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.
+
+#### 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
+
+##### 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 `[]`)
+
+### subscribe
+
+add a callback for change events
+
+##### Parameters
+
+*   `callback` &#x20;
+
+### subscribePath
+
+Subscribe to a specific topic only. Unlike in `subscribe`, here callback
+only receives the value.
+
+##### 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
+
+##### 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
+
+*   `$0` **[Object][1]**&#x20;
+
+    *   `$0.mqttClient` &#x20;
+    *   `$0.onChange` &#x20;
+    *   `$0.ignoreRetain` &#x20;
+    *   `$0.migrate` &#x20;
+    *   `$0.onReady` &#x20;
+    *   `$0.sliceTopic` &#x20;
+
+### 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][2].
+
+##### 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;
+
+### heartbeatWaitersOnce
+
+List of callbacks waiting for next heartbeat, gets purged with each
+heartbeat
+
+### publishedMessages
+
+Store messages retained on mqtt so we can publish what is necessary to
+achieve the "should-be" state. Note that we cannot use a structured document
+for storing these publishedMessages since we need to be able to store separate
+values at non-leaf nodes in the object (just like mqtt, where you can have
+/a/b = 1 and /a/b/c = 1 at the same time). Note: not used in atomic mode.
+
+### publishQueue
+
+The order in which we send retained messages matters, which is why we use
+a queue for sending things. Note that we here use the property of Map that it
+remembers insertion order of keys.
+
+### subscribedPaths
+
+Directory of paths we've subscribed to in this class; this matters
+because the same mqtt client may have subscriptions to paths that we don't
+care to store (sync).
+
+## clone
+
+clone a mqtt payload, if necessary
+
+#### Parameters
+
+*   `payload` &#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;
+
+## ensureHashSuffix
+
+return new string that ends in /# for sure
+
+#### Parameters
+
+*   `topic` &#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 logger; call with a name, e.g., `module.id`
+
+## 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`)
+
+## oneDown
+
+called each time one item is done
+
+## 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;
+
+## resolveDoubleSlashes
+
+given a path, replace any double slashes, '//', with single ones
+
+#### Parameters
+
+*   `path` &#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][3]** 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 object where all sub-objects are
+replaced by topic-values, e.g.:
+{a: {b: 1, c: 2}, d: 3}   ->   {'/a/b': 1, '/a/c': 2, d: 3}
+Note: not idempotent!
+{'/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, usable in async functions
+
+#### Parameters
+
+*   `delay` &#x20;
+
+## create
+
+#### Parameters
+
+*   `wrapper` **JSX.Element** : the wrapper component class to be instantiated and wrapped
+*   `tagName` **[string][4]** The name of the web component. Has to be minus "-" delimited.
+*   `useShadowDom` **[boolean][5]** If the value is set to "true" the web component will use the `shadowDom`. The default value is true. (optional, default `true`)
+*   `observedAttributes` **[Array][3]<[string][4]>** The observed attributes of the web component (optional, default `[]`)
+*   `compRef`   (optional, default `undefined`)
+
+## 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;
+
+## setAll
+
+convenience function to set all loggers to the given level
+
+#### Parameters
+
+*   `level` &#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://github.com/chfritz/transitive/issues/85
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitive-sdk/utils-web",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "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",