gl_command 1.2.0 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 705c23dec5e3038e7a6b4d0736f58589b775edd30ee53056d2478b8361f9a3d6
-  data.tar.gz: a547c64df86a0f2a533ad43ea5f1ee0a1e2dfcc8fe27e6f1c85b4a018ad75b39
+  metadata.gz: affffd85a3150ca92bd45b28822125b8a64117bb41d2f8bffa9fd2861712c9d5
+  data.tar.gz: 45e62be391f6958720e3e8aec0a7f04fbaf0d9fe4a5b9b382fc2ae4b91246689
 SHA512:
-  metadata.gz: b13e47c074cc18aeeb50cd0e874c088cd7c0091b52fc5d705b4b5b79ddbb18fa1b3d12b596bf2febd85264a1fe5f9e933fa0893444b21369a4a8cc4a3a33c64f
-  data.tar.gz: 25ac2f9a597e199fef77ebcd08442937615b63102bd8e071d0aea68ede1a2e83da085e902022f54ed32a41ddcf474510e9be811f3dc37941b78f7a2498a0c383
+  metadata.gz: 9c2ac5fcedfc9156231e3d146a221945deca5e3f687b2413fe7db9fecd02e9ba3c8f0b94223d0e414fae1946b1ce52eb574118cfaa873a2524cea1f9b8a7812a
+  data.tar.gz: 31aee586028c0cf073f22f267ee3ad095f48041aace47df51fe9b4c48ed6a6487f2a1d138ad26e786f75e314adc087e87b573032663d9bf363adfceb6a8ac790

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,21 @@ 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)
+- [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 +65,7 @@ class SomeCommand < GLCommand::Callable
 end
 ```
 
-## Success/Failure
+### Success/Failure
 
 GLCommand context's are successful by default (`successful?` aliases `success?`).
 
@@ -70,13 +85,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 +104,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!`
@@ -139,7 +155,7 @@ If validations fail, `GLExceptionNotifier` is not called
 
 ## 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 +163,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 +227,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/gl_command.gemspec

@@ -19,5 +19,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'activerecord', '>= 3.2.0'
   spec.add_dependency 'gl_exception_notifier', '>= 1.0.2'
 
+  spec.add_development_dependency 'rspec', '~> 3.0'
+
   spec.metadata['rubygems_mfa_required'] = 'true'
 end

data/lib/gl_command/callable.rb

@@ -202,6 +202,7 @@ module GLCommand
 
       chain_rollback if self.class.chain? # defined in GLCommand::Chainable
       rollback
+      instrument_command(:after_rollback)
     end
 
     # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity

data/lib/gl_command/context_inspect.rb

@@ -1,5 +1,9 @@
+# frozen_string_literal: true
+
 module GLCommand
   class ContextInspect
+    PERMITTED_OUTPUTS = %i[string hash].freeze
+
     class << self
       def error(error_obj)
         return '' if error_obj.blank?
@@ -7,35 +11,50 @@ module GLCommand
         error_obj.is_a?(Array) ? error_obj.uniq.join(', ') : error_obj.to_s
       end
 
-      def hash_params(hash)
-        hash.map do |key, value|
-          value_s =
-            if value.nil?
-              'nil'
-            elsif value.respond_to?(:to_sql)
-              object_param_as_sql(value)
-            elsif value.respond_to?(:uuid)
-              object_param_with_id(value, :uuid)
-            elsif value.respond_to?(:id)
-              object_param_with_id(value, :id)
-            else
-              value
-            end
-          "#{key}: #{value_s}"
-        end.join(', ')
+      def hash_params(hash, output: :string)
+        unless PERMITTED_OUTPUTS.include?(output)
+          raise "Unknown output type: #{output}, must be one of #{PERMITTED_OUTPUTS}"
+        end
+
+        result = hash.map { |key, value| output_for(key:, value:, output:) }
+        output == :string ? result.join(', ') : result.to_h
       end
 
       private
 
+      def output_for(key:, value:, output:)
+        value_s = if value.nil?
+                    'nil'
+                  elsif value.respond_to?(:to_sql)
+                    object_param_as_sql(value, output:)
+                  elsif value.respond_to?(:id)
+                    object_param_with_id(value, :id, output:)
+                  elsif value.respond_to?(:uuid)
+                    object_param_with_id(value, :uuid, output:)
+                  else
+                    value
+                  end
+
+        output == :string ? "#{key}: #{value_s}" : [key, value_s]
+      end
+
       # Active record objects can be really big - rather than rendering the whole object, just show the ID
-      def object_param_with_id(obj, key)
+      def object_param_with_id(obj, key, output:)
         obj_id = obj.send(key)
-        id_value = obj_id.is_a?(Integer) ? obj_id : "\"#{obj_id}\""
-        "#<#{obj.class.name} #{key}=#{id_value}>"
+        if output == :string
+          id_value = obj_id.is_a?(Integer) ? obj_id : "\"#{obj_id}\""
+          "#<#{obj.class.name} #{key}=#{id_value}>"
+        else
+          obj_id
+        end
       end
 
-      def object_param_as_sql(obj)
-        "#<#{obj.class.name} sql=\"#{obj.to_sql}\">"
+      def object_param_as_sql(obj, output:)
+        if output == :string
+          "#<#{obj.class.name} sql=\"#{obj.to_sql}\">"
+        else
+          obj.to_sql
+        end
       end
     end
   end

data/lib/gl_command/rspec/matchers.rb

@@ -0,0 +1,111 @@
+# 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; end
+      def action; 'require'; end
+    end
+
+    class AllowArgumentMatcher < CommandArgumentMatcher
+      private
+
+      def scope; :allows; end
+      def action; 'allow'; end
+    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
+
+      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
+
+      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

data/lib/gl_command/version.rb

@@ -1,3 +1,3 @@
 module GLCommand
-  VERSION = '1.2.0'.freeze
+  VERSION = '1.4.0'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: gl_command
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Give Lively
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-01 00:00:00.000000000 Z
+date: 2025-07-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.2
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description:
 email:
 executables: []
@@ -54,6 +68,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