gl_command 1.3.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d64529ae90558047a1a67fb4641fcbc6807f4bac0ef8b503945d2981dac33f80
-  data.tar.gz: 541c75d629f1ba4971ab7d6fd37ac4a1fdfee2f19cb6256477d4857408fb64ce
+  metadata.gz: 5c1d353b0428b6aa32adf96b5962256b415dfacc45116d3e4a21ea8ca345de8e
+  data.tar.gz: f8056f5711ef8ffdfafd3678fd25c05fa1879f2893f1d9acecaa9a3880565d7a
 SHA512:
-  metadata.gz: 7767272a19c79ed50bc21bcd5a94a04f8f16c26e509bdfc3b86937e8204dabf2d053ea2fc85919acc56de3a770fd35ff88490b2d101fdcf6e6a89a714c55176f
-  data.tar.gz: f4fd2347bedf5ccbd94c09e230bf760d16d0ec1f19a4ecada73416d7a4b0da52a7f79759f074c4a38f98cd783ce45a07dd84c46dd1f13b87685cfdec8d0e9c9e
+  metadata.gz: 8229ae95a48c6b5fc83fbeb647d604666be82cc2e35b08d294c6c8c4c7e44ec4c52d40f520ead9005d38edeee0aab9fc03f0db9e637271b2fd1dbd98619efd21
+  data.tar.gz: 678f19f03349988f5a033eeb1f5cff6acb846e0c2b5eea744b7493e0419232d7e0e56f2b4684c9857f0d5e78d7119b9147bef86cf0b5ac642056f9b67365cd8d

data/README.md

@@ -1,6 +1,6 @@
 # GLCommand
 
-`GLCommand` is a way to encapsulate business logic.
+`GLCommand` is a way to encapsulate business logic and standardize error handling.
 
 Calling a command returns a `GLCommand::Context` which has these properties:
 
@@ -10,6 +10,22 @@ Calling a command returns a `GLCommand::Context` which has these properties:
 - `full_error_message` - which renders a string from the error, or can be set explicitly (used to show a legible error to the user).
 - `success` - `true` if the command executed without an error (false if there is an `error`)
 
