You're Invited:Meet the Socket Team at BlackHat and DEF CON in Las Vegas, Aug 7-8.RSVP
Sign inDemoInstall


Package Overview
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies



A basic package for building fake messaging services that communicate over websockets. Can run as a nodejs service, or be bundled inside the browser.

Version published
Weekly downloads
decreased by-9.22%
Weekly downloads




NPM Version


See the docs for more info.

A basic package for building fake messaging services that communicate over websockets. Can run as a nodejs service, or be bundled inside the browser.

This library won't give you much on its own. Instead its used to support running the same fake service code hosted within the browser or running as a node process.

Provides two main objects:

  • WsHost. For starting a websocket service. This runs as a node process which can be started from the command line, or started from nodejs tests e.g. jest, vitest, playwright, webdriver etc.
  • BrowserWsHost. For starting a "mocked" websocket service. This runs directly within the browser, and is useful for bundling "fake" services within Storybook, or a demo application, and for running browser based tests such as Cypress.

⚠️ Don't use this in production environments. This is for testing, and demo purposes only.

Example Usage

For a full example see @fakehost/fake-signalr.

Protocol Handler

Messaging services have many different types of protocols to manage the exchange of messages. Many of these are custom.

Lets say we are building a fake protocol handler for a service that has the following incoming message and outgoing message structure:

type IncomingMessage = {
    destination: string
    payload: unknown

type OutgoingMessage = {
    destination: string
    payload: unknown

Messages are all in JSON, so we can easily inspect what the service is doing by examining the network tab and looking at the messages.

An extremely basic protocol that only supports simple request/response messages could look like:

import { Host, ConnectionId, Connection, ExchangeEvent } from '@fakehost/exchange'

type MessageHandler = (payload: unknown) => unknown

export class MyProtocolHandler {

    private messageHandlers = new Map<string, MessageHandler>()

    constructor(host: Host) {
        host.on('connection', this.onConnection.bind(this))
        host.on('disconnection', this.onDisconnection.bind(this))
        host.on('message', this.onMessage.bind(this))

    onConnection({ connection }: ExchangeEvent<'connection'>) {
        console.log(`a new connection "${}"`)

    onDisconnection({ connection }: ExchangeEvent<'disconnect'>) {
        console.log(`connection "${}" has disconnected`)

    onMessage({ connection, message: rawMessage }: ExchangeEvent<'message'>) {
        // deserialize the incoming message
        const message: IncomingMessage = this.deserialize(rawMessage)

        // get the handler for the service + method
        const handler = this.messageHandlers.get(message.destination)

        if(!handler) {
            console.log(`"${destination}" not handled`)

        // call the handler
        const result = handler(message.payload)

        // send the handler's response
            destination: message.destination,
            payload: result

    deserialize(message: string | Buffer) {
        const parsed = typeof message === 'string' ? message : new TextDecoder('utf-8').decode(message);
        return JSON.parse(parsed) as IncomingMessage;

    register(destination: string, handler: MessageHandler) {
        this.messageHandlers.set(destination, handler)

And lets wire up a handler, and start MyProtocolHandler running as a localhost service:

import { WsHost } from '@fakehost/exchange'

// start a websocket service listening on port 5000 at /json
const host = new WsHost({
    name: 'fake',
    debug: true,
    port: 5000,
    path: '/json'

// create a new protocol handler
const protocol = new MyProtocolHandler(host)

// create a simple handler and register it to handle incoming messages with destination of `greeting`
const greetingHandler = (payload: { name: string }) => {
    return `Hello, ${name}!`
protocol.register('greeting', greetingHandler)


Debug logging can be enabled through the constructors, or via the environment variable:



@fakehost/exchange is licensed under the MIT License.

Migrating from v0.x

See Migrating from v0.x



Package last updated on 04 Oct 2023

Did you know?


Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.


Related posts

SocketSocket SOC 2 Logo


  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog


Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc