npm.io
3.0.0 • Published 2d ago

@solid-primitives/event-bus

Licence
MIT
Version
3.0.0
Deps
1
Size
34 kB
Vulns
0
Weekly
0
Stars
1.6K

Solid Primitives Event Bus

@solid-primitives/event-bus

size size stage tested with vitest

A collection of SolidJS primitives providing various features of a pubsub/event-emitter/event-bus:

  • createEventBus - Provides a simple way to listen to and emit events.
  • createEmitter - Creates an emitter with which you can listen to and emit various events.
  • createEventHub - Provides helpers for using a group of buses.
  • createEventStack - Provides the emitted events as list/history, with tools to manage it.

Installation

npm install @solid-primitives/event-bus
# or
pnpm add @solid-primitives/event-bus
# or
yarn add @solid-primitives/event-bus

Requires solid-js ^2.0.0-beta.10.

createEventBus

Provides all the base functions of an event-emitter, plus additional functions for managing listeners, it's behavior could be customized with an config object. Good for advanced usage.

import { render } from "@solidjs/web";
import { createSignal } from "solid-js";
import { createEventBus } from "@solid-primitives/event-bus";

function Demo() {
  const bus = createEventBus<boolean>();
  const [lightOn, setLightOn] = createSignal(false);
  // the light only knows about the bus, not the switch
  bus.listen(setLightOn);

  return (
    <>
      <button onClick={() => bus.emit(!lightOn())}>Toggle switch</button>
      <p>light: {lightOn() ? "ON" : "OFF"}</p>
    </>
  );
}

render(() => <Demo />, document.getElementById("app")!);
How to use it
import { createEventBus } from "@solid-primitives/event-bus";

const bus = createEventBus<string>();

// can be used without payload type, if you don't want to send any
createEventBus();

// bus can be destructured:
const { listen, emit, clear } = bus;

const unsub = bus.listen(a => console.log(a));

bus.emit("foo");

// unsub gets called automatically on cleanup
unsub();

createEmitter

Creates an emitter with which you can listen to and emit various events.

import { render } from "@solidjs/web";
import { createSignal, For } from "solid-js";
import { createEmitter } from "@solid-primitives/event-bus";

function Demo() {
  const emitter = createEmitter<{ greet: string; count: number }>();
  const [log, setLog] = createSignal<string[]>([]);
  const push = (msg: string) => setLog(prev => [msg, ...prev].slice(0, 5));

  emitter.on("greet", name => push(`Hello, ${name}!`));
  emitter.on("count", n => push(`Count: ${n}`));

  let count = 0;
  return (
    <>
      <button onClick={() => emitter.emit("greet", "world")}>Greet</button>
      <button onClick={() => emitter.emit("count", ++count)}>Count</button>
      <ul>
        <For each={log()}>{entry => <li>{entry}</li>}</For>
      </ul>
    </>
  );
}

render(() => <Demo />, document.getElementById("app")!);
How to use it
import { createEmitter } from "@solid-primitives/event-bus";

const emitter = createEmitter<{
  foo: number;
  bar: string;
}>();
// can be destructured
const { on, emit, clear } = emitter;

emitter.on("foo", e => {});
emitter.on("bar", e => {});

emitter.emit("foo", 0);
emitter.emit("bar", "hello");

// unsub gets called automatically on cleanup
unsub();
createGlobalEmitter

Wrapper around createEmitter.

Creates an emitter with which you can listen to and emit various events. With this emitter you can also listen to all events.

import { createGlobalEmitter } from "@solid-primitives/event-bus";

const emitter = createGlobalEmitter<{
  foo: number;
  bar: string;
}>();
// can be destructured
const { on, emit, clear, listen } = emitter;

emitter.on("foo", e => {});
emitter.on("bar", e => {});

emitter.emit("foo", 0);
emitter.emit("bar", "hello");

// global listener - listens to all channels
emitter.listen(e => {
  switch (e.name) {
    case "foo": {
      e.details;
      break;
    }
    case "bar": {
      e.details;
      break;
    }
  }
});

createEventHub

Provides helpers for using a group of event buses.

import { render } from "@solidjs/web";
import { createSignal } from "solid-js";
import { createEventHub } from "@solid-primitives/event-bus";

function Demo() {
  const hub = createEventHub(bus => ({
    spin: bus<number>(),
    reset: bus<void>(),
  }));
  const [angle, setAngle] = createSignal(0);
  const [last, setLast] = createSignal("none");

  hub.on("spin", deg => setAngle(a => a + deg));
  hub.reset.listen(() => setAngle(0));
  // global listener - receives events from every channel
  hub.listen(e => setLast(`${e.name}(${e.details ?? ""})`));

  return (
    <>
      <button onClick={() => hub.emit("spin", 45)}>Spin +45°</button>
      <button onClick={() => hub.emit("reset")}>Reset</button>
      <div
        style={{
          width: "60px",
          height: "60px",
          background: "orange",
          transform: `rotate(${angle()}deg)`,
        }}
      />
      <p>last event: {last()}</p>
    </>
  );
}

