statefully 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 97acdf9e907dd51ad5227ef53828030d0943d35d
-  data.tar.gz: 3d9564c5fa59479e584e38c94ebdf504e1e1894d
+  metadata.gz: 4f804d2bf7a4e93cce2e444f0bf61ecbf93fcc40
+  data.tar.gz: 9fdf666b486671a6a45cab5e5c4bb885ffcb2baf
 SHA512:
-  metadata.gz: 94467d76d84d115d674c84db44022a6c4e76d81e417b1ca48eb613734802fd80c420f4a79832aa248f1622e9260c26d1bdfb8c72f9c73f078a14df230cde96b5
-  data.tar.gz: 732e6d9e831787099ae318d706a0c6d95280ea8ee06217e1bc0b3f9a30bd058d150b8053a972ffd631a626e3e75937cac403a5fc9e14609f0413f870e6da9894
+  metadata.gz: d4d379b599bf47f4cfb48ec9a5d7450be76e07f8debacc0c1eb18d603fe0a846d2103b69e8cc53951350e12ed17a8ea9bac4a030728365113001b1007a0c6ac2
+  data.tar.gz: 9ed5595f56f566543fdc0bd69d71ef917ba674d2abf49502670c3d92d1fe021780c3304d8056ca87da4681443bf112491d3b2138b098ce16eec16533ebc7a9e8

data/lib/statefully.rb

@@ -1,3 +1,5 @@
+require 'statefully/change'
 require 'statefully/diff'
+require 'statefully/errors'
 require 'statefully/inspect'
 require 'statefully/state'

data/lib/statefully/change.rb

@@ -0,0 +1,52 @@
+module Statefully
+  # Change is a tuple of current and previous value of a field in a {Diff}.
+  class Change
+    # Returns the current {State} field value
+    #
+    # @return [Object] current {State} field value
+    # @api public
+    # @example
+    #   Statefully::Change.new(current: 7, previous: 8).current
+    #   => 7
+    attr_reader :current
+
+    # Returns the previous {State} field value
+    #
+    # @return [Object] previous {State} field value
+    # @api public
+    # @example
+    #   Statefully::Change.new(current: 7, previous: 8).previous
+    #   => 8
+    attr_reader :previous
+
+    # Constructor for the {Change} object
+    # @param current [Object] current {State} field value
+    # @param previous [Object] previous {State} field value
+    # @api public
+    # @example
+    #   Statefully::Change.new(current: 7, previous: 8)
+    #   => #<Statefully::Change current=7, previous=8>
+    def initialize(current:, previous:)
+      @current = current
+      @previous = previous
+    end
+
+    # Internal-only method used to determine whether there was any change
+    # @api private
+    def none?
+      @current == @previous
+    end
+
+    # Human-readable representation of the {Change} for console inspection
+    #
+    # @return [String]
+    # @api semipublic
+    # @example
+    #   Statefully::Change.new(current: 7, previous: 8)
+    #   => #<Statefully::Change current=7, previous=8>
+    def inspect
+      "#<#{self.class.name} " \
+      "#{Inspect.from_fields(current: current, previous: previous)}>"
+    end
+  end # class Change
+end # module Statefully

data/lib/statefully/diff.rb

@@ -2,124 +2,299 @@ require 'set'
 require 'singleton'
 
 module Statefully
-  module Diff
+  # {Diff} is a difference between two neighboring instances of {State}.
+  #
+  # @abstract
+  class Diff
+    # Create is the only public interface to the Diff class
+    #
+    # @param current [Statefully::State] current state
+    # @param previous [Statefully::State] previous state
+    #
+    # @return [Statefully::Diff] Difference between states.
+    # @api public
+    # @example
+    #   previous = Statefully::State.create
+    #   current = previus.succeed(key: 'val')
+    #   Statefully::Diff.create(current, previous)
+    #   => #<Statefully::Diff::Changed added={key: "val"}>
+    #
     # This method reeks of :reek:FeatureEnvy (of current).
-    def create(current, previous)
+    def self.create(current:, previous:)
       return current.diff if current.failed? || current.finished?
-      changes = Builder.new(current, previous).build
+      changes = Builder.new(current: current, previous: previous).build
+      return Created.new(**changes).freeze if previous.none?
       changes.empty? ? Unchanged.instance : Changed.new(**changes).freeze
     end
-    module_function :create
 
-    class Changed
-      attr_reader :added, :changed
+    # Check if a {Diff} is empty
+    #
+    # An empty {Diff} means that is there are no changes in properties between
+    # current and previous {State}.
+    #
+    # @return [Boolean]
+    # @api public
+    # @example
+    #   Statefully::Diff::Unchanged.instance.empty?
+    #   => true
+    def empty?
+      true
+    end
 
