typed-events

typed-events

Typed, schema-validated wrappers for native browser event APIs. Each factory returns an object with dispatch() and listen() — listen() returns a cleanup function.

Choosing the right factory

Goal	Use
Fire an event on the current page	createEvent
Group related events under a namespace	createEventMap
Sync state across browser tabs	createBroadcastChannel
Fire locally AND across tabs simultaneously	createBroadcastEvent
Send a message to an iframe or cross-origin window	createMessage

Setup

import * as z from "zod";
import { createEvent } from "@stephansama/typed-events";

export const animationEvent = createEvent(
  "my-app:animation",
  z.object({ x: z.number(), y: z.number() }),
);

Core Patterns

Single validated CustomEvent

import * as z from "zod";
import { createEvent } from "@stephansama/typed-events";

export const clickEvent = createEvent(
  "my-app:click",
  z.object({ id: z.string() }),
);

// dispatch
clickEvent.dispatch({ id: "btn-1" });

// listen — store cleanup and call it when done
const cleanup = clickEvent.listen(({ data }) => {
  console.log(data.id);
});
// later:
cleanup();

Namespaced event map (group related events)

import * as z from "zod";
import { createEventMap } from "@stephansama/typed-events";

export const formEvents = createEventMap("form", {
  submit: z.object({ values: z.record(z.string()) }),
  reset: z.object({}),
});

formEvents.dispatch("submit", { values: { email: "[email protected]" } });

const cleanup = formEvents.listen("submit", ({ data }) => {
  console.log(data.values);
});

Event names are scoped internally as form:submit and form:reset.

Cross-tab sync with BroadcastChannel

import * as z from "zod";
import { createBroadcastChannel } from "@stephansama/typed-events";

export const tabChannel = createBroadcastChannel("my-app", {
  theme: z.object({ mode: z.enum(["light", "dark"]) }),
});

tabChannel.dispatch("theme", { mode: "dark" });

const cleanup = tabChannel.listen("theme", ({ data }) => {
  document.documentElement.dataset.theme = data.mode;
});