draft_approve 0.1.0

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "draft_approve"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/draft_approve.gemspec

@@ -0,0 +1,56 @@
+
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'draft_approve/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'draft_approve'
+  spec.version       = DraftApprove::VERSION
+  spec.authors       = ['Andrew Sibley']
+  spec.email         = ['andrew.s@38degrees.org.uk']
+  spec.license       = 'MIT'
+  spec.homepage      = 'https://github.com/38dgs/draft_approve'
+  spec.summary       = %q{Save drafts of ActiveRecord models & approve them to apply the changes.}
+  spec.description   = %q{
+    All draft data is saved in a separate table, so no need to worry about
+    existing code / SQL accidentally finding non-approved data. Supports draft
+    changes to existing objects, and creating new objects as drafts. Supports
+    'draft transactions' which may update / create many objects, and must be
+    approved / rejected in their entirety.
+  }
+
+  # Prevent pushing this gem to RubyGems.org. To allow pushes either set the 'allowed_push_host'
+  # to allow pushing to a single host or delete this section to allow pushing to any host.
+  # if spec.respond_to?(:metadata)
+  #   spec.metadata['allowed_push_host'] = "TODO: Set to 'http://mygemserver.com'"
+  #
+  #   spec.metadata['homepage_uri'] = spec.homepage
+  #   spec.metadata['source_code_uri'] = 'https://github.com/38dgs/draft_approve'
+  #   spec.metadata['changelog_uri'] = 'https://github.com/38dgs/draft_approve/CHANGELOG.md'
+  # else
+  #   raise 'RubyGems 2.0 or newer is required to protect against public gem pushes.'
+  # end
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "activerecord", "~> 5.2"
+
+  spec.add_development_dependency "bundler", "~> 1.17"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "database_cleaner", "~> 1.7"
+  spec.add_development_dependency "sqlite3", "~> 1.3"
+  spec.add_development_dependency "pg", ">= 0.18", "< 2.0"
+  spec.add_development_dependency "factory_bot", "~> 4.11"
+  spec.add_development_dependency "codecov", "~> 0.1"
+  spec.add_development_dependency "appraisal", "~> 2.2"
+  spec.add_development_dependency "pry", "~> 0.12"
+  spec.add_development_dependency "yard", "~> 0.9.18"
+end

data/lib/draft_approve.rb

@@ -0,0 +1,5 @@
+require 'active_record'
+
+require 'draft_approve/draftable/base_class_methods'
+
+ActiveRecord::Base.extend DraftApprove::Draftable::BaseClassMethods

data/lib/draft_approve/draft_changes_proxy.rb

