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.

Documentation in progress. This is the growing TypeScript documentation set, ported from the .NET docs. The guides below are complete; more (the service mesh, schema/spec generation, and the rest of the cookbook collection) are still being ported. For the complete API surface today, 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
  • 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, 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 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 Setup — the Azure Functions v4 model over HTTP, Service Bus, and Event Hub

• Integrations

  • Validation — reject bad requests before they reach your handler, via the Zod, Joi, and Yup 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, and parallel fan-out
  • 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.