in_order 0.1.0

data/app/models/in_order/aux/repair.rb

@@ -0,0 +1,71 @@
+
+module InOrder
+  module Aux
+    class Repair
+      attr_accessor :dry_run, :owners, :elements
+      alias dry_run? dry_run
+
+      def initialize(_dry_run=false, dry_run: _dry_run)
+        self.dry_run = dry_run
+
+        self.owners = []
+        self.elements = []
+      end
+
+      def call
+        InOrder::Element.transaction do
+          unreferenced :owner do |type_id|
+            owners << type_id * '-'
+
+            InOrder::Element.by_owner_keys(*type_id).delete_all unless dry_run?
+          end
+
+          unlinked :subject do |element|
+            elements << element
+
+            InOrder::Remove.new(element).call unless dry_run?
+          end
+        end
+
+        return owners, elements
+      end
+
+      class << self
+        def ic
+          owners, elements = new(true).call
+
+          puts show 'Owners', owners
+          puts show 'Elements', elements
+        end
+
+        def show(name, list)
+          out = name << ' ' << list.size.to_s << "\n"
+
+          out << list.map(&:to_param) * " " << "\n"
+        end
+      end
+
+      def unlinked(name)
+        unreferenced(name).map do |type_id|
+          InOrder::Element.by_subject_keys(*type_id).first.tap do |element|
+            yield element if block_given?
+          end
+        end
+      end
+
+      def unreferenced(name)
+        linked(name).reject do |(type, id)|
+          type.constantize.where(id: id).exists?
+        end
+      end
+
+      def linked(name)
+        fields = [ :"#{name}_type", :"#{name}_id" ]
+
+        InOrder::Element.select(*fields).distinct.pluck(*fields)
+      end
+
+    end
+  end
+end
+

data/app/models/in_order/aux/sort_elements.rb

@@ -0,0 +1,32 @@
+
+module InOrder
+  module Aux
+    module SortElements
+      module_function \
+        def sort_elements(elements)
+          index = elements.size
+
+          sorted = Array.new(index)
+
+          element_id = nil
+
+          while index > 0
+            index -= 1
+
+            element = elements.find do |element|
+                        element.element_id == element_id
+                      end
+
+            if element
+              sorted[index] = element
+
+              element_id = element.id
+            end
+          end
+
+          sorted
+        end
+    end
+  end
+end
+

data/app/models/in_order/aux/var_keys.rb

@@ -0,0 +1,20 @@
+
+module InOrder
+  module Aux
+    module VarKeys
+      include GetKeys
+
+      def self.included(base)
+        base.instance_eval { attr_accessor :keys }
+      end
+ 
+      # +keys+ InOrder::Keys or an Array, used as constructor args to former
+      def initialize(*keys)
+        super()
+
+        self.keys = get_keys(keys)
+      end
+    end
+  end
+end
+

data/app/models/in_order/create.rb

@@ -0,0 +1,62 @@
+
+module InOrder
+  # Creates a list of elements for a given Owner and/or Scope,
+  # which make up the key.
+  # This list links a number of arbitrary *ActiveRecords* together,
+  # retaining the given order (sequence).
+  # Owner and Record are any ActiveRecord model (linked polymorphically).
+  # The Scope is a string with an application-dependent value.
+  # At least one of Owner and Scope must be given.
+  # If a list of elememts with the same Owner/Scope combo already exists,
+  # then the new elements will be appended to them,
+  # unless the 'append' parameter is given as *false*,
+  # in which case, they'll be prepended.
+  class Create
+    include Aux::VarKeys
+    include Aux::CreateElement
+
+    # +models+ are an Araay of ActiveRecord models to be linked
+    def call(models, append: true)
+      InOrder::Element.transaction do
+        if append
+          previous_last_element = InOrder::Element.last_element(keys)
+        else
+          previous_first_element = InOrder::Element.first_element(keys)
+        end
+
+        add_elements(models.dup).tap do |created_elements|
+          if created_elements.any?
+            if previous_first_element
+              InOrder::Element.link_elements created_elements.last,
+                                             previous_first_element
+            elsif previous_last_element
+              InOrder::Element.link_elements previous_last_element,
+                                             created_elements.first
+            end
+          end
+        end
+      end
+    end
+    alias elements call
+
+    def subjects(*args)
+      call(*args).map &:subject
+    end
+    alias records subjects
+
+    protected
+
+    def add_elements(models, created=[], element_id=nil)
+      if record = models&.pop
+        element = create_element(record, keys, element_id)
+
+        add_elements models, created, element.id
+
+        created << element
+      else
+        created
+      end
+    end
+  end
+end
+

