unetjs 5.0.1 → 6.0.0

package/README.md

@@ -7,13 +7,13 @@ The library contains helper methods, commonly used [Messages](https://fjage.read
 ## Installation
 
 ```sh
-$ npm install unetjs
+$ pnpm 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](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/unetsockets/tree/master/js/docs](https://github.com/org-arl/unetsockets/tree/master/js/docs)
 
 ## Versions
 
@@ -65,47 +65,15 @@ The UnetSocket API is a high-level API exposed by UnetStack to allow users to co
 
 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
+Socket-level transmission metadata can be configured once and applied to subsequent sends using methods such as `setTTL()`, `setPriority()`, `setReliability()`, `setRoute()`, `setMimeType()`, `setRemoteRecipient()`, `setMailbox()`, and `setMessageClass()`. A specific service provider may also be forced with `setServiceProvider()`.
 
-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.
+`send()` now supports three send modes via `setSendMode()`:
 
-> This behaviour used to be enabled by default in unetsocket.js v2.0.0 till v2.0.10. From v3.0.0 onwards, this behaviour is **disabled** by default but a available as an option.
+- `UnetSocket.NON_BLOCKING`: returns `true` once the request has been accepted for sending.
+- `UnetSocket.SEMI_BLOCKING` (default): waits for an `AGREE`, and if reliability is enabled, also waits for a delivery/success notification.
+- `UnetSocket.BLOCKING`: waits for an `AGREE` followed by a transmission, delivery, or failure notification.
 
-You can use the `CachingGateway` class instead of the `Gateway` class to enable this behaviour.
-
-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.
-
-> unetsockets.js v5.0.0 and beyond the UnetSocket API was changed to remove the optional parameter `caching` from the `agentForService`, `agentsForService` and `agent` methods. This was done to simplify the API and avoid confusion. The caching behaviour is now enabled by using a different class, `CachingGateway` instead of `Gateway`. The `CachingGateway` class extends the `Gateway` class and adds the caching behaviour.
-
-```js
-import {UnetMessages, CachingGateway} from 'unetjs'
-let gw = new CachingGateway({...});
-let nodeinfo = await gw.agentForService(Services.NODE_INFO); // returns a CachingAgentID
-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, CachingGateway} from 'unetjs'
-let gw = new CachingGateway({...});
-let nodeinfo = await gw.agentForService(Services.NODE_INFO); // returns a CachingAgentID
-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.
-```
+Passing a `DatagramReq` directly to `send()` is still supported for compatibility, but it is deprecated. Prefer setting socket defaults and calling `send(data, to, protocol)` instead.
 
 ### Importing/Modules