Domain-eventrix NPM

domain-eventrix

A powerful TypeScript library for managing domain events with seamless integration for React, React Native, and Domain-Driven Design (DDD). Built to enhance event-driven architectures with features like retry strategies, dead letter queues, and state management.

Features

🚀 Robust event bus implementation with TypeScript support
🔄 Built-in retry strategies and dead letter queue
📊 Event processing state management
⚛️ First-class React and React Native integration
🏛️ DDD-friendly with aggregate root support
🔍 Event monitoring system
🎨 Flexible configuration options

Installation

npm install domain-eventrix
# or
yarn add domain-eventrix
# or
pnpm add domain-eventrix

Quick Start

1. Create an Event Bus

import DomainEventrix from "domain-eventrix"

// Create a shared (default) event bus
DomainEventrix.create()

// Or create a named event bus
DomainEventrix.create({
  eventBusKey: "CustomEventBus",
  enableStateManagement: true
})

2. Define Events and Handlers

import { DomainEvent, DomainEventMessage, EventHandler, DomainEventHandler } from "domain-eventrix"

// Define an event
@DomainEventMessage("UserRegistered")
class UserRegisteredEvent extends DomainEvent<User> {
  constructor(user: User) {
    super(user)
  }
}

// Define a handler
@DomainEventHandler(UserRegisteredEvent, {
  message: "Handle user registration",
  isVisibleOnUI: true
})
class UserRegistrationHandler extends EventHandler<User, UserRegisteredEvent> {
  async execute(event: UserRegisteredEvent): Promise<void> {
    const user = event.data
    // Handle the registration
    console.log(`User registered: ${user.name}`)
  }
}

3. Use the Event Bus

const eventBus = DomainEventrix.get() // Get shared bus
// or
const customBus = DomainEventrix.get("CustomEventBus") // Get named bus

// Publish events
eventBus.publish(new UserRegisteredEvent(user))
// or publish and execute immediately
eventBus.publishAndDispatchImmediate(new UserRegisteredEvent(user))

Core Concepts

Event Bus Types

Domain-eventrix provides two types of event buses:

SharedEnhancedEventBus (Default)
- Singleton instance shared across your application
- Perfect for most use cases
EnhancedEventBus
- Named instances for specific contexts
- Useful when you need isolated event handling

Event Processing Features

Retry Strategy: Configurable retry attempts for failed event processing
Dead Letter Queue: Handle persistently failed events
State Management: Track event processing status
Monitoring: observe event flow and processing metrics

Advanced Usage

Domain-Driven Design Integration

import { AggregateEventDispatcher, Aggregate } from 'domain-eventrix/ddd'

class UserAggregate implements Aggregate {
  private domainEvents: DomainEvent<any>[] = []
  
  constructor(public id: string, public name: string) {}
  
  register() {
    const event = new UserRegisteredEvent({ id: this.id, name: this.name })
    this.domainEvents.push(event)
    AggregateEventDispatcher.get().queueAggregateForDispatch(this)
  }
  
  getDomainEvents() { return this.domainEvents }
  getID() { return this.id }
  clearDomainEvent() { this.domainEvents = [] }
}

// Usage
const user = new UserAggregate("1", "John Doe")
user.register()
AggregateEventDispatcher.get().dispatchEventsForMarkedAggregate(user.id)

React Integration

Setup Event Provider

// eventrix.config.ts
import DomainEventrix from "domain-eventrix"

DomainEventrix.create({
  eventBusKey: "ReactApp",
  enableStateManagement: true
})

// App.tsx
import { EventProvider } from "domain-eventrix/react"
import "./eventrix.config"

function App() {
  return (
    <EventProvider eventBusKey="ReactApp">
      <YourApp />
    </EventProvider>
  )
}

Use Hooks

import { 
  useEventBus,
  useEventContext,
  useEventBusMethods,
  useEventProcessingState
} from "domain-eventrix/react"

function UserComponent() {
  const { publish } = useEventBusMethods()
  
  const handleRegister = () => {
    publish(new UserRegisteredEvent({ name: "John Doe" }))
  }
  
  // Monitor event processing
  useEventProcessingState(state => {
    console.log('Current processing state:', state)
  })
  
  return <button onClick={handleRegister}>Register User</button>
}

Configuration Options

DomainEventrix.create({
  eventBusKey?: string,           // Custom event bus identifier
  enableStateManagement?: boolean, // Enable processing state tracking
  enableMonitoringSystem?: boolean,// Enable event monitoring
  enableRetrySystem?: boolean,     // Enable retry strategy
  retryAttempts?: number,         // Number of retry attempts
  initialRetryDelay?: number,     // Initial delay between retries (ms)
  maxRetryDelay?: number,         // Maximum delay between retries (ms)
  deadLetterQueueSize?: number    // Size of dead letter queue
})

Usage

Best Practices

Event Bus Creation
- Use DomainEventrix.create() at your application's entry point
- Configure options based on your environment needs
Event Handling
- Keep handlers focused and single-purpose
- Handle errors appropriately in execute methods
- Use TypeScript for better type safety
React Integration
- Initialize configuration before rendering
- Use hooks for accessing event bus functionality
- Monitor processing state for better UX
DDD Implementation
- Keep aggregates focused and consistent
- Dispatch events after completing business logic
- Clear domain events after successful dispatch

Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.