Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/solid-process/solid-process

Write business logic for Ruby/Rails that scales.
https://github.com/solid-process/solid-process

ruby ruby-on-rails solid-process solid-result

Last synced: about 5 hours ago
JSON representation

Write business logic for Ruby/Rails that scales.

Awesome Lists containing this project

README

        


⚛️ Solid::Process


Write business logic for Ruby/Rails that scales.





Ruby
Rails

## 📚 Table of Contents

- [Introduction](#introduction)
- [Installation](#installation)
- [The Basic Structure](#the-basic-structure)
- [Further Reading](#further-reading)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)
- [Code of Conduct](#code-of-conduct)
- [Acknowledgments](#acknowledgments)
- [About](#about)

## Supported Ruby and Rails

This library is tested (100% coverage) against:

| Ruby / Rails | 6.0 | 6.1 | 7.0 | 7.1 | Edge |
|--------------|-----|-----|-----|-----|------|
| 2.7 | ✅ | ✅ | ✅ | ✅ | |
| 3.0 | ✅ | ✅ | ✅ | ✅ | |
| 3.1 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 3.2 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 3.3 | ✅ | ✅ | ✅ | ✅ | ✅ |
| Head | | | | ✅ | ✅ |

## Introduction

`solid-process` is a Ruby/Rails library designed to encapsulate business logic into manageable processes. It simplifies writing, testing, maintaining, and evolving your code, ensuring it remains clear and approachable as your application scales.

**Features:** (_touch to expand_)

1️⃣ Seamless Rails integration

> Designed to complement Ruby on Rails, this library integrates smoothly without conflicting with existing framework conventions and features.

2️⃣ Support progressive mastery

> Offers an intuitive entry point for novices while providing robust, advanced features that cater to experienced developers.

3️⃣ Promote conceptual integrity and rapid onboarding

> By maintaining a consistent design philosophy, `solid-process` reduces the learning curve for new developers, allowing them to contribute more effectively and quickly to a codebase.

4️⃣ Enhanced observability

> Equipped with sophisticated instrumentation mechanisms, the library enables detailed logging and tracing without compromising code readability, even when processes are nested.

⬆️  back to top

### Examples

Check out [Solid Rails App](https://github.com/solid-process/solid-rails-app) for a complete example of how to use `solid-process` in a Rails application. [Twelve versions (branches)](https://github.com/solid-process/solid-rails-app?tab=readme-ov-file#-repository-branches) show how the gem can be incrementally integrated, access it to see from simple services/form objects to implementing the ports and adapters (hexagonal) architectural pattern.

You can also check the [examples](examples) directory for more simple examples of how to use the gem.

⬆️  back to top

## Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add solid-process

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install solid-process

And require it in your code:

require 'solid/process'

⬆️  back to top

## The Basic Structure

All `Solid::Process` requires at least two things: an `input` and a `call` method.

1. The `input` is a set of attributes needed to perform the work.
2. The `#call` method is the entry point and where the work is done.
- It receives the attributes Hash (symbolized keys), defined by the `input`.
- It returns a `Success` or `Failure` as the output.

```ruby
class User::Creation < Solid::Process
input do
# Define the attributes needed to perform the work
end

def call(attributes)
# Perform the work and return a Success or Failure as the output
end
end
```

#### Example

```ruby
class User::Creation < Solid::Process
input do
attribute :email
attribute :password
attribute :password_confirmation
end

def call(attributes)
user = User.create(attributes)

if user.persisted?
Success(:user_created, user: user)
else
Failure(:user_not_created, user: user)
end
end
end
```

⬆️  back to top

### Calling a Process

To call a process, you can use the `call` method directly, or instantiate the class and call the `#call` method.

```ruby
###############
# Direct call #
###############

User::Creation.call(email: '[email protected]', password: 'password', password_confirmation: 'password')
# => ##}>

########################
# Instantiate and call #
########################

process = User::Creation.new

process.call(email: '[email protected]', password: 'password', password_confirmation: 'password')
```

For now, it's essential to know that a process instance is stateful, and because of this, you can call it only once.

```ruby
process = User::Creation.new

input = {email: '[email protected]', password: 'password', password_confirmation: 'password'}

process.call(input)

process.call(input)
# The `User::Creation#output` is already set. Use `.output` to access the result or create a new instance to call again. (Solid::Process::Error)
```

⬆️  back to top

## Further Reading

1. [Key Concepts](docs/010_KEY_CONCEPTS.md)
2. [Basic Usage](docs/020_BASIC_USAGE.md)
3. [Intermediate Usage](docs/030_INTERMEDIATE_USAGE.md)
4. [Advanced Usage](docs/040_ADVANCED_USAGE.md)
5. [Error Handling](docs/050_ERROR_HANDLING.md)
6. [Testing](docs/060_TESTING.md)
7. [Instrumentation / Observability](docs/070_INSTRUMENTATION.md)
8. [Rails Integration](docs/080_RAILS_INTEGRATION.md)
9. [Internal libraries](docs/090_INTERNAL_LIBRARIES.md)
- Solid::Input
- Solid::Model
- Solid::Value
- ActiveModel validations
10. [Ports and Adapters (Hexagonal Architecture)](docs/100_PORTS_AND_ADAPTERS.md)

⬆️  back to top

## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rake dev` to run the 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](https://rubygems.org).

⬆️  back to top

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/solid-process/solid-process. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/solid-process/solid-process/blob/main/CODE_OF_CONDUCT.md).

⬆️  back to top

## License

The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

⬆️  back to top

## Code of Conduct

Everyone interacting in the Solid::Process project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/solid-process/solid-process/blob/main/CODE_OF_CONDUCT.md).

⬆️  back to top

## Acknowledgments

I want to thank some people who helped me by testing and giving feedback as this project took shape, they are:

- [Diego Linhares](https://github.com/diegolinhares) and [Ralf Schmitz Bongiolo](https://github.com/mrbongiolo) they were the brave ones who worked for a few months with the first versions of the ecosystem (it was called B/CDD). Their feedback was essential for improving DX and helped me to pivot some core decisions.
- [Vitor Avelino](https://github.com/vitoravelino), [Tomás Coêlho](https://github.com/tomascco), [Haroldo Furtado](https://github.com/haroldofurtado) (I could repeat Ralf and Diego again) for the various feedbacks, documentation, API, support and words of encouragement.

## About

[Rodrigo Serradura](https://rodrigoserradura.com) created this project. He is the Solid Process creator and has already made similar gems like the [u-case](https://github.com/serradura/u-case) and [kind](https://github.com/serradura/kind). This gem can be used independently, but it also contains essential features that facilitate the adoption of Solid Process (the method) in code.

⬆️  back to top