attribute-trackable 0.0.2.pre.rc1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec7576bd556386c9eb3e9e21a3f6f1872dd36240cbd0f9625d7478e26dade44c
+  data.tar.gz: 1e88eb34d0624aa3394c80743b4ed4700831cd237a4f7bedfe668a7f1ecf0b4a
+SHA512:
+  metadata.gz: c1ad9d08eb731530e2ebbe3adc257d397d82b1dd2ad4cccf2ef0948a645f8700e211abc407caa95fbc46201d2b5eb4886b8122bd65c7fe8a9dc11e7473e1d51a
+  data.tar.gz: 6c239fbd602b9ffd2b6688f660f5a51b8c49cefb115ee4f118ce88fac8102abade074e783e16aa7dab7ea40d0e4188c177ccf07df41e8da78510e444f46f44ae

data/lib/trackable.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+# Defines tracking logic to an internal field and/or to an external resource using a hash DSL
+#
+# Interface: `object.trackable_update(params.merge(unlink_fields: [:teeth]))`
+# Reserved params:
+#   unlink_fields: Array - array of symbolized field names to unlink from tracked their fields
+#   unlink_child_fields: Array - array of symbolized field names to unlink child fields
+#
+# The modified external resources can be found in: `object.trackable_dependents`
+#
+# DSL Structure:
+# {
+#   species: {
+#     linked_attributes: {
+#       coat: {
+#         if: ->(animal) { animal.tracking_coat },
+#         tracking_bool: :tracking_coat,
+#         track: ->(animal) { TrackableAnimal.track_coat_to_species(animal) }
+#       },
+#       teeth: {
+#         tracking_bool: :tracking_teeth,
+#         track: ->(a) { TrackableAnimal.track_teeth_to_species(animal) }
+#       }
+#     },
+#     linked_child_attributes: {
+#       species: {
+#         children: :children,
+#         tracking_bool: :tracking_species,
+#         track: ->(animal, child) { TrackableAnimal.track_species_to_parent(animal, child) }
+#       }
+#     }
+#   },
+#   teeth: {
+#     linked_attributes: {
+#       diet: {
+#         tracking_bool: :tracking_diet,
+#         track: ->(animal) { TrackableAnimal.track_diet_to_teeth(animal) }
+#       }
+#     }
+#   }
+# }
+#
+# DSL Params:
+#  1. tracking_bool: boolean value used to determine whether or not a field is linked
+#  2. if: proc used to determine whether or not to track the linked field
+#  3. children: symbol to send to object to obtain it's children
+#  4. track: proc used to translate tracked field into its linked dependent
+#       - when attributes are linked to base object, param passed to proc is (object)
+#       - when attributes are linked to parent object, params passed to proc are (object, child)
+module Trackable
+  require 'trackable/errors'
+  require 'trackable/helpers/circular_dependency'
+  require 'trackable/helpers/verify_options'
+  require 'active_support/concern'
+  require 'active_support/core_ext/class/attribute'
+  require 'active_support/core_ext/object'
+  extend ::ActiveSupport::Concern
+
+  included do
+    class_attribute :trackable_data, :trackable_defaults
+
+    attr_accessor :trackable_dependents
+  end
+
+  module ClassMethods
+    def tracking(structure)
+      self.trackable_data = structure
+    end
+
+    def set_trackable_defaults(children: nil, linked_bool: nil)
+      self.trackable_defaults = {
+        linked_bool: linked_bool,
+        children: children
+      }
+    end
+
+    def propagate_changes(opts)
+      add_trackable_dependency(opts)
+    end
+
+    def propagate_changes_to_children(opts)
+      add_trackable_dependency(opts.merge(child: true))
+    end
+
+    def add_trackable_dependency(opts)
+      self.trackable_data ||= {}
+      self_or_child_attributes = opts[:child] ? :linked_child_attributes : :linked_attributes
+      new_option = { track: opts[:use] }
+      new_option[:if] = opts[:if] if opts[:if]
+      new_option[:tracking_bool] = opts[:linked_bool] if opts[:linked_bool]
+      new_option[:skip_assignment] = opts[:skip_assignment] if opts[:skip_assignment]
+      new_option[:children] = opts[:children] if opts[:children] && opts[:child]
+      linked_attrs = trackable_data.dig(opts[:from], self_or_child_attributes) || {}
+      trackable_data[opts[:from]] = (trackable_data.dig(opts[:from]) || {})
+                                    .merge(self_or_child_attributes => linked_attrs
+          .merge(opts[:to] => new_option))
+    end
+
+    def explain_trackable_attribute(attribute)
+      linked_to = []
+      linked_to_parent = []
+
+      trackable_data.each do |key, value|
+        linked_to << key if value[:linked_attributes] && attribute.in?(value[:linked_attributes])
+        if value[:linked_child_attributes] && attribute.in?(value[:linked_child_attributes])
+          linked_to_parent << key
+        end
+      end
+
+      {
+        inherits: linked_to,
+        inherits_from_parent: linked_to_parent,
+        inherited_by: trackable_data[attribute][:linked_child_attributes],
+        inherited_by_to_children: trackable_data[attribute][:linked_child_attributes]
+      }
+    end
+
+    def verify_trackable_options!
+      Trackable::Helpers::VerifyOptions.new(trackable_data, trackable_defaults).verify!
+    end
+  end
+
+  def self.prepended(base)
+    class << base
+      prepend ClassMethods
+    end
+  end
+
+  define_method(:trackable_update) do |attrs|
+    unlink_fields = Array(attrs.delete(:unlink_fields))
+    unlink_child_fields = Array(attrs.delete(:unlink_child_fields))
+
+    attrs.each do |key, value|
+      # set the value using the default setter method
+      public_send("#{key.to_sym}=", value)
+      next unless trackable_data.key? key
+
+      changes_to_propagate = trackable_data[key][:linked_attributes]
+      changes_to_propagate_to_children = trackable_data[key][:linked_child_attributes]
+
+      changes_to_propagate&.each do |attribute, options|
+        next unless should_track?(linked_bool(attribute, options), options[:if])
+
+        new_value = options[:track].is_a?(Symbol) ? public_send(options[:track]) : options[:track].call(self)
+        trackable_update("#{attribute}": new_value) unless options[:skip_assignment]
+      end
+
+      self.trackable_dependents ||= {} # build hash of mutated child objects keyed by :id
+      changes_to_propagate_to_children&.each do |attribute, options|
+        unlink_child = attribute.in? unlink_child_fields
+        update_dependents(attribute, options, unlink_child)
+      end
+    end
+
+    # Make the dependency tree order agnostic by overriding attributes that are explicitly set in params
+    overriding_attrs = attrs.keys & all_linked_attributes
+    override(attrs.slice(*overriding_attrs), unlink_fields)
+  end
+
+  define_method(:trackable_link_child) do |child|
+    self.trackable_dependents ||= {}
+    all_linked_attributes(:linked_child_attributes).each do |attribute|
+      update_dependents(
+        attribute,
+        trackable_data.dig(attribute, :linked_child_attributes, attribute),
+        false,
+        child
+      )
+    end
+  end
+
+  define_method(:trackable_unlink) do |attribute|
+    unlinked = trackable_data.each_value.map do |options|
+      opts = options.dig(:linked_attributes, attribute) || options.dig(:linked_child_attributes, attribute)
+      linked_bool(attribute, opts) if opts
+    end.compact
+
+    if unlinked.empty?
+      raise Trackable::Errors::InvalidUnlink, "Must include tracking_bool for #{attribute} to override"
+    end
+
+    unlinked.each { |tracking_bool| public_send("#{tracking_bool}=", false) }
+  end
+
+  private
+
+  def linked_bool(attribute, options)
+    return false unless options
+
+    defaults = trackable_defaults&.dig(:linked_bool)
+    if options[:tracking_bool].is_a?(Symbol)
+      options[:tracking_bool]
+    elsif defaults && options[:tracking_bool]
+      [defaults[:prefix], attribute, defaults[:sufix]]
+        .compact.join('_').to_sym
+    end
+  end
+
+  def should_track?(bool, func, child = nil)
+    bool_result = bool.nil? || (child || self).send(bool.to_sym)
+    proc_params = func&.parameters&.map(&:last) || []
+    parameters = { root: self, child: child }
+
+    func.present? ? bool_result && func.call(**parameters.slice(*proc_params)) : bool_result
+  end
+
+  # Overrides an attribute when it is passed as a parameter to trackable_update
+  def override(attrs, unlink_fields)
+    attrs.each do |attribute, value|
+      unlink_field = attribute.in? unlink_fields
+      public_send("#{attribute}=", value)
+
+      if trackable_data.dig(attribute, :linked_child_attributes)
+        update_dependents(
+          attribute,
+          trackable_data.dig(attribute, :linked_child_attributes, attribute),
+          unlink_field
+        )
+      end
+
+      next unless unlink_field
+
+      trackable_unlink(attribute)
+    end
+  end
+
+  def update_dependents(attribute, options, unlink_field, override_child = nil)
+    dependents = Array(override_child || public_send((options[:children] || trackable_defaults[:children])))
+    dependents.each do |dependent|
+      dependent.trackable_unlink(attribute) if unlink_field
+      next unless options && should_track?(linked_bool(attribute, options), options[:if], dependent)
+
+      current_dep = trackable_dependents[dependent.id] || dependent
+
+      new_value = options[:track].is_a?(Symbol) ? public_send(options[:track]) : options[:track].call(self, current_dep)
+      current_dep.trackable_update("#{attribute}": new_value) unless options[:skip_assignment]
+
+      trackable_dependents[current_dep.id] = current_dep
+    end
+  end
+
+  def all_linked_attributes(from = :linked_attributes)
+    trackable_data.map { |_k, v| v[from]&.keys }.flatten.compact
+  end
+end

