rails_use_case 0.0.6 → 0.0.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 54ea39257a8eca46fc85b8e8f6b7cd8523f953b9ec27dd25a3efe52f78f4fc18
-  data.tar.gz: e9fb8c9f2302c110914fc071aba9646a665f02e8218abf80b5fe0e7d4a916f35
+  metadata.gz: 96f24873c4a93a2084c377f236b387605286fd7cbae9915fc53fd85d8f5b07c1
+  data.tar.gz: 7b2d97ab8d3ac97e3cbe5a9b78ec6f0e1590a8f7692bce3a9b207e5891d40577
 SHA512:
-  metadata.gz: 2ebdad5670ad1543263dff016033b6158567220a6c65d982aa5f839c89ec9c635b7b421e10484439e8fff3ce23915250b5d11c649338e2862c09b46b592ab299
-  data.tar.gz: ffb2d162f29baaf3574435b138748f1da4ae85414015fa0a9accc5de7e486b18f26ed5f0ca8daaf8d019f92337de59126df0f4ad5b07889c867c2c384156c209
+  metadata.gz: dca166f3929ce6782995814218a95cd9d485f2c83ce4f7cd0282d0aa7e3fc83d58c79a65a70a407c8157883f8d6833c371dfc2b64948ba8c9f74aec368b6fe79
+  data.tar.gz: 03b6342cdbd9c244a07ffd034d9873fff5baaef554dd69a1da07f406f4e6dff27da095f1210a4914398b7bf1ba55c005586707c9b59c3e35b467857507a90eb6

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
+  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
@@ -75,14 +115,21 @@ 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?`.
+- 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.
+
+
 
 ## 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 = 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.6
+  version: 0.0.10
 platform: ruby
 authors:
 - Benjamin Klein
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-04-05 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: 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: []