A Ruby gem for functional flow control that chains service objects and blocks, providing a new approach to error handling and command execution.
Waterfall is a Ruby gem that provides a functional programming approach to flow control by chaining service objects and blocks. It solves the problem of managing complex application logic and error handling in a readable, maintainable way by allowing developers to define flows where commands execute sequentially, and errors dam the flow to bypass subsequent steps.
Ruby developers building service-oriented architectures, especially those working with Rails applications who need to manage complex business logic, error handling, and database transactions across multiple service objects.
Developers choose Waterfall for its elegant chaining syntax, robust error management with dam/on_dam patterns, and seamless integration with Rails transactions, making it ideal for writing intention-revealing code that handles both happy and unhappy paths cleanly.
A slice of functional programming to chain ruby services and blocks, thus providing a new approach to flow control. Make them flow!
Open-Awesome is built by the community, for the community. Submit a project, suggest an awesome list, or help improve the catalog on GitHub.
Enables clear, sequential chaining of service objects and blocks, with execution continuing only on success, as shown in the FetchUser example where commands are linked in a flow.
Uses `dam` to halt flows on errors, bypassing subsequent commands and triggering `on_dam` blocks for reporting, providing a clean separation of happy and unhappy paths.
Offers a `with_transaction` method to wrap flows in database transactions, ensuring automatic rollback when dammed, as demonstrated in the Rails setup example with ActiveRecord.
Includes `reverse_flow` methods to undo actions in previously executed services if a later step fails, complementing transaction-based rollback for non-database side effects.
Core features like transaction support and recommended error handling with ActiveModel::Validations are tightly coupled to Rails, making it less useful for pure Ruby or other frameworks.
Chaining requires careful attention to block return values; for instance, returning a Waterfall object without calling its method is necessary for automatic chaining, as noted in the syntactic sugar section, which can be error-prone.
Designed for sequential execution, it doesn't natively support branching or parallel flows, which might be restrictive for complex, concurrent logic not fitting a linear model.