data/lib/trackable/errors.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Trackable
+  module Errors
+    class TrackableError < StandardError; end
+    class CyclicDependency < TrackableError; end
+    class InvalidOptions < TrackableError; end
+
+    class TrackableRuntimeError < RuntimeError; end
+    class InvalidUnlink < TrackableRuntimeError; end
+  end
+end

data/lib/trackable/helpers/circular_dependency.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+# Example graph
+# {
+#   'a': ['b', 'd'],
+#   'b': ['c', 'e'],
+#   'c': ['d', 'a']
+# }
+# TODO: refactor to use sets
+module Trackable
+  module Helpers
+    class CircularDependency
+      attr_accessor :cyclic_dependencies, :graph, :traversed_verticies,
+                    :verticies, :work_graph
+
+      def initialize(graph = {})
+        @graph = graph
+        @work_graph = @graph.dup
+        @verticies = @graph.keys
+        @traversed_verticies = []
+        @cyclic_dependencies = []
+      end
+
+      def check_graph
+        verticies.each do |vertex|
+          check_node(vertex) if work_graph[vertex]
+        end
+        cyclic_dependencies
+      end
+
+      def check_node(node)
+        traversed_verticies << node
+
+        work_graph[node].each do |child|
+          # There is no point in further investigating this node
+          # since it has been removed
+          if work_graph[child].nil?
+            # We have followed this tree to its end
+            self.traversed_verticies = [] if graph[child].nil?
+            next
+          end
+
+          repeated_index = repeated_index(child)
+          if repeated_index # Found a cycle so bust the stack and continue on
+            new_dep = (traversed_verticies[repeated_index..-1] +
+              [child, traversed_verticies[repeated_index]])
+            self.traversed_verticies = []
+            cyclic_dependencies << new_dep
+            next
+          end
+
+          check_node(child)
+        end
+
+        # Finished checking all cycles for this node so don't repeat it
+        work_graph.delete(node)
+      end
+
+      def repeated_index(child)
+        traversed_verticies.index { |v| v.in?(work_graph[child]) }
+      end
+    end
+  end
+end

