Extension-event-bus NPM

browser-extension-event-bus

Description

Why this library was created?

After Google announced Manifest V3 for browser extensions, then we as developers could not use persistent background page anymore. What worse we have to use Service worker, which could be inactive from time to time. So simple in-memory event bus implementation is not enough.

TL;DR:

This tool allows (again) to decouple business logic hidden in orthogonal modules written for MV3 extensions.

How it works?

Browser extension event bus is a cross-browser library that is utilizing browser local storage in order to buffer and dispatch all events to multiple subscribers if needed.

Events are persisted as soon as possible, then all subscribers receive them.

Features

Sending events
Subscribing for events (from many places if needed)
Buffering events (local storage implementation)
Cross context communication *

Technical side of things

Installation

NPM - use command presented below

npm i extension-event-bus

YARN - use command presented below

yarn add extension-event-bus

Dependencies

For now library is using only:

Typescript
webextension-polyfill

API documentation

Sending an event

In order to send event you need to use method presented below.

async send(topic: string, data: any): Promise<boolean>

We simply pass topic name and data we want to include in event.

Subscribing or receiving an event

In order to subscribe to an event we need to use method shown below.

subscribe(topic: string, f: Function): Promise<void>

Again, we are passing topic and handler function that would take data that were sent as an argument.

Usage example

import { EventBusFactory } from 'extension-event-bus';
import { IEventBus } from 'extension-event-bus/dist/cjs/iEventBus';

// Define custom handler
const multiply = (n: number) => {
  const result = n * n;
  console.log(result);
}

const browser = null; // import it from webextension-polyfill library
const config = Config.default();

// Create an event bus by using factory class
const eventBus: IEventBus = EventBusFactory.getEventBus(browser, config);

// Define all subsribents
await eventBus.subscribe('numbers', console.log);
await eventBus.subscribe('numbers', multiply);

// Send event
await eventBus.send('numbers',10);

// Result in the console should be like ...
// 10
// 100

Other things

Contribution

Library is still on development stage. So please create an issues if you have some ideas or problems.

Unit tests

If you want implement some new features or test something locally you can use Jest framework to do it. Take a look at __tests__ directory. In order to run all tests please execute npm run test command.

Known issues and limitations

As you know we could distinguish a couple of sub-packages in browser extension:

service worker
content scripts
popup
devtools

We need to initialize our event bus in each context itself. Because an event bus is utilizing local storage (which is shared between contexts) we could send events between these contexts.

WARN: THIS FEATURE IS IN TEST STAGE