rails_application_service 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2660a3497bae6216e343a1b8a930f75bbd0dd470ed3229060cc8881438d56b1
-  data.tar.gz: b97c1a7919d2ca70aef177a1701e14416caf3f0a170970bbecfcf10c0e745a49
+  metadata.gz: b7e3b78a33f41ea84a56ce29d482a739d1c4431122ec8eb766d76fd4d4598552
+  data.tar.gz: 5cf617de77f52dad4444d4cdfefbfd84b62e1bf2d54a3e0140dd64d890ab5661
 SHA512:
-  metadata.gz: 5ab05ae5a159d838c65ff1b41badb518df968734462c9d52eaeeed705643de2ca6cf1aec0bc529d0f4d045efc98d4c612ebec5a7f351a953f8205fa9571cce2f
-  data.tar.gz: ef48067c66734b18053e04c6bc87934b9841fc4adcd19e39fe7e526d032d4f64506553c7020d7ffff5b416664e2a517b1d964f4e8dc9bc4fd3360abab5e43e1e
+  metadata.gz: 6116887b8a93ab25f5efcea6ab0e03c3f9cffd75aa7be4df4437956979db258b9d9ac671fa43323ebf26b2e78a5b3787c36ea888c41d07063d46e2c0d99e8948
+  data.tar.gz: cf929d8a4dad1d3f330a35b65cf1506aa67d0c0ab18c3113b9bab6a1451593c1862f74c321bf0a6fac15dd24fdee79073dfbb7f2b9400971c581a13743f7d561

data/CHANGELOG.md

@@ -1,5 +1,83 @@
-## [Unreleased]
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.6.0] - 2025-06-16
+
+### Added
+
+### Changed
+- Enhanced the changelog
+
+### Removed
+
+### Breaking Changes
+
+## [0.5.0] - 2025-06-16
+
+### Added
+
+### Changed
+- Improved code documentation and README
+- Refactored and simplified test specs
+- Fixed Rubocop offenses
+- Updated dependencies
+
+### Removed
+
+### Breaking Changes
+
+## [0.4.0] - 2025-06-16
+
+### Added
+- Added support for `ActiveModel::API` and `ActiveModel::Attributes`
+- Enabled type casting through `ActiveModel::Attributes`
+- Added validation via `ActiveModel::Validations`
+
+### Changed
+- Service initialization now exclusively uses keyword arguments
+- Improved error messages and documentation
+- Enhanced example code in docstrings
+
+### Removed
+- Removed support for positional arguments in the `call` method
+
+### Breaking Changes
+- Services must now use keyword arguments instead of positional arguments
+- All existing services using positional arguments need to be updated
+
+## [0.3.0] - 2025-02-05
+
+### Added
+
+### Changed
+- Refactored source code and tests
+
+### Removed
+
+### Breaking Changes
+
+## [0.2.0] - 2025-02-04
+
+### Added
+
+### Changed
+- Refactored source code and tests
+
+### Removed
+
+### Breaking Changes
 
 ## [0.1.0] - 2025-02-04
 
+### Added
 - Initial release
+
+### Changed
+
+### Removed
+
+### Breaking Changes

data/README.md

@@ -1,32 +1,36 @@
-# ApplicationService
+# Rails Application Service
 
-Service objects for Rails - the Rails way. This Ruby gem adds service objects to Rails applications.
+Service objects for Rails, the Rails way. This Ruby gem adds service objects to your Rails applications.
 
 ## Installation
 
-**1 - Add the gem to the Rails application's Gemfile by entering:**
+**1 - Add the gem to your Rails application's Gemfile:**
 
 ```bash
-gem add application_service
+bundle add rails_application_service
 ```
 
-**2 - Install the gem into the Rails application's directory by running:**
+**2 - Install the gem by running:**
 
 ```bash
 bundle install
 ```
 
-**3 - Create a `app/services` subdirectory into the Rails application's directory by running:**
+**3 - Create an `app/services` directory in your Rails application:**
+
 ```bash
 mkdir -p app/services
 ```
 
 ## Usage
 
-The `ApplicationService::Base` class provides a standard interface for calling service objects. It defines a class method `call` that initializes a new instance of the service object and invokes its `call` instance method. The `call` method can accept any number of arguments, which are passed to the initializer of the service object. You can define attributes and validations just like in Active Record, using the same syntax and conventions.
+The `ApplicationService::Base` class provides a standard interface for calling service objects with robust type handling and validations. It leverages `ActiveModel::API` for initialization with keyword arguments, `ActiveModel::Attributes` for type casting, and `ActiveModel::Validations` for input validation.
+
+### Basic service example
 
-### Example of a basic service:
 ```ruby
+require "application_service"
+
 class MyService < ApplicationService::Base
   def call
     # Perform the service action
@@ -36,33 +40,43 @@ end
 my_service = MyService.call # nil
 ```
 
-### Example of a more complete service:
-```ruby
-class Sum < ApplicationService::Base
-  attr_accessor :number_a, :number_b
+### Example with attributes and validations
 
-  validates :number_a, :number_b, presence: true, numericality: { only_integer: true, greater_than: 0 }
+```ruby
+require "application_service"
 
-  def initialize(number_a, number_b)
-    super
+class Sum < ApplicationService::Base
+  attribute :number_a, :integer
+  attribute :number_b, :integer
 