data/lib/trackable/helpers/verify_options.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Trackable
+  module Helpers
+    class VerifyOptions
+      attr_accessor :options, :defaults
+
+      def initialize(options, defaults)
+        self.options = options
+        self.defaults = defaults.to_h
+      end
+
+      def verify!
+        verify_trackable_opts(options)
+        verify_cyclical_dependencies(options)
+      end
+
+      private
+
+      def verify_trackable_opts(options)
+        options.each_value do |opts|
+          if no_attribute_dependencies?(opts)
+            raise Trackable::Errors::InvalidOptions,
+                  'Missing tracking attributes'
+          end
+
+          verify_attributes(opts)
+          verify_attributes(opts, true)
+        end
+      end
+
+      def verify_attributes(opts, child = false)
+        opt_key = child ? :linked_attributes : :linked_child_attributes
+        opts[opt_key]&.each_value do |opt_value|
+          verify_track_attribute(opt_value, child)
+        end
+      end
+
+      def verify_track_attribute(opt_value, child = false)
+        if child && opt_value[:children].blank? && defaults[:children]&.blank?
+          raise Trackable::Errors::InvalidOptions, 'Missing children attribute'
+        end
+
+        return unless opt_value[:track].blank?
+
+        raise Trackable::Errors::InvalidOptions, 'Missing track attribute'
+      end
+
+      def verify_cyclical_dependencies(options)
+        graph = build_graph(options)
+        cycles = Trackable::Helpers::CircularDependency.new(graph).check_graph
+        return if cycles.empty?
+
+        raise Trackable::Errors::CyclicDependency,
+              "Cyclic dependency found: #{cycles.map { |c| c.join(' -> ') }}"
+      end
+
+      def build_graph(options)
+        options.each_with_object({}) do |(k, v), h|
+          h[k] = v[:linked_attributes]&.keys
+        end
+      end
+
+      def no_attribute_dependencies?(opts)
+        opts[:linked_attributes].nil? && opts[:linked_child_attributes].nil?
+      end
+    end
+  end
+end

data/lib/trackable/version.rb

@@ -0,0 +1,3 @@
+module Trackable
+  VERSION = '0.0.2-rc1'.freeze
+end

metadata

@@ -0,0 +1,146 @@
+--- !ruby/object:Gem::Specification
+name: attribute-trackable
+version: !ruby/object:Gem::Version
+  version: 0.0.2.pre.rc1
+platform: ruby
+authors:
+- Adam David
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2019-11-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry-nav
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- adam.david@bugcrowd.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/trackable.rb
+- lib/trackable/errors.rb
+- lib/trackable/helpers/circular_dependency.rb
+- lib/trackable/helpers/verify_options.rb
+- lib/trackable/version.rb
+homepage: https://github.com/adamrdavid/trackable
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">"
+    - !ruby/object:Gem::Version
+      version: 1.3.1
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: A flowdown wrapper for attribute dependencies
+test_files: []