active_call 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4673cf511194223bf9481aa7ed85507c9162556b20469f28c9421cc59f4230a9
-  data.tar.gz: 20fed6531fd0ac7bc7c6e6f8ffb03d336c82e6b91131354c3c5da6e202ea56b0
+  metadata.gz: e129c0113e02eef8e739a830213f343eddb585c6798f4237f127256b1a5ac419
+  data.tar.gz: 550cdfc7e5285f9dc353003eb570fc89ae1d36d54025af035ab2a4751b61658a
 SHA512:
-  metadata.gz: 0064c55032419b699535d0f19cfbf90d730089f57da8a7ac360bdb96fbb7f40dc6d2a19859baec6074e180aef6ef290a45bb818ba872a5418f2ad8c0432786cf
-  data.tar.gz: bea908f7aeb097617edaf7694a5fffd21e8ef6f3a90f8fdcebd8e4efd23cf90fba289df598914c35540b16400b7ae46dd6ce4c4bd5df29e1b42feb1ad6dabfa2
+  metadata.gz: 91d837ea7bead55372e4eaf777f84f35ac4ad3a9183633e9bc9042d14cdf26ae02c425a30391ff4dc85116d66d38edb62202fa114c5657c9c5bee60fa02bde83
+  data.tar.gz: 4025432ebc6ef1dbf2cbe5129b4e235808ab91ded26d192c04b7253bca008423e6d054808e3f774421e86bc42465e005ee0e4bfd26241ab19e685fc6ffc219d2

data/.rubocop.yml

@@ -15,6 +15,9 @@ AllCops:
     - 'vendor/**/*'
     - 'gem/**/*'
 
+Layout/LineEndStringConcatenationIndentation:
+  EnforcedStyle: indented
+
 Lint/MissingSuper:
   AllowedParentClasses:
     - ActiveCall::Base