@@ -0,0 +1,242 @@
+module DraftApprove
+
+  # Mixin wrapper for +Draft+ and +acts_as_draftable+ objects, such that both
+  # have a consistent API to get current and new values within the context of
+  # a specific +DraftTransaction+.
+  #
+  # References to other objects returned by methods from this class are also
+  # wrapped in a +DraftChangesProxy+, meaning it is relatively easy to chain
+  # and navigate complex association trees within the context of a
+  # +DraftTransaction+.
+  #
+  # This can be useful, for example, to display all changes that will occur
+  # on an object, including changes to all it's associated 'child' objects.
+  #
+  # It is often most convenient to use the
+  # +DraftTransaction#draft_proxy_for+ method to construct a
+  # +DraftApproveProxy+ instance. This will ensure the correct implementation
+  # of +DraftApproveProxy+ is used.
+  #
+  # Classes which include this module must implement the instance methods
+  # +new_value+, +association_changed?+, +associations_added+,
+  # +associations_updated+, +associations_removed+.
+  #
+  # @see DraftTransaction#draft_proxy_for
+  module DraftChangesProxy
+    attr_reader :draft, :draftable, :draftable_class, :draft_transaction
+
+    # Creates a new DraftChangesProxy
+    #
+    # @param object [Object] the +Draft+ object, or the instance of an
+    #   +acts_as_draftable+ class, which is being proxied to get changes
+    # @param transaction [DraftTransaction] the +DraftTransaction+ within
+    #   which to look for changes. If +object+ is a +Draft+, this parameter
+    #   is optional and if not provided will use the +DraftTransaction+
+    #   associated with the given +Draft+. If +object+ is not a +Draft+,
+    #   this parameter is required.
+    def initialize(object, transaction = nil)
+      if object.blank?
+        raise(ArgumentError, "object is required")
+      end
+
+      if object.new_record?
+        raise(ArgumentError, "object #{object} must already be persisted")
+      end
+
+      if object.is_a? Draft
+        if transaction.present? && object.draft_transaction != transaction
+          raise(ArgumentError, "draft_transaction for #{object} is inconsistent with given draft_transaction #{transaction}")
+        end
+
+        # Construct DraftableProxy from a draft
+        # Note that @draftable may be nil (if this is a CREATE draft)
+        @draft = object
+        @draftable = (object.draftable.present? && object.draftable.persisted?) ? object.draftable : nil
+        @draftable_class = Object.const_get(object.draftable_type)
+        @draft_transaction = object.draft_transaction
+      else
+        if transaction.blank?
+          raise(ArgumentError, "draft_transaction is required when object is a draftable")
+        end
+
+        # Construct DraftableProxy from a draftable
+        # Note that @draft may be nil (if the draftable has no changes within the scope of this transaction)
+        @draft = transaction.drafts.find_by(draftable: object)
+        @draftable = object
+        @draftable_class = object.class
+        @draft_transaction = transaction
+      end
+    end
+
+    # @return [Boolean] +true+ if this +Draft+ is to create a new record,
+    #   +false+ otherwise
+    def create?
+      @draft.present? && @draft.create?
+    end
+
+    # @return [Boolean] +true+ if this +Draft+ is to delete an existing
+    #   record, +false+ otherwise
+    def delete?
+      @draft.present? && @draft.delete?
+    end
+
+    # Whether or not the proxied +Draft+ or draftable object has any
+    # changes.
+    #
+    # Note, this method only considers changes to attributes and changes
+    # to any +belongs_to+ references. Any added / changed / deleted
+    # +has_many+ or +has_one+ associations are not considered.
+    #
+    # @return [Boolean] whether or not the proxied object has changes
+    def changed?
+      if @draft.blank?
+        false # No draft for this object, so nothing changed
+      else
+        @draft.draft_changes.present?
+      end
+    end
+
+    # List of attributes on the proxied +Draft+ or draftable object which
+    # have changes.
+    #
+    # Note, this method only considers changes to attributes and changes
+    # to any +belongs_to+ references. Any added / changed / deleted
+    # +has_many+ or +has_one+ associations are not considered.
+    #
+    # @return [Array<String>] array of the attributes which have changed on
+    #   the proxied object
+    def changed
+      if @draft.blank?
+        [] # No draft for this object, so no attributes have changed
+      else
+        @draft.draft_changes.keys
+      end
+    end
+
+    # Hash of changes on the proxied +Draft+ or draftable object which
+    # have changes.
+    #
+    # Note, this method only considers changes to attributes and changes
+    # to any +belongs_to+ references. Any added / changed / deleted
+    # +has_many+ or +has_one+ associations are not considered.
+    #
+    # @return [Hash<String, Array>] hash of the changes on the proxied
+    #   object, eg. <tt>{ "name" => ["old_name", "new_name"] }</tt>
+    def changes
+      @changes_memo ||= begin  # Memoize result
+        if @draft.blank?
+          {} # No draft for this object, so no attributes have changed
+        else
+          @draft.draft_changes.each_with_object({}) do |(k,v), new_hash|
+            new_hash[k] = [current_value(k), new_value(k)]
+          end
+        end
+      end
+    end
+
+    # The currently persisted value for the given attribute on the proxied
+    # +Draft+ or draftable object.
+    #
+    # @param attribute_name [String]
+    #
+    # @return [Object, nil] the old value of the given attribute, or +nil+
+    #   if there was no previous value
+    def current_value(attribute_name)
+      # Create hash with default block for auto-memoization
+      @current_values_memo ||= Hash.new do |hash, attribute|
+        hash[attribute] = begin
+          if @draftable.present?
+            # Current value is what's on the draftable object
+            draft_proxy_for(@draftable.public_send(attribute))
+          else
+            # No draftable exists, so this must be a CREATE draft, meaning
+            # there's no 'old' value...
+            association = @draftable_class.reflect_on_association(attribute)
+            if (association.blank? || association.belongs_to? || association.has_one?)
+              nil # Not an association, or links to a single object
+            else
+              []  # Is a has_many association
+            end
+          end
+        end
+      end
+
+      # Get memoized value, or calculate and store it
+      @current_values_memo[attribute_name.to_s]
+    end
+
+    # The new, drafted value for the given attribute on the proxied +Draft+
+    # or draftable object. If no changes have been drafted for the given
+    # attribute, then returns the currently persisted value for the
+    # attribute.
+    #
+    # @param attribute_name [String]
+    #
+    # @return [Object, nil] the new value of the given attribute, or the
+    #   currently persisted value if there are no draft changes for the
+    #   attribute
+    def new_value(attribute_name)
+      raise "#new_value has not been implemented in #{self.class.name}"
+    end
+
+    # Whether any changes will occur to the given association of the proxied
+    # +Draft+ or draftable object.
+    #
+    # @param association_name [String]
+    #
+    # @return [Boolean] +true+ if any objects will be added to this
+    #   association, removed from this association, or existing associations
+    #   changed in any way. +false+ otherwise.
+    def association_changed?(association_name)
+      raise "#association_changed? has not been implemented in #{self.class.name}"
+    end
+
+    # All associated objects which will be added to the given association of
+    # the proxied +Draft+ or draftable object.
+    #
+    # @param association_name [String]
+    #
+    # @return [Array<DraftChangesProxy>] DraftChangesProxy objects for each
+    #   object which will be added to the given association
+    def associations_added(association_name)
+      raise "#associations_added has not been implemented in #{self.class.name}"
+    end
+
+    # All associated objects which have been updated, but remain
+    # the proxied +Draft+ or draftable object.
+    #
+    # @param association_name [String]
+    #
+    # @return [Array<DraftChangesProxy>] DraftChangesProxy objects for each
+    #   object which will be added to the given association
+    def associations_updated(association_name)
+      raise "#associations_updated has not been implemented in #{self.class.name}"
+    end
+
+    # All associated objects which will be removed from the given
+    # association of the proxied +Draft+ or draftable object.
+    #
+    # @param association_name [String]
+    #
+    # @return [Array<DraftChangesProxy>] DraftChangesProxy objects for each
+    #   object which will be removed from the given association
+    def associations_removed(association_name)
+      raise "#associations_removed has not been implemented in #{self.class.name}"
+    end
+
+    # Returns a string representing the current value of the proxied object.
+    #
+    # @return [String] the +to_s+ of the current value of the proxied object
+    #   (ie. the value before any changes would take effect). If there is no
+    #   current value (ie. this is a proxy for a new draft) then simply
+    #   returns "New <classname>".
+    def current_to_s
+      if @draftable.present?
+        return "#{@draftable.to_s} <#{@draftable_class} ##{@draftable.id}>"
+      else
+        # No current draftable
+        return "New #{@draftable_class}"
+      end
+    end
+  end
+end

