HyperBridge

A library for smooth communication between different javascript contexts

API References

• Fast. It has many performance optimization to track changes only from needed instances.
• Typed. The library provide full coverage typings via TypeScript.
• Small. We try to minimize distributed size and use tiny dependencies.

🚀 Quick Start

1. Install the library from NPM

Execute this command in your project to install the library as new dependency:

npm install --save hyperbridge

Or if you using yarn:

yarn add hyperbridge

2. Define your API.

import { declareApi } from "hyperbridge";

export const api = declareApi({
  actions: {
    test1: () => console.log("test1"),
    test2: () => Promise.resolve().then(() => console.log("test2")),
  },
  queries: {
    load1: () => ({ value: "sync" }),
    load2: () => Promise.resolve().then(() => ({ value: "async" })),
  },
  stores: {
    timer: declareStore((set) => {
      let value = 0;
      const callUpdater = () => set(value);
      setInterval(callUpdater, 1000);
    }),
  },
});

3. Create client info provider

Not required for Worker.

import { ClientInfoProvider } from "hyperbridge";

export type ClientInfo =
  | {
      readonly type: "my-client-one";
      readonly foo: "additional-value";
    }
  | { readonly type: "my-client-two" };

export const clientInfoProvider = new ClientInfoProvider<ClientInfo>((info) => {
  if (info.type === "my-client-one") {
    return `one_${info.value}`;
  }
  if (info.type === "my-client-two") {
    return `two`;
  }

  throw new Error(`Unknown client info: ${JSON.stringify(info)}`);
});

4. Create server

Use here WorkerHyperBridgeServer or ChromeHyperBridgeServer instead of abstract HyperBridgeServer

import { HyperBridgeServer } from "hyperbridge";
import { api } from "./api";
import { clientInfoProvider } from "./clientInfoProvider";

const server = new HyperBridgeServer({ api, clientInfoProvider, ... });

5. Use it on client-side

Use here WorkerHyperBridgeClient or ChromeHyperBridgeClient instead of abstract HyperBridgeClient

import { HyperBridgeClient } from "hyperbridge";
import { clientInfoProvider } from "./clientInfoProvider";

const client = new HyperBridgeClient({
  clientInfo: { type: "my-client-two" },
  clientInfoProvider,
  ...
});

// Actions are return nothing
client.actions.test1();
client.actions.test2();

// Queries always returns promise with response from server
client.queries.load1().then(console.log);
client.queries.load2().then(console.log);

// Stores have `null` state by default after creating.
// After receiving every update from server it will notify all subscribers
client.stores.timer.subscribe((fooValue) => console.log(fooValue));

🤖 Worker

TODO

Server

import { WorkerHyperBridgeServer } from "hyperbridge";
import { api } from "./api";

const server = new WorkerHyperBridgeServer({ api });

export type Server = typeof server;

Client

import { useWorkerHyperBridge } from "hyperbridge";
import type { Server } from "./server";

const worker = new Worker("./server.js");
const client = useWorkerHyperBridge<Server>({ worker });

💽 Chrome Extension

TODO

Server

import { ChromeHyperBridgeServer, ChromeHealthCheckServer } from "hyperbridge";
import { api } from "./api";

// required only once for auto-reloading all connected clients
const healthCheck = new ChromeHealthCheckServer(chrome);

const ntpServer = new ChromeHyperBridgeServer({
  id: "ntp",
  clientInfoProvider,
  api,

  // Optional callbacks:
  onConnect: (port) =>
    console.log(`Client with name "${port.name}" has been connected`),
  onDisconnect: (port) =>
    console.log(`Client with name "${port.name}" has been disconnected`),
});

export type NtpServer = typeof ntpServer;

Client

import { useChromeHyperBridge, connectToBackgroundPort } from "hyperbridge";
import { clientInfoProvider } from "./clientInfoProvider";
import type { NtpServer } from "./server";

const client = useChromeHyperBridge<NtpServer>({
  port: connectToBackgroundPort(`ntp_${crypto.randomUUID()}`),
  clientInfo: { type: "my-client-two" },
  clientInfoProvider,
});

✨ API References

TODO