arkonatechnologies/vscript repository overview

⁠vscript

⁠What is this?

vscript provides a node.js API to the WebSocket interface of the V__matrix. There currently is an official release (v0.0.151) that is widely in use and will remain compatible with the WebSocket API for the foreseeable future.

The version of vscript contained within this Docker image is similarly structured, but backwards-incompatible and not yet supported by the Web UI's recording functionality. It is, however, robust enough for production use, and offers major correctness and productivity improvements over the previous version. Early adopters are thus encouraged to use this image as their starting point for new developments.

⁠How do I set it up?

To run this image, you will need a Linux machine, or possibly a Windows machine with WSL (we haven't tested this though we certainly welcome your feedback if you do). Install Docker, or some functionally equivalent alternative such as podman, then navigate to the directory you wish to use as your working directory and execute the following command:

docker run -v $PWD:/local-fs -it arkonatechnologies/vscript:beta-0.4.5

An interactive shell should pop up that allows you to execute TypeScript files using ts-node, or JavaScript files using nodejs, or to initialize a vscript working directory using init-workspace. Try that now by executing

init-workspace

After execution has completed, your local directory (i.e., the directory you linked to /local-fs during the first step) should contain a node_modules directory with vscript, a development snapshot of vapi and TypeScript 3.8. It should also contain a tsconfig.json as well as a file named template.ts. Opening that file with any TypeScript-aware editor, you should find that your editor provides full autocompletion and allows you to interactively inspect the state model represented by the template's VMatrix object.

So far, this has been tested with Emacs (using lsp-mode) and Visual Studio Code (though you should make sure that VSC uses version 3.8 of the TypeScript SDK; the version that came bundled with your copy of Visual Studio Code might still be 3.7.3 or older).

⁠How am I supposed to use this?

The functionality that used to be available within the old vscript module now revolves around the VSocket object and the subtree representations that can be obtained from it using various selectors such as find or table. For example, the following snippet will open a VSocket to a V__matrix at 172.16.1.23, query its PTP agents table, and create an agent at index 0 if it doesn't already exist (assuming that 172.16.1.23 runs software version v1.10 or higher, otherwise p_t_p_flows will have to be renamed to p_t_p):

import { VSocket } from "vscript";

async function main() {
  const vsocket = await VSocket.open({ ip: "172.16.1.23", towel: "test" });
  const agents_table = vsocket.root.named_table("p_t_p_flows.agents");
  for (const agent of await agents_table.rows()) {
    const index = agent.index;
    const state = await agent.read({ kw: "state" });
    console.log(
      `There is an agent at index ${index}. It is currently in state '${state}'`
    );
  }
  const agent_0 = await agents_table.create_row({
    index: 0,
    allow_reuse_row: true
  });
  console.log(
    `Obtained agent #0, state is ${await agent_0.read({ kw: "state" })}`
  );
  await vsocket.close();
}

main();

Like the previous API, the vscript API is fairly generic in that most operations require you to provide kwl and kw identifiers. The upside of this approach is that scripts can flexibly adapt to the machine's version-specific data schema (this is what we use in our vtelemetry⁠ image); the downside is that many sorts of mistakes---such as typos or trying to set an enum keyword to a nonexistent enumerator---will often go unnoticed until the script is executed.

On top of the weakly typed vscript layer, we now provide a strictly typed schema overlay (called vapi). Starting with software release v1.11, the vapi module will be autogenerated for every software release and shipped with the V__matrix operating software. Until then, a development snapshot of the vapi module will be distributed with the vscript image, and will be installed by the init-workspace script.

Using the vapi module, our example script might look as follows:

import { VMatrix } from "vapi";

async function main() {
  const vmatrix = await VMatrix.open({ ip: "172.16.1.23", towel: "test" });
  const agents_table = vmatrix.p_t_p_flows.agents;
  for (const agent of await agents_table.rows()) {
    const index = agent.index;
    const state = await agent.state.read();
    console.log(
      `There is an agent at index ${index}. It is currently in state '${state}'`
    );
  }
  const agent_0 = await agents_table.create_row({
    index: 0,
    allow_reuse_row: true
  });
  console.log(`Obtained agent #0, state is ${await agent_0.state.read()}`);
  await vmatrix.close();
}

main();

The advantages of this approach will quickly become apparent in a TypeScript-aware editor, as TypeScript will not allow you to misspell p_t_p_flows or agents, nor will it allow you to read a keyword named stat or stote. It will also know that the variable state can only hold one of the 5 fixed strings "Inactive", "Listening", "Passive", "Slave" or "Master" and make sure that this invariant is respected in all further operations.

Once you have come up with a script of your own that you wish to try out in practice, you may execute it by going back to the container shell and calling ts-node myfile.ts (this will transparently compile the TypeScript file myfile.ts and execute it, unless compilation fails). Or you may want to precompile myfile.ts using the TypeScript compiler tsc and then run it using nodejs myfile.js. You may also choose to use the container for workspace initialization only and execute all your scripts using a regular nodejs installation on your host system.

You may also forego the compile-time checks (and better autocompletion) that TypeScript provides and continue writing regular JavaScript, though in our opinion TypeScript is a much better choice for all but the most trivial projects.

⁠Where is the documentation?

Unfortunately, it doesn't exist yet. We will provide example scripts in due time; until then, we encourage you to try out the excellent autocompletion facilities offered by any TypeScript-aware editor. Should you find our API to be a lot less self-explanatory than we believe it to be, we would appreciate your feedback on confusing nomenclature, inconsistencies or any other pain points.