-    self.number_a = number_a
-    self.number_b = number_b
-  end
+  validates :number_a, :number_b, presence: true, numericality: { greater_than: 0 }
 
   def call
-    (number_a + number_b)
+    number_a + number_b
   end
 end
 
-sum = Sum.call(1, 2) # 2
+sum = Sum.call(number_a: 1, number_b: 2) # => 3
 ```
 
+### Supported attribute types
+
+This gem supports the following attribute types through `ActiveModel::Attributes` and custom types defined in `ActiveModel::Type`:
+
+- `:boolean`
+- `:date`
+- `:datetime`
+- `:decimal`
+- `:float`
+- `:integer`
+- `:string`
+- `:time`
+
 ## 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.
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to execute the tests. You can also run `bin/console` for an interactive prompt to experiment.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, then run `bundle exec rake release`. This will create a git tag for the version, push git commits and the tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
@@ -74,7 +88,7 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the ApplicationService project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/mariomarroquim/rails_application_service/blob/main/CODE_OF_CONDUCT.md).
+Everyone interacting in the ApplicationService project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/mariomarroquim/rails_application_service/blob/main/CODE_OF_CONDUCT.md).
 
 ## Support
 

data/lib/application_service/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ApplicationService
-  VERSION = "0.4.0"
+  VERSION = "0.6.0"
 end

data/lib/application_service.rb

@@ -8,52 +8,61 @@ require "active_model"
 # perform a single action or a series of related actions.
 module ApplicationService
   # The Base class within the ApplicationService module provides a standard
-  # interface for calling service objects. It defines a class method `call`
-  # that initializes a new instance of the service object and invokes its
-  # `call` instance method.
+  # interface for calling service objects with robust type handling and validations.
+  # It leverages ActiveModel::API for initialization with keyword arguments,
+  # ActiveModel::Attributes for type casting, and ActiveModel::Validations for
+  # input validation.
   #
   # Example usage:
-  #   class Sum < ApplicationService::Base
-  #     attr_accessor :number_a, :number_b
-  #
-  #     validates :number_a, :number_b, presence: true, numericality: { only_integer: true, greater_than: 0 }
   #
-  #     def initialize(number_a, number_b)
-  #       super
+  #   class Sum < ApplicationService::Base
+  #     attribute :number_a, :integer
+  #     attribute :number_b, :integer
   #
-  #       self.number_a = number_a
-  #       self.number_b = number_b
-  #     end
+  #     validates :number_a, :number_b, presence: true, numericality: { greater_than: 0 }
   #
   #     def call
-  #       (number_a + number_b)
+  #       number_a + number_b
   #     end
   #   end
   #
-  #   sum = Sum.call(1, 2) # 2
+  #   sum = Sum.call(number_a: 1, number_b: 2) # => 3
   #
-  # The `call` method can accept any number of arguments, which are
-  # passed to the initializer of the service object. You can define
-  # attributes and validations just like in Active Record, using
-  # the same syntax and conventions.
+  # This gem supports the following attribute types through ActiveModel::Attributes and
+  # other custom types defined in ActiveModel::Type:
+  #
+  # - :boolean
+  # - :date
+  # - :datetime
+  # - :decimal
+  # - :float
+  # - :integer
+  # - :string
+  # - :time
   class Base
+    include ::ActiveModel::API
+    include ::ActiveModel::Attributes
     include ::ActiveModel::Validations
 
     # Initializes a new instance of the service object.
     #
-    # @param args [Array] the arguments to be passed to the initializer of the service object
-    # @raise [NotImplementedError] if an attempt is made to instantiate the abstract class directly
-    def initialize(*_args)
-      raise NotImplementedError, "#{self.class} can not be instantiated" if instance_of?(Base)
+    # @param kwargs [Hash] The attributes to be passed to the service object.
+    # @raise [NotImplementedError] if an attempt is made to instantiate the Base class directly.
+    def initialize(**kwargs)
+      super
+
+      if instance_of?(Base)
+        raise ::NotImplementedError, "#{self.class.name} is an abstract class and cannot be instantiated directly"
+      end
     end
 
-    # Initializes a new instance of the service object and invokes its `call` method.
+    # Instantiates a new service object and invokes its `call` method.
     #
-    # @param args [Array] the arguments to be passed to the initializer of the service object
-    # @return [Object] the recently instantiated service object
-    def self.call(*args)
-      service = new(*args)
-
+    # @param kwargs [Hash] The attributes to be passed to the service object.
+    # @return [Object] The result of the service object's call method.
+    # @return [false] If the service object is invalid.
+    def self.call(**kwargs)
+      service = new(**kwargs)
       return false unless service.valid?
 
       service.call
@@ -61,9 +70,9 @@ module ApplicationService
 
     # Encapsulates the implementation to be executed by the service object.
     #
-    # @raise [NotImplementedError] if the method is not implemented in a child class
+    # @raise [NotImplementedError] if the method is not implemented in a child class.
     def call
-      raise NotImplementedError, "The `call` method must be implemented in #{self.class}"
+      raise ::NotImplementedError, "The `call` method must be implemented in #{self.class.name}"
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: rails_application_service
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Mário Marroquim
 bindir: exe
 cert_chain: []
-date: 2025-02-05 00:00:00.000000000 Z
+date: 2025-06-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -62,7 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.3
+rubygems_version: 3.6.6
 specification_version: 4
 summary: Service objects for Rails - the Rails way.
 test_files: []