data/app/models/in_order/element.rb

@@ -0,0 +1,119 @@
+
+module InOrder
+  # An element of a persisted linked-list 
+  class Element < ApplicationRecord
+    extend Aux::GetKeys
+
+    self.table_name_prefix = 'in_order_'
+
+    belongs_to :owner, optional: true, polymorphic: true
+
+    belongs_to :subject, polymorphic: true
+
+    belongs_to :element, optional: true
+
+    scope :by_scope, -> (scope=nil) { where scope: scope }
+
+    scope :by_owner, -> owner { where owner: owner }
+
+    scope :by_owner_keys, -> (type, id) { where owner_type: type, owner_id: id }
+
+    scope :by_subject, -> subject { where subject: subject }
+
+    scope :by_subject_keys, -> (type, id) { where subject_type: type, subject_id: id }
+
+    scope :by_keys, -> keys { by_scope(keys.scope).by_owner(keys.owner) }
+
+    scope :by_element, -> element { where element_id: element.to_param }
+
+    scope :include_all, -> { includes :subject, :owner }
+
+    scope :fetch, -> keys { by_keys(keys).include_all }
+
+    scope :null_element, -> { where element_id: nil }
+
+    validate :validate_has_key_fields_valued
+
+    alias call subject
+
+    def to_s
+      call.to_s
+    end
+
+    def as_json(*)
+      super except: %i(created_at updated_at),
+            #include: :subject,
+            methods: :value
+    end
+    def value
+      subject.as_json
+    end
+
+    def to_keys
+      Aux::Keys.new(owner, scope)
+    end
+
+    def iterator
+      Aux::ElementIterator.new(to_keys)
+    end
+
+    class << self
+      def find_with_keys(*keys)
+        keys = get_keys(keys)
+
+        by_owner_keys(*keys.owner_key.to_a).by_scope(keys.scope)
+      end
+      alias find_with_key find_with_keys
+
+      def fetch_with_keys(*keys)
+        find_with_keys(keys).include_all
+      end
+      alias fetch_with_key fetch_with_keys
+
+      def delete_elements(*keys)
+        transaction do
+          by_keys(get_keys keys).map {|element| element.destroy }
+        end
+      end
+
+      def delete_list(*keys)
+        by_keys(get_keys keys).delete_all
+      end
+
+      def first_element(*keys)
+        keyed = by_keys(get_keys keys)
+
+        if keyed.exists?
+          keyed.where.not(id: keyed.pluck(:element_id)).first
+        end
+      end
+
+      def last_element(*keys)
+        by_keys(get_keys keys).null_element.first
+      end
+
+      def for_subject(*keys)
+        poly_key = Aux::PolyKey.new(yield)
+
+        by_keys(get_keys keys).by_subject_keys(*poly_key.to_a)
+      end
+
+      def has_subject?(*keys, &block)
+        for_subject(keys, &block).exists?
+      end
+
+      def link_elements(end_of_former, beginning_of_latter)
+        end_of_former.update_attribute :element, beginning_of_latter
+      end
+    end
+
+    private
+
+    def validate_has_key_fields_valued
+      unless scope.present? or owner.present?
+        errors[:base] << "Cannot leave both scope and owner blank"
+      end
+    end
+  end
+end
+

