use_cases 1.0.6 → 1.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7c9560f067bb15b9e9a94d5e89b2840e438486452c640f9b2b2b2b828529850
-  data.tar.gz: 7c5a1beaedb5d0c4c159860c059513d4da8018e6864e9bb71d0ea855170b8768
+  metadata.gz: 2f810a00826d0e18fb1defbddb6a54055f4b77b43141a943d48d8a56273b7bf9
+  data.tar.gz: b6f1724c28186e1e8f4ca3b0b79807d4db534903b5f0ee5ace23363b180b8fc2
 SHA512:
-  metadata.gz: 5a88ed6dfdacb0d141aa1a782f6f0219f131a52b3c800b86ca62fa6d8a1e77c139e5bfa6fd3bd726d10f278d06ab0e848edd31a1542797f70a405e35e93342ba
-  data.tar.gz: aacfe4f3862a363757534b259f6ca332f998c8dec8bf7be26568b6db6789d893794a933eaa55cba640ad5b769dd278b94b7ea9419216470fccd3b0abce3f9e95
+  metadata.gz: 8973b6cc8d4b89d16af39f010af3a8bf8cd9aea88f9c5c3679356955fc566ee1596711eed422beb9bd928364645640689ec03efd4e8cde11ec7b9d5c3e5c1357
+  data.tar.gz: b7c595a0645bf0b8938aa09f99d9fe8167b34c0ca6d9c6e9dfa4ed652a9c8341dfcf216fe70c222ad2321fb094f4667417a6bf1efb7cc1c8c2f2b79b8fe5c0a4

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    use_cases (1.0.5)
+    use_cases (1.0.10)
       activesupport
       dry-events
       dry-matcher

data/README.md

@@ -8,254 +8,174 @@
 
 It's concept is largely based on `dry-transaction` but does not use it behind the scenes. Instead it relies on other `dry` libraries like [dry-validation](https://dry-rb.org/gems/dry-validation/), [dry-events](https://dry-rb.org/gems/dry-validation/) and [dry-monads](https://dry-rb.org/gems/dry-validation/) to implement a DSL that can be flexible enough for your needs.
 
-## Why `UseCases` came about:
+### Including UseCase
 
