Sn::Foil

Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file lib/sn_foil. To experiment with that code, run bin/console for an interactive prompt.

TODO: Delete this and the text above, and describe your gem

Installation

Add this line to your application's Gemfile:

gem 'snfoil'

And then execute:

$ bundle

Or install it yourself as:

$ gem install snfoil

Usage

Major Components

Model

Policy

Searcher

Contexts

Contexts are groupings of common actions that a certain entity can perform.

Data

Actions

SnFoil Contexts handle basic CRUD through a few different actions

Action Description
Build The action on setting up a model but not persiting.
Author's note: So far I have just been using this so factories in testing follow the same setup logic as a context would.
Create The action of setting up a model and persisting it.
Update The action of finding a pre-existing model and updating the attributes.
Destroy The action of finding a pre-existing model and destroying it.
Show The action of finding a pre-existing model by an identifier.
Index The action of finding a pre-existing models by using a searcher.

Methods

Methods allow users to create inheritable actions that occur in a specific order. Methods will always run before their hook counterpart. Since these are inheritable, you can chain needed actions all the way through the parent heirarchy by using the super keyword.

Important Note Methods always need to return the options hash at the end.

Author's opinion: While simplier than hooks, they do not allow for as clean of a composition as hooks.

Example

# Call the webhooks for third party integrations
# Commit business logic to internal process
def after_create_success(**options)
    options = super

    call_webhook_for_model(options[:object])
    finalize_business_logic(options[:object])

    options
end

# notify error tracker
def after_create_error(**options)
    options = super

    notify_errors(options[:object].errors)

    options
end

Hooks

Hooks make it very easy to compose multiple actions that need to occur in a specific order. You can have as many repeated hooks as you would like. This makes defining single responsibility hooks very simple, and they will get called in the order they are defined. The major downside of hooks are that they are currently not inheritable.

Important Note Hooks always need to return the options hash at the end.

Example

Lets take the Method example and make it into hooks instead.

# Call the webhooks for third party integrations
after_create_success do |options|
    call_webhook_for_model(options[:object])
    options
end

# Commit business logic to internal process
after_create_success do |options|
    finalize_business_logic(options[:object])
    options
end

# notify error tracker
after_create_error do |options|
    notify_errors(options[:object].errors)
    options
end

Name Timing Description
setup -Always at the beginning Primarily used for basic setup logic that always needs to occur
setup_<action> -Before the object has been found or created Primarily used for basic setup logic that only needs to occur for certain actions
before_<action>
-After the object has been found or created
-Before the object has been persisted/altered
after_<action>success -After the object has been successfully been persisted/altered
after<action>failure -After an error has occured persisting/altering the object
after<action> -Always at the end

Call Order

The call order for actions is extremely important because SnFoil passes the options hash throughout the entire process. So any data you may need down the call order can be added earlier in the stack.

Action Order
Type Name
Build
Method setup
Hooks setup
Method setup_build
Hooks setup_build
Create
Method setup
Hooks setup
Method setup_build
Hooks setup_build
Method setup_change
Hooks setup_change
Method setup_create
Hooks setup_create
Method before_change
Hooks before_change
Method before_create
Hooks before_create
Method *after_change_success
Hooks *after_change_success
Method *after_create_success
Hooks *after_create_success
Method *after_change_failure
Hooks *after_change_failure
Method *after_create_failure
Hooks *after_create_failure
Method after_change
Hooks after_change
Method after_create
Hooks after_create
Update
Method setup
Hooks setup
Method setup_change
Hooks setup_change
Method setup_update
Hooks setup_update
Method before_change
Hooks before_change
Method before_update
Hooks before_update
Method *after_change_success
Hooks *after_change_success
Method *after_update_success
Hooks *after_update_success
Method *after_change_failure
Hooks *after_change_failure
Method *after_update_failure
Hooks *after_update_failure
Method after_change
Hooks after_change
Method after_update
Hooks after_update
Destroy
Method setup
Hooks setup
Method setup_change
Hooks setup_change
Method setup_destroy
Hooks setup_destroy
Method before_change
Hooks before_change
Method before_destroy
Hooks before_destroy
Method *after_change_success
Hooks *after_change_success
Method *after_destroy_success
Hooks *after_destroy_success
Method *after_change_failure
Hooks *after_change_failure
Method *after_destroy_failure
Hooks *after_destroy_failure
Method after_change
Hooks after_change
Method after_destroy
Hooks after_destroy
Show
Method setup
Hooks setup
Method setup_show
Hooks setup_show
Index
Method setup
Hooks setup
Method setup_index
Hooks setup_index

* only occurs depeding on the success or failure of the action

Policies

Searchers

Development

After checking out the repo, run bin/setup to install dependencies. 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 tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/snfoil. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Sn::Foil project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.