service_base 1.0.1 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9c9ee7f7424ddd348b82d0708fa79703e7869771284b7018f7e3cb41828770b
-  data.tar.gz: 92032edd435bc81747cbd0a15670e3210716cefd51d8fc7598f7fca5194f5127
+  metadata.gz: 17af4f8d7a5f86ee24adbbbba2118e7b47134f2730e4e04fb0c0107c86cfa168
+  data.tar.gz: 1ad5a04d75c99bbc061d1ab53ce67d0d8864c132b8be85ebeb4da3b1f759d996
 SHA512:
-  metadata.gz: a95dd087bca43238c0ed3e6c94773f61e05758def00c38e9ac4bfd0f258f0eb3514092e404c9f1fd14a9dc47f6f08b4529869d8fa5e489967848396b57347910
-  data.tar.gz: a524e1751b728e6cce6fd723c78b3f5ccb7369e8db0f27a412b42d9be6d4cb35a17e7b6926bae291300ed56e5585b5a97b12dea4b3fdc5efa01f88c86a8be007
+  metadata.gz: 559196375ec8a48520b076feb989287c43e84cf7a759b91d0db753448f9199fe02f3febff0a06e9d797523f5774e58d26e4745f921820f94298519873d4a5732
+  data.tar.gz: ec37a4775094ebf67fa9e09b3db800206f31f8cfa5775866675f0213f9f188f5b228bc503e6e2ff7b3827bcfae039cc1dc0285796e96831ef990f182174a5709

data/README.md

@@ -1,6 +1,10 @@
 # Service Base
 
-A base service class for Ruby applications that provides common functionality and argument type annotations.
+A base service class for Ruby applications that provides common functionality and argument type annotations DSL.
+
+## Dependencies
+
+Simply Ruby. This gem can be used in a standalone fashion and Rails is not a dependency. This gem does, however, work very nicely with Rails conventions and includes generators for getting set up quickly.
 
 ## Installation
 
@@ -11,18 +15,23 @@ gem "service_base"
 ```
 
 And then execute:
-```bash
+```sh
 $ bundle install
 ```
 
 Or install it yourself as:
-```bash
+```sh
 $ gem install service_base
 ```
 
-To follow convention in a Rails application, it's recommended that you create an `ApplicationService` subclass.
+For Rails projects, then run:
+```sh
+rails g service_base:install
+```
 
+Installing the gem in a Rails project will create an `ApplicationService` subclass, following Rails conventions.
 ```rb
