smash_the_state 1.2.4

data/lib/smash_the_state.rb

@@ -0,0 +1,7 @@
+module SmashTheState
+end
+
+require 'active_model'
+require 'active_model_attributes'
+
+require_relative 'smash_the_state/operation'

data/lib/smash_the_state/matchers.rb

@@ -0,0 +1,56 @@
+module SmashTheState
+  module Matchers
+    RSpec::Matchers.define :continue_from do |original|
+      match do |continuation|
+        expect(
+          continuation.
+            sequence.
+            steps.
+            slice(0, original.sequence.steps.length)
+        ).to eq(original.sequence.steps)
+      end
+    end
+
+    # expect(Some::Operation).to represent_with Thing::Representer
+    RSpec::Matchers.define :represent_with do |representer|
+      match do |operation|
+        expect(representer).to receive(:represent).and_return "representation"
+        expect(operation.call.as_json).to eq "representation"
+      end
+
+      # Magic: Calling this matcher with an operation works the way you'd expect. Calling it with
+      # a block turns the block into a proc and stuffs it into |operation|. Since operations and
+      # procs both respond to .call in the same way, `operation.call.as_json` does the same thing
+      # in both cases.
+      def supports_block_expectations?
+        true
+      end
+    end
+
+    # expect(Some::Operation).to represent_collection_with Thing::Representer
+    RSpec::Matchers.define :represent_collection_with do |representer|
+      match do |operation|
+        expect(representer).to receive(:represent).and_return "representation"
+        expect(operation.call.as_json).to eq "representation"
+      end
+
+      def supports_block_expectations?
+        true
+      end
+    end
+
+    # expect(Some::Operation).to represent_collection :things, with: Thing::Representer
+    RSpec::Matchers.define :represent_collection do |key, options|
+      match do |operation|
+        representer = options[:with]
+
+        expect(representer).to receive(:represent).and_return "representation"
+        expect(operation.call.as_json).to eq key.to_s => "representation"
+      end
+
+      def supports_block_expectations?
+        true
+      end
+    end
+  end
+end

data/lib/smash_the_state/operation.rb

