rails_use_case 0.0.8 → 0.0.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 789a956d7cf0a8545c91465e9a664e44aa5ae79481127f954cf4e7a4b2b90ec4
-  data.tar.gz: 9be655cf0d0c3e16c81ce8700af3b2952ba82e3b6a1dc2b28c87880ba8c6e281
+  metadata.gz: c46cd0289d56e4cf86a62f9e1dd780b5fe311c9f7426dfdb942cab5a1b8b8b74
+  data.tar.gz: cd02462628e21a6fbda7bed59f237d0b1fdbf1a082d148747404ded5c2b0e365
 SHA512:
-  metadata.gz: 0a01d5e6930473a0140ce41ca2b0d6744c4bc4af1a9d425afe6416a639de96b40410a1d67c1858cb439d7813553a6edc32712754fd099d541cf81a6088c05e70
-  data.tar.gz: 661ae29ab31c2b4b69b3843758c36e5bbab74392dfc621375aa6ac9cb835c15a1f3e83cb5af5e1c04720504593e1d7aff903d997e7d1235e6d68049e52ffe984
+  metadata.gz: 6bd525db88d52a6b9563fed40b80e69d9bc035f115fa77ae6a5668688df7576d5426e4f8caba222986e741b4fa61c9790b75751b582913b009217089998fd8ac
+  data.tar.gz: 2274ca1dfa0312c2bd9f1e2cc8245665bde540b30919c4eefe0875e3d0eba1a3609d2a55c4acac40849e8d237a20bd228ad6aabcaabac8f2c4c50f79cbd9e1bc

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,37 +22,88 @@ 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.
+
+You can either set the `@record` manually or via the `record` method. This comes
+in two flavors:
+
+Either passing the name of a param as symbol. Let's assume the UseCase
+has a parameter called `user` (defined via `attr_accessor`), then you can assign
+the user to `@record` by adding `record :user` to your use case.
+
+The alternative way is to pass a block which returns the value for `@record`
+like in the example UseCase below.
 
 
 ### 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 }
+  record { BlogPost.new }
+
+  failure :access_denied, message: 'No permission', unless: -> { author.can_publish_blog_posts? }
+  step    :assign_attributes
+  step    :save!
+  succeed unless: -> { publish }
+  step    :publish, do: -> { record.publish! }
+  step    :notify_subscribers, unless: -> { skip_notifications }
 
 
-  private def build_post
-    @record = BlogPost.new(
+  private def assign_attributes
+    @record.assign_attributes(
       title: title,
       content: content,
       created_by: author,
@@ -67,22 +120,69 @@ 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
+    }
+
+    outcome = BlogPosts::Create.perform(parameters).code
+
+    case outcome.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

@@ -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)
@@ -49,17 +67,51 @@ module Rails
     end
 
 
+    # DSL to set the record source.
+    # @param [Symbol|nil] Name of the param.
+    # @yields
+    def self.record(param = nil, &block)
+      block = -> { send(param.to_sym) } unless block_given?
+
+      define_method(:determine_record, &block)
+    end
+
+
     # Will run the steps of the use case.
     def process
+      @record = determine_record if respond_to?(:determine_record)
+      run_steps
+    end
+
+
+    def run_steps
       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 +145,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 +171,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 +192,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.8
+  version: 0.0.12
 platform: ruby
 authors:
 - Benjamin Klein
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-05 00:00:00.000000000 Z
+date: 2021-10-06 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: []