Have you ever worked on code that evolves so quickly that not only it gives you anxiety, but becomes technical debt over time?
Apparatus is a very simple architectural way to solve this. It uses composition over inheritance and is a (very) simple ECS (entity-component-system) implementation.
It decouples data and logic.
It ensures your complex code parts are highly structured and easy to understand and modify:
- code is organized and tidy by default
- data is always separated from logic
- adding, removing, modifying data and logic is easy
- complete freedom how data is shaped
- very easy to to see what is being done at a glance
Only use this gem for the business logic that is very volatile:
- there are or will be a lot of changes in the business logic
- feature requests come frequently and are aplenty
- you still have no idea how to structure your complex piece of code
gem install apparatus
Add the following to your Gemfile:
gem "apparatus"
Let's build code that outputs delivery methods to the standard output. We have a imaginary cart and three shipping methods.
require "apparatus"
# aliases (optional)
Entity = Apparatus::Entity
System = Apparatus::System
# component classes
Type = Struct.new(:value)
Name = Struct.new(:value)
Identifier = Struct.new(:value)
Price = Struct.new(:value)
WeightInKg = Struct.new(:value)
Boolean = Struct.new(:value)
# entities
delivery = Entity.new({
type: Type.new("delivery_method"),
identifier: Identifier.new("delivery"),
name: Name.new("Delivery by courier"),
price: Price.new(3.99)
})
pickup = Entity.new({
type: Type.new("delivery_method"),
identifier: Identifier.new("pickup"),
name: Name.new("Pickup in closest store"),
price: Price.new(0.0)
})
pigeon = Entity.new({
type: Type.new("delivery_method"),
identifier: Identifier.new("pigeon"),
name: Name.new("Delivery by pigeon"),
price: Price.new(50.0)
})
cart = Entity.new({
type: Type.new("cart"),
total_price: Price.new(27.0),
total_weight: WeightInKg.new(5.0)
})
# systems
class PrintShippingMethods < System
def run
entities.each do |entity|
next if !entity.has?(:type, :price)
next if entity[:type].value.to_s != "delivery_method"
name, price, enabled = entity[:name], entity[:price], entity[:enabled]
next if enabled && !enabled.value
puts "#{name.value} (#{price.value} €)"
end
end
end
class EnableDeliveryMethods < System
def run
cart = entities.find { _1.has?(:type) && _1[:type].value.to_s == "cart" }
return if !cart
delivery_methods = entities.select do |entity|
entity.has?(:type, :identifier) &&
entity[:type].value.to_s == "delivery_method"
end
delivery_methods.each do |delivery_method|
delivery_method[:enabled] = delivery_method[:identifier].value.to_s == "pigeon" ?
Boolean.new(cart[:total_weight].value < 0.1) :
Boolean.new(true)
end
end
end
# apparatus itself
apparatus = Apparatus::Body.new
apparatus.add_entities(delivery, pickup, pigeon, cart)
apparatus.add_systems(
EnableDeliveryMethods,
PrintShippingMethods
)
# run all systems
apparatus.run
If you run this code, the output is following:
Delivery by courier (3.99)
Pickup in closest store (0.0)
Delivery by pigeon is missing, because the cart weight is too heavy and pigeon cannot bring you (imaginary) package.
However if you comment the line EnableDeliveryMethods,
and run the code again, the output changes to:
Delivery by courier (3.99)
Pickup in closest store (0.0)
Delivery by pigeon (50.0)
I think you should notice some positive things about the basic example:
- Component classes are really simple classes that can be of any shape that is useful to you. I chose
Struct
, but it can be anything: custom class, String, Integer, etc. - An entity is just a collection of components
- A system just processes entities one by one
- When apparatus is run, each system is run one by one
- Nowhere did I call a loose method on a data object: data is data and has no logic; all logic lies within systems
- I can easily disable any amount of systems if needed without breaking the apparatus
- The whole implementation is very linear and easy to read
- Code is easy to debug (just use
puts
orbyebug
)
This is not THE SOLUTION.
This gem is not meant to be used always, everywhere. It shines when you have suspicion that the incoming feature will be extremely volatile (business logic will change a lot or complexity will grow, there might be a lot of feature requests, etc).
If you check the source code of this gem, it is absurdly simple. However, with simplicity come the drawbacks:
- No magic
- No queries or cached queries
- Almost no helper methods
- If you have not encountered ECS, then apparatus might seem strange
There are alternatives that have a lot more features:
After checking out the repo, run bin/setup
to install dependencies. Then, run make check
to run the checks (rubocop + tests). You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and the created tag, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/pirminis/apparatus.
The gem is available as open source under the terms of the MIT License.