smash_the_state 1.2.4 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: afd9065697aa4494f7ccf324fd1322f0a44c7dd99495c772766f7b1ad63070b2
-  data.tar.gz: 7a58038b3b8f06b9d21871a5321d627224f7c56f65b3d3bbcb7d40b54af3b802
+  metadata.gz: ffbecb9f1fd850903e2f88e7576bf684f03e38d14e70c3e07e61c0db93621961
+  data.tar.gz: f259e6b012ff0bfca16320de3403967518de35e9c9b8e5d4baf53c5cd03ce6d2
 SHA512:
-  metadata.gz: 6305468c38c4f46fdfda9e38134896b405e57f425afad55bada899b0e2071659eaa005eed4e0851708765d8da36c834ac97ba3e7698cf0c2855e8f699808dd4c
-  data.tar.gz: 91cc65e7186915376b8990b2efc40093573a8dbc16039177786ba20b524a1c3b95713c9b0d0eb733cdbfe7ea66cdf22f5ce7dc22dcd61675aedb21855e005017
+  metadata.gz: 143ca4fdccc3fd34300f133dae21d70e55ceff9121523a456ad499839403901d56d086059913defe0fddc6ba612046489065d8c9160e13b189da0a6a1cfe0719
+  data.tar.gz: 2c40f91ac88831ea57b0ab44b24e4b514eea3524b5445c3cfb246dc12f1d5047731ed7620145f7a4d57478bf292fc93d540bb38916bc5c23a7e513aad83385db

data/README.md

