rails_use_case 0.0.9 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56f84c351e857b7fd1ac1963d18138f96608376c4952fe3a12e8e7db2dbc0152
-  data.tar.gz: 46de14ac109e227a1a36dfdbb7f75a4e0595652c3d0e59189788cbbe8ea1ccd3
+  metadata.gz: 96f24873c4a93a2084c377f236b387605286fd7cbae9915fc53fd85d8f5b07c1
+  data.tar.gz: 7b2d97ab8d3ac97e3cbe5a9b78ec6f0e1590a8f7692bce3a9b207e5891d40577
 SHA512:
-  metadata.gz: 990f15747a27962ea59d7428416c8b525cf297e5e18f592fbaf3feeed8d4eecfe231bc7608acaa6516bc6273973ab651639a272c8b885f8b672fc4cb9b699ecf
-  data.tar.gz: '009f04d247c31452fec07815ff7be8c6af90ba3e5e03ef08f3ac4fd4b87cfcd4103cf44963ffc2a09f8791e8f9430327dd7db98f0d2e11d06feba3b646cbabd1'
+  metadata.gz: dca166f3929ce6782995814218a95cd9d485f2c83ce4f7cd0282d0aa7e3fc83d58c79a65a70a407c8157883f8d6833c371dfc2b64948ba8c9f74aec368b6fe79
+  data.tar.gz: 03b6342cdbd9c244a07ffd034d9873fff5baaef554dd69a1da07f406f4e6dff27da095f1210a4914398b7bf1ba55c005586707c9b59c3e35b467857507a90eb6

data/README.md

@@ -25,30 +25,68 @@ located in the controller. It defines a process via `step` definitions. A UseCas
 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
+  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
@@ -77,12 +115,14 @@ result = CreateBlogPost.perform(
 )
 
 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?`.

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 = 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.9
+  version: 0.0.10
 platform: ruby
 authors:
 - Benjamin Klein
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-04-13 00:00:00.000000000 Z
+date: 2021-10-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -16,28 +16,28 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: 6.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: 6.1.3
 - !ruby/object:Gem::Dependency
   name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: 6.1.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 6.1.0
+        version: 6.1.3
 - !ruby/object:Gem::Dependency
   name: bundler-audit
   requirement: !ruby/object:Gem::Requirement