-      def empty?
-        false
+    # Hash of added properties and their values
+    #
+    # @return [Hash<Symbol, Object>]
+    # @api public
+    # @example
+    #   Statefully::Diff::Unchanged.instance.added
+    #   => {}
+    def added
+      {}
+    end
+
+    # Hash of changed properties and their current and previous values
+    #
+    # @return [Hash<Symbol, Statefully::Diff::Change>]
+    # @api public
+    # @example
+    #   Statefully::Diff::Unchanged.instance.added.changed
+    #   => {}
+    def changed
+      {}
+    end
+
+    # Check if a key has been added
+    #
+    # @param key [Symbol]
+    # @return [Boolean]
+    # @api public
+    # @example
+    #   diff = Statefully::Diff::Changed.new(added: {key: 7})
+    #   diff.added?(:key)
+    #   => true
+    #   diff.added?(:other)
+    #   => false
+    def added?(key)
+      added.key?(key)
+    end
+
+    # Check if a key has been changed
+    #
+    # @param key [Symbol]
+    # @return [Boolean]
+    # @api public
+    # @example
+    #   diff = Statefully::Diff::Changed.new(
+    #     changed: {key: Statefully::Change.new(current: 7, previous: 8)},
+    #   )
+    #   diff.changed?(:key)
+    #   => true
+    #   diff.changed?(:other)
+    #   => false
+    def changed?(key)
+      changed.key?(key)
+    end
+
+    # {Changed} is a {Diff} which contains changes between two successful
+    # {State}s.
+    class Changed < Diff
+      # Hash of added properties and their values
+      #
+      # @return [Hash<Symbol, Object>]
+      # @api public
+      # @example
+      #   Statefully::Diff::Changed.new(added: {key: 7}).added
+      #   => {:key => 7}
+      attr_reader :added
+
+      # Hash of changed properties and their current and previous values
+      #
+      # @return [Hash<Symbol, Change>]
+      # @api public
+      # @example
+      #   Statefully::Diff::Changed.new(
+      #     changed: {key: Statefully::Change.new(current: 7, previous: 8)},
+      #   )
+      #   => {:key=>#<Statefully::Change current=7, previous=8>}
+      attr_reader :changed
+
+      # Constructor for {Diff::Changed}
+      #
+      # @param added [Hash<Symbol, Object>] added fields
+      # @param changed [Hash<Symbol, Change>] [changed fields]
+      # @api public
+      # @example
+      #   Statefully::Diff::Changed.new(added: {key: 7})
+      #   => #<Statefully::Diff::Changed added={key: 7}>
+      def initialize(added: {}, changed: {})
+        @added = added.freeze
+        @changed = changed.freeze
       end
 
-      def inspect
-        "#<#{self.class.name} #{inspect_details}>"
+      # Check if a {Diff} resulted from creating a {State}
+      #
+      # @return [Boolean]
+      # @api public
+      # @example
+      #   Stateful::State.created.created?
+      #   => true
+      #
+      #   Stateful::State.created.succeed.created?
+      #   => false
+      def created?
+        false
       end
 
-      def added?(key)
-        added.key?(key)
+      # Check if a {Diff} is empty
+      #
+      # An empty {Diff} means that there are no changes in properties between
+      # current and previous {State}.
+      #
+      # @return [Boolean]
+      # @api public
+      # @example
+      #   Statefully::Diff::Changed.new(added: {key: 7}).empty?
+      #   => false
+      def empty?
+        added.empty? && changed.empty?
       end
 
-      def changed?(key)
-        changed.key?(key)
+      # Human-readable representation of the {Change} for console inspection
+      #
+      # @return [String]
+      # @api semipublic
+      # @example
+      #   Statefully::Diff::Changed.new(added: {key: 7})
+      #   => #<Statefully::Diff::Changed added={key: 7}>
+      def inspect
+        details = [self.class.name]
+        details << inspect_details unless empty?
+        "#<#{details.join(' ')}>"
       end
 
       private
 
+      # Helper method to print out added and changed fields
+      # @return [String]
+      # @api private
       def inspect_details
         [inspect_added, inspect_changed].compact.join(', ')
       end
 
+      # Helper method to print out added fields
+      # @return [String]
+      # @api private
       def inspect_added
         added.empty? ? nil : "added=#{Inspect.from_hash(added)}"
       end
 
+      # Helper method to print out changed fields
+      # @return [String]
+      # @api private
       def inspect_changed
         changed.empty? ? nil : "changed=#{Inspect.from_hash(changed)}"
       end
-
-      def initialize(added:, changed:)
-        @added = added.freeze
-        @changed = changed.freeze
-      end
     end # class Changed
 