+# app/services/application_service.rb
 class ApplicationService < ServiceBase::Service
 end
 ```
@@ -47,46 +56,37 @@ on Rails pattern: Service Objects](https://dev.to/joker666/ruby-on-rails-pattern
 
 ## Advantages
 
-- The action of a service should read as a list of steps which makes
-reading and maintaining the service easy.
+- The action of a service should read as a list of steps which makes reading and maintaining the service easy.
 - Instantiation of a service object allows fine grained control over
 the arguments being passed in and reduces the need to pass arguments
 between methods in the same instance.
 - Encapsulation of logic in a service makes for reusable code, simpler
 testing, and extracts logic from other objects that should not be
 responsible for handling that logic.
+- Removes the need for ActiveRecord callbacks and consolidates logic of related models into one place in the codebase.
 - Verb-naming makes the intention of the service explicit.
 - Single service actions reveal a single public interface.
 
 ## What defines a service?
 
-- The main difference between a model and a service is that a model
-“models” **what** something is while a service lists
-**how** an action is performed.
+- The main difference between a model and a service is that a model “models” **what** something is while a service lists **how** an action is performed.
 - A service has a single public method, ie. `call`
-- A model is a noun, a service is a verb’ed noun that does the one
-thing the name implies
-    - Ie. `User` (model) versus `User::CreatorService` (service)
-    - Ie. `StripeResponse` (model) versus `PaymentHistoryFetcherService` (service)
+- A model is a noun, a service is a verb or verb’ed noun that does the one thing the name implies
+  - Ie. `User` (model) versus `User::CreatorService` (service)
+  - Ie. `StripeResponse` (model) versus `PaymentHistoryFetcherService` (service)
 
 ## Naming
 
-One of the best ways to use the service pattern is for CRUD services - Ie. `ActiveRecordModel` +
-`::CreateService`, `::UpdateService`,
-`::DeleteService`. This avoids the use of callbacks, mystery guests, and unexpected side effects because all the steps to do a CRUD action are in one place and in order.
+One of the best ways to use the service pattern is for CRUD services - Ie. `ActiveRecordModel` + `::CreateService`, `::UpdateService`, `::DeleteService`. This avoids the use of callbacks, mystery guests, and unexpected side effects because all the steps to do a CRUD action are in one place and in order of execution.
 
 ## Returning a Result
 
-Each service inheriting from BaseService must define
-`#call` and return a `Success` or
-`Failure`. These types are `Result` Monads from
-the dry-monads gem. Both `Result` types may take any value as
-input, ie. `Success(user)`,
-`Failure(:not_found)`
+Each service inheriting from BaseService must define `#call` and return a `Success` or `Failure`. These types are `Result` Monads from
+the [dry-monads gem](https://dry-rb.org/gems/dry-monads/1.3/). Both `Result` types may take any value as input, ie. `Success(user)`, `Failure(:not_found)`
 
 `Failure` can return any value you’d like the caller to have in order to understand the failure.
 
-The caller of service can unwrap the Success, Failure or like so
+The caller of service can unwrap the `Success` or `Failure`.
 
 ```ruby
 MyService.call(name: user.name) do |on|
@@ -95,8 +95,7 @@ MyService.call(name: user.name) do |on|
 end
 ```
 
-To match different expected values of success or failure, pass the
-value as an argument.
+To match different expected values of success or failure, pass the value as an argument when unwrapping it.
 
 ```ruby
 MyService.call(name: user.name) do |on|
@@ -107,36 +106,23 @@ MyService.call(name: user.name) do |on|
 end
 ```
 
-Note that you must define both `on.success` and
-`on.failure` or else an error will be raised in the
-caller.
+Note that you must define both `on.success` and `on.failure` or else an error will be raised in the caller.
 
-Note that `raise`ing an error requires an error class
-unless the error itself is an instance of an error class.
+Note that `raise`ing an error requires an error class unless the error itself is an instance of an error class.
 
-Please see [result](https://dry-rb.org/gems/dry-monads/1.3/result/) for
-additional mechanisms used for chaining results and handling
-success/failure values.
-
-A recommended pattern within services is to return a
-`Success` and/or `Failure` from each method and
-yield the result in the caller. This forces you to consider how each
-method could fail and allows for automatic bubbling up of the
-`Failure` via railway-style programming. Examples at [https://dry-rb.org/gems/dry-monads/1.3/do-notation/#adding-batteries](https://dry-rb.org/gems/dry-monads/1.3/do-notation/#adding-batteries)
+Please see [result](https://dry-rb.org/gems/dry-monads/1.3/result/) for additional mechanisms used for chaining results and handling success/failure values.
 
 ## Failures vs Exceptions
 
-Failure = a known error case that may happen and should be gracefully
-handled
+Failure = a known error case that may happen and should be gracefully handled
 
-Raising = an unexpected exception (exceptional circumstances)
+Raising = an **unexpected** exception (exceptional circumstances)
 
 Any call that `raise`s is not rescued by default and will
-behave as a typical Ruby exception. This is a good thing. We will be
+behave as a typical Ruby exception. This is a good thing. You will be
 alerted when exceptional circumstances arise.
 
-Return a `Failure` instead when you know of a potential
-failure case.
+Return a `Failure` instead when you know of a potential failure case.
 
 Avoid rescuing major error/exception superclasses such as
 `StandardError`. Doing so will rescue all subclasses of that
@@ -161,81 +147,104 @@ end
 ## Arguments
 
 Arguments to a service are defined via the `argument` DSL.
-The positional name and type arguments are required, the other options
-are as follows.
-`argument(:name, String, optional: true, description: "The User's name")`
-
-If an argument is optional and has a default value, simply set
-`default: your_value` but do not also specify
-`optional: true`. Doing so will raise an
-`ArgumentError`. Additionally, be sure to
-`.freeze` any mutable default values, ie.
-`default: {}.freeze`. Failure to do so will raise an
-`ArgumentError`.
+The positional name and type arguments are required, the other options are as follows.
+`argument(:name, Type::String, optional: true, description: "The User's name")`
 
-Empty strings attempted to coerce into integers will throw an error.
-See [https://github.com/dry-rb/dry-types/issues/344#issuecomment-518743661](https://github.com/dry-rb/dry-types/issues/344#issuecomment-518743661)
-To instead accept `nil`, do the following:
-`argument(:some_integer, Params::Nil | Params::Integer)`
+If an argument is optional and has a default value, simply set `default: your_value` but do not also specify `optional: true`.
+Doing so will raise an `ArgumentError`.
+
+Additionally, be sure to `.freeze` any mutable default values, ie.  `default: {}.freeze`.
+Failure to do so will raise an `ArgumentError`.
+
+To allow multiple types as arguments, use `|`. For example,
+
+```rb
+argument(:value, Type::String | Type::Integer)
+```
 
-A service should also define a `description`. This is
-recommended for self-documentation, ie.
+A service should also define a `description`. This is recommended for self-documentation, ie.
 
 ```ruby
-class MyService < ServiceBase::Service
+class MyService < ApplicationService
   description("Does a lot of cool things")
 end
 ```
 
-To get the full hash of `argument`s passed into a service,
-use `attributes`. This is a very useful technique for
-services that update an object. For example
+To get the full hash of `argument`'s keys and values passed into a service,
+call `arguments`. This is a very useful technique for services that update an object. For example
 
 ```ruby
-class User::UpdateService < ServiceBase::Service
+class User::UpdateService < ApplicationService
+  argument(:name, String)
+
   def call
-    user.update(attributes)
+    user.update(arguments)
   end
 end
 ```
 
-### ApplicationRecord Args
+### Nil
 
-If you add `ApplicationRecord = Types.Instance(ApplicationRecord)` in a Rails project, you can accept any `ApplicationRecord` via
+Empty strings attempted to coerce into integers will throw an error.
+See [this GH issue for an explaination](https://github.com/dry-rb/dry-types/issues/344#issuecomment-518743661)
+To instead accept `nil`, do the following:
+`argument(:some_integer, Type::Params::Nil | Type::Params::Integer)`
 
-`argument(:my_record, ApplicationRecord)`
 
-You can also limit the type of AR record via
+## Types
 
-`argument(:my_record, Types.Instance(MyRecord))`
+Argument types come from, [Dry.rb’s Types](https://dry-rb.org/gems/dry-types/1.2/built-in-types/), which can be extended.
+You may also add custom types as outlined in [Dry.rb Custom Types](https://dry-rb.org/gems/dry-types/1.2/custom-types/).
 
-## Types
+The Rails generators will create a Type module, which includes `ServiceBase::Types`, which includes `Dry.Types`. Therefore, all types defined in Dry.rb's Types are available to you.
 
-Argument types are defined in Types, which can be extended, ie. app/models/types.rb, and are an extension of [Dry.rb’s
-Types](https://dry-rb.org/gems/dry-types/1.2/built-in-types/). In order to access constants outside of the dry.rb namespace,
-or to access a type that collides with one of our defined types, you
-must include `::` to allow a global constant search.
+```rb
+# app/models/type.rb
+module Type
+  include ServiceBase::Types
+
+  # Any ApplicationRecord subclass
+  ApplicationRecord = Dry.Types.Instance(ApplicationRecord)
+  User = Dry.Types.Instance(User)
+  Project = Dry.Types.Instance(Project)
+
+  # Controller params are an ActionController::Parameters instance or a hash (easier for testing)
+  ControllerParams = Dry.Types.Instance(ActionController::Parameters) | Dry.Types.Instance(Hash)
+
+  # Customer param hashes
+  AddressParams = Dry::Types['hash'].schema(
+    address: Dry::Types['string'],
+    address2: Dry::Types['string'],
+    city: Dry::Types['string'],
+    state: Dry::Types['string'],
+    zip: Dry::Types['string']
+  )
+end
 
-Ie. `::ApplicationRecord...`
+# app/services/example_service.rb
+class ExampleService < ApplicationService
+  argument(:any_model, Type::ApplicationRecord, description: "The model to update")
+  argument(:params, Type::ControllerParams, description: "The attributes to update")
+  argument(:user, Type::User, description: "A cool user that relates to the model")
+  argument(:project, Type::Project, description: "A project that the user is working on")
+  argument(:address, Type::AddressParams, description: "The user's address")
+end
+```
 
-`Coercible` and `Params` Types are very
-powerful and recommended for automatic parsing of inputs, ie. controller
-parameters.
+Dry.rb's `Coercible` and `Params` Types are very powerful and recommended for automatic parsing of inputs, ie. controller parameters.
 
-For example `argument(:number, Params::Integer)` will
-convert `"12"` ⇒ `12`
+For example `argument(:number, Type::Params::Integer)` will convert `"12"` ⇒ `12`.
 
-Entire hash structures may also be validated and automatically
-parsed, for example:
+Entire hash structures may also be validated and automatically parsed, for example:
 
 ```ruby
 argument(
   :line_items,
-  Array(
-    Hash.schema(
-      vintage_year: Params::Integer,
-      number_of_credits: Params::Integer,
-      price_dollars_usd: Params::Float,
+  Type::Array(
+    Type::Hash.schema(
+      vintage_year: Type::Params::Integer,
+      number_of_credits: Type::Params::Integer,
+      price_dollars_usd: Type::Params::Float,
     ),
   ),
 ```
@@ -266,10 +275,10 @@ roll the transaction back](https://www.loyalty.dev/posts/returning-from-transact
 
 ## Internal Method Result
 
-The Railway Pattern can be used internally within services via
-`yield` and `do` notation. This forces the
-programmer to think about the success and failure cases within each
-method. See [the dry-monads gem](https://dry-rb.org/gems/dry-monads/1.3/) for more details.
+A recommended pattern within services is to return a `Success` and/or `Failure` from each method and
+`yield` the result in the caller. This forces you to consider how each
+method could fail and allows for automatic bubbling up of the
+`Failure` via railway-style programming. Examples at [https://dry-rb.org/gems/dry-monads/1.3/do-notation/#adding-batteries](https://dry-rb.org/gems/dry-monads/1.3/do-notation/#adding-batteries)
 
 If the internal methods of the service need to unwrap values, those specific methods need to be registered with the result matcher like so.
 
@@ -323,4 +332,4 @@ Bug reports and pull requests are welcome on GitHub.
 
 ## License
 
-The gem is available as open source under the terms of the MIT License.
+The gem is available as open source under the terms of the MIT License.

data/lib/generators/application_service_generator.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+class ApplicationServiceGenerator < Rails::Generators::Base
+  source_root File.expand_path('templates', __dir__)
+
+  def create_application_service_file
+    service_path = 'app/services/application_service.rb'
+
+    if File.exist?(service_path)
+      # File exists, check if it needs to be updated
+      content = File.read(service_path)
+
+      unless content.include?('class ApplicationService < ServiceBase::Service')
+        # Update the class definition
+        new_content = content.sub(/class ApplicationService.*\n/, "class ApplicationService < ServiceBase::Service\n")
+        File.write(service_path, new_content)
+      end
+    else
+      # Create new file with template
+      create_file service_path, <<~RUBY
+        class ApplicationService < ServiceBase::Service
+        end
+      RUBY
+    end
+  end
+end

data/lib/generators/service_base/install_generator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module ServiceBase
+  class InstallGenerator < Rails::Generators::Base
+    source_root File.expand_path('templates', __dir__)
+
+    def run_generators
+      generate 'application_service'
+      generate 'types'
+    end
+  end
+end

data/lib/generators/types_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+class TypesGenerator < Rails::Generators::Base
+  source_root File.expand_path('templates', __dir__)
+
+  def create_types_file
+    types_path = 'app/models/type.rb'
+
+    if File.exist?(types_path)
+      # File exists, check if it needs the include statement
+      content = File.read(types_path)
+
+      unless content.include?('include ServiceBase::Types')
+        # Add include statement at the top of the module
+        new_content = content.sub(/module Type\s*\n/, "module Type\n  include ServiceBase::Types\n")
+        File.write(types_path, new_content)
+      end
+    else
+      # Create new file with template
+      create_file types_path, <<~RUBY
+        module Type
+          include ServiceBase::Types
+        end
+      RUBY
+    end
+  end
+end

data/lib/service_base/argument_type_annotations.rb

@@ -7,10 +7,6 @@ module ServiceBase
         if !klass.is_a?(Class) || !klass.ancestors.include?(Dry::Struct)
           raise(TypeError, "#{name} should be extended on a Dry::Struct subclass")
         end
-
-        # `Types` overrides default types to help shorthand Type::String.
-        # To access Ruby's native types within a service, use `::`, ie. `::String`
-        klass.include(Types)
       end
 
       def included(klass)

data/lib/service_base/service.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require 'dry-matcher'
-require 'dry-struct'
-require 'dry/matcher/result_matcher'
 require 'dry/monads'
 require 'dry/monads/do'
+require 'dry/matcher/result_matcher'
+require 'dry-struct'
+require 'dry-matcher'
 require 'memery'
 
 module ServiceBase
@@ -95,24 +95,16 @@ module ServiceBase
       end
     end
 
+    # Returns a hash of all arguments and their values
+    def arguments
+      attributes
+    end
+
     private
 
     # The call method that must be defined by every inheriting service class
     def call
       raise(NotImplementedError)
     end
-
-    # A locale lookup helper that uses the name of the service
-    def locale(selector, args = {})
-      class_name = self.class.name.gsub('::', '.').underscore
-      I18n.t(".#{selector}", scope: "services.#{class_name}", **args)
-    end
-
-    # Structured Monad Result Failure type for returning a ResponseError
-    class ResponseFailure < Dry::Monads::Result::Failure
-      def initialize(message, code, trace = Dry::Monads::RightBiased::Left.trace_caller)
-        super(ResponseError.new(message: message, code: code), trace)
-      end
-    end
   end
 end

data/lib/service_base/types.rb

@@ -1,20 +1,14 @@
-# frozen_string_literal: true
-
-# Defines Dry Types. These Types are included in the ServiceBase for type
-# enforcement when defining `argument`s.
-#
-# For example, you may want to add `ApplicationRecord = Types.Instance(ApplicationRecord)`
-#
-# Add custom types as outlined in
-# https://dry-rb.org/gems/dry-types/1.2/custom-types/
-
 require 'dry-types'
 
 module ServiceBase
   module Types
     include Dry.Types()
 
-    UpCasedString = Types::String.constructor(&:upcase)
-    Boolean = Bool # alias the built in type, Bool
+    def self.included(base)
+      constants.each { |constant| base.const_set(constant, const_get("#{self}::#{constant}")) }
+    end
+
+    # Alias Bool -> Boolean
+    Boolean = Dry::Types['bool']
   end
 end

data/lib/service_base/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ServiceBase
-  VERSION = '1.0.1'
+  VERSION = '1.0.3'
 end

data/lib/service_base.rb

@@ -1,9 +1,9 @@
 # frozen_string_literal: true
 
 require_relative 'service_base/version'
-require_relative 'service_base/types'
 require_relative 'service_base/argument_type_annotations'
 require_relative 'service_base/service'
+require_relative 'service_base/types'
 
 module ServiceBase
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: service_base
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.3
 platform: ruby
 authors:
 - James Klein
 bindir: bin
 cert_chain: []
-date: 2025-04-02 00:00:00.000000000 Z
+date: 2025-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-matcher
@@ -89,6 +89,9 @@ extra_rdoc_files: []
 files:
 - LICENSE.txt
 - README.md
+- lib/generators/application_service_generator.rb
+- lib/generators/service_base/install_generator.rb
+- lib/generators/types_generator.rb
 - lib/service_base.rb
 - lib/service_base/argument_type_annotations.rb
 - lib/service_base/rspec.rb