service_actor 3.9.4 → 5.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f91c36f4113eb695e8398ac43395dc85b5f51cb103c2dcdc72b8e351839932a7
-  data.tar.gz: f536f4d3d552d07544cd46706faca94240711758ba39da68e07db7e819236b24
+  metadata.gz: 971f7ed20085d9eb94a796326b5a9f06d9080d765fbea5b3f80e7f311eb48a3e
+  data.tar.gz: 38c6168b68139741f7c3209ec8cbceb90028c1ce0029b4a22d5e0535e0c544da
 SHA512:
-  metadata.gz: 5e8260d8e84d2ef2c918e01eb13c8ac0417bff3cf3f0683acc3a3d6281184c9ef9d6af1c20d0cba3c65b74ba51a48ae3a72ba40e2c64280df936c307331957b4
-  data.tar.gz: 0a93c5b2eecc2e1cd7724b3a42ffd7664d4caa069de6066a2ae3f0c40fdc405492c0ec2cea964cf92df6016a34296c07acad48f7f018a6b46bd26a7864be5378
+  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
@@ -314,20 +309,20 @@ end
 
 ### Defaults
 
-Inputs can be optional by providing a `default` value or lambda.
+Inputs can be optional by providing a `default` value in a lambda.
 
 ```rb
 class BuildGreeting < Actor
   input :name
-  input :adjective, default: "wonderful"
+  input :adjective, default: -> { "wonderful" }
   input :length_of_time, default: -> { ["day", "week", "month"].sample }
   input :article,
-        default: -> context { context.adjective.match?(/^aeiou/) ? "an" : "a" }
+        default: -> actor { actor.adjective.match?(/^[aeiou]/) ? "an" : "a" }
 
   output :greeting
 
   def call
-    self.greeting = "Have #{article} #{length_of_time}, #{name}!"
+    self.greeting = "Have #{article} #{adjective} #{length_of_time}, #{name}!"
   end
 end
 
@@ -338,6 +333,34 @@ 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.
+
+```rb
+# frozen_string_literal: true
+
+class ExampleActor < Actor
+  input :options, default: {
+    names: {man: "Iaroslav", woman: "Anna"}.freeze,
+    country_codes: %w[gb ru].freeze
+  }.freeze
+end
+```
+
+Note that default values might be mutated if the values returned by the lambda
+are references to mutable objects, e.g.
+
+```rb
+class ExampleActor < Actor
+  # `Registry::DEFAULT_OPTIONS` is not frozen
+  input :options, default: -> { Registry::DEFAULT_OPTIONS }
+
+  def call
+    options[:names] = nil
+  end
+end
+```
+
 ### Allow nil
 
 By default inputs accept `nil` values. To raise an error instead:
@@ -471,20 +494,6 @@ end
   end
   ```
 
-  #### Default
-
-  ```ruby
-  class MultiplyThing < Actor
-    input :multiplier,
-          default: {
-            is: -> { rand(1..10) },
-            message: (lambda do |input_key:, **|
-              "Input \"#{input_key}\" is required"
-            end)
-          }
-  end
-  ```
-
   #### Type
 
   ```ruby
@@ -516,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"
@@ -16,4 +19,13 @@ module ServiceActor::ArgumentsValidator
 
     raise ArgumentError, "Expected #{value} to be a subclass of Exception"
   end
+
+  def validate_default_value(value, origin_type:, origin_name:, actor:)
+    return if value.is_a?(Proc) || !defined?(Ractor.shareable?) || Ractor.shareable?(value)
+
+    ::Kernel.warn(
+      "DEPRECATED: Actor `#{actor}` has #{origin_type} `#{origin_name}` with default " \
+        "which is not a Proc or an immutable object.",
+    )
+  end
 end

data/lib/service_actor/attributable.rb

@@ -23,7 +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,
       )
 
       inputs[name] = arguments
@@ -44,7 +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,
       )
 
       outputs[name] = arguments

data/lib/service_actor/checkable.rb

@@ -31,10 +31,9 @@ module ServiceActor::Checkable
 
     # rubocop:disable Metrics/MethodLength
     def service_actor_checks_for(origin)
-      check_classes = CHECK_CLASSES.select { _1.applicable_to_origin?(origin) }
       self.class.public_send(:"#{origin}s").each do |input_key, input_options|
         input_options.each do |check_name, check_conditions|
