mojones 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0e3e1098a30a3cb361430de99a97ede30f422ed06c4778d20f140bd313c7a3d
-  data.tar.gz: addc8a5acded5a911a9fd214a1983aeac71258a3d55e66f34e59f2ad7b18afba
+  metadata.gz: ab2a33993a4fda3c283c9e61948fa594c550422bfd8faab82037c9603fc2f335
+  data.tar.gz: 7df0d3e348b050307dd5c26c8de32d4cb18bf588ec6e1435a4818925c518dae9
 SHA512:
-  metadata.gz: 1705669f6ef6e3084bbe785385ebe343a8217825532255e0b48338eff104f6a2d1ba4e77e7dbd70666e43648030626833ffad5b45cc48e2c039a10f04bfdef91
-  data.tar.gz: 9907b26c7a0af8ccb7233a7f8c6830ae89ac4a806f963c21c41d88a652effa073b505769bacb480ab97448b950911a15b5c85612d77623184681fe375cc00bf0
+  metadata.gz: 8e360c4ab6d4c34059cf4b0aa68fe7bc25276a080ef908c6355aab4dfdbf2b3898cd9531009abd1b45c8d7b62920293e84dcc413e8faef2a85b45fd2b797fb03
+  data.tar.gz: efb0eac1c498889aa00d2c08a233721e730ed039015535e4ba8ae30af3a9376653dc57fc1a7224efdf48d48c20ddf19b011f1491c1c584fe93c34624f94ea3e6

