spacebro client

🌟 Connect easily to a spacebro server.

🌍 Installation

yarn add spacebro-client
# or
npm i -S spacebro-client

👋 Usage

First, you need to start a spacebro server.

$ npm i -g spacebro # or yarn global add spacebro
$ spacebro

Then, write the following client code:

const { SpacebroClient } = require('spacebro-client')

const client = new SpacebroClient({
  host: '127.0.0.1',
  port: 36000,
  channelName: 'bar',
  client: {
    name: 'foo',
    description: "a foo tool",
    in: {
      inFoo: {
        eventName: "inFoo",
        description: "Input foo",
        type: "all"
      }
    },
    out: {
      outBar: {
        eventName: "outBar",
        description: "Output bar",
        type: "all"
      }
    }
  },
  connection: "bar/outBar => bar/inFoo"
})

client.on('inFoo', (data) => console.log('inFoo', data))
client.emit('outBar', { do: stuff})

The connection string was sent to the spacebro server, that will then connects every event named outBar from client bar to a new event named inFoo sent to client bar

🚀 API

class SpacebroClient([options], [connect])

Look for a server, and return a handle to the connection.

// For more details about possible options, see below.
const client = new SpacebroClient({
  host: '127.0.0.1',
  port: 8888,
  client: {name: 'foo'},
  channelName: 'bar'
})

options:

name	default	required	description
host	-	required	The spacebro server's address. Ignored if connect is false.
port	-	required	The spacebro server's address. Ignored if connect is false.
client.name	null	recommended	Your client's name. Can be useful to perform targeted events and for monitoring.
channelName	null	recommended	The channel your app will communicate in. This is especially usefull if you have multiple apps using the same server.
verbose	true	optional	Should spacebro-client display logs (connection / emission / reception)?
sendBack	true	optional	Should this client receive the events it sent?

connect

If the connect parameter is false, then the options are saved and a disconnected handle is returned; you have to call its connect method later before you can emit or receive events.

Default value: true

const client = new SpacebroClient({
  client: {name: 'myClient'},
  channelName: 'someChannel'
}, false)

// ...

client.connect('127.0.0.1', 8888)

create([options])

Look for a server, and creates a handle to the connection. Takes the same options as new SpacebroClient. Returns a Promise like client.connect.

setDefaultSettings(options, [verbose])

Overwrite the default options of new SpacebroClient with the given options.

If standard-settings is installed in your module, spacebro-client will call this function with the contents of services.spacebro from your settings file.

client.connect(address, port)

Look for a server, and connect client to this server. Returns a Promise that resolves to client when the connection is established, or throws an error if the connection fails.

client.emit(eventName[, data])

Broadcast a specific event to all the clients in the channel. data must be a JSON object.

client.sendTo(eventName, target[, data])

Send an event to a specific target in the channel. data must be a JSON object.

client.on(eventName, handler)

Listen to a specific event.

client.once(eventName, handler)

Listen to a specific event only once.

client.off(eventName)

Remove a specific event listener.

client.disconnect()

Close the connection.

Socket.io callbacks (acknowledgments)

Spacebro now works with acknowlegdments too !

const { SpacebroClient } = require('spacebro-client')

const client = new SpacebroClient({
  host: '127.0.0.1',
  port: 36000,
  channelName: 'bar',
  client: {
    name: 'foo',
    description: "a foo tool",
    in: {
      inFoo: {
        eventName: "inFoo",
        description: "Input foo",
        type: "all"
      }
    },
    out: {
      outBar: {
        eventName: "outBar",
        description: "Output bar",
        type: "all"
      }
    }
  },
  connection: "bar/outBar => bar/inFoo"
})

client.on('inFoo', (data, fn) => {
  console.log('inFoo', data)
  fn('thank you')
})

client.emit('outBar', { do: stuff}, function (data) {
  console.log('Received from callback: ' + data)
})

🖥 Browser

You can use spacebro-client in the browser. You will need the following dependencies:

<script src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.1.0/socket.io.js"></script>
<script src="https://wzrd.in/standalone/socketio-wildcard@latest"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/js-signals/1.0.0/js-signals.min.js"></script>

After adding these dependencies, you can include the spacebro-client lib like any script:

<script src="./dist/spacebro-client.js"></script>

Then use the window.spacebroClient object.

⚛ Electron

Spacebro-client also works in Electron. You just require('spacebro-client') in your electron main process and use ipc or web-contents to forward events to the renderer process.

From the example/electron/ folder of this repository:

// In the main process.
const { app, BrowserWindow } = require('electron')
const { SpacebroClient } = require('../../dist/spacebro-client')

let win = null

const client = new SpacebroClient({
  host: '127.0.0.1',
  port: 8888,
  client: {name: 'foo'},
  channelName: 'bar'
})

app.on('ready', () => {
  win = new BrowserWindow({ width: 800, height: 600 })
  win.loadURL(`file://${__dirname}/index.html`)

  for (const eventName of ['hello', 'world']) {
    client.on(eventName, (data) => {
      win.webContents.send(eventName, data)
    })
  }

  win.webContents.on('did-finish-load', () => {
    setTimeout(() => { client.emit('hello', { hello: 'world' }) }, 3000)
    setTimeout(() => { client.emit('world', { world: 'hello' }) }, 5000)
  })
})

<!-- index.html -->
<html>
<body>
  <script>
    require('electron').ipcRenderer.on('hello', (event, message) => {
      console.log(message)
    })
    require('electron').ipcRenderer.on('world', (event, message) => {
      console.log(message)
    })
  </script>
</body>
</html>

Examples

You can find many real life examples in the example/ folder of this repository.

🕳 Troubleshooting

newClient event 👋

The Spacebro server automatically broadcasts a newClient event when a client connects. Thus, you should avoid using that event name. See the example/simple-node script for more details.

Using native modules in Electron 🌀

If you want to use spacebro-client in an Electron app, you'll have to use electron-rebuild in order to rebuild MDNS according to the version of Node.js embedded with Electron.

Use the following commands:

$ npm i --save-dev electron-rebuild # or yarn
$ ./node_modules/.bin/electron-rebuild # call the executable every time you add a new native module

You can also add "rebuild": "./node_modules/.bin/electron-rebuild" to your package.json and run npm run rebuild for convenience.

source

yarn and node-gyp issue (i.e not compiling) 🤖

You need to use at least yarn version 0.17.8. You might have similar problems with outdated versions of npm, simply try to update it.

source

https

If the spacebro server is on https, use following settings:

  'service': {
    'spacebro': {
      'host': 'https://example.com'
      'port': 0
    }
  }

subdir on server

If the server url is something like https://example.com/subdir. You can use this url as host. Spacebro will process subdir as a path, contrary to socket.io that would process subdir as a namespace.

That means the requested urls will look like https://example.com/subdir/?EIO=3&transport=polling&sid=<id>

ping pong 🏓

Do not try to test with 'ping' and 'pong' events, those are reserved.

- `ping`. Fired when a ping packet is written out to the server.
- `pong`. Fired when a pong is received from the server.

source

❤️ Contribute

Please follow Standard JS conventions.

The package has lint testing and unit testing baked-in. Please use npm run test to run both sets of tests before making a pull request. Use npm run build to transpile the project.

The project's release versions are named after stars in Andromeda . The current version is named Sirrah.

Enjoy !