⚠️ Package Deprecated

The @snapback-oss/events package has been deprecated. Please visit vreko.dev for information about the Vreko platform.

Migration Information

This package is no longer maintained. If you were using this package, please update your dependencies accordingly.

What This Means

• This npm package has been deprecated
• No further updates will be made to this codebase
• This repository is kept for historical reference

License

This repository remains available under the Apache-2.0 license for reference purposes.

Quick Start

import { EventBus } from '@snapback-oss/events';

// Create event bus
const events = new EventBus();

// Subscribe to events
events.on('user.created', (data) => {
  console.log('New user:', data);
});

// Emit events
events.emit('user.created', { id: '123', name: 'Alice' });

// Wildcard support
events.on('user.*', (data) => {
  console.log('Any user event:', data);
});

Features

• 🎯 Type-Safe: Full TypeScript support
• 🌲 Namespacing: Organize events with dot notation
• 🔍 Wildcards: Listen to patterns like user.*
• ⚡ Fast: Built on EventEmitter2
• 🪶 Lightweight: Minimal dependencies

API Reference

Basic Usage

import { EventBus } from '@snapback-oss/events';

const bus = new EventBus();

// Subscribe
bus.on(event, handler);
bus.once(event, handler);
bus.off(event, handler);

// Emit
bus.emit(event, data);

// Check listeners
bus.listenerCount(event);

Namespaced Events

// Organize events hierarchically
bus.emit('user.created', user);
bus.emit('user.updated', user);
bus.emit('user.deleted', userId);

// Listen to all user events
bus.on('user.*', (data) => {
  console.log('User event:', data);
});

Multiple Listeners

// Multiple handlers for same event
bus.on('order.placed', logOrder);
bus.on('order.placed', sendEmail);
bus.on('order.placed', updateInventory);

// All execute when event fires
bus.emit('order.placed', orderData);

Error Handling

// Handle errors in listeners
bus.on('error', (err) => {
  console.error('Event bus error:', err);
});

// Errors in handlers are caught
bus.on('risky.event', () => {
  throw new Error('Oops');
});

Examples

Simple Pub/Sub

const events = new EventBus();

// Publisher
function createUser(name: string) {
  const user = { id: Date.now(), name };
  events.emit('user.created', user);
  return user;
}

// Subscriber
events.on('user.created', (user) => {
  console.log(`Welcome ${user.name}!`);
});

createUser('Alice');
// Output: Welcome Alice!

Event Aggregation

// Collect events
const userEvents: any[] = [];

events.on('user.*', (data) => {
  userEvents.push(data);
});

events.emit('user.created', { id: 1 });
events.emit('user.updated', { id: 1 });
events.emit('user.deleted', { id: 1 });

console.log(userEvents.length); // 3

What's Included

Public API (OSS)

• ✅ EventEmitter2 wrapper
• ✅ Type-safe event definitions
• ✅ Wildcard support
• ✅ Namespace support

Not Included (Private)

• ❌ Platform-specific events
• ❌ Config/SDK integration hooks

Configuration

const bus = new EventBus({
  wildcard: true,        // Enable wildcards (default: true)
  delimiter: '.',        // Namespace delimiter (default: '.')
  maxListeners: 10,      // Max listeners per event
  verboseMemoryLeak: false
});

TypeScript Support

// Define your events
interface AppEvents {
  'user.created': { id: string; name: string };
  'user.updated': { id: string; changes: any };
  'user.deleted': { id: string };
}

// Type-safe event bus
const bus = new EventBus<AppEvents>();

// TypeScript knows the event data types
bus.on('user.created', (data) => {
  // data is { id: string; name: string }
  console.log(data.name);
});

Contributing

See CONTRIBUTING.md

pnpm install
pnpm build
pnpm test

Links

• Documentation: docs.snapback.dev
• Main Repository: Marcelle-Labs/snapback.dev
• NPM: @snapback-oss/events

Related Packages

• @snapback-oss/contracts - Type definitions
• @snapback-oss/sdk - Client SDK

License

Apache-2.0 © SnapBack