service_base 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d20e049647526253612ef6cf134c73ce8ab076c69e9a1f3a5524586f035f8ae3
-  data.tar.gz: 8fe635ae9d66b5358030440828f45e0706a2cad092e7eb45f9738af5c53c9896
+  metadata.gz: b9c9ee7f7424ddd348b82d0708fa79703e7869771284b7018f7e3cb41828770b
+  data.tar.gz: 92032edd435bc81747cbd0a15670e3210716cefd51d8fc7598f7fca5194f5127
 SHA512:
-  metadata.gz: '0595ddabc674a039b1dfb3189f4f7a6d8aa2e3a6c694391b94c26235180f7b67475685b3c5e19283c07f8b8e141b6c99b109d35659af6ef7d4e436f74ab0a832'
-  data.tar.gz: a38e09b26353baa8a4b37edb97522d33a2bd95a9209f9b930c109f67dbd5d305623c57aa5508c82bdb574150536c37048a5399cb25eed4df5f5c22838456aac4
+  metadata.gz: a95dd087bca43238c0ed3e6c94773f61e05758def00c38e9ac4bfd0f258f0eb3514092e404c9f1fd14a9dc47f6f08b4529869d8fa5e489967848396b57347910
+  data.tar.gz: a524e1751b728e6cce6fd723c78b3f5ccb7369e8db0f27a412b42d9be6d4cb35a17e7b6926bae291300ed56e5585b5a97b12dea4b3fdc5efa01f88c86a8be007

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
@@ -175,7 +182,7 @@ 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
 ```
@@ -185,7 +192,7 @@ use `attributes`. This is a very useful technique for
 services that update an object. For example
 
 ```ruby
-class User::UpdateService < Service
+class User::UpdateService < ServiceBase::Service
   def call
     user.update(attributes)
   end

data/lib/service_base/argument_type_annotations.rb

@@ -1,106 +1,108 @@
 # 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
+
+        # `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
 
-      # `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

@@ -7,110 +7,112 @@ require 'dry/monads'
 require 'dry/monads/do'
 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]
 
-  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
+    private
 
-  # The call method that must be defined by every inheriting service class
-  def call
-    raise(NotImplementedError)
-  end
+    # 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
+    # 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)
+    # 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

@@ -10,9 +10,11 @@
 
 require 'dry-types'
 
-module Types
-  include Dry.Types()
+module ServiceBase
+  module Types
+    include Dry.Types()
 
-  UpCasedString = Types::String.constructor(&:upcase)
-  Boolean = Bool # alias the built in type, Bool
+    UpCasedString = Types::String.constructor(&:upcase)
+    Boolean = Bool # alias the built in type, Bool
+  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.1'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: service_base
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 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