data/lib/draft_approve/draftable/base_class_methods.rb

@@ -0,0 +1,33 @@
+require 'draft_approve/draftable/class_methods'
+require 'draft_approve/draftable/instance_methods'
+require 'draft_approve/models/draft'
+
+module DraftApprove
+  module Draftable
+
+    # Methods automatically added to +ActiveRecord::Base+ when including the
+    # DraftApprove gem
+    module BaseClassMethods
+
+      # Allows the object to be used as a draftable, adding the
+      # +DraftApprove::Draftable+ instance and class methods to the object.
+      #
+      # @param options [Hash] optional configuration, currently unused
+      #
+      # @example
+      #   class Person < ActiveRecord::Base
+      #     acts_as_draftable
+      #   end
+      #
+      # @see DraftApprove::Draftable::InstanceMethods
+      # @see DraftApprove::Draftable::ClassMethods
+      def acts_as_draftable(options={})
+        include DraftApprove::Draftable::InstanceMethods
+        extend DraftApprove::Draftable::ClassMethods
+
+        has_many :drafts, as: :draftable
+        has_one :draft_pending_approval, -> { pending_approval }, class_name: "Draft", as: :draftable, inverse_of: :draftable
+      end
+    end
+  end
+end

data/lib/draft_approve/draftable/class_methods.rb