@@ -0,0 +1,111 @@
+require_relative 'operation/error'
+require_relative 'operation/sequence'
+require_relative 'operation/step'
+require_relative 'operation/state'
+require_relative 'operation/dry_run'
+require_relative 'operation/state_type'
+require_relative 'operation/definition'
+
+module SmashTheState
+  class Operation
+    extend DryRun
+
+    class << self
+      attr_reader :state_class
+
+      # Runs the operation, creating the state based on the provided params,
+      # passing it from step to step and returning the last step.
+      def call(params = {})
+        run_sequence(sequence, params)
+      end
+      alias run call
+
+      # inheritance doesn't work with class attr_readers, this method is provided to
+      # bootstrap an operation as a continuation of a "prelude" operation
+      def continues_from(prelude)
+        @state_class = prelude.state_class && prelude.state_class.dup
+        sequence.steps.concat prelude.sequence.steps
+
+        # also make the dry run sequence continue
+        dry_run_sequence.steps.concat(prelude.dry_run_sequence.steps)
+      end
+
+      def schema(&block)
+        @state_class = Operation::State.build(&block)
+      end
+
+      def step(step_name, options = {}, &block)
+        sequence.add_step(step_name, options, &block)
+      end
+
+      def error(*steps, &block)
+        steps.each do |step_name|
+          sequence.add_error_handler_for_step(step_name, &block)
+        end
+      end
+
+      def policy(klass, method_name)
+        step :policy do |state, original_state|
+          state.tap do
+            policy_instance = klass.new(original_state.current_user, state)
+
+            # pass the policy instance back in the NotAuthorized exception so
+            # that the state, the user, and the policy can be inspected
+            policy_instance.send(method_name) ||
+              raise(NotAuthorized, policy_instance)
+          end
+        end
+      end
+
+      def middleware_class(&block)
+        sequence.middleware_class_block = block
+      end
+
+      def middleware_step(step_name, options = {})
+        sequence.add_middleware_step(step_name, options)
+      end
+
+      def validate(&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)
+        end
+      end
+
+      def custom_validation(&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, original_state|
+          Operation::State.eval_custom_validator_block(state, original_state, &block)
+        end
+      end
+
+      def represent(representer)
+        step :represent, side_effect_free: true do |state|
+          representer.represent(state)
+        end
+      end
+
+      def sequence
+        @sequence ||= Operation::Sequence.new
+      end
+
+      private
+
+      def error!(state)
+        raise Error, state
+      end
+
+      def run_sequence(sequence_to_run, params = {})
+        # state class can be nil if the schema is never defined. that's ok. in that
+        # situation it's up to the first step to produce the original state and we'll pass
+        # the params themselves in
+        state = state_class && state_class.new(params)
+        sequence_to_run.call(state || params)
+      end
+    end
+  end
+end

data/lib/smash_the_state/operation/definition.rb

@@ -0,0 +1,37 @@
+module SmashTheState
+  class Operation
+    # fundamentally a definition is a re-usable schema block with a name
+    class Definition < SmashTheState::Operation::State
+      class << self
+        attr_reader :schema_block
+
+        # the "name" is available as a reference
+        def ref
+          @definition_name
+        end
+
+        # whenever this module is evaluated as a string, use its name
+        alias to_s ref
+
+        private
+
+        # assigns a name to the definition
+        def definition(definition_name)
+          @definition_name = definition_name
+        end
+
+        def schema(name = nil, options = {}, &block)
+          # if a name is provided, it's an inline schema or a reference to another
+          # definition
+          return super(name, options, &block) unless name.nil?
+
+          # called with no name, we infer that this is the definition's own schema. the
+          # provided schema block is both stored for re-use and also evaluated in the
+          # definition module itself
+          @schema_block = block
+          class_eval(&block)
+        end
+      end
+    end
+  end
+end

data/lib/smash_the_state/operation/dry_run.rb

@@ -0,0 +1,75 @@
+module SmashTheState
+  class Operation
+    module DryRun
+      class Builder
+        attr_reader :wet_sequence, :dry_sequence
+
+        def initialize(wet_sequence)
+          @wet_sequence = wet_sequence
+          @dry_sequence = Operation::Sequence.new
+        end
+
+        def step(step_name, &block)
+          referenced_steps = wet_sequence.steps_for_name(step_name)
+
+          if block
+            dry_sequence.add_step(step_name, side_effect_free: true, &block)
+            return
+          end
+
+          if referenced_steps.empty?
+            raise "dry run sequence referred to unknown step " \
+                  "#{step_name.inspect}. make sure to define " \
+                  "your dry run sequence last, after all your steps are defined"
+          end
+
+          referenced_steps.each do |referenced_step|
+            # 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
+            )
+          end
+        end
+      end
+
+      # dry runs are meant to produce the same types of output as a normal call/run,
+      # except they should not produce any side-effects (writing to a database, etc)
+      def dry_run(params = {})
+        # if an valid dry run sequence has been specified, use it. otherwise run the main
+        # sequence in "side-effect free mode" (filtering out steps that cause
+        # side-effects)
+        seq = if dry_run_sequence?
+                dry_run_sequence
+              else
+                sequence.side_effect_free
+              end
+
+        run_sequence(seq, params)
+      end
+      alias dry_call dry_run
+
+      def dry_run_sequence(&block)
+        # to keep the operation code cleaner, we will delegate dry run sequence building
+        # to another module (allows us to have a method named :step without having to make
+        # the operation :step method super complicated)
+        @dry_run_builder ||= DryRun::Builder.new(sequence)
+
+        # if a block is given, we want to evaluate it with the builder
+        @dry_run_builder.instance_eval(&block) if block_given?
+
+        # the builder will produce a side-effect-free sequence for us
+        @dry_run_builder.dry_sequence
+      end
+
+      # a valid dry run sequence should have at least one step. if there isn't at least
+      # one step, the dry run sequence is basically a no-op
+      def dry_run_sequence?
+        !dry_run_sequence.steps.empty?
+      end
+    end
+  end
+end

data/lib/smash_the_state/operation/error.rb

@@ -0,0 +1,19 @@
+module SmashTheState
+  class Operation
+    class Error < StandardError
+      attr_reader :state
+
+      def initialize(state)
+        @state = state
+      end
+    end
+
+    class NotAuthorized < StandardError
+      attr_reader :policy_instance
+
+      def initialize(policy_instance)
+        @policy_instance = policy_instance
+      end
+    end
+  end
+end

data/lib/smash_the_state/operation/sequence.rb

