service_actor 4.0.0 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86aa1f5411838fa24961e50eff4138d414c86aa99c7bdc5907953f7643406431
-  data.tar.gz: 1e0c82c0ba0e3b3c8278fa7d286454f891266972d34144b2ee3aa18a2bddd20d
+  metadata.gz: 971f7ed20085d9eb94a796326b5a9f06d9080d765fbea5b3f80e7f311eb48a3e
+  data.tar.gz: 38c6168b68139741f7c3209ec8cbceb90028c1ce0029b4a22d5e0535e0c544da
 SHA512:
-  metadata.gz: ed8bfce6061647dee123bfdecc2a89f92cb7b4fc09664bef3671d722e59605787acfe3ceb9822b785a4a0ed651b315a9c27a38366516cbeadef9403d92c49709
-  data.tar.gz: 9dec2bb8b9d5815c1c8d39108432003575f2f5a9a9431c93c69228c2c13f776eea60794696328e2d9ebc6e13849e2fa3e6db3e6e3ac337c03a39d29b24c578ea
+  metadata.gz: 8a26e9cac7270f392e7cb58b96cd6a899f92f36f603ad175e9ec9965449b4a1c0ad58cef053252bc5c31d2dc3b570e3bc77a64a88dc9f5d9890f05268f17b1c2
+  data.tar.gz: bc08967e46472cc15f71f516290f67dd01dd244786ea4881fc9df82db30b2e199171bf88f2a4ad4497d51274cbff24bcd2434de66647f2035cb7d0de785ad28b

data/README.md

@@ -4,7 +4,7 @@ This Ruby gem lets you move your application logic into small composable
 service objects. It is a lightweight framework that helps you keep your models
 and controllers thin.
 
