Benzene (TypeScript)

Benzene is a hexagonal framework for services running in serverless environments, containers, or on physical servers. It supports multiple cloud providers and provides a unified programming model for message-based architectures. This is the TypeScript port of Benzene — you write a message handler once and host it unchanged on Express, AWS Lambda, or Azure Functions.

New to Benzene? Start with Getting Started — a small HTTP service running locally in about five minutes, no cloud account needed. Note that the @benzenejs/* packages aren't published to npm yet; that guide explains how to work from the cloned workspace in the meantime.

Documentation in progress. This TypeScript documentation set is being ported from the .NET docs. The guides below and the full cookbook collection are complete; a few areas (the service mesh UI and usage feed) are still being ported — for the mesh today, the mesh-service example is runnable. For the complete API surface, see the repository README, and for runnable projects covering every transport, the examples/ folder.

Main Themes

• General

  • Getting Started — build and run your first Benzene service in about five minutes
    • AWS Lambda — one function over API Gateway, SQS, SNS, EventBridge, and Kafka
    • Azure Functions — HTTP, Service Bus, and Event Hub triggers
    • Google Cloud Functions — HTTP + Pub/Sub
    • gRPC — expose handlers over a gRPC server and call other services
    • Kafka — run your handlers as a self-hosted Kafka consumer-group worker
    • Kubernetes — one handler hosted over HTTP, SQS, and Kafka from a single process and Deployment
  • Unified Hosting Model — the same handler on Express, AWS Lambda, Azure Functions, or a self-hosted worker
  • Message Handlers — the components that process a message, and how they're discovered and routed
  • Message Results — IBenzeneResultOf<T>, the BenzeneResult factory, RFC 9457 problem documents, and how statuses map onto each transport
  • Middleware — the pipeline mechanism every request flows through
  • Common Middleware — the ready-made middleware Benzene ships
  • Correlation IDs — trace a request end-to-end across services
  • Monitoring & Diagnostics — tracing, metrics, and logging via OpenTelemetry
  • Sampling Strategies — control how much tracing you keep in production
  • Diagnosing Failures — a message failed in production; find out why across results, logs, traces, and metrics
  • Health Checks — liveness/readiness checks and the built-in disk/HTTP/TCP/database checks
  • Kubernetes Health Checks — wiring liveness/readiness probes for K8s
  • Testing Benzene — test handlers in isolation and drive whole transport pipelines in-memory with vitest
  • Payload Testing — build demo payloads and send them into a service by topic

• Cloud Providers

  • AWS
    • AWS Lambda Setup — API Gateway, SQS, SNS, EventBridge, and Kafka, plus the one-function-per-transport vs composite deployment models
  • Azure
    • Azure Functions — getting started — one set of handlers over HTTP, Service Bus, and Event Hub triggers
    • Azure Functions Setup — the Azure Functions v4 model over HTTP, Service Bus, and Event Hub
  • Google Cloud
    • Google Cloud Functions — getting started — one set of handlers over HTTP + Pub/Sub

• Messaging

  • Getting started with gRPC — expose handlers over a gRPC server and call other services with the gRPC client binding
  • Getting started with Kafka — run your handlers as a self-hosted Kafka consumer-group worker

• Integrations

  • Validation — reject bad requests before they reach your handler, via the Zod, Joi, Yup, and JSON Schema (ajv) adapters
  • Serialization & Media Formats — JSON by default, plus the XML, MessagePack, and Avro adapters
  • Schema Registry — register and evolve message schemas across services
  • Rate Limiting — fixed-window, token-bucket, and payload-size limiting

• Clients & Resilience

  • Clients — call other Benzene services with outbound routing, retries, parallel fan-out, and the in-process transport (@benzenejs/clients-in-process) for the modular monolith
  • Generating a client from a Contract Document — a typed, topic-scoped client from any Benzene service's committed .spec.json, no other language's SDK required
  • Caching — the cache abstraction and the Redis-backed adapter
  • Resilience — retry-with-backoff around a pipeline stage

• Cookbooks

  • Cookbooks — practical recipes for real-world scenarios

About the port

Benzene TypeScript mirrors the .NET library's structure, names, and file layout as closely as the language allows; ported tests come from the C# suite. Where the two necessarily differ — free functions instead of extension methods, Promise instead of Task, decorators instead of attributes, Zod/Joi/Yup instead of FluentValidation/DataAnnotations — the reasons are recorded in the README's Porting conventions. Every doc here uses the real, current TypeScript API; when in doubt, the src/ in the repository is the source of truth.

The language-neutral parts of Benzene — the core concepts, wire contracts, status vocabulary, mesh shapes, and the Cloud Service Profile — are defined once, for every language, in the cross-language Benzene specification. The docs here cover the TypeScript surface of those contracts and link to the spec for the normative detail.

Maintaining

• Publishing — how the packages are released to npm under the @benzenejs scope (trusted publishing, beta dist-tag). Benzene ships as many small packages — one per capability, so a service depends only on the transports and integrations it actually uses.

Edit this page on GitHub