Stone.js - Event Bus

Agnostic cloud event bus for Stone.js. emit on one side, @OnBusEvent on the other. The core EventEmitter already handles in-process events; this module handles the cloud: publish domain events to local and/or cloud targets, and route incoming bus events to their handlers via the key-router, on any simple cloud adapter (AWS Lambda, GCP, Azure...). No dedicated adapter: the listener side injects itself as the kernel event handler, exactly like @stone-js/router. The core is never touched.

Installation

npm install @stone-js/event-bus

# the EventBridge driver (optional peer, imported lazily):
npm install @aws-sdk/client-eventbridge

Peer dependency: @stone-js/core. @aws-sdk/client-eventbridge is an optional peer, imported lazily.

Emit

import { StoneApp } from '@stone-js/core'
import { EventBus } from '@stone-js/event-bus'

@EventBus({ driver: 'eventbridge', source: 'my.app' })
@StoneApp({ name: 'orders' })
export class Application {}

eventBus is injected. Emit to the default targets, or pick them per call:

export class OrderService {
  constructor (private readonly eventBus) {}

  async ship (order) {
    // reaches in-process listeners AND the cloud bus: same code, monolith or distributed
    await this.eventBus.emit('order.shipped', { id: order.id }, { targets: ['local', 'cloud'] })
  }
}

• local uses the app's own EventEmitter (used, never modified).
• cloud publishes through the driver (EventBridge PutEvents).

Listen (on any cloud adapter)

The listener side is the light key-router from @stone-js/router: @BusListener, @BusHandler and @OnBusEvent are bus-flavoured aliases of @KeyRouting, @KeyHandler and @OnKey. It installs itself as the kernel event handler and plugs onto a simple cloud adapter (here AWS Lambda); the adapter receives the event, the light router routes it to the handler.

import { StoneApp } from '@stone-js/core'
import { AwsLambda } from '@stone-js/aws-lambda-adapter'
import { BusListener, BusHandler, OnBusEvent } from '@stone-js/event-bus'

@BusListener({ source: 'detail-type' })   // which incoming property carries the routing key
@AwsLambda()
@StoneApp({ name: 'consumer' })
export class Application {}

@BusHandler()
export class Orders {
  @OnBusEvent('order.shipped')   async onShipped (payload) { /* … */ }
  @OnBusEvent('order.cancelled') async onCancelled (payload) { /* … */ }
}

The routing-key source defaults to detail-type (where the EventBridge driver puts the event name, so the pair round-trips). It is not hard-coded: set another property, or pass a full extractor via @BusListener({ extractor }) for any bus shape.

Drivers

| driver | backing | notes | | ------------- | ------------- | -------------------------------------------------------------- | | local | built-in | The app's EventEmitter. In-process delivery. | | memory | built-in | Records emitted messages (tests / local dev). | | eventbridge | AWS SDK | PutEvents (Source / DetailType / Detail). Rules fan out to consumers. |

License

MIT