use_cases 0.3.8 → 1.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad9722f48d9d6f073a9699cb042c246d935994b4384e340e3b985c35ea6a697b
-  data.tar.gz: 8d3cc6daeef1b64fb86a96a9e6ff13a3b95ef328ff2a4e453696cae0724a1572
+  metadata.gz: e41f6c5b8670e047cafdd85d068a66aa0efac27700f2c179d5d893ee1593c466
+  data.tar.gz: 629cef02e18325528d6155a34356b80e48acaf31520ef45fddb4937e058c3ad2
 SHA512:
-  metadata.gz: aefef04cfa79694d593848a6c245ad3d282416fdf28de6a934581f8fa15bfadf1faf5fccf1624a272b997473619af36841464feb8b1f26b6329ee8333a688e4b
-  data.tar.gz: 00bb31d99dfd4e9f1d98d99778b1263e4d32949dc5270af41f78d19dba6a460afeba44797219984dcbe964c516c150e2c0ee1db1392645760de14a7599ae2876
+  metadata.gz: 2b5fdb9fd7bd52211b9194abd49fa2247b9b814e26f763f25f0c9f3ee995dff527977a19e7192576565a563af19dbf3cfeccae833fbd74f4fba74fa4589f46a3
+  data.tar.gz: 7d51d14db15b08764a1bbf3dc6ccede0806085e532e42273e436f1c91029f911282c3da31495b978a7dc87d5ba569fa33bc077b1b15673d7df795c9bf53ed781

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [1.0.1] - 2021-12-19
+
+- Async published events are now suffixed by `".async"`
+
+## [1.0.0] - 2021-12-19
+
+- Fixed some minor bugs that have been pending todos.
+- Deprecated the `UseCases::Base` superclass as a DSL injection method. You must now use the `UseCase` module.
+- Added the `publish` option for steps, which allows the publishing of an event when a step is completed.
+
 ## [0.1.0] - 2021-09-21
 
 - Added the basic DSL of them with the following modules:
@@ -9,7 +19,7 @@
   - Notifications [WIP]
   - StackRunner 
   - Stack
-  - StepResult
+  - UseCases::Result
   - Steps
   - Validate
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    use_cases (0.3.7)
+    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

@@ -4,250 +4,179 @@
 
 # UseCases
 
-## Currently Unstable! Use at your own risk.
+`UseCases` is a dry-ecosystem-based gem that implements a DSL for the use case pattern using the railway programming paradigm.
 