-![Photo of theater seats](https://user-images.githubusercontent.com/132/78340166-e7567000-7595-11ea-97c0-b3e5da2de7a1.png)
+![Photo of red and black theater seats with lighting from the top](https://user-images.githubusercontent.com/132/78340166-e7567000-7595-11ea-97c0-b3e5da2de7a1.png)
 
 ## Contents
 
@@ -24,6 +24,7 @@ and controllers thin.
   - [Conditions](#conditions)
   - [Types](#types)
   - [Custom input errors](#custom-input-errors)
+  - [Custom type validations](#custom-type-validations)
 - [Testing](#testing)
 - [FAQ](#faq)
 - [Thanks](#thanks)
@@ -40,19 +41,8 @@ bundle add service_actor
 
 ### Extensions
 
-For **Rails generators**, you can use the
-[service_actor-rails](https://github.com/sunny/actor-rails) gem:
-
-```sh
-bundle add service_actor-rails
-```
-
-For **TTY prompts**, you can use the
-[service_actor-promptable](https://github.com/pboling/service_actor-promptable) gem:
-
-```sh
-bundle add service_actor-promptable
-```
+- Rails generators: [service_actor-rails](https://github.com/sunny/actor-rails)
+- TTY prompts: [service_actor-promptable](https://github.com/pboling/service_actor-promptable)
 
 ## Usage
 
@@ -75,9 +65,9 @@ Trigger them in your application with `.call`:
 SendNotification.call # => <ServiceActor::Result…>
 ```
 
-When called, an actor returns a result. Reading and writing to this result allows
-actors to accept and return multiple arguments. Let’s find out how to do that
-and then we’ll see how to
+When called, an actor returns a result. Reading and writing to this result
+allows actors to accept and return multiple arguments. Let’s find out how to do
+that and then we’ll see how to
 [chain multiple actors together](#play-actors-in-a-sequence).
 
 ### Inputs
@@ -181,6 +171,11 @@ class UsersController < ApplicationController
 end
 ```
 
+> [!WARNING]
+> If you specify the type option for output fields, it will not be enforced for
+> failed actors.
+> As a result, their output might not match the specified type.
+
 ## Play actors in a sequence
 
 To help you create actors that are small, single-responsibility actions, an
@@ -338,15 +333,15 @@ actor = BuildGreeting.call(name: "Siobhan", adjective: "elegant")
 actor.greeting # => "Have an elegant week, Siobhan!"
 ```
 
-While lambdas are the preferred way to specify defaults, you can also provide
-a default value without using lambdas by using an immutable object.
+While lambdas are the preferred way to specify defaults, you can also provide a
+default value without using lambdas by using an immutable object.
 
 ```rb
 # frozen_string_literal: true
 
 class ExampleActor < Actor
   input :options, default: {
-    names: {male: "Iaroslav", female: "Anna"}.freeze,
+    names: {man: "Iaroslav", woman: "Anna"}.freeze,
     country_codes: %w[gb ru].freeze
   }.freeze
 end
@@ -357,7 +352,8 @@ are references to mutable objects, e.g.
 
 ```rb
 class ExampleActor < Actor
-  input :options, default: -> { Registry::DEFAULT_OPTIONS } # `Registry::DEFAULT_OPTIONS` is not frozen
+  # `Registry::DEFAULT_OPTIONS` is not frozen
+  input :options, default: -> { Registry::DEFAULT_OPTIONS }
 
   def call
     options[:names] = nil
@@ -529,6 +525,50 @@ end
 
 </details>
 
+### Custom type validations
+
+This gem provides a minimal API for checking the types of `input` and `output`
+values:
+
+- A direct class match: `input :age, type: Integer`
+- A choice between classes: `output :height, type: [Integer, Float]`
+
+More complex type checks are outside the scope of this gem. However, type
+checking is performed using Ruby’s `===` method.
+This means you can define a custom class with a `===` method to implement your
+own type logic.
+
+For example, to define a “positive integer” type, you can create a custom class:
+
+```ruby
+class PositiveInteger
+  class << self
+    def ===(value)
+      value.is_a?(Integer) && value.positive?
+    end
+  end
+end
+```
+
+Then you can use it in an actor:
+
+```ruby
+class AgeActor < Actor
+  input :age, type: PositiveInteger
+end
+
+AgeActor.call(age: 25)
+# => #<ServiceActor::Result {age: 25}>
+AgeActor.call(age: -42)
+# ServiceActor::ArgumentError: The "age" input on "AgeActor" must be of type
+# "PositiveInteger" but was "Integer" (ServiceActor::ArgumentError)
+```
+
+This approach also allows you to define adapters for third-party validation
+gems, providing the flexibility to integrate custom type checks.
+
+See [more examples](./docs/examples/custom_types).
+
 ## Testing
 
 In your application, add automated testing to your actors as you would do to any

data/lib/service_actor/arguments_validator.rb

@@ -4,8 +4,11 @@ module ServiceActor::ArgumentsValidator
   module_function
 
   def validate_origin_name(name, origin:)
-    return if name.to_sym == :error
-    return unless ServiceActor::Result.instance_methods.include?(name.to_sym)
+    name = name.to_sym
+    return if name == :error
+
+    methods = ServiceActor::Core.instance_methods + ServiceActor::Result.instance_methods
+    return unless methods.include?(name)
 
     raise ArgumentError,
           "#{origin} `#{name}` overrides `ServiceActor::Result` instance method"

data/lib/service_actor/attributable.rb

@@ -23,11 +23,15 @@ module ServiceActor::Attributable
 
     def input(name, **arguments)
       ServiceActor::ArgumentsValidator.validate_origin_name(
-        name, origin: :input
+        name,
+        origin: :input,
       )
 
       ServiceActor::ArgumentsValidator.validate_default_value(
-        arguments[:default], actor: self, origin_type: :input, origin_name: name
+        arguments[:default],
+        actor: self,
+        origin_type: :input,
+        origin_name: name,
       )
 
       inputs[name] = arguments
@@ -48,11 +52,15 @@ module ServiceActor::Attributable
 
     def output(name, **arguments)
       ServiceActor::ArgumentsValidator.validate_origin_name(
-        name, origin: :output
+        name,
+        origin: :output,
       )
 
       ServiceActor::ArgumentsValidator.validate_default_value(
-        arguments[:default], actor: self, origin_type: :output, origin_name: name
+        arguments[:default],
+        actor: self,
+        origin_type: :output,
+        origin_name: name,
       )
 
       outputs[name] = arguments

data/lib/service_actor/checks/inclusion_check.rb

@@ -28,7 +28,15 @@ class ServiceActor::Checks::InclusionCheck < ServiceActor::Checks::Base
   private_constant :DEFAULT_MESSAGE
 
   class << self
-    def check(check_name:, input_key:, actor:, conditions:, result:, **)
+    def check(
+      check_name:,
+      input_key:,
+      actor:,
+      conditions:,
+      result:,
+      input_options:,
+      **
+    )
       # DEPRECATED: `in` is deprecated in favor of `inclusion`.
       return unless %i[inclusion in].include?(check_name)
 
@@ -37,42 +45,47 @@ class ServiceActor::Checks::InclusionCheck < ServiceActor::Checks::Base
         actor: actor,
         inclusion: conditions,
         value: result[input_key],
+        input_options: input_options,
       ).check
     end
   end
 
-  def initialize(input_key:, actor:, inclusion:, value:)
+  def initialize(input_key:, actor:, inclusion:, value:, input_options:)
     super()
 
     @input_key = input_key
     @actor = actor
     @inclusion = inclusion
     @value = value
+    @input_options = input_options
   end
 
   def check
     inclusion_in, message = define_inclusion_and_message
 
     return if inclusion_in.nil?
-    return if inclusion_in.include?(@value)
+    return if inclusion_in.include?(value)
+    return if input_options[:allow_nil] && value.nil?
 
     add_argument_error(
       message,
-      input_key: @input_key,
-      actor: @actor,
+      input_key: input_key,
+      actor: actor,
       inclusion_in: inclusion_in,
-      value: @value,
+      value: value,
     )
   end
 
   private
 
+  attr_reader :value, :inclusion, :input_key, :actor, :input_options
+
   def define_inclusion_and_message
-    if @inclusion.is_a?(Hash)
-      @inclusion[:message] ||= DEFAULT_MESSAGE
-      @inclusion.values_at(:in, :message)
+    if inclusion.is_a?(Hash)
+      inclusion[:message] ||= DEFAULT_MESSAGE
+      inclusion.values_at(:in, :message)
     else
-      [@inclusion, DEFAULT_MESSAGE]
+      [inclusion, DEFAULT_MESSAGE]
     end
   end
 end

data/lib/service_actor/checks/must_check.rb

@@ -34,7 +34,15 @@ class ServiceActor::Checks::MustCheck < ServiceActor::Checks::Base
   private_constant :DEFAULT_MESSAGE
 
   class << self
-    def check(check_name:, input_key:, actor:, conditions:, result:, **)
+    def check(
+      check_name:,
+      input_key:,
+      actor:,
+      conditions:,
+      result:,
+      input_options:,
+      **
+    )
       return unless check_name == :must
 
       new(
@@ -42,47 +50,56 @@ class ServiceActor::Checks::MustCheck < ServiceActor::Checks::Base
         actor: actor,
         nested_checks: conditions,
         value: result[input_key],
+        input_options: input_options,
       ).check
     end
   end
 
-  def initialize(input_key:, actor:, nested_checks:, value:)
+  def initialize(input_key:, actor:, nested_checks:, value:, input_options:)
     super()
 
     @input_key = input_key
     @actor = actor
     @nested_checks = nested_checks
     @value = value
+    @input_options = input_options
   end
 
   def check
-    @nested_checks.each do |nested_check_name, nested_check_conditions|
-      message = prepared_message_with(nested_check_name, nested_check_conditions) # rubocop:disable Layout/LineLength
+    return if input_options[:allow_nil] && value.nil?
+
+    nested_checks.each do |nested_check_name, nested_check_conditions|
+      message = prepared_message_with(
+        nested_check_name,
+        nested_check_conditions,
+      )
 
       next unless message
 
       add_argument_error(
         message,
-        input_key: @input_key,
-        actor: @actor,
+        input_key: input_key,
+        actor: actor,
         check_name: nested_check_name,
-        value: @value,
+        value: value,
       )
     end
 
-    @argument_errors
+    argument_errors
   end
 
   private
 
+  attr_reader :input_key, :actor, :nested_checks, :value, :input_options
+
   def prepared_message_with(nested_check_name, nested_check_conditions)
     check, message = define_check_and_message_from(nested_check_conditions)
 
-    return if check.call(@value)
+    return if check.call(value)
 
     message
   rescue StandardError => e
-    "The \"#{@input_key}\" input on \"#{@actor}\" has an error in the code " \
+    "The \"#{input_key}\" input on \"#{actor}\" has an error in the code " \
       "inside \"#{nested_check_name}\": [#{e.class}] #{e.message}"
   end
 

data/lib/service_actor/checks/nil_check.rb

@@ -75,23 +75,25 @@ class ServiceActor::Checks::NilCheck < ServiceActor::Checks::Base
   end
 
   def check
-    return unless @value.nil?
+    return unless value.nil?
 
     allow_nil, message =
-      define_allow_nil_and_message_from(@input_options[:allow_nil])
+      define_allow_nil_and_message_from(input_options[:allow_nil])
 
     return if allow_nil?(allow_nil)
 
     add_argument_error(
       message,
-      origin: @origin,
-      input_key: @input_key,
-      actor: @actor,
+      origin: origin,
+      input_key: input_key,
+      actor: actor,
     )
   end
 
   private
 
+  attr_reader :origin, :input_key, :input_options, :actor, :allow_nil, :value
+
   def define_allow_nil_and_message_from(allow_nil)
     if allow_nil.is_a?(Hash)
       allow_nil[:message] ||= DEFAULT_MESSAGE
@@ -104,10 +106,10 @@ class ServiceActor::Checks::NilCheck < ServiceActor::Checks::Base
   def allow_nil?(tmp_allow_nil)
     return tmp_allow_nil unless tmp_allow_nil.nil?
 
-    if @input_options.key?(:default) && @input_options[:default].nil?
+    if input_options.key?(:default) && input_options[:default].nil?
       return true
     end
 
-    !@input_options[:type]
+    !input_options[:type]
   end
 end

data/lib/service_actor/checks/type_check.rb

@@ -67,36 +67,39 @@ class ServiceActor::Checks::TypeCheck < ServiceActor::Checks::Base
   end
 
   def check
-    return if @type_definition.nil?
-    return if @given_type.nil?
+    return if type_definition.nil?
+    return if given_type.nil?
 
     types, message = define_types_and_message
 
-    return if types.any? { |type| type === @given_type }
+    return if types.any? { |type| type === given_type }
 
     add_argument_error(
       message,
-      origin: @origin,
-      input_key: @input_key,
-      actor: @actor,
+      origin: origin,
+      input_key: input_key,
+      actor: actor,
       expected_type: types.map(&:name).join(", "),
-      given_type: @given_type.class,
+      given_type: given_type.class,
     )
   end
 
   private
 
+  attr_reader :origin, :input_key, :actor, :type_definition, :given_type
+
   def define_types_and_message
-    if @type_definition.is_a?(Hash)
-      @type_definition[:message] ||= DEFAULT_MESSAGE
+    definition = type_definition
+
+    if definition.is_a?(Hash)
+      definition[:message] ||= DEFAULT_MESSAGE
 
-      @type_definition, message =
-        @type_definition.values_at(:is, :message)
+      definition, message = definition.values_at(:is, :message)
     else
       message = DEFAULT_MESSAGE
     end
 
-    types = Array(@type_definition).map do |name|
+    types = Array(definition).map do |name|
       name.is_a?(String) ? Object.const_get(name) : name
     end
 

data/lib/service_actor/result.rb

@@ -19,6 +19,7 @@ class ServiceActor::Result < BasicObject
     instance_variables
     is_a?
     kind_of?
+    method
     methods
     nil?
     object_id

data/lib/service_actor/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ServiceActor
-  VERSION = "4.0.0"
+  VERSION = "5.0.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: service_actor
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 5.0.0
 platform: ruby
 authors:
 - Sunny Ripert
 bindir: bin
 cert_chain: []
-date: 2025-02-24 00:00:00.000000000 Z
+date: 2025-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -71,14 +71,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '18.2'
+        version: '24.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '18.2'
+        version: '24.0'
 - !ruby/object:Gem::Dependency
   name: standard-rubocop-lts
   requirement: !ruby/object:Gem::Requirement
@@ -219,6 +219,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.0'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.14'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.14'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.10'
 description: Service objects for your application logic
 email:
 - sunny@sunfox.org
@@ -267,7 +295,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="