@oreefy/event

A lightweight, type-safe event emitter for frontend web applications with built-in cross-tab communication support.

@oreefy/event is a library built for the Oreefy ecosystem. The package is officially developed, maintained, and fully controlled by Oreefy, ensuring long-term stability, consistency, and compatibility across the ecosystem.

Browser only: This package is designed exclusively for frontend/browser environments. It requires the native BroadcastChannel API and is not intended for Node.js, server-side, or other non-browser environments.

Required Capabilities

• JavaScript / TypeScript
• A browser environment with native BroadcastChannel support
• Frontend/client-side application

Basic Usage

The following example demonstrates a typical client-side usage:

import { eventInstance } from "@oreefy/event";

const event = eventInstance();

function listener(data) {
  console.log("Signed in:", data); // { success: true }
}

// Register a listener
event.on("signedIn", listener);

// Remove the listener (Memory Efficient)
event.off("signedIn", listener);

// Emit an event
event.emit("signedIn", { success: true });

Events emitted via event.emit() work exclusively across other open tabs. The current (emitting) tab ignores the event and will not trigger its own listeners.

API Reference

Import eventInstance and create an event instance:

import { eventInstance } from "@oreefy/event";

const event = eventInstance();
event.emit();
event.on();
event.off();

All operations are synchronous.

event.emit()

Emits an event with data payload.

import { eventInstance } from "@oreefy/event";

interface Theme {
  mode: "light" | "dark" | "system";
  fontSize: string;
  // ...
}

const event = eventInstance();

// With type safety
event.emit<Theme>("theme", {
  mode: "system",
  fontSize: "14px",
});

// Without type safety
event.emit("theme", {
  mode: "system",
  fontSize: "14px",
});

The event is broadcast to all other open tabs in the same origin using BroadcastChannel. It does not execute listeners in the originating tab.

idb.on()

Registers a listener for a specific event.

import { eventInstance } from "@oreefy/event";

interface Theme {
  mode: "light" | "dark" | "system";
  fontSize: string;
  // ...
}

function listener(theme: Theme) {
  console.log(theme); // { mode: "system", fontSize: "14px" }
}

const event = eventInstance();
event.on<Theme>("theme", listener);

Multiple listeners can be registered for the same event.

idb.off()

Removes a previously registered listener.

import { eventInstance } from "@oreefy/event";

interface Theme {
  mode: "light" | "dark" | "system";
  fontSize: string;
  // ...
}

function listener(theme: Theme) {
  console.log(theme);
}

const event = eventInstance();
event.on<Theme>("theme", listener);
event.off("theme", handler); // Must pass the same function reference

If the listener is not registered, the call is silently ignored.

Cross-Tab Communication

@oreefy/event uses the browser’s native BroadcastChannel API to share events across tabs.

Tab A:

event.emit("signedIn", true);

Tab B:

event.on("signedIn", (data) => {
  console.log("Received from another tab:", data);
});

The originating tab (Tab A) does not fire its own on() listeners, guaranteeing zero self-triggering side effects.

Same-Tab vs Cross-Tab Behavior

When you call event.emit()

1. The event payload is broadcast directly to all other open tabs via BroadcastChannel.
2. The current tab ignores the event locally, allowing your primary action handler to finish without interruption.

Event Listener Errors

Errors thrown inside a listener do not prevent other listeners from running.

event.on("example", () => {
  throw new Error("Something went wrong");
});

event.on("example", (data) => {
  console.log("This listener still executes:", data);
});

event.emit("example", true);

An error thrown by one listener does not interrupt the event dispatch process.

Browser Compatibility

This package depends on the native BroadcastChannel Web API. It is intended for modern browsers that provide BroadcastChannel support.

It is not designed for:

• Node.js
• Server-side applications
• Backend services
• Serverless runtime environments
• Cloudflare Workers
• Other non-browser JavaScript runtimes

Use this package when the code is running in a browser/client environment.

About Oreefy

Oreefy is an affordable business ecosystem designed for small to enterprise businesses. Oreefy provides essential software you need for your modern business within a single ecosystem. It will save you significant time, effort, and money.

License

MIT © Oreefy