data/app/models/in_order/fetch.rb

@@ -0,0 +1,33 @@
+
+module InOrder
+  # Returns a list of elements in order, given a key of Owner and/or Scope.
+  class Fetch
+    include Aux::VarKeys
+
+    include Aux::SortElements
+
+    def call
+      elements.map &:subject
+    end
+
+    def elements
+      sort_elements fetch
+    end
+
+    def fetch
+      InOrder::Element.fetch_with_key(keys).to_a
+    end
+
+    def repair
+      InOrder::Element.transaction do
+        fetch.each do |element|
+          if element.subject.nil?
+            Remove.new(element).call
+          end
+        end
+      end
+      self
+    end
+  end
+end
+

data/app/models/in_order/insert.rb

@@ -0,0 +1,42 @@
+
+module InOrder
+  # Puts a new element anywhere in a pre-exising list.
+  class Insert < Aux::PositionBase
+    extend Aux::CreateElement
+    extend Aux::GetElement
+
+    def call
+      InOrder::Element.transaction do
+        if marker
+          if after?
+            target.update element_id: marker.element_id
+
+            marker.update element_id: target.id
+          else
+            if previous = InOrder::Element.find_by(element_id: marker.id)
+              previous.update element_id: target.id
+            end
+
+            target.update element_id: marker.id
+          end
+        end
+        target
+      end
+    end
+
+    def self.call(record, marker, adjacency, keys: nil)
+      keys = InOrder::Aux::Keys.new(*keys) if Array === keys
+
+      unless ActiveRecord::Base === record
+        record = InOrder::Aux::PolyFind.new(record).call
+      end
+
+      marker = get_element(marker)
+
+      element = create_element(record, keys || marker.to_keys)
+
+      new(element, marker, adjacency).call
+    end
+  end
+end
+

data/app/models/in_order/move.rb

@@ -0,0 +1,15 @@
+
+module InOrder
+  # Repositions an existing list element.
+  # Can be used in drag'n'drop lists.
+  class Move < Aux::PositionBase
+    def call
+      InOrder::Element.transaction do
+        Remove.new(target, destroy: false).call
+
+        Insert.new(target, marker, adjacency).call
+      end
+    end
+  end
+end
+

data/app/models/in_order/purge.rb

@@ -0,0 +1,71 @@
+
+module InOrder
+  # Removes unwanted subjects from a list.
+  # Identified (i.e. keyed) by an Owner and/or Scope.
+  class Purge
+    include Aux::VarKeys
+
+    # +keep_last+ determines whether the first or last occurrence remains
+    def call(keep_last: false)
+      elements = get_elements
+
+      elements.reverse! if keep_last
+
+      traverse elements do |element, found_subjects, subject|
+        Remove.new(element).call if found_subjects.include?(subject)
+      end
+    end
+    alias uniq call
+
+    def remove(*subjects, elements: get_elements)
+      did_remove = false
+
+      subjects.flatten! if Array === subjects.first
+
+      traverse elements do |element|
+        if subjects.include?(element.subject)
+          Remove.new(element).call
+
+          did_remove = true
+        end
+      end
+
+      did_remove
+    end
+
+    def exists?(subject)
+      InOrder::Element.has_subject?(keys) { subject }
+    end
+
+    def self.delete_by_subject(subject)
+      InOrder::Element.transaction do
+        InOrder::Element.by_subject(subject).each do |element|
+          Remove.new(element).call
+        end
+      end
+    end
+
+    protected
+
+    def traverse(elements)
+      found_subjects = []
+
+      InOrder::Element.transaction do
+        elements.each do |element|
+          subject = element.subject
+
+          yield element, found_subjects, subject
+
+          found_subjects << subject
+        end
+      end
+    end
+
+    private
+
+    def get_elements
+      Fetch.new(keys).elements
+    end
+  end
+end
+

