Skip to content
🔩 Hexnut is a middleware based, express/koa like framework for web sockets
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci
docs
src
test
.gitignore
package-lock.json
package.json
readme.md

readme.md

Hexnut

Hexnut is a middleware based, express/koa like framework for web sockets.

npm version license CircleCI

For an introduction, and API documentation, please check out the docs.

Middleware

Client side

You can use hexnut as a client in the frontend with hexnut-client. It is also middleware based and can use many of the server middlewares directly, such as hexnut-bodyparser and hexnut-sequence.

Examples

Trivial Example

const Hexnut = require('hexnut');
const errorService = require(/* some error logging service */);
const app = new Hexnut({ port: 8080 });

app.onerror = async (err, ctx) => {
  await errorService(err);
  ctx.send(`Error! ${err.message}`);
};

app.use(ctx => {
  if (ctx.isConnection) {
    ctx.state = { count: 0 };
    return ctx.send('Hello, and welcome to the socket!');
  }

  ctx.state.count++;
  ctx.send(`Message No. ${ctx.state.count}: ${ctx.message}`);
});

app.start();

Parsing JSON automatically

const Hexnut = require('hexnut');
const bodyParser = require('hexnut-bodyparser');
const app = new Hexnut({ port: 8080 });

app.use(bodyParser.json());

app.use(ctx => {
  if (ctx.isConnection) {
    ctx.state = { count: 0 };
    return ctx.send('Hello, and welcome to the socket!');
  }

  if (ctx.message.type) {
    ctx.state.count++;
    ctx.send(`Message No. ${ctx.state.count}: ${ctx.message.type}`);
  } else {
    ctx.send(`Invalid message format, expecting JSON with a "type" key`);
  }
});

app.start();

Handling messages by type

const Hexnut = require('hexnut');
const handle = require('hexnut-handle');
const app = new Hexnut({ port: 8080 });

app.use(handle.connect(ctx => {
  ctx.count = 0;
}));

app.use(handle.matchMessage(
  msg => msg === 'incCount',
  ctx => ctx.count++
));

app.use(handle.matchMessage(
  msg => msg === 'decCount',
  ctx => ctx.count--
));

app.use(handle.matchMessage(
  msg => msg === 'getCount',
  ctx => ctx.send(ctx.count)
));

app.start();

Sequencing Interactions

const Hexnut = require('hexnut');
const bodyParser = require('hexnut-bodyparser');
const sequence = require('hexnut-sequence');
const app = new Hexnut({ port: 8080 });

app.use(bodyParser.json());

// This sequence happens when the user connects
app.use(sequence.onConnect(function* (ctx) {
  ctx.send(`Welcome, ${ctx.ip}`);
  const name = yield sequence.getMessage();
  ctx.clientName = name;
  return;
}));

app.use(sequence.interruptible(function* (ctx) {
  // In order to use this sequence, we assert that we must have a clientName on the ctx
  yield sequence.assert(() => 'clientName' in ctx);

  // We first expect a message with type == greeting
  const greeting = yield sequence.matchMessage(msg => msg.type === 'greeting');

  // Then a message that has type == timeOfDay
  const timeOfDay = yield sequence.matchMessage(msg => msg.type === 'timeOfDay');

  return ctx
    .send(`And a ${greeting.value} to you too, ${ctx.clientName} on this fine ${timeOfDay.value}`);
}));

app.start();

Integrating with rxjs

const Hexnut = require('hexnut');
const { withObservable, filterMessages } = require('hexnut-with-observable');

const { tap, filter } = require('rxjs/operators');
const { pipe } = require('rxjs');

const app = new Hexnut({ port: 8181 });

app.use(withObservable(pipe(
  // Do setup operations here...
  tap(({ctx}) => {
    if (ctx.isConnection) {
      console.log(`[${ctx.ip}] Connection started`);
    }
  }),

  // Filter to only messages
  filterMessages(msg => msg !== 'skip'),

  // Process messages
  tap(({ctx, next}) => {
    ctx.send(`You sent: ${ctx.message}`);
  })
)));


app.start();
You can’t perform that action at this time.