use_cases 1.0.4 → 1.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c1ed9f7d86b9109062b207489f37e67f84b93e676d7e81b930f219abbd47224
-  data.tar.gz: 2b9234f7075cb8240836875845d5d61036caa9a3c7feeb72abf31d2dd5830f91
+  metadata.gz: 3cec89e8a4f4ecdabae86c99156447d8b39ffd5de5e918130b21ccae18f045a7
+  data.tar.gz: e36cd9587aab933815775ee1181360ccea4a24e58e82c3a4a073a99bb565ff31
 SHA512:
-  metadata.gz: fe3e66534633de66dff8811dad8a3d2c9f0f350d392db60a7e91989d11a861510e32937abc77f47ff8d74b9439a8c6bb321e18d655f655af0778bf676efcc28f
-  data.tar.gz: 4da7071b68b859462feda741591b9862330f9b7dbe5ad127a76ff6052ac13bf7622241620c17a3ef20ee52e6f8b16c67e44b398f01621643df646b6d94759e62
+  metadata.gz: fdaa3ea0104e5bb38190c5c65f59e44569d38b08f0f4174e1c82f5f3b6f0698900a7001463dc3215007a2af2f4030616cc038ae2f2c78aba388b2cab90c520ad
+  data.tar.gz: 0c9663e589c521677529bb5b8a4cbe87c4c3591c82dfbc30ea9248b215c53f16c915f4a37dd3683f22b8dc7698f20e46e7cc8dfe20c5390ae9daaf418ee8e26d

data/CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## [1.0.1] - 2021-12-19
 
-- Async published events are now suffixed by `".aync"`
+- Async published events are now suffixed by `".async"`
 
 ## [1.0.0] - 2021-12-19
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    use_cases (1.0.2)
+    use_cases (1.0.12)
       activesupport
       dry-events
       dry-matcher
@@ -126,4 +126,4 @@ DEPENDENCIES
   use_cases!
 
 BUNDLED WITH
-   2.2.25
+   2.2.28

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.subscribe_and_publish_event(publish_key, payload)
       end
     end
   end

data/lib/use_cases/events/publisher.rb

@@ -1,9 +1,52 @@
-require 'dry/events/publisher'
+require "dry/events/publisher"
 
 module UseCases
   module Events
     class Publisher
       include Dry::Events::Publisher[:use_cases]
+
+      def subscribe_and_publish_event(event_name, payload)
+        subscribe_to_event(event_name)
+        publish(event_name, payload)
+        publish_async(event_name, payload) if event_should_be_published_asynchronously?(event_name)
+      end
+
+      private
+
+      def publish_async(event_name, payload)
+        UseCases::Events::PublishJob.perform_later(event_name, payload)
+      end
+
+      def event_should_be_published_asynchronously?(event_name)
+        defined? UseCases::Events::PublishJob && !event_name.end_with?(".async")
+      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.should_subscribe_to?(event_name) && !subscribed?(subscriber)
+        end
+      end
+
+      def subscribe(listener)
+        subcribers << listener
+        super
+      end
+
+      def subscribed?(listener)
+        subcribers.include?(listener)
+      end
+
+      def subcribers
+        @subcribers ||= []
+      end
+
+      def available_subscribers
+        UseCases.subscribers
+      end
     end
   end
 end

data/lib/use_cases/events/subscriber.rb

@@ -1,6 +1,15 @@
 module UseCases
   module Events
-    class Subscriber
+    module Subscriber
+      def self.included(base)
+        UseCases.subscribers << base.new
+      end
+
+      def should_subscribe_to?(event_name)
+        event_handler_name = "on_#{event_name.gsub('.', '_')}"   
+        
+        respond_to?(event_handler_name.to_sym)
+      end
     end
   end
 end

data/lib/use_cases/module_optins/publishing.rb

@@ -9,35 +9,60 @@ module UseCases
     module Publishing
       def self.included(base)
         super
-        base.prepend DoCallPatch
+        StepAdapters::Abstract.prepend StepPatch
       end
 
-      module DoCallPatch
-        def do_call(*args)
-          super(*args, method(:publish_step_result).to_proc)
+      module StepPatch
+        def initialize(*args)
+          super
+          return unless options[:publish] && UseCases.publisher
+
+          register_events
+        end
+
+        def register_events
+          event_names.each do |event_name|
+            next if UseCases.publisher.class.events[event_name]
+
+            UseCases.publisher.class.register_event(event_name)
+          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 event_names
+          event_name = options[:publish]
+          [
+            "#{event_name}.success", "#{event_name}.failure",
+            "#{event_name}.success.async", "#{event_name}.failure.async"
+          ]
+        end
 
-          register_event(publish_key)
-          peform_publish(publish_key, payload)
+        def call(*args)
+          super(*args).tap do |result|
+            publish_step_result(result, args)
+          end
         end
 
-        def register_event(publish_key)
-          return if UseCases.publisher.class.events[publish_key]
+        def publish_step_result(step_result, args)
+          return unless options[:publish]
+
+          key = extract_event_key(step_result)
+          payload = extract_payload(step_result, args)
 
-          UseCases.publisher.class.register_event(publish_key)
+          UseCases.publisher.subscribe_and_publish_event(key, payload)
         end
 
-        def peform_publish(publish_key, payload)
-          UseCases.publisher.publish(publish_key, payload)
-          return unless defined? UseCases::Events::PublishJob
+        private
+
+        def extract_payload(step_result, args)
+          {
+            return_value: step_result.value!,
+            params: args[-2],
+            current_user: args[-1]
+          }
+        end
 
-          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/rspec/matchers.rb

@@ -38,7 +38,7 @@ RSpec::Matchers.define(:be_failure_with) do |*expected_failure|
     expect(test_subject.failure).to eql expected_failure
   end
 
-  expected_result, expected_code = expect_failure
+  expected_result, expected_code = expected_failure
 
   failure_message do |test_subject|
     if test_subject.failure?

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
@@ -42,7 +41,7 @@ module UseCases
 
         return args.first(callable_args_count) unless external? && selects_external_args?
 
-        hashed_args(args)
+        hashed_args(args).values
       end
 
       def hashed_args(args)
@@ -86,11 +85,11 @@ module UseCases
       end
 
       def external?
-        with_option.present?
+        !with_option.nil?
       end
 
       def selects_external_args?
-        pass_option.present?
+        !pass_option.nil?
       end
 
       def callable_args_count

data/lib/use_cases/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UseCases
-  VERSION = "1.0.4"
+  VERSION = "1.0.13"
 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 :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
+  setting :publisher, default: ::UseCases::Events::Publisher.new, reader: true
+  setting :subscribers, default: [], reader: true
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: use_cases
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.13
 platform: ruby
 authors:
 - Ring Twice
-autorequire:
+autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-01-05 00:00:00.000000000 Z
+date: 2022-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -178,7 +178,7 @@ metadata:
   homepage_uri: https://github.com/listminut/use_cases
   source_code_uri: https://github.com/listminut/use_cases
   changelog_uri: https://github.com/listminut/use_cases/CHANGELOG.md
-post_install_message:
+post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -193,8 +193,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key:
+rubygems_version: 3.1.6
+signing_key: 
 specification_version: 4
 summary: Use Cases
 test_files: []