Overview

Asyngular (pronounced “A-singular”) is a framework for writing scalable real-time applications which leverage the latest async/await features of JavaScript (works well with async generators). It is a fork of SocketCluster; a (5+ years) battle-tested framework used in production by hundreds of companies. See this article for a list of improvements which Asyngular introduces over SocketCluster.

The Asyngular GitHub repo is here: https://github.com/SocketCluster/asyngular

Requirements

Optional dependency (for containerization):

Installing

The easiest way to get started with Asyngular is to install the CLI toolkit from npm:

// Or with sudonpm install -g asyngular

then run this in your console/terminal:

asyngular create myapp

Running the server

Once it’s ready, go to your new myapp/ directory and launch with:

node server

You can interact with your app by opening http://localhost:8000/ in your browser.

If you have docker installed, you can alternatively run your Asyngular app inside a container on your local machine using the following shortcut command (run from inside your myapp/ directory):

asyngular run

Stop and remove container with:

asyngular stop

Use asyngular --help for a list of all docker shortcut commands.

[Server] Listening for inbound socket connections

Inside server.js, find the for-await-of loop which is handling inbound connections. It should look like this:

[Server] Listening for inbound RPCs and messages

You can add nested for-await-of loops to handle different kinds of socket messages/RPCs within this main connection loop. For example:

!! Note that you can also register socket.procedure(procedureName) and socket.receiver(receiverName) handlers on a client socket using the same syntax.

[Client] Connecting to the server

Note that you can pass an optional object to the asyngularClient.create function to modify socket options. This function supports the same options as the create function on the socketcluster-client. See https://socketcluster.io/#!/docs/api-socketcluster-client for more details.

[Client] Invoking RPCs

!! Note that you should always add a try-catch block around the socket.invoke call to capture any async errors:

!! Note that you can also invoke procedures which are registered on the client socket from the server socket using the same syntax.

[Client] transmitting messages

!! Note that you can also transmit to receivers which are registered on the client socket from the server socket using the same syntax. Transmit can never fail, so you don’t need a try-catch block.

[Client] Subscribing to a channel and watching for messages

[Client] Publishing to a channel

!! Note that you can also publish from an AGChannel object; in this case, you omit the first parameter. For example:

let fooChannel = socket.channel('foo');fooChannel.transmitPublish('This is some data');

[Server] Publishing to a channel

[Server] Registering middleware functions

Asyngular supports 4 different middleware lines which allow you to block, delay or preprocess specific actions. Middleware functions in Asyngular work differently from those in SocketCluster. In Asyngular, a middleware function can handle multiple different types of actions (represented by an AGAction instance which has a type property).

This is how to setup a middleware (this example shows the MIDDLEWARE_INBOUND middleware handling TRANSMIT and INVOKE actions):

!! Note that in Asyngular, you can only have one middleware function for each middleware line.

The following middleware lines and actions are supported:

Each action object (AGAction) which is streamed through the middleware has different properties depending on its type property. These are the properties supported by different action types:

^ In all of the above cases, type is a string, channel is a string, request is a Node.js [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) object, socket is an AGServerSocket object, receiver is a string, procedure is a string, signedAuthToken is a string (or null), authToken is an object (or null) and data can be of any type (depending on what is provided by the client).

!! Note that middlewares are applied on a per-socket basis. So delaying an action in a middleware will only create back pressure for a single socket and not affect other concurrent sockets.

Supporting documentation