-`UseCases` is a gem based on the [dry-transaction](https://dry-rb.org/gems/dry-transaction/) DSL that implements macros commonly used internally by Ring Twice.
+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.
 
-`UseCases` does not however use `dry-transaction` 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 our needs.
+### Including UseCase
 
-## Why `UseCases` came about:
+Including the `UseCase` module ensures that your class implements the base use case [Base DSL](#the-base-dsl).
 
-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.
-
-## 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:
-
-    $ gem install use_cases
-
-## Usage
-
-To fully understand `UseCases`, make sure to read [dry-transaction](https://dry-rb.org/gems/dry-transaction/0.13/)'s documentation first.
-
-### Validations
-
-See [dry-validation](https://dry-rb.org/gems/dry-validation/)
-
-### Step Adapters
-
-https://dry-rb.org/gems/dry-transaction/0.13/step-adapters/
-
-**Basic Example**
+### Using a UseCase
 
 ```ruby
-class YourCase < UseCases::Base
-  params {}
+create_user = Users::Create.new
+params = { first_name: 'Don', last_name: 'Quixote' }
 
-  step :do_something
+result = create_user.call(params, current_user)
 
-  def do_something(params, current_user)
-    params[:should_fail] ? Failure([:failed, "failed"]) : Success("it succeeds!")
-  end
-end
+# Checking if succeeded
+result.success?
 
-params = { should_fail: true }
+# Checking if failed
+result.failure?
 
-YourCase.new.call(params, nil) do |match|
-  match.failure :failed do |(code, result)|
-    puts code
-  end
+# Getting return value
+result.value!
+```
 
-  match.success do |message|
-    puts message
-  end
-end
-# => failed
+Or with using dry-matcher by passing a block:
 
-params = { should_fail: false }
+```ruby
+create_user = Users::Create.new
+params = { first_name: 'Don', last_name: 'Quixote' }
 
-YourCase.new.call(params, nil) do |match|
-  match.failure :failed do |(code, result)|
-    puts code
+create_user.call(params, current_user) do |on|
+  on.success do |user|
+    puts "#{user.first_name} created!"
   end
 
-  match.success do |message|
-    puts message
+  on.failure do |(code, message)|
+    puts "Failure (#{code}): #{message}"
   end
 end
-# => it succeeds!
 ```
 
-**Complex Example**
-
-```ruby
-class YourCase < UseCases::Base
-  params {}
+### Available Optins
 
-  try :load_some_resource
 
-  step :change_this_resource
+| 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. | 
 
-  tee :log_a_message
+### The base DSL
 
-  check :user_can_create_another_resource?
+Use cases implements a DSL similar to dry-transaction, using the [Railway programming paradigm](https://fsharpforfunandprofit.com/rop/).
 
-  map :create_some_already_validated_resource
 
-  enqueue :send_email_to_user
+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.
 
-  private
-
-  def load_some_resource(_, params)
-    Resource.find(params[:id])
-  end
+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.
 
-  def change_this_resource(resource, params)
-    resource.text = params[:new_text]
-
-    if resource.text == params[:new_text]
-      Success(resource)
-    else
-      Failure([:failed, "could not update resource"])
-    end
-  end
-
-  def log_a_message(resource)
-    Logger.info('Resource updated')
-  end
 
-  def user_can_create_another_resource?(_, _, user)
-    user.can_create?(Resource)
-  end
+|  | 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` | ❌ |
 
-  def create_some_already_validated_resource(resource, params, user)
-    new_resource = Resource.create(text: params[:text])
-  end
+#### Optional steps
 
-  def send_email_to_user(new_resource, _, user)
-    ResourcEMailer.notify_user(user, new_resource).deliver!
-  end
-end
-```
+|  | 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` | ❌ |
 
-### Authorization
 
-`authorize` is a `check` step that returns an `:unauthorized` code in it's `Failure`.
+### Defining Steps
 
-**Example**
+Defining a step can be done in the body of the use case.
 
 ```ruby
-class YourCase < UseCases::Base
-  authorize 'User must be over 18' do |user|
-    user.age >= 18
-  end
-end
-
-user = User.where('age = 15').first
+class Users::DeleteAccount
+  include UseCases[:validated, :transactional, :publishing, :validated]
 
-YourCase.new.call({}, user) do |match|
-  match.failure :unauthorized do |(code, result)|
-    puts code
-  end
-end
-# => User must be over 18
+  step :do_something, {}
 ```
 
-### Example
-
-For the case of creating posts within a thread.
-
-**Specs**
-
-- 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.
+In real life, a simple use case would look something like:
 
 ```ruby
-class Posts::Create < UseCases::Base
+class Users::DeleteAccount
+  include UseCases[:validated, :transactional, :publishing, :validated]
 
   params do
-    required(:body).filled(:string).value(size?: 25..150)
-    required(:thread_id).filled(:integer)
+    required(:id).filled(:str?)
   end
 
-  try :load_post_thread, failure: :not_found
+  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
 
-  authorize 'User is not active' do |user, params, thread|
-    user.active?
-  end
+  private 
 
-  authorize 'User must be active or the thread author.' do |user, params, thread|
-    user.active? || thread.author == user
+  def user_owns_account?(_previous_step_input, params, current_user)
+    current_user.account_id == params[:id]
   end
 
-  step :sanitize_body
-
-  step :create_post
-
-  private
-
-  def load_post_thread(params, user)
-    Thread.find(params[:thread_id])
+  def load_account(_previous_step_input, params, _current_user)
+    Account.find_by!(user_id: params[:id])
   end
 
-  def sanitize_body(params)
-    SanitizeText.new.call(params[:body]).to_monad
+  def delete_account(account, _params, _current_user)
+    account.destroy!
   end
 
-  def create_post(body, params, user)
-    post = Post.new(body: body, user_id: user.id, thread_id: params[:thread_id])
-
-    post.save ? Success(post) : Failure([:failed_to_save, post.errors.details])
+  # 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
 ```
 
-And in your controller action
+#### Available Options
+
+| 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>
+
+## Installation
+
+Add this line to your application's Gemfile:
 
 ```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
+gem 'use_cases'
 ```
 
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install use_cases
+
+## Usage
+
+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
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/use_case.rb

@@ -6,20 +6,16 @@ require "dry/monads/do"
 require "dry/monads/do/all"
 require "dry/matcher/result_matcher"
 
-require "use_cases/authorize"
 require "use_cases/dsl"
-require "use_cases/errors"
-require "use_cases/validate"
 require "use_cases/stack"
 require "use_cases/params"
 require "use_cases/stack_runner"
-require "use_cases/step_result"
-require "use_cases/notifications"
-require "use_cases/prepare"
+require "use_cases/result"
 require "use_cases/step_adapters"
 require "use_cases/module_optins"
 
 module UseCase
+  extend UseCases::DSL
   extend UseCases::ModuleOptins
 
   def self.included(base)
@@ -33,7 +29,6 @@ module UseCase
       extend UseCases::ModuleOptins
 
       include UseCases::StepAdapters
-      include UseCases::Notifications
     end
   end
 
@@ -41,7 +36,6 @@ module UseCase
 
   def initialize(*)
     @stack = UseCases::Stack.new(self.class.__steps__).bind(self)
-    # self.class.bind_step_subscriptions
   end
 
   def call(params, current_user = nil)

data/lib/use_cases/dsl.rb

@@ -17,19 +17,5 @@ module UseCases
     def __steps__
       @__steps__ ||= []
     end
-
-    def subscribe(listeners)
-      @listeners = listeners
-
-      if listeners.is_a?(Hash)
-        listeners.each do |step_name, listener|
-          __steps__.detect { |step| step.name == step_name }.subscribe(listener)
-        end
-      else
-        __steps__.each do |step|
-          step.subscribe(listeners)
-        end
-      end
-    end
   end
 end

data/lib/use_cases/events/publish_job.rb

@@ -0,0 +1,13 @@
+
+return unless defined? ActiveJob
+
+module UseCases
+  module Events
+    class PublishJob < ActiveJob::Base
+      def perform(publish_key, payload)
+        publish_key += ".async"
+        UseCases.publisher.register_and_publish_event(publish_key, payload)
+      end
+    end
+  end
+end

data/lib/use_cases/events/publisher.rb

@@ -0,0 +1,50 @@
+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

@@ -0,0 +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/authorized.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "use_cases/step_adapters/check"
+
+module UseCases
+  module ModuleOptins
+    module Authorized
+      def self.included(base)
+        super
+        base.class_eval do
+          extend DSL
+        end
+      end
+
+      module DSL
+        DEFAULT_OPTIONS = {
+          failure: :unauthorized,
+          failure_message: "Not Authorized",
+          merge_input_as: :resource
+        }
+
+        def authorize(name, options = {})
+          options = DEFAULT_OPTIONS.merge(options)       
+
+          check name, options
+        end
+      end
+    end
+  end
+end

data/lib/use_cases/module_optins/prepared.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "use_cases/step_adapters/tee"
+
+module UseCases
+  module ModuleOptins
+    module Prepared
+      def self.included(base)
+        super
+        base.class_eval do
+          extend DSL
+        end
+      end
+
+      module DSL
+        def prepare(name, options = {})
+          __steps__.unshift StepAdapters::Tee.new(name, nil, options)
+        end
+      end
+    end
+  end
+end

data/lib/use_cases/module_optins/publishing.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "use_cases/events/publisher"
+require "use_cases/events/subscriber"
+require "use_cases/events/publish_job"
+
+module UseCases
+  module ModuleOptins
+    module Publishing
+      def self.included(base)
+        super
+        StepAdapters::Abstract.prepend StepCallPatch
+      end
+
+      module StepCallPatch
+        def call(*args)
+          super(*args).tap do |result|
+            publish_step_result(result, args)
+          end
+        end
+
+        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.register_and_publish_event(key, payload)
+        end
+
+        private
+
+        def extract_payload(step_result, args)
+          {
+            return_value: step_result.value!,
+            params: args[-2],
+            current_user: args[-1]
+          }
+        end
+
+        def extract_event_key(step_result)
+          options[:publish].to_s + (step_result.success? ? ".success" : ".failure")
+        end
+      end
+    end
+  end
+end