-1. It allows you to use `dry-validation` without much gymastics.
-2. It abstracts common steps like **authorization** and **validation** into macros.
-3. It solves what we consider a problem of `dry-transaction`. The way it funnels down `input` through `Dry::Monads` payloads alone. `UseCases` offers more flexibility in a way that still promotes functional programming values.
-4. It implements a simple pub/sub mechanism which can be async when `ActiveJob` is a project dependency.
-5. It implements an `enqueue` mechanism to delay execution of steps, also using `ActiveJob` as a dependency.
+Including the `UseCase` module ensures that your class implements the base use case [Base DSL](#the-base-dsl).
 
-## Installation
+```ruby
+class Users::Create
+  include UseCase
+end
+````
 
-Add this line to your application's Gemfile:
+In order to add optional modules (optins), use the following notation:
 
 ```ruby
-gem 'use_cases'
+class Users::Create
+  include UseCase[:validated, :transactional, :publishing]
+end
 ```
 
-And then execute:
-
-    $ bundle install
-
-Or install it yourself as:
+### Using a UseCase
 
-    $ gem install use_cases
-
-## Usage
+```ruby
+create_user = Users::Create.new
+params = { first_name: 'Don', last_name: 'Quixote' }
 
-To get a good basis to get started on `UseCases`, make sure to read [dry-transaction](https://dry-rb.org/gems/dry-transaction/0.13/)'s documentation first.
+result = create_user.call(params, current_user)
 
-### Validations
+# Checking if succeeded
+result.success?
 
-See [dry-validation](https://dry-rb.org/gems/dry-validation/)
+# Checking if failed
+result.failure?
 
-### Creating a Use Case
+# Getting return value
+result.value!
+```
 
-**Basic Example**
+Or with using dry-matcher by passing a block:
 
 ```ruby
-class DeleteUser
-  include UseCase
-
-  check :current_user_is_user?
-  step :build_user
-  map :persist_user
+create_user = Users::Create.new
+params = { first_name: 'Don', last_name: 'Quixote' }
 
-  private
-
-  def current_user_is_user?(params, current_user)
+create_user.call(params, current_user) do |on|
+  on.success do |user|
+    puts "#{user.first_name} created!"
   end
 
-  def build_user(params, current_user)
+  on.failure do |(code, message)|
+    puts "Failure (#{code}): #{message}"
   end
+end
+```
 
+### Available Optins
 
-  def do_something(user, params, current_user)
-    params[:should_fail] ? Failure([:failed, "failed"]) : Success("it succeeds!")
-  end
-end
 
-params = { should_fail: true }
+| Optin | Description |
+|---|---|
+| `:authorized` | Adds an extra `authorize` step macro, used to check user permissions. |
+| `:prepared` | Adds an extra `prepare` step macro, used to run some code before the use case runs. |
+| `:publishing` | Adds extra extra `publish` option to all steps, which allows a step to broadcast an event after executing | 
+| `:transactional` | Calls `#transaction` on a given `transaction_handler` object around the use case execution |
+| `:validated` | Adds all methods of `dry-transaction` to the use case DSL, which run validations on the received `params` object. | 
 
-YourCase.new.call(params, nil) do |match|
-  match.failure :failed do |(code, result)|
-    puts code
-  end
+### The base DSL
 
-  match.success do |message|
-    puts message
-  end
-end
-# => failed
+Use cases implements a DSL similar to dry-transaction, using the [Railway programming paradigm](https://fsharpforfunandprofit.com/rop/).
 
-params = { should_fail: false }
 
-YourCase.new.call(params, nil) do |match|
-  match.failure :failed do |(code, result)|
-    puts code
-  end
+Each step macro has a different use case, and so a different subset of available options, different expectations in return values, and interaction with the following step.
 
-  match.success do |message|
-    puts message
-  end
-end
-# => it succeeds!
-```
+By taking a simple look at the definition of a use case, anyone should be able to understand the business rules it emcompasses. For that it is necessary to understand the following matrix.
 
-**Complex Example**
 
-```ruby
-class YourCase < UseCases::Base
-  params {}
+|  | Rationale for use | Accepted Options | Expected return | Passes return value |
+|---|---|---|---|---|
+| **step** | This step has some complexity, and it can fail or succeed. | `with`, `pass` | `Success`/ `Failure` | ✅ |
+| **check** | This step checks sets some rules for the operation, usually verifying that domain models fulfil some conditions.  | `with`, `pass`, `failure`, `failure_message` | `boolean` | ❌ |
+| **map** | Nothing should go wrong within this step. If it does, it's an unexpected application error. | `with`, `pass` | `any` | ✅ |
+| **try** | We expect that, in some cases, errors will occur, and the operation fails in that case. | `catch`, `with`, `pass`, `failure`, `failure_message` | `any` | ✅ |
+| **tee** | We don't care if this step succeeds or fails, it's used for non essential side effects. | `with`, `pass` | `any` | ❌ |
 
-  try :load_some_resource
+#### Optional steps
 
-  step :change_this_resource
+|  | Rationale for use | Accepted Options | Expected return | Passes return value |
+|---|---|---|---|---|
+| **enqueue** *(requires ActiveJob defined) | The same as a `tee`, but executed later to perform non-essential expensive operations. | `with`, `pass`, and sidekiq options | `any` | ❌ |
+| **authorize**<br> *(requires authorized) | Performs authorization on the current user, by running a  `check` which, in case of failure, always returns an `unauthorized` failure. | `with`, `pass`, `failure_message` | `boolean` | ❌ |
+| **prepare**<br> *(requires prepared) | Adds a `tee` step that always runs first. Used to mutate params if necessary. | `with`, `pass` | `any` | ❌ |
 
-  tee :log_a_message
 
-  check :user_can_create_another_resource?
+### Defining Steps
 
-  map :create_some_already_validated_resource
+Defining a step can be done in the body of the use case.
 
-  enqueue :send_email_to_user
+```ruby
+class Users::DeleteAccount
+  include UseCases[:validated, :transactional, :publishing, :validated]
 
-  private
+  step :do_something, {}
+```
 
-  def load_some_resource(_, params)
-    Resource.find(params[:id])
-  end
+In real life, a simple use case would look something like:
 
-  def change_this_resource(resource, params)
-    resource.text = params[:new_text]
+```ruby
+class Users::DeleteAccount
+  include UseCases[:validated, :transactional, :publishing, :validated]
 
-    if resource.text == params[:new_text]
-      Success(resource)
-    else
-      Failure([:failed, "could not update resource"])
-    end
+  params do
+    required(:id).filled(:str?)
   end
 
-  def log_a_message(resource)
-    Logger.info('Resource updated')
-  end
+  authorize :user_owns_account?, failure_message: 'Cannot delete account'
+  try :load_account, catch: ActiveRecord::RecordNotFound, failure: :account_not_found, failure_message: 'Account not found'
+  map :delete_account, publish: :account_deleted
+  enqueue :send_farewell_email
 
-  def user_can_create_another_resource?(_, _, user)
-    user.can_create?(Resource)
-  end
+  private 
 
-  def create_some_already_validated_resource(resource, params, user)
-    new_resource = Resource.create(text: params[:text])
+  def user_owns_account?(_previous_step_input, params, current_user)
+    current_user.account_id == params[:id]
   end
 
-  def send_email_to_user(new_resource, _, user)
-    ResourcEMailer.notify_user(user, new_resource).deliver!
+  def load_account(_previous_step_input, params, _current_user)
+    Account.find_by!(user_id: params[:id])
   end
-end
-```
-
-### Authorization
-
-`authorize` is a `check` step that returns an `:unauthorized` code in it's `Failure`.
 
-**Example**
-
-```ruby
-class YourCase < UseCases::Base
-  authorize 'User must be over 18' do |user|
-    user.age >= 18
+  def delete_account(account, _params, _current_user)
+    account.destroy!
   end
-end
 
-user = User.where('age = 15').first
-
-YourCase.new.call({}, user) do |match|
-  match.failure :unauthorized do |(code, result)|
-    puts code
+  # since this executed async, all args are serialized
+  def send_farewell_email(account_attrs, params, current_user_attrs)
+    user = User.find(params[:id])
+    UserMailer.farewell(user).deliver_now!
   end
 end
-# => User must be over 18
 ```
 
-### Example
+#### Available Options
 
-For the case of creating posts within a thread.
+| Name | Description | Expected Usage |
+|---|---|---|
+| `with` | Retrieves the callable object used to perform the step. |<em><br> Symbol: `send(options[:with])` <br> String: `UseCases.config.container[options[:with]]` <br> Class: `options[:with]`</em>  |
+| `pass` | An array of the arguments to pass to the object set by `with`. <br> _options: params, current_user & previous_step_result_ | Array\<Symbol> |
+| `failure` | The code passed to the Failure object. | Symbol / String |
+| `failure_message` | The string message passed to the Failure object. | Symbol / String | 
+| `catch` | Array of error classes to rescue from. | Array\<Exception>
 
-**Specs**
+## Installation
 
-- Only active users or the thread owner can post.
-- The post must be between 25 and 150 characters.
-- The post must be sanitized to remove any sensitive or explicit content.
-- The post must be saved to the database in the end.
-- In case any conditions are not met, an failure should be returned with it's own error code.
+Add this line to your application's Gemfile:
 
 ```ruby
-class Posts::Create < UseCases::Base
-
-  params do
-    required(:body).filled(:string).value(size?: 25..150)
-    required(:thread_id).filled(:integer)
-  end
-
-  try :load_post_thread, failure: :not_found
-
-  authorize 'User is not active' do |user, params, thread|
-    user.active?
-  end
-
-  authorize 'User must be active or the thread author.' do |user, params, thread|
-    user.active? || thread.author == user
-  end
-
-  step :sanitize_body
-
-  step :create_post
-
-  private
+gem 'use_cases'
+```
 
-  def load_post_thread(params, user)
-    Thread.find(params[:thread_id])
-  end
+And then execute:
 
-  def sanitize_body(params)
-    SanitizeText.new.call(params[:body]).to_monad
-  end
+    $ bundle install
 
-  def create_post(body, params, user)
-    post = Post.new(body: body, user_id: user.id, thread_id: params[:thread_id])
+Or install it yourself as:
 
-    post.save ? Success(post) : Failure([:failed_to_save, post.errors.details])
-  end
-end
-```
+    $ gem install use_cases
 
-And in your controller action
+## Usage
 
-```ruby
-# app/controllers/posts_controller.rb
-class PostsController < ApplicationController
-  def create
-    Posts::Create.new.call(params, current_user) do |match|
-
-      # in success, the return value is the Success payload of the last step (#create_post)
-      match.success do |post|
-        # result => <Post:>
-      end
-
-      # in case ::params or any other dry-validation fails.
-      match.failure :validation_error do |result|
-        # result => [:validation_error, ['validation_error', { thread_id: 'is missing' }]
-      end
-
-      # in case ::try raises an error (ActiveRecord::NotFound in this case)
-      match.failure :not_found do |result|
-        # result => [:not_found, ['not_found', 'Could not find thread with id='<params[:thread_id]>'']
-      end
-
-      # in case any of the ::authorize blocks returns false
-      match.failure :unauthorized do |result|
-        # result => [:unauthorized, ['unauthorized', 'User is not active']
-      end
-
-      # in case #create_post returns a Failure
-      match.failure :failed_to_save do |result|
-        # result => [:failed_to_save, ['failed_to_save', { user_id: 'some error' }]
-      end
-    end
-  end
-end
-```
+To get a good basis to get started on `UseCases`, make sure to read [dry-transaction](https://dry-rb.org/gems/dry-transaction/0.13/)'s documentation first.
 
 ## Development
 

data/lib/use_cases/events/publish_job.rb

@@ -5,14 +5,8 @@ module UseCases
   module Events
     class PublishJob < ActiveJob::Base
       def perform(publish_key, payload)
-        publish_key += '.async'
-        UseCases.publisher.publish(publish_key, payload)
-      end
-
-      private
-
-      def publisher
-        UseCases.publisher
+        publish_key += ".async"
+        UseCases.publisher.register_and_publish_event(publish_key, payload)
       end
     end
   end

data/lib/use_cases/events/publisher.rb

@@ -1,9 +1,50 @@
-require 'dry/events/publisher'
+require "dry/events/publisher"
 
 module UseCases
   module Events
     class Publisher
       include Dry::Events::Publisher[:use_cases]
+
+      def self.register_and_publish_event(event_name, payload)
+        register_events(event_name)
+
+        new.tap do |publisher|
+          publisher.subscribe_to_event(event_name)
+          publisher.publish(event_name, payload)
+        end
+
+        return unless defined? UseCases::Events::PublishJob
+
+        UseCases::Events::PublishJob.perform_later(event_name, payload)
+      end
+
+      def self.extract_payload(use_case_args)
+        {
+          return_value: use_case_args[0],
+          params: use_case_args[1],
+          current_user: use_case_args[2]
+        }
+      end
+
+      def self.register_events(event_name)
+        [event_name, "#{event_name}.aync"].each do |key|
+          register_event(key) unless events[key]
+        end
+      end
+
+      def subscribe_to_event(event_name)
+        subscribers_for(event_name).each(&method(:subscribe))
+      end
+
+      def subscribers_for(event_name)
+        available_subscribers.select do |subscriber|
+          subscriber.subscribed_to?(event_name)
+        end
+      end
+
+      def available_subscribers
+        UseCases::Events::Subscriber.descendants.map(&:new) + UseCases.subscribers
+      end
     end
   end
 end

data/lib/use_cases/events/subscriber.rb

@@ -1,6 +1,13 @@
+require "active_support/core_ext/class/subclasses"
+
 module UseCases
   module Events
     class Subscriber
+      def subscribed_to?(event_name)
+        event_handler_name = "on_#{event_name.gsub('.', '_')}"   
+        
+        respond_to?(event_handler_name)
+      end
     end
   end
 end

data/lib/use_cases/module_optins/publishing.rb

@@ -9,35 +9,37 @@ module UseCases
     module Publishing
       def self.included(base)
         super
-        base.prepend DoCallPatch
+        StepAdapters::Abstract.prepend StepCallPatch
       end
 
-      module DoCallPatch
-        def do_call(*args)
-          super(*args, method(:publish_step_result).to_proc)
+      module StepCallPatch
+        def call(*args)
+          super(*args).tap do |result|
+            publish_step_result(result, args)
+          end
         end
 
-        def publish_step_result(step_result, step_object)
-          publish_key = step_object.options[:publish]
-          publish_key += step_result.success? ? ".success" : ".failure"
-          payload = step_result.value!
-          return unless publish_key
+        def publish_step_result(step_result, args)
+          return unless options[:publish]
 
-          register_event(publish_key)
-          peform_publish(publish_key, payload)
+          key = extract_event_key(step_result)
+          payload = extract_payload(step_result, args)
+
+          UseCases.publisher.register_and_publish_event(key, payload)
         end
 
-        def register_event(publish_key)
-          return if UseCases.publisher.class.events[publish_key]
+        private
 
-          UseCases.publisher.class.register_event(publish_key)
+        def extract_payload(step_result, args)
+          {
+            return_value: step_result.value!,
+            params: args[-2],
+            current_user: args[-1]
+          }
         end
 
-        def peform_publish(publish_key, payload)
-          UseCases.publisher.publish(publish_key, payload)
-          return unless defined? UseCases::Events::PublishJob
-
-          UseCases::Events::PublishJob.perform_later(publish_key, payload.to_json)
+        def extract_event_key(step_result)
+          options[:publish].to_s + (step_result.success? ? ".success" : ".failure")
         end
       end
     end

data/lib/use_cases/stack_runner.rb

@@ -17,8 +17,6 @@ module UseCases
     def do_call(*args)
       stack.call do
         result = _run_step(stack, args)
-        args.last.call(result, stack.current_step) if args.last.is_a? Proc
-
         return result if result.failure?
 
         result

data/lib/use_cases/step_adapters/abstract.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "dry/monads/all"
-require "byebug"
 
 module UseCases
   module StepAdapters

data/lib/use_cases/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UseCases
-  VERSION = "1.0.6"
+  VERSION = "1.0.11"
 end

data/lib/use_cases.rb

@@ -15,24 +15,6 @@ module UseCases
   extend Dry::Configurable
 
   setting :container, reader: true
-  setting :publisher, ::UseCases::Events::Publisher.new, reader: true
+  setting :publisher, ::UseCases::Events::Publisher, reader: true
   setting :subscribers, [], reader: true
-
-  def self.configure(&blk)
-    super
-    finalize_subscriptions!
-  end
-
-  def self.finalize_subscriptions!
-    subscribe(*subscribers)
-    return unless UseCases::Events::Subscriber.respond_to?(:descendants)
-
-    usecase_subscriber_children = UseCases::Events::Subscriber.descendants
-    subscribe(*usecase_subscriber_children)
-    subscribers.concat(usecase_subscriber_children)
-  end
-
-  def self.subscribe(*subscribers)
-    subscribers.each { |subscriber| publisher.subscribe(subscriber) }
-  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: use_cases
 version: !ruby/object:Gem::Version
-  version: 1.0.6
+  version: 1.0.11
 platform: ruby
 authors:
 - Ring Twice
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-01-05 00:00:00.000000000 Z
+date: 2022-01-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport