rails_use_case 0.0.7 → 0.0.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26b3c53326dd3bd10cd2b119eba354e2cebe8333deeb0781eca31dfea6ba6281
-  data.tar.gz: 75b6d7e2dbc461a6fef31f2ea8bfb0a3c65edfbb52892a4dc93bec2f5dd0bcdb
+  metadata.gz: 7ede9e2243fddfc8ed59a395ca97b7f14062c4180e27d1f956f793a435559e90
+  data.tar.gz: 3f56c4fe1f24f74af0226aa5adacbb1341ac042e52b0caf767d61005c8d04b9a
 SHA512:
-  metadata.gz: 5e2a68e4b6939116696dfb69ed347d131eccf05e029b4ff97b26ae563726c8239faa76d2ef07be3025ba642ce4932ebd4e522dc689da50b3f618d76a613cef76
-  data.tar.gz: 03fbc54da3a23e932fab54359c222a07d988297ffdd57c1e8832526d8affefcc1bf3b9870c26929ac5067a0a61b9f7bdd7a563653865592dba2d33d37f64635f
+  metadata.gz: e21f3ab1cc85466ec37bccfcc1dae363c478bb4d49a15bdcd5b1e093e5d63d270d5be3befccd66f41f0b81cd79015cdcf41f124f9321fa3d968f17300d7ba1a8
+  data.tar.gz: 34ec8bbeb3e95a0ffce45ef6945d859e71b3122b53c1a01b7d7ad122b9c2d884f681c67a47a355bd0905b4e19ca482defcd7ba572b2aaf209f29920911a53862

data/README.md

@@ -1,6 +1,8 @@
 # Rails Use Case gem
 
-Opinionated gem for UseCases and Services in rails to keep models and controllers slim.
+Opinionated gem for UseCases and Services in Rails to keep your Models and Controllers slim.
+
+Read more: https://dev.to/phortx/pimp-your-rails-application-32d0
 
 The purpose of a UseCase is to contain reusable high level business logic which would normally be
 located in the controller. Examples are: Place an item in the cart, create a new user or delete a comment.
@@ -20,33 +22,71 @@ gem 'rails_use_case'
 
 The purpose of a UseCase is to contain reusable high level business logic which would normally be
 located in the controller. It defines a process via `step` definitions. A UseCase takes params
-and has a outcome, which is successfully or failed. It doesn't have a configuration file and doesn't
+and has a outcome, which is either successful or failed. It doesn't have a configuration file and doesn't
 log anything. Examples are: Place an item in the cart, create a new user or delete a comment.
 
+The params should always passed as hash and are automatically assigned to instance variables.
+
+Use Cases should be placed in the `app/use_cases/` directory and the file and class name should start with a verb like `create_blog_post.rb`.
+
+
+### Steps
+
 Steps are executed in the defined order. Only when a step succeeds (returns true) the next step will
 be executed. Steps can be skipped via `if` and `unless`.
 
-The UseCase should assign the main record to `@record`. Calling save! without argument will try to
-save that record or raises an exception. Also the `@record` will automatically passed into the outcome.
+The step either provides the name of a method within the use case or a block.
+When a block is given, it will be executed. Otherwise the framework will try to
+call a method with the given name.
 
-The params should always passed as hash and are automatically assigned to instance variables.
+You can also have named inline steps: `step :foo, do: -> { ... }` which is
+equivalent to `step { ... }` but with a given name. An existing method `foo`
+will not be called in this case but rather the block be executed.
 
-Use Cases should be placed in the `app/use_cases/` directory and the file and class name should start with a verb like `create_blog_post.rb`.
+There are also two special steps: `success` and `failure`. Both will end the
+step chain immediately. `success` will end the use case successfully (like there
+would be no more steps). And `failure` respectively will end the use case with a
+error. You should pass the error message and/or code via `message:` and/or
+`code:` options.
+
+
+### Failing
+
+A UseCase fails when a step returns a falsy value or raises an exception.
+
+For even better error handling, you should let a UseCase fail via the shortcut
+`fail!()` which actually just raised an `UseCase::Error` but you can provide
+some additional information. This way you can provide a human readable message
+with error details and additionally you can pass an error code as symbol, which
+allows the calling code to do error handling:
+
+`fail!(message: 'You have called this wrong. Shame on you!', code: :missing_information)`.
+
+The error_code can also passed as first argument to the `failure` step definition.
+
+
+### Record
+
+The UseCase should assign the main record to `@record`. Calling `save!` without argument will try to
+save that record or raises an exception. Also the `@record` will automatically passed into the outcome.
 
 
 ### Example UseCase
 
 ```ruby
-class CreateBlogPost < Rails::UseCase
-  attr_accessor :title, :content, :author, :skip_notifications
+class BlogPosts::Create < Rails::UseCase
+  attr_accessor :title, :content, :author, :skip_notifications, :publish
 
   validates :title, presence: true
   validates :content, presence: true
   validates :author, presence: true
 
-  step :build_post
-  step :save!
-  step :notify_subscribers, unless: -> { skip_notifications }
+  failure :access_denied, message: 'No permission', unless: -> { author.can_publish_blog_posts? }
+  step    :build_post
+  step    :save!
+  succeed unless: -> { publish }
+  step    :publish, do: -> { record.publish! }
+  step    :notify_subscribers, unless: -> { skip_notifications }
 
 
   private def build_post
@@ -67,22 +107,67 @@ end
 Example usage of that UseCase:
 
 ```ruby
-result = CreateBlogPost.perform(
+result = BlogPosts::Create.perform(
   title: 'Super Awesome Stuff!',
   content: 'Lorem Ipsum Dolor Sit Amet',
-  created_by: current_user,
+  author: current_user,
   skip_notifications: false
 )
 
 puts result.inspect
-# => {
-#   success: true,
-#   record: BlogPost(...)
-#   errors: [],
-#   error: nil
-# }
+=> {
+  success: false,                        # Wether the UseCase ended successfully
+  record: BlogPost(...)                  # The value assigned to @record
+  errors: [],                            # List of validation errors
+  exception: Rails::UseCase::Error(...), # The exception raised by the UseCase
+  message: "...",                        # Error message
+  error_code: :save_failed               # Error Code
+}
 ```
 
+- You can check whether a UseCase was successful via `result.success?`.
+- You can access the value of `@record` via `result.record`.
+- You can stop the UseCase process with a error message via throwing `Rails::UseCase::Error` exception.
+
+
+### Working with the result
+
+The `perform` method of a UseCase returns an outcome object which contains a
+`code` field with the error code or `:success` otherwise. This comes handy when
+using in controller actions for example and is a great way to delegate the
+business logic part of a controller action to the respective UseCase.
+Everything the controller has to do, is to setup the params and dispatch the
+result.
+
+Given the Example above, here is the same call within a controller action with
+an case statement.
+
+```ruby
+class BlogPostsController < ApplicationController
+  # ...
+
+  def create
+    parameters = {
+      title: params[:post][:title],
+      content: params[:post][:content],
+      publish: params[:post][:publish],
+      author: current_user
+    }
+
+    case BlogPosts::Create.perform(parameters).code
+    when :success       then redirect_to(outcome.record)
+    when :access_denied then render(:new, flash: { error: "Access Denied!" })
+    when :foo           then redirect_to('/')
+    else                     render(:new, flash: { error: outcome.message })
+    end
+  end
+
+  # ...
+end
+```
+
+However this is not rails specific and can be used in any context.
+
 
 ## Behavior
 

data/lib/rails/callable.rb

@@ -8,8 +8,8 @@ module Rails
     extend ActiveSupport::Concern
 
     class_methods do
-      def call(*args)
-        new.call(*args)
+      def call(...)
+        new.call(...)
       end
 
       alias_method :perform, :call

data/lib/rails/service.rb

@@ -70,7 +70,7 @@ module Rails
       @logger = Logger.new(STDOUT)
 
       @logger.formatter = proc do |severity, datetime, progname, msg|
-        "[@service_name] #{msg}"
+        "[#{@service_name}] #{msg}"
       end
     end
 
@@ -121,8 +121,8 @@ module Rails
 
 
     # Allows call syntax on class level: SomeService.(some, args)
-    def self.call(*args)
-      new.(*args)
+    def self.call(...)
+      new.(...)
     end
 
     # Allows to use rails view helpers

data/lib/rails/use_case/outcome.rb

@@ -4,19 +4,28 @@ module Rails
   class UseCase
     # Outcome of a UseCase
     class Outcome
-      attr_reader :success, :errors, :record, :exception
+      attr_reader :success, :errors, :record, :exception, :message, :code
 
       # Constructor.
       # @param success [Boolean] Wether the UseCase was successful.
       # @param errors [Array|nil] ActiveModel::Validations error.
       # @param record [ApplicationRecord|nil] The main record of the use case.
       # @param exception [Rails::UseCase::Error|nil] The error which was raised.
-      def initialize(success:, errors: nil, record: nil, exception: nil)
+      # @param message [String|nil] The error message.
+      # @param code [Symbol|String|nil] The error code.
+      # rubocop:disable Metrics/ParameterLists
+      def initialize(
+        success:, errors: nil, record: nil, exception: nil,
+        message: nil, code: nil
+      )
         @success = success
         @errors = errors
         @record = record
         @exception = exception
+        @message = message || exception&.message || errors&.full_messages
+        @code = success ? :success : code&.to_sym
       end
+      # rubocop:enable Metrics/ParameterLists
 
 
       # @return [Boolean] Whether the UseCase was successful.

data/lib/rails/use_case.rb

@@ -34,14 +34,32 @@ module Rails
     # DSL to define a process step of the UseCase.
     # You can use if/unless with a lambda in the options
     # to conditionally skip the step.
+    #
     # @param name [Symbol]
     # @param options [Hash]
-    def self.step(name, options = {})
+    def self.step(name = :inline, options = {}, &block)
       @steps ||= []
+
+      if block_given?
+        options[:do] = block
+        name = :inline
+      end
+
       @steps << { name: name.to_sym, options: options }
     end
 
 
+    def self.success(options = {})
+      step :success, options
+    end
+
+
+    def self.failure(code = nil, options = {})
+      options[:code] = code || options[:code] || :failure
+      step :failure, options
+    end
+
+
     # DSL to include a behavior.
     # @param mod [Module]
     def self.with(mod)
@@ -52,14 +70,32 @@ module Rails
     # Will run the steps of the use case.
     def process
       self.class.steps.each do |step|
+        # Check wether to skip when :if or :unless are set.
         next if skip_step?(step)
-        next if send(step[:name])
 
-        raise UseCase::Error, "Step #{step[:name]} returned false"
+        opts = step[:options]
+        name = step[:name]
+
+        # Handle failure and success steps.
+        return true if name == :success
+
+        fail!(code: opts[:code], message: opts[:message]) if name == :failure
+
+        # Run the lambda, when :do is set. Otherwise call the method.
+        next if opts[:do] ? instance_eval(&opts[:do]) : send(name)
+
+        # result is false, so we have a failure.
+        fail! code: :step_false, message: "Step '#{name}' returned false"
       end
     end
 
 
+    def fail!(code: nil, message: 'Failed')
+      @error_code = code
+      raise UseCase::Error, message
+    end
+
+
     # Checks whether to skip a step.
     # @param step [Hash]
     def skip_step?(step)
@@ -93,7 +129,7 @@ module Rails
     def break_when_invalid!
       return true if valid?
 
-      raise UseCase::Error, errors.full_messages.join(', ')
+      fail! code: :validation_failed, message: errors.full_messages.join(', ')
     end
 
 
@@ -119,7 +155,7 @@ module Rails
         message: record.errors.full_messages.join(', ')
       )
 
-      raise UseCase::Error, "#{record.class.name} is not valid"
+      fail! code: :save_failed, message: errors.full_messages.join(', ')
     end
 
 
@@ -140,7 +176,9 @@ module Rails
         success: false,
         record: @record,
         errors: errors,
-        exception: error
+        exception: error,
+        message: error.message,
+        code: @error_code
       )
     end
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rails_use_case
 version: !ruby/object:Gem::Version
-  version: 0.0.7
+  version: 0.0.11
 platform: ruby
 authors:
 - Benjamin Klein
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-05 00:00:00.000000000 Z
+date: 2021-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: 6.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: 6.1.3
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: 6.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.1.0
+        version: 6.1.3
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
@@ -195,7 +195,7 @@ homepage: https://github.com/phortx/rails-use-case
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -210,8 +210,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.1.2
+signing_key:
 specification_version: 4
 summary: Rails UseCase and Service classes
 test_files: []