service_base 1.0.0 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d20e049647526253612ef6cf134c73ce8ab076c69e9a1f3a5524586f035f8ae3
-  data.tar.gz: 8fe635ae9d66b5358030440828f45e0706a2cad092e7eb45f9738af5c53c9896
+  metadata.gz: 79ca15b6d1d305ea1dea4ab6633e63725de9f5d5f951c4221b9b59bef38b03ab
+  data.tar.gz: 3bb44ec63bd53452ac09c3fc0f531bf25218dcbb1434b5e8bd0a1dc3f8f75be0
 SHA512:
-  metadata.gz: '0595ddabc674a039b1dfb3189f4f7a6d8aa2e3a6c694391b94c26235180f7b67475685b3c5e19283c07f8b8e141b6c99b109d35659af6ef7d4e436f74ab0a832'
-  data.tar.gz: a38e09b26353baa8a4b37edb97522d33a2bd95a9209f9b930c109f67dbd5d305623c57aa5508c82bdb574150536c37048a5399cb25eed4df5f5c22838456aac4
+  metadata.gz: 4a730fb152af189eb68c07bf5a55a31529605af58a4a8980afbf3369769ec0d3dcf81ab3e6d89ade5b9903dd547fa3f06b2db62edb9621d4ef8edfbab46c2d81
+  data.tar.gz: 2f666d22c5368a817de07145a1e27eb32faf98b326128c9b6c8192fa48eecda9d3d0dd6d36b0eaf8848c7f9c5340b770e726777c4e7f78f2550e0393208ffe94

data/README.md

@@ -20,6 +20,13 @@ Or install it yourself as:
 $ gem install service_base
 ```
 
+To follow convention in a Rails application, it's recommended that you create an `ApplicationService` subclass.
+
+```rb
+class ApplicationService < ServiceBase::Service
+end
+```
+
 # Base Service Pattern
 
 The general concept of a Service Pattern is useful when a you need to execute a set of
@@ -158,13 +165,10 @@ 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`.
+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`.
 
 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)
@@ -175,37 +179,58 @@ A service should also define a `description`. This is
 recommended for self-documentation, ie.
 
 ```ruby
-class MyService < Service
+class MyService < ServiceBase::Service
   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
+To get the full hash of `argument`'s keys and values passed into a service,
+use `arguments`. This is a very useful technique for
 services that update an object. For example
 
 ```ruby
-class User::UpdateService < Service
+class User::UpdateService < ServiceBase::Service
+  argument(:name, String)
+
   def call
-    user.update(attributes)
+    user.update(arguments)
   end
 end
 ```
 
-### ApplicationRecord Args
+## Types
+
+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/).
 
-If you add `ApplicationRecord = Types.Instance(ApplicationRecord)` in a Rails project, you can accept any `ApplicationRecord` via
+It is recommended that you define your own `Type` module and include it in your `ServiceBase` subclass, as so.
 
-`argument(:my_record, ApplicationRecord)`
+```rb
+# app/models/types.rb
+module Types
+  ApplicationRecord = Types.Instance(ApplicationRecord)
+  ControllerParams = ServiceBase::Types.Instance(ActionController::Parameters)
+end
 
-You can also limit the type of AR record via
+# app/services/application_service.rb
+class ApplicationService < ServiceBase::Service
+  include Types
+end
 
-`argument(:my_record, Types.Instance(MyRecord))`
+# app/services/example_service.rb
+class ExampleService < ApplicationService
+  argument(:user, ApplicationRecord, description: "The user to update")
+  argument(:params, ControllerParams, description: "The attributes to update")
+end
+```
 
-## Types
+You can also limit the type of `ApplicationRecord` record via
+
+`argument(:user, Types.Instance(User))`
+
+Or defining `User = Types.Instance(User)`
 
-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,
+Note: 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.
 
@@ -215,11 +240,9 @@ Ie. `::ApplicationRecord...`
 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, 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(

data/lib/service_base/argument_type_annotations.rb

@@ -1,106 +1,104 @@
 # frozen_string_literal: true
 
-module ArgumentTypeAnnotations
-  class << self
-    def extended(klass)
-      if !klass.is_a?(Class) || !klass.ancestors.include?(Dry::Struct)
-        raise(TypeError, "#{name} should be extended on a Dry::Struct subclass")
+module ServiceBase
+  module ArgumentTypeAnnotations
+    class << self
+      def extended(klass)
+        if !klass.is_a?(Class) || !klass.ancestors.include?(Dry::Struct)
+          raise(TypeError, "#{name} should be extended on a Dry::Struct subclass")
+        end
       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)