data/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 0.2.0 (unreleased)
+
+### Breaking
+
+- **The first matching handler now wins, and later handlers don't run.**
+  Before, every matching handler ran and the last one's result was
+  returned. If you put a catch-all before a more specific handler, swap
+  them so the specific one comes first:
+
+  ```ruby
+  # 0.1.0
+  m.failure { |_| "Something went wrong" }
+  m.failure(:card_declined) { |_| "Your card was declined" }
+
+  # 0.2.0
+  m.failure(:card_declined) { |_| "Your card was declined" }
+  m.failure { |_| "Something went wrong" }
+  ```
+
+- **Failure values other than Symbols and exceptions reach the handler
+  unchanged.** For example, `Failure(user.errors)` now yields the errors
+  object. Before, it became a string: `to_s`, or a "translation missing"
+  message when I18n was loaded.
+- **Ruby 3.3 or later is required.** Ruby 3.2 reached end of life in March 2026.
+
+### Fixed
+
+- `rails generate mojones:service` works when the gem is installed from
+  RubyGems. The template was missing from the packaged gem.
+- Failures from anonymous service or exception classes no longer raise
+  `NoMethodError` when I18n is loaded.
+- Apps that load I18n without ActiveSupport no longer raise
+  `NoMethodError` from failure handlers. Translation is skipped instead.
+- The matcher no longer writes debug output to stdout outside Rails.
+
+## 0.1.0 (2026-03-21)
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Phil Brockwell, Habib Alamin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,127 @@
+# Mojones
+
+Service objects with monadic result handling. A lightweight framework
+around [dry-monads](https://dry-rb.org/gems/dry-monads/) that gives every
+service object one enforced shape — `.call` always returns a `Success`/
+`Failure` result (or raises), and a small block-based matcher lets callers
+branch on the outcome without a pile of `if result.success?` checks.
+
+## Installation
+
+```
+bundle add mojones
+```
+
+Or add it to your Gemfile directly:
+
+```ruby
+gem "mojones"
+```
+
+## Usage
+
+Inherit from `Mojones::Base` and return a `Dry::Monads::Result` from
+`#call`:
+
+```ruby
+class CreateUser < Mojones::Base
+  def initialize(params)
+    @params = params
+  end
+
+  def call
+    user = User.new(@params)
+    return Failure(user.errors) unless user.save
+
+    Success(user)
+  end
+end
+```
+
+Calling `.call` without a block gives you the `Result` itself:
+
+```ruby
+result = CreateUser.call(params) # => Success(#<User ...>) or Failure(#<ActiveModel::Errors ...>)
+result.value!                    # => #<User ...>, or raises on failure
+```
+
+Pass a block to match on the outcome instead:
+
+```ruby
+CreateUser.call(params) do |m|
+  m.success { |user| redirect_to user }
+  m.failure { |errors| render :new, status: :unprocessable_entity }
+end
+```
+
+`success` and `failure` can also filter on the value or error, using `===`
+(so classes, ranges, regexps and literal values all work):
+
+```ruby
+notice = ChargeCard.call(order) do |m|
+  m.success { |charge| "Charged #{charge.amount}" }
+  m.failure(CardDeclined) { |_| "Your card was declined" }
+  m.failure { |_error, message| message }
+end
+```
+
+Handlers are tried in order and the **first** match wins, like
+`case`/`when`. Later handlers don't run at all, so put specific handlers
+before catch-alls, and side effects like `redirect_to` only ever happen
+once.
+
+If the service raises, the exception is matchable as a failure, so
+`m.failure(ActiveRecord::RecordNotFound) { ... }` works. Without a block,
+or when no handler matches, the exception is re-raised.
+
+If `#call` returns something that isn't a `Dry::Monads::Result`, `.call`
+raises `Mojones::Base::Errors::ServiceReturnedNonResult`. That's a bug in
+the service, so it can't be matched.
+
+### Failure values and I18n
+
+A one-argument `failure` block gets the failure value translated:
+
+- A Symbol is looked up under the service's I18n scope, so
+  `Failure(:card_declined)` in `Billing::ChargeCard` is looked up as
+  `billing.charge_card.card_declined`. If there's no translation, it falls
+  back to `"Card declined"`.
+- An exception is looked up by its class name, falling back to its message.
+- Any other value (for example `user.errors`) is passed through unchanged.
+
+Translation needs I18n and ActiveSupport, so in practice it means Rails.
+Without them, Symbols and exceptions arrive as `to_s` strings. Anonymous
+classes are never translated.
+
+To get the untranslated value as well, take two arguments:
+
+```ruby
+m.failure { |error, message| flash[:alert] = message }
+```
+
+### Rails generator
+
+```
+bin/rails generate mojones:service CreateUser
+```
+
+Scaffolds `app/services/create_user.rb` with the `Mojones::Base` skeleton
+above.
+
+## Development
+
+```
+bundle install
+bundle exec rspec    # tests
+bundle exec rubocop  # lint
+```
+
+CI (`.github/workflows/`) runs both on every push and pull request.
+
+## License
+
+MIT — see `LICENSE.txt`.
+
+---
+
+Built by [TrueFlux](https://trueflux.agency).

data/lib/generators/mojones/templates/service.rb.tt

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class <%= class_name %> < Mojones::Base
+  def call
+    # TODO: implement service logic
+    Success(:ok)
+  end
+end

data/lib/mojones/base.rb

@@ -7,22 +7,13 @@ module Mojones
     module Errors
       class NoHandlerMatched < StandardError
         def initialize(value)
-          super
-          @value = value
+          super("No handler matched for #{value.inspect}")
         end
-
-        def message = "No handler matched for #{@value.inspect}"
       end
 
       class ServiceReturnedNonResult < StandardError
         def initialize(service, value)
-          super(value)
-          @service_name = service.class.inspect.sub(/^Mojones::/, "")
-          @value = value
-        end
-
-        def message
-          "Service #{@service_name} returned non-Result value (#{@value.inspect} : #{@value.class})"
+          super("Service #{service.name} returned non-Result value (#{value.inspect} : #{value.class})")
         end
       end
     end
@@ -36,10 +27,6 @@ module Mojones
         @value
       end
 
-      def fmap
-        yield @value
-      end
-
       def success?
         @value.success?
       end
@@ -57,30 +44,6 @@ module Mojones
       end
     end
 
-    class InitializerReturnedValue < ReturnedValue
-      def success? = true
-      def failure? = true
-      def original = @value
-
-      def assert_call_returned_result_monad_or_raised!
-        self
-      end
-    end
-
-    class CallReturnedValue < ReturnedValue
-      def initialize(service, value)
-        super(value)
-        @service = service
-        @value = value
-      end
-
-      def assert_call_returned_result_monad_or_raised!
-        return self if @value.is_a?(Dry::Monads::Result)
-
-        raise Errors::ServiceReturnedNonResult.new(@service, @value)
-      end
-    end
-
     class RaisedError
       def initialize(error)
         @error = error
@@ -97,35 +60,30 @@ module Mojones
         @error
       end
 
-      def fmap
-        self
-      end
-
       def no_matches!
         raise @error
       end
-
-      def assert_call_returned_result_monad_or_raised!
-        self
-      end
     end
 
-    def self.call(*args, **kwargs, &)
-      result = (
-        begin
-          InitializerReturnedValue.new(new(*args, **kwargs))
-        rescue StandardError => e
-          RaisedError.new(e)
-        end
-      ).fmap do |service_object|
-        CallReturnedValue.new(service_object, service_object.call)
-      rescue StandardError => e
-        RaisedError.new(e)
-      end.assert_call_returned_result_monad_or_raised!
-
+    def self.call(*, **, &)
+      result = execute(*, **)
       return result.value! unless block_given?
 
       Matcher.new(result, self, &).result
     end
+
+    # Errors raised by the service become a matchable RaisedError. Returning a
+    # non-Result is a bug in the service, so it raises instead (an exception
+    # raised in `else` isn't caught by the method's `rescue`).
+    def self.execute(*, **)
+      value = new(*, **).call
+    rescue StandardError => e
+      RaisedError.new(e)
+    else
+      raise Errors::ServiceReturnedNonResult.new(self, value) unless value.is_a?(Dry::Monads::Result)
+
+      ReturnedValue.new(value)
+    end
+    private_class_method :execute
   end
 end

data/lib/mojones/matcher.rb

@@ -1,98 +1,88 @@
 # frozen_string_literal: true
 
-require "logger"
-
 module Mojones
   class Matcher
-    class Match
-      attr_reader :matched, :result
-
-      def initialize(matched:, result:)
-        @matched = matched
-        @result = result
-      end
-
-      class Success < self; end
-      class Failure < self; end
-    end
-
     def initialize(service_result, service)
       @service = service
       @service_result = service_result
-      @matches = []
+      @matched = false
       yield(self) if block_given?
     end
 
     def result
-      return @service_result.no_matches! if @matches.empty?
-
-      @matches.last.result.tap do |chosen|
-        if @matches.size > 1
-          logger.debug <<~WARNING
-            #{service.name} matched multiple handlers; returning last result (#{chosen})
-          WARNING
-        end
-      end
+      return @service_result.no_matches! unless @matched
+
+      @result
     end
 
-    def success(*match_values, &block)
-      return unless @service_result.success?
+    # Handlers are tried in order and the first match wins, like case/when.
+    # Later handlers are skipped entirely, so their side effects never run.
+    def success(*patterns)
+      return if @matched || !@service_result.success?
 
       value = @service_result.original
+      return unless matches?(patterns, value)
 
-      return unless match_values.empty? || match_values.any? { _1 === value } # rubocop:disable Style/CaseEquality
-
-      @matches << Match::Success.new(
-        matched: value,
-        result: block.call(value)
-      )
+      match(yield(value))
     end
 
-    def failure(*match_errors, &block)
-      return unless @service_result.failure?
+    def failure(*patterns, &block)
+      return if @matched || !@service_result.failure?
 
       error = @service_result.original
-
-      return unless match_errors.empty? || match_errors.any? { _1 === error } # rubocop:disable Style/CaseEquality
+      return unless matches?(patterns, error)
 
       translated = translate_error(error)
-
-      @matches << Match::Failure.new(
-        matched: error,
-        result: block.arity == 2 ? block.call(error, translated) : block.call(translated)
-      )
+      match(block.arity == 2 ? yield(error, translated) : yield(translated))
     end
 
     private
 
     attr_reader :service
 
-    def logger
-      @logger ||= defined?(Rails) ? Rails.logger : Logger.new($stdout)
+    def match(result)
+      @matched = true
+      @result = result
     end
 
-    def service_name_lookup
-      @service_name_lookup ||= service.name.gsub("::", ".").underscore
+    # Matches like case/when, so classes, ranges, regexps and plain values all work.
+    def matches?(patterns, value)
+      return true if patterns.empty?
+
+      case value
+      when *patterns then true
+      else false
+      end
     end
 
     def translate_error(error)
-      return error.to_s unless defined?(I18n)
-
-      key =
-        case error
-        when Symbol
-          error
-        when StandardError
-          error.class.name.gsub("::", ".").underscore
-        end
-
-      default =
-        case error
-        when Symbol then error.to_s.humanize
-        when StandardError then error.message
-        end
-
-      I18n.t("#{service_name_lookup}.#{key}", default: default)
+      return error unless error.is_a?(Symbol) || error.is_a?(StandardError)
+      return error.to_s unless translatable?(error)
+
+      I18n.t(error_key(error), default: error_default(error))
+    end
+
+    # Keys are built from class names, so anonymous classes can't be translated.
+    def translatable?(error)
+      i18n_available? && service.name && (error.is_a?(Symbol) || error.class.name)
+    end
+
+    # Key building and defaults use ActiveSupport's inflector.
+    def i18n_available?
+      defined?(I18n) && defined?(ActiveSupport::Inflector)
+    end
+
+    def error_key(error)
+      key = error.is_a?(Symbol) ? error : i18n_path(error.class.name)
+      "#{i18n_path(service.name)}.#{key}"
+    end
+
+    def error_default(error)
+      error.is_a?(Symbol) ? ActiveSupport::Inflector.humanize(error) : error.message
+    end
+
+    def i18n_path(name)
+      ActiveSupport::Inflector.underscore(name.gsub("::", "."))
     end
   end
 end

data/lib/mojones/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mojones
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mojones
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Phil Brockwell
@@ -33,15 +33,20 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
 - lib/generators/mojones/service_generator.rb
+- lib/generators/mojones/templates/service.rb.tt
 - lib/mojones.rb
 - lib/mojones/base.rb
 - lib/mojones/matcher.rb
 - lib/mojones/version.rb
-homepage: https://trueflux.agency
+homepage: https://github.com/TrueFlux/mojones
 licenses:
 - MIT
 metadata:
+  changelog_uri: https://github.com/TrueFlux/mojones/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -50,14 +55,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Service objects with monadic result handling
 test_files: []