Benzene Cookbooks

Practical recipes for common real-world scenarios using the TypeScript port of Benzene.

What are cookbooks?

Cookbooks are step-by-step guides that show you how to solve a specific problem with Benzene. Each one focuses on a single use case and gives you complete, copy-pasteable TypeScript you can adapt to your own service — the same three-level documentation set the .NET original ships, ported to npm, ESM, and vitest.

If you're new to Benzene, start with Getting Started and the docs index first; the cookbooks assume you already have a handler and a host wired up.

Available cookbooks

AWS

• Handling SQS Message Failures — report only the messages that actually failed back to SQS for redelivery, retry transient errors in-process, and let permanent failures fall through to a dead-letter queue.
• SNS Fan-Out Pattern — publish one event to an SNS topic and have several independently-deployed Lambda functions each process their own copy of it.
• S3 Event Processing (coming soon)

Reliability & Workflow

• Idempotency — make a handler safe to invoke more than once, so an at-least-once transport (SQS, SNS, retries) can't apply the same effect twice.
• Sagas — coordinate a multi-step workflow across services with compensating rollback when a later step fails.
• Global Error Handling — catch any thrown error at the pipeline edge, log it, and map it to a safe error result without leaking internals.

Messaging & Integration

• Response as Event — publish a domain event derived from a handler's result, either by explicit mapping or the CRUD naming convention.

Security

• Auth Patterns — establish authentication (Basic, OAuth2/bearer) and authorize per-handler with requireRole/requireScope/requirePolicy.

Architecture & Testing

• Secrets & Configuration — resolve secrets through composable stores (env var, file, in-memory, cached), and adapt a cloud secret manager against the ISecretStore seam.
• Bring Your Own DI Container — the default container, the static inject convention, and adapting an external container against Benzene's DI contracts.
• Mocking External Dependencies — test a handler in isolation by swapping its real dependencies (databases, HTTP clients, cloud SDKs) for fakes registered in the container, while still running the message through the real pipeline.
• Per-Request Unit of Work — commit a scoped unit of work when the pipeline succeeds and roll it back when it fails, transport-independently, via unitOfWorkMiddleware.

Cookbook structure

Each cookbook follows the same shape:

1. Problem Statement — what you're trying to achieve.
2. Prerequisites / Installation — what you need, and the npm install @benzene/… packages.
3. Step-by-Step Implementation — a detailed walkthrough with complete, runnable code.
4. Testing — how to verify it with vitest.
5. Troubleshooting — common issues and fixes.
6. Variations — alternative approaches or extensions.
7. Further Reading — related docs and resources.

See also

• Documentation index — the full docs tree.
• Getting Started — from an empty folder to a running service.
• AWS Lambda Setup — hosting the same handler on Lambda.
• Testing Benzene — the complete testing guide.