@@ -159,6 +159,69 @@ class CreateDatabase < SmashTheState::Operation
 end
 ```
 
+## Inheritance-like Behavior
+
+Smash is a library that generally follows the functional approach and you should focus on using that approach when using it. However, there are times when sprinkling a dash of inheritance into the mix can make your life easier.
+
+When using the inheritance pattern, all validation blocks are evaluated together and are run together as one big validation step. The parent class' schema is copied to the child class. All steps are copied to the child class, but individual steps may be overridden using `override_step`. Overridden steps are run in the same step index in which they were originally defined in the parent sequence.
+
+``` ruby
+class CreateOperation < SmashTheState::Operation
+  schema do
+    attribute :version, :string
+    attribute :name,    :string
+  end
+
+  validate do
+    validates_presence_of :name
+  end
+
+  step :download_image do |state|
+    GenericImage.download(name)
+  end
+
+  step :create do |state|
+    Deployment.create(state.to_hash)
+  end
+
+  step :set_up_billing do |deployment|
+    Billing.charge_for_deployment(deployment)
+
+    deployment
+  end
+end
+
+class RestoreOperation < CreateOperation
+  # we get the parent class' schema for free when we inherit. if you want to extend the
+  # schema in child classes, I recommend breaking out your schema into modules
+
+  # the validation of CreateOperation will be evaluated at the same time as this following
+  # block. in other words, not only will :name have to be present, but for restoration,
+  # the name has to be the name of a known source image
+  validate do
+    validate :source_image_exists
+
+    def source_image_exists
+      unless SourceImage.exist?(name)
+        add_error(:name, "is not a restorable image")
+      end
+    end
+  end
+
+  # steps from the parent class are copied over in order. you can override specific steps
+  # in the child class
+
+  # ...download_image runs
+
+  override_step :create do |state|
+    # we're going to diverge from create by "restoring" an image rather than "creating" an image
+    Deployment.restore(state.to_hash)
+  end
+
+  # ... set_up_billing runs
+end
+```
+
 ## Representation
 
 Let's say you want to represent the state of the operation, wrapped in a class that defines some `as_*` and `to_*` methods. You can do this with a `represent` step.

data/lib/smash_the_state/operation/dry_run.rb

@@ -13,7 +13,7 @@ module SmashTheState
           referenced_steps = wet_sequence.steps_for_name(step_name)
 
           if block
-            dry_sequence.add_step(step_name, side_effect_free: true, &block)
+            add_dry_run_step(step_name, &block)
             return
           end
 
@@ -27,11 +27,17 @@ module SmashTheState
             # we're gonna copy the implementation verbatim but add a new step marked as
             # side-effect-free, because if the step was added to the dry run sequence it
             # must be assumed to be side-effect-free
-            dry_sequence.add_step(
-              step_name,
-              side_effect_free: true,
-              &referenced_step.implementation
-            )
+            add_dry_run_step(step_name, &referenced_step.implementation)
+          end
+        end
+
+        private
+
+        def add_dry_run_step(step_name, &block)
+          if step_name == :validate
+            dry_sequence.add_validation_step(&block)
+          else
+            dry_sequence.add_step(step_name, side_effect_free: true, &block)
           end
         end
       end

data/lib/smash_the_state/operation/sequence.rb

@@ -1,6 +1,9 @@
 module SmashTheState
   class Operation
     class Sequence
+      class BadOverride < StandardError; end
+      class StepConflict < StandardError; end
+
       attr_accessor :middleware_class_block
       attr_reader :steps, :run_options
 
@@ -42,14 +45,39 @@ module SmashTheState
       end
 
       def add_step(step_name, options = {}, &block)
-        # mulitple validation steps are okay but otherwise step names need to be unique
-        if step_name != :validate && !steps_for_name(step_name).empty?
-          raise "an operation step named #{step_name.inspect} already exists"
+        # steps need to be unique
+        unless steps_for_name(step_name).empty?
+          raise(
+            StepConflict,
+            "an operation step named #{step_name.inspect} already exists"
+          )
         end
 
         @steps << Step.new(step_name, options, &block)
       end
 
+      def add_validation_step(options = {}, &block)
+        step = steps_for_name(:validate).first ||
+               SmashTheState::Operation::ValidationStep.new(options)
+
+        step.add_implementation(&block)
+        @steps |= [step]
+      end
+
+      def override_step(step_name, options = {}, &block)
+        step = steps_for_name(step_name).first
+
+        if step.nil?
+          raise(
+            BadOverride,
+            "overriding step #{step_name.inspect} failed because it does " \
+            "not exist"
+          )
+        end
+
+        @steps[@steps.index(step)] = Step.new(step_name, options, &block)
+      end
+
       # returns steps named the specified name. it's generally bad form to have mulitple
       # steps with the same name, but it can happen in some reasonable cases (the most
       # common being :validate)
@@ -95,14 +123,18 @@ module SmashTheState
         original_state = state.dup
         current_step = nil
 
-        steps_to_run.reduce(state) do |memo, step|
-          current_step = step
+        steps_to_run.reduce(state) do |memo, s|
+          current_step = s
 
           # we're gonna pass the state from the previous step into the implementation as
           # 'memo', but for convenience, we'll also always pass the original state into
           # the implementation as 'original_state' so that no matter what you can get to
           # your original input
-          step.implementation.call(memo, original_state, run_options)
+          if s.name == :validate
+            s.validate!(memo)
+          else
+            s.implementation.call(memo, original_state, run_options)
+          end
         end
       rescue Operation::State::Invalid => e
         e.state

data/lib/smash_the_state/operation/state.rb

@@ -48,6 +48,12 @@ module SmashTheState
           end
         end
 
+        def extend_validation_directives_block(state, &block)
+          state.tap do |s|
+            s.class_eval(&block)
+          end
+        end
+
         # for non-ActiveModel states we will just evaluate the block as a validator
         def eval_custom_validator_block(state, original_state = nil)
           yield(state, original_state)

data/lib/smash_the_state/operation/step.rb

@@ -16,6 +16,10 @@ module SmashTheState
       def side_effect_free?
         options[:side_effect_free] == true
       end
+
+      def dup
+        super
+      end
     end
   end
 end

data/lib/smash_the_state/operation/validation_step.rb

@@ -0,0 +1,47 @@
+module SmashTheState
+  class Operation
+    class ValidationStep < Step
+      attr_accessor :implementations
+
+      def initialize(options = {})
+        @name            = :validate
+        @implementations = []
+        @options         = {
+          side_effect_free: true
+        }.merge(options)
+      end
+
+      def add_implementation(&block)
+        tap do
+          @implementations << block
+        end
+      end
+
+      def implementation
+        blocks = @implementations
+
+        proc do
+          # self here should be a state
+          blocks.reduce(self) do |memo, i|
+            memo.class_eval(&i)
+          end
+        end
+      end
+
+      def validate!(state)
+        state.tap do
+          SmashTheState::Operation::State.
+            eval_validation_directives_block(state, &implementation)
+        end
+      end
+
+      def dup
+        # it's not enough to duplicate the step, we should also duplicate our
+        # implementations. otherwise the list of implementations will be shared
+        super.tap do |s|
+          s.implementations = s.implementations.dup
+        end
+      end
+    end
+  end
+end

data/lib/smash_the_state/operation.rb

@@ -1,6 +1,7 @@
 require_relative 'operation/error'
 require_relative 'operation/sequence'
 require_relative 'operation/step'
+require_relative 'operation/validation_step'
 require_relative 'operation/state'
 require_relative 'operation/dry_run'
 require_relative 'operation/state_type'
@@ -38,6 +39,10 @@ module SmashTheState
         sequence.add_step(step_name, options, &block)
       end
 
+      def override_step(step_name, options = {}, &block)
+        sequence.override_step(step_name, options, &block)
+      end
+
       def error(*steps, &block)
         steps.each do |step_name|
           sequence.add_error_handler_for_step(step_name, &block)
@@ -65,12 +70,12 @@ module SmashTheState
         sequence.add_middleware_step(step_name, options)
       end
 
-      def validate(&block)
+      def validate(options = {}, &block)
         # when we add a validation step, all proceeding steps must not produce
         # side-effects (subsequent steps are case-by-case)
         sequence.mark_as_side_effect_free!
-        step :validate, side_effect_free: true do |state|
-          Operation::State.eval_validation_directives_block(state, &block)
+        sequence.add_validation_step(options) do |state|
+          Operation::State.extend_validation_directives_block(state, &block)
         end
       end
 
@@ -78,7 +83,7 @@ module SmashTheState
         # when we add a validation step, all proceeding steps must not produce
         # side-effects (subsequent steps are case-by-case)
         sequence.mark_as_side_effect_free!
-        step :validate, side_effect_free: true do |state, original_state|
+        step :custom_validation do |state, original_state|
           Operation::State.eval_custom_validator_block(state, original_state, &block)
         end
       end
@@ -107,5 +112,16 @@ module SmashTheState
         sequence_to_run.call(state || params)
       end
     end
+
+    def self.inherited(child_class)
+      # all steps from the parent first need to be cloned
+      new_steps = sequence.steps.map(&:dup)
+
+      # and then we add them to the child's empty sequence
+      child_class.sequence.steps.concat(new_steps)
+
+      # also copy the state class over
+      child_class.instance_variable_set(:@state_class, state_class && state_class.dup)
+    end
   end
 end

data/lib/smash_the_state/version.rb

@@ -1,3 +1,3 @@
 module SmashTheState
-  VERSION = "1.2.4".freeze
+  VERSION = "1.3.0".freeze
 end

data/spec/unit/operation/sequence_spec.rb

@@ -137,6 +137,63 @@ describe SmashTheState::Operation::Sequence do
     end
   end
 
+  describe "#override_step" do
+    let!(:instance) { subject.new }
+
+    before do
+      instance.add_step :one do |state|
+        state << :one
+      end
+
+      instance.add_step :two do |state|
+        state << :two
+      end
+
+      instance.add_step :three do |state|
+        state << :three
+      end
+    end
+
+    context "when no step by the given name exists" do
+      it "raises an exception" do
+        begin
+          instance.override_step :four do
+          end
+
+          raise "should not reach this"
+        rescue SmashTheState::Operation::Sequence::BadOverride => e
+          expect(
+            e.to_s
+          ).to eq("overriding step :four failed because it does not exist")
+        end
+      end
+    end
+
+    context "with a pre-existing step by that name" do
+      it "replaces the step in the position in which it originally appeared" do
+        instance.override_step :two do |state|
+          state << :pants
+        end
+
+        expect(instance.call([])).to eq(%i[one pants three])
+      end
+    end
+  end
+
+  describe "#add_validation_step" do
+    let!(:instance) { subject.new }
+    let!(:implementations) { 3.times.map { -> {} } }
+
+    before do
+      implementations.each { |i| instance.add_validation_step(&i) }
+    end
+
+    it "adds all the validation implementations to the validate step" do
+      validate_step = instance.steps_for_name(:validate).first
+      expect(validate_step.implementations).to eq(implementations)
+    end
+  end
+
   describe "#middleware_class" do
     let!(:instance) { subject.new }
 

data/spec/unit/operation_spec.rb

@@ -103,6 +103,94 @@ describe SmashTheState::Operation do
     end
   end
 
+  describe "self#override_step" do
+    let!(:step_name) { :override_me }
+    let!(:step_options) { { some: :option } }
+    let!(:implementation) do
+      proc do
+        :success
+      end
+    end
+    let!(:token_result) { double }
+
+    it "delegates to the sequence implementation of :override_step" do
+      expect(
+        klass.sequence
+      ).to receive(:override_step).with(
+        step_name,
+        step_options,
+        &implementation
+      ).and_return(token_result)
+
+      expect(klass.override_step(step_name, step_options, &implementation)).to eq(token_result)
+    end
+  end
+
+  describe "inheritance" do
+    let!(:parent) do
+      Class.new(SmashTheState::Operation).tap do |k|
+        k.class_eval do
+          schema do
+            attribute :countup, :string
+          end
+
+          validate do
+            validates_presence_of :countup
+          end
+
+          step :one do |state|
+            state.countup += "one"
+            state
+          end
+
+          step :two do |state|
+            state.countup += "two"
+            state
+          end
+        end
+      end
+    end
+
+    let!(:child) do
+      Class.new(parent).tap do |k|
+        k.class_eval do
+          override_step :two do |state|
+            state.countup += "oneandahalf"
+            state
+          end
+
+          validate do
+            validates_length_of :countup, maximum: 5
+          end
+
+          step :three do |state|
+            state.countup += "three"
+            state
+          end
+        end
+      end
+    end
+
+    it "duplicates steps from the parent operation, allows overrides" do
+      expect(parent.sequence.steps.length).to eq(3)
+      expect(child.sequence.steps.length).to eq(4)
+      expect(child.call(countup: "zero").countup).to eq("zerooneoneandahalfthree")
+    end
+
+    it "duplicates the state class from the parent operation" do
+      expect(child.state_class).to_not eq(parent.state_class)
+      expect(child.state_class.attributes_registry).to eq(countup: [:string, {}])
+    end
+
+    it "merges the validation blocks" do
+      too_large = child.call(countup: "thisistoolarge")
+      expect(too_large.errors[:countup]).to eq(["is too long (maximum is 5 characters)"])
+
+      too_large = child.call(countup: "")
+      expect(too_large.errors[:countup]).to eq(["can't be blank"])
+    end
+  end
+
   describe "self#dry_run_sequence" do
     context "with a custom dry run sequence block" do
       before do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: smash_the_state
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.3.0
 platform: ruby
 authors:
 - Dan Connor
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-13 00:00:00.000000000 Z
+date: 2019-08-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: active_model_attributes
@@ -57,6 +57,7 @@ files:
 - lib/smash_the_state/operation/state.rb
 - lib/smash_the_state/operation/state_type.rb
 - lib/smash_the_state/operation/step.rb
+- lib/smash_the_state/operation/validation_step.rb
 - lib/smash_the_state/version.rb
 - spec/unit/operation/definition_spec.rb
 - spec/unit/operation/sequence_spec.rb
@@ -82,7 +83,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubyforge_project: 
+rubygems_version: 2.7.7
 signing_key: 
 specification_version: 4
 summary: A useful utility for transforming state that provides step sequencing, middleware,