data/app/models/in_order/queue.rb

@@ -0,0 +1,65 @@
+
+# A first in, last out queue.
+module InOrder
+  class Queue
+    include Aux::VarKeys
+
+    def join(record, max=nil)
+      adder.prepend(record).tap { trim(max) if max }
+    end
+    alias add join
+
+    def call
+      remove_element
+    end
+    alias leave call
+    alias take call
+
+    def peek
+      last_element&.subject
+    end
+
+    def trim(max, take_last=is_queue?)
+      if size > max
+        if take_last
+          remove_element
+        else
+          remove_element { first_element }
+        end
+
+        trim max, take_last
+      end
+    end
+
+    def size
+      InOrder::Element.by_keys(keys).count
+    end
+
+    private
+
+    def last_element
+      InOrder::Element.last_element(keys)
+    end
+
+    def first_element
+      InOrder::Element.first_element(keys)
+    end
+
+    def remove_element
+      if element = (block_given? ? yield : last_element)
+        Remove.new(element).call
+
+        element.subject
+      end
+    end
+
+    def adder
+      Add.new(keys)
+    end
+
+    def is_queue?
+      InOrder::Queue == self.class
+    end
+  end
+end
+

data/app/models/in_order/remove.rb

@@ -0,0 +1,29 @@
+
+module InOrder
+  # Takes an element out of a list
+  class Remove
+    include Aux::GetElement
+
+    attr_accessor :element_id, :destroy
+    alias destroy? destroy
+
+    def initialize(element_id, destroy: true)
+      self.element_id = element_id
+
+      self.destroy = destroy
+    end
+
+    def call
+      InOrder::Element.transaction do
+        element = get_element element_id
+
+        if previous = InOrder::Element.find_by(element_id: element.id)
+          previous.update element_id: element.element_id
+        end
+
+        element.tap {|element| element.destroy if destroy? }
+      end
+    end
+  end
+end
+

data/app/models/in_order/stack.rb

@@ -0,0 +1,12 @@
+
+# A first in, first out queue.
+module InOrder
+  class Stack < InOrder::Queue
+    def push(record, max=nil)
+      adder.append(record).tap { trim(max) if max }
+    end
+
+    alias pop call
+  end
+end
+

data/app/models/in_order/trim.rb

@@ -0,0 +1,74 @@
+
+module InOrder
+  # Ensures a list does not exceed a specified length
+  class Trim
+    include Aux::SortElements
+
+    attr_accessor :destroy, :max, :take_from
+    alias destroy? destroy
+
+    def initialize(_max=nil, destroy: true, take_from: :bottom, max: _max)
+      self.destroy = destroy
+
+      self.max = max&.to_i
+
+      self.take_from = take_from
+    end
+
+    def call(elements, max_size=max)
+      return unless max_size
+
+      elements = elements.dup
+
+      InOrder::Element.transaction do
+        while elements.size > max_size.to_i
+          if take_from == :bottom
+            delete elements.pop
+
+            unlink elements.last
+          else
+            delete elements.shift
+          end
+        end
+      end
+      elements
+    end
+
+    class << self
+      mattr_accessor :maximum, default: 10
+
+      def call(*keys)
+        elements = InOrder::Fetch.new(*keys).elements
+
+        args = block_given? ? yield : [ maximum, destroy: false ]
+
+        InOrder::Trim.new(*args).call(elements).map(&:subject)
+      end
+
+      def set_max(max)
+        self.maximum = max
+
+        self
+      end
+    end
+
+    private
+
+    def delete(element)
+      element.destroy if destroy? and is_an_element!(element)
+    end
+
+    def unlink(element)
+      element.update(element_id: nil) if destroy?
+    end
+
+    def is_an_element!(element)
+      if InOrder::Element === element
+        true
+      else
+        raise "Cannot trim: #{element.class} is not an instance of InOrder::Element"
+      end
+    end
+  end
+end
+