gl_command 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 11a5d5ab9dd4a28700cb671153c1a757612f5b735194a28ad22f8be660a09250
+  data.tar.gz: a3a351134af335563ee6e970d5920d08e52f2b4375cef1c8adc87e555bd1e64f
+SHA512:
+  metadata.gz: 4344a62dca3bccad299425f9d22db05ca7e3062518c0f4a0c3b1be2d3708de8ccb3d310380c5a4eb73b515a21c4866c8b3385f9ee18c23e9389fd49e9afb8803
+  data.tar.gz: '08c842fe87ac92bc793fad76498e0b12ecc772a8d5385fea2d5c34670115ba40a17545227e572a5ce1bcee9b3bc6c52f2e70f59e45a8755a871b93ebe3d344a2'

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,202 @@
+# GLCommand
+
+`GLCommand` is a way to encapsulate business logic.
+
+Calling a command returns a `GLCommand::Context` which has these properties:
+
+- The arguments that were passed in to the command `.call` method (set via `allows` `requires`)
+- The returns from the `.call` method
+- `error` (which contains the error, if an error was raised)
+- `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`)
+
+
+## Installation
+
+Add the following line to your Gemfile:
+
+```ruby
+gem 'gl_command'
+```
+
+Download and install the gem:
+```sh
+bundle install
+```
+
+## Using GLCommand
+
+Invoke a command with `.call` or `.call!`
+
+`.call` will return the `GLCommand::Context`, with `error` assigned (if there is an error)
+
+`.call!` will raise the error (if there is an error), otherwise it will return the `GLCommand::Context`
+
+General rules for deciding whether to use `.call!`
+
+- In controllers use `.call` (make sure you check that it succeeds and [render errors](#displaying-errors) appropriately)
+- In background jobs and rake tasks, use `.call!`
+- Use `.call!` when calling a command within another command. If the inner command fails, it will assign errors to the outer command.
+
+```ruby
+class SomeCommand < GLCommand::Callable
+  returns :data
+
+  def call
+    # If OtherCommand fails, SomeCommand will also fail - with the error from OtherCommand
+    result = OtherCommand.call!
+    context.data = result.data
+  end
+end
+```
+
+## Success/Failure
+
+GLCommand context's are successful by default (`successful?` aliases `success?`).
+
+They are a failure (`success? == false`) if the context has an error.
+
+Here are the ways of adding an error to a command:
+
+- Raising an exception
+  - Immediately stops execution
+- Calling `stop_and_fail!`
+  - Immediately stops execution
+- Failing a validation
+  - Validation errors are checked before the `call` method is invoked (if `valid? == false` the command will return).
+  - If validations are added during the `call` method, the command fails after call
+- Directly assigning `context.error` or `context.full_error_message` to a non-nil value
+  - Checked after `call` method finishes
+
+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!`)
+
+### Displaying errors
+
+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`
+
+```ruby
+result = GLCommand::Callable.call(params)
+if result.success?
+  redirect_to new_controller_action
+else
+  flash[:error] = result.full_error_message
+  redirect_back
+end
+```
+
+In general, use `context.full_error_message` to render errors.
+
+
+### `stop_and_fail!`
+
+Use `stop_and_fail!` to immediately stop a command and raise an error (`GLCommand::StopAndFail` by default)
+
+The argument to `stop_and_fail!` is assign to the `context.error`
+
+- If you pass an exception, that exception will be raised and/or sent to Sentry
+- Otherwise, the error will be a `GLCommand::StopAndFail` and what was passed will be assigned to `full_error_message`
+
+```ruby
+# Passing a string:
+stop_and_fail!('An error message')
+context.error # => GLCommand::StopAndFail
+context.full_error_message # => 'An error message'
+
+# Passing an exception:
+stop_and_fail!(ActiveRecord::RecordNotFound)
+context.error # => ActiveRecord::RecordNotFound
+context.full_error_message # => ActiveRecord::RecordNotFound
+
+# Passing an exception with an error message
+stop_and_fail!(ActiveRecord::RecordNotFound.new('Some error message'))
+context.error # => ActiveRecord::RecordNotFound
+context.full_error_message # => 'Some error message'
+```
+
+You can also include `no_notify: true`, which prevents `GLExceptionNotifier` from being called.
+
+```ruby
+# Sentry is notified when #call fails by default:
+stop_and_fail!('An error message') # GLExceptionNotifier is called
+
+# If you don't want to alert Sentry when the command fails in a specific way:
+stop_and_fail!('An error message', no_notify: true) # GLExceptionNotifier is *not* called
+```
+
+
+### Validations
+
+You can add validations to `GLCommand::Callable` and `GLCommand::Chainable`.
+
+If the validations fail, the command returns `success: false` without executing.
+
+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))
+
+When a command fails `GLExceptionNotifier` is called, unless:
+
+- The command is invoked with `call!` (because an error will be raised, which will alert Sentry)
+- 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.
+
+```ruby
+class InteriorCommand < GLCommand::Callable
+  def call
+    stop_and_fail!('An error message', no_notify: true)
+  end
+end
+
+class MainCommand < GLCommand::Callable
+  def call
+    # Use call! in commands that invoke other commands to have the errors automatically bubble up
+    InteriorCommand.call!
+  end
+end
+
+# This won't call GLExceptionNotifier, because no_notify: true was used on InteriorCommand
+result = MainCommand.call
+result.success? # => false
+result.full_error_message # => 'An error message'
+```
+
+## Chainable
+
+Bundle commands together with `GLCommand::Chainable`
+
+- Automatically passes the requires/allows and returns between the commands
+- Returns a `GLCommand::ChainableContext`, that inherits from `GLCommand::Context`. It adds a `Commands` array that contains the Command class names that were called.
+- A command in the chain failing will call `rollback` on itself and then each command in the context `Command` array (in reverse order)
+
+
+If you need to do logic in the `GLCommand::Chainable` class, define the `call` method and invoke `chain` from that.
+
+```ruby
+class SomeChain < GLCommand::Chainable
+  requires :item
+
+  returns :new_item
+
+  chain CommmandOne, CommandTwo
+
+  def call
+    # Add some logic goes here
+    chain(item:) # Automatically assigns the return to the context
+    # Additional logic here
+  end
+end
+```
+
+
+---
+
+This library is influenced by [interactors](https://github.com/collectiveidea/interactor) and inspired by the [Command Pattern](https://en.wikipedia.org/wiki/Command_pattern).

data/gl_command.gemspec

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'lib/gl_command/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'gl_command'
+  spec.version = GLCommand::VERSION
+  spec.authors = ['Give Lively']
+  spec.summary = 'Give Lively Commands'
+  spec.homepage = 'https://github.com/givelively/gl_command'
+  spec.license = 'Apache'
+  spec.platform = Gem::Platform::RUBY
+
+  spec.required_ruby_version = '>= 3.1'
+  spec.extra_rdoc_files = ['README.md']
+  spec.files = %w[gl_command.gemspec README.md LICENSE] + `git ls-files | grep -E '^(lib)'`.split("\n")
+
+  spec.add_dependency 'activerecord', '>= 3.2.0'
+  spec.add_dependency 'gl_exception_notifier', '>= 1.0.2'
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+end

data/lib/gl_command/callable.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'active_support/core_ext/module'
+require 'gl_exception_notifier'
+require 'gl_command/validatable'
+
+module GLCommand
+  class Callable
+    DEFAULT_OPTS = { raise_errors: false, skip_unknown_parameters: true }.freeze
+    RESERVED_WORDS = (DEFAULT_OPTS.keys + GLCommand::ChainableContext.reserved_words).sort.freeze
+
+    class << self
+      # Make raise_errors and skip_unknown_parameters reserved and raise if they're passed in
+      def call(*posargs, **args)
+        if arguments_and_returns.intersect?(RESERVED_WORDS)
+          raise ArgumentError,
+                "You used reserved word(s): #{arguments_and_returns & RESERVED_WORDS}\n" \
+                '(check GLCommand::Callable::RESERVED_WORDS for the full list)'
+        end
+
+        if posargs.any?
+          raise ArgumentError,
+                "`call` only supports keyword args, not positional - you passed: '#{posargs}'"
+        end
+
+        # DEFAULT_OPTS contains skip_unknown_parameters: true - so it raises on call
+        # (rather than in context initialize) to make errors more legible
+        opts = DEFAULT_OPTS.merge(raise_errors: args.delete(:raise_errors)).compact
+        # args are passed in in perform_call(args) so that invalid args raise in a legible place
+        new(build_context(**args.merge(opts))).perform_call(args)
+      end
+
+      def call!(*posargs, **args)
+        call(*posargs, **args.merge(raise_errors: true))
+      end
+
+      def build_context(raise_errors: false, skip_unknown_parameters: false,
+                        **arguments_and_returns)
+        context_class.new(self, raise_errors:, skip_unknown_parameters:, **arguments_and_returns)
+      end
+
+      def requires(*attributes, **strong_attributes)
+        @requires ||= strong_args_hash(*attributes, **strong_attributes).freeze
+      end
+
+      def allows(*attributes, **strong_attributes)
+        @allows ||= strong_args_hash(*attributes, **strong_attributes).freeze
+      end
+
+      def returns(*attributes, **strong_attributes)
+        # NOTE: Because returns aren't validated, we don't store the types (only store keys)
+        @returns ||= strong_args_hash(*attributes, **strong_attributes).keys.freeze
+      end
+
+      # arguments are what's passed to the .call command (the allows and requires)
+      def arguments
+        return @arguments if defined?(@arguments)
+
+        duplicated_keys = requires.keys & allows.keys
+        raise "Duplicated: #{duplicated_keys} - in both requires and allows" if duplicated_keys.any?
+
+        @arguments = (requires.keys + allows.keys).freeze
+
+        delegate(*@arguments + returns, to: :context)
+        @arguments
+      end
+
+      # arguments_and_returns is just the keys (names) of the arguments and returns
+      def arguments_and_returns
+        (arguments + returns).uniq
+      end
+
+      # Used internally by GLCommand (probably don't reference them in your own GLCommands)
+      # is true in GLCommand::Chainable
+      def chain?
+        false
+      end
+
+      def rescue_from(error_class, with:)
+        error_handlers[error_class] = with
+      end
+
+      def error_handlers
+        @error_handlers ||= {}
+      end
+
+      private
+
+      def context_class
+        chain? ? GLCommand::ChainableContext : GLCommand::Context
+      end
+
+      def strong_args_hash(*attributes, **strong_attributes)
+        # Convert attributes to strong attributes with nil value
+        attributes.index_with { nil }.merge(strong_attributes)
+      end
+    end
+
+    include GLCommand::Validatable
+
+    attr_reader :context
+
+    def initialize(context = nil)
+      @context = context
+    end
+
+    def perform_call(args)
+      raise_for_invalid_args!(**args)
+      call_with_callbacks
+      raise_unless_chained_or_skipped if self.class.chain? # defined in GLCommand::Chainable
+      context.failure? ? handle_failure : context
+    rescue StandardError => e
+      handle_failure(e)
+    end
+
+    def stop_and_fail!(passed_error = nil, no_notify: false)
+      # manually setting instance_variable because @no_notify shouldn't be updated in commands
+      # (e.g. context shouldn't have an attr_writer)
+      context.instance_variable_set(:@no_notify, no_notify)
+      context.error = passed_error
+
+      raise context.no_notifiable_error_to_raise # See comment in #handle_failure
+    end
+
+    # define a rollback method if you want to have actions for rolling back
+    # it is called in handle_failure
+    def rollback; end
+
+    # Ensure that call is overridden in subclass
+    def call
+      raise 'You must define the `call` instance method on your GLCommand'
+    end
+
+    private
+
+    # rubocop:disable Metrics/AbcSize
+    def handle_failure(e = nil)
+      context.error ||= e
+
+      call_rollbacks
+
+      # Don't call GLExceptionNotifier if:
+      # - already notified
+      # - raise_errors: true (because raising error will call sentry)
+      # - context.no_notify?
+      unless @notified || context.raise_errors? || context.no_notify?
+        GLExceptionNotifier.call(context.error)
+        @notified = true
+      end
+
+      return context unless context.raise_errors?
+
+      # NOTE: this is tricksy. Exception#cause stores the previous error that was raised.
+      # If we are in no_notify, raise CommandNoNotifyError first
+      # Then raise the original error (so that the error is just the original error, with a #cause)
+      # context.no_notify? checks error #cause - if it's CommandNoNotifyError, the context is no_notify
+      # This is so validation errors in chainables don't call GLExceptionNotifier
+      raise context.no_notifiable_error_to_raise
+    rescue GLCommand::CommandNoNotifyError
+      raise context.error # makes CommandNoNotifyError the cause
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    # rubocop:disable Metrics/AbcSize
+    def call_with_callbacks
+      GLExceptionNotifier.breadcrumbs(data: { context: context.inspect }, message: self.class.to_s)
+      validate_validatable! # defined in GLCommand::Validatable
+
+      # This is the where the call actually happens
+      assign_returns(call)
+    rescue StandardError => e
+      handler = self.class.error_handlers[e.class]
+      handler ? send(handler, e) : raise(e)
+    end
+
+    def assign_returns(returned)
+      return if returned.is_a?(context.class) # prevent looping assignment
+      # Naive assign of the return. Only assigns if not already assigned, and if a single item
+      # Could be made to accept a hash instead and assign based on that...
+      return unless self.class.returns.count == 1 && context.returns[self.class.returns.first].nil?
+
+      context.assign_parameters(self.class.returns.first => returned)
+    end
+    # rubocop:enable Metrics/AbcSize
+
+    def call_rollbacks
+      return if defined?(@rolled_back) # Not sure this is required
+
+      @rolled_back = true
+
+      chain_rollback if self.class.chain? # defined in GLCommand::Chainable
+      rollback
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def raise_for_invalid_args!(**args)
+      missing = (self.class.requires || {}).keys - args.keys
+      raise ArgumentError, "missing #{error_keys_str(missing)}" if missing.any?
+
+      unknown = args.keys - self.class.arguments - DEFAULT_OPTS.keys
+      raise ArgumentError, "unknown #{error_keys_str(unknown)}" if unknown.any?
+
+      # strong_attributes type checking
+      self.class.requires.merge(self.class.allows).each do |arg, type|
+        next if type.nil? || args[arg].is_a?(type)
+        # 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}"
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    def error_keys_str(keys)
+      "keyword#{keys.count > 1 ? 's' : ''}: #{keys.map { |k| ":#{k}" }.join(', ')}"
+    end
+  end
+end

data/lib/gl_command/chainable.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module GLCommand
+  class Chainable < GLCommand::Callable
+    UNCHAINED_MESSAGE = '#chain method not called in GLCommand::Chainable #call. ' \
+                        "The #call method *must* include 'chain(args)' or 'super' " \
+                        'for chaining to take place!'
+
+    class << self
+      def chain?
+        true
+      end
+
+      def chain(*commands)
+        @commands = commands.flatten
+      end
+
+      def commands
+        @commands || []
+      end
+
+      def chain_arguments_and_returns(*)
+        (chain_arguments + chain_returns).uniq.zip([]).to_h
+      end
+
+      def chain_arguments
+        @chain_arguments ||= commands.map(&:arguments).flatten.uniq
+      end
+
+      def chain_returns
+        @chain_returns ||= commands.map(&:returns).flatten.uniq
+      end
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+    def chain(args)
+      return if @chain_skipped
+
+      @chain_called = true
+      context.assign_parameters(**args)
+
+      commands.map do |command|
+        cargs = context.chain_arguments_and_returns.slice(*command.arguments)
+                       .merge(context.opts_hash)
+
+        result = command.call(**cargs)
+        context.assign_parameters(skip_unknown_parameters: true, **result.returns)
+
+        if result.success?
+          context.called << command
+        else
+          @notified = true # chained command already notified
+          errors.merge!(result.errors)
+          stop_and_fail!(result.error, no_notify: result.no_notify?)
+          break
+        end
+      end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    def commands
+      self.class.commands
+    end
+
+    def chain_rollback
+      context.called.reverse_each do |command|
+        chain_params = context.chain_arguments_and_returns
+                              .slice(*command.arguments_and_returns)
+
+        command.new(command.build_context(**chain_params)).rollback
+      end
+    end
+
+    def call(**args)
+      chain(args)
+    end
+
+    def skip_chain
+      @chain_skipped = true
+    end
+
+    private
+
+    def raise_unless_chained_or_skipped
+      return if @chain_called || @chain_skipped
+
+      raise UNCHAINED_MESSAGE
+    end
+  end
+end

data/lib/gl_command/chainable_context.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module GLCommand
+  class ChainableContext < GLCommand::Context
+    def self.reserved_words
+      %i[callable called failure no_notify raise_errors] + instance_methods
+    end
+
+    # Called at the end of GLCommand::Context initialize
+    def initialize_chain_context(**arguments_and_returns)
+      @called = []
+      @chain_arguments_and_returns = @klass.chain_arguments_and_returns(**arguments_and_returns)
+    end
+
+    attr_accessor :called
+
+    def chain?
+      true
+    end
+
+    def to_h
+      arguments.merge(returns)
+    end
+
+    def chain_arguments_and_returns
+      @chain_arguments_and_returns.merge(to_h)
+    end
+
+    private
+
+    def inspect_values
+      super + ["called=#{called}"]
+    end
+
+    def assignable_parameters
+      @assignable_parameters ||=
+        (@klass.arguments_and_returns + @chain_arguments_and_returns.keys).uniq.freeze
+    end
+
+    # Overrides Context method, called by assign_parameters
+    def assign_parameter_val(arg, val, skip_unknown_parameters:)
+      super
+      @chain_arguments_and_returns[arg] = val if @chain_arguments_and_returns.key?(arg)
+    end
+  end
+end

data/lib/gl_command/context.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require 'English'
+# TODO: can we use forwardable instead of ActiveSupport delegate ?
+require 'active_support/core_ext/module'
+
+module GLCommand
+  class Context
+    def initialize(klass, raise_errors: false, skip_unknown_parameters: false,
+                   **arguments_and_returns)
+      @klass = klass
+      @raise_errors = raise_errors.nil? ? false : raise_errors
+      @klass.arguments_and_returns.each { |key| singleton_class.class_eval { attr_accessor key } }
+      initialize_chain_context(**arguments_and_returns) if chain?
+      assign_parameters(skip_unknown_parameters:, **arguments_and_returns)
+    end
+
+    # TODO: figure out a different place to pass skip_unknown_parameters than initialize,
+    # it doesn't make sense to include in the opts hash
+    def opts_hash
+      { raise_errors: raise_errors? }
+    end
+
+    attr_reader :klass, :error
+    attr_writer :full_error_message
+
+    delegate :errors, to: :@callable, allow_nil: true
+
+    def chain?
+      false
+    end
+
+    def returns
+      @klass.returns.index_with { |rattr| send(rattr) }
+    end
+
+    def arguments
+      @klass.arguments.index_with { |rattr| send(rattr) }
+    end
+
+    def raise_errors?
+      @raise_errors
+    end
+
+    def failure?
+      @failure || errors.present? || @full_error_message.present? || false
+    end
+
+    def success?
+      !failure?
+    end
+
+    # @no_notify is set by passing no_notify into stop_and_fail!
+    # If a command is no_notify within another command call!, inside_no_notify_error? is true
+    def no_notify?
+      @no_notify.presence || inside_no_notify_error?
+    end
+
+    def full_error_message
+      return nil if @full_error_message.blank? && error.blank?
+
+      ContextInspect.error(defined?(@full_error_message) ? @full_error_message : @error)
+    end
+
+    alias_method :successful?, :success?
+
+    def to_h
+      arguments.merge(returns)
+    end
+
+    # Set up to make errors visible when specs fail
+    def inspect
+      "<#{self.class.name} #{inspect_values.join(', ')}, class=#{klass}>"
+    end
+
+    def assign_parameters(skip_unknown_parameters: false, **arguments_and_returns)
+      arguments_and_returns.each do |arg, val|
+        assign_parameter_val(arg, val, skip_unknown_parameters:)
+      end
+    end
+
+    # This is what makes validation work
+    def assign_callable(callable)
+      @callable = callable
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+    def error=(passed_error = nil)
+      @failure = true
+
+      @error =
+        if exception?(passed_error)
+          # This catches errors within GLCommand::Context and prevents self referential error display
+          # $ERROR_INFO (aka $!), stores the last Ruby error
+          @full_error_message ||= $ERROR_INFO.to_s if $ERROR_INFO.to_s.include?('for <GLCommand::Context')
+          # If something raised ActiveRecord::RecordInvalid, assign its errors to #errors
+          merge_errors(passed_error.record.errors) if
+            passed_error.is_a?(ActiveRecord::RecordInvalid) && defined?(passed_error.record.errors)
+          # Return a new error if it's an error (rather than the class)
+          passed_error.is_a?(Class) ? passed_error.new(@full_error_message) : passed_error
+        elsif errors.present? # check for validation errors
+          # Assign ActiveRecord::RecordInvalid if validatable error
+          ActiveRecord::RecordInvalid.new(@callable)
+        else
+          @full_error_message ||= passed_error if passed_error.present?
+          GLCommand::StopAndFail.new(passed_error || @full_error_message)
+        end
+    end
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+    def no_notifiable_error_to_raise
+      if no_notify? && !inside_no_notify_error?
+        GLCommand::CommandNoNotifyError.new(full_error_message)
+      else
+        error
+      end
+    end
+
+    private
+
+    def exception?(passed_error)
+      passed_error.is_a?(Exception) ||
+        (passed_error.respond_to?(:ancestors) && passed_error.ancestors.include?(Exception))
+    end
+
+    def inside_no_notify_error?
+      @error.present? && @error.respond_to?(:cause) && @error.cause.present? &&
+        @error.cause.is_a?(GLCommand::CommandNoNotifyError)
+    end
+
+    def merge_errors(new_errors)
+      # When merging the errors, don't add duplicate errors
+      new_errors.each do |new_error|
+        errors.import(new_error) unless errors&.full_messages&.include?(new_error.full_message)
+      end
+    end
+
+    # Overridden in ChainableContext
+    def assignable_parameters
+      @klass.arguments_and_returns
+    end
+
+    # Overridden in ChainableContext
+    def assign_parameter_val(arg, val, skip_unknown_parameters:)
+      if assignable_parameters.include?(arg)
+        # if required because chain_arguments_and_returns are assignable_parameters
+        send(:"#{arg}=", val) if @klass.arguments_and_returns.include?(arg)
+      elsif !skip_unknown_parameters
+        raise ArgumentError, "Unknown argument or return attribute: '#{arg}'"
+      end
+    end
+
+    # Overridden in ChainableContext
+    def inspect_values
+      [
+        "error=#{success? ? 'nil' : full_error_message}",
+        "success=#{success?}",
+        "arguments={#{::GLCommand::ContextInspect.hash_params(arguments)}}",
+        "returns={#{::GLCommand::ContextInspect.hash_params(returns)}}"
+      ]
+    end
+  end
+end

data/lib/gl_command/context_inspect.rb

@@ -0,0 +1,44 @@
+module GLCommand
+  class ContextInspect
+    def self.error(error_obj)
+      return '' if error_obj.blank?
+
+      error_obj.is_a?(Array) ? error_obj.uniq.join(', ') : error_obj.to_s
+    end
+
+    def self.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(', ')
+    end
+
+    # Active record objects can be really big - rather than rendering the whole object, just show the ID
+    private_class_method def self.object_param_with_id(obj, key)
+      obj_id = obj.send(key)
+      id_value = obj_id.is_a?(Integer) ? obj_id : "\"#{obj_id}\""
+      "#<#{obj.class.name} #{key}=#{id_value}>"
+    end
+
+    private_class_method def self.object_param_as_sql(obj)
+      count =
+        if obj.respond_to?(:count)
+          obj.count
+        else
+          'N/A'
+        end
+      "#<#{obj.class.name} count=#{count}, sql=\"#{obj.to_sql}\">"
+    end
+  end
+end

data/lib/gl_command/validatable.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'active_model'
+
+module GLCommand
+  module Validatable
+    extend ActiveSupport::Concern
+    # In reality, validations should be in the context
+    # BUT, since we don't write context classes,
+    # we need to have everything about validations get passed
+    include ActiveModel::Validations
+
+    class_methods do
+      def i18n_scope
+        :activerecord
+      end
+    end
+
+    # This is called in Callable.perform_call (via validate_validatable!)
+    def validatable_valid?
+      context.assign_callable(self) # used by validatable
+      validate
+      errors.none?
+    end
+
+    def validate_validatable!
+      return true if validatable_valid?
+
+      stop_and_fail!(ActiveRecord::RecordInvalid.new(self), no_notify: true)
+    end
+  end
+end

data/lib/gl_command/version.rb

@@ -0,0 +1,3 @@
+module GLCommand
+  VERSION = '1.0.1'.freeze
+end

data/lib/gl_command.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require 'gl_command/context_inspect'
+require 'gl_command/context'
+require 'gl_command/chainable_context'
+require 'gl_command/callable'
+require 'gl_command/chainable'
+
+module GLCommand
+  class ArgumentTypeError < StandardError; end
+
+  class StopAndFail < StandardError; end
+
+  # NOTE: CommandNoNotifyError should not be the final error raised,
+  # It should be the #cause for the final error raised. See callable#handle_failure
+  class CommandNoNotifyError < StandardError; end
+end

metadata

@@ -0,0 +1,83 @@
+--- !ruby/object:Gem::Specification
+name: gl_command
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Give Lively
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+- !ruby/object:Gem::Dependency
+  name: gl_exception_notifier
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.2
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.0.2
+description:
+email:
+executables: []
+extensions: []
+extra_rdoc_files:
+- README.md
+files:
+- LICENSE
+- README.md
+- gl_command.gemspec
+- lib/gl_command.rb
+- lib/gl_command/callable.rb
+- lib/gl_command/chainable.rb
+- lib/gl_command/chainable_context.rb
+- lib/gl_command/context.rb
+- lib/gl_command/context_inspect.rb
+- lib/gl_command/validatable.rb
+- lib/gl_command/version.rb
+homepage: https://github.com/givelively/gl_command
+licenses:
+- Apache
+metadata:
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Give Lively Commands
+test_files: []