+# Table of contents
+
+- [Installation](#installation)
+- [Using GLCommand](#using-glcommand)
+  - [Success/Failure](#successfailure)
+  - [Displaying errors (use `full_error_message`)](#displaying-errors-use-full_error_message)
+  - [stop_and_fail!](#stop_and_fail)
+  - [Validations](#validations)
+  - [Best practices for error handling](#best-practices-for-error-handling)
+- [GLExceptionNotifier](#glexceptionnotifier)
+- [Chainable](#chainable)
+- [Testing `GLCommand`s](#testing-glcommands)
+  - [Stubbing with `build_context`](#stubbing-with-build_context)
+  - [Rspec matchers](#rspec-matchers)
+- [Publishing the gem to Rubygems](#publishing-the-gem-to-rubygems)
+
 
 ## Installation
 
@@ -50,7 +66,7 @@ class SomeCommand < GLCommand::Callable
 end
 ```
 
-## Success/Failure
+### Success/Failure
 
 GLCommand context's are successful by default (`successful?` aliases `success?`).
 
@@ -70,13 +86,14 @@ Here are the ways of adding an error to a command:
 
 If you invoke a command with `.call!` all of the above will raise an exception
 
-If a command fails, it will call its `rollback` method before returning (even when invoked with `.call!`)
+If a command fails, it calls its `rollback` method before returning (even when invoked with `.call!`)
 
-### Displaying errors
+
+### Displaying errors (use `full_error_message`)
 
 In addition to encapsulating business logic, GLCommand also standardizes error handling.
 
-This means that rather than having to rescue errors in controllers, you can just render the command's `full_error_message`
+This means that rather than having to rescue errors in controllers, just render the command's `full_error_message`
 
 ```ruby
 result = GLCommand::Callable.call(params)
@@ -88,7 +105,7 @@ else
 end
 ```
 
-In general, use `context.full_error_message` to render errors.
+In general, use `context.full_error_message` to render errors (rather than `context.error.message` which might not have the full error message text).
 
 
 ### `stop_and_fail!`
@@ -130,16 +147,45 @@ stop_and_fail!('An error message', no_notify: true) # GLExceptionNotifier is *no
 
 ### Validations
 
-You can add validations to `GLCommand::Callable` and `GLCommand::Chainable`.
+You can add validations to `GLCommand::Callable` and `GLCommand::Chainable`. They include `ActiveModel::Validations`, so you can use [Rails active record validations](https://guides.rubyonrails.org/active_record_validations.html).
+
+If the validations fail, the command returns `success: false` without executing and if validations fail, `GLExceptionNotifier` is **not** called.
+
+```ruby
+class ExampleCommand < GLCommand::Callable
+  validates :name, presence: true
+  validate :name_must_start_with_cool
+
+  def name_must_start_with_cool
+    return true unless name.start_with?('cool')
+
+    errors.add(:name, "Doesn't start with 'cool'")
+  end
+end
+```
+
+### Best practices for error handling
 
-If the validations fail, the command returns `success: false` without executing.
+#### Only add validation errors in validations
 
-If validations fail, `GLExceptionNotifier` is not called
+i.e. don't use `errors.add` in the `call` method. Use `stop_and_fail!` instead.
 
+#### Prefer raising the original error
+
+For example, if you want to raise a custom error message, don't rescue and then `stop_and_fail!('Some special error message')`. Do this instead:
+
+```ruby
+rescue StandardError => e
+  context.full_error_message = "Some special error message"
+  raise e
+end
+```
+
+This will preserve the original error and stack trace, which makes it easier to debug and track down issues.
 
 ## GLExceptionNotifier
 
-[ExceptionNotifier](https://github.com/givelively/gl_exception_notifier) is Give Lively's wrapper for notify our error monitoring service (currently [Sentry](https://github.com/getsentry/sentry-ruby))
+[GLExceptionNotifier](https://github.com/givelively/gl_exception_notifier) is Give Lively's wrapper for notify our error monitoring service (currently [Sentry](https://github.com/getsentry/sentry-ruby))
 
 When a command fails `GLExceptionNotifier` is called, unless:
 
@@ -147,7 +193,7 @@ When a command fails `GLExceptionNotifier` is called, unless:
 - The failure is a validation failure
 - `stop_and_fail!` is called with `no_notify: true` - for example `stop_and_fail!('An error message', no_notify: true)`
 
-**NOTE:** commands that invoke other commands with `call!` inherit the no_notify property of called command.
+**NOTE:** commands that invoke other commands with `call!` inherit the `no_notify` property of the called command.
 
 ```ruby
 class InteriorCommand < GLCommand::Callable
@@ -211,9 +257,104 @@ class SomeChain < GLCommand::Chainable
     chain(:item)
   end
 end
+```
+
+## RSpec Matchers
+
+`GLCommand` comes with a set of RSpec matchers to make testing your command's interface declarative and simple.
+
+### Setup
+
+To enable the matchers, add the following line to your `spec/spec_helper.rb` or `spec/rails_helper.rb`:
+
+```ruby
+require 'gl_command/rspec'
+```
+
+This will automatically include the necessary matchers and configure RSpec for specs marked with `type: :command`.
+
+### Usage
+
+You can now test your command's interface like this:
+
+```ruby
+# spec/commands/some_command_spec.rb
+
+RSpec.describe SomeCommand, type: :command do
+  describe 'interface' do
+    it { is_expected.to require(:user).being(User) }
+    it { is_expected.to allow(:subject) }
+    it { is_expected.to returns(:message) }
+    it { is_expected.not_to require(:other_thing) }
+  end
+end
+```
+
+**Note:** The `.being(ClassName)` chain is supported for `require` and `allow` but not for `return`, as `GLCommand` does not store type information for return values.
+
+## Testing `GLCommand`s
+
+Give Lively uses Rspec for testing, so this section assumes you're using RSpec.
+
+### Stubbing with `build_context`
+
+If you need the response from a command (typically because you are stubbing it), use the `build_context` method to create a context with the desired response. This has the advantage of using the actual Command's `requires`, `allows`, and `returns` methods.
+
+```ruby
+class SomeCommand < GLCommand::Callable
+  requires user: User
+  allows :subject
+  returns :message
+
+  def call
+    user.update!(subject:)
+    context.message = "Hello - user subject: #{user.subject}"
+  end
+end
+
+result = SomeCommand.build_context(user: User.new, message: "Hello!")
+result.success? # true
+result.full_error_message # nil
+result_error = SomeCommand.build_context(error: "invalid")
+result_error.success? # false
+result_error.full_error_message # "invalid"
 
+SomeCommand.build_context(other_thing: "some other thing")
+# ArgumentError: Unknown argument or return attribute: 'other_thing'
+```
+
+### RSpec Matchers
+
+`GLCommand` comes with a set of RSpec matchers to make testing your command's interface declarative and simple.
+
+### Setup
+
+To enable the matchers, add the following line to your `spec/spec_helper.rb` or `spec/rails_helper.rb`:
+
+```ruby
+require 'gl_command/rspec'
+```
+
+This will automatically include the necessary matchers and configure RSpec for specs marked with `type: :command`.
+
+### Usage
+
+You can now test your command's interface like this:
+
+```ruby
+# spec/commands/some_command_spec.rb
+
+RSpec.describe SomeCommand, type: :command do
+  describe 'interface' do
+    it { is_expected.to require(:user).being(User) }
+    it { is_expected.to allow(:subject) }
+    it { is_expected.to returns(:message) }
+    it { is_expected.not_to require(:other_thing) }
+  end
+end
 ```
 
+**Note:** The `.being(ClassName)` chain is supported for `require` and `allow` but not for `return`, as `GLCommand` does not store type information for return values.
 
 ## Publishing the gem to Rubygems
 

data/lib/gl_command/callable.rb

@@ -214,12 +214,15 @@ module GLCommand
       raise ArgumentError, "unknown #{error_keys_str(unknown)}" if unknown.any?
 
       # strong_attributes type checking
+      # type can be a class (e.g. String), a symbol naming a predicate method
+      # the value must answer truthily (e.g. :acts_as_syncable?), or an array of
+      # either (e.g. [User, AdminUser]), in which case the value may match any
       self.class.requires.merge(self.class.allows).each do |arg, type|
-        next if type.nil? || args[arg].is_a?(type)
+        next if type.nil? || Array(type).any? { |t| value_matches_type?(args[arg], t) }
         # Validation skipped if allows and nil (but not if blank)
         next if args[arg].nil? && self.class.allows.include?(arg)
 
-        raise GLCommand::ArgumentTypeError, ":#{arg} is not a #{type}"
+        raise GLCommand::ArgumentTypeError, ":#{arg} is not #{type_error_str(type)}"
       end
     end
     # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
@@ -227,5 +230,21 @@ module GLCommand
     def error_keys_str(keys)
       "keyword#{keys.count > 1 ? 's' : ''}: #{keys.map { |k| ":#{k}" }.join(', ')}"
     end
+
+    # A type can be a class (checked with is_a?) or a symbol naming a predicate
+    # method the value must respond to and return truthy from
+    def value_matches_type?(value, type)
+      if type.is_a?(Symbol)
+        value.respond_to?(type) && value.public_send(type)
+      else
+        value.is_a?(type)
+      end
+    end
+
+    def type_error_str(type)
+      return "one of #{type.join(', ')}" if type.is_a?(Array)
+
+      type.is_a?(Symbol) ? type.to_s : "a #{type}"
+    end
   end
 end

data/lib/gl_command/context.rb

@@ -27,7 +27,7 @@ module GLCommand
 
     # If someone calls #errors, they expect to get the errors! Include the non-validation error, if it exists
     def errors
-      current_errors&.add(:base, "Command Error: #{full_error_message}") if add_command_error?
+      current_errors&.add(:base, full_error_message) if add_command_error?
       current_errors
     end
 
@@ -126,7 +126,10 @@ module GLCommand
     private
 
     def current_errors
-      @callable&.errors
+      return @callable.errors if defined?(@callable)
+
+      # @standalone_errors only is instantiated when you use build_context
+      (@standalone_errors ||= ActiveModel::Errors.new(self))
     end
 
     def add_command_error?
@@ -136,7 +139,7 @@ module GLCommand
 
       # Add command error unless the existing error is a validation error or there's already a command error
       @error&.class != ActiveRecord::RecordInvalid &&
-        current_errors.full_messages.none? { |err| err.start_with?('Command Error: ') }
+        current_errors.full_messages.none? { |err| err == @error.message }
     end
 
     def exception?(passed_error)

data/lib/gl_command/rspec/matchers.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# This file is intended to be required by lib/gl_command/rspec.rb
+
+module GLCommand
+  module Matchers
+    # Base matcher for `requires` and `allows`, which store a Hash of { attribute: Type }.
+    class CommandArgumentMatcher
+      def initialize(attribute)
+        @attribute = attribute
+        @expected_type = nil
+      end
+
+      def being(expected_type)
+        @expected_type = expected_type
+        self
+      end
+
+      def matches?(command_class)
+        @command_class = command_class.is_a?(Class) ? command_class : command_class.class
+        attributes = @command_class.public_send(scope)
+
+        return false unless attributes.key?(@attribute)
+        return true if @expected_type.nil? # Type check not requested
+
+        attributes[@attribute] == @expected_type
+      end
+
+      def description
+        "#{action} argument `#{@attribute}`"
+      end
+
+      def failure_message
+        message = "Expected #{@command_class.name} to #{action} `#{@attribute}`"
+        message += " of type `#{@expected_type}`" if @expected_type
+        message
+      end
+
+      def failure_message_when_negated
+        message = "Expected #{@command_class.name} not to #{action} `#{@attribute}`"
+        message += " of type `#{@expected_type}`" if @expected_type
+        message
+      end
+    end
+
+    class RequireArgumentMatcher < CommandArgumentMatcher
+      private
+
+      def scope = :requires
+      def action = 'require'
+    end
+
+    class AllowArgumentMatcher < CommandArgumentMatcher
+      private
+
+      def scope = :allows
+      def action = 'allow'
+    end
+
+    # Specific matcher for `returns`, which only stores an Array of keys.
+    class ReturnAttributeMatcher
+      def initialize(attribute)
+        @attribute = attribute
+        @type_check_attempted = false
+      end
+
+      def being(_expected_type)
+        @type_check_attempted = true
+        self
+      end
+
+      # rubocop:disable Layout/LineLength
+      def matches?(command_class)
+        @command_class = command_class.is_a?(Class) ? command_class : command_class.class
+
+        if @type_check_attempted
+          @failure_reason = 'GLCommand::Callable does not store types for `returns`, so `.being()` cannot be used.'
+          return false
+        end
+
+        @command_class.returns.include?(@attribute)
+      end
+      # rubocop:enable Layout/LineLength
+
+      def description
+        "return attribute `#{@attribute}`"
+      end
+
+      def failure_message
+        return @failure_reason if @failure_reason
+
+        "Expected #{@command_class.name} to return `#{@attribute}`"
+      end
+
+      def failure_message_when_negated
+        "Expected #{@command_class.name} not to return `#{@attribute}`"
+      end
+    end
+
+    # Helper methods to provide the clean syntax in specs
+    def require(attribute)
+      RequireArgumentMatcher.new(attribute)
+    end
+
+    def allow(attribute)
+      AllowArgumentMatcher.new(attribute)
+    end
+
+    def returns(attribute)
+      ReturnAttributeMatcher.new(attribute)
+    end
+  end
+end

data/lib/gl_command/rspec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require 'gl_command/rspec/matchers'
+
+# A shared context to automatically set the subject of a spec to the
+# described class. This allows `is_expected` to work directly on the
+# command class in specs with `type: :command`.
+RSpec.shared_context 'GLCommand::Command subject' do
+  subject { described_class }
+end
+
+RSpec.configure do |config|
+  # Makes the matcher methods (require, allow, returns) available in these specs.
+  config.include GLCommand::Matchers, type: :command
+
+  # Allows `is_expected` to work directly on the command class.
+  config.include_context 'GLCommand::Command subject', type: :command
+end

data/lib/gl_command/validatable.rb

@@ -2,6 +2,7 @@
 
 require 'active_support/concern'
 require 'active_model'
+require 'active_record'
 
 module GLCommand
   module Validatable
@@ -12,7 +13,7 @@ module GLCommand
     include ActiveModel::Validations
 
     class_methods do
-      def i18n_scope
+      define_method(:i18n_scope) do
         :activerecord
       end
     end

data/lib/gl_command/version.rb

@@ -1,3 +1,3 @@
 module GLCommand
-  VERSION = '1.3.0'.freeze
+  VERSION = '2.0.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gl_command
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Give Lively
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-05-22 00:00:00.000000000 Z
+date: 2026-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -54,6 +54,8 @@ files:
 - lib/gl_command/chainable_context.rb
 - lib/gl_command/context.rb
 - lib/gl_command/context_inspect.rb
+- lib/gl_command/rspec.rb
+- lib/gl_command/rspec/matchers.rb
 - lib/gl_command/validatable.rb
 - lib/gl_command/version.rb
 homepage: https://github.com/givelively/gl_command
@@ -76,7 +78,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: Give Lively Commands