overhead-js

overhead

Tiny, framework-agnostic pubsub core with a TypeScript-first API.

Use the core package anywhere JavaScript runs, and add the optional React package only when you want hooks and provider-based integration in React apps.

Install

npm install overhead-js

Usage (ESM/CJS)

import { createPubSub } from 'overhead-js';

type Events = {
  scoreUpdated: { home: number; away: number };
};

const bus = createPubSub<Events>();

const unsubscribe = bus.subscribe('scoreUpdated', (payload) => {
  console.log(payload.home, payload.away);
});

bus.publish('scoreUpdated', { home: 1, away: 0 });
unsubscribe();

React Adapter

import { createPubSub } from 'overhead-js';
import {
  OverheadProvider,
  usePublish,
  useSubscription,
} from 'overhead-js/react';

type Events = {
  toast: { message: string };
};

const testBus = createPubSub<Events>();

function ToastListener() {
  useSubscription<Events, 'toast'>('toast', (payload) => {
    console.log(payload.message);
  });

  return null;
}

function ToastButton() {
  const publishToast = usePublish<Events, 'toast'>('toast');

  return (
    <button onClick={() => publishToast({ message: 'Saved' })}>
      Publish toast
    </button>
  );
}

export function App() {
  return (
    <OverheadProvider bus={testBus}>
      <ToastListener />
      <ToastButton />
    </OverheadProvider>
  );
}

Use bus injection on OverheadProvider when you want a scoped event bus in tests.

Usage (Script Tag)

<script src="https://unpkg.com/overhead-js/dist/index.global.js"></script>
<script>
  const bus = window.Overhead.createPubSub();

  const unsubscribe = bus.subscribe('ping', (payload) => {
    console.log('ping payload:', payload);
  });

  bus.publish('ping', { ok: true });
  unsubscribe();
</script>

API

• createPubSub()
• subscribe(topic, handler)
• publish(topic, payload)
• clear(topic?)
• size(topic?)
• OverheadProvider
• usePubSub()
• usePublish(topic)
• useSubscription(topic, handler)

Scripts

npm run test
npm run build
npm run typecheck