telephone 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b95df7745edfdcccffb9d141f444fb2b487b55d0cd20ae6e1dd86a51033f064a
-  data.tar.gz: 3d680e1fecccb620ab8823e0e46cba6b9fa506f1718b5486e38750ccf4ab86ab
+  metadata.gz: 45fbcb9aaecf2dc2d66072e93b97b168c2a505f6d4e0cc1ed08cfad4e8267bb2
+  data.tar.gz: 4f3992fbc6840c3d624fadb7de3faa56f3952ba4b4b5eae7cde0b61ecdf343f6
 SHA512:
-  metadata.gz: dd79447632f18c1ac6237254589df28980098b1988172886b10c3a46e2e2ea6bf6122d81219653111a51dbfc75edefea2b79450905c099875bb48ab5e6fcdd1b
-  data.tar.gz: d40dd3b806a554920571c40841ccc539a1531eef7cde07800a171cfc9b5cbcf4a2f98c140fa702f22bbc1e3d2e68077c55cd21c45eafbf2af464dfdc9a2431cb
+  metadata.gz: ef63c3786eb25e545259ed90894ace7a67af3098028ebcdfc9206aa7bd995729dafa3ed5533a8109bd42696255216efb4db84e53fd9160304f8c7c868862dde5
+  data.tar.gz: 3a9419a284e42bde8b0de7bd8517a4dc7986e9f59b8c685a41059c8e5d81660d36c4aea2d3c3bba4610213211d243fceb2007103f2d79ac7f1fadea9be673431

data/README.md

@@ -94,6 +94,48 @@ You can also give a default value for an argument.
 argument :name, default: "Benjamin"
 ```
 
+Defaults can also be callable (procs or lambdas) that are evaluated at runtime. Callable defaults have access to other attributes and are processed in definition order:
+
+```ruby
+class GreetingService < ApplicationService
+  argument :first_name, default: "John"
+  argument :last_name, default: "Doe"
+  argument :full_name, default: -> { "#{first_name} #{last_name}" }
+  argument :created_at, default: -> { Time.current }
+
+  def call
+    "Hello, #{full_name}!"
+  end
+end
+
+GreetingService.call.result #=> "Hello, John Doe!"
+GreetingService.call(first_name: "Jane").result #=> "Hello, Jane Doe!"
+```
+
+Arguments can also be validated against a type. When `type:` is provided, the argument is checked with `is_a?` before the service runs. `nil` is allowed unless the argument is also marked as `required:`.
+
+```ruby
+class UpdateUserService < ApplicationService
+  argument :user, type: User, required: true
+
+  def call
+    user.update!(status: "active")
+  end
+end
+
+s = UpdateUserService.call(user: "not a user")
+s.success? #=> false
+s.errors.full_messages #=> ["User must be a User"]
+s.result #=> nil
+```
+
+Type validation works with any class or module:
+
+```ruby
+argument :tags, type: Array
+argument :metadata, type: Enumerable
+```
+
 ### Validations
 
 Since `Telephone::Service` includes `ActiveModel::Model`, you can define validations in the same way you would for an ActiveRecord model.
@@ -107,13 +149,49 @@ def admin_user?
 end
 ```
 
-If a validation fails, the service object will not execute and return `nil` as the result of th call. You can check the status of the service object by calling `success?`.
+If a validation fails, the service object will not execute and return `nil` as the result of the call. You can check the status of the service object by calling `success?`.
 
 ```ruby
 s = SomeService.call
 s.success? #=> false
 ```
 
+#### Internationalization
+
+Type validation errors are translated through I18n. Telephone ships with translations for:
+
+* `en` — English
+* `es` — Spanish
+* `fr` — French
+* `de` — German
+* `pt` — Portuguese
+* `ja` — Japanese
+* `zh-CN` — Chinese (Simplified)
+* `it` — Italian
+* `nl` — Dutch
+* `ru` — Russian
+* `ko` — Korean
+
+In a Rails app, these are used automatically based on the current locale:
+
+```ruby
+I18n.locale = :es
+
+s = UpdateUserService.call(user: "not a user")
+s.errors.full_messages #=> ["User debe ser un User"]
+```
+
+You can also override the default message in your own locale files:
+
+```yaml
+# config/locales/telephone.en.yml
+en:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "must be an instance of %{type}"
+```
+
 ## Best Practices
 
 Service objects are a great way to keep your code DRY and encapsulate business logic. As a rule of thumb, try to keep your service objects to a single responsibility. If you find yourself dealing with very complex logic, consider breaking it up into smaller services.

data/lib/telephone/locale/de.yml

@@ -0,0 +1,5 @@
+de:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "muss ein %{type} sein"

data/lib/telephone/locale/en.yml

@@ -0,0 +1,5 @@
+en:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "must be a %{type}"

data/lib/telephone/locale/es.yml

@@ -0,0 +1,5 @@
+es:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "debe ser un %{type}"

data/lib/telephone/locale/fr.yml

@@ -0,0 +1,5 @@
+fr:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "doit être un %{type}"

data/lib/telephone/locale/it.yml

@@ -0,0 +1,5 @@
+it:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "deve essere un %{type}"

data/lib/telephone/locale/ja.yml

@@ -0,0 +1,5 @@
+ja:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "%{type}である必要があります"

data/lib/telephone/locale/ko.yml

@@ -0,0 +1,5 @@
+ko:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "%{type}이어야 합니다"

data/lib/telephone/locale/nl.yml

@@ -0,0 +1,5 @@
+nl:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "moet een %{type} zijn"

data/lib/telephone/locale/pt.yml

@@ -0,0 +1,5 @@
+pt:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "deve ser um %{type}"

data/lib/telephone/locale/ru.yml

