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 for a list of improvements which Asyngular introduces over SocketCluster. this article The Asyngular GitHub repo is here: https://github.com/SocketCluster/asyngular Requirements Node.js v10 (can work with older versions but you won’t be able to use the loop to consume streams) for-await-of Optional dependency (for containerization): CLI docker 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 directory and launch with: myapp/ node server You can interact with your app by opening in your browser. http://localhost:8000/ If you have installed, you can alternatively run your Asyngular app inside a container on your local machine using the following shortcut command (run from inside your directory): docker myapp/ asyngular run Stop and remove container with: asyngular stop Use for a list of all shortcut commands. asyngular --help docker [Server] Listening for inbound socket connections Inside , find the loop which is handling inbound connections. It should look like this: server.js for-await-of [Server] Listening for inbound RPCs and messages You can add nested loops to handle different kinds of socket messages/RPCs within this main connection loop. For example: for-await-of !! Note that you can also register and handlers on a client socket using the same syntax. socket.procedure(procedureName) socket.receiver(receiverName) [Client] Connecting to the server Note that you can pass an optional object to the function to modify socket options. This function supports the same options as the function on the . See for more details. asyngularClient.create create socketcluster-client https://socketcluster.io/#!/docs/api-socketcluster-client [Client] Invoking RPCs !! Note that you should always add a block around the call to capture any async errors: try-catch socket.invoke !! 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 object; in this case, you omit the first parameter. For example: AGChannel 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 instance which has a property). AGAction type This is how to setup a middleware (this example shows the middleware handling and actions): MIDDLEWARE_INBOUND TRANSMIT INVOKE !! Note that in Asyngular, you can only have one middleware function for each middleware line. The following middleware lines and actions are supported: : The loop iterates whenever a socket handshake occurs. The property can be either or . AGServer.MIDDLEWARE_HANDSHAKE for-await-of action.type AGAction.HANDSHAKE_WS AGAction.HANDSHAKE_AG : The loop iterates whenever an inbound message (I.e. from client -> server) is received by the server. This includes all raw messages and operations; including those which are not recognized by Asyngular. The property will always be . AGServer.MIDDLEWARE_INBOUND_RAW for-await-of action.type AGAction.MESSAGE : The loop iterates whenever an inbound operation (I.e. a recognized operation from client -> server) occurs. The property can be , , , or . AGServer.MIDDLEWARE_INBOUND for-await-of action.type AGAction.TRANSMIT AGAction.INVOKE AGAction.SUBSCRIBE AGAction.PUBLISH_IN AGAction.AUTHENTICATE : The loop iterates whenever an outbound operation (I.e. server -> client) occurs. The property will always be . AGServer.MIDDLEWARE_OUTBOUND for-await-of action.type AGAction.PUBLISH_OUT Each object ( ) which is streamed through the middleware has different properties depending on its property. These are the properties supported by different action types: action AGAction type : and properties. AGAction.HANDSHAKE_WS type request : , and properties. AGAction.HANDSHAKE_AG type request socket : , and properties. AGAction.MESSAGE type socket data : , , and properties. AGAction.TRANSMIT type socket receiver data : , , and properties. AGAction.INVOKE type socket procedure data : , , and properties. AGAction.SUBSCRIBE type socket channel data : , , and properties. AGAction.PUBLISH_IN type socket channel data : , , and properties. AGAction.PUBLISH_OUT type socket channel data : , , and properties. AGAction.AUTHENTICATE type socket signedAuthToken authToken ^ In all of the above cases, is a string, is a string, is a Node.js object, is an object, is a string, is a string, is a string (or null), is an object (or null) and can be of any type (depending on what is provided by the client). type channel request [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage) socket AGServerSocket receiver procedure signedAuthToken authToken data !! 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 https://github.com/SocketCluster/asyngular https://github.com/SocketCluster/asyngular-server https://github.com/SocketCluster/asyngular-client https://socketcluster.io/