@@ -0,0 +1,119 @@
+require 'draft_approve/transaction'
+
+module DraftApprove
+  module Draftable
+
+    # Class methods automatically added to an ActiveRecord model when
+    # +acts_as_draftable+ is called
+    module ClassMethods
+      ##### Basic DraftApprove class methods #####
+
+      # Starts a new +DraftTransaction+ to group together a number of draft
+      # changes that must be approved and applied together.
+      #
+      # @yield the block which creates a group of draft changes that must be
+      #   approved and applied together
+      # @param created_by [String] the person or process responsible for
+      #   creating the draft changes in this transaction
+      # @param extra_data [Hash] any extra metadata to be associated with
+      #   these draft changes
+      #
+      # @return [DraftTransaction, nil] the +DraftTransaction+ which was
+      #   created, or +nil+ if no draft changes were saved within the given
+      #   block (ie. if approving the +DraftTransaction+ would be a
+      #   'no-operation')
+      def draft_transaction(created_by: nil, extra_data: nil)
+        DraftApprove::Transaction.in_new_draft_transaction(created_by: created_by, extra_data: extra_data) do
+          yield
+        end
+      end
+
+      ##### Additional convenience DraftApprove class methods #####
+
+      # Creates a new object with the given attributes, and saves the new object
+      # as a draft.
+      #
+      # @param attributes [Hash] a hash of attribute names to attribute values,
+      #   like the hash expected by the ActiveRecord +create+ / +create!+
+      #   methods
+      #
+      # @return [Draft] the resulting +Draft+ record (*not* the created
+      #   draftable object)
+      def draft_create!(attributes)
+        self.new(attributes).draft_save!
+      end
+
+      # Finds an object with the given attributes. If none found, creates a new
+      # object with the given attributes, executes the given block, and saves
+      # the new object as a draft.
+      #
+      # @param attributes [Hash] a hash of attribute names to attribute values,
+      #   like the hash expected by the ActiveRecord +find_or_create_by+ method
+      # @yield [instance] a block which sets additional attributes on the newly
+      #   created object instance if no existing instance is found
+      #
+      # @return [Object] the draftable object which was found or created
+      #   (*not* the +Draft+ object which may have been saved)
+      #
+      # @example
+      #   # Find a person by their name. If no person found, create a person
+      #   # with that name, and also set their birth date.
+      #   Person.find_or_create_draft_by!(name: 'My Name') do |p|
+      #     p.birth_date = '1980-01-01'
+      #   end
+      def find_or_create_draft_by!(attributes)
+        instance = self.find_by(attributes)
+
+        if instance.blank?
+          instance = self.new(attributes)
+
+          # Only execute the block if this is a new record
+          yield(instance) if block_given?
+        end
+
+        instance.draft_save!
+        return instance
+      end
+
+      # Finds an object with the given attributes and draft update it with the
+      # given block, or draft create a new object.
+      #
+      # If an object is found matching the given attributes, the given block
+      # is applied to this object and the updates are saved as a draft.
+      #
+      # If no object is found matching the given attributes, a new object is
+      # initialised with the given attributes, and the given block is applied to
+      # this new object before it is saved as a draft.
+      #
+      # @param attributes [Hash] a hash of attribute names to attribute values,
+      #   like the hash expected by the ActiveRecord +find_or_create_by+ method
+      # @yield [instance] a block which makes changes to the object instance
+      #   which was found or created using the given attributes hash
+      #
+      # @return [Object] the draftable object which was found and updated, or
+      #   the draftable object which was created (*not* the +Draft+ object
+      #   which may have been saved)
+      #
+      # @example
+      #   # Find a person by their name, and draft update their birth date,
+      #   # OR draft create a person with the given name and birth date.
+      #   Person.find_and_draft_update_or_create_draft_by!(name: 'My Name') do |p|
+      #     p.birth_date = '1980-01-01'
+      #   end
+      def find_and_draft_update_or_create_draft_by!(attributes)
+        instance = self.find_by(attributes)
+
+        if instance.blank?
+          instance = self.new(attributes)
+        end
+
+        # Whether or not this is a new record, execute the block to update
+        # additional, non-find_by attributes
+        yield(instance) if block_given?
+
+        instance.draft_save!
+        return instance
+      end
+    end
+  end
+end