Add this line to your application's Gemfile:
gem 'nanites', github: 'tstaetter/nanites', branch: 'main'
And then execute:
$ bundle install
When available on rubygems.org, you can install it yourself as:
$ gem install nanites
TODO: Push gem to rubygems when initial release is ready
Using the commands is pretty straight forward (see specs/support for more examples).
class MyCommand < Nanites::Commands::Command
def execute(**params)
# your code here
if all_went_well
success success_payload
else
error error_payload
end
end
end
# Be sure to only use the class method #execute, it ensures save execution
result = MyCommand.execute some_payload
puts result.option if result.success?
# => Nanites::Some @value=<success payload>
Result values are always wrapped in an Nanites::Option
object which
either is a Nanites::Some
indicating some return value is available or
Nanites::None
for no value.
This is done in order to not having the hassle to deal with nil
values. This
approach is inspired by the Option type in Rust.
Compounds can be used to combine several commands. A little example:
cmd1 = SomeUsefulCommand.new payload
cmd2 = SomeAnalyticsCommand.new payload
compound = Nanites::Commands::Compound.new cmd1, cmd2
context = compound.execute
# => 'context' is a hash containing the execution results of each command with the commands ID as key
There are some specials compounds as well, e.g. FirstSomeCompound
returning the first result option which is
a Some
, or MatchSomeCompound
returning only results of commands returning Some
options.
For a full list of special compounds see lib/nanites/compounds
. Implementing your own specialized compound is
as easy as the following (taken from lib/nanites/compounds/match_some_compound.rb
):
class MatchSomeCompound < Compound
def initialize(*nanites)
super
@filter = ->(result) { result.option.some? }
end
end
The magic happens here in the line @filter = ->(result) { result.option.some? }
defining lambda checking the result.
The filter is applied within the parent class execute
method, getting passed each command result.
Some
and None
are both descendants of Option
. Each call of Nanites::Commands::Command#execute
will
return either a Some
or None
, indicating that the call returns some value, or no value resp.
When using those values, calling None#value
will always return nil. If you need to have an error raised, use None#value!
.
Taking the example from the above code, the behaviour is as follows:
puts result.option.value
# => will return some value if result.success? is true, nil otherwise
puts result.option.value!
# => will return some value if result.success? is true, raise a Nanites::Errors::ValueError otherwise
rake spec
to run the tests.
Bug reports and pull requests are welcome on GitHub at https://github.com/tstaetter/nanites.