KafkaMessaging Design Philosophy - demingongo/kaapi GitHub Wiki

๐Ÿง  Design Philosophy

KafkaMessaging is built with a clear purpose: to provide a resilient, developer-friendly abstraction over KafkaJS without overcomplicating the interface or hiding essential control.

๐ŸŽฏ Focused Responsibility

This library handles:

  • Lifecycle management of producers, consumers, and admin clients
  • Automatic tracking and cleanup of Kafka resources
  • Graceful shutdown with timeout protection
  • Topic creation and readiness utilities for integration testing

It intentionally does not:

  • Expose the raw Kafka instance (getKafka() is protected)
  • Wrap every KafkaJS feature
  • Impose opinionated patterns on advanced use cases

Developers retain full control over KafkaJS clients via createAdmin() if needed.

๐Ÿ” Encapsulation with Flexibility

By exposing only createProducer, createConsumer, and createAdmin, the library ensures:

  • Safe resource tracking
  • Clean shutdown behavior
  • Reduced risk of memory leaks or unmanaged connections

Advanced users can still access KafkaJS features directly through the returned clients, but are encouraged to follow the lifecycle-aware methods provided.

๐Ÿงช Built for Real-World Testing

The library includes:

  • createTopic() for dynamic topic setup
  • waitForTopicReady() for metadata propagation
  • Integration test compatibility with Docker-based Kafka brokers

This makes it ideal for both production and CI environments.

๐Ÿ›  Extendable, Not Overengineered

Rather than wrapping every KafkaJS method, KafkaMessaging focuses on the 90% use case: reliable message flow with clean lifecycle boundaries. Developers are free to extend or compose it as needed.