@majkapp/event-bus-types

Core type definitions and interfaces for type-safe event bus implementations.

Overview

This package provides the fundamental interfaces and types that define the contract for event bus implementations. It contains zero implementation code - only TypeScript interfaces, types, and type definitions.

Purpose

• Define Contracts: Establish clear interfaces for event bus implementations
• Type Safety: Provide strong TypeScript typing across implementations
• Portability: Enable multiple implementations (in-memory, distributed, persistent, etc.)
• Zero Dependencies: Pure TypeScript types with no runtime dependencies

Core Types

Event

The fundamental unit of communication:

interface Event<TPayload = any, TType extends string = string> {
  type: TType;
  payload: TPayload;
  timestamp: Date;
  metadata?: Record<string, any>;
}

EventFilter

Filter events by type, metadata, or custom predicates:

interface EventFilter<TPayload = any, TType extends string = string> {
  types?: TType | TType[];
  predicate?: (event: Event<TPayload, TType>) => boolean;
  metadata?: Record<string, any>;
}

EventListener

Function that handles events:

type EventListener<TPayload = any, TType extends string = string> = (
  event: Event<TPayload, TType>
) => void | Promise<void>;

Subscription

Handle to manage event subscriptions:

interface Subscription {
  unsubscribe(): void;
  readonly id: string;
  readonly active: boolean;
}

IEventChannel

Core channel interface for event distribution:

interface IEventChannel<TPayload = any, TType extends string = string> {
  readonly channelId: string;
  subscribe(listener, filter?, options?): Subscription;
  emit(event): void;
  clear(): void;
  getListenerCount(): number;
  getDiagnostics(): ChannelDiagnostics;
}

QueryableEventChannel

Enhanced channel with query builder:

interface QueryableEventChannel<TPayload = any, TType extends string = string>
  extends IEventChannel<TPayload, TType> {
  query(): QueryBuilder<TPayload, TType>;
  onEvent(type, listener, options?): Subscription;
}

QueryBuilder

Fluent API for building complex filters:

interface QueryBuilder<TPayload = any, TType extends string = string> {
  whereType(type): QueryBuilder<TPayload, TType>;
  where(predicate): QueryBuilder<TPayload, TType>;
  whereMetadata(key, value): QueryBuilder<TPayload, TType>;
  subscribe(listener, options?): Subscription;
}

Installation

npm install @majkapp/event-bus-types

Usage

import {
  Event,
  EventFilter,
  EventListener,
  Subscription,
  IEventChannel,
  QueryableEventChannel
} from '@majkapp/event-bus-types';

// Define your domain types
interface User {
  id: string;
  name: string;
}

type UserEventType = 'created' | 'updated' | 'deleted';

// Implement the interfaces
class MyEventChannel implements QueryableEventChannel<User, UserEventType> {
  // ... implementation
}

Implementations

This types package is used by:

• @majkapp/event-bus-local: In-memory implementation
• Future: Distributed, persistent, and other implementations

Benefits

For Library Authors

• Clear Contract: Implement the interfaces to create compatible event buses
• Type Safety: Full TypeScript support with generics
• Flexibility: Multiple implementations from one set of types

For Library Users

• Swap Implementations: Change implementations without code changes
• Type Consistency: Same types across all implementations
• No Vendor Lock-in: Interface-based design enables portability

Design Philosophy

1. Interface Segregation: Small, focused interfaces
2. Generics First: Full generic support for type safety
3. Zero Implementation: Only types, no runtime code
4. Future-Proof: Extensible without breaking changes

License

MIT