Remote: a little module for more elegant remoting with WebSockets

Remote¹ is a tiny (< 50 lines of code) module that creates a very lightweight façade over a socket connection, using convention over configuration to give you an expressive interface with which to send outgoing messages and handle incoming ones.

You can use it both on the server and on the client.²

Here’s a simple Site.js example that performs some basic arithmetic on the server and keeps a count.

1. Install Site.js.

2. Create a folder to hold the example and the following directory structure inside it.

   ├── .dynamic
   │  └── .wss
   │     └── index.cjs
   └── index.html
   

   The index.cjs file is where you will put your server-side WebSocket route and index.html is where you will have your client.

3. Initialise an npm project.

   npm init -y
   

4. Install the Remote module.

   npm install @small-tech/remote
   

5. Create the client (in index.html).

   <script type='module'>
     // Only load from Skypack for simple demonstration purposes. Don’t
     // use in production as it doesn’t support sub-resource integrity.
     // (See https://ar.al/2020/12/30/skypack-backdoor-as-a-service/)
     import Remote from 'https://cdn.skypack.dev/@small-tech/remote'
   
     const socket = new WebSocket(`wss://${window.location.hostname}/`)
     const remote = new Remote(socket)
   
     socket.addEventListener('open', () => {
       // Send remote events.
       remote.counter.increment.send()
       remote.addNumbers.request.send({firstNumber: 40, secondNumber: 2})
       remote.subtractNumbers.request.send({firstNumber: 44, secondNumber: 2})
     })
   
     // Handle remote events.
   
     remote.counter.update.handler = message => {
       log(`Counter is now ${message.count}`)
     }
   
     remote.addNumbers.response.handler = message => {
       log (`${message.firstNumber} + ${message.secondNumber} = ${message.result}`)
     }
   
     remote.subtractNumbers.response.handler = message => {
       log(`${message.firstNumber} - ${message.secondNumber} = ${message.result}`)
     }
   
     // DOM manipulation.
     const output = document.getElementById('output')
     const log = message => {
       const li = document.createElement('li')
       li.innerHTML = message
       output.appendChild(li)
     }
   </script>
   
   <h1>Simple remote arithmetic</h1>
   <ul id='output'></ul>
   

6. Create the server (in .dynamic/.wss/index.cjs).

   const Remote = require('@small-tech/remote')
   
   let count = 0
   
   module.exports = function (client, request) {
   
     const remote = new Remote(client)
   
     remote.addNumbers.request.handler = message => {
       remote.addNumbers.response.send({
         firstNumber: message.firstNumber,
         secondNumber: message.secondNumber,
         result: message.firstNumber + message.secondNumber
       })
     }
   
     remote.subtractNumbers.request.handler = message => {
       remote.subtractNumbers.response.send({
         firstNumber: message.firstNumber,
         secondNumber: message.secondNumber,
         result: message.firstNumber - message.secondNumber
       })
     }
   
     remote.counter.increment.handler = message => {
       count++
       remote.counter.update.send({ count })
     }
   }
   

7. Run Site.js (in the root of your example folder).

   site
   

Now hit https://localhost and you should see the following output:

Simple remote arithmetic

    • Counter is now 1
    • 40 + 2 = 42
    • 44 - 2 = 42

If you hit the page from other browser tabs, you should see the counter increase (it will reset if you restart Site.js as we are not persisting the value anywhere.³).

How it works

Messages are sent as JSON strings and received messages are parsed from JSON strings.

There are two special keywords: send and handler. You use the former when sending a message and you define the latter as a function to handle received messages.

Otherwise, there is nothing special about the path segments that make up the rest of the statements you see. Anything between the remote instance reference and either send or handler is used as the message type.

So, for example, addNumbers.request and addNumbers.response are message types, as is counter.update. Remote automatically creates the defined object hierarchies using some Proxy magic.

So far, Remote is working well for me as I build Domain. Give it a shot and see if it works for you too.