React Tiny Events

Description

This tiny package is a simple event emitter for React. It enables a reactive bottom up approach to event handling, where events are emitted from the bottom of the component tree and handled at the top of the component tree.

Project aims

• Simplicity: This package is designed to be simple and easy to use. It is designed to be used in a React environment, but it can be used in any JavaScript environment.
• Lightweight: This package is lightweight and have ~~minimal~~ zero dependencies.
• Type safety: This package is fully type safe. When used with TypeScript, it provides type safety for the event data and event handlers.

Installation

#- npm
npm install react-tiny-package
#- yarn
yarn add react-tiny-package
#- pnpm
pnpm add react-tiny-package

Usage

Here's a basic example of how to use this package, where an event can be created to open a modal.

ModalEventManager.ts

Here, we create a file to manage the events related to the modal. We create a static list of events, and then use the createEventManager function to create a provider and hooks for the events. We then export the provider and hooks, as well as the type of event handlers that can be used with the events.

// ./example/ModalEventManager.ts

import {
  createEventManager,
  TypedEvent,
  type EventHandlers,
} from "react-tiny-events";

// Create a static list of events
const events = {
  onOpenModal: new TypedEvent<{ modalId: string }>(),
} as const;

const { provider, useEvent, useEvents, useEventHandler } =
  createEventManager(events);

// Export the event provider and hooks
export const ModalEventProvider = provider;
export const useModalEvents = useEvents;
export const useModalEvent = useEvent;
export const useModalEventHandler = useEventHandler;
export type ModalEventHandlers = EventHandlers<typeof events>;

App.tsx

Here, we create a simple app that uses the ModalEventProvider to manage the modal events. The ModalEventProvider is used to wrap the app content. We then create a modal component that uses the useModalEventHandler hook to listen for the onOpenModal event. We also create a button component that uses the useModalEvent hook to emit the onOpenModal event.

// ./example/App.tsx

import React from "react";
import {
  ModalEventProvider,
  useModalEvent,
  useModalEventHandler,
} from "./ModalEventManager";

export default function App() {
  return (
    <ModalEventProvider>
      <MyModalComponent />
      <MyButtonComponent />
      ...appContent
    </ModalEventProvider>
  );
}

function MyModalComponent() {
  const [modalId, setModalId] = React.useState("");

  // Subscribe to the onOpenModal event
  useModalEventHandler("onOpenModal", (event) => {
    setModalId(event.modalId);
  });

  return <div>...modalContent</div>;
}

function MyButtonComponent() {
  const openModal = useModalEvent("onOpenModal");

  return (
    <button onClick={() => openModal.emit({ modalId: "my-modal" })}>
      Open Modal
    </button>
  );
}

API

createEventManager

This function creates a provider and hooks for the events. It takes an object of events as an argument, and returns an object with the provider and hooks.

const { provider, useEvent, useEvents, useEventHandler } = createEventManager(events);

createEventManager().useEvent

This hook is used to retrieve and emit an event. It takes the event name as an argument, and returns an object with event utilities

const openModal = useEvent("onOpenModal");

createEventManager().useEvents

This hook is used to retrieve all the events. It returns an object with all the events, indexed by name.

const {openModal, closeModal} = useEvents();

createEventManager().useEventHandler

This hook is used to subscribe to an event. It takes the event name and a callback as arguments.

useEventHandler("onOpenModal", (event) => {
  console.log(event.modalId);
});

TypedEvent

This class is used to create an event. It is a simple event emitter that can be used to emit and subscribe to events. It takes a type as an argument, which is the type of the event data.

const openModal = new TypedEvent<{ modalId: string }>();

TypedEvent.emit

This method is used to emit an event. It takes the event data as an argument.

openModal.emit({ modalId: "my-modal" });

TypedEvent.once

This method is used to subscribe to an event once. It takes a callback as an argument.

openModal.once((event) => {
  console.log(event.modalId);
});

TypedEvent.off

This method is used to unsubscribe from an event. It takes a callback as an argument.

const callback = (event) => {
  console.log(event.modalId);
};

TypedEvent.on

This method is used to subscribe to an event. It takes a callback as an argument.

openModal.on((event) => {
  console.log(event.modalId);
});

TypedEvent.pipe

This method is used to pipe an event to another event. It takes another event as an argument.

openModal.pipe(closeModal);

License

This package is licensed under the MIT license.