inra-server-socket

The purpose of this component is to intercept the manipulation of most of the socket work by creating special wrappers. These wrappers allow the developer to integrate his client with inra-server rapidly, manipulate data, connections and/or namespaces.

Note: full documentation with more examples is published on our Wiki. Please, refer to our Wiki for installation details and API references.

• Installation
• API reference
• Contributing
  • Bug reporting
  • Development

Installation

$ npm install --save inra-server-socket

API

const socket = new Socket(config);

Socket Server

.send(id, event [, data = {}])

Emits an event with data for a specific connection. This is usefll in event listeners on server-side, when you intercept specific events and want to send back a response for the given source.

Example:

socket.on("eventA", (data, connection, namespace) => {
  socket.send(connection.id, "eventB", ...data);
});

.emit(event [, data = {}])

Emits an event with data for every connection in every namespace registered.

Example:

socket.emit("event", ...data);

.broadcast(event [, data = {}])

Emits an event with data for every connection in every namespace registered. Broadcast behaviour is the same as for .emit (in Socket only - it changes for SocketNamespace and SocketConnection).

Example:

socket.broadcast("event", ...data);

.on(event, callback)

Registers a callback for a specific event coming from all the registered namespaces. This means that event will be intercepted even if it was registered only for a specific SocketNamespace.

Note: You can still register events which will be intercepted only by specified namespaces.

socket.on("event", (data, connection, namespace) => {
  // …
});

.create(id)

Creates a new room with id room. Automically resolves new connections and events. Returns the created room instance (SocketNamespace).

const indexNamespace = socket.create("/").listen();
const adminNamespace = socket.create("/admin").use(authMiddleware).listen();

.trigger(event, data, connection, namespace)

Triggers a specific event with data, connection and namespace.

socket.on("event", (data, connection, namespace) => {
  if (/* … */) {
    socket.trigger("another_event", data, connection, namespace);
  }
});

.io

socket.io instance.

.host

.port

.hostname

.config

.callbacks

.connections

Socket Connection

.on(event, callback)

Executes callback on event from the actual socket.

.emit(event [, data = {}])

Emits an event with data from the actual socket.

.broadcast(event [, data = {}])

Emits an event with data to everyone else in the namespace except for the actual socket.

.id

Unique id for actual connection. Same as in Socket.connections<id>. Can be used for Socket.send(id, event, data).

.instance

Instance from the initial socket from socket.io.

.namespace

Reference to the namespace the actual socket comes from.

.server

Reference to the server the actual socket comes from.

Socket Namespace

Returned by Socket.create.

const indexNamespace = socket.create("/").listen();
const adminNamespace = socket.create("/admin").use(authMiddleware).listen();

indexNamespace.on("event", (data, socket) => {
  // accessible for all users
});

adminNamespace.on("event", (data, socket) => {
  // accessible for authenticated users
});

.on(event, callback)

Registers a callback for event for the actual namespace. Events registered with this method are local. This means that those events will not be intercepted by Socket.on.

.broadcast(event [, data = {}])

Emits an event with data to everyone in the actual namespace.

.use(middleware)

Adds a custom middleware to the actual namespace.

.listen()

Registers customs event listeners for the actual namespace. Integrates the actual namespace with socket server. You probably want to always call this method once you've configured your namespace.

.id

Unique id (name) for the actual namespace.

.instance

Instance of the initial room from socket.io.

.server

Reference to the server the actual namespace comes from.

Contributing

Bug reporting

We want contributing to Inra Server to be fun, enjoyable, and educational for anyone, and everyone. Changes and improvements are more than welcome! Feel free to fork and open a pull request. If you have found any issues, please report them here - they are being tracked on GitHub Issues.

License

Inra Server is built and maintained by Bartosz Łaniewski. The full list of contributors can be found here. Inra's code is MIT licensed.

Development

We have prepared multiple commands to help you develop inra-server-socket on your own. Don't forget to install all Node.js dependencies from npm. You will need a local copy of Node.js installed on your machine.

$ sudo npm install

Usage

$ sudo npm run <command>

List of commands

| Command | Description | |---------------|---------------------------------------------------| | build | Builds inra-server-socket | | watch | Re-builds inra-server-socket on changes | | clean | Deletes builds ands cache | | lint | Fixes Lint errors | | flow | Checks Flow errors | | test | Checks Flow errors and runs tests |