unetjs 1.1.0 → 2.0.0

package/README.md

@@ -1,21 +1,19 @@
-JavaScript Helper Library for UnetStack
-==========================
+# JavaScript Helper Library for UnetStack
 
 The JavaScript Helper Library for UnetStack is a JavaScript library that enables controlling of a UnetStack Node from JavaScript, both Browser-based (over WebSockets) and Node.JS (TCP).
 
 The library contains helper methods, commonly used [Messages](https://fjage.readthedocs.io/en/latest/messages.html) and [Services](https://fjage.readthedocs.io/en/latest/services.html) in Unet, and an implementation of the [UnetSocket API](https://unetstack.net/handbook/unet-handbook_unetsocket_api.html), which is a high-level [Socket-like](https://en.wikipedia.org/wiki/Network_socket) API for communicating over an Unet.
 
-
 ## Installation
 
 ```sh
 $ npm install unetjs
+...
 ```
 
 ## Documentation
 
-The API documentation of the latest version of unet.js is published at https://github.com/org-arl/unet-contrib/tree/master/unetsocket/js/docs
-
+The API documentation of the latest version of unet.js is published at [https://github.com/org-arl/unet-contrib/tree/master/unetsocket/js/docs](https://github.com/org-arl/unet-contrib/tree/master/unetsocket/js/docs)
 
 ## Usage
 
@@ -57,10 +55,46 @@ rxNtf instanceof UnetMessages.DatagramReq; // returns true;
 
 ### UnetSocket
 
-The UnetSocket API is a high-level API exposed by UnetStack to allow users to communicate over an Unet. It is a socket-style API, which allows a user to send [Datagrams]() to specific nodes, or as a broadcast, and similarly listen to Datagrams from specific nodes, etc. A detailed explanation of UnetSocket API can be found in the [Unet Handbook](https://unetstack.net/handbook/unet-handbook_unetsocket_api.html)
+The UnetSocket API is a high-level API exposed by UnetStack to allow users to communicate over an Unet. It is a socket-style API, which allows a user to send [Datagrams](https://unetstack.net/handbook/unet-handbook_datagram_service.html) to specific nodes, or as a broadcast, and similarly listen to Datagrams from specific nodes, etc. A detailed explanation of UnetSocket API can be found in the [Unet Handbook](https://unetstack.net/handbook/unet-handbook_unetsocket_api.html)
 
 The JavaScript version of the UnetSocket API allows a user to connect to a node in an Unet from a browser/Node.JS-based application and communicate with other nodes in the Unet. The Datagrams received on those nodes could be consumed by other instances of the UnetSocket, either directly on the node, or on a remote [Gateway](https://fjage.readthedocs.io/en/latest/remote.html#interacting-with-agents-using-a-gateway) connected to that node.
 
+### Caching Parameter Responses
+
+The UnetSocket API allows a user to cache responses to parameter requests. This is useful in a scenario where the parameters aren't changing very often, and the user wants to reduce the round trip time for parameter requests.
+
+UnetSocket API acheives this using two mechanism, firstly, it can request ALL of the parameters from an Agent instead of just one, and then cache the responses. This is called the `greedy` mode. The greedy mode is enabled by default but can be disabled by setting the `greedy` property to `false` in the `CachingAgentID` constructor.
+
+Secondly, the UnetSocket API caches the responses to parameter requests for a limited time. If the user requests the same parameter again, the UnetSocket will return the cached response. The time to cache a response is set by the `cacheTime` property in the `CachingAgentID` constructor.
+
+```js
+import {UnetMessages, Gateway} from 'unetjs'
+let gw = new Gateway({...});
+let nodeinfo = await gw.agentForService(Services.NODE_INFO); // returns a CachingAgentID by default.
+let cLoc = nodeinfo.get('location'); // this will request all the Parameters from the Agent, and cache the responses.
+...
+cLoc = nodeinfo.get('location', maxage=5000); // this will return the cached response if it was called within 5000ms of the original request.
+...
+cLoc = nodeinfo.get('location', maxage=0); // this will force the Gateway to request the parameter again.
+```
+
+```js
+import {UnetMessages, Gateway} from 'unetjs'
+let gw = new Gateway({...});
+let nodeinfo = await gw.agentForService(Services.NODE_INFO); // returns a CachingAgentID by default.
+let nonCachingNodeInfo = await gw.agentForService(Services.NODE_INFO, false); // returns an AgentID without caching (original fjage.js functionality).
+let cLoc = nonCachingNodeInfo.get('location'); // this will request the `location` parameter from the Agent.
+...
+cLoc = nonCachingNodeInfo.get('location'); // this will request the `location` parameter from the Agent again.
+
+let nonGreedyNodeInfo = await gw.agentForService(Services.NODE_INFO, true, false); // returns an CachingAgentID that's not greedy.
+let cLoc = nonGreedyNodeInfo.get('location'); // this will request the `location` parameter from the Agent.
+...
+cLoc = nonCachingNodeInfo.get('location'); // this will request the `location` parameter from the cache.
+...
+let cLoc = nonGreedyNodeInfo.get('heading'); // this will request the `heading` parameter from the Agent.
+```
+
 ### Importing/Modules
 
 A distribution-ready bundle is available for types of module systems commonly used in the JS world. Examples of how to use it for the different module systems are available in the [examples](/examples) directory.
@@ -92,6 +126,7 @@ const gw = new Gateway({
 ```
 
 ### [UMD](dist)
+
 ```js
 <script src="unet.min.js"></script>
 <script>
@@ -102,4 +137,4 @@ const gw = new Gateway({
         pathname: '/ws/'
     });
 </script>
-```
+```

package/dist/cjs/unet.cjs

@@ -1,4 +1,4 @@
-/* unet.js v1.1.0 2022-02-19T07:01:46.580Z */
+/* unet.js v2.0.0 2022-05-18T02:36:38.084Z */
 
 'use strict';
 
@@ -1417,6 +1417,267 @@ let UnetMessages = {
   'SaveStateReq'           : MessageClass('org.arl.unet.state.SaveStateReq')
 };
 
+/**
+  * Convert coordinates from a local coordinates to GPS coordinate
+  * @param {Array} origin - Local coordinate system's origin as `[latitude, longitude]`
+  * @param {Number} x - X coordinate of the local coordinate to be converted
+  * @param {Number} y - Y coordinate of the local coordinate to be converted
+  * @returns {Array} - GPS coordinates (in decimal degrees) as `[latitude, longitude]`
+  */
+
+function toGps(origin, x, y) {
+  let coords = [] ;
+  let [xScale,yScale] = _initConv(origin[0]);
+  coords[1] = x/xScale + origin[1];
+  coords[0] = y/yScale + origin[0];
+  return coords;
+}
+
+/**
+  * Convert coordinates from a GPS coordinates to local coordinate
+  * @param {Array} origin - Local coordinate system's origin as `[latitude, longitude]`
+  * @param {Number} lat - Latitude of the GPS coordinate to be converted
+  * @param {Number} lon - Longitude of the GPS coordinate to be converted
+  * @returns {Array} - GPS coordinates (in decimal degrees) as `[latitude, longitude]`
+  */
+function toLocal(origin, lat, lon) {
+  let pos = [];
+  let [xScale,yScale] = _initConv(origin[0]);
+  pos[0] = (lon-origin[1]) * xScale;
+  pos[1] = (lat-origin[0]) * yScale;
+  return pos;
+}
+
+function _initConv(lat){
+  let rlat = lat * Math.PI/180;
+  let yScale = 111132.92 - 559.82*Math.cos(2*rlat) + 1.175*Math.cos(4*rlat) - 0.0023*Math.cos(6*rlat);
+  let xScale = 111412.84*Math.cos(rlat) - 93.5*Math.cos(3*rlat) + 0.118*Math.cos(5*rlat);
+  return [xScale, yScale];
+}
+
+/**
+ * A message which requests the transmission of the datagram from the Unet
+ *
+ * @typedef {Message} DatagramReq
+ * @property {number[]} data - data as an Array of bytes
+ * @property {number} from - from/source node address
+ * @property {number} to - to/destination node address
+ * @property {number} protocol - protocol number to be used to send this Datagram
+ * @property {boolean} reliability - true if Datagram should be reliable, false if unreliable
+ * @property {number} ttl - time-to-live for the datagram. Time-to-live is advisory, and an agent may choose it ignore it
+ */
+
+/**
+ * Notification of received datagram message received by the Unet node.
+ *
+ * @typedef {Message} DatagramNtf
+ * @property {number[]} data - data as an Array of bytes
+ * @property {number} from - from/source node address
+ * @property {number} to - to/destination node address
+ * @property {number} protocol - protocol number to be used to send this Datagram
+ * @property {number} ttl - time-to-live for the datagram. Time-to-live is advisory, and an agent may choose it ignore it
+ */
+
+/**
+ * An identifier for an agent or a topic.
+ * @external AgentID
+ * @see {@link https://org-arl.github.io/fjage/jsdoc/|fjåge.js Documentation}
+ */
+
+/**
+ * Services supported by fjage agents.
+ * @external Services
+ * @see {@link https://org-arl.github.io/fjage/jsdoc/|fjåge.js Documentation}
+ */
+
+/**
+ *  An action represented by a message.
+ * @external Performative
+ * @see {@link https://org-arl.github.io/fjage/jsdoc/|fjåge.js Documentation}
+ */
+
+/**
+ * Function to creates a unqualified message class based on a fully qualified name.
+ * @external MessageClass
+ * @see {@link https://org-arl.github.io/fjage/jsdoc/|fjåge.js Documentation}
+ */
+
+/**
+ * A caching CachingAgentID which caches Agent parameters locally.
+ *
+ * @class
+ * @extends AgentID
+ * @param {string | AgentID} name - name of the agent or an AgentID to copy
+ * @param {boolean} topic - name of topic
+ * @param {Gateway} owner - Gateway owner for this AgentID
+ * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
+ *
+*/
+class CachingAgentID extends AgentID {
+
+  constructor(name, topic, owner, greedy=true) {
+    if (name instanceof AgentID) {
+      super(name.getName(), name.topic, name.owner);
+    } else {
+      super(name, topic, owner);
+    }
+    this.greedy = greedy;
+    this.cache = {};
+  }
+
+  /**
+   * Sets parameter(s) on the Agent referred to by this AgentID, and caches the parameter(s).
+   *
+   * @param {(string|string[])} params - parameters name(s) to be set
+   * @param {(Object|Object[])} values - parameters value(s) to be set
+   * @param {number} [index=-1] - index of parameter(s) to be set
+   * @param {number} [timeout=5000] - timeout for the response
+   * @returns {Promise<(Object|Object[])>} - a promise which returns the new value(s) of the parameters
+   */
+  async set(params, values, index=-1, timeout=5000) {
+    let s = await super.set(params, values, index, timeout);
+    this._updateCache(params, s, index);
+  }
+
+  /**
+   * Gets parameter(s) on the Agent referred to by this AgentID, getting them from the cache if possible.
+   *
+   * @param {(string|string[])} params - parameters name(s) to be fetched
+   * @param {number} [index=-1] - index of parameter(s) to be fetched
+   * @param {number} [timeout=5000] - timeout for the response
+   * @param {number} [maxage=5000] - maximum age of the cached result to retreive
+   * @returns {Promise<(Object|Object[])>} - a promise which returns the value(s) of the parameters
+   */
+  async get(params, index=-1, timeout=5000, maxage=5000) {
+    if (this._isCached(params, index, maxage)) return this._getCache(params, index);
+    if (this.greedy && !(Array.isArray(params) && params.includes('name')) && params != 'name') {
+      let rsp = await super.get(null, index, timeout);
+      this._updateCache(null, rsp, index);
+      if (Array.isArray(params)) {
+        return params.map(p => {
+          let f = Object.keys(rsp).find(rv => this._toNamed(rv) === p);
+          return f ? rsp[f] : null;
+        });
+      } else {
+        let f = Object.keys(rsp).find(rv => this._toNamed(rv) === params);
+        return f ? rsp[f] : null;
+      }
+    } else {
+      let r = await super.get(params, index, timeout);
+      this._updateCache(params, r, index);
+      return r;
+    }
+  }
+
+  _updateCache(params, vals, index) {
+    if (vals == null || Array.isArray(vals) && vals.every(v => v == null)) return;
+    if (params == null) {
+      params = Object.keys(vals);
+      vals = Object.values(vals);
+    } else if (!Array.isArray(params)) params = [params];
+    if (!Array.isArray(vals)) vals = [vals];
+    params = params.map(this._toNamed);
+    if (this.cache[index.toString()] === undefined) this.cache[index.toString()] = {};
+    let c = this.cache[index.toString()];
+    for (let i = 0; i < params.length; i++) {
+      if (c[params[i]] === undefined) c[params[i]] = {};
+      c[params[i]].value = vals[i];
+      c[params[i]].ctime = Date.now();
+    }
+  }
+
+  _isCached(params, index, maxage) {
+    if (maxage <= 0) return false;
+    if (params == null) return false;
+    let c = this.cache[index.toString()];
+    if (!c) {
+      return false;
+    }
+    if (!Array.isArray(params)) params = [params];
+    const rv = params.every(p => {
+      p = this._toNamed(p);
+      return (p in c) && (Date.now() - c[p].ctime <= maxage);
+    });
+    return rv;
+  }
+
+  _getCache(params, index) {
+    let c = this.cache[index.toString()];
+    if (!c) return null;
+    if (!Array.isArray(params)){
+      if (params in c) return c[params].value;
+      return null;
+    }else {
+      return params.map(p => p in c ? c[p].value : null);
+    }
+  }
+
+  _toNamed(param) {
+    const idx = param.lastIndexOf('.');
+    if (idx < 0) return param;
+    else return param.slice(idx+1);
+  }
+
+}
+
+
+class CachingGateway extends Gateway{
+
+  /**
+   * Get an AgentID for a given agent name.
+   *
+   * @param {string} name - name of agent
+   * @param {Boolean} [caching=true] - if the AgentID should cache parameters
+   * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
+   * @returns {AgentID|CachingAgentID} - AgentID for the given name
+   */
+  agent(name, caching=true, greedy=true) {
+    const aid = super.agent(name);
+    return caching ? new CachingAgentID(aid, null, null, greedy) : aid;
+  }
+
+  /**
+   * Returns an object representing the named topic.
+   *
+   * @param {string|AgentID} topic - name of the topic or AgentID
+   * @param {string} topic2 - name of the topic if the topic param is an AgentID
+   * @param {Boolean} [caching=true] - if the AgentID should cache parameters
+   * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
+   * @returns {AgentID|CachingAgentID} - object representing the topic
+   */
+  topic(topic, topic2, caching=true, greedy=true) {
+    const aid = super.topic(topic, topic2);
+    return caching ? new CachingAgentID(aid, null, null, greedy) : aid;
+  }
+
+  /**
+   * Finds an agent that provides a named service. If multiple agents are registered
+   * to provide a given service, any of the agents' id may be returned.
+   *
+   * @param {string} service - the named service of interest
+   * @param {Boolean} [caching=true] - if the AgentID should cache parameters
+   * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
+   * @returns {Promise<?AgentID|CachingAgentID>} - a promise which returns an agent id for an agent that provides the service when resolved
+   */
+  async agentForService(service, caching=true, greedy=true) {
+    const aid = await super.agentForService(service);
+    return caching ? new CachingAgentID(aid, null, null, greedy) : aid;
+  }
+
+  /**
+   * Finds all agents that provides a named service.
+   *
+   * @param {string} service - the named service of interest
+   * @param {Boolean} [caching=true] - if the AgentID should cache parameters
+   * @param {Boolean} [greedy=true] - greedily fetches and caches all parameters if this Agent
+   * @returns {Promise<?AgentID|CachingAgentID[]>} - a promise which returns an array of all agent ids that provides the service when resolved
+   */
+  async agentsForService(service, caching=true, greedy=true) {
+    const aids = await super.agentsForService(service);
+    return caching ? aids.map(a => new CachingAgentID(a, null, null, greedy)) : aids;
+  }
+}
+
 const REQUEST_TIMEOUT = 1000;
 
 const AddressResolutionReq = UnetMessages.AddressResolutionReq;
@@ -1444,7 +1705,7 @@ class UnetSocket {
 
   constructor(hostname, port, path='') {
     return (async () => {
-      this.gw = new Gateway({
+      this.gw = new CachingGateway({
         hostname : hostname,
         port : port,
         path : path
@@ -1655,31 +1916,34 @@ class UnetSocket {
   /**
    * Gets an AgentID providing a specified service for low-level access to UnetStack
    * @param {string} svc - the named service of interest
+   * @param {Boolean} caching - if the AgentID should cache parameters
    * @returns {Promise<?AgentID>} - a promise which returns an {@link AgentID} that provides the service when resolved
    */
-  async agentForService(svc) {
+  async agentForService(svc, caching=true) {
     if (this.gw == null) return null;
-    return await this.gw.agentForService(svc);
+    return await this.gw.agentForService(svc, caching);
   }
 
   /**
    *
    * @param {string} svc - the named service of interest
+   * @param {Boolean} caching - if the AgentID should cache parameters
    * @returns {Promise<AgentID[]>} - a promise which returns an array of {@link AgentID|AgentIDs} that provides the service when resolved
    */
-  async agentsForService(svc) {
+  async agentsForService(svc, caching=true) {
     if (this.gw == null) return null;
-    return await this.gw.agentsForService(svc);
+    return await this.gw.agentsForService(svc, caching``);
   }
 
   /**
    * Gets a named AgentID for low-level access to UnetStack.
    * @param {string} name - name of agent
+   * @param {Boolean} caching - if the AgentID should cache parameters
    * @returns {AgentID} - AgentID for the given name
    */
-  agent(name) {
+  agent(name, caching=true) {
     if (this.gw == null) return null;
-    return this.gw.agent(name);
+    return this.gw.agent(name, caching);
   }
 
   /**
@@ -1700,7 +1964,8 @@ class UnetSocket {
 }
 
 exports.AgentID = AgentID;
-exports.Gateway = Gateway;
+exports.CachingAgentID = CachingAgentID;
+exports.Gateway = CachingGateway;
 exports.Message = Message;
 exports.MessageClass = MessageClass;
 exports.Performative = Performative;
@@ -1708,3 +1973,5 @@ exports.Protocol = Protocol;
 exports.Services = Services;
 exports.UnetMessages = UnetMessages;
 exports.UnetSocket = UnetSocket;
+exports.toGps = toGps;
+exports.toLocal = toLocal;