callable-mixin 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f02bb980d5c43522ab33033a546c9b9418bb02cec29dcc1ef7254413c9beaf7f
-  data.tar.gz: 796a78f8e6f06b9518742cde7b3fd6101921bad24b8201a0bcd26e0befff1a3d
+  metadata.gz: 3c4ab883eaeb5a2633c55642e2ad8aef2c97fc836d8eeb9a037e55d7e93bca84
+  data.tar.gz: b5b8203b5653d12f6d40730a734dd29febf78fd8e6db065cc651dced0b6ec248
 SHA512:
-  metadata.gz: 7be17d2dc903fe4b37bb4b5a8003296e36c6dfde4cefecfaf5ec5305ae02800b14088bc90443b74fb78796e49191def264b67b7b0aee9c00c0651f62e37673ce
-  data.tar.gz: 7d6b34a18d7bf1bf4ce34d919d8f0fbc3803bcc1a94cccb78d96f27db63e0a4f3667174d3fa53879aaf899c2705f2c85928e8f4354cdc1b4df5b440b5409bac2
+  metadata.gz: 2726c5f636c2ab6502db98a40afce7d237ae811d7a1b3c177c745b3926441ba2dd918b7a9dcb56800271e91b2ea624ade06de9e4da5233a07cdab20092eed547
+  data.tar.gz: c46915a2fb9687b707aaea865bd4c002ae197a0ed2f84355a9a924bf380240d8b8a26170c5175d8a338337e25cee66db60f7a87c1fefe1da3c1c1c90546b1a50

data/README.md

