@kakang/fastify-ws

This package is a fork of fastify-websocket and rewritten as Typescript. It provides more utility for using the websocket, e.g. boardcast.

Install

1npm install @kakang/fastify-ws --save
2
3yarn add @kakang/fastify-ws

Usages

After regitered the plugin, you can pass { ws: true } to the route option. By default, it accepts the websocket handler when using the shorten method.

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5fastify.get('/', { ws: true }, (request /* WebsocketFastifyRequest */) => {
6  const { socket } = request.ws
7  socket.on('message', message => {
8    // message.toString() === 'hi from client'
9    socket.send('hi from server')
10  })
11})

WebsocketFastifyRequest

WebsocketFastifyRequest is extended from FastifyRequest and provide some utility for websocket usage.

WebsocketFastifyRequest#subscribe

Subscribe to a topic.

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5fastify.get('/', { ws: true }, (request /* WebsocketFastifyRequest */) => {
6  const { subscribe } = request.ws
7  subscribe('foo')
8})

WebsocketFastifyRequest#unsubscribe

Unsubscribe from a topic.

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5fastify.get('/', { ws: true }, (request /* WebsocketFastifyRequest */) => {
6  const { unsubscribe } = request.ws
7  unsubscribe('foo')
8})

WebsocketFastifyRequest#boardcast

Boardcast to all websocket except itself.

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5fastify.get('/', { ws: true }, (request /* WebsocketFastifyRequest */) => {
6  const { boardcast } = request.ws
7  boardcast('hello all.')
8})

FastifyInstance

This plugin also decorate the fastify instance to provide more ability for normal route communicate to the websocket.

FastifyInstance#server

ws Server instance.

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5fastify.ws.server // ws instance

FastifyInstance#clients

All avaiable websocket clients. It is a shortcut of fastify.ws.server.clients

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5fastify.ws.clients // websocket clients
6fastify.ws.server.clients = fastify.ws.clients // true

FastifyInstance#topics

All topics that have registered before.

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5for(const topic of fastify.ws.topics) {
6  console.log(topic)
7}

FastifyInstance#topicMap

All topic with WebsocketFastifyRequest.

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5for(const [topic, requests] of fastify.ws.topicMap.entries()) {
6  for(const request of requests) {
7    console.log(topic, request)
8  }
9}

FastifyInstance#boardcast

Boardcast to all websocket.

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5fastify.ws.boardcast('hello all.')

FastifyInstance#boardcastToTopic

Boardcast to all websocket in specified topic.

1import Fastify from 'fastify'
2import { fastifyWS } from '@kakang/fastify-ws'
3
4fastify.register(fastifyWS)
5fastify.ws.boardcastToTopic('foo', 'hello foo.')