@thesmilingsloth/eventflow-react v0.0.3

@thesmilingsloth/eventflow-react

React integration for EventFlow event broker with hooks and context support.

Features

• ⚛️ React Hooks: First-class React integration
• 🎯 Type-safe: Full TypeScript support
• 🔄 Automatic Cleanup: Handles subscription cleanup
• 📦 Tree-shakeable: Only bundle what you use
• 🎭 Context Provider: Easy broker access
• 🪝 Custom Hooks: useEventListener, useEventEmitter, useEventState

Installation

# Using npm
npm install @thesmilingsloth/eventflow-react @thesmilingsloth/eventflow-core

# Using yarn
yarn add @thesmilingsloth/eventflow-react @thesmilingsloth/eventflow-core

# Using pnpm
pnpm add @thesmilingsloth/eventflow-react @thesmilingsloth/eventflow-core

Quick Start

import {
  EventBrokerProvider,
  useEventListener,
  useEventEmitter,
  useEventState,
} from "@thesmilingsloth/eventflow-react";
import { createEventBroker } from "@thesmilingsloth/eventflow-core";

// Define your events
interface MyEvents {
  "user:login": { userId: string };
  "theme:change": "light" | "dark";
  "notification:show": { message: string; type: "success" | "error" };
}

// Create broker
const broker = createEventBroker<MyEvents>();

// Provider setup
function App() {
  return (
    <EventBrokerProvider broker={broker}>
      <LoginButton />
      <ThemeToggle />
      <NotificationListener />
    </EventBrokerProvider>
  );
}

// Emit events
function LoginButton() {
  const emitLogin = useEventEmitter("user:login");

  return <button onClick={() => emitLogin({ userId: "123" })}>Login</button>;
}

// Listen to events
function NotificationListener() {
  useEventListener("notification:show", (data) => {
    alert(`${data.type}: ${data.message}`);
  });

  return null;
}

// Manage state with events
function ThemeToggle() {
  const [theme, setTheme] = useEventState("theme:change", "light");

  return (
    <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
      Toggle Theme
    </button>
  );
}

Hooks API

useEventListener

Subscribe to events in components.

useEventListener<K extends keyof T>(
  eventName: K,
  listener: (data: T[K]) => void
): void;

useEventEmitter

Get a typed emit function.

const emit = useEventEmitter<K extends keyof T>(eventName: K);
// Returns (data: T[K]) => void

useEventState

Manage state through events.

const [state, setState] = useEventState<K extends keyof T>(
  eventName: K,
  initialState: T[K]
): [T[K], (data: T[K]) => void];

useEventOnce

Subscribe to an event once.

useEventOnce<K extends keyof T>(
  eventName: K,
  listener: (data: T[K]) => void
): void;

Best Practices

1. Component Cleanup

// Hooks handle cleanup automatically
function MyComponent() {
  useEventListener("user:login", (data) => {
    // This listener is automatically removed on unmount
  });
}

2. Type Safety

// Events are fully typed
const emit = useEventEmitter("notification:show");
emit({
  message: "Hello",
  type: "success", // Type-checked: must be "success" | "error"
});

3. State Management

// Use useEventState for shared state
function ThemeManager() {
  const [theme, setTheme] = useEventState("theme:change", "light");
  // Any component can listen to or update the theme
}

Related Packages

• @thesmilingsloth/eventflow-core - Core event broker

Contributing

Contributions are welcome!

License

MIT © Smiling Sloth