@@ -1,21 +1,28 @@
+[![Gem Version](https://badge.fury.io/rb/callable-mixin.svg)](https://badge.fury.io/rb/callable-mixin)
+[![Build Status](https://github.com/dbongo/callable-mixin/actions/workflows/ci.yml/badge.svg)](https://github.com/dbongo/callable-mixin/actions)
+
 # Callable
 
-Callable is a minimal Ruby mix-in that provides your classes with a simple `.call` class method. It allows you to instantiate and immediately invoke an instance method (`call`) without boilerplate or additional dependencies. Perfect for clean, readable, and concise service objects.
+Callable is a minimal Ruby mix-in that provides your classes with a simple `.call` class method (plus `to_proc`). It allows you to instantiate and immediately invoke an instance method (`call`) without boilerplate or additional dependencies. Perfect for clean, readable, and concise service objects.
+
+Learn more at https://rubydoc.info/gems/callable-mixin
 
 ## Features
 
 - Provides a `.call` class method to any Ruby class.
-- Transparently forwards positional arguments, keyword arguments, and blocks.
-- Handles argument errors gracefully, raising clear exceptions.
+- Supports `Class#to_proc`, letting you use `&YourService` in `Enumerable` methods.
+- Transparently forwards positional args, keyword args, and blocks to `#call`.
+- Raises `ConstructionError` (subclass of `ArgumentError`) for constructor arity/kwarg mismatches.
+- Raises `NotImplementedError` when the class does not define an instance `#call`.
 - Zero external runtime dependencies.
 - Compatible with MRI Ruby 2.3 through Ruby 3.x.
 
 ## Installation
 
-Add this to your application's Gemfile:
+Add this to your application's Gemfile (version 0.2.0 or later):
 
 ```ruby
-gem 'callable-mixin'
+gem 'callable-mixin', '~> 0.2.0'
 ```
 
 Then execute:
@@ -32,9 +39,7 @@ gem install callable-mixin
 
 ## Usage
 
-### In a Bundler-based app (Rails, Hanami, etc.)
-
-Simply include `Callable` in your class and implement an instance method named `call`:
+### Example Service with Multiple Arguments
 
 ```ruby
 class SendNotification
@@ -51,36 +56,66 @@ class SendNotification
 end
 ```
 
-### In a plain Ruby script
+- **Explicit invocation** when you need multiple constructor args:
 
-Require `'callable'`, include `Callable` in your class and implement an instance method named `call`:
+  ```ruby
+  users.each do |user|
+    SendNotification.call(user, "Your message here")
+  end
 
-```ruby
-require 'callable'
+  # You can also call via the `.()` alias:
+  SendNotification.(user, "Your message here")
+  ```
 
-class SendNotification
+### Example Service with Single Argument (to_proc Shorthand)
+
+```ruby
+class WelcomeUser
   include Callable
 
-  def initialize(user, message)
+  def initialize(user)
     @user = user
-    @message = message
   end
 
   def call
-    NotificationMailer.notify(@user, @message).deliver_now
+    NotificationMailer.welcome(@user).deliver_now
   end
 end
 ```
 
-Then run your class using the `.call` class method:
+- **Proc shorthand** for one-arg services:
+
+  ```ruby
+  users.each(&WelcomeUser)
+
+  # Or invoke with the `.()` alias:
+  WelcomeUser.(current_user)
+  ```
+
+### Using in a Plain Ruby Script
 
 ```ruby
-SendNotification.call(current_user, "Hello from Callable!")
+require 'callable-mixin'
 
-# or use .() (syntactic sugar for .call)
-SendNotification.(current_user, "Hello from Callable!")
-```
+# Define your service with Callable
+class MyService
+  include Callable
+
+  def initialize(value)
+    @value = value
+  end
 
+  def call
+    puts "Processing #{@value}"
+  end
+end
+
+# Invoke the service
+MyService.call("some data")
+
+# Or use the `.()` alias:
+MyService.("more data")
+```
 
 ## Development
 

data/lib/callable/mixin.rb

@@ -1,7 +1,28 @@
 # frozen_string_literal: true
 
+##
+# Callable
+#
+# A lightweight mix‑in that gives any class a convenient class‑level `.call` helper.
+#
+#   class SendEmail
+#     include Callable
+#
+#     def initialize(user)
+#       @user = user
+#     end
+#
+#     def call
+#       Mailer.welcome(@user).deliver_now
+#     end
+#   end
+#
+#   SendEmail.call(User.first)  # => delivers email
+#   users.each(&SendEmail)      # => thanks to #to_proc
+#
+# Compatible with Ruby 2.3+ and works the same on 3.x.
 module Callable
-  # Raised when .new fails due to arity / keyword mismatch
+  # Raised when `.call` cannot build the instance (arity/keyword mismatch).
   class ConstructionError < ArgumentError; end
 
   def self.included(base)
@@ -10,28 +31,32 @@ module Callable
 
   module ClassMethods
     ##
-    # Instantiate and immediately invoke #call
-    # @param args [Array] positional arguments for initialize
-    # @param kwargs [Hash] keyword arguments for initialize
-    # @yield [*] optional configuration/result block
-    # @return [Object] whatever the instance #call returns
-    # @raise  [ConstructionError] when instantiation fails
+    # Instantiate the class and immediately invoke its instance `#call`.
+    #
+    # @param args [Array] positional arguments for `initialize`.
+    # @param kwargs [Hash] keyword arguments for `initialize`.
+    # @yield [optional] block passed directly to the instance method `#call`; ignored if not yielded.
+    # @return anything returned by the instance `#call`.
+    # @raise [ConstructionError] if construction fails (plain `ArgumentError`).
+    # @raise [NotImplementedError] if the instance does not implement `#call`.
     def call(*args, **kwargs, &block)
-      inst = begin
-        # avoids Ruby 2.3–2.6 quirk
-        kwargs.empty? ? new(*args, &block) : new(*args, **kwargs, &block)
-      rescue ArgumentError => error
-        raise if error.class != ArgumentError
-        raise ConstructionError,
-              "Failed to construct #{name}.new with the supplied arguments: #{error.message}",
-              error.backtrace
+      # Ruby versions earlier than 2.7 can't reliably handle splatting empty kwargs, so branch for compatibility
+      inst = kwargs.empty? ? new(*args) : new(*args, **kwargs)
+    rescue ArgumentError => e
+      # Bubble up anything that isn't exactly ArgumentError (e.g., subclasses)
+      raise unless e.instance_of?(ArgumentError)
+      raise ConstructionError, "Cannot instantiate #{name}: #{e.message}", e.backtrace
+    else
+      # Ensure the instance defines `#call`
+      unless inst.respond_to?(:call)
+        raise NotImplementedError, "#{name} must implement #call"
       end
+      inst.call(&block)
+    end
 
-      if block_given? && inst.method(:call).arity.zero?
-        inst.call(&block)
-      else
-        inst.call
-      end
+    # @return [Proc] a proc that delegates to `.call`, enabling `&MyService` shorthand.
+    def to_proc
+      method(:call).to_proc
     end
   end
 end

data/lib/callable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Callable
-  VERSION = '0.1.2'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: callable-mixin
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Michael Crowther