render(() => <Demo />, document.getElementById("app")!);

Can be used with createEventBus, createEventStack or any emitter that has the same api.

How to use it
Creating EventHub
import { createEventHub } from "@solid-primitives/event-bus";

// by passing an record of Channels
const hub = createEventHub({
  busA: createEventBus(),
  busB: createEventBus<string>(),
  busC: createEventStack<{ text: string }>(),
});

// by passing a function
const hub = createEventHub(bus => ({
  busA: bus<number>(),
  busB: bus<string>(),
  busC: createEventStack<{ text: string }>(),
}));

// hub can be destructured
const { busA, busB, on, emit, listen, value } = hub;
Listening & Emitting
const hub = createEventHub({
  busA: createEventBus<void>(),
  busB: createEventBus<string>(),
  busC: createEventStack<{ text: string }>(),
});
// can be destructured
const { busA, busB, on, listen, emit } = hub;

hub.on("busA", e => {});
hub.on("busB", e => {});

hub.emit("busA", 0);
hub.emit("busB", "foo");

// global listener - listens to all channels
hub.listen(e => {
  switch (e.name) {
    case "busA": {
      e.details;
      break;
    }
    case "busB": {
      e.details;
      break;
    }
  }
});
Accessing values

If a emitter returns an accessor value, it will be available in a .value store.

hub.value.myBus;
// same as
hub.myBus.value();

createEventStack

Extends createEmitter. Provides the emitted events in a list/history form, with tools to manage it.

import { render } from "@solidjs/web";
import { createSignal, For } from "solid-js";
import { createEventStack } from "@solid-primitives/event-bus";

function Demo() {
  const stack = createEventStack<string, { text: string }>({
    toValue: text => ({ text }),
    length: 5,
  });
  const [draft, setDraft] = createSignal("Hello");

  return (
    <>
      <input value={draft()} onInput={e => setDraft(e.currentTarget.value)} />
      <button onClick={() => stack.emit(draft())}>Send</button>
      {/* stack.clear() removes listeners, not items — reset the value instead */}
      <button onClick={() => stack.setValue([])}>Clear</button>
      <ul>
        <For each={stack.value()}>
          {item => (
            <li>
              {item.text} <button onClick={() => stack.remove(item)}>×</button>
            </li>
          )}
        </For>
      </ul>
    </>
  );
}

render(() => <Demo />, document.getElementById("app")!);
How to use it
import { createEventStack } from "@solid-primitives/event-bus";

const bus = createEventStack<string, { message: string }>({
  // toValue parsing function is optional
  toValue: e => ({ message: e })
});
// can be destructured:
const { listen, emit, clear, value } = bus;

const listener: EventStackListener<{ text: string }> = ({ event, stack, remove }) => {
  console.log(event, stack);
  // you can remove the value from stack
  remove();
};
bus.listen(listener);

bus.emit({ text: "foo" });

// a signal accessor:
bus.value() // => { text: string }[]

bus.setValue(stack => stack.filter(item => {...}))

EventBus Utils

toPromise

Turns a stream-like listen function, into a promise resolving when the first event is captured.

import { toPromise } from "@solid-primitives/event-bus";

const emitter = createEmitter<string>();
const event = await toPromise(emitter.listen);

// can be used together with raceTimeout from @solid-primitives/utils
import { raceTimeout } from "@solid-primitives/utils";
try {
  const event = await raceTimeout(toPromise(emitter.listen), 2000, true, "event was too slow");
  // if event is quicker:
  event; // => string
} catch (err) {
  // if timeouts:
  console.log(err); // => "event was too slow"
}
once

Listen to any EventBus/Emitter, but the listener will automatically unsubscribe on the first captured event. So the callback will run only once.

import { once } from "@solid-primitives/event-bus";

const { listen, emit } = createEmitter<string>();
const unsub = once(listen, event => console.log(event));

emit("foo"); // will log "foo" and unsub

emit("bar"); // won't log
toEffect

Wraps emit calls inside a createEffect. It causes that listeners execute having an reactive owner available. It allows for usage of effects, memos and other primitives inside listeners, without having to create a synthetic root.

import { toEffect } from "@solid-primitives/event-bus";

const { listen, emit } = createEmitter();
const emitInEffect = toEffect(emit);

// owner is needed for creating computations like createEffect
listen(() => console.log(getOwner()));

// ...sometime later (after root initiation):
emit(); // listener will log `null`
emitInEffect(); // listener will log an owner object
batchEmits

In Solid 2.0, all signal writes are automatically batched via microtasks, so this function is now a no-op that returns the bus unchanged. It is kept for backwards compatibility.

import { createEventBus, batchEmits } from "@solid-primitives/event-bus";

const bus = batchEmits(createEventBus());

Changelog

See CHANGELOG.md

Keywords