@@ -0,0 +1,5 @@
+ru:
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "должно быть %{type}"

data/lib/telephone/locale/zh-CN.yml

@@ -0,0 +1,5 @@
+"zh-CN":
+  activemodel:
+    errors:
+      messages:
+        invalid_type: "必须是 %{type}"

data/lib/telephone/service.rb

@@ -20,10 +20,26 @@ module Telephone
     # Primary responsibility of initialize is to instantiate the
     # attributes of the service object with the expected values.
     def initialize(attributes = {})
-      self.class.defaults.merge(attributes).each do |key, value|
+      attributes = attributes.transform_keys(&:to_sym)
+
+      attributes.each do |key, value|
         send("#{key}=", value)
       end
 
+      self.class.defaults.each do |key, value|
+        next if attributes.key?(key)
+
+        resolved = if value.is_a?(Proc)
+          instance_exec(&value)
+        elsif value.respond_to?(:call)
+          value.call
+        else
+          value
+        end
+
+        send("#{key}=", resolved)
+      end
+
       super
       yield self if block_given?
     end
@@ -51,21 +67,44 @@ module Telephone
       # to pass in a default, or set the argument to "required" to add a validation
       # that runs before executing the block.
       #
+      # The default value can be a static value or any callable object (Proc, lambda,
+      # method, or any object that responds to #call) that will be evaluated at
+      # runtime when the service is instantiated.
+      #
+      # Callable defaults are evaluated in the context of the service instance,
+      # so they can access other attributes. They are processed in definition order,
+      # meaning a callable can depend on any argument defined before it.
+      #
+      # To store a Proc as the actual value, wrap it in another lambda:
+      #   argument :my_proc, default: -> { -> { puts "hi" } }
+      #
+      # You can also pass +type:+ to validate that the argument is an instance of
+      # the given class or module. Nil values are allowed unless the argument is
+      # also marked as required.
+      #
       # @example
       #   class SomeService < Telephone::Service
-      #     argument :foo, default: "bar"
-      #     argument :baz, required: true
+      #     argument :first_name, default: "John"
+      #     argument :last_name, default: "Doe"
+      #     argument :full_name, default: -> { "#{first_name} #{last_name}" }
+      #     argument :timestamp, default: -> { DateTime.current }
+      #     argument :user, type: User
       #
       #     def call
-      #       puts foo
-      #       puts baz
+      #       puts full_name
+      #       puts timestamp
       #     end
       #   end
-      def argument(arg, default: nil, required: false)
-        send(:attr_accessor, arg.to_sym)
-        send(:validates, arg.to_sym, presence: true) if required
+      def argument(arg, default: nil, required: false, type: nil)
+        arg = arg.to_sym
+        send(:attr_accessor, arg)
+        send(:validates, arg, presence: true) if required
+
+        if type
+          send(:validates_with, Telephone::TypeValidator, attributes: arg, with: type, allow_nil: true)
+        end
 
-        defaults[arg.to_sym] = default
+        defaults[arg] = default
       end
 
       ##
@@ -82,8 +121,9 @@ module Telephone
       #
       # @example
       #   Telephone::Service.call(foo: bar)
-      def call(**args)
-        new(args).call
+      #   Telephone::Service.call({ foo: bar })
+      def call(*args, **kwargs)
+        new(args.extract_options!.merge(kwargs)).call
       end
 
       ##

data/lib/telephone/validators/type_validator.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "active_model"
+
+module Telephone
+  class TypeValidator < ActiveModel::EachValidator
+    def validate_each(record, attribute, value)
+      expected_type = options[:with]
+
+      return if value.is_a?(expected_type)
+
+      record.errors.add(
+        attribute,
+        :invalid_type,
+        **options.except(:with).merge(type: type_name(expected_type))
+      )
+    end
+
+    private
+
+    def type_name(type)
+      type.name || type.to_s
+    end
+  end
+end

data/lib/telephone/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Telephone
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/telephone.rb

@@ -1,3 +1,8 @@
 # frozen_string_literal: true
 
+require "i18n"
+
+I18n.load_path += Dir[File.join(__dir__, "telephone", "locale", "*.yml")]
+
+require "telephone/validators/type_validator"
 require "telephone/service"

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: telephone
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Benjamin Hargett
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-08-05 00:00:00.000000000 Z
+date: 2026-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -24,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: i18n
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Utility class for creating and calling service objects.
 email: hargettbenjamin@gmail.com
 executables: []
@@ -32,7 +45,19 @@ extra_rdoc_files: []
 files:
 - README.md
 - lib/telephone.rb
+- lib/telephone/locale/de.yml
+- lib/telephone/locale/en.yml
+- lib/telephone/locale/es.yml
+- lib/telephone/locale/fr.yml
+- lib/telephone/locale/it.yml
+- lib/telephone/locale/ja.yml
+- lib/telephone/locale/ko.yml
+- lib/telephone/locale/nl.yml
+- lib/telephone/locale/pt.yml
+- lib/telephone/locale/ru.yml
+- lib/telephone/locale/zh-CN.yml
 - lib/telephone/service.rb
+- lib/telephone/validators/type_validator.rb
 - lib/telephone/version.rb
 homepage: https://github.com/bharget/telephone
 licenses: []
@@ -40,7 +65,6 @@ metadata:
   bug_tracker_uri: https://github.com/bharget/telephone/issues
   changelog_uri: https://github.com/bharget/telephone/blob/master/CHANGELOG.md
   source_code_uri: https://github.com/bharget/telephone
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -48,7 +72,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -56,8 +80,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements:
 - none
-rubygems_version: 3.1.6
-signing_key: 
+rubygems_version: 3.6.3
 specification_version: 4
 summary: Utility class for creating and calling service objects.
 test_files: []