+        if !klass.singleton_class? || !klass.attached_object.ancestors.include?(Dry::Struct)
+          raise(TypeError, "#{name} should be included on the singleton class of a Dry::Struct subclass")
+        end
 
-    def included(klass)
-      if !klass.singleton_class? || !klass.attached_object.ancestors.include?(Dry::Struct)
-        raise(TypeError, "#{name} should be included on the singleton class of a Dry::Struct subclass")
+        # `Types` overrides default types to help shorthand Type::String.
+        # To access Ruby's native types within a service, use `::`, ie. `::String`
+        klass.attached_object.include(Types)
       end
-
-      # `Types` overrides default types to help shorthand Type::String.
-      # To access Ruby's native types within a service, use `::`, ie. `::String`
-      klass.attached_object.include(Types)
     end
-  end
 
-  # Defines an argument using the ServiceBase DSL.
-  # Under the hood, this uses dry-struct's attribute DSL.
-  def argument(name, type, configuration = {}, &)
-    description = configuration[:description] == "" ? nil : configuration[:description]
-    type = type.meta(description:)
-
-    default = configuration[:default]
-    validate_frozen_default!(name:, default:)
-
-    optional = configuration.fetch(:optional, false)
-    validate_optional_or_default!(optional:, default:, name:)
-
-    type = set_default(type:, default:)
-
-    if optional
-      # attribute? allows the key to be omitted.
-      # .optional allows the value to be nil.
-      # https://dry-rb.org/gems/dry-types/1.2/optional-values/
-      # https://github.com/dry-rb/dry-struct/blob/master/lib/dry/struct/class_interface.rb#L141-L169
-      attribute?(name, type.optional, &)
-    else
-      # https://github.com/dry-rb/dry-struct/blob/master/lib/dry/struct/class_interface.rb#L30-L104
-      attribute(name, type, &)
+    # Defines an argument using the ServiceBase DSL.
+    # Under the hood, this uses dry-struct's attribute DSL.
+    def argument(name, type, configuration = {}, &)
+      description = configuration[:description] == "" ? nil : configuration[:description]
+      type = type.meta(description:)
+
+      default = configuration[:default]
+      validate_frozen_default!(name:, default:)
+
+      optional = configuration.fetch(:optional, false)
+      validate_optional_or_default!(optional:, default:, name:)
+
+      type = set_default(type:, default:)
+
+      if optional
+        # attribute? allows the key to be omitted.
+        # .optional allows the value to be nil.
+        # https://dry-rb.org/gems/dry-types/1.2/optional-values/
+        # https://github.com/dry-rb/dry-struct/blob/master/lib/dry/struct/class_interface.rb#L141-L169
+        attribute?(name, type.optional, &)
+      else
+        # https://github.com/dry-rb/dry-struct/blob/master/lib/dry/struct/class_interface.rb#L30-L104
+        attribute(name, type, &)
+      end
     end
-  end
 
-  private
+    private
 
-  # Raises a warning from dry-types to avoid memory sharing.
-  # https://github.com/dry-rb/dry-types/blob/master/lib/dry/types/builder.rb#L71-L81
-  def validate_frozen_default!(name:, default:)
-    return if default.frozen?
+    # Raises a warning from dry-types to avoid memory sharing.
+    # https://github.com/dry-rb/dry-types/blob/master/lib/dry/types/builder.rb#L71-L81
+    def validate_frozen_default!(name:, default:)
+      return if default.frozen?
 
-    raise(
-      ArgumentError,
-      "#{default} provided as a default value for #{name} is mutable. " \
-      "Please `.freeze` your `default:` input.",
-    )
-  end
+      raise(
+        ArgumentError,
+        "#{default} provided as a default value for #{name} is mutable. " \
+        "Please `.freeze` your `default:` input.",
+      )
+    end
 
-  # Do not allow setting both a default value and optional: true. If both
-  # are specified, the default will not be used.
-  def validate_optional_or_default!(optional:, default:, name:)
-    return unless optional && !default.nil?
+    # Do not allow setting both a default value and optional: true. If both
+    # are specified, the default will not be used.
+    def validate_optional_or_default!(optional:, default:, name:)
+      return unless optional && !default.nil?
 
