@stackra/ts-events

Laravel-style event dispatcher for TypeScript with multiple drivers, wildcard matching, priority listeners, decorators, subscribers, and RxJS streaming.

Installation

pnpm add @stackra/ts-events

Features

• 🚀 Multi-driver dispatching: Memory, Redis, Null
• 🎯 Wildcard event matching (user.*, **)
• ⚡ Priority-based listener execution
• 🔁 One-time listeners via once()
• 🎭 @OnEvent and @Subscriber decorators
• 📡 RxJS observable streaming via asObservable()
• 🛑 Halt-on-first-response with until()
• 🏗️ EventsModule.forRoot() with DI integration
• ⚛️ React hooks: useEvents(), useEvent()
• 🏷️ DI tokens: EVENT_CONFIG, EVENT_MANAGER
• 📦 EventManager extends MultipleInstanceManager pattern
• 🔇 NullDispatcher for testing

Usage

Module Registration

/**
 * |-------------------------------------------------------------------
 * | Register EventsModule in your root AppModule.
 * |-------------------------------------------------------------------
 */
import { Module } from '@stackra/ts-container';
import { EventsModule } from '@stackra/ts-events';

@Module({
  imports: [
    EventsModule.forRoot({
      default: 'memory',
      dispatchers: {
        memory: { driver: 'memory', wildcards: true },
        redis: { driver: 'redis', connection: 'events' },
        test: { driver: 'null' },
      },
    }),
  ],
})
export class AppModule {}

Dispatching Events

/**
 * |-------------------------------------------------------------------
 * | Inject EventManager and dispatch events from services.
 * |-------------------------------------------------------------------
 */
import { Injectable, Inject } from '@stackra/ts-container';
import { EventManager, EVENT_MANAGER } from '@stackra/ts-events';

@Injectable()
export class UserService {
  constructor(@Inject(EVENT_MANAGER) private events: EventManager) {}

  async createUser(name: string) {
    const user = { id: '1', name };
    this.events.dispatcher().dispatch('user.created', user);
    return user;
  }
}

Decorators

/**
 * |-------------------------------------------------------------------
 * | Use @OnEvent on subscriber methods for declarative listening.
 * |-------------------------------------------------------------------
 */
import { Subscriber, OnEvent } from '@stackra/ts-events';

@Subscriber()
class UserSubscriber {
  subscribe() {}

  @OnEvent('user.created', { priority: 10 })
  onUserCreated(payload: any) {
    console.log('User created:', payload);
  }

  @OnEvent('user.*', { once: true })
  onAnyUserEvent(event: string, payload: any) {
    console.log(`[${event}]`, payload);
  }
}

React Hooks

/**
 * |-------------------------------------------------------------------
 * | useEvents() returns the EventManager from DI context.
 * |-------------------------------------------------------------------
 */
import { useEvents, useEvent } from '@stackra/ts-events';

function Notifications() {
  const events = useEvents();

  useEvent('notification.received', (payload) => {
    console.log('New notification:', payload);
  });

  return <div>Listening for notifications...</div>;
}

API Reference

| Export | Type | Description | | -------------------------- | ---------- | ------------------------------------------------------ | | EventsModule | Module | DI module with forRoot() static method | | EventManager | Service | Multi-driver manager (extends MultipleInstanceManager) | | EventService | Service | High-level API wrapping a single dispatcher | | MemoryDispatcher | Dispatcher | In-memory event dispatcher with wildcard support | | RedisDispatcher | Dispatcher | Redis-backed cross-process dispatcher | | NullDispatcher | Dispatcher | No-op dispatcher for testing | | @OnEvent(event, opts?) | Decorator | Mark a method as an event listener | | @Subscriber() | Decorator | Mark a class as an event subscriber | | @Channel(name) | Decorator | Bind a subscriber to a specific dispatcher channel | | useEvents() | Hook | Access EventManager from React context | | useEvent(event, handler) | Hook | Subscribe to an event in a component | | EVENT_CONFIG | Token | DI token for raw config object | | EVENT_MANAGER | Token | DI token (useExisting alias to EventManager) | | EventPriority | Enum | Priority levels: LOW, NORMAL, HIGH, CRITICAL | | defineConfig() | Utility | Type-safe config helper |

License

MIT