@@ -0,0 +1,116 @@
+module SmashTheState
+  class Operation
+    class Sequence
+      attr_accessor :middleware_class_block
+      attr_reader :steps, :run_options
+
+      def initialize
+        @steps = []
+        @run_options = { dry: false }
+      end
+
+      def call(state)
+        run_steps(@steps, state)
+      end
+
+      def slice(start, count)
+        # slice should return a copy of the object being sliced
+        dup.tap do |seq|
+          # we're going to slice the steps, which is really the meat of a sequence, but we
+          # need to evaluate in the copy context so that we can swap out the steps for a
+          # new copy of steps (because note - even though we've copied the sequence
+          # already, the steps of the copy still refer to the steps of the original!)
+          seq.instance_eval do
+            @steps = seq.steps.slice(start, count)
+          end
+        end
+      end
+
+      # return a copy without the steps that produce side-effects
+      def side_effect_free
+        dup.tap do |seq|
+          seq.run_options[:dry] = true
+          seq.instance_eval do
+            @steps = seq.steps.select(&:side_effect_free?)
+          end
+        end
+      end
+
+      # marks all the the currently defined steps as free of side-effects
+      def mark_as_side_effect_free!
+        steps.each { |s| s.options[:side_effect_free] = true }
+      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"
+        end
+
+        @steps << 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)
+      def steps_for_name(name)
+        steps.select { |s| s.name == name }
+      end
+
+      def add_error_handler_for_step(step_name, &block)
+        step = @steps.find { |s| s.name == step_name }
+
+        # should we raise an exception instead?
+        return if step.nil?
+
+        step.error_handler = block
+      end
+
+      # rubocop:disable Lint/ShadowedException
+      def middleware_class(state, original_state = nil)
+        middleware_class_block.call(state, original_state).constantize
+      rescue NameError, NoMethodError
+        nil
+      end
+      # rubocop:enable Lint/ShadowedException
+
+      def add_middleware_step(step_name, options = {})
+        step = Operation::Step.new step_name, options do |state, original_state|
+          if middleware_class(state, original_state).nil?
+            # no-op
+            state
+          else
+            middleware_class(state, original_state).send(step_name, state, original_state)
+          end
+        end
+
+        @steps << step
+      end
+
+      private
+
+      def run_steps(steps_to_run, state)
+        # retain a copy of the original state so that we can refer to it for posterity as
+        # the operation state gets mutated over time
+        original_state = state.dup
+        current_step = nil
+
+        steps_to_run.reduce(state) do |memo, step|
+          current_step = step
+
+          # 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)
+        end
+      rescue Operation::State::Invalid => e
+        e.state
+      rescue Operation::Error => e
+        raise e if current_step.error_handler.nil?
+
+        current_step.error_handler.call(e.state, original_state)
+      end
+    end
+  end
+end

data/lib/smash_the_state/operation/state.rb

@@ -0,0 +1,104 @@
+require "active_support/core_ext/hash/indifferent_access"
+
+module SmashTheState
+  class Operation
+    class State
+      include ActiveModel::Model
+      include ActiveModelAttributes
+
+      class Invalid < StandardError
+        attr_reader :state
+
+        def initialize(state)
+          @state = state
+        end
+      end
+
+      class << self
+        attr_accessor :representer
+
+        def build(&block)
+          Class.new(self).tap do |k|
+            k.class_eval(&block)
+          end
+        end
+
+        # defines a nested schema inside of a state. can be nested arbitrarily
+        # deep. schemas may be described inline via a block *or* can be a reference to a
+        # definition
+        def schema(key, options = {}, &block)
+          attribute key,
+                    :state_for_smashing,
+                    options.merge(
+                      # allow for schemas to be provided inline *or* as a reference to a
+                      # type definition
+                      schema: attribute_options_to_ref_block(options) || block
+                    )
+        end
+
+        # for ActiveModel states we will treat the block as a collection of ActiveModel
+        # validator directives
+        def eval_validation_directives_block(state, &block)
+          state.tap do |s|
+            # each validate block should be a "fresh start" and not interfere with the
+            # previous blocks
+            s.class.clear_validators!
+            s.class_eval(&block)
+            s.validate || invalid!(s)
+          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)
+          invalid!(state) if state.errors.present?
+          state
+        end
+
+        def model_name
+          ActiveModel::Name.new(self, nil, "State")
+        end
+
+        private
+
+        # if a reference to a definition is provided, use the reference schema block
+        def attribute_options_to_ref_block(options)
+          options[:ref] && options[:ref].schema_block
+        end
+
+        def invalid!(state)
+          raise Invalid, state
+        end
+      end
+
+      attr_accessor :current_user
+
+      def initialize(attributes = {})
+        @current_user = attributes.delete(:current_user) ||
+                        attributes.delete("current_user")
+
+        indifferent_whitelisted_attributes = self.
+                                               class.
+                                               attributes_registry.
+                                               with_indifferent_access
+
+        # ActiveModel will raise an ActiveRecord::UnknownAttributeError if any unexpected
+        # attributes are passed in. since operations are meant to replace strong
+        # parameters and enforce against arbitrary mass assignment, we should filter the
+        # params to inclide only the whitelisted attributes.
+        # TODO: what about nested attributes?
+        whitelisted_attributes = attributes.select do |attribute|
+          indifferent_whitelisted_attributes.key? attribute
+        end
+
+        super(whitelisted_attributes)
+      end
+
+      def as_json
+        Hash[self.class.attributes_registry.keys.map do |key|
+          [key, send(key).as_json]
+        end]
+      end
+    end
+  end
+end