@@ -23,6 +26,11 @@ Metrics/BlockLength:
   Exclude:
     - spec/*/**.rb
 
+Metrics/MethodLength:
+  AllowedMethods:
+    - call
+    - call!
+
 RSpec/ExampleLength:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-03-20
+
+- Added method `.call!` with a bang, which will raise an `ActiveCall::ValidationError` exception when validation fails and an `ActiveCall::RequestError` exception when errors were added to the service object in the `after_call` callback.
+- Use new method `success?` instead of `valid?`.
+- Method `valid?` will return `true` if the service object passed validation and was able to make the `call` method.
+- Use `validate, on: :response` to validate the response object.
+- Raise `NotImplementedError` when `call` is not defined in subclasses.
+- Use `self.abstract_class = true` to treat the class as a base class that does not define a `call` method.
+- Adding a `@bang` instance variable on the service objects to determine if `call` or `call!` was invoked.
+- Don't set `@response` if the object is an `Enumerable`. The response will be set in `each` and not `call`.
+
 ## [0.1.0] - 2025-03-08
 
 - Initial release

data/README.md

@@ -4,46 +4,64 @@ Active Call provides a standardized way to create service objects.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add active_call
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install active_call
 ```
 
 ## Usage
 
 Your child classes should inherit from `ActiveCall::Base`.
 
-Now you can start adding your own service object classes in your gem's `lib` folder.
+You can add your own service object classes in your gem's `lib` folder or your project's `app/services` folder.
 
 Each service object must define only one public method named `call`.
 
-A `response` attribute is set with the result of the `call` method.
+### Logic Flow
+
+1. **Before** invoking `call`.
+
+  - Validate the request with `validates`.
+
+  - Use the `before_call` hook to set up anything **after validation** passes.
+
+2. **During** `call` invocation.
+
+  - A `response` attribute gets set with the result of the `call` method.
+
+3. **After** invoking `call`.
+
+  - Validate the response with `validate, on: :response`.
 
-An `errors` object will be set if you specified any validations that failed before the `call` method could be invoked.
+  - Use the `after_call` hook to set up anything **after response validation** passes.
 
-There is also a `before_call` hook to set up anything before invoking the `call` method. This only happens after all validations have passed.
+### Example Service Object
 
 Define a service object with optional validations and callbacks.
 
 ```ruby
 require 'active_call'
 
-class YourGemName::SomeResource::GetService < ActiveCall::Base
+class YourGemName::SomeResource::CreateService < ActiveCall::Base
   attr_reader :message
 
   validates :message, presence: true
 
+  validate on: :response do
+    errors.add(:message, :invalid, message: 'cannot be baz') if response[:foo] == 'baz'
+  end
+
   before_call :strip_message
 
+  after_call :log_response
+
   def initialize(message: nil)
     @message = message
   end
@@ -57,41 +75,89 @@ class YourGemName::SomeResource::GetService < ActiveCall::Base
   def strip_message
     @message.strip!
   end
+
+  def log_response
+    puts "Successfully called #{response}"
+  end
 end
 ```
 
-You will get a **response** object.
+### Using `.call`
+
+You will get an **errors** object when validation fails.
 
 ```ruby
-service = YourGemName::SomeResource::GetService.call(message: ' bar ')
-service.valid? # => true
-service.response # => { foo: 'bar' }
+service = YourGemName::SomeResource::CreateService.call(message: '')
+service.success? # => false
+service.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=blank, options={}>]>
+service.errors.full_messages # => ["Message can't be blank"]
+service.response # => nil
 ```
 
-And an **errors** object when validation failed.
+A **response** object on a successful `call` invocation.
 
 ```ruby
-service = YourGemName::SomeResource::GetService.call(message: '')
-service.valid? # => false
-service.errors.full_messages # => ["Message can't be blank"]
-service.response # => nil
+service = YourGemName::SomeResource::CreateService.call(message: ' bar ')
+service.success? # => true
+service.response # => {:foo=>"bar"}
 ```
 
-If you have secrets, use a **configuration** block.
+And an **errors** object if you added errors during the `validate, on: :response` validation.
 
 ```ruby
-require 'net/http'
+service = YourGemName::SomeResource::CreateService.call(message: 'baz')
+service.success? # => false
+service.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=invalid, options={:message=>"cannot be baz"}>]>
+service.errors.full_messages # => ["Message cannot be baz"]
+service.response # => {:foo=>"baz"}
+```
+
+### Using `.call!`
 
+An `ActiveCall::ValidationError` **exception** gets raised when validation fails.
+
+```ruby
+begin
+  service = YourGemName::SomeResource::CreateService.call!(message: '')
+rescue ActiveCall::ValidationError => exception
+  exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=blank, options={}>]>
+  exception.errors.full_messages # => ["Message can't be blank"]
+end
+```
+
+A **response** object on a successful `call` invocation.
+
+```ruby
+service = YourGemName::SomeResource::CreateService.call!(message: ' bar ')
+service.success? # => true
+service.response # => {:foo=>"bar"}
+```
+
+And an `ActiveCall::RequestError` **exception** gets raised if you added errors during the `validate, on: :response` validation.
+
+```ruby
+begin
+  service = YourGemName::SomeResource::CreateService.call!(message: 'baz')
+rescue ActiveCall::RequestError => exception
+  exception.errors # => #<ActiveModel::Errors [#<ActiveModel::Error attribute=message, type=invalid, options={:message=>"cannot be baz"}>]>
+  exception.errors.full_messages # => ["Message cannot be baz"]
+  exception.response # => {:foo=>"baz"}
+end
+```
+
+## Configuration
+
+If you have secrets, use a **configuration** block.
+
+```ruby
 class YourGemName::BaseService < ActiveCall::Base
-  config_accessor :api_key, default: ENV['API_KEY'], instance_writer: false
+  self.abstract_class = true
 
-  def call
-    Net::HTTP.get_response(URI("http://example.com/api?#{URI.encode_www_form(api_key: api_key)}"))
-  end
+  config_accessor :api_key, default: ENV['API_KEY'], instance_writer: false
 end
 ```
 
-Then in your application code you can overrite the configuration defaults.
+Then in your application code you can overwite the configuration defaults.
 
 ```ruby
 YourGemName::BaseService.configure do |config|
@@ -99,6 +165,18 @@ YourGemName::BaseService.configure do |config|
 end
 ```
 
+And implement a service object like so.
+
+```ruby
+require 'net/http'
+
+class YourGemName::SomeResource::CreateService < YourGemName::BaseService
+  def call
+    Net::HTTP.get_response(URI("http://example.com/api?#{URI.encode_www_form(api_key: api_key)}"))
+  end
+end
+```
+
 ## Gem Creation
 
 To create your own gem for a service.
@@ -121,6 +199,10 @@ spec.add_dependency 'active_call'
 
 Now start adding your service objects in the `lib` directory and make sure they inherit from `ActiveCall::Base`.
 
+## Gems Using Active Call
+
+- [Zoho Sign](https://github.com/kobusjoubert/zoho_sign)
+
 ## 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/active_call/base.rb

@@ -10,15 +10,84 @@ class ActiveCall::Base
   define_model_callbacks :call
 
   class << self
+    # Set your class to `self.abstract_class = true` if the class is used as a base class and not as a service object.
+    # Abstract classes are not meant to be instantiated directly, but rather inherited from.
+    # The `call` method doesn't need to be implemented in abstract classes.
+    #
+    # Example:
+    #
+    #   class YourGemName::BaseService < ActiveCall::Base
+    #     self.abstract_class = true
+    #   end
+    #
+    #   class YourGemName::SomeResource::CreateService < YourGemName::BaseService
+    #     def call
+    #       # Implementation specific to this service.
+    #     end
+    #   end
+    #
+    attr_accessor :abstract_class
+
+    def abstract_class?
+      @abstract_class == true
+    end
+
+    # TODO: Refactor `call` and `call!`. The only differences are the two lines raising exceptions.
     def call(...)
       service_object = new(...)
-      return service_object if service_object.invalid?
+      service_object.instance_variable_set(:@bang, false)
+      return service_object if service_object.invalid?(except_on: :response)
+
+      service_object.run_callbacks(:call) do
+        next if service_object.is_a?(Enumerable)
+
+        service_object.instance_variable_set(:@response, service_object.call)
+        service_object.validate(:response)
+
+        return service_object unless service_object.success?
+      end
+
+      service_object
+    end
+
+    def call!(...)
+      service_object = new(...)
+      service_object.instance_variable_set(:@bang, true)
+      raise ActiveCall::ValidationError, service_object.errors if service_object.invalid?(except_on: :response)
 
       service_object.run_callbacks(:call) do
+        next if service_object.is_a?(Enumerable)
+
         service_object.instance_variable_set(:@response, service_object.call)
+        service_object.validate(:response)
+
+        unless service_object.success?
+          raise ActiveCall::RequestError.new(service_object.response, service_object.errors)
+        end
       end
 
       service_object
     end
   end
+
+  def success?
+    errors.empty?
+  end
+
+  def valid?(context = nil)
+    return true if response
+
+    super
+  end
+
+  def bang?
+    !!@bang
+  end
+
+  def call
+    return if self.class.abstract_class?
+
+    raise NotImplementedError, 'Subclasses must implement a call method. If this is an abstract base class, set ' \
+      '`self.abstract_class = true`.'
+  end
 end

data/lib/active_call/concerns/request_errorable.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module ActiveCall::RequestErrorable
+  extend ActiveSupport::Concern
+
+  included do
+    attr_reader :response, :errors
+  end
+
+  def initialize(response = nil, errors = ActiveModel::Errors.new(self), message = nil)
+    @response = response
+    @errors   = errors
+    message   ||= errors.full_messages.to_sentence.presence || 'Request failed'
+
+    super(message)
+  end
+end

data/lib/active_call/concerns/validation_errorable.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module ActiveCall::ValidationErrorable
+  extend ActiveSupport::Concern
+
+  included do
+    attr_reader :errors
+  end
+
+  def initialize(errors = ActiveModel::Errors.new(self), message = nil)
+    @errors = errors
+    message ||= errors.full_messages.to_sentence.presence || 'Validation failed'
+
+    super(message)
+  end
+end

data/lib/active_call/error.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module ActiveCall
+  class Error < StandardError; end
+
+  class ValidationError < Error
+    include ActiveCall::ValidationErrorable
+  end
+
+  class RequestError < Error
+    include ActiveCall::RequestErrorable
+  end
+end

data/lib/active_call/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ActiveCall
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/active_call.rb

@@ -3,11 +3,12 @@
 require 'active_model'
 require 'zeitwerk'
 
-require_relative 'active_call/version'
-
 loader = Zeitwerk::Loader.for_gem
+loader.ignore("#{__dir__}/active_call/error.rb")
+loader.collapse("#{__dir__}/active_call/concerns")
 loader.setup
 
-module ActiveCall
-  class Error < StandardError; end
-end
+require_relative 'active_call/error'
+require_relative 'active_call/version'
+
+module ActiveCall; end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: active_call
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Kobus Joubert
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-03-10 00:00:00.000000000 Z
+date: 2025-03-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -53,6 +53,9 @@ files:
 - Rakefile
 - lib/active_call.rb
 - lib/active_call/base.rb
+- lib/active_call/concerns/request_errorable.rb
+- lib/active_call/concerns/validation_errorable.rb
+- lib/active_call/error.rb
 - lib/active_call/version.rb
 - sig/active_call.rbs
 homepage: https://github.com/kobusjoubert/active_call