-    raise(
-      ArgumentError,
-      "#{name} cannot specify both a default value and optional: true. " \
-      "Only specify a default value if the value is optional.",
-    )
-  end
+      raise(
+        ArgumentError,
+        "#{name} cannot specify both a default value and optional: true. " \
+        "Only specify a default value if the value is optional.",
+      )
+    end
 
-  # Ensures that provided args are declared as `argument`s
-  def validate_args!(args:)
-    invalid_args = (args.keys - attribute_names)
-    return if invalid_args.empty?
+    # Ensures that provided args are declared as `argument`s
+    def validate_args!(args:)
+      invalid_args = (args.keys - attribute_names)
+      return if invalid_args.empty?
 
-    raise(
-      ArgumentError,
-      "#{self} provided invalid arguments: #{invalid_args.join(', ')}",
-    )
-  end
+      raise(
+        ArgumentError,
+        "#{self} provided invalid arguments: #{invalid_args.join(', ')}",
+      )
+    end
 
-  # Sets the default value on the type.
-  # For primitive types, the default can be set after initialization.
-  # For enums, the default must be set during initialization. Therefore,
-  # we must check the type of the enum and then reconstruct the enum with
-  # the default value being set.
-  # See "Note" in https://dry-rb.org/gems/dry-types/1.2/enum/
-  def set_default(type:, default:)
-    return type if default.nil?
-
-    if type.is_a?(Dry::Types::Enum)
-      values = type.values
-      type_class = "Types::#{values.first.class}".constantize
-      type_class.default(default).enum(*values)
-    else
-      type.default(default)
+    # Sets the default value on the type.
+    # For primitive types, the default can be set after initialization.
+    # For enums, the default must be set during initialization. Therefore,
+    # we must check the type of the enum and then reconstruct the enum with
+    # the default value being set.
+    # See "Note" in https://dry-rb.org/gems/dry-types/1.2/enum/
+    def set_default(type:, default:)
+      return type if default.nil?
+
+      if type.is_a?(Dry::Types::Enum)
+        values = type.values
+        type_class = "Types::#{values.first.class}".constantize
+        type_class.default(default).enum(*values)
+      else
+        type.default(default)
+      end
     end
   end
 end

data/lib/service_base/service.rb

@@ -1,116 +1,112 @@
 # 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-types'
+require 'dry-struct'
+require 'dry-matcher'
 require 'memery'
 
-class Service < Dry::Struct
-  extend Dry::Monads::Result::Mixin::Constructors
-  include Dry::Monads::Do.for(:call)
-  include Dry::Monads[:result, :do]
+module ServiceBase
+  class Service < Dry::Struct
+    extend Dry::Monads::Result::Mixin::Constructors
+    include Dry::Monads::Do.for(:call)
+    include Dry::Monads[:result, :do]
+    include Dry.Types()
 
-  extend ArgumentTypeAnnotations
-  include Memery
+    extend ArgumentTypeAnnotations
+    include Memery
 
-  class ServiceNotSuccessful < StandardError
-    attr_reader(:failure)
+    class ServiceNotSuccessful < StandardError
+      attr_reader(:failure)
 
-    def initialize(failure)
-      super('Failed to call service')
-      @failure = failure
+      def initialize(failure)
+        super('Failed to call service')
+        @failure = failure
+      end
     end
-  end
 
-  class << self
-    # The public class call method.
-    #
-    # The default empty hash is important to prevent an argument error when
-    # passing no arguments to a service that defines defaults for every argument.
-    def call(args = {}, &block)
-      validate_args!(args: args)
+    class << self
+      # The public class call method.
+      #
+      # The default empty hash is important to prevent an argument error when
+      # passing no arguments to a service that defines defaults for every argument.
+      def call(args = {}, &block)
+        validate_args!(args: args)
 
-      result = new(args).call
-      match_result(result, &block)
-    end
+        result = new(args).call
+        match_result(result, &block)
+      end
 
-    def call!(*args)
-      result = call(*args)
-      raise(ServiceNotSuccessful, result.failure) if result.failure?
+      def call!(*args)
+        result = call(*args)
+        raise(ServiceNotSuccessful, result.failure) if result.failure?
 
-      result
-    end
+        result
+      end
 
