npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

unetjs

v3.1.5

Published

JavaScript Helper Library for UnetStack

Downloads

11

Readme

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 and Services in Unet, and an implementation of the UnetSocket API, which is a high-level Socket-like API for communicating over an Unet.

Installation

$ 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

Usage

Pre-defined Messages and Services

This library provides 2 major components, the pre-defined Message and Service dictionaries, and the UnetSocket implementation.

The pre-defined Message and Service dictionaries are a convenient way to define commonly used Messages and Services in your code.

// Instead of writing this,

import {MessageClass, Gateway} from 'unetjs'
let gw = new Gateway({...});
const DatagramReq = MessageClass('org.arl.unet.DatagramReq');
let req = new DatagramReq();
...
req.recipient = await gw.agentForService('org.arl.unet.Services.DATAGRAM')
let rsp = await gw.send(req);
...

// you can write this
import {UnetMessages, Gateway} from 'unetjs'
let gw = new Gateway({...});
let req = new UnetMessages.DatagramReq();
...
req.recipient = await gw.agentForService(Services.DATAGRAM)
let rsp = await gw.send(req);

The pre-defined Message also follows the class hierarchy that is implemented in UnetStack, so syntax like instanceof will yield the same results as in UnetStack.

// RxFrameNtf is a subclass of DatagramNtf
let rxNtf = new UnetMessages.RxFrameNtf();

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

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 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.

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.

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.

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.
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.

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 directory.

At runtime, fjage.js (the underlying library used to connect to an Unet node) will check its context (browser or Node.js) and accordingly use the appropriate Connector (WebSocket or TCP) for connecting to the Unet node.

Here are some code snippets of how you can start using unet.js in the various module systems.

CommonJS

const { Performative, AgentID, Message, Gateway, MessageClass } = require('unetjs');
const shell = new AgentID('shell');
const gw = new Gateway({
    hostname: 'localhost',
    port : '5081',
});

ECMAScript modules

import { Performative, AgentID, Message, Gateway, MessageClass } from 'unetjs'
const shell = new AgentID('shell');
const gw = new Gateway({
    hostname: 'localhost',
    port : '5081',
});

UMD

<script src="unet.min.js"></script>
<script>
    const shell = new fjage.AgentID('shell');
    const gw = new fjage.Gateway({
        hostname: 'localhost',
        port : '8080',
        pathname: '/ws/'
    });
</script>