@apogeelabs/hoppity

Contract-driven RabbitMQ topology builder for Node.js microservices, built on Rascal.

Declare your domain contracts, wire up handlers, and let Hoppity derive the entire RabbitMQ topology automatically. No manual topology files. No Rascal config by hand.

Installation

pnpm add @apogeelabs/hoppity
# or
npm install @apogeelabs/hoppity

Requires Node >= 22.

Quick Start

import { z } from "zod";
import hoppity, { defineDomain, onEvent, onCommand } from "@apogeelabs/hoppity";

// 1. Define your domain contracts
const OrdersDomain = defineDomain("orders", {
    events: {
        orderCreated: z.object({ orderId: z.string(), total: z.number() }),
    },
    commands: {
        cancelOrder: z.object({ orderId: z.string() }),
    },
});

// 2. Wire up handlers
const handleOrderCreated = onEvent(
    OrdersDomain.events.orderCreated,
    async (content, { broker }) => {
        console.log("New order:", content.orderId);
    }
);

const handleCancelOrder = onCommand(
    OrdersDomain.commands.cancelOrder,
    async ({ orderId }, { broker }) => {
        await cancelOrder(orderId);
    }
);

// 3. Build the service
const broker = await hoppity
    .service("order-service", {
        connection: { url: "amqp://localhost" },
        handlers: [handleOrderCreated, handleCancelOrder],
        publishes: [OrdersDomain.events.orderCreated],
        logger, // optional — defaults to ConsoleLogger
    })
    .build();

// 4. Use the broker
await broker.publishEvent(OrdersDomain.events.orderCreated, {
    orderId: "ord-123",
    total: 49.99,
});

await broker.shutdown();

Features

• Contract-driven topology — defineDomain + handlers = all exchanges, queues, bindings, publications, and subscriptions derived automatically
• Type-safe handlers — onEvent, onCommand, onRpc infer content types from Zod schemas at compile time
• RPC built in — broker.request() / broker.cancelRequest() with correlation IDs, timeouts, and typed responses
• Middleware pipeline — Cross-cutting concerns (logging, custom topology) via composable middleware
• Interceptors — Per-message wrappers for telemetry, tracing, metrics, and header injection
• Schema validation — Optional inbound/outbound Zod validation on every message
• Escape hatch — Pass raw Rascal BrokerConfig via topology in ServiceConfig for anything that can't be derived

API

Entry Point

import hoppity from "@apogeelabs/hoppity";

const builder = hoppity.service("my-service", config);
const broker = await builder.use(middleware).build();

ServiceConfig

interface ServiceConfig {
    connection: ConnectionConfig;
    handlers?: HandlerDeclaration[];
    publishes?: (EventContract | CommandContract | RpcContract)[];
    interceptors?: Interceptor[]; // per-message wrappers for telemetry, tracing, metrics
    logger?: Logger; // custom logger — replaces ConsoleLogger for entire build pipeline
    topology?: BrokerConfig; // raw Rascal config — merged as base
    instanceId?: string; // auto-generated UUID if omitted
    defaultTimeout?: number; // RPC timeout in ms (default 30_000)
    validateInbound?: boolean; // default true
    validateOutbound?: boolean; // default false
}

ServiceBroker

Returned by .build(). Extends Rascal's BrokerAsPromised with:

• publishEvent(contract, message, overrides?) — publish a domain event
• sendCommand(contract, message, overrides?) — send a domain command
• request(contract, message, overrides?) — make an RPC call
• cancelRequest(correlationId) — cancel a pending RPC request

Interceptors

Interceptors wrap handler execution (inbound) and publish calls (outbound) on every message. They're the right place for telemetry, tracing, metrics, and header injection — anything that needs to observe or modify message processing at runtime.

interface Interceptor {
    name: string;
    inbound?: InboundWrapper; // wraps event, command, and RPC handler execution
    outbound?: OutboundWrapper; // wraps publishEvent, sendCommand, and request calls
}

Either field is optional — an interceptor can be inbound-only, outbound-only, or both.

Example: handler timing

import hoppity, { Interceptor } from "@apogeelabs/hoppity";

const withHandlerTiming: Interceptor = {
    name: "handler-timing",
    inbound: (handler, meta) => async (payload, ctx) => {
        const start = performance.now();
        try {
            return await handler(payload, ctx);
        } finally {
            console.log(`${meta.contract._name} took ${performance.now() - start}ms`);
        }
    },
};

const broker = await hoppity
    .service("order-service", {
        connection: { url: process.env.RABBITMQ_URL },
        handlers: [handleOrderCreated],
        publishes: [OrdersDomain.events.orderCreated],
        interceptors: [withHandlerTiming],
    })
    .build();

Composition

For interceptors: [A, B], the call chain is A → B → handler → B → A. The first interceptor in the array is the outermost wrapper.

Inbound wrappers receive InboundMetadata — the contract, operation kind ("event" | "command" | "rpc"), service name, and AMQP message headers. Outbound wrappers receive OutboundMetadata — the contract, kind, and service name.

Interceptors vs. middleware

| | Middleware (.use()) | Interceptors | | -------- | ------------------------------------ | ---------------------------------- | | When | Before broker creation | During message processing | | What | Modifies topology, lifecycle hooks | Wraps handler/publish execution | | Scope | Service-level setup | Per-message | | Examples | Custom logger, topology augmentation | Tracing, metrics, header injection |

Interceptor Packages

@apogeelabs/hoppity-open-telemetry provides production-ready withTracing and withMetrics interceptors built on @opentelemetry/api. Both are dual-use: pass them directly as values for default configuration, or call them as factories to supply a custom tracer/meter name or histogram buckets. withTracing handles W3C context propagation across service boundaries automatically — trace context is injected into AMQP headers on publish and extracted on receive, so spans link up without any extra plumbing.

Documentation

• ReadMe.LLM — complete API reference with all type signatures
• llms-usage.md — LLM code generation guide for this package

License

ISC