-    # Pretty prints (pp) the description of the service, ie. `MyService.pp`
-    def pp
-      logger = Logger.new($stdout)
-      logger.info("#{name}: #{service_description}")
-      logger.info('Arguments')
+      # Pretty prints (pp) the description of the service, ie. `MyService.pp`
+      def pp
+        logger = Logger.new($stdout)
+        logger.info("#{name}: #{service_description}")
+        logger.info('Arguments')
 
-      schema_definition.each do |arg|
-        logger.info("  #{arg[:name]} (#{arg[:type]}): #{arg[:description]}")
+        schema_definition.each do |arg|
+          logger.info("  #{arg[:name]} (#{arg[:type]}): #{arg[:description]}")
+        end
       end
-    end
 
-    # @description getter
-    def service_description
-      @description || 'No description'
-    end
+      # @description getter
+      def service_description
+        @description || 'No description'
+      end
 
-    private
+      private
 
-    # Set the description on the service
-    def description(text)
-      @description = text
-    end
+      # Set the description on the service
+      def description(text)
+        @description = text
+      end
 
-    # Employs ResultMatcher to unwrap values using `on.success` & `on.failure`
-    # syntax. If not using block form to extract the result of a service,
-    # ie. `MyService.call.fmap { |result| result + 2 }`, ensure you explictly
-    # handle Failures. See https://dry-rb.org/gems/dry-monads/1.3/result/
-    def match_result(result, &block)
-      # https://medium.com/swlh/better-rails-service-objects-with-dry-rb-702687394e3d
-      if block
-        # raises Dry::Matcher::NonExhaustiveMatchError: cases +failure+ not handled
-        # if `on.failure` is not declared
-        Dry::Matcher::ResultMatcher.call(result, &block)
-      else
-        result
+      # Employs ResultMatcher to unwrap values using `on.success` & `on.failure`
+      # syntax. If not using block form to extract the result of a service,
+      # ie. `MyService.call.fmap { |result| result + 2 }`, ensure you explictly
+      # handle Failures. See https://dry-rb.org/gems/dry-monads/1.3/result/
+      def match_result(result, &block)
+        # https://medium.com/swlh/better-rails-service-objects-with-dry-rb-702687394e3d
+        if block
+          # raises Dry::Matcher::NonExhaustiveMatchError: cases +failure+ not handled
+          # if `on.failure` is not declared
+          Dry::Matcher::ResultMatcher.call(result, &block)
+        else
+          result
+        end
       end
-    end
 
-    # Introspects the arguments DSL to extract information on each argument
-    def schema_definition
-      attribute_names.each_with_object([]) do |attribute_name, list|
-        dry_type = schema.key(attribute_name)
-        list << {
-          name: attribute_name,
-          description: dry_type.meta[:description],
-          type: dry_type.type.name
-        }
+      # Introspects the arguments DSL to extract information on each argument
+      def schema_definition
+        attribute_names.each_with_object([]) do |attribute_name, list|
+          dry_type = schema.key(attribute_name)
+          list << {
+            name: attribute_name,
+            description: dry_type.meta[:description],
+            type: dry_type.type.name
+          }
+        end
       end
     end
-  end
-
-  private
 
-  # The call method that must be defined by every inheriting service class
-  def call
-    raise(NotImplementedError)
-  end
+    # Returns a hash of all arguments and their values
+    def arguments
+      attributes
+    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
+    private
 
-  # 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)
+    # The call method that must be defined by every inheriting service class
+    def call
+      raise(NotImplementedError)
     end
   end
 end

data/lib/service_base/version.rb

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

data/lib/service_base.rb

@@ -1,7 +1,6 @@
 # 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'
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: service_base
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.2
 platform: ruby
 authors:
 - James Klein
 bindir: bin
 cert_chain: []
-date: 2025-04-01 00:00:00.000000000 Z
+date: 2025-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dry-matcher
@@ -94,7 +94,6 @@ files:
 - lib/service_base/rspec.rb
 - lib/service_base/rspec/service_support.rb
 - lib/service_base/service.rb
-- lib/service_base/types.rb
 - lib/service_base/version.rb
 homepage: https://github.com/kleinjm/service_base
 licenses:

data/lib/service_base/types.rb

@@ -1,18 +0,0 @@
-# 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 Types
-  include Dry.Types()
-
-  UpCasedString = Types::String.constructor(&:upcase)
-  Boolean = Bool # alias the built in type, Bool
-end