}
// Wrap your application with EventProvider
const App: React.FC = () => (
)
export default App
```
---
## π Use Cases and Kickstarters
`evently-react` is designed to simplify communication in complex React applications. Here are some inspiring real-world use cases to help you explore its potential:
### 1οΈβ£ **Cross-Component Communication**
Emit an event in one component and listen to it in anotherβno need for prop drilling or context juggling.
**Example:**
- A button in a header component emits an event to toggle a sidebar menu managed by a sibling component.
```tsx
// In Header component
emitEvent('toggleSidebar', { isVisible: true })
// In Sidebar component
useSubscribe('toggleSidebar', (eventName, payload) => setSidebarVisible(payload.isVisible))
```
### 2οΈβ£ **Global Notifications**
Create a centralized system for displaying notifications (like toast messages) triggered from anywhere in your app.
**Example:**
- A failed API call emits an event to show an error toast notification.
```tsx
emitEvent('showToast', { type: 'error', message: 'Failed to fetch data!' })
```
### 3οΈβ£ **Dynamic Data Updates**
Trigger UI updates in real-time when backend events or user actions occur.
**Example:**
- A WebSocket listener emits data updates that a dashboard component subscribes to for live charts or metrics.
```tsx
// WebSocket listener emits new data
emitEvent('updateMetrics', newMetrics)
// Dashboard listens to updates
useSubscribe('updateMetrics', (eventName, metrics) => updateChart(metrics))
```
### 4οΈβ£ **Hybrid State/Event Management**
Combine event-driven architecture with existing state management tools (e.g., Redux or Context API) for specific, modular use cases.
**Example:**
- Use events for decoupled interactions like resetting forms or syncing components without modifying the global state.
```tsx
// Emit form reset event
emitEvent('resetForm')
// Form component subscribes to reset action
useSubscribe('resetForm', (eventName, payload) => setFormData(initialValues))
```
By adopting `evently-react`, you can create scalable, decoupled, and maintainable solutions for modern web applications. π―
---
## π§ Usage
### Emitting Events
Use the `useEvent` hook to emit events:
```tsx
import React from 'react'
import { useEvent } from 'evently-react'
const EmitExample: React.FC = () => {
const { emitEvent } = useEvent()
const handleClick = () => {
emitEvent('exampleEvent', { message: 'Hello, Evently!' }) // Emit an event with a payload
}
return
}
export default EmitExample
```
### Subscribing to Events
Use the `useSubscribe` hook to listen to events:
```tsx
import React from 'react'
import { useSubscribe } from 'evently-react'
const SubscribeExample: React.FC = () => {
useSubscribe('exampleEvent', (eventName, payload) => {
console.log('Received payload:', payload) // Logs: { message: 'Hello, Evently!' }
})
return
Listening for events...
}
export default SubscribeExample
```
### Subscribing to Multiple Events
Use the enhanced `useSubscribe` hook to listen to multiple events:
```tsx
import React from 'react'
import { useSubscribe } from 'evently-react'
const MultiSubscribeExample: React.FC = () => {
useSubscribe(['eventOne', 'eventTwo'], (eventName, payload) => {
console.log(`Received payload for ${eventName}:`, payload)
})
return
Listening for multiple events...
}
export default MultiSubscribeExample
```
### Using State from Events
Leverage the `useSubscribeState` hook to access the latest event payload as state:
```tsx
import React from 'react'
import { useSubscribeState } from 'evently-react'
const StateExample: React.FC = () => {
const latestEventPayload = useSubscribeState('exampleEvent')
return
Latest Payload: {latestEventPayload?.message}
}
export default StateExample
```
---
## πΉοΈ Advanced Features
### Middlewares π
Middleware allows you to intercept or transform events before they are processed.
#### Global Middleware: `.use()`
```tsx
import { useEvent } from 'evently-react'
const App = () => {
const { eventBus } = useEvent()
eventBus.use((event, payload) => {
console.log(`Global Middleware: ${event}`)
return { ...payload, eventSeen: true }
})
return
Your App
}
```
#### Event-Specific Middleware: `.useForEvent()`
```tsx
eventBus.useForEvent('myEvent', (event, payload) => {
console.log(`Event middleware for ${event}`)
return { ...payload, transformed: true }
})
```
---
### In-Memory Caching π¦
Late subscribers can still receive the latest events:
```tsx
useSubscribe('exampleEvent', (eventName, payload) => {
console.log('Late subscriber received:', payload) // Works even if the event was emitted earlier
})
```
---
### Priority-Based Subscription π¦
Control the execution order of event handlers by assigning priorities. Higher priority callbacks execute first (default is `0`).
```tsx
// Low priority handler.
useSubscribe('important-event', (eventName, payload) => console.log('Low priority'), 1)
// High priority handler.
useSubscribe('important-event', (eventName, payload) => console.log('High priority'), 3)
```
Handlers are executed in descending order of priority, making it easy to manage complex event flows.
---
### Accessing EventBus Instance π
The `eventBus` instance, accessible via the `useEvent` hook, allows integration of `evently-react` into non-Component environments such as utility functions or external libraries. This enables advanced use cases like chaining events, transforming payloads, or other customized workflows.
#### Example: Using EventBus in Utility Functions
The following example demonstrates how to pass the `eventBus` instance to a utility function for chaining events:
```tsx
// Component file
import { useEvent } from 'evently-react'
import { handleEventChain } from './utils'
const Component = () => {
const { eventBus } = useEvent()
// Pass the eventBus instance to utility functions
handleEventChain('logoutUser', eventBus)
return