1066/operation callbacks (#1108)

* feat: Add operation callbacks

* refactor: 🔥 Remove debugging log

* docs: Remove dev clause from spec

Author: franciscoGPS

spec/avram/operations/operation_callbacks_spec.cr

@@ -37,6 +37,64 @@ private class OperationWithCallbacks < Avram::Operation
   end
 end
 
+class OperationWithIf < Avram::Operation
+  include TestableOperation
+  attribute number : Int32 = 1
+
+  before_run :update_number, if: :should_run_callback?
+
+  def run
+    number.value
+  end
+
+  private def update_number
+    mark_callback("before_run_update_number")
+    number.value = 10
+  end
+
+  private def should_run_callback?
+    true
+  end
+end
+
+class OperationWithUnless < Avram::Operation
+  include TestableOperation
+  attribute number : Int32 = 1
+
+  before_run :update_number, unless: :skip_callback?
+
+  def run
+    number.value
+  end
+
+  private def update_number
+    mark_callback("before_run_update_number")
+    number.value = 20
+  end
+
+  private def skip_callback?
+    true
+  end
+end
+
+class OperationWithBlockUnless < Avram::Operation
+  include TestableOperation
+  attribute number : Int32 = 1
+
+  before_run(unless: :skip_callback?) do
+    mark_callback("before_run_block")
+    number.value = 30
+  end
+
+  def run
+    number.value
+  end
+
+  private def skip_callback?
+    false
+  end
+end
+
 describe "Avram::Operation callbacks" do
   it "runs before_run and after_run callbacks" do
     OperationWithCallbacks.run do |operation, value|
@@ -49,4 +107,25 @@ describe "Avram::Operation callbacks" do
       operation.callbacks_that_ran.should contain "after_run_in_a_block with 4"
     end
   end
+
+  it "runs before_run with if condition" do
+    OperationWithIf.run do |operation, value|
+      operation.callbacks_that_ran.should contain "before_run_update_number"
+      value.should eq 10
+    end
+  end
+
+  it "does not run before_run with unless condition" do
+    OperationWithUnless.run do |operation, value|
+      operation.callbacks_that_ran.should_not contain "before_run_update_number"
+      value.should eq 1
+    end
+  end
+
+  it "runs before_run block with unless condition" do
+    OperationWithBlockUnless.run do |operation, value|
+      operation.callbacks_that_ran.should contain "before_run_block"
+      value.should eq 30
+    end
+  end
 end

src/avram/callbacks/callbacks.cr

@@ -1,35 +1,75 @@
 module Avram::Callbacks
   # Run the given method before `run` is called on an `Operation`.
   #
-  # ```
-  # before_run :validate_inputs
+  # Examples:
+  #
+  #   before_run :validate_inputs
+  #
+  #   before_run :validate_inputs, if: :should_validate?
+  #   before_run :validate_inputs, unless: :skip_validation?
   #
   # private def validate_inputs
   #   validate_required data
   # end
-  # ```
-  macro before_run(method_name)
-    before_run do
+  macro before_run(method_name, if _if = nil, unless _unless = nil)
+    {% unless _if.is_a?(SymbolLiteral) || _if.is_a?(NilLiteral) %}
+      conditional_error_for_inline_callbacks(:before_run, {{ method_name }}, :if)
+    {% end %}
+    {% unless _unless.is_a?(SymbolLiteral) || _unless.is_a?(NilLiteral) %}
+      conditional_error_for_inline_callbacks(:before_run, {{ method_name }}, :unless)
+    {% end %}
+    before_run(if: {{ _if }}, unless: {{ _unless }}) do
       {{ method_name.id }}
     end
   end
 
   # Run the given block before `run` is called on an `Operation`.
   #
+  # This runs before `run` is invoked on the operation.
+  # You can set defaults, validate, or perform any other setup necessary before running the operation.
+  #
+  # Optionally you can pass an `if` or `unless` argument which allows you to
+  # run this conditionally. The symbol should reference a method you've defined
+  # that returns a truthy/falsey value.
+  #
   # ```
-  # before_run do
+  # before_run(unless: :skip_callback?) do
   #   validate_required data
   # end
+  #
+  # private def skip_callback?
+  #   false
+  # end
   # ```
-  macro before_run
+  macro before_run(if _if = nil, unless _unless = nil)
+    {% if _if != nil && _unless != nil %}
+      {% raise "Your before_run callbacks should only specify `if` or `unless`, but not both." %}
+    {% end %}
+    {% unless _if.is_a?(SymbolLiteral) || _if.is_a?(NilLiteral) %}
+      conditional_error_for_block_callbacks(:before_run, :if)
+    {% end %}
+    {% unless _unless.is_a?(SymbolLiteral) || _unless.is_a?(NilLiteral) %}
+      conditional_error_for_block_callbacks(:before_run, :unless)
+    {% end %}
+
     def before_run : Nil
       {% if @type.methods.map(&.name).includes?(:before_run.id) %}
         previous_def
       {% else %}
         super
       {% end %}
 
-      {{ yield }}
+      {% if _if %}
+      if {{ _if.id }}
+        {{ yield }}
+      end
+      {% elsif _unless %}
+      unless {{ _unless.id }}
+        {{ yield }}
+      end
+      {% else %}
+        {{ yield }}
+      {% end %}
     end
   end