-    module NoChanges
-      def empty?
-        true
-      end
-
-      def added
-        {}
+    module SingletonInspect
+      # Human-readable representation of the {Diff} singleton
+      #
+      # @return [String]
+      # @api private
+      def inspect
+        "#<#{self.class.name}>"
       end
-
-      def changed
-        {}
+    end # module SingletonInspect
+    private_constant :SingletonInspect
+
+    # {Created} represents a difference between a null and non-null {State}.
+    class Created < Changed
+      # Check if a {Diff} resulted from creating a {State}
+      #
+      # @return [Boolean]
+      # @api public
+      # @example
+      #   Stateful::State.created.created?
+      #   => true
+      #
+      #   Stateful::State.created.succeed.created?
+      #   => false
+      def created?
+        true
       end
-    end # module NoChanges
-    private_constant :NoChanges
+    end # class Created
 
-    class Unchanged
+    # {Unchanged} represents a lack of difference between two {State}s.
+    class Unchanged < Diff
       include Singleton
-      include NoChanges
-
-      def inspect
-        "#<#{self.class.name}>"
-      end
+      include SingletonInspect
     end # class Unchanged
 
-    class Failed
-      include NoChanges
+    # {Failed} represents a difference between a succesful and failed {State}.
+    class Failed < Diff
+      # Error that caused the {State} to fail
+      #
+      # @return [StandardError]
+      # @api public
+      # @example
+      #   Statefully::Diff::Failed.new(RuntimeError.new('Boom!')).error
+      #   => #<RuntimeError: Boom!>
       attr_reader :error
 
+      # Constructor for {Diff::Failed}
+      #
+      # @param error [StandardError] error that caused the {State} to fail
+      # @api semipublic
+      # @example
+      #   Statefully::Diff::Failed.new(RuntimeError.new('Boom!'))
+      #   => #<Statefully::Diff::Failed error=#<RuntimeError: Boom!>>
       def initialize(error)
         @error = error
       end
 
+      # Human-readable representation of the {Diff::Failed}
+      #
+      # @return [String]
+      # @api semipublic
+      # @example
+      #   Statefully::Diff::Failed.new(RuntimeError.new('Boom!'))
+      #   => #<Statefully::Diff::Failed error=#<RuntimeError: Boom!>>
       def inspect
         "#<#{self.class.name} error=#{error.inspect}>"
       end
     end # class Failed
 
-    class Finished < Unchanged
+    # {Failed} represents a difference between a succesful and finished {State}.
+    class Finished < Diff
+      include Singleton
+      include SingletonInspect
     end # class Finished
 
-    class Change
-      attr_reader :current, :previous
-
-      def initialize(current, previous)
-        @current = current
-        @previous = previous
-      end
-
-      def none?
-        @current == @previous
-      end
-
-      def inspect
-        "#<#{self.class.name} " \
-        "#{Inspect.from_fields(current: current, previous: previous)}>"
-      end
-    end # class Change
-
     class Builder
-      def initialize(current, previous)
+      # Constructor for the {Builder} object
+      #
+      # @param current [State] current {State}
+      # @param previous [State] previous {State}
+      # @api private
+      def initialize(current:, previous:)
         @current = current
         @previous = previous
       end
 
+      # Build a Hash of added and changed {State} fields
+      #
+      # @return [Hash]
+      # @api private
       def build
         empty? ? {} : { added: added, changed: changed }
       end
 
       private
 
+      # List added fields
+      #
+      # @return [Hash]
+      # @api private
       def added
         @added ||=
           (current_keys - previous_keys)
@@ -127,6 +302,10 @@ module Statefully
           .to_h
       end
 
+      # List changed fields
+      #
+      # @return [Hash]
+      # @api private
       def changed
         @changed ||=
           (current_keys & previous_keys)
@@ -135,22 +314,43 @@ module Statefully
           .reject { |_, val| val.none? }
       end
 
+      # Change for individual key
+      #
+      # @param [Symbol] key name
+      #
+      # @return [Change]
+      # @api private
       def change_for(key)
-        Change.new(@current.fetch(key), @previous.fetch(key)).freeze
+        Change.new(
+          current: @current.fetch(key),
+          previous: @previous.fetch(key),
+        ).freeze
       end
 
+      # Check if the nothing has changed
+      #
+      # @return [Boolean]
+      # @api private
       def empty?
         added.empty? && changed.empty?
       end
 
+      # Return the set of keys for the current {State}
+      #
+      # @return [Set<Symbol>]
+      # @api private
       def current_keys
         Set.new(@current.keys)
       end
 
+      # Return the set of keys for previous {State}
+      #
+      # @return [Set<Symbol>]
+      # @api private
       def previous_keys
         Set.new(@previous.keys)
       end
     end # class Builder
     private_constant :Builder
-  end # module Diff
+  end # class Diff
 end # module Statefully