-          check_classes.each do |check_class|
+          CHECK_CLASSES.each do |check_class|
             argument_errors = check_class.check(
               check_name: check_name,
               origin: origin,

data/lib/service_actor/checks/base.rb

@@ -1,12 +1,6 @@
 # frozen_string_literal: true
 
 class ServiceActor::Checks::Base
-  class << self
-    def applicable_to_origin?(_origin)
-      true
-    end
-  end
-
   def initialize
     @argument_errors = []
   end

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| @given_type.is_a?(type) }
+    return if types.any? { |type| type === given_type }
 
     add_argument_error(
       message,
-      origin: @origin,
-      input_key: @input_key,
-      actor: @actor,
-      expected_type: types.join(", "),
-      given_type: @given_type.class,
+      origin: origin,
+      input_key: input_key,
+      actor: actor,
+      expected_type: types.map(&:name).join(", "),
+      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/defaultable.rb

@@ -9,22 +9,6 @@
 #     input :counter, default: 1
 #     input :multiplier, default: -> { rand(1..10) }
 #   end
-#
-#   class MultiplyThing < Actor
-#     input :counter,
-#           default: {
-#             is: 1,
-#             message: "Counter is required"
-#           }
-#
-#     input :multiplier,
-#           default: {
-#             is: -> { rand(1..10) },
-#             message: (lambda do |input_key:, actor:|
-#               "Input \"#{input_key}\" is required"
-#             end)
-#           }
-#   end
 module ServiceActor::Defaultable
   class << self
     def included(base)
@@ -43,19 +27,13 @@ module ServiceActor::Defaultable
           )
         end
 
-        default = input[:default]
-
-        if default.is_a?(Hash) && default[:is]
-          default_for_advanced_mode_with(result, key, default)
-        else
-          default_for_normal_mode_with(result, key, default)
-        end
+        apply_default_for_origin(key, input)
       end
 
-      self.class.outputs.each do |key, options|
-        unless result.key?(key)
-          result.send(:"#{key}=", options[:default])
-        end
+      self.class.outputs.each do |key, output|
+        next if result.key?(key)
+
+        apply_default_for_origin(key, output)
       end
 
       super
@@ -63,26 +41,13 @@ module ServiceActor::Defaultable
 
     private
 
-    def default_for_normal_mode_with(result, key, default)
-      result[key] = reify_default(result, default)
-    end
-
-    def default_for_advanced_mode_with(result, key, content)
-      default, message = content.values_at(:is, :message)
+    def apply_default_for_origin(origin_name, origin_options)
+      default = origin_options[:default]
 
-      unless default
-        raise_error_with(message, input_key: key, actor: self.class)
-      end
-
-      result[key] = reify_default(result, default)
-
-      message.call(key, self.class)
+      result[origin_name] = reify_default(result, default)
     end
 
-    # Raises an error depending on the mode
-    def raise_error_with(message, **arguments)
-      message = message.call(**arguments) if message.is_a?(Proc)
-
+    def raise_error_with(message)
       raise self.class.argument_error_class, message
     end
 

data/lib/service_actor/playable.rb

@@ -90,7 +90,15 @@ module ServiceActor::Playable
     end
 
     def play_actor(actor)
-      if actor.is_a?(Symbol)
+      actor_includes_kernel = begin
+        actor.respond_to?(:is_a?)
+      rescue NoMethodError
+        false
+      end
+
+      if !actor_includes_kernel
+        actor.call(result)
+      elsif actor.is_a?(Symbol)
         send(actor)
       elsif actor.is_a?(Class) && actor.ancestors.include?(ServiceActor::Core)
         play_service_actor(actor)

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
@@ -124,9 +125,7 @@ class ServiceActor::Result < BasicObject
   # Key `_default_output` is an internal datum used by actor class
   # method `.valuable`. Don't expose it with the rest of the result.
   def filter_default_output(h)
-    # using `filter` instead of `except` to maintain Ruby 2.7 compatibility
-    # update once support for 2.7 is dropped
-    h.filter { |k| k != :_default_output }
+    h.except(:_default_output)
   end
 
   def respond_to_missing?(method_name, _include_private = false)

data/lib/service_actor/version.rb

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

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: service_actor
 version: !ruby/object:Gem::Version
-  version: 3.9.4
+  version: 5.0.0
 platform: ruby
 authors:
 - Sunny Ripert
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-25 00:00:00.000000000 Z
+date: 2025-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -72,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
@@ -206,6 +205,48 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0.0'
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !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
@@ -247,7 +288,6 @@ metadata:
   source_code_uri: https://github.com/sunny/actor
   changelog_uri: https://github.com/sunny/actor/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -255,15 +295,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.7'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key:
+rubygems_version: 3.6.5
 specification_version: 4